create-yss-spec 2.2.7 → 2.2.9

package/template/docs/templates/implementation-routing-template.md

@@ -95,11 +95,34 @@ owner: ai
 | verification_commands |  |
 | human_review_points |  |
 | full_reroute_triggers | 新 API/schema、状态机、数据模型、写目录、仓库、skill、风险、seam、交付顺序或其他未冻结行为等变化 |
+| quality_baseline_ref | 工程基线的 `baseline_id` / `baseline_version`；切片不得重新定义质量标准 |
+| context_plan | 必需上下文、按需上下文、停止规则和缺失动作 |
+| doubt_driven_review | 高风险影响的主张、反证、证据、残余风险和审查引用；未命中时 `not-applicable` |
 
 | 不适用 skill | 原因 |
 |---|---|
 |  |  |
 
+### Context Plan（上下文工程）
+
+| 字段 | 内容 |
+|---|---|
+| required_context_refs | `CONTEXT.md`、已批准 Spec、当前 Slice Contract、适用 ADR / 工程基线 |
+| on_demand_context_refs | 命中影响面后再加载的专项 references、实现仓库文件和历史证据 |
+| context_stop_rule | `minimal-sufficient-evidence` |
+| missing_context_action | `blocked` / `reroute`；不得猜测补齐 |
+
+### Doubt-Driven 高风险反证
+
+| 字段 | 内容 |
+|---|---|
+| status | `not-applicable` / `required` / `completed` / `blocked` |
+| trigger_impacts | API、数据迁移、跨仓契约、发布回滚、实际安全行为、生命周期 / 生成语义 |
+| claim / counterclaim |  |  |
+| evidence_refs |  |
+| residual_risks |  |
+| reviewer_ref |  |
+
 ## 3. YSS skill 最小集合
 
 | 领域 | skill | 使用原因 | 是否必需 |

package/template/docs/templates/requirement-freeze-template.md

@@ -17,7 +17,7 @@ owner: ai
 | Spec 初稿 |  |  |  |
 | 产品总体设计 / 功能架构 |  |  | 必需 |
 | 产品设计 / 交互说明 |  |  |  |
-| 高保真 HTML 原型 | `docs/.scratch/<feature>/design/prototypes/index.html` |  | 有 UI 时必需；Ant Design v6 |
+| 高保真 HTML 原型 | `docs/.scratch/<feature>/design/prototypes/index.html` |  | 有 UI 时必需；Ant Design v6 主题/视觉标准 + schema v2 语义映射/浏览器/无障碍证据，生产 API 为 YSS UI + Ant Design Vue 4.x |
 | Prototype Review |  |  |  |
 | CONTEXT 术语 |  |  | 业务术语须含 PascalCase `英文标识` |
 

package/template/docs/user-guide//346/210/230/346/234/257/350/256/276/350/256/241/345/255/220/351/241/271/347/233/256/347/224/250/346/210/267/346/211/213/345/206/214.md

