datai/datai-scenes/datai-scene-salesforce/docs/skill/0004-define-requirements.md

---
name: 0004-define-requirements
description: 需求定义与入库，创建需求文档并更新索引
---

# 技能：需求定义与入库 (Define Requirements)

## 元数据 (Metadata)

- **name**: define-requirements
- **description**: 需求定义与入库，创建需求文档并更新索引
- **version**: 1.0.0
- **author**: SSOT Architect
- **lastUpdated**: 2026-01-15

## 触发与定位 (Triggers & Scope)

### 触发条件 (Triggers)
当以下情况发生时，AI 应当"觉醒"本技能：

1. **新功能需求**: 用户提出新的功能需求
2. **Bug 修复需求**: 用户报告 Bug 并要求修复
3. **性能优化需求**: 用户要求优化系统性能
4. **技术债务清理**: 用户要求清理技术债务
5. **工作流阶段 1**: 用户进入工作流的"需求定义与入库"阶段

### 定位范围 (Scope)
- **适用模块**: 所有 Datai 项目模块
- **影响文件**: `docs/requirements/REQ-XXX.md`, `docs/index.md`
- **相关技能**: skill-architecture-decision, skill-prompt-engineering

## 核心指令集 (Instructions)

### 架构约束 (Architecture Constraints)

1. **需求文档命名规范**:
   - 格式: `REQ-XXX.md`
   - XXX: 三位数字，从 001 开始递增
   - 示例: `REQ-001.md`, `REQ-002.md`

2. **需求文档必须包含**:
   - 需求编号和标题
   - 需求类型（功能/非功能）
   - 优先级（高/中/低）
   - 用户故事
   - 验收标准（AC）
   - 相关文档链接
   - 状态（Draft/In Progress/Completed）

3. **必须同步更新 docs/index.md**:
   - 将新需求添加到"需求文档"表格
   - 标记需求状态
   - 包含需求描述和更新日期

### 业务逻辑 SOP (Business Logic SOP)

#### 步骤 1: 解析用户原始需求
```markdown
## 需求解析

### 原始需求
[用户提供的原始需求描述]

### 需求类型
- [ ] 功能需求
- [ ] 非功能需求（性能/安全/可用性等）

### 优先级
- [ ] 高
- [ ] 中
- [ ] 低

### 影响范围
- [ ] 前端
- [ ] 后端
- [ ] 数据库
- [ ] API
- [ ] 文档
```

#### 步骤 2: 编写用户故事
```markdown
## 用户故事

### 用户角色
[目标用户角色]

### 用户目标
[用户想要达成的目标]

### 用户价值
[用户为什么需要这个功能]

### 用户故事格式
作为一个 [用户角色]，
我想要 [用户目标]，
以便于 [用户价值]。
```

#### 步骤 3: 定义验收标准（AC）
```markdown
## 验收标准 (Acceptance Criteria)

### 功能验收标准
- [ ] AC1: [具体的验收标准]
- [ ] AC2: [具体的验收标准]
- [ ] AC3: [具体的验收标准]

### 非功能验收标准
- [ ] 性能要求: [具体的性能指标]
- [ ] 安全要求: [具体的安全要求]
- [ ] 可用性要求: [具体的可用性要求]

### 测试用例
| 用例编号 | 用例描述 | 预期结果 |
|----------|----------|----------|
| TC-001 | [测试用例描述] | [预期结果] |
| TC-002 | [测试用例描述] | [预期结果] |
```

