06 · 需求设计说明书规范

📦 来源：wl-skills-design v0.11.1 · standards/06-spec-doc.md · 可判定条目由 verify（[M] 机械项）自动执行。

本规范定义需求设计说明书的结构、深度、追溯与验证口径。示例均为匿名合成内容，不对应任何组织、项目、地点、人员或线上数据。

§一交付 profile 与事实边界

生成前记录以下 profile；未确认项使用 【待补充：说明】 并标记 Pending，不得编造。

字段	取值	说明
`projectCode`	已确认代号	用作目录名，不写组织名称
`moduleScope`	模块与非目标	控制本次边界
`deliveryFormat`	`markdown-source` / `final-word`	决定固定页面检查是否可执行
`dictionarySource`	词典路径 / Pending	统一字段与枚举
`roles`	已确认角色集合	用于泳道和权限矩阵
`externalSystems`	已确认系统代号集合	不使用真实域名、账号或地址
`privacyClass`	public / internal / restricted	控制脱敏和展示

事实优先级：用户提供并确认的事实 → 工作区现有设计 → 明确标注的假设 → Pending。假设不得伪装成事实；验证和评审默认只读。

§二文件边界与装配

Markdown 源文件固定为五类：

text

docs/spec/{project-code}/
├── ch1-3.md
├── 4.1-{submodule}.md
├── 4.2-{submodule}.md
├── ...
└── 4.N-data-report.md

不得为单个流程、活动或 IPO 创建任意命名文件。合并顺序为 ch1-3.md → 各子模块文件 → 4.N-data-report.md。

最终 Word 装配包含：信息封面、签署封面、修订记录、自动目录、正文、页眉和页脚。Markdown 阶段不模拟分页；完成 Word 装配后必须渲染核验目录、表格、分页、页眉和页脚。

§三正文结构

3.1 系统目标

3～5 条，每条 20～60 字。
描述业务能力、范围和可验证价值，不写技术实现。
缺少业务目标时保留 Pending，不用通用口号补齐数量。

匿名句式示例：

markdown

- 申请受理：以结构化申请驱动审核，减少重复录入并保留处理轨迹。
- 过程可见：展示待办、处理中和已完成状态，为授权角色提供可追溯视图。

3.2 组织、角色与术语

岗位定义表固定五列：

序号	角色名称	所属职能	角色职责	系统操作范围

术语表固定四列：

序号	标准术语	类别	定义与边界

角色名称必须与流程泳道和权限矩阵一致。术语定义至少回答“是什么”和“适用范围”；个人姓名不得作为角色名称。

3.3 总体设计

第 3 章包含：

业务架构图占位和边界说明；
系统流程总图占位与流程清单；
功能层级表。

流程清单：

子模块	流程稳定 ID	流程编码	流程名称	范围

功能层级：

子模块	一级菜单	二级菜单	功能稳定 ID	功能编码

3.4 子模块结构

每个 4.x 子模块固定包含：

text

4.x.1 系统流程清单
4.x.2 系统流程说明
4.x.3 流程与作业画面对照表
4.x.4 功能设计
4.x.5 内部接口
4.x.6 权限矩阵

3.5 数据需求

区分外部输入和数据输出：

数据稳定 ID	数据对象	来源/目标系统代号	关键字段 ID	条件或时机	用途

不得猜测真实表名、系统名、同步周期或字段。未确认时使用 Pending。

3.6 报表设计

报表清单至少包含编码、名称、模块、类型、用途、使用角色、刷新策略和导出支持。每张报表说明必须包含：

查看权限；
数据刷新策略；
导出支持与限制；
数据来源；
查询条件表；
输出字段表；
样例图占位。

刷新、导出和权限均来自 profile 或用户确认，不设静默默认值。

§四流程与活动说明

流程说明包含范围、触发条件、主路径、异常路径和结束条件。每条流程紧跟流程图占位和活动说明表。

活动稳定 ID	活动编码	活动名称	执行角色	输入	处理	输出

活动编码使用 [流程编码]-[操作类型]-[NN]；操作类型为 E 执行、C 检查、M 人工。序号从 01 连续递增。活动集合必须与 draw.io 节点集合一致。

执行类（E）活动是未来系统命令端点的需求侧投影：每个 E 活动应可对应一个明确的后端命令动作（如下达、取消、确认、退回），在 IPO 中由同名按钮承载。无法建立该对应关系时，说明活动粒度过粗或过细，应先调整活动划分再进入功能设计。

