工程级需求规格编写范式

核心原则

范式与数据分离 — skill 定义的是编写范式（模板结构+工作流程+质量标准），
领域知识（角色、术语、数据约定、业务模式）通过 Phase 0 从标书动态生成，不写死在 skill 中。

工程级粒度 — 每个功能点必须展开为完整的业务对象+数据字典+用例+业务规则+约束+角色权限，
达到可直接指导概要设计和编码的粒度。

一次只写一个系统 — Phase 1 每次调用处理一个子系统，保证专注和完整性。

两阶段架构

┌─────────────────────────────────────────────────┐
│  Phase 0: 项目元数据生成（每个项目执行一次）         │
│                                                   │
│  输入：标书/响应文件/分析报告                        │
│      ↓                                            │
│  分析：行业识别 → 角色提取 → 术语梳理 → 数据约定     │
│      ↓                                            │
│  输出：_metadata.md（结构化元数据文件）               │
│      ↓                                            │
│  用户确认 & 调整                                    │
└─────────────────────────────┬───────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────┐
│  Phase 1: 需求规格编写（每个系统执行一次）           │
│                                                   │
│  输入：_metadata.md + 该系统功能清单                 │
│      ↓                                            │
│  处理：功能分类 → 套用模板 → 展开细节                │
│      ↓                                            │
│  输出：{系统编号}-{系统名称}.md                      │
└─────────────────────────────────────────────────┘

工作模式

初始化模式（Phase 0）

• 触发： 用户首次要求编写需求，且 _metadata.md 不存在
• 行为： 执行 Phase 0 生成元数据

编写模式（Phase 1，默认）

• 触发： _metadata.md 已存在，用户指定要编写某系统
• 行为： 执行 Phase 1 编写该系统的需求规格

修复模式

• 触发： 目标系统的需求文件已存在，用户要求修复/补充
• 行为： 执行修复工作流程（R1-R4）

---

Phase 0: 项目元数据生成

目标： 从标书文件中提取所有项目特定信息，生成结构化元数据文件，
为 Phase 1 的编写提供领域上下文。

0.1 定位数据源

扫描项目工作目录，定位以下类型的文件（文件名/路径不固定，按内容识别）：

数据源类型	识别方法	提取内容
分析报告	文件名含"分析报告"	项目概况、评分标准、合规要求
技术响应表	含系统/功能/响应列表格	全部功能点清单
技术方案	含架构/技术选型描述	系统架构、技术栈、接口关系
实施方案	含实施阶段/交付计划	交付期、里程碑
需求总纲	项目文档/01-需求分析/ 下的总纲文件	已有的角色定义、非功能需求

如未找到某类文件，向用户询问路径。

0.2 行业领域分析

从标书内容中识别：

## 行业领域

| 维度 | 内容 |
|------|------|
| 行业 | {如：医疗卫生/电力能源/教育/金融/政务/交通/制造...} |
| 细分领域 | {如：护理信息化/配电自动化/智慧校园/核心银行...} |
| 业务特征 | {如：强合规/高并发/数据密集/流程驱动/移动优先...} |
| 监管要求 | {如：等保二级/HIPAA/PCI-DSS/国密...} |
| 信息化现状 | {如：已有HIS/EMR需对接 / 全新建设 / 替换旧系统...} |

0.3 系统清单与分域

从技术响应表中提取全部系统，按业务领域分组：

## 系统清单

### 分域规划

| 分册 | 业务领域 | 包含系统 | 系统编号 |
|------|---------|---------|---------|
| 第一册 | {领域名} | {系统A}、{系统B} | S01-S0N |
| 第二册 | {领域名} | {系统C}、{系统D} | S0N-S0M |
| ... | ... | ... | ... |

### 系统功能点统计

| 系统编号 | 系统名称 | 功能点数 | ▲标注数 | 所属分册 |
|---------|---------|---------|---------|---------|
| S01 | {系统名} | {N} | {M} | 第{X}册 |
| ... | ... | ... | ... | ... |
| **合计** | | **{总数}** | **{总▲}** | |

分域原则：

• 按业务流程的上下游关系分组
• 同一业务域的系统放在同一分册
• 基础设施/平台/合规类单独成册
• 每册 3-6 个系统为宜

