原型转详细设计（proto-to-doc）
理念
通过原型设计驱动需求工程产出，而不是手工重复搬文档。一条流水线把同一个原型源，生成三份互相对齐的载体：
- 详细设计 .docm（Word 宏启用，5 章标准结构 + 3 个自动增强章；含封面 + 修订记录 + 目录（TOC 域）+ 页脚页码，标题用真·Word 标题样式
Heading1~5，Word/WPS 导航窗格与目录可识别；全章节由原型真实/推导填充，无空占位）：
- 第 1 章 总体设计：1.1 项目概述（由项目名 + 模块列表推导）、1.2 模块总览表、1.3 图件（ER / 数据结构类图 / 业务流程图 / 架构图 / 状态扭转）——由gen_diagrams.py自动生成并嵌入 PNG（附可编辑 SVG 源）
- 第 2 章 界面设计：每模块自动展开「功能点清单 / 字段明细表 / 操作流程 / 业务规则与异常」四级子结构，内容由原型真实抽取
- 第 3 章 后端 API：按模块 + 工具条动作推导候选 REST 接口；每个模块附字段级入参/出参契约——优先用table_relations.md的富模型（49 字段级真实设计），按docm.moduleTableMap把模块绑定到表；缺绑定时回退原型候选；另含「错误码目录」
- 第 4 章 数据库表：数据库表设计在解析阶段（parse_prototype.py）即完成——解析时推导候选表/字段写入dbTables，无table_relations.md时自动生成起始稿。生成 docm 时优先用项目根table_relations.md，其次回退dbTables，不再留空
- 第 5 章 对外接口：由原型正文 + 表关系数据中的「语义关键词」自动检测外部系统（如 审批/驳回→审批流系统、邮件/飞书→消息办公系统、主数据→主数据系统），仅列入真实检测到的，不再写死模板
- （自动增强，无需配置）第 6 章 非功能性设计与质量保障（性能/安全/可靠性/日志监控/测试设计要点，并锚定本模块实际界面/动作数量）、第 7 章 权限与角色设计 RBAC（角色与权限矩阵、按钮级权限均由原型工具栏真实动作推导，非写死四角色；+ role_group 数据权限）、附录A 术语表（从系统字段/缩写/模块名/解析字段自动抽取） - 五段式开发文档 .html（需求背景/相关需求/UI界面/要求/注意事项）
- TAPD 需求（父=模块、子=工种包，前后端独立拆包）
并内置 DB 字段类型门禁（db_lint），在交付/推送前挡住「类型宽度 < 文档化枚举值」这类低级错误。
> 本技能是通用模板，不绑定任何具体业务系统或项目管理平台。所有项目 specifics（表前缀、跟踪系统 workspace、凭证）都来自项目本地配置文件，绝不在技能内硬编码。
> 付费定位：相比主流空白模板，本技能在「图件（ER/类图/流程/架构/状态全 5 类自动生成并嵌入）+ 接口字段级契约 + 错误码目录 + 非功能性/权限/术语增强章」上明显更厚，产出即可读可评审。
六能力（scripts/）
| 脚本 | 作用 | 自测状态 |
|---|---|---|
parse_prototype.py |
解析 HTML 原型 → 结构化 JSON（模块/视图/表格/导航 + 每视图元信息）；无字段表的界面模块也保留为视图；解析阶段即完成数据库表设计——推导候选表/字段写入 dbTables，无 table_relations.md 时自动生成起始稿 |
✅ --selftest 通过，已对 10MB 级真实原型验证 |
gen_diagrams.py |
自动图件生成（零依赖 SVG + Chrome 栅格化 PNG）：从 table_relations.md 或 dbTables 抽取表结构，自动推断外键，产出 ER 图 / 数据结构类图 / 业务流程图 / 架构图 / 状态扭转图 五类 SVG+PNG + manifest.json；ER/类图连线走正交折线（按行间走廊均匀错开、拐角圆角、不斜穿成团），默认剔除 creator_id/modifier_id 等审计外键（仅画业务外键，避免 SYS_USER 等基表被堆成团；config.docm.diagramExcludeAuditFk 可关），并明确 ER（蓝/crow's foot+1:N）与类图（紫/UML 三段式+0..*·1）区分 |
✅ --selftest 通过（FK 推断/状态识别/五类 SVG 合法 + ER·类图可区分断言），已对真实原型端到端生成 |
gen_fiveseg.py |
生成五段式 HTML（UI界面段由原型自动填充） | ✅ --selftest 通过，已对真实原型端到端生成 |
gen_docm.py |
生成详细设计 .docm（封面 / 修订记录 / TOC 域 / 真·标题样式 / 页脚页码 / 全章节真实/推导填充 / 模块四级子结构 / 字段表 / 候选库表 / 候选 API + 字段级契约 / 错误码目录 / 嵌入五类图件 PNG / 第 6·7·附录A 增强章） | ✅ --selftest 通过（OOXML 全部件合规 + 字段回抽 + 图件嵌入 + 新章节），已对真实原型端到端生成 |
sync_tracker.py |
需求同步（跟踪系统无关）：默认 dry-run 规划 + 配额核算 + db_lint 闸门；--push 推送/导出 |
✅ 解析/规划/闸门/generic 导出自测通过；⚠️ TAPD 实时推送路径未线上实测 |
trackers.py |
跟踪系统适配器（可插拔）：TapdTracker（自动写默认节点+处理人）/ GenericTracker（CSV+MD 导出） |
✅ generic 路径端到端验证；TAPD 路径 mock 校验 payload |
db_lint.py |
DB 字段类型门禁（R1~R6），规则来自 config | ✅ --selftest 通过，已对真实交付物验证（HARD=0） |
> 不绑 TAPD：config.tracker.tool 决定后端（tapd / generic / …）。不用 TAPD 的团队设 tool="generic"，
> 脚本导出 requirements_export.csv（可导入禅道/Jira/PingCode/飞书项目等）；其他 tool 未内置原生适配器时自动回退为通用导出。
标准工作流
1. 准备：把 templates/config.example.json 复制为项目根下的 `design-doc-config.json`（中性、agent 无关；WorkBuddy 用户也可放 `<项目>/.workbuddy/design-doc-config.json`，脚本自动兼容）并填写。
2. python3 scripts/parse_prototype.py <原型.html> --json parse.json # 解析 + 自动产出 table_relations.md（若缺失）
3. python3 scripts/gen_diagrams.py --json parse.json --out-dir diagrams # 自动生成 5 类图件（SVG+PNG）
4. python3 scripts/gen_fiveseg.py --from-json parse.json --out <五段式.html>
5. python3 scripts/gen_docm.py --from-json parse.json --out <详细设计.docm> # 自动嵌入 diagrams/ 图件
6. python3 scripts/db_lint.py # 推送/交付前闸门，须 HARD=0
7. python3 scripts/sync_tracker.py --fiveseg <五段式.html> # 先 dry-run 看规划+配额
8. python3 scripts/sync_tracker.py --fiveseg <五段式.html> --push # 过闸门+配额后才推送/导出
> 第 2~5 步也可不传 --from-json，直接读 config 约定的原型路径自动串联；gen_docm 会自动发现 diagramDir（默认 diagrams/）下的图件并嵌入。
> 第 2 步解析时会产出数据库表设计：若项目根尚不存在 table_relations.md，脚本会按原型列表/字段表列自动生成一份标注「原型推导候选」的起始稿。人工精修后保留，再次运行不会覆盖；gen_docm 第 4 章优先采用 table_relations.md，覆盖解析产物的候选。
配置（设计源，项目内）
复制 templates/config.example.json → 项目根 design-doc-config.json（WorkBuddy 用户放 .workbuddy/ 亦可，脚本自动发现；也可用环境变量 DESIGN_DOC_CONFIG 或 --config 显式指定）。关键字段：
project.name/table.prefix/table.pkType/table.systemFieldstable.externalIdFields：允许使用外部系统 id 宽度的字段（如 ext_inst_id）docm.chapters+chapterTitles（默认 5 章：总体/界面/后端API/数据库表/对外接口；第 6/7 章与附录A 为自动增强章，已内置标题，可在chapterTitles覆盖文案）docm.title/docm.version/docm.author：封面与修订记录用的元数据（可留空，留空时回退为「<project> · 详细设计/ 1.0.0 / （待填）」）docm.diagramDir/docm.embedDiagrams/docm.erRelations/docm.diagramExcludeAuditFk：图件目录 / 是否嵌入 / 可选显式外键覆盖 / 是否剔除审计外键连线（默认 true）docm.dataPermissionNotes：第 7.2 节「数据权限隔离」要点列表，默认中性通用口径（不硬编码项目专有系统名）；本项目若需写明「与某外部系统口径一致」，用该键覆盖docm.moduleTableMap：可选，解决「中文模块名 ↔ 英文表名」匹配失败导致第 3 章字段契约退回通用模板。key=原型视图标题（含子串即可），value=table_relations.md中的表名列表（支持表名带中文注释后缀，如SALES_REPORT匹配SALES_REPORT（销售报告主表））fiveseg.segments（默认 5 段）tracker.tool（tapd/generic/…）+workspace/storyLimit/workPackages/credentialEnvtracker.defaultOwner/initialStatus/statusField：创建时自动写入处理人与初始工作流节点dbLint.rules（pkMustBe / warnAmount / 最小宽度）prototype.path/tableRelations（DB 表关系文件名；留空时默认用table_relations.md，也支持通配自动发现）
约束（上架铁律）
- 绝不硬编码任何项目的表名前缀、跟踪系统 workspace、API 凭证、业务数据。
- 凭证只从环境变量读取（默认
TAPD_API_USER/TAPD_API_PASSWORD，可用tracker.credentialEnv改），config 仅存提示文案。 - 推送前强制过
db_lint闸门 + workspace 需求上限配额核算（余量 <20 告警，超上限拒绝）。 - 不绑单一平台：TAPD 只是默认适配器；
tool=generic或其它值均可用（非 TAPD 回退为通用导出）。
诚实声明
- ✅ 已实测：
parse_prototype/gen_fiveseg/gen_docm/db_lint/gen_diagrams逻辑，且对真实大型原型 + 真实交付物（800+ 字段）端到端跑通。 - ✅ 已实测：
sync_tracker的解析/规划/闸门/配额，以及 generic 导出端到端（47 模块 → 141 行 CSV+MD）；TAPD 适配器的创建/置状态 payload 经 mock 校验。 - ✅ 已实测：
gen_diagrams自动产出 ER/类图/流程/架构/状态五类图件（SVG 零依赖 + Chrome 栅格化 PNG），gen_docm把 PNG 嵌入 docm 第 1.3 章（DrawingML + 动态部件），OOXML 合规校验通过。 - ⚠️
gen_docm生成的 .docm 通过 OOXML 合规校验与字段回抽，但未在 Word/WPS 中人工打开确认排版（沙箱无 Office）；首次交付建议打开核对样式。 - ⚠️ 图件 PNG 依赖系统 Chrome 栅格化；若环境无 Chrome/Node 路径，
gen_diagrams自动降级保留 SVG 并在 docm 中注明「待补图」，不阻断生成。 - ⚠️
sync_tracker --push的 TAPD 实时 HTTP 路径依赖 TAPD Open API 与有效凭证，本环境无凭证未线上实测；请使用者--limit 1试推后再批量。 - ⚠️ 「默认初始状态」通过创建后
update(status=v_status/status)实现；若你的 TAPD 用多分支流程节点模式，把tracker.statusField调为v_status或step并按需填initialStatus。
