需求规格说明书写作规范（西点信息 · 投行类系统）

本技能沉淀自一份投行类管理系统的需求规格说明书（实测 v4.0.5，3187 段 / 221 表）。
后续所有需求文档按此格式产出，保证与既有文档风格一致、可直接并入主文档。

> 目录结构按需裁剪（v1.4） —— 三处不要写死：
> ① H1 系统名按本次开发的功能来定（写 <系统名>标准产品需求），不要沿用模板来源文档的系统名；
> ② 端别层（H2 WEB端需求 这类）默认不设 —— 只有同一系统跨多个端且各端需求不同才加，
> 功能只落一个端时整层省掉、一级功能模块直接挂 H1（功能点随之从 H4 上移到 H3）；
> ③ 定制化需求章默认不写 —— 只有确有特殊定义、或明确属于定制功能时才追加。
> 详见「文档骨架」与 references/01-文档整体结构.md 第三～六节。

> v1.3 起需求点结构为「七节式」（业务说明 / 业务规则 / 使用角色 / 权限说明 / 功能说明 / 页面字段说明 / 输入、输出），
> 替代 v4.0.5 及更早文档用的「四段式」。同一份文档内不要混用两套结构；要把新章节并入仍在用四段式的主文档时，
> 先与业务方确认口径再动手。两套的槽位对照见 references/02-需求点模板.md 第九节。

> 交付物形态（v1.1 / v1.2 起脚本已内置，别再靠人肉补）
> ① 目录打开即自动重排（清模板旧缓存 + w:updateFields，不必手动 F9）；
> ② 每张表都有显式全边框（模板自带的菜单目录表本身无边框，光套样式压不住）；
> ③ 逐条列用真实项目符号（业务说明/功能概述不加、单条不加、手写「1、」自动去掉）；
> ④ 图：流程图用 skill mermaid转图片 渲染、界面截图用 Playwright 从原型工程抓；
> 宽 ≤15cm / 高 ≤20.5cm 双向封顶，差于 1:2.2 的图先拆上下两张（否则字小到读不出）。
> 详见「生成方式」一节与 references/03-样式与编号规范.md 第五、六节。

何时使用

• 写新的《××需求规格说明书》/《××需求说明书》；
• 给现有需求规格说明书补章节、补需求点；
• 把口头/邮件/访谈材料整理成规范需求点；
• 检查一份需求文档是否符合本规范。

四条铁律

1. 需求点采用"七节式"：业务说明 → 业务规则 → 使用角色 → 权限说明 → 功能说明 → 页面字段说明 → 输入、输出，顺序固定，无内容的节可整节省略（见 references/02-需求点模板.md）。业务说明 / 功能说明 / 输入、输出 三节不能省。
2. 「输入、输出」必须成对写：输入 = 这个功能点运行需要哪些数据（表 数据项 | 来源 | 说明），输出 = 它产生或改变哪些数据（表 数据项 | 去向 | 说明）。只写单向的"数据来源"是旧四段式写法，不算完成。
3. 操作/字段明细一律用三列表：名称 | 类型 | 规则/说明（112 张表、281 个"按钮"条目实测）。不要用散文描述按钮行为。
4. 标题层级与【菜单目录】强对应：H1 系统 →〔H2 端别〕→ 一级功能模块 → 功能点（页面级）→ 七节式小节，禁止跳级。
   系统名按本次开发的功能来定（写 <系统名>标准产品需求，不要沿用别的系统的名字）；
   端别层是按需的 —— 只有同一系统跨多个端且各端需求不同才设，功能只落一个端时整层不要（见下方骨架与 references/01）。

文档骨架（自上而下）

封面：系统名 / 需求说明书vX.Y.Z / 西安西点信息技术有限公司 / 年月
文档修改历史  表：版本号 | 修改日期 | 编写人 | 评审人 | 批准人 | 修改内容
编写说明      3 条固定说明（原样保留）
目录（TOC 域，**打开文档即按当前正文自动重排**，不必手动 F9）
H1 菜单目录   +  表：一级菜单 | 二级菜单 | 三级菜单

┌─ 默认形态：功能只落一个端，**不设端别层** ────────────────────
H1 <系统名称>标准产品需求          ← 系统名按本次开发的功能定
    H2 <版本>变化概览              ← 仅大版本升级时写；非功能点，不要挂功能点
    H2 一级功能模块（首页 / ××管理 / ××统计分析 / ××基础维护 / 系统设置 …）
        H3 功能点（页面级）
            H4 业务说明 / 业务规则 / 使用角色 / 权限说明 / 功能说明 / 页面字段说明 / 输入、输出