0.3.1 系统规模分级与拆分计划

根据每个系统的功能点数量，确定 Phase 1 的处理策略：

## 系统拆分计划

| 系统编号 | 系统名称 | 功能点数 | 子模块数 | 分级 | Phase 1 输出方式 |
|---------|---------|---------|---------|------|-----------------|
| S01 | {系统名} | 5 | 0 | 小型 | 单文件，一次性完成 |
| S02 | {系统名} | 18 | 4 | 中型 | 单文件，按功能域分批编写 |
| S05 | {系统名} | 61 | 12 | 大型 | 目录拆分，每子模块独立文件 |
| ... | ... | ... | ... | ... | ... |

分级规则：

• 小型（功能点 ≤ 6）：Phase 1 一次性加载全部功能点，输出单个完整文件
• 中型（功能点 7-20）：Phase 1 按功能域分 2-3 个批次编写，输出单文件
• 大型（功能点 > 20）：Phase 1 先输出系统概述文件，再按子模块逐个编写独立文件

子模块划分原则（大型系统）：

• 按业务流程的上下游关系分组
• 每个子模块包含 3-8 个功能点
• 同一业务域的功能点放在同一子模块
• 子模块编号：{系统编号}-M{序号:02d}，如 S05-M01

0.4 角色定义

从标书中提取业务角色，编号并描述：

## 角色定义

| 角色编码 | 角色名称 | 说明 | 关联系统 |
|---------|---------|------|---------|
| R01 | {角色1} | {职责描述} | S01,S02 |
| R02 | {角色2} | {职责描述} | S01,S03 |
| ... | ... | ... | ... |

角色提取来源：

• 技术响应表中提及的使用人员
• 技术方案中的用户角色描述
• 行业通用角色（根据行业领域推断，标注"推断"）

0.5 领域术语表

提取标书中的专业术语：

## 领域术语

| 术语 | 全称/英文 | 定义 | 关联系统 |
|------|---------|------|---------|
| {术语1} | {全称} | {定义说明} | S01,S02 |
| {术语2} | {全称} | {定义说明} | S03 |
| ... | ... | ... | ... |

包括：

• 标书原文出现的专业缩写和术语
• 行业标准/规范名称
• 系统间交互的协议/标准

0.6 通用数据类型约定

根据项目技术栈生成数据类型约定表：

## 数据类型约定

数据库：{如 MySQL 8.0 / PostgreSQL 15 / 达梦 DM8 / Oracle 19c}

| 场景 | 数据类型 | 长度/精度 | 说明 |
|------|---------|----------|------|
| 主键ID | {BIGINT/VARCHAR} | {20/36} | {自增/UUID/雪花} |
| 人员姓名 | VARCHAR | 50 | |
| 编码/代号 | VARCHAR | {根据业务} | |
| 日期时间 | DATETIME | - | {格式约定} |
| 金额 | DECIMAL | (12,2) | |
| 状态枚举 | TINYINT | 1 | |
| 长文本 | TEXT | - | |
| 布尔 | TINYINT | 1 | 0=否 1=是 |
| 文件引用 | VARCHAR | 255 | {存储方式} |
| ... | ... | ... | {按行业补充} |

根据行业特点补充领域特有字段类型，如：

• 医疗：体温DECIMAL(4,1)、血压INT、ICD编码VARCHAR(20)
• 电力：电压DECIMAL(8,3)、电流DECIMAL(8,3)、GPS坐标DECIMAL(10,7)
• 金融：利率DECIMAL(8,6)、账号VARCHAR(32)

0.7 外部系统与接口

## 外部系统清单

| 编码 | 系统名称 | 系统类型 | 对接方式 | 说明 |
|------|---------|---------|---------|------|
| EXT-01 | {系统名} | {如HIS/ERP/OA} | {REST/HL7/MQ/DB} | {简述} |
| EXT-02 | {系统名} | {类型} | {方式} | {简述} |
| ... | ... | ... | ... | ... |

0.8 合规与标准

## 合规要求

| 类别 | 标准/要求 | 影响范围 | 说明 |
|------|---------|---------|------|
| {等保/认证/行业规范} | {具体标准名} | {全局/特定系统} | {关键要求} |
| ... | ... | ... | ... |

