datai/docs/skill/phase1-requirement-definition.md

阶段 1：需求定义与入库技能书

A. 元数据 (Metadata)

name: phase1-requirement-definition

description: 在 Datai 项目中，当用户提出新功能、Bug 修复、性能优化或重构需求时，负责创建标准化的需求文档、更新索引、建立需求追踪，并初始化会话记录。此技能是 SSOT 架构的起点，确保所有开发活动都有文档依据。

---

B. 触发与定位 (Triggers & Scope)

触发关键词

当用户输入包含以下关键词时，必须觉醒此技能：

• "新增功能"、"添加功能"、"实现功能"
• "修复 bug"、"修复问题"、"解决错误"
• "优化性能"、"性能调优"
• "重构"、"重构代码"
• "需求"、"需求文档"、"PRD"
• "开发任务"、"开发需求"

触发场景

• 用户首次提出新的开发需求
• 用户要求创建需求文档
• 用户提到"按照项目规则"或"SSOT 流程"
• 用户询问如何开始一个开发任务

操作路径

此技能涉及以下文件和目录的操作：

• 创建: docs/requirements/YYYY-MM-DD-00X-需求名.md
• 更新: docs/index.md
• 创建: docs/sessions/YYYY-MM-DD-00X-session.md
• 读取: .trae/rules/project_rules.md (项目规则)
• 读取: docs/Prompt/0004-单一真源文档驱动架构师.md (SSOT 架构师提示词)

SSOT 依赖

必须参考以下"唯一真源"：

• project_rules.md - 项目规则和阶段定义
• 0004-单一真源文档驱动架构师.md - SSOT 架构师提示词
• docs/requirements/ 目录下的现有需求文档（作为格式参考）

---

C. 核心指令集 (Instructions)

架构约束

1. 文档命名规范（强制）

• 必须使用格式：YYYY-MM-DD-00X-需求名.md
• YYYY-MM-DD：当前日期（如 2026-01-21）
• 00X：需求编号，从 001 开始递增
• 需求名：简洁描述，使用中文，如"用户登录功能"、"订单导出优化"
• 严禁使用英文、拼音或无意义的文件名

2. 文档结构约束（强制）

需求文档必须包含以下章节，顺序不能改变：

# 需求文档

## 元数据
- 需求编号：001
- 创建时间：YYYY-MM-DD
- 创建人：AI Assistant
- 状态：进行中
- 优先级：高/中/低

## 需求概述
[需求描述]

## 目标
[需求目标]

## 功能需求
### 核心功能
- [功能1]
- [功能2]

### 次要功能
- [功能1]
- [功能2]

## 非功能需求
### 性能要求
[性能要求]

### 安全要求
[安全要求]

### 兼容性要求
[兼容性要求]

## 技术约束
[技术约束]

## 成功标准
[成功标准]

## 相关文档
- [设计文档](../design/YYYY-MM-DD-00X-设计名.md)
- [决策记录](../decisions/YYYY-MM-DD-00X-ADR-决策名.md)

3. 索引更新约束（强制）

• 必须在创建需求文档后立即更新 docs/index.md
• 采用增量更新策略，严禁删除现有内容
• 索引链接格式：[文档名](./相对路径/文件名.md)
• 必须在 docs/index.md 中添加到"需求文档"部分

4. 会话记录约束（强制）

• 必须在 docs/sessions/ 目录下创建会话记录
• 文件命名：YYYY-MM-DD-00X-session.md
• 必须记录需求编号和当前阶段（阶段 1）
• 必须包含用户原始需求的完整描述

业务逻辑 SOP（标准操作流程）

步骤 1：需求分析（Let's think step by step）

在创建文档前，必须执行以下分析：

1. 分析用户需求的核心目标

   • 识别用户真正想要解决的问题
   • 区分表面需求和深层需求
   • 提炼出 1-2 句简洁的需求概述

2. 识别需求的关键要素

   • 涉及哪些业务模块（如 datai-modules-salesforce、datai-modules-system）
   • 涉及哪些技术组件（如 Salesforce API、MyBatis Plus、若依权限）
   • 是否涉及数据库变更
   • 是否涉及外部接口调用

