Skill: 业务需求分析 → 技术文档生成

Skill: 业务需求分析 → 技术文档生成

适用场景

当用户提到以下关键词时，自动进入本Skill流程：

• "帮我分析需求"、"我有个新系统/新功能要做"
• "帮我设计表结构/Collection/接口"
• "生成需求说明书"

---

技术栈约定（全程遵守）

• 后端：Python + FastAPI
• 数据库：MongoDB，使用 motor 异步驱动
• 前端：Vue 3 + Pinia + axios + Element Plus
• DB操作封装规范：语义化方法，以 news Collection为例：
  • find_news(query) → 查单条，返回 dict or None
  • list_news(query, page, page_size) → 查多条，返回 {"total": int, "items": list}
  • add_news(doc) → 插入单条，返回插入后的文档（含 _id）
  • add_news_batch(docs) → 批量插入
  • update_news(query, update) → 更新，返回更新后文档
  • delete_news(query) → 删除，返回删除条数
• 所有Collection均遵循此命名规范，生成代码骨架时直接使用对应方法

---

工作流程

第一步：需求接收

用户描述需求后，Claude先输出一个简短的"理解摘要"，格式如下：

【我的理解】
系统类型：（管理后台 / 数据采集 / AI Agent工具 / 内容展示 / 混合型）
核心实体：（初步识别到的主要数据对象，例如：用户、任务、新闻）
主要功能：（3-5条）
不确定的地方：（列出明显信息缺口）

确认理解无误后，进入第二步。

---

第二步：结构化追问

原则：每轮最多问3个问题，按优先级从高到低提问，不要一次性抛出所有问题。

提问分为以下模块，根据系统类型选取相关模块：

模块A：用户与权限

• 使用这个系统的角色有哪些？每个角色的权限边界是什么？
• 数据是否需要隔离？（例如：用户只能看自己创建的数据）
• 是否需要操作日志？

模块B：业务流程与状态

• 核心实体有没有状态流转？（例如：草稿→审核中→已发布）
• 哪些操作是不可逆的？哪些需要二次确认？
• 是否有定时任务或自动触发的逻辑？

模块C：数据关系（MongoDB核心决策点）

• 哪些数据会被同时读取？（用于判断嵌入 vs 引用）
• 哪些字段会随时间增长（例如评论、日志），数量级大概多少？
• 最高频的查询场景是什么？按什么字段筛选和排序？
• 数据写入频率如何？是批量写入还是实时单条写入？

模块D：数据生命周期

• 数据是否允许删除？是物理删除还是软删除（is_deleted 标记）？
• 历史版本或操作记录是否需要保留？
• 数据有没有过期/归档的需求？

模块E：外部依赖

• 是否需要对接已有系统？有没有固定的数据格式要求？
• 是否涉及文件上传、第三方API调用？
• 是否有现成的数据来源（爬虫/Agent输出），字段结构是否已确定？

模块F：前端界面

• 主要页面有哪些？每个页面的核心功能是什么？
• 是否有通用的布局模式？（例如：顶部导航+侧边栏、纯表格页、表单页）
• 哪些页面需要移动端适配？移动端的布局如何变化？
• 有哪些可复用的组件？（例如：用户选择器、富文本编辑器、文件上传）
• 主要交互操作是什么？（点击打开弹窗/抽屉、点击跳转、直接执行）
• 哪些状态需要全局管理？（放入 Pinia）

追问结束后，输出：

【需求完整度评估】
已明确：...
仍待确认：...（如有，标注影响范围）
→ 是否继续生成技术方案？

---

第三步：技术方案草案确认

在生成正式文档前，先输出精简草案供确认：

【Collection草案】
- collection_name：说明用途
  嵌入字段：...
  引用字段：...（引用哪个Collection）

【前端页面草案】
- /route_path：页面名称
  布局：顶部导航 + 侧边栏 + 内容区
  核心组件：表格 + 搜索 + 新建按钮
  响应式：移动端侧边栏隐藏，表格转为卡片

【API草案】
- GET /xxx    说明
- POST /xxx   说明
...

→ 以上方案是否调整？

---

第四步：生成需求说明书

用户确认后，按 templates/spec.md 模板生成完整文档，输出为 .md 文件。

---

MongoDB设计原则（生成方案时强制遵守）

1. 访问模式优先：先明确查询场景，再决定数据结构
2. 嵌入优先于引用，当满足以下条件时选择嵌入：
   • 子数据数量有限且不会无限增长（通常 < 100条）
   • 子数据总是随父文档一起读取
   • 子数据不需要被独立查询
3. 引用优先于嵌入，当满足以下条件时选择引用：
   • 子数据会无限增长（如评论、日志）
   • 子数据需要被独立查询或更新
   • 多个文档共享同一份子数据
4. 索引设计必须覆盖最高频查询字段，复合索引注意字段顺序
5. 对于一般的实体Collection，应当包含以下的通用字段：

   created_at  datetime  创建时间，默认 datetime.now()
   updated_at  datetime  更新时间，每次update自动刷新
   is_deleted  bool      软删除标记，默认 False（除非明确说不需要）
   

---

前端设计原则（生成方案时强制遵守）

1. 线框图优先：使用 ASCII 字符绘制简单布局，不追求细节，只展示结构关系
2. 响应式必问：每个页面必须考虑移动端适配，明确布局变化方式
3. 组件复用优先：识别可复用组件（选择器、上传器、编辑器等），减少重复代码
4. 交互明确：每个操作都要说明触发方式和反馈（弹窗/抽屉/跳转/直接执行）
5. Pinia 状态范围：只有跨页面共享的状态才放入 Store，页面内状态用组件本地状态
6. Element Plus 规范：
   • 表格页：el-table + el-pagination + el-form（搜索）
   • 表单页：el-form + el-row/el-col 布局
   • 弹窗：el-dialog + el-form
   • 抽屉：el-drawer（适合详情页）