0.9 功能原型分类

预扫描所有功能点，按通用功能原型分类（供 Phase 1 使用）：

## 功能原型分类

| 原型 | 说明 | 匹配的功能点 |
|------|------|------------|
| 数据录入/维护 | CRUD + 校验 + 同步 | S01-001, S01-006, ... |
| 评估/量表/评分 | 评估项 + 自动计算 + 等级判定 | S01-017, S01-018, ... |
| 文书/报告/表单 | 模板 + 填写 + 审核 + 签名 + 打印 | S01-014, S01-021, ... |
| 统计/分析/报表 | 维度 + 指标 + 聚合 + 可视化 | S01-037, S01-038, ... |
| 流程/闭环/审批 | 状态机 + 节点操作 + 校验 + 追踪 | S02-xxx, ... |
| 管理/配置/权限 | 配置项 + 规则 + 范围 + 审计 | S01-036, ... |
| 集成/同步/对接 | 数据映射 + 协议转换 + 监控 | S13-xxx, ... |
| 移动端/扫码 | 离线 + 扫码 + 推送 + 轻量交互 | S02-xxx, ... |

每个功能点至少归入一个原型，可归入多个。

0.10 输出与确认

将以上所有内容组装为 _metadata.md，输出到：

项目文档/01-需求分析/_metadata.md

必须向用户展示元数据摘要并等待确认，重点确认：

• 行业领域和业务特征是否准确
• 系统分域是否合理
• 系统分级和拆分计划是否合理
• 角色列表是否完整
• 领域术语是否准确
• 功能原型分类是否恰当

用户可修改任何部分后再进入 Phase 1。

---

Phase 1: 需求规格编写

目标： 读取 _metadata.md 元数据，对指定系统的每个功能点，
套用通用模板展开为工程级需求规格。

1.1 加载上下文

读取以下文件：

1. 项目文档/01-需求分析/_metadata.md — 项目元数据（含拆分计划）
2. 技术响应表中目标系统的功能清单
3. 技术方案中该系统的架构描述

从元数据中提取当前系统需要的：

• 关联角色子集
• 关联术语子集
• 关联外部系统子集
• 功能原型分类
• 系统分级（小型/中型/大型）

分级加载策略：

系统分级	加载范围	处理方式
小型	一次读取全部功能点	一次性展开所有功能，输出单文件
中型	先读功能清单，按功能域分批读取详情	分 2-3 批次展开，输出单文件
大型	先只读系统概述和功能清单摘要	先输出概述文件，再按子模块逐个加载和编写

大型系统关键原则：编写某子模块时，只读取该子模块的功能点详情，不加载其他子模块内容。

1.2 确认范围

输出该系统的功能列表供用户确认：

## {系统编号} {系统名称} — 功能清单确认

| 序号 | 功能模块 | 需求内容摘要 | 功能原型 | ▲ | 优先级 |
|------|---------|------------|---------|---|-------|
| 1 | {模块名} | {摘要} | {原型} | | P{N} |
| ... | ... | ... | ... | ... | ... |

共 {N} 个功能点，其中 ▲{M} 个。

等待用户确认后继续（AUTO_MODE 下跳过）。

1.3 逐功能展开 — 通用模板

对每个功能点，根据其功能原型选择展开策略，按以下通用模板输出：

---

通用功能需求模板

### {功能编号} {功能名称}

#### 一、功能综述

{基于技术响应表需求内容，用 2-3 段话描述：
 - 业务背景和使用场景
 - 该功能解决的业务问题
 - 与上下游功能的关系}

#### 二、业务对象

| 编码 | 业务对象 | 数据项 | 数据类型 | 长度 | 必填 | 编码引用说明 | 备注 |
|------|---------|--------|---------|------|------|------------|------|
| {BO编码} | {对象名} | {字段} | {类型} | {长度} | {Y/N} | {引用说明} | {备注} |
| ... | ... | ... | ... | ... | ... | ... | ... |

> 数据类型遵循 _metadata.md 中的数据类型约定。
> 编码引用说明标注关联字典表或外部系统数据源。

#### 三、业务活动

