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](file:///d:\idea_demo\datai\.trae\rules\project_rules.md) - 项目规则和阶段定义
- [0004-单一真源文档驱动架构师.md](file:///d:\idea_demo\datai\docs\Prompt\0004-单一真源文档驱动架构师.md) - SSOT 架构师提示词
- `docs/requirements/` 目录下的现有需求文档（作为格式参考）

---

## C. 核心指令集 (Instructions)

### 架构约束

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

#### 2. 文档结构约束（强制）
需求文档必须包含以下章节，顺序不能改变：
```markdown
# 需求文档

## 元数据
- 需求编号：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. **填充会话内容**
   ```markdown
   # 会话记录

   ## 元数据
   - 需求编号：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（错误示例）
```markdown
# 需求文档

## 需求概述
用户登录

## 目标
实现登录

## 功能需求
- 登录功能
```

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

#### Correct（正确示例）
```markdown
# 需求文档

## 元数据
- 需求编号：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`

### 工具命令速查
```powershell
# 检查目录
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](file:///d:\idea_demo\datai\.trae\rules\project_rules.md) 的"阶段 2：方案设计"
- 准备创建设计文档
- 准备分析技术方案和架构设计