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

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

技能：需求定义与入库 (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: 解析用户原始需求

## 需求解析

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

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

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

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

步骤 2: 编写用户故事

## 用户故事

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

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

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

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

步骤 3: 定义验收标准（AC）

## 验收标准 (Acceptance Criteria)

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

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

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

步骤 4: 创建需求文档

---
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

### 📝 需求文档 (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 示例

## 用户故事

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

## 验收标准

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

Incorrect 示例

## 用户故事

用户想要批量导入数据。

## 验收标准

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

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

相关文档 (Related Documents)

• 工作流提示词
• 架构决策技能
• 提示词资产化技能
• 需求模板