{描述该功能涉及的全部业务活动，包括数据的新增、修改、删除、查询、审批、同步等操作}

#### 四、用例描述

##### 用例 {用例编号}

| 项目 | 内容 |
|------|------|
| 用例编号 | {编号} |
| 用例名称 | {名称} |
| 业务说明 | {场景和目标} |
| 规范引用 | {引用 _metadata.md 合规要求，无则填"无"} |
| 业务规则 | 1. {规则1} |
| | 2. {规则2} |
| | 3. {规则3} |
| 使用范围 | {引用 _metadata.md 角色定义} |
| 先决条件 | {前置条件} |

**功能要求：**

| 类型 | 描述 |
|------|------|
| 基本功能 | 共计 {N} 个基本功能点：|
| | 1. {功能点1} |
| | 2. {功能点2} |
| 辅助功能 | {无则填"无"} |
| 提示信息 | {无则填"无"} |

**处理逻辑：**
1. {步骤1}
2. {步骤2}

**状态流转**（流程/闭环类功能适用，其他类型可省略）：

| 当前状态 | 事件 | 目标状态 | 前置校验 | 后置动作 |
|---------|------|---------|---------|---------|
| {状态A} | {事件} | {状态B} | {校验规则} | {触发动作} |
| ... | ... | ... | ... | ... |

**约束条件：**
1. {约束1}
2. {约束2}

**信息处理要求：**

| 方向 | 内容 |
|------|------|
| 输入信息 | {来源和格式} |
| 输出信息 | {业务对象引用} |

**业务表单：** {关联的业务对象/表单}

**角色权限：**

| 功能点 | 使用人员 |
|--------|---------|
| {功能点范围} | {角色编码+名称，引用 _metadata.md} |

#### 五、接口依赖

| 方向 | 对接系统 | 接口说明 | 数据格式 |
|------|---------|---------|---------|
| {输入/输出} | {引用 _metadata.md 外部系统编码} | {描述} | {格式} |

#### 六、需求追溯

| 来源 | 引用 |
|------|------|
| 技术响应表 | {系统名} 序号{N}："{原文摘要}" |
| 技术方案 | {章节引用} |
| 优先级 | P{0-3} |
| ▲标注 | 是/否 |

---

1.4 功能原型展开策略

不同功能原型在套用通用模板时，侧重点不同：

原型 A：数据录入/维护

• 业务对象重点：完整列出所有数据字段，区分"本系统自有"和"外部同步"字段
• 用例重点：录入流程、数据校验规则、批量操作、数据共享/同步
• 约束重点：字段校验规则、唯一性约束、级联更新

原型 B：评估/量表/评分

• 业务对象重点：评估维度 + 各维度选项/分值 + 结果等级 + 关联措施
• 用例重点：评估触发条件、自动计算规则、等级阈值、措施自动关联
• 业务规则重点：量表各维度的具体评分标准和分级阈值

原型 C：文书/报告/表单

• 业务对象重点：文书模板结构 + 填写内容 + 签名信息
• 用例重点：模板选择/自定义、内容组装、数据引用、审核签名、打印
• 约束重点：电子签名要求、时限要求、打印格式规范

原型 D：统计/分析/报表

• 业务对象重点：统计维度定义 + 指标定义（公式）+ 结果集
• 用例重点：查询条件组合、计算逻辑、展示形式（图表/列表/导出）
• 处理逻辑重点：数据聚合方式、时间粒度、对比基线

原型 E：流程/闭环/审批

• 业务对象重点：流程节点 + 状态定义（状态机）+ 操作记录
• 用例重点：各节点操作、状态流转规则、异常/回退处理
• 约束重点：身份校验（扫码/指纹）、多人核查、时序约束

原型 F：管理/配置/权限

• 业务对象重点：配置项 + 规则参数 + 生效条件
• 用例重点：配置范围（全局/部门/个人）、生效规则、权限分级
• 约束重点：配置变更审计、影响范围评估、回滚机制

原型 G：集成/同步/对接

• 业务对象重点：数据映射表（源字段↔目标字段）+ 同步日志
• 用例重点：同步触发机制（实时/定时/事件）、冲突处理、失败重试
• 约束重点：数据一致性保证、超时处理、监控告警