#### 步骤 4: 创建需求文档
```markdown
---
name: REQ-001
description: [需求描述]
---

# 需求: [需求标题]

## 元数据 (Metadata)

- **需求编号**: REQ-001
- **需求标题**: [需求标题]
- **需求类型**: [功能需求/非功能需求]
- **优先级**: [高/中/低]
- **状态**: [Draft/In Progress/Completed]
- **创建日期**: YYYY-MM-DD
- **最后更新**: YYYY-MM-DD
- **创建人**: [创建人姓名]
- **负责人**: [负责人姓名]

## 需求描述 (Description)

### 背景
[需求背景和上下文]

### 问题陈述
[当前存在的问题]

### 目标
[需求要达成的目标]

## 用户故事 (User Story)

作为一个 [用户角色]，
我想要 [用户目标]，
以便于 [用户价值]。

## 验收标准 (Acceptance Criteria)

### 功能验收标准
- [ ] AC1: [具体的验收标准]
- [ ] AC2: [具体的验收标准]
- [ ] AC3: [具体的验收标准]

### 非功能验收标准
- [ ] 性能要求: [具体的性能指标]
- [ ] 安全要求: [具体的安全要求]
- [ ] 可用性要求: [具体的可用性要求]

## 技术要求 (Technical Requirements)

### 技术栈
- [ ] Java 17/21
- [ ] Spring Boot 3.x
- [ ] MyBatis Plus
- [ ] Salesforce API

### 接口要求
- [ ] REST API
- [ ] SOAP API
- [ ] GraphQL API

### 数据库要求
- [ ] MySQL
- [ ] PostgreSQL
- [ ] Oracle

## 依赖关系 (Dependencies)

### 前置需求
- [REQ-XXX](./REQ-XXX.md) - [前置需求描述]

### 后续需求
- [REQ-XXX](./REQ-XXX.md) - [后续需求描述]

### 外部依赖
- [外部系统/服务] - [依赖描述]

## 相关文档 (Related Documents)

- [设计文档](../design/DES-XXX.md)
- [ADR 文档](../decisions/adr/ADR-XXX.md)
- [提示词文档](../prompts/PROMPT-XXX.md)

## 变更历史 (Change History)

| 日期 | 版本 | 变更内容 | 变更人 |
|------|------|----------|--------|
| YYYY-MM-DD | 1.0.0 | 初始版本 | [姓名] |
```

#### 步骤 5: 更新 docs/index.md
```markdown
### 📝 需求文档 (Requirements)
| 文档 | 状态 | 描述 | 更新日期 |
|------|------|------|----------|
| [REQ-001](requirements/REQ-001.md) | 🔄 In Progress | [需求描述] | 2026-01-15 |
```

### 工具调用 (Tool Usage)

1. **需求编号生成工具**:
   - 使用 `Grep` 工具搜索 `docs/requirements/` 目录
   - 查找最大的 REQ 编号
   - 生成新的 REQ 编号

2. **文件创建工具**:
   - 使用 `Write` 工具创建需求文档
   - 确保文件路径正确

3. **索引更新工具**:
   - 使用 `Read` 工具读取 `docs/index.md`
   - 使用 `SearchReplace` 工具更新索引

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

### 常见错误 (Anti-Patterns)

1. **错误**: 需求描述过于模糊
   - **后果**: 无法准确理解需求，导致开发偏差
   - **修正**: 使用具体的、可量化的描述

2. **错误**: 验收标准不完整
   - **后果**: 无法验证需求是否满足
   - **修正**: 确保每个功能点都有对应的验收标准

3. **错误**: 忘记更新 docs/index.md
   - **后果**: 产生孤儿文件，违反 SSOT 原则
   - **修正**: 创建需求文档后必须更新索引

4. **错误**: 用户故事格式不规范
   - **后果**: 难以理解用户需求
   - **修正**: 使用标准格式：作为一个...我想要...以便于...

5. **错误**: 缺少非功能需求
   - **后果**: 系统性能、安全性等无法保证
   - **修正**: 必须包含性能、安全、可用性等非功能需求

### 验收清单 (Acceptance Checklist)

- [ ] 需求文档已创建
- [ ] 需求编号符合规范
- [ ] 需求类型已明确
- [ ] 优先级已设定
- [ ] 用户故事已编写
- [ ] 验收标准已定义
- [ ] 技术要求已明确
- [ ] 依赖关系已列出
- [ ] docs/index.md 已更新
- [ ] 相关文档已链接

### Correct vs Incorrect 对比

#### Correct 示例
```markdown
## 用户故事

作为一个系统管理员，
我想要批量导入用户数据，
以便于快速初始化系统用户。

## 验收标准

- [ ] AC1: 支持 CSV 格式的批量导入
- [ ] AC2: 单次导入最多支持 1000 条记录
- [ ] AC3: 导入失败时提供详细的错误信息
- [ ] AC4: 导入耗时不超过 30 秒（1000 条记录）
```

#### Incorrect 示例
```markdown
## 用户故事

用户想要批量导入数据。

## 验收标准

- [ ] 支持批量导入
- [ ] 导入速度快
```

**问题**: 用户故事格式不规范，验收标准不具体、不可量化。

## 相关文档 (Related Documents)

- [工作流提示词](../prompts/03-创建工作流提示词.md#阶段-1-需求定义与入库-requirements)
- [架构决策技能](./0005-architecture-decision.md)
- [提示词资产化技能](./0006-prompt-engineering.md)
- [需求模板](../prompts/03-创建工作流提示词.md#阶段-1-需求定义与入库-requirements)