3. 确定需求的优先级和复杂度

   • 优先级：高（阻塞功能）/ 中（重要功能）/ 低（优化改进）
   • 复杂度：简单（1-2 天）/ 中等（3-5 天）/ 复杂（5 天以上）
   • 根据复杂度预估是否需要拆分为多个子需求

步骤 2：创建需求文档

1. 确定文档路径

   • 路径：docs/requirements/YYYY-MM-DD-00X-需求名.md
   • 使用 Write 工具创建文件
   • 确保目录存在（使用 LS 工具检查）

2. 填充文档内容

   • 元数据：填写需求编号、创建时间、状态、优先级
   • 需求概述：用 2-3 句话描述需求的核心内容
   • 目标：列出 1-3 个明确的、可衡量的目标
   • 功能需求：
     • 核心功能：必须实现的功能（2-5 项）
     • 次要功能：可选或后续迭代的功能（1-3 项）
   • 非功能需求：
     • 性能要求：响应时间、并发数等
     • 安全要求：权限控制、数据加密等
     • 兼容性要求：浏览器、操作系统、数据库版本等
   • 技术约束：
     • 必须使用的框架或库
     • 必须遵循的设计模式
     • 必须继承的基类
   • 成功标准：列出 3-5 个可验证的验收标准
   • 相关文档：暂时为空，后续阶段会填充

3. 文档质量检查

   • 使用 Read 工具读取刚创建的文档
   • 检查是否符合文档结构约束
   • 检查是否有遗漏的章节
   • 检查语言是否清晰、无歧义

步骤 3：更新索引

1. 读取现有索引

   • 使用 Read 工具读取 docs/index.md
   • 找到"需求文档"部分
   • 如果不存在，则创建该部分

2. 添加新需求链接

   • 在"需求文档"部分追加新需求
   • 格式：- [需求名](./requirements/YYYY-MM-DD-00X-需求名.md) - [状态] - [优先级]
   • 示例：- [用户登录功能](./requirements/2026-01-21-001-用户登录功能.md) - 进行中 - 高

3. 保存索引

   • 使用 Write 工具更新 docs/index.md
   • 严禁删除现有内容，只追加新内容

步骤 4：创建会话记录

1. 创建会话文件

   • 路径：docs/sessions/YYYY-MM-DD-00X-session.md
   • 使用 Write 工具创建文件

2. 填充会话内容

   # 会话记录
   
   ## 元数据
   - 需求编号：001
   - 开始时间：YYYY-MM-DD HH:MM:SS
   - 结束时间：YYYY-MM-DD HH:MM:SS
   - 当前阶段：阶段 1：需求定义与入库
   
   ## 需求描述
   [用户原始需求的完整描述]
   
   ## 执行阶段
   ### 阶段 1：需求定义与入库
   - 状态：已完成
   - 生成文档：[需求文档](../requirements/YYYY-MM-DD-00X-需求名.md)
   - 关键决策：[记录关键决策，如优先级、复杂度等]
   
   ### 阶段 2：方案设计
   - 状态：未开始
   
   ...（后续阶段初始状态）
   
   ## 对话记录
   [记录完整的对话过程]
   
   ## 生成的文档
   - [需求文档](../requirements/YYYY-MM-DD-00X-需求名.md)
   
   ## 回退记录
   [如果有回退，记录回退操作]
   

3. 记录对话

   • 将用户原始需求完整记录在"需求描述"部分
   • 将 AI 的分析和决策记录在"对话记录"部分

步骤 5：确认与询问

1. 向用户确认

   • 显示需求文档的链接
   • 询问："需求文档是否符合预期？"
   • 询问："是否进入下一阶段（方案设计）？"

2. 等待用户反馈

   • 如果用户不满意，询问具体需要修改的地方
   • 如果用户要求回退，执行回退机制（见错误陷阱部分）
   • 如果用户确认，标记阶段 1 为已完成，准备进入阶段 2

工具调用

必须使用的工具

1. LS 工具：检查目录是否存在

   • 使用场景：创建文档前检查 docs/requirements/、docs/sessions/ 目录
   • 命令：LS(path="d:\\idea_demo\\datai\\docs")