原型 H：移动端/扫码

• 业务对象重点：与PC端共用对象 + 移动端特有字段（GPS/扫码结果）
• 用例重点：离线操作、扫码交互流程、消息推送、轻量展示
• 约束重点：网络断连处理、数据同步策略、设备兼容性

1.5 文档组装

将所有功能点的展开内容组装为完整的系统需求文档：

# {系统编号} {系统名称} — 需求规格说明书

## 文档信息

| 项目 | 内容 |
|------|------|
| 项目名称 | {从 _metadata.md 读取} |
| 所属分册 | 第{N}册 {业务领域名} |
| 系统编号 | {编号} |
| 功能点总数 | {N} |
| ▲标注数 | {N} |
| 编制日期 | {YYYY-MM-DD} |
| 文档版本 | V1.0 |

## 一、系统概述
### 1.1 系统定位
### 1.2 业务范围
### 1.3 用户角色（引用 _metadata.md 角色子集）
### 1.4 系统边界

## 二、功能需求
### 2.1 {功能域1}
#### {功能编号} {功能名称}
（逐个展开）

## 三、业务对象汇总
## 四、接口汇总
## 五、需求追溯矩阵

1.6 自检清单

Phase 0 自检

• 行业领域和业务特征有明确依据（来自标书原文）
• 系统清单与技术响应表条目数一致
• 系统分级（小/中/大）合理，拆分计划完整
• 角色列表覆盖标书中提及的所有人员类型
• 数据类型约定与项目技术栈匹配
• 功能原型分类覆盖所有功能点（无遗漏）

Phase 1 通用自检（每系统）

• 功能点数量 = 数据源中该系统的条目数（精确匹配）
• 每个功能点都有完整展开（业务对象+用例+规则+约束+角色）
• 每个业务对象都有完整数据字典（字段名/类型/长度/必填/说明）
• 数据类型与 _metadata.md 约定一致
• 每个用例至少 3 条业务规则
• 每个用例都有角色权限映射（角色编码引用 _metadata.md）
• 流程/闭环类功能包含状态流转表
• ▲标注功能已标注对应优先级
• 所有编号连续无缺失
• 接口依赖引用 _metadata.md 外部系统编码
• 需求追溯矩阵完整

Phase 1 大型系统附加自检

• 子模块划分覆盖全部功能点（无遗漏、无重复）
• 00-系统概述.md 的 BO 汇总与各子模块文件的 BO 一致
• 跨子模块引用的业务对象编码一致（同一 BO 在不同子模块中编码相同）
• 各子模块文件行数 ≤ 500 行
• 系统概述中的接口汇总覆盖所有子模块的接口依赖

1.7 输出与保存

小型/中型系统输出文件路径：

项目文档/01-需求分析/{系统编号}-{系统名称}.md

大型系统输出目录结构：

项目文档/01-需求分析/{系统编号}-{系统名称}/
├── 00-系统概述.md            （系统定位+BO汇总+接口汇总+追溯矩阵）
├── 01-{子模块名称}.md        （子模块1的详细功能需求）
├── 02-{子模块名称}.md        （子模块2的详细功能需求）
└── ...

1.8 大型系统编写流程

大型系统（功能点 > 20）的 Phase 1 分两步执行：

步骤一：系统概述文件

输出 00-系统概述.md，包含：

• 文档信息（同 1.5 模板的文档信息部分）
• 一、系统概述（定位、业务范围、角色、边界）
• 二、子模块划分表（子模块编号/名称/功能点范围/功能点数）
• 三、业务对象汇总（全系统BO清单，只列编码+名称+所属子模块）
• 四、接口汇总（全系统接口清单）
• 五、需求追溯矩阵（全系统）

步骤二：逐子模块编写

对每个子模块，读取该子模块的功能点详情，按 1.3 模板逐功能展开，
输出 {序号}-{子模块名称}.md。

每个子模块文件包含：

• 子模块信息表（所属系统、功能点范围、功能点数）
• 该子模块全部功能点的详细展开
• 该子模块的BO数据字典汇总

单文件行数控制：建议不超过 500 行。如某子模块功能点过多（>8个），考虑进一步拆分。