┌─ 多端形态：同一系统跨多个端且各端需求不同时才用 ───────────────
H1 <系统名称>标准产品需求
    H2 <端别>需求（WEB端 / 移动端 / 助手端 / 客户端 …；本期没需求的端不写）
        H3 一级功能模块 → H4 功能点（页面级）→ H5 七节式

裁剪口径（详见 references/01-文档整体结构.md 第五、六节）

• 系统：本次需求涉及几个系统就留几个 H1 <系统名>标准产品需求，只涉及一个就留一个；
• 端别层：只落一个端 → 不设端别层（H2 直接是一级功能模块）；跨多端 → 只写本期有需求的端；
• 定制化需求章：默认不写。只有该功能确有特殊定义、或明确属于定制功能才追加这一章；
  能并进标准产品功能点写的（如"多封函证共用一个快递面单"这类形态差异）一律并进去，不另立定制章。
  不写时连引言、需求总览、空标题一起省（空标题会白占一个自动编号）；
• 裁剪只删章节，不要改章节名、不要重排顺序、不要手写序号（序号自动）。

「定制化需求」是按需章节：项目没有定制内容就整章不写 —— 连"定制化需求引言""需求总览"一起省，不要留空标题（空标题还会白占一个自动编号）。判断口径：一条需求如果本来就落在标准产品功能点上（比如"多封函证共用一个面单"这种形态差异），就并进对应功能点写，不另立定制章。

生成方式（推荐直接跑脚本）

# 用户环境：C:/ProgramData/Anaconda3/envs/pytorch/python.exe
python scripts/build_req_spec.py "D:/out/××需求规格说明书V1.0.docx"

脚本 scripts/build_req_spec.py：
- 以 assets/需求规格说明书_模板.docx 为底（已剥离正文，完整保留原文档的 styles.xml、numbering.xml、页眉页脚、多级标题自动编号）；标题序号 1. / 1.1. / 1.1.1. / 1.1.1.1. 全自动，不要手写序号；
- 传入 SPEC 字典即可生成，示例见文件末尾 EXAMPLE；
- 关键 API：h1..h6 / p / table / kv / bullets / fig / req(...)（一次生成七节式）；
req(..., level=) 传的是功能点的层级，按目录形态选：单端（不设端别层）3 → 功能点 H3 + 七节 H4；
多端（有端别层）4（默认）→ 功能点 H4 + 七节 H5；多页模块再 +1 传 5；定制化需求章传 3。
七节的入参名即节名：业务说明 / 业务规则 / 使用角色 / 权限说明 / 功能说明 / 页面字段说明 / 输入输出（注意「输入、输出」的参数名是 输入输出）。
旧四段式的键名（用户场景/功能描述/补充说明…）会直接报 ValueError 并给出迁移指引 —— 四段式的「补充说明」在七节式里没有一一对应项，静默映射会写错文档。迁移对照见 references/02-需求点模板.md 第九节。
- 已知易踩坑：模板前置有一个空标题段同时承载分节符，脚本会自动摘掉其标题样式（不能删，否则页面设置丢失）；findall 请用 body.findall(W) 而非 W+'p'（W 已含 }p）。

脚本自带的五条"格式底线"（v1.1 起，别再靠人肉补）

1. 目录自动更新 —— 清掉模板里带过来的旧条目（那是另一份文档的"1. 引言 / 1.1 编写目的"，不更新域就会显示这些无关内容）+ settings 置 w:updateFields + 域起点标 w:dirty；Word/WPS 打开即按当前正文重排。收录层级默认沿用主文档的 \o "1-3"，要让 H4 功能点也进目录就传 SPEC['目录层级'] = '1-4'。
2. 每张表都有显式全边框 —— 收尾统一写 tblBorders（六向 single＋sz=4＋color=auto）。必须显式写：模板自带的菜单目录表本来是无边框的（六向 val="none"），而直接格式比 Table Grid 样式更"具体"，光套样式压不住。
3. 逐条列自动加项目符号 —— 用 numbering 里现成的 bullet 定义（实心圆 ●、left=420 hanging=420），不是手打"●"。覆盖 业务规则 / 使用角色 / 权限说明 / 页面字段说明 的逐条内容，段落级清单用 ('bullets', [...]) 块。两条口径：只有一条时不加圆点（"● 无"很怪）；叙述性段落不加（业务说明 与 功能说明 的 功能概述，加了就变清单）。
   另一条七节式专有口径：节标题已承担标签职责时不要再写标签行 —— 业务规则/使用角色/页面字段说明 走无标签（prefix=False），只有 功能说明 里的 二级页面/操作说明 和 输入、输出 的 输入/输出 才写 xxx：。