2. Write 工具：创建新文件

   • 使用场景：创建需求文档、更新索引、创建会话记录
   • 命令：Write(file_path="d:\\idea_demo\\datai\\docs\\requirements\\YYYY-MM-DD-00X-需求名.md", content="...")

3. Read 工具：读取现有文件

   • 使用场景：读取 docs/index.md、读取刚创建的文档进行验证
   • 命令：Read(file_path="d:\\idea_demo\\datai\\docs\\index.md")

4. SearchCodebase 工具：搜索现有需求

   • 使用场景：确定需求编号（避免重复）
   • 命令：SearchCodebase(information_request="查找 docs/requirements 目录下的所有需求文档")

可选使用的工具

1. Glob 工具：查找文件

   • 使用场景：查找所有需求文档
   • 命令：Glob(pattern="docs/requirements/*.md")

2. TodoWrite 工具：管理任务

   • 使用场景：跟踪阶段执行进度
   • 命令：TodoWrite(todos=[...])

---

D. 错误陷阱与验证 (Anti-Patterns & Checklist)

常见错误（Anti-Patterns）

错误 1：跳过需求分析直接创建文档

错误示例：

用户：帮我实现一个用户登录功能
AI：直接创建文档，不分析需求

正确示例：

用户：帮我实现一个用户登录功能
AI：让我先分析一下这个需求：
1. 核心目标：实现用户身份验证
2. 关键要素：涉及 datai-modules-system 模块，使用若依权限系统
3. 优先级：高（核心功能）
4. 复杂度：中等（需要考虑安全性）

错误 2：文档命名不符合规范

错误示例：

• user-login.md（使用英文）
• 001.md（缺少日期和描述）
• 需求.md（无意义）

正确示例：

• 2026-01-21-001-用户登录功能.md
• 2026-01-21-002-订单导出优化.md

错误 3：忘记更新索引

错误示例：

AI：创建需求文档
AI：创建会话记录
AI：完成（忘记更新 docs/index.md）

正确示例：

AI：创建需求文档
AI：更新 docs/index.md，添加需求链接
AI：创建会话记录
AI：完成

错误 4：需求描述模糊不清

错误示例：

## 需求概述
用户需要一个功能

正确示例：

## 需求概述
实现基于用户名和密码的用户登录功能，支持记住密码和自动登录，集成若依权限系统，确保登录过程的安全性。

错误 5：不询问用户确认就进入下一阶段

错误示例：

AI：创建需求文档
AI：进入阶段 2：方案设计（未询问用户）

正确示例：

AI：创建需求文档
AI：需求文档已创建：[链接]
AI：需求文档是否符合预期？
AI：是否进入下一阶段（方案设计）？

验收清单（Checklist）

在完成阶段 1 前，必须检查以下项目：

文档完整性检查

• 需求文档已创建在 docs/requirements/ 目录下
• 文档命名符合 YYYY-MM-DD-00X-需求名.md 格式
• 文档包含所有必需章节（元数据、需求概述、目标、功能需求、非功能需求、技术约束、成功标准、相关文档）
• 元数据已正确填写（需求编号、创建时间、状态、优先级）
• 需求概述清晰、无歧义
• 目标明确、可衡量
• 功能需求区分核心功能和次要功能
• 非功能需求包含性能、安全、兼容性要求
• 技术约束明确（框架、设计模式、基类）
• 成功标准可验证（3-5 条）

索引更新检查

• docs/index.md 已更新
• 新需求链接已添加到"需求文档"部分
• 索引链接格式正确：[文档名](./相对路径/文件名.md)
• 索引更新采用增量策略，未删除现有内容

会话记录检查

• 会话记录已创建在 docs/sessions/ 目录下
• 会话记录文件命名符合 YYYY-MM-DD-00X-session.md 格式
• 会话记录包含元数据（需求编号、开始时间、结束时间、当前阶段）
• 会话记录包含用户原始需求的完整描述
• 会话记录包含阶段 1 的执行状态
• 会话记录包含生成的文档链接

用户确认检查

