Spec design

设计阶段：PRD + 原型 → 技术设计

当前年份 2026。

流水线第 3 阶段（设计），回答 HOW 的结构层：定整体架构、数据模型、以及关键接口与流程的详细设计。上游是 /spec-prd（+ /spec-prototype），下游是 /spec-plan（据本设计拆任务、写 migration、出覆盖矩阵）。

设计是计划的前提：先把架构与数据模型定准，/spec-plan 才拆得准任务。设计与计划分两份文档但同 NNN 串联——设计回答「系统长什么样」，计划回答「谁按什么顺序建」。需求层面的改动回流 /spec-change，不在 design 里临时发明需求。

术语提示

PRD 的功能需求用 R/F 编号、验收用 AE/AC 编号（详见 /spec-prd 术语表）。设计承上启下：把 R/F（要做什么）接成可实现的结构（架构 / 接口 / 数据 / 流程），供 /spec-plan 的实现单元 U 引用、被 AE/AC 验证。

核心原则

1. 单一事实源 — 优先级 docs/engineering/constitution.md（工程宪法 / 原则）> docs/engineering/workflow.md 阶段 3「完成标准」> 本 skill 内置默认值；项目文档存在时以其为准。
2. 同序号串联 — design 复用与 PRD 完全相同的 YYYY-MM-DD-NNN，prd/…-NNN-* ↔ design/…-NNN-* ↔ plans/…-NNN-* 一眼对应。
3. 设计先于拆分 · 一份文档分步走 — 概要、ER、详细设计同处一份 design.md（单一事实源，不拆成多份，理由见 README「为什么设计是一份文档」），但分步推进：先定架构与数据模型（概要 + ER）并确认，再写详细设计（落到模块 / 接口 / 关键流程，不是实现单元——那是 /spec-plan 的事）。
4. 数据是逻辑视图 — ER 模型是逻辑视图；物理 migration sql 在 /spec-plan 落地，二者逐字段一致，本设计是其唯一逻辑来源。
5. NFR 落到设计手段 — PRD 的每条非功能约束（性能/并发/安全权限/兼容性）→ 一个具体设计手段或校验点，不让 NFR 停在 PRD 里。

执行流程

Phase 0 · 加载输入

1. 读 docs/engineering/workflow.md 阶段 3 与「命名与追溯约定」。
2. 读目标 PRD（$ARGUMENTS 指定，或 docs/product/prd/ 最近 status: active 的一份），取其 NNN 与全部 R/F、AE/AC、非功能约束。
3. 读对应原型页面（docs/engineering/prototype/），作为接口与交互设计的 UI 依据。
4. 扫相关代码与现有数据库脚本（docs/ops/install/），识别要改的表/接口/页面与既有模式（Patterns），让设计贴合现状。

Phase 1 · 概要设计

确定整体技术方案，写清：

• 架构与模块划分：本特性涉及的后端模块/前端页面/外部依赖，以及它们的协作关系。
• 核心业务流程：用一张概要级流程图（Mermaid flowchart）画出主流程的关键节点与分支（评审最先看它）；细粒度时序留到详细设计。
• 技术选型与关键决策：选了什么、为什么、放弃了什么备选（决策要可追溯）。
• 接口清单与契约：新增/变更的接口（path、方法、入参出参概述）+ 鉴权（如 @RequiresRoles）、字段校验规则（含字符串字段的最大字符数，对齐 DB varchar 字符数，作为前后端校验唯一真值）、分页约定、新增错误码清单（按域续编，不重排）、典型请求/返回示例，与覆盖的 R/F 对应。
• 前端设计（涉及界面时必写）：页面清单 + 路由、页面间跳转/数据流关系（哪页进哪页、带什么参数）、关键组件划分、每页调用的接口。UI 以 prototype/ 为基线，本节只讲结构与协作，不重画样式。
• 权限设计（四级）：菜单权限 / 按钮权限 / 接口权限 / 数据权限——前两级定前端可见性，接口级定谁能调（权限矩阵 角色 × 接口），数据级定行级可见域（按部门/角色过滤，如 assistant 只看本部门）。
• 非功能约束承接：把 PRD 的每条 NFR（性能/并发/安全权限/兼容性）落到具体设计手段或校验点。
• 可观测与审计设计：关键日志点（入参/出参/耗时/异常，敏感字段脱敏）、审计记录（谁在何时对谁做了什么，承接「不可审计」类诉求）、监控指标/告警（必要时）。
• 风险与回滚：高风险点、并发/权限/性能注意项。

Phase 2 · 数据 ER 模型