4. 条目开头的手写序号会被自动去掉（1、 → 加圆点后就成了"● 1、…"两层标记）。若某条序号被正文引用（"见第 4 点"），那一条别用 bullets，改用 p() 逐条写。
5. 两张"标准化"表自动补表头 —— 操作说明（名称|类型|规则/说明）、输入（数据项|来源|说明）、输出（数据项|去向|说明）、页面字段说明（字段名称|规则/说明）只写数据行即可，首行不是标准表头时脚本自动补一行。

插图（v1.2）—— 文档没有图不算交付

('h3', '业务流程'),
('p', '回函管理的业务链路：……。下面三张图分别是……。'),
('fig', dict(图注='回函管理业务数据分工（AI 读取 / 人工定性 / 系统推导）', 图片=r'D:/proj/docs/figures/mermaid_0.png')),

• 图源先渲染：用 skill mermaid转图片 把 Markdown 里的 ``mermaid 代码块导出成 PNG：python ~/.codebuddy/skills/mermaid-doc-rendere/scripts/render_mermaid.py <md> --out <图目录> --format png --scale 3（输出按 md 中出现顺序命名mermaid_0/1/2…；**--scale 3` 是为了打印清晰**，2 也行但别更低）
• 尺寸双向封顶：宽 ≤ 15cm（正文区）、高 ≤ 20.5cm —— 纵向流程图（flowchart TB 长链路，
  宽高比能到 1:1.8）会自动改按高度反算宽度，否则一张图横跨两三页
• 又高又瘦的图先拆：宽高比差于 1:2.2 的，按页高封顶后宽度只剩一点点，字会小到读不出
  （实测 1:2.35 → 8.7cm 宽、约 4.7pt）。用 scripts/split_image_for_docx.py <图> 拆成
  <图>_top.png / <图>_bottom.png（切线自动挑最靠近中部的空白带，不切进方框里；
  避开竖线箭头是允许的）→ 拆完分别约 7.4pt / 9.3pt，可读。图注写「（上半：…）」「（下半：…，接上图）」
• 图注：用「列出段落1」样式（styleId 25）、写在图片上方、冒号结尾（如「回函管理数据流转路径：」）；
  不要写「图 4.5-1」这类手写图号 —— 标题编号是样式自动生成的，插删章节后手写图号必然对不上
• 界面截图（界面原型图）：传图片路径（或 {'图片':…, '图注':…}）就插图，也可以传一个列表（一个功能点常有多个入口/状态：原始文件 / AI 批注、首次确认 / 修改态…）→ 逐张插：
  python '界面原型图': [ dict(图注='回函管理列表（总览）', 图片=UI('ui_reply_list.png')), dict(图注='展开行：回函记录表 + 留痕', 图片=UI('ui_expand_row.png')), ],
• 从原型工程抓（Playwright 驱动 dev server），抓完降采样到 ≤1500px 宽——15cm 宽里 1500px ≈ 254dpi，肉眼无差别而 docx 体积小 4 倍；
• 字号提醒：整屏截图（1680px 宽）铺到 15cm 里，界面上 14px 的字只剩 ≈3.5pt —— 读者必须放大看。要看清细节就另出「近景图」（裁到关键区域再插），别指望一张整屏图能同时交代全局和细节；
• 截图必须与当前界面一致；界面已经改了但图没重抓，比没有图更糟（读者会照着旧图理解产品）。
• 改了 md 里的图就必须重跑渲染，否则 Word 里还是旧图（脚本不会自己发现）
• 图片文件不存在时插灰色占位 [图表未找到：…] 并打警告，不会让整篇文档生成失败

没有脚本可用时：直接以 assets/需求规格说明书_模板.docx 为副本手写，沿用其中的 heading 1..6 样式；不要新建样式、不要手工改字号。

硬性格式参数（详见 references/03）

样式层级

正文直接格式（★ 光靠样式不够 —— 主文档的排版是逐段写死的，必须照抄）

表格版式（_fix_table() 已封好）：每张表显式写 tblBorders（六向 single、sz=4、color=auto）＋ tblW pct 5000 ＋ tblLayout fixed ＋ 同步 tblGrid 列宽。

元素顺序（改 XML 时最致命的坑）：w:numPr 在 pPr 里必须排在 w:spacing/w:ind 之前；w:tblBorders 在 tblPr 里必须排在 w:tblLayout/tblCellMar/tblLook 之前；w:updateFields 在 settings 里必须排在 w:compat 之前。顺序错 Word 打开会报"文档已损坏"，且 python-docx 不会拦你 —— 一律用带顺序的插入（脚本里是 _tbl_pr_set() / ppr.get_or_add_numPr() / 以 w:compat 为锚点），不要 append。

> 只设 eastAsia=宋体 会让数字/英文落到样式里的 Calibri，肉眼可见不一致；行距不显式写 line=360 会明显偏紧。脚本里 fmt_para() / fmt_run() 已封好，直接调用即可。

页面：A4（21×29.7cm）；标题编号 %1. %1.%2. %1.%2.%3. … 由样式内置的 numId 驱动。

自检清单（交付前逐条过）

• [ ] H1 系统名是本次开发的系统 —— 不是照抄模板来源文档的系统名；涉及几个系统就几个 H1
• [ ] 端别层按需：功能只落一个端 → 不设端别层（H2 直接是一级功能模块）；设了端别层 → 只列本期有需求的端，没有需求的端不留空标题
• [ ] 每个功能点都能在【菜单目录】里找到对应菜单，反之亦然（菜单与需求点不重复、不遗漏）
• [ ] 每个功能点都有 业务说明 / 功能说明 / 输入、输出 这三节（不能省）；有权限差异的必须写 权限说明
• [ ] 七节顺序固定、节名未改写：业务说明 → 业务规则 → 使用角色 → 权限说明 → 功能说明 → 页面字段说明 → 输入、输出
• [ ] 「输入、输出」成对写全：输入表 数据项|来源|说明、输出表 数据项|去向|说明 都在，且来源/去向写的是"人工录入 / 哪个系统对接 / 系统推导 / 去向：哪个页面"这一层，不是技术实现（接口名、表名、SQL）
• [ ] 使用角色 与 权限说明 不重叠 —— 权限说明里没有"使用人员"，权限说明 只写菜单权限 / 功能权限 / 列表数据权限
• [ ] 所有可点击元素都进了 名称|类型|规则/说明 表，类型 用词表内的词
• [ ] 图都进文档了：① 界面原型图： 处已插入截图（传图片路径即插图），且截图与页面一致；② 流程 / 框架图（渲染自 md 的 ```mermaid）已插入，图注在图片上方、冒号结尾；③ 图是当前内容 —— 改了 md 里的图就要重跑渲染，否则 Word 里还是旧图；④ 没有一张图高过正文区（纵向流程图会自动按高度反算宽度）；⑤ 又高又瘦的图（差于 1:2.2）已拆成上下两张，拆完每张的字号能读（≥7pt）
• [ ] 未收录需求在文末以「本章节未涉及/暂无」明确交代，不要默默省略
• [ ] 行距 1.5 倍、正文宋体 12pt（含 ascii）、叙述性段落（业务说明 / 功能概述）首行缩进 2 字符 —— 与主文档逐段核对
• [ ] 标题序号未手工输入（靠样式自动编号）
• [ ] 目录已自动更新：域起点带 w:dirty、settings 里有 w:updateFields="true"，且域内没有上一份文档的旧条目（搜索"引言""编写目的"或 HYPERLINK \l _Toc 应为 0）。读者的阅读器若不更新域，才回退到手动 F9
• [ ] 每张表都有可见框线 —— 含从模板继承的菜单目录表（它自身是 val="none"，必须显式覆盖），表格数应与正文一一对上
• [ ] 逐条列是真实项目符号（numbering，不是手打"●"），且条目内没有残留手写序号（"● 1、…"是两层标记）；业务说明 / 功能概述没有圆点；单条内容不加圆点
• [ ] 节标题下没有多余的标签行 —— 业务规则 / 使用角色 / 页面字段说明 三节正文不写"业务规则："这类重复标签（二级页面/操作说明/输入/输出 例外，它们是节内子要素/分段）
• [ ] 默认不存在「定制化需求」章 —— 只有该功能确有特殊定义、或明确属于定制功能才追加；不写时连引言、需求总览、空标题一起省
• [ ] XML 元素顺序自检：pPr 里 numPr 在 spacing/ind 之前、tblPr 里 tblBorders 在 tblLayout 之前、settings 里 updateFields 在 compat 之前
• [ ] 生成后用 python-docx 读回一遍（能读 ≠ Word 一定能开，但读不回一定有问题）

参考文件