流程与作业画面对照表：

流程稳定 ID	活动稳定 ID	功能稳定 ID	功能编码	页面	操作

纯线下活动明确写“线下操作（无系统支持）”，不得虚构页面。

§五功能设计与 IPO

每个功能有且仅有“画面逻辑”和“处理逻辑（IPO）”两个小节。

画面逻辑至少说明：页面入口、页面类型、原型占位、字段、按钮、状态、联动和权限。存在字段联动时给出字段交互矩阵；存在状态变化时给出状态图和状态约束表。

IPO 固定五列：

序号	按钮功能/字段	输入（Input）	处理逻辑（Process）	输出（Output）

规则：

无输入填 /，不留空。
字段行写明必填性、控件类型、数据来源、格式、范围和联动。
提交类操作的 Process 分为“数据校验”和“数据处理”；数据处理说明数据变化和触发事件。
Output 同时描述失败与成功结果，包括页面、消息和状态变化。
取消类操作写“关闭【页面名称】，不保存任何修改”。
数据表名、接口名或规则未知时使用 Pending，不得套用样例值。

5.1 按钮级覆盖

IPO 表按“一行一按钮/一功能”组织，颗粒度基线：

页面工具栏、行操作和查询区的每个按钮至少占一行；批量按钮与单选按钮不合并成一行。
初始化与重置各占一行：初始化说明默认查询条件、排序和状态着色规则；重置说明清空范围和还原行为。
每个命令按钮（改变业务状态的操作）与流程中的 E 活动一一对应；按钮名与活动名称使用同一动词。

5.2 Process 步骤颗粒度基线（GB 系列）

命令按钮的 Process 使用编号步骤书写，每个步骤只表达一件事，并按以下要素自检。已确认的要素必须写出具体值，未确认的要素标 Pending，不得笼统写“系统处理”：

基线	要素	书写要求
GB1	数据对象	写出被读写的表稳定 ID 或表名、被变更的字段名；读和写分开成步
GB2	状态与字典	校验和赋值使用字典稳定值（如 `W1A`），不写“状态正确”这类模糊表述
GB3	前置校验	逐条列出允许操作的状态组合与排除条件；批量操作说明逐条还是整批校验
GB4	审计与履历	写明同步更新审计字段，以及写入哪张履历表、记录哪些关键值
GB5	联动与外部同步	说明主档/明细联动、对外系统触发时机和失败时的补偿行为
GB6	异常文案	校验失败与系统失败分别给出提示文案原文（用「」包裹）
GB7	展示规则	列表排序字段、行着色、按钮可用条件等展示规则随步骤写明
GB8	步骤可测	每个步骤可映射为一条可执行的校验或一次明确的写入，无法验证的步骤拆分或标 Pending

匿名片段（仅示意格式，对象与值均为合成）：

markdown

| 3 | 【工单下达】按钮 | 选中的工单（支持批量） | 1. 校验选中工单的 WORK_STATUS：仅允许 `W1A 未开始`；2. 校验 SEND_FLAG 为空（未下达）；3. 通过后更新 ORD_WORK_MAIN.SEND_FLAG 为 `Y`，同步更新审计字段；4. 校验 ORD_WORK_MAIN_D 明细完整后触发对外同步事件 EVT_WORK_RELEASED；5. 异常处理：状态不合法弹出「选中工单不满足下达条件，请检查！」；更新失败弹出「下达失败，请联系维护人员！」；6. 将下达的工单号写入履历表 ORD_WORK_LOG | 成功：列表刷新、行变为已下达样式；失败：保留选中并提示 |

§六内部接口与跨文档追溯

说明书中的内部接口只表达需求级契约：

接口稳定 ID	接口编码	名称	提供方功能 ID	消费方功能 ID	输入字段 ID	输出字段 ID	触发时机

详细 REST/OpenAPI 由接口设计 Skill 维护。说明书不得复制一份可能漂移的完整接口契约。

必须维护以下追溯：

text

流程 → 活动 → 功能 → 页面
功能 → 权限角色
功能 → 接口 → 字段
持久化字段 → 词典字段 → 数据库字段

优先使用统一设计模型中的稳定 ID；没有模型时使用编码，并报告无法可靠匹配的项。

§七权限设计