注意：如文件较大，使用 Bash 工具的 cat > file << 'HEREDOC' 方式写入。

---

编号规则（通用）

系统编号

S{系统序号:02d}  例: S01, S02, ..., S19

功能需求编号

S{系统序号:02d}-{功能序号:03d}  例: S01-001, S05-012

用例编号

U-{系统序号:02d}-{功能序号:03d}-{用例序号:02d}  例: U-01-001-01

业务对象编号

BO-{系统序号:02d}-{序号:03d}  例: BO-01-001

---

修复模式工作流程

当进入修复模式时，执行以下步骤：

R1. 读取反馈

读取用户提供的评审反馈或问题清单：

• 按严重程度分组：缺失 / 错误 / 不完整 / 建议
• 按操作类型分组：补充 / 修正 / 完善 / 删除

R2. 加载上下文

读取 _metadata.md 和目标系统的需求文件，作为修复基准。

R3. 逐项修复

按严重程度优先处理：

问题类型	修复方式
功能点缺失	从数据源提取，按模板展开
业务对象缺字段	参考 _metadata.md 数据约定补充
用例缺业务规则	分析业务场景补充，每用例至少3条
角色权限缺失	引用 _metadata.md 角色定义补充
编号不连续	重新编号，更新追溯矩阵
数据类型不当	参考 _metadata.md 数据约定修正

R4. 修复后验证

• 重新执行自检清单
• 输出修复摘要

---

自动模式

当上下文中包含 AUTO_MODE=true 时：

• 跳过确认步骤：Phase 0 和 Phase 1 中的用户确认步骤均跳过
• 跳过中间询问：编写过程中不暂停
• 保留自检：发现问题自动修复
• 连续系统：一个系统完成后自动进入下一个

---

常见错误类型

类型	后果	预防
功能点遗漏	需求缺失导致开发遗漏	编写后核对条目数
业务对象缺字段	详细设计需返工	按原型策略完整列出
用例缺业务规则	开发无法处理边界情况	每用例至少3条规则
角色权限缺失	权限设计遗漏	每用例必有角色表
元数据与正文不一致	角色/术语/类型引用错乱	正文引用 _metadata.md 编码
接口遗漏	集成开发时才发现	对照 _metadata.md 外部系统表

---

输出格式

所有文件输出到 项目文档/01-需求分析/ 目录，Markdown 格式。

目录结构：

项目文档/01-需求分析/
├── _metadata.md                          （Phase 0 输出，全局唯一）
├── S01-油库任务管理.md                    （小型系统：单文件）
├── S02-油料供应管理.md                    （中型系统：单文件）
├── S05-质量计量管理/                      （大型系统：目录拆分）
│   ├── 00-系统概述.md
│   ├── 01-检验管理.md
│   ├── 02-计量管理.md
│   └── ...
└── ...

格式规范：

• 标题使用 # ## ### #### 层级
• 表格使用 Markdown 表格语法
• 业务对象表列：编码/业务对象/数据项/数据类型/长度/必填/编码引用说明/备注
• 用例描述使用 key-value 表格
• 单文件行数建议不超过 500 行

---

完成状态

Phase 0 完成

--- BID-REQUIREMENTS PHASE0 COMPLETE ---
项目名称: {项目名称}
行业领域: {行业} / {细分领域}
系统总数: {N}
功能点总数: {N}
分册数: {N}
小型系统: {N} 个（单文件输出）
中型系统: {N} 个（单文件分批编写）
大型系统: {N} 个（目录拆分输出）
角色数: {N}
术语数: {N}
外部系统数: {N}
输出文件: 项目文档/01-需求分析/_metadata.md
状态: SUCCESS
--- END ---

Phase 1 完成（每系统）

--- BID-REQUIREMENTS PHASE1 COMPLETE ---
系统编号: {编号}
系统名称: {名称}
系统分级: {小型/中型/大型}
所属分册: 第{N}册 {领域}
功能点总数: {N}
子模块数: {N}（大型系统适用，小型/中型填0）
▲标注数: {N}
业务对象数: {N}
用例数: {N}
数据字段总数: {N}
接口数: {N}
输出文件: 项目文档/01-需求分析/{文件名或目录名}
状态: SUCCESS
--- END ---