@@ -0,0 +1,218 @@
+# 战术设计子项目用户手册
+
+第一次接触 Tactical Design，不需要先会写代码，也不需要背诵 DDD 术语。
+
+这本手册把已经确认的 Strategic Design Handoff，继续细化成研发团队可以实现、测试和评审的领域模型。全文使用虚构的“客户合同审批”作为例子；示例只用于学习，不要把示例名称直接写入真实项目。
+
+## 这本手册适合谁
+
+- 产品经理、业务专家：想知道业务规则在技术设计中如何被保护。
+- 架构师、开发者：需要把业务边界细化为聚合、状态和一致性规则。
+- 测试人员：需要找到可以独立验证的领域行为。
+- AI Agent 操作者：需要知道何时让 Agent 起草、何时要求人工确认、何时必须停下。
+
+不懂代码也可以读完“业务读者篇”；“研发接手篇”会出现少量工程术语，但每个术语都会先用白话解释。
+
+## 看完能做什么
+
+1. 说清 Strategic Design 和 Tactical Design 的分工。
+2. 判断轻量 `Tactical DDD Check` 是否足够，还是需要独立的 Tactical Design 产物。
+3. 把一个业务场景拆成聚合、Entity、Value Object、领域服务和领域事件。
+4. 说明不变量、一致性边界、Repository / Gateway 和 API 的隔离方式。
+5. 形成可评审、可测试、可交给实现团队的战术设计结果。
+
+## 先记住：它解决什么问题
+
+Strategic Design 解决“业务应该怎样分工和划边界”；Tactical Design 解决“在一个边界里面，具体由哪些对象协作，以及规则如何不被破坏”。
+
+| 工作 | 大白话 | 典型结果 |
+|---|---|---|
+| Strategic Design | 决定业务地图和上下文边界 | 子域、限界上下文、统一语言、Context Map |
+| Tactical Design | 决定一个上下文内部怎样组织规则 | 聚合、状态机、不变量、领域服务、领域事件 |
+| 工程实现 | 把设计变成可运行的软件 | OpenAPI、代码、数据映射、测试和发布 |
+
+本手册的终点是“战术设计已评审并可交给实现”；OpenAPI Freeze、代码和发布仍由下游研发流程负责。
+
+## 开始前：确认输入和仓库身份
+
+### 输入必须来自已确认的交接包
+
+开始前应能找到批准且版本当前的 `Strategic Design Handoff`，其中至少包括：
+
+- 已确认的业务术语和上下文边界；
+- 关键场景、业务不变量和领域事件候选；
+- Spec、原型或业务级 Ticket 的版本引用；
+- 交给 Tactical Design 裁决的问题，例如聚合边界、状态、一致性和持久化；
+- 未决问题、责任人和后续验证计划。
+
+如果交接包缺失、过期或与当前 Spec 不一致，先回到上游处理，不要凭经验补写模型。
+
+### 确认项目实例
+
+打开项目根目录的 `yss-project.yaml`：
+
+| 配置 | 含义 | 处理方式 |
+|---|---|---|
+| `repository_mode: project-instance` | 真实业务项目 | 可以记录真实战术设计 |
+| `repository_mode: template-source` | 模板源 | 只能维护通用模板，不能写具体产品模型 |
+| 文件缺失或值不合法 | 身份不清楚 | 先停止并做迁移检查 |
+
+在项目实例中，先让 Agent 只读分诊：
+
+```text
+使用 yss-product-lifecycle，以 route 模式检查“客户合同审批”的 Tactical Design 输入。
+请先读取 yss-project.yaml、CONTEXT.md、Strategic Design Handoff 和当前已有架构资料。
+本轮只读，不要修改文件。请用普通话告诉我：
+1. 上游交接包是否批准且仍然有效；
+2. 当前是轻量 Tactical DDD Check 还是需要独立 Tactical Design；
+3. 已确认、待确认和冲突的业务规则分别是什么；
+4. 下一步只做哪一件事。
+正式 ID 放在普通话解释后面。
+```
+
+## 业务读者篇：用白话理解核心概念
+
+### 1. 聚合（Aggregate）
+
+聚合是一组必须一起守规则的对象。聚合根是这组对象对外唯一的入口；外部不能绕过聚合根直接修改内部对象。
+
+例子：一次“客户合同审批”可以由 `Contract` 聚合根管理审批状态和审批记录。审批记录如果只能随合同一起新增、退回和查询，就可以放在这个聚合内；不相关的通知不要硬塞进来。
+
+判断一个对象是否属于同一聚合，可以问：
+
+- 这些数据是否必须在同一次事务中保持一致？
+- 修改其中一个对象时，是否必须立即检查另一个对象？
+- 聚合变得很大后，是否会造成锁、并发或性能问题？
+
+不要按数据库表的外键关系画聚合；表关系图和业务一致性边界不是一回事。
+
+### 2. Entity（实体）
+
+实体有自己的身份，即使其他属性变化，它仍然是“同一个东西”。例如合同有 `contractId`，合同名称或金额修改后仍是同一份合同。
+
+### 3. Value Object（值对象）
+
+值对象由它的值决定身份，没有单独的业务身份。例如合同金额、客户地址、审批意见或时间范围。两个值完全相同的金额可以互相替换；值对象通常应尽量不可变。
+
+### 4. 不变量（Invariant）
+
+不变量是无论哪条入口执行，都不能被破坏的规则。例如：
+
+- 合同资料完整且校验通过后才能提交审批；
+- 已通过审批的合同不能直接改回草稿；
+- 同一份合同不能同时存在两个正在处理的审批流程；
+- 每次审批都必须留下操作人、时间、动作和意见。
+
+每条不变量都要能对应至少一个测试场景。不要把“页面上有一个发布按钮”当成不变量。
+
+### 5. 状态机
+
+状态机把允许的状态变化写清楚。合同示例：`草稿 → 待审批 → 审批中 → 已通过`；审批人退回时回到“草稿”，但“已通过”不能直接回到“草稿”。
+
+| 当前状态 | 动作 | 下一状态 | 必须满足 |
+|---|---|---|---|
+| 草稿 | 提交审批 | 待审批 | 合同资料完整 |
+| 待审批 | 审批人接单 | 审批中 | 已分配审批人 |
+| 审批中 | 审批通过 | 已通过 | 规则检查通过 |
+| 审批中 | 退回 | 草稿 | 必须填写退回原因 |
+| 已通过 | 修改 | 不允许 | 创建新的合同草稿 |
+
+### 6. 领域服务（Domain Service）
+
+当一条业务规则不自然属于某个实体，或需要协调多个聚合时，可以使用领域服务。领域服务只表达业务决策，不负责 HTTP、数据库连接或页面跳转。
+
+### 7. 领域事件（Domain Event）
+
+领域事件记录“业务上已经发生了什么”，例如 `ContractApproved`。它适合通知订阅者、触发异步处理或留下审计线索；事件名称应使用业务语言，不要直接暴露数据库表名。
+
+## 研发接手篇：从场景形成战术设计
+
+### 第一步：从用户场景开始，不从类名开始
+
+以“提交客户合同审批”为例，先写出：谁发起、前置条件、动作、结果、失败方式和后续影响。
+
+```text
+角色：销售人员
+前置条件：合同资料完整，且当前没有正在处理的审批流程
+动作：提交合同审批
+成功：合同进入“待审批”，产生 ContractSubmitted 事件
+失败：保留原状态，返回可理解的失败原因
+```
+
+### 第二步：列出规则并划一致性边界
+
+把规则分成“必须立即成立”和“可以稍后完成”：
+
+| 规则 | 一致性要求 | 设计提示 |
+|---|---|---|
+| 提交前资料必须完整 | 立即成立 | 放在合同聚合的不变量中 |
+| 同一合同不能重复提交 | 立即成立 | 由聚合 + Repository 检查并发冲突 |
+| 审批结果通知销售 | 可稍后完成 | 审批完成后发送领域事件 |
+| 统计报表更新 | 可稍后完成 | 使用异步订阅，不阻塞审批事务 |
+
+跨聚合流程由 Application 编排；核心规则仍放在 Domain。不要把所有规则塞进 Controller 或 Application Service。
+
+### 第三步：画出对象职责，而不是字段清单
+
+至少记录以下内容：
+
+| 对象 | 类型 | 负责什么 | 不负责什么 |
+|---|---|---|---|
+| `Contract` | Aggregate Root / Entity | 状态变化、提交前检查 | 发送 HTTP、直接操作表 |
+| `ApprovalRecord` | Entity 或 Value Object（需裁决） | 表达审批动作、意见和时间 | 决定整个流程 |
+| `ApproveContract` | Domain Service（必要时） | 协调跨对象的审批规则 | 事务提交和接口适配 |
+| `ContractRepository` | Repository seam | 保存和加载聚合 | 对外暴露数据库结构 |
+| `ContractApproved` | Domain Event | 描述审批已通过 | 代替主事务中的规则检查 |
+
+“Value Object 还是 Entity”不是凭习惯决定的：如果版本需要独立追踪身份、生命周期或并发操作，可能是 Entity；如果它只是不可变的版本值，可能是 Value Object。把裁决理由写下来。
+
+### 第四步：隔离 Repository、Gateway 和 API
+
+- `Repository` 面向领域模型的保存 / 加载，不让领域层依赖 ORM 或表结构。
+- `Gateway` 面向外部系统能力，例如通知、文件存储或规则服务；领域层只依赖抽象接口。
+- API schema 面向调用方，不直接暴露聚合内部对象、Repository 或持久化表。
+- Application 负责用例编排、事务边界和跨聚合协调；Domain 负责核心业务规则。
+
+### 第五步：写测试 seam
+
+每条关键规则都要有可执行的验证入口：
+
+- 聚合行为测试：给定状态和动作，验证状态变化或拒绝原因；
+- Repository / Gateway 契约测试：验证抽象接口的输入输出；
+- Application 用例测试：验证事务边界和跨聚合协调；
+- API 契约测试：验证公开 wire shape，不验证内部类名。
+
+## 什么时候需要独立 Tactical Design
+
+大多数简单变更，在系统概要设计中的 `Tactical DDD Check` 写清楚即可。只有当以下内容复杂到无法在一节中审查时，才升级为独立 Tactical Design 产物：
+
+- 多个聚合之间有复杂的一致性或并发规则；
+- 状态机有分支、补偿、重试或不可逆状态；
+- 持久化映射会隐藏或破坏领域边界；
+- Gateway、领域事件或最终一致性需要明确时序；
+- 评审者无法仅凭概要设计复现关键业务行为。
+
+升级不是为了增加文档数量，而是为了让复杂决策可读、可测试、可追责。无论采用轻量检查还是独立文档，都必须引用同一份 `tactical-design` contract 和 `evidence.tactical-design-review`，不能产生两套互相矛盾的事实源。
+
+## 评审前自检
+
+- [ ] 输入来自批准且版本当前的 `Strategic Design Handoff`。
+- [ ] 统一语言与 `CONTEXT.md` 一致，没有临时创造同义词。
+- [ ] 聚合根、Entity、Value Object 的身份和边界有理由。
+- [ ] 每个聚合的不变量和允许的状态转换都写清楚。
+- [ ] 一致性规则区分了立即成立与最终一致。
+- [ ] Application、Domain、Repository、Gateway 和 API 的职责没有混淆。
+- [ ] 领域事件表达业务事实，不暴露内部表结构。
+- [ ] 关键规则都有测试 seam 和失败场景。
+- [ ] 已判断轻量 `Tactical DDD Check` 是否足够；需要升级时写明原因。
+- [ ] 未决问题有负责人、后续 Ticket、验证计划和目标版本。
+
+## 与其他文档怎么分工
+
+- [用户手册索引](./用户手册索引.md)：所有入门手册的入口。
+- [战略设计子项目用户手册](../../submodules/yss-strategic-design-harness/docs/user-guide/战略设计子项目用户手册.md)：上游 Discovery、DDD 战略设计、Spec、原型和 Strategic Design Handoff。
+- [系统概要设计模板](../architecture/templates/system-overview-design-template.md)：轻量 Tactical DDD Check 的记录位置。
+- [架构评审清单](../architecture/templates/architecture-review-checklist.md)：设计评审时的结构化检查项。
+- `yss-router` 与后端 / 前端专项技能：批准后的实现合同、代码和验证规则。
+
+本手册是模板源中的通用分发资产。真实项目应使用自己的术语、规则、合同版本和批准记录；不要把“客户合同审批”示例当成真实业务结论。