权限矩阵覆盖子模块内全部功能和操作。权限值只使用 ✅、❌、只读、自建。存在行级数据权限时，另列角色、范围维度、控制字段 ID 和说明；无行级权限需求时该条件项不计入总数。

§八隐私与安全

示例只使用 DEMO、REQ 等合成代号和角色，不写组织、地点、人员、联系方式、域名、账号、令牌或生产数据。
个人信息字段只描述用途、最小化、展示和访问策略，不填示例值。
外部系统使用已确认代号；截图和附件必须单独完成元数据、修订历史与嵌入对象检查。
未经授权不写入既有文件，不把评审当成修复授权。

§九报告与图片

图片统一使用 【此处插入 {名称} 图】。图片占位必须可追溯到流程、页面或报表稳定 ID。

报告中的查询条件和输出字段必须使用词典定义；个人信息字段需标注掩码、授权和导出限制。报表功能是否支持导出、文件格式和刷新频率必须有 profile 证据。

§十编码规则

对象	格式	示例
流程	`[模块码]-A-[NN]`	`REQ-A-01`
活动	`[流程编码]-[E/C/M]-[NN]`	`REQ-A-01-E-01`
功能	`[模块码][NNN]`，可插入 2～4 位大写子域码	`REQ001` / `REQPS001`
报表	`RP[NNN]`	`RP001`
接口	`API-[模块码]-[NNN]`	`API-REQ-001`

功能超过约 10 个或分属多个二级菜单时推荐启用子域码（如 PS 计划调度、BD 基础数据），同一子模块内只用一种格式。编码全文唯一且稳定；显示名称变化不应导致稳定 ID 重建。

§十一验证清单（43 项）

先记录 deliveryFormat。P01–P05 只能对 final-word 判定通过或失败；在 markdown-source 阶段一律标记 Pending 并注明“待 Word 装配验证”，不得判失败。

执行方式标记：[M] 机械可判、[J] 语义判断。四域 [M] 项均由 wl-skills-design verify 执行（未覆盖时输出 skip）；Agent 先取机械结论，再判 [J] 项，合并为同一编号的报告。

A. 固定页面完整性（5 项）

[ ] P01 [J] — 信息封面和签署封面均存在，变量字段完整
[ ] P02 [J] — 修订记录存在且版本、日期、修改说明完整
[ ] P03 [J] — 自动目录显示三级标题和页码
[ ] P04 [J] — 页眉符合交付 profile 且不泄露未授权信息
[ ] P05 [J] — 页脚包含文档代号、版本、页码和隐私级别

B. 正文结构完整性（6 项）

[ ] S01 [M] — 第 1～3 章全部存在
[ ] S02 [M] — 系统目标为 3～5 条，每条 20～60 字；事实不足则标 Pending
[ ] S03 [M] — 每个子模块包含 4.x.1～4.x.6
[ ] S04 [M] — 最后两节为数据需求和报表设计
[ ] S05 [M] — 所有图片节点有统一占位或有效引用
[ ] S06 [J] — 目录层级与正文一致

C. 编码规范（4 项）

[ ] C01 [M] — 流程编码符合 [模块码]-A-[NN]
[ ] C02 [M] — 活动编码符合 [流程编码]-[E/C/M]-[NN] 且连续
[ ] C03 [M] — 功能编码符合 [模块码][NNN] 或含子域码的 [模块码][子域码][NNN]
[ ] C04 [M] — 编码和稳定 ID 无重复

D. 组织与术语（4 项）

[ ] D01 [M] — 角色表五列齐全
[ ] D02 [J] — 所有参与流程或权限的角色都已定义
[ ] D03 [M] — 术语表四列齐全
[ ] D04 [J] — 每条术语有定义、边界和来源

E. IPO 质量（11 项）

[ ] I01 [M] — 每个功能有且仅有画面逻辑和 IPO 两小节
[ ] I02 [J] — 画面逻辑含入口、类型、原型引用和字段说明
[ ] I02b [J] — 有字段联动时存在完整字段交互矩阵
[ ] I02c [J] — 有状态变化时存在状态图和状态约束表
[ ] I03 [J] — 多页面功能按页面分段
[ ] I04 [M] — IPO 表固定五列
[ ] I05 [M] — 无输入项使用 /
[ ] I06 [J] — 字段行描述必填、类型、来源和校验
[ ] I07 [J] — 提交类操作覆盖校验、数据变化、触发事件、成功和失败
[ ] I08 [J] — 取消类操作明确不保存修改
[ ] I09 [J] — 条件必填、显隐和联动规则包含触发与还原逻辑