把数据设计画成 Mermaid erDiagram（逻辑视图）：实体、关系、关键字段、主外键、唯一约束都要体现。可填骨架与 erDiagram 示例见本 skill 目录 templates/design.md 的「数据 ER 模型」节。ER 是逻辑视图，是 /spec-plan 物理 migration sql 的唯一逻辑来源，二者须逐字段一致。

时间戳规约：每个业务实体默认带创建/更新时间戳两列（命名沿用项目惯例，如 create_time / update_time 或 created_at / updated_at，以项目现有表为准）；纯字典/只读/关联中间表可豁免，但要在该实体旁注明豁免原因。ER 里把这两列画出来，/spec-plan 建表时照此落地。

字段长度规约：字符串字段 varchar(N) 的 N 是字符数（utf8mb4 下可存 N 个汉字/字母/数字/符号）；按业务最大汉字个数定义 N，不按字节估算——避免「想存 10 个汉字却定义 varchar(30)」式的认知偏差与冗余。DB 字符数是唯一真值：在 ER 或接口契约里标注每个字符串字段的「最大字符数 + 内容类型」，供前后端校验对齐（前端 maxLength、后端入参校验都按这个字符数）。超长 varchar 建索引时注意 utf8mb4 索引前缀字节上限。

检查点 · 概要 + ER 确认（Phase 2 之后、Phase 3 之前）

概要设计与 ER 是承重决策，详细设计是它们的展开——所以先把概要 + ER 回显给用户确认（或自检无误），再往下写详细设计，避免地基未稳就盖上层、回头大面积返工。若此处概要/ER 仍要改，就地改完再进入 Phase 3。

Phase 3 · 详细设计

把概要设计展开到可实现的颗粒度，按模块 / 接口 / 关键流程组织（不要按实现单元 U 切——拆单元是 /spec-plan 的职责，那里会反过来引用本节）。

右尺寸（AI 时代尤其重要）：详细设计的价值是锁定 AI 推不出、或推错代价高的决策，不是把代码预写一遍。判断标准——「给一个称职的 AI 概要设计 + 项目约定（CLAUDE.md/constitution），它能否可靠地自推出这处细节？能则不写（CRUD 骨架、DTO 映射、样板签名、常规校验留给 ce-work 生成后评审）；推不出或会猜错且代价高则必写（并发/事务边界/状态机/判定规则/跨单元接口契约与错误码/权限边界）。」

按上面这条闸，重点写：

• 关键接口签名（仅跨单元契约或非显然处）：入参出参类型、错误码/异常约定。
• 核心算法 / 判定逻辑：资格判定、状态机、计算规则等。
• 必要时序：复杂交互（如资格判定、并发占名额、回滚补偿）画清调用顺序与边界条件。
• 并发与幂等（占名额、重复提交等高频写场景必写）：明确并发控制手段——乐观锁 / 悲观锁 / 唯一键兜底 / 接口幂等键，以及冲突时的失败处理与提示。
• 代码结构落点：分层落点（哪个 Controller/Service/Mapper）、新增枚举/常量（消灭魔法值）、异常码 / 异常体系（按域续编错误码）、可复用的公共组件/工具——给 plan 拆单元时一个统一锚点。
• 每段详细设计标注它服务的 R/F（便于 plan 拆单元时按需求对齐、被 AE/AC 验证），并标注它依赖的概要/ER 小节——这样概要或 ER 一旦要改，一眼看出哪些详细设计要跟着动，改得准、不漏、也不必全盘重来。

Phase 4 · 写设计文件

先用 Read 读取本 skill 目录下的 templates/design.md（设计骨架），按骨架填充。写到 docs/engineering/design/YYYY-MM-DD-NNN-<type>-<slug>-design.md（<type> 常用 feat/fix/refactor，与 PRD 同 NNN）。结构（模板没读到时按此兜底）：

• frontmatter：title / type / status: active / date / origin（指向对应 PRD）。
• 正文：Summary → Problem Frame → 概要设计（Phase 1）→ 数据 ER 模型（Phase 2 的 mermaid）→ 详细设计（Phase 3，按模块/接口/流程）。

Phase 5 · 交接（进入计划阶段）

输出设计文件路径与关键决策摘要。然后提示下一步：

• 阶段 4 计划 → /spec-plan：据本设计把方案拆成可独立认领的实现单元、定依赖顺序、写 DB migration（与本设计的 ER 逐字段一致）、出三向覆盖矩阵。
• 改动需求范围（新增/调整 R/F）→ 先回流 /spec-change 改 PRD（必要时原型），再回到本 skill 同步设计。
• 想确认 PRD/原型/设计是否对得上 → /spec-check（只读体检覆盖矩阵与跨文档一致性）。