本篇对应仓库 README 的「核心特性」与《项目原理.md》§1–§2。做需求分析不是为了写文档，是为了让后面每一行代码都有"为什么"。
一、先讲清业务场景
假设你是一家跨境电商公司的技术负责人。公司在亚马逊开店，你会观察到三个真实痛点：
- 同一个问题每天被回答几十遍。"FBA 发货外箱标签怎么打？""退货率超 5% 怎么处理？"——答案就在公司的 SOP 文档里，但新员工不知道去哪找，老人也懒得翻。
- 老板想让 AI 提效，但不敢放开用。直接让员工用公共 ChatGPT：企业资料外泄、按人头买账号无法审计、出了错没人知道谁在哪次调用里花了多少钱。
- AI 用法停留在"聊天"。运营真正想要的是"每周把销售 CSV 丢进去，自动出一份分析报告"——这是流程自动化，不是聊天窗口。
于是需求浮出水面：做一个把"模型能力、岗位知识、业务流程"统一收拢到一个后端的 AI 中控平台——员工用浏览器访问，能力通过 /api/* REST 接口暴露，将来还能被企业微信、ERP 复用（这正是仓库《项目原理.md》§1 的原话）。
二、用户故事：从三种角色出发
需求分析的老手艺：先列"谁在用系统，他要做什么"。
员工（employee，如运营小张） - 我想登录后看到分给我的岗位助手（运营部的我不该看到财务助手的内部提示词） - 我提问时，助手基于公司知识库回答，并告诉我引用了哪个文件哪一段——不然我不敢信 - 回答要逐字流式输出（打字机效果），等 10 秒一次性蹦出来体验很差 - 我的会话记录别人不能看，反过来我也看不了别人的
管理员（admin） - 我要在后台创建助手：写系统提示词、绑知识库、选模型、按部门开放——不改代码 - 我要上传文档建知识库（SOP、产品资料、供应商信息） - 我要看到每一次模型调用：谁、什么时候、哪个模型、多少 token、成功还是降级——这是成本与审计的抓手 - 我要给某个员工单独授权某个助手（部门规则之外的补充）
系统自身（非功能需求） - 模型可插拔：今天是 Mock，明天接 DeepSeek，后天接公司私有网关——上层零改动 - 模型挂了系统不能装死：自动重试，重试失败要显式标注"已降级"，绝不静默给假回复 - 成本可控：限流必须存在（对话和跑工作流是两个烧钱入口） - 离线可跑可测：不接真实模型时，整套系统照样能开发、测试、演示
三、翻译成功能清单（含验收标准）
| # | 功能 | 验收标准（怎么算做完） |
|---|---|---|
| F1 | 多用户与角色 | 注册默认 employee；admin 可见后台；员工访问他人资源 403/404 |
| F2 | 岗位助手（配置驱动） | 新增助手 = 后台加一条配置，无需改代码 |
| F3 | 知识库 RAG | 上传 txt/md/docx/csv → 提问命中 → 回复带《文件名》第 N 段引用 |
| F4 | 混合检索 | TF-IDF/BM25/加权 RRF 三模式可切换，效果有量化报告 |
| F5 | SSE 流式对话 | 逐字输出；多轮上下文生效；引用随回复下发 |
| F6 | LLM 网关 | 重试/降级/每用户限流（429+Retry-After）/token 审计落库 |
| F7 | 工作流引擎 | JSON-DAG 定义；校验环节检测；节点级执行记录；code 节点防注入 |
| F8 | 使用统计与审计 | 每用户/每助手/近 7 日统计；登录与敏感操作写审计日志 |
| F9 | 接真实模型 | 后台填 OpenAI 兼容端点即可切换，无需重启 |
刻意不做的（需求分析同样要说"不做什么"）：不做多租户 SaaS、不做移动端、初期不做向量数据库——用"够用的企业级"守住交付边界。
四、非功能需求：安全与可测试性
功能清单之外，两件决定架构的事必须在需求阶段定下来：
安全基线（仓库最终落地了这些，01 篇先把"为什么"立住）： - 口令绝不存明文（pbkdf2 哈希）；会话 token 有有效期 - 权限判定必须收敛在一处——否则迟早出现"列表页校验了、使用处漏校验"的横向越权（这是作者真实踩过的坑，见 05 篇） - 用户上传的文件是攻击面：体积上限、类型白名单、解析器防 zip 炸弹 - 工作流允许用户写代码表达式 = 典型代码注入风险点，必须沙箱
可测试性：
- "107 项测试全绿"不能是口号。需求阶段就要求：核心逻辑不依赖真实大模型（于是有了 Mock Provider）、每个测试用例用独立数据库（于是有了 create_app(db_path) 应用工厂——03 篇细讲）
- RAG 检索"效果好不好"要能量化： golden set 评估是需求，不是锦上添花
五、需求→功能的映射心法（写给小白）
回看这个过程，你会注意到三个手法：
- 痛点 → 用户故事 → 功能 → 验收标准，一条链走到底。"员工怕 AI 瞎编"（痛点）→"我要带引用的回答"（故事）→ F3 RAG（功能）→"回复含《文件名》第 N 段"（验收）。
- 非功能需求藏在故事里。"老板要审计" → F6/F8；"模型不能装死" → 网关降级语义。
- 给出明确的"不做清单"。没有边界的项目永远做不完。
动手清单
- 照第三节表格，为本项目手写一版功能清单（你会发现自己的措辞和仓库实现惊人一致——这就是需求分析的意义）
- 想一个你自己业务里的"AI 中台"需求，模仿第二、三节写 5 条用户故事 + 3 条非功能需求
下一篇，我们拿着这份清单做架构设计：为什么是三层解耦、为什么敢用 SQLite、为什么不用任何框架写前端。