F. 流程说明（3 项）

[ ] F01 [M] — 每条流程包含流程图、说明和活动表
[ ] F02 [M] — 活动表七列齐全并覆盖所有节点
[ ] F03 [M] — 流程与作业画面对照表覆盖所有活动

G. 数据与报表（2 项）

[ ] G01 [J] — 数据需求区分外部输入和数据输出，并说明来源/目标
[ ] G02 [J] — 每张报表具备权限、刷新、导出、来源、查询条件、输出字段和样例占位

H. 权限设计（2 项 + 1 条件项）

[ ] H01 [J] — 权限矩阵覆盖全部功能和操作
[ ] H02 [J] — 权限值只使用约定枚举
[ ] H03（条件项）[J] [J] — 存在行级权限时，范围维度与控制字段完整；无需求时不计入总数

X. 跨文档一致性（6 项）

[ ] X01 [M] — 流程清单与活动集合双向一致
[ ] X02 [M] — 活动集合与画面对照表双向一致
[ ] X03 [M] — 对照表引用的功能均有定义，且无孤儿功能
[ ] X04 [J] — 功能与权限矩阵双向一致
[ ] X05 [J] — 内部接口引用的提供方和消费方功能存在
[ ] X06 [J] — 流程、岗位表和权限矩阵的角色集合一致

§十二验证闭环

验证结果逐项记录：规则 ID、Pass/Fail/Pending/NotApplicable、证据路径与锚点、差异和建议。[M] 项以 wl-skills-design verify spec 的机械结论为准，[J] 项由 Agent 判定并给出证据；两类结果合并输出，不得相互覆盖。

text

交付阶段：markdown-source | final-word
目录项：43
通过：N | 失败：M | 暂挂：K | 不适用：L

Pass + Fail + Pending + NotApplicable 必须等于 43；H03 作为条件项单独报告。Pending 和 NotApplicable 不得伪装成 Pass。

创建模式只修复本轮生成内容；验证或评审模式只读。既有内容只有在用户明确授权 repair 后才可修改，并在修改后重跑受影响项和 X 组。最终 Word 必须渲染核验，不能只验证文件存在。

06 · 需求设计说明书规范 ​

§一 交付 profile 与事实边界 ​

§二 文件边界与装配 ​

§三 正文结构 ​

3.1 系统目标 ​

3.2 组织、角色与术语 ​

3.3 总体设计 ​

3.4 子模块结构 ​

3.5 数据需求 ​

3.6 报表设计 ​

§四 流程与活动说明 ​

§五 功能设计与 IPO ​

5.1 按钮级覆盖 ​

5.2 Process 步骤颗粒度基线（GB 系列） ​

§六 内部接口与跨文档追溯 ​

§七 权限设计 ​

§八 隐私与安全 ​

§九 报告与图片 ​

§十 编码规则 ​

§十一 验证清单（43 项） ​

A. 固定页面完整性（5 项） ​

B. 正文结构完整性（6 项） ​

C. 编码规范（4 项） ​

D. 组织与术语（4 项） ​

E. IPO 质量（11 项） ​

F. 流程说明（3 项） ​

G. 数据与报表（2 项） ​

H. 权限设计（2 项 + 1 条件项） ​

X. 跨文档一致性（6 项） ​

§十二 验证闭环 ​

06 · 需求设计说明书规范

§一交付 profile 与事实边界

§二文件边界与装配

§三正文结构

3.1 系统目标

3.2 组织、角色与术语

3.3 总体设计

3.4 子模块结构

3.5 数据需求

3.6 报表设计

§四流程与活动说明

§五功能设计与 IPO

5.1 按钮级覆盖

5.2 Process 步骤颗粒度基线（GB 系列）

§六内部接口与跨文档追溯

§七权限设计

§八隐私与安全

§九报告与图片

§十编码规则

§十一验证清单（43 项）

A. 固定页面完整性（5 项）

B. 正文结构完整性（6 项）

C. 编码规范（4 项）

D. 组织与术语（4 项）

E. IPO 质量（11 项）

F. 流程说明（3 项）

G. 数据与报表（2 项）

H. 权限设计（2 项 + 1 条件项）

X. 跨文档一致性（6 项）

§十二验证闭环