• 已向用户显示需求文档链接
• 已询问用户"需求文档是否符合预期？"
• 已询问用户"是否进入下一阶段？"
• 已等待用户反馈

回退机制检查（如果需要）

• 如果用户不满意，已询问具体需要修改的地方
• 如果用户要求回退，已删除相关文档
• 如果用户要求回退，已撤销索引更新
• 如果用户要求回退，已更新会话记录

Correct vs Incorrect 代码对比

Incorrect（错误示例）

# 需求文档

## 需求概述
用户登录

## 目标
实现登录

## 功能需求
- 登录功能

问题：

• 缺少元数据
• 需求概述过于简单
• 目标不明确
• 功能需求未区分核心和次要
• 缺少非功能需求、技术约束、成功标准

Correct（正确示例）

# 需求文档

## 元数据
- 需求编号：001
- 创建时间：2026-01-21
- 创建人：AI Assistant
- 状态：进行中
- 优先级：高

## 需求概述
实现基于用户名和密码的用户登录功能，支持记住密码和自动登录，集成若依权限系统，确保登录过程的安全性。

## 目标
1. 实现用户身份验证，验证用户名和密码的正确性
2. 支持记住密码功能，减少用户重复输入
3. 支持自动登录功能，提升用户体验
4. 集成若依权限系统，确保用户只能访问有权限的功能

## 功能需求
### 核心功能
- 用户名和密码验证
- 记住密码功能
- 自动登录功能
- 登录失败提示
- 登录成功后跳转到首页

### 次要功能
- 登录历史记录
- 登录失败次数限制
- 验证码功能（后续迭代）

## 非功能需求
### 性能要求
- 登录响应时间不超过 2 秒
- 支持并发登录用户数不少于 100

### 安全要求
- 密码必须加密存储（使用 BCrypt）
- 登录失败 5 次后锁定账户 30 分钟
- 支持 HTTPS 协议

### 兼容性要求
- 支持 Chrome、Firefox、Edge 最新版本
- 支持 Windows 10、macOS、Linux

## 技术约束
- 必须使用 Spring Security 框架
- 必须继承若依的 `LoginService` 基类
- 必须使用 JWT Token 进行身份验证
- 必须集成若依权限系统

## 成功标准
1. 用户可以使用正确的用户名和密码成功登录
2. 用户可以使用记住密码功能，下次登录时自动填充
3. 用户可以使用自动登录功能，下次访问时自动登录
4. 登录失败时显示明确的错误提示
5. 登录成功后正确跳转到首页
6. 登录失败 5 次后账户被锁定

## 相关文档
- [设计文档](../design/2026-01-21-001-用户登录功能-设计.md)
- [决策记录](../decisions/2026-01-21-001-ADR-用户登录功能-技术选型.md)

---

附录：快速参考

文件路径速查

• 需求文档：docs/requirements/YYYY-MM-DD-00X-需求名.md
• 主索引：docs/index.md
• 会话记录：docs/sessions/YYYY-MM-DD-00X-session.md
• 项目规则：.trae/rules/project_rules.md
• SSOT 架构师提示词：docs/Prompt/0004-单一真源文档驱动架构师.md

工具命令速查

# 检查目录
LS(path="d:\\idea_demo\\datai\\docs")

# 创建文档
Write(file_path="d:\\idea_demo\\datai\\docs\\requirements\\2026-01-21-001-用户登录功能.md", content="...")

# 读取索引
Read(file_path="d:\\idea_demo\\datai\\docs\\index.md")

# 搜索现有需求
SearchCodebase(information_request="查找 docs/requirements 目录下的所有需求文档")

# 查找所有需求文档
Glob(pattern="docs/requirements/*.md")

阶段 1 输出清单

• 需求文档：docs/requirements/YYYY-MM-DD-00X-需求名.md
• 更新的索引：docs/index.md
• 会话记录：docs/sessions/YYYY-MM-DD-00X-session.md

下一阶段提示

如果用户确认进入下一阶段，请参考：

• project_rules.md 的"阶段 2：方案设计"
• 准备创建设计文档
• 准备分析技术方案和架构设计