create-yss-spec 3.0.1 → 3.1.3

package/template/docs/process/templates/frontend-implementation-verification-template.yaml

@@ -1,21 +1,41 @@
-schema_version: 1
+schema_version: 2
 kind: verification
 template: true
 status: draft
-prototype_ref: docs/.scratch/example/design/prototype.html
+prototype_ref: docs/.scratch/example/design/prototypes/index.html
 spec_ref: docs/.scratch/example/spec.md
+visual_baseline:
+  baseline_id: visual-baseline.example
+  version: v1
+  digest: sha256:0000000000000000000000000000000000000000000000000000000000000000
+  manifest_ref: docs/.scratch/example/handoff/visual-baseline-v1/visual-baseline.yaml
+  status: approved
+  case_ids: [primary-desktop, primary-narrow]
 route_and_page_inventory:
   - route: /example
     page: ExamplePage
-desktop_visual_evidence: [docs/.scratch/example/verification/desktop.png]
-narrow_view_visual_evidence: [docs/.scratch/example/verification/narrow.png]
+    case_ids: [primary-desktop, primary-narrow]
+case_results:
+  - case_id: primary-desktop
+    baseline_image_ref: docs/.scratch/example/handoff/visual-baseline-v1/images/primary-desktop.png
+    implementation_image_ref: docs/.scratch/example/verification/images/primary-desktop.png
+    diff_ref: docs/.scratch/example/verification/diffs/primary-desktop.png
+    mask_ref: not-applicable
+    result: blocked
+    uncovered_difference: false
+    explanation: <difference-or-not-applicable>
 interaction_results: [loading, empty, error, permission, selected, key-interaction]
 console_warning_check: blocked
 pnpm_commands: [pnpm lint, pnpm type-check, pnpm test]
+actual_verification:
+  - command: pnpm test
+    exit_code: 0
+    executed_at: <iso-8601>
+    evidence_ref: docs/.scratch/example/verification/pnpm-test.txt
 uncovered_differences: []
 difference_owner: null
 independent_review:
   reviewer: non-implementer
-  candidate_digest: pending
+  candidate_digest: sha256:0000000000000000000000000000000000000000000000000000000000000000
   status: pending
   findings_ref: docs/.scratch/example/verification/ui-fidelity-review.md

package/template/docs/process/templates/lifecycle-checkpoint-template.yaml

@@ -1,9 +1,15 @@
 schema_version: 1
+repository_mode: project-instance
 mode: route
 status: routing
 stage: stage.entry-triage
 artifacts: {}
 gates: {}
+context_reconciliation:
+  status: pending
+  ref: null
+  reason: 等待当前工作单元完成稳定术语回写与核对
+  evidence_refs: []
 next_work_unit: work-unit.discovery-opportunity
 phase_boundary:
   decision: continue
@@ -21,6 +27,9 @@ verification:
   commands: []
   evidence_refs: []
 human_review:
+  user_decisions: []
+  required_decisions: []
+  not_applicable: []
   required: false
   status: not-applicable
 git_checkpoint:

package/template/docs/process/templates/scaffold-architecture-decisions-template.yaml

@@ -0,0 +1,32 @@
+schema_version: 1
+kind: scaffold-architecture-decisions
+template: true
+status: draft
+decisions:
+  - decision_id: scaffold-decision.main-service
+    project_id: main-service
+    parent_project_id: null
+    status: awaiting-user-decision
+    recommended_architecture: domain-driven
+    recommendation_reasons:
+      - 存在聚合不变量或复杂状态转换
+    confirmed_architecture: null
+    override_reason: null
+    inheritance_mode: root-default
+    inherited_from: null
+    platform_profile: spring-boot-2.7-jdk8
+    architecture_profile: target-domain-model
+    verification_database: h2
+    production_database: not-bound
+    requested_capabilities: []
+    resolved_modules: [domain, application, infrastructure, adapter, bootstrap]
+    resolution_version: 1
+    user_confirmation:
+      user_decision_ref: null
+      decision_subject_ref: null
+      confirmed_by: null
+      channel: null
+      confirmation_ref: null
+      confirmed_at: null
+      normalized_text: null
+    decision_inputs_digest: sha256:0000000000000000000000000000000000000000000000000000000000000000

package/template/docs/process/templates/stage-checkpoint-template.md

@@ -2,6 +2,7 @@
 
 ```yaml
 schema_version: 1
+repository_mode: <template-source|project-instance>
 mode: <route|orchestrate|resume|audit>
 status: <routing|running|paused-human-gate|blocked|completed>
 stage: <lifecycle stage>
@@ -16,6 +17,10 @@ gates:
     reason: <why this status applies>
     evidence_refs: []
     approval_ref: <docs/.scratch/<feature>/gates/<gate-id>-approval.yaml when approved countersign gate>
+context_reconciliation:
+  status: <pending|reconciled|not-applicable|blocked>
+  ref: <docs/.scratch/<feature>/evidence/context-reconciliation-<work-unit>.yaml>
+  evidence_refs: [CONTEXT.md]
 phase_boundary:
   decision: <continue|clear|handoff|subagent|compact>
   reason: <decision evidence>

package/template/docs/process/templates/user-decision-template.yaml

@@ -0,0 +1,30 @@
+# 待填写模板；不是批准证据。原始来源字段必须由真实消息提取。
+schema_version: 1
+kind: user-decision
+request:
+  id: <request-id>
+  requester_ref: <提问者原始身份>
+  requester_source:
+    kind: session-export
+    ref: <原始请求捕获文件>
+    digest: <sha256>
+    message_id: <原始消息ID>
+  items:
+    - id: <item-id>
+      boundary: <引用 user_decision_policy 中的门禁或决定类型>
+      title: <可审阅决定>
+      subject: {ref: <资产正文或冻结快照>, version: <version>, digest: <sha256>}
+      basis: []
+      scope: [<批准范围>]
+      changes: <关键变化>
+      risks: []
+      recommendation: <推荐方案>
+      next_actions: [<批准后将执行的动作>]
+      responder_ref: <提问者或其明确指定的负责人>
+      # 指定其他负责人时追加 delegation_source，与 requester_source 同形状。
+  presented_source:
+    kind: session-export
+    ref: <完整展示请求的原始消息捕获>
+    digest: <sha256>
+    message_id: <原始消息ID>
+responses: [] # 收到真实回复后追加；无回复永不预填 approved。

package/template/docs/templates/approval-record-template.yaml

@@ -12,3 +12,7 @@ countersigner_role_ids:
 evidence_refs: []
 biological_veto: false
 notes: 会签必须可读取；起草者不得出现在 countersigner_role_ids。运行时表情/reaction 无效。
+# 关键门禁正式放行时必填；模板/历史结构校验不构成批准。
+subject_ref: null
+approval_scope: []
+user_decision_ref: null

package/template/docs/templates/build-architecture-checklist-template.md

@@ -19,7 +19,7 @@ owner: ai
 | 系统 / 数据架构设计 |  |  |
 | 风险 / 回滚约束 | `AGENTS.md` |  |
 | Slice Implementation Contract |  | 填写 contract_id / contract_version / 生命周期批准状态 |
-| 后端脚手架策略 | `orchestration-contract.yaml` / `yss-ddd-scaffold-generator` |  | backend `scaffold_status=required` 时填写结构化合同身份、批准/持久化引用、生成器输入、预期文件、实际 `./mvnw` 结果和后置 实现合同编译器 重编译 |
+| 后端脚手架策略 | `orchestration-contract.yaml` / DDD 或 Layered MVC 生成器 |  | backend `scaffold_status=required` 时填写 architecture decision、schema v3 合同身份、批准/持久化引用、生成器输入、Manifest v3、实际 `./mvnw` 结果和后置实现合同编译器重编译 |
 | 工程项目路径策略 | `docs/process/implementation-repo-integration.md` / 实现合同编译器 Contract |  | Harness 内必须是 `apps/backend/<project>/` 或 `apps/frontend/<project>/`；`apps/backend/`、`apps/frontend/` 仅为容器，`app/backend/`、`app/frontend/` 及其子路径阻断 |
 | 垂直切片工作单元 |  |  |
 | YSS Skill Execution Result |  | 每个 skill / work_unit 的结果文件引用 |
@@ -32,7 +32,7 @@ owner: ai
 | 后端切片必须回勾 `Backend Slice Implementation Contract`：required skills、允许写范围、禁止模式、证据文件、延期 seam 和验证命令完整 | implementation routing / 垂直切片 Ticket / `AGENTS.md` |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 缺合同或合同不完整时暂停并记录替代方案 |
 | 统一合同版本：实现消费的 contract_id / contract_version 与生命周期批准并持久化的版本一致，实现合同编译器 未自行批准合同或推进 `ready-for-agent` | Slice Implementation Contract / 生命周期证据 |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 版本不一致时将工作单元标记 `stale` 并暂停 build |
 | 合同子项闭环：Common、Frontend、Backend、Contract、Cross-repo 子合同按影响面填写，不适用项有原因 | Slice Implementation Contract |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 缺失适用子合同时回到 实现合同编译器 |
-| 原型确认后的后端脚手架顺序：工程基线 → 实现合同编译器 脚手架合同 draft / 生命周期批准 → `yss-ddd-scaffold-generator` → `yss-backend-scaffold-parent` → 实现合同编译器 重编译；脚手架不得生成业务行为 | `yss-product-lifecycle` / `yss-ddd-scaffold-generator` |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 顺序缺失、生成器混入业务行为或缺 Execution Result 时阻断 |
+| 后端脚手架顺序：工程基线与 Agent 推荐 → 用户确认并持久化 architecture decision → schema v3 合同 draft / 生命周期批准 → DDD 或 Layered MVC 生成器 → 对应基线与 Manifest v3 校验 → 实现合同编译器重编译；生成器无交互且不得生成业务行为 | `yss-product-lifecycle` / `yss-ddd-scaffold-generator` / `yss-layered-mvc-scaffold-generator` |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 选择缺失、digest 漂移、顺序缺失、生成器混入业务行为或缺 Execution Result 时阻断 |
 | 写路径与证据：Execution Result 的 changed_files 均位于 allowed_write_paths，expected_evidence_files 已实际生成 | Slice Implementation Contract / YSS Skill Execution Result |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 路径越界或证据缺失标记 `violation` 并阻断 build |
 | TDD 模式：每个工作单元唯一选择 `behavior-tdd` 或 `controlled-generation`；生成器未承载状态、权限、业务过滤、事务、错误映射或用户可见交互 | Slice Implementation Contract / 垂直切片 Ticket / Execution Result |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 模式不匹配时拆分工作单元并完整重路由 |
 | 所有后续生成代码：必须消费当前批准合同、主 YSS skill、依赖闭包、允许写路径、预期证据和 YSS Skill Execution Result；业务行为使用 `behavior-tdd` | `post_scaffold_generated_code_policy` |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 缺任一条件或以时间压力豁免时阻断 build |
@@ -42,7 +42,7 @@ owner: ai
 | Application：负责用例编排、事务边界和跨聚合协调，不承载核心领域规则 | `yss-application` / 系统架构 |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 领域规则下沉 Domain，事务边界留在 Application |
 | Infrastructure：需要持久化的切片必须有 PO / Repository / Convertor / GatewayImpl；`InMemory*Gateway` 只能作为显式 `seam-deferred` | `yss-repository` / 数据架构 |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 未补齐时不得声称生产持久化完成 |
 | POJO / Convertor：DTO / VO / CMD / Query / PO / Domain Model 样板代码默认使用 Lombok；对象转换默认使用 MapStruct，禁止 `BeanUtils.copyProperties`、反射拷贝和重复手写字段赋值 | `lombok` / `mapstruct` / `AGENTS.md` |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 未加载 skill、缺注解处理器配置、缺 Convertor 或无例外说明时标记 `violation` |
-| 后端工程工具链：构建、测试、运行、OpenAPI 生成、CI 和 Release 命令必须使用项目根目录 `./mvnw ...`；裸 `mvn ...` 必须有受控例外记录 | `yss-ddd-scaffold-generator` / `yss-backend-scaffold-parent` / implementation routing |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 无例外记录时改为 `./mvnw ...`，否则不得进入完成 / 可合并结论 |
+| 后端工程工具链：构建、测试、运行、OpenAPI 生成、CI 和 Release 命令必须使用项目根目录 `./mvnw ...`；裸 `mvn ...` 必须有受控例外记录 | DDD / Layered MVC 生成器及 implementation routing |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 无例外记录时改为 `./mvnw ...`，否则不得进入完成 / 可合并结论 |
 | 工程项目路径：每个 Harness 内项目必须有具体项目段，禁止直接写入容器根或单数 `app/...` | `docs/process/implementation-repo-integration.md` / implementation path validator |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 路径违规时停止 build，并回到实现路由 |
 | 文档语言：持久化生命周期文档、实施记录、审查报告、发布说明和 Git checkpoint 正文必须使用中文，英文 skill / 模板不得原样落地 | `AGENTS.md` / `yss-product-lifecycle` |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 仅保留必要英文技术标识、命令和 metadata |
 | 高风险变更：按已批准的普通影响面结论记录验证证据、责任人和回滚约束 | `AGENTS.md` / Spec / 架构记录 |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 缺验证证据或责任人时不得发布或合并 |

package/template/docs/templates/implementation-repo-registry-template.md

@@ -28,7 +28,9 @@ owner: ai
 | superproject_git_url | 父仓远端；必须与 `git_url` 不同 |
 | checkout_state | attached-branch / detached-head / uninitialized / empty-gitlink / 不适用 |
 | scaffold_status | existing / required / initialized |
-| scaffold_skill | `yss-ddd-scaffold-generator` / `yss-frontend-scaffold-generator` / none |
+| scaffold_architecture | `domain-driven` / `layered-mvc` / 不适用；required 时必须由用户确认 |
+| scaffold_decision_ref | `scaffold-architecture-decisions.yaml` 的 decision_id + digest |
+| scaffold_skill | `yss-ddd-scaffold-generator` / `yss-layered-mvc-scaffold-generator` / `yss-frontend-scaffold-generator` / none |
 | scaffold_target_confirmed | 是 / 否 / 不适用 |
 | target_git_url_or_output_dir |  |
 | owner |  |

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

@@ -142,6 +142,8 @@ owner: ai
 | required_skills |  |
 | approved_prototype_ref |  |
 | state_matrix_ref |  |
+| visual_baseline_ref | `visual-baseline.yaml` 路径、版本与 digest |
+| visual_baseline_case_ids | 当前切片实际消费的 case_id；禁止目录 glob |
 | generated_api_client_ref |  |
 | allowed_write_paths |  |
 | component_test_seams | loading / empty / error / permission / 其他公开 seam |
@@ -224,7 +226,7 @@ owner: ai
 
 | 受影响端 | 是否已有可用工程 | scaffold_status | 目标是否确认 | 处理结论 | 使用 skill | 输出位置 / 仓库 | 备注 |
 |---|---|---|---|---|---|---|---|
-| backend | 是 / 否 / 不适用 | existing / required / initialized / not-applicable | 是 / 否 / 不适用 | 复用现有 / 初始化 / 阻塞 | `yss-ddd-scaffold-generator` / none |  |  |
+| backend | 是 / 否 / 不适用 | existing / required / initialized / not-applicable | 是 / 否 / 不适用 | 复用现有 / 初始化 / 阻塞 | `yss-ddd-scaffold-generator` / `yss-layered-mvc-scaffold-generator` / none |  | 填写 architecture_family、decision_id 与 digest |
 | frontend | 是 / 否 / 不适用 | existing / required / initialized / not-applicable | 是 / 否 / 不适用 | 复用现有 / 初始化 / 阻塞 | `yss-frontend-scaffold-generator` / none |  |  |
 
 脚手架输出位置必须回指具体项目根：后端为 `apps/backend/<project>/`，前端为 `apps/frontend/<project>/`；不得把 `apps/backend/`、`apps/frontend/` 容器根或任何 `app/backend/`、`app/frontend/` 路径作为生成目标。
@@ -238,18 +240,18 @@ owner: ai
 
 ### 4.3 后端脚手架工作单元
 
-当 backend `scaffold_status=required` 时，先登记一个 `controlled-generation` 工作单元：`primary_skill=yss-ddd-scaffold-generator`，并在后续追加 `yss-backend-scaffold-parent` 基线校验和 `yss-implementation-contract-compiler` 合同重编译。`existing` / `initialized` 不重复全量生成，但必须提供等价基线和 Wrapper 证据。
+当 backend `scaffold_status=required` 时，生命周期先按领域复杂度推荐 DDD/MVC，并以批量决策表反问用户确认本体默认与子项目覆盖。选择写入 `scaffold-architecture-decisions.yaml`；缺失、未确认或 stale 时阻断。随后登记一个 `controlled-generation` 工作单元：`domain-driven` 使用 `primary_skill=yss-ddd-scaffold-generator`，`layered-mvc` 使用 `primary_skill=yss-layered-mvc-scaffold-generator`。生成后执行对应基线校验和 `yss-implementation-contract-compiler` 合同重编译。`existing` / `initialized` 不重复生成，架构转换另立迁移工作单元。
 
 | 项 | 内容 |
 |---|---|
-| 前置 | `prototype_confirmation`、工程基线、实现仓库和脚手架目标已确认；实现合同编译器 脚手架合同 draft 已经生命周期批准并持久化为结构化 JSON，生成器通过 `--contract-file` 消费 |
-| 生成器 | `yss-ddd-scaffold-generator` |
+| 前置 | `prototype_confirmation`、工程基线、实现仓库和脚手架目标已确认；`scaffold-architecture-decisions.yaml` 已由用户确认且 digest 当前；实现合同编译器 schema v3 脚手架合同 draft 已经生命周期批准并持久化为结构化 JSON，生成器通过 `--contract-file` 消费 |
+| 生成器 | `domain-driven` → `yss-ddd-scaffold-generator`；`layered-mvc` → `yss-layered-mvc-scaffold-generator` |
 | 模式 | `controlled-generation` |
 | Java / Maven 身份 | `base_package` 与 Maven `group_id` 分开登记；项目版本、父 POM GAV、`yss-components.version` 进入批准合同并原样传给 CLI |
-| 允许生成 | Domain / Application / Infrastructure / Adapter / Bootstrap 目录骨架、POM、配置、Wrapper 和非业务机械模板 |
+| 允许生成 | DDD 的 Domain / Application / Infrastructure / Adapter / Bootstrap，或 MVC 的 server / service / repository 与能力解析出的 adapter / client / feign-client；以及 POM、配置、Wrapper 和非业务机械模板 |
 | 禁止生成 | 业务规则、状态机、权限、事务、复杂查询、错误映射、业务字段和用户可见行为 |
 | 生成选项 | 关闭 `--with-example`；生成器严格 initialize-only，非空目录、`--force`、旧项目迁移和当前模板升级均为 `unsupported` |
-| Profile | `target-domain-model` / `mybatis-plus` / `mysql` / `spring-boot-2.7-jdk8` / `javax` / `web` / `yss-internal`；其他组合须先通过独立 fixture |
+| Profile | DDD：`target-domain-model` + MySQL；MVC：`layered-mvc` + MySQL/Oracle/OceanBase Oracle；共同固定 Spring Boot 2.7 / Java 8 / `javax` / MyBatis-Plus，其他组合须先通过独立 fixture |
 | 验证 | 使用一键生成验证入口，实际执行项目根目录 `./mvnw validate`、`./mvnw test`、`./mvnw package`；通过后仅为 `empty-scaffold-verified`，golden first slice 通过后才是 `first-slice-verified` |
 | 后置 | `yss-backend-scaffold-parent`、`yss-implementation-contract-compiler` 业务合同重编译、YSS Skill Execution Result |
 

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

@@ -17,7 +17,7 @@ owner: ai
 | Spec 初稿 |  |  |  |
 | 产品总体设计 / 功能架构 |  |  | 必需 |
 | 产品设计 / 交互说明 |  |  |  |
-| 原型交付物 | `docs/.scratch/<feature>/design/prototypes/index.html` 或稳定 URL |  | 有产品设计影响时必需；按 H1/H2 档位提供 schema v3 浏览器、Design QA 与条件 AntD 事实；真实组件待验事项进入前端实现计划 |
+| 原型交付物 | `docs/.scratch/<feature>/design/prototypes/index.html` 或稳定 URL |  | 有产品设计影响时必需；按 H1/H2 档位提供 Prototype Evidence schema v4、Visual Baseline schema v1、浏览器、Design QA 与条件 AntD 事实；真实组件待验事项进入前端实现计划 |
 | Prototype Review |  |  |  |
 | CONTEXT 术语 |  |  | 业务术语须含 PascalCase `英文标识` |
 

package/template/docs/templates/review-report-template.md

@@ -88,7 +88,7 @@ rg -n "class (SingleResult|MultiResult|PageResult|Result)<|public static class .
 | 检查项 | 结论 | 证据 |
 |---|---|---|
 | `yss-ui` 组件路由已落实：YSS `required` 封装（如 `YTable` / `YTree` / `YFormily`）未被 AntDV 裸组件或其他重型方案绕过；受控回退有能力缺口记录 | pass / violation / not-applicable |  |
-| `yss-ui-business-page-generation` 页面生成与 `yss-page-module-development` 生命周期编排已落实：`index.vue` 只编排，请求与分页不堆在页面根组件 | pass / violation / not-applicable |  |
+| `yss-ui-business-page-generation` 页面生成与生命周期编排已落实：`index.vue` 只编排，请求与分页不堆在页面根组件 | pass / violation / not-applicable |  |
 | 切片合同 `required_skills` 中的 Formily / 表格 / 树 / 高度 / 主题 / API 专项 skill 已按影响面引用规则；未命中项有 `not-applicable` 原因 | pass / violation / not-applicable |  |
 | 前端验证使用项目根 `pnpm ...`；实际退出码已记录。只做 type-check 或声称“已对齐”不算通过 | pass / violation / not-applicable |  |
 | 机器检查（`pnpm lint` / `pnpm type-check` 等已存在脚本）已执行，或缺失工具已写 `not-applicable` 及原因 | pass / violation / not-applicable |  |

package/template/docs/templates/spec-template.md

@@ -67,16 +67,16 @@ owner: ai
 |---|---|---|
 | | | |
 
-## DDD 影响判断
+## 业务边界与规则影响判断
 
-> 仅做轻量判断，不新增流程阶段。若均为“否”，后续不需要单独 DDD 设计；若触发边界、模型或一致性变化，在产品总体设计 / 系统概要设计中补齐对应小节。
+> 仅做轻量判断，不新增流程阶段。若均为“否”，后续不需要单独补充业务边界或复杂技术模型设计；若触发责任边界、关键规则、状态或一致性变化，在产品总体设计 / 系统概要设计中补齐对应小节。
 
 | 检查项 | 是 / 否 | 说明 / 处理 |
 |---|---|---|
-| 是否新增或改变统一语言 / 核心术语 |  | 需要回写 `CONTEXT.md` 的中文术语和 PascalCase `英文标识` |
-| 是否新增或改变限界上下文 / 模块边界 |  | 需要在产品总体设计中完成 Strategic DDD Check |
+| 是否新增或改变统一业务词汇 / 核心术语 |  | 需要回写 `CONTEXT.md` 的中文术语、PascalCase `英文标识` 和适用业务责任区 |
+| 是否新增或改变业务责任区 / 模块边界 |  | 需要在产品总体设计中完成业务边界与协作检查 |
 | 是否改变上下文间协作关系 |  | 说明上游 / 下游 / 防腐层 / 共享内核关系 |
-| 是否新增或改变聚合、不变量、状态机 |  | 需要在系统概要设计 / 数据架构中完成 Tactical DDD Check |
+| 是否新增或改变关键业务对象、不可违反规则或状态机 |  | 需要在系统概要设计 / 数据架构中完成技术模型检查 |
 | 是否影响 API、权限、数据、审计或风险 / 回滚约束 |  | 进入对应契约、架构或人工审查门禁 |
 
 ## 测试决策

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

@@ -1,218 +1,34 @@
 # 战术设计子项目用户手册
 
-第一次接触 Tactical Design，不需要先会写代码，也不需要背诵 DDD 术语。
+本入口保留给既有读者。Tactical Design 把已批准业务规则映射为聚合、状态、不变量、一致性边界和测试 seam；它不是新的模板家族，不代替 API Freeze 或 Slice Contract 批准。
 
-这本手册把已经确认的 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`。它适合通知订阅者、触发异步处理或留下审计线索；事件名称应使用业务语言，不要直接暴露数据库表名。
-
-## 研发接手篇：从场景形成战术设计
-
-### 第一步：从用户场景开始，不从类名开始
-
-以“提交客户合同审批”为例，先写出：谁发起、前置条件、动作、结果、失败方式和后续影响。
+先核对本仓身份、profile、根 CONTEXT.md、当前战略交接及批准证据。导入快照后完成目标词汇对账，再逐项登记源规则/关键场景的承接；缺失、冲突或过期先回交，不能猜测业务规则。
 
 ```text
-角色：销售人员
-前置条件：合同资料完整，且当前没有正在处理的审批流程
-动作：提交合同审批
-成功：合同进入“待审批”，产生 ContractSubmitted 事件
-失败：保留原状态，返回可理解的失败原因
+请按本仓生命周期检查“设备领用”当前战略输入及目标词汇对账。
+有领域行为影响时，使用 yss-tactical-design 起草战术设计，
+解释设备占用的竞争、状态转换和一致性边界，并映射公开测试 seam。
+逐项列出已承接、冲突、延期及依赖切片，等待适用审查后再编译实现合同。
 ```
 
-### 第二步：列出规则并划一致性边界
-
-把规则分成“必须立即成立”和“可以稍后完成”：
-
-| 规则 | 一致性要求 | 设计提示 |
-|---|---|---|
-| 提交前资料必须完整 | 立即成立 | 放在合同聚合的不变量中 |
-| 同一合同不能重复提交 | 立即成立 | 由聚合 + 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`，不能产生两套互相矛盾的事实源。
+| 设计问题 | 设备借用中的例子 |
+|---|---|
+| 谁保护不变量 | 哪个对象/边界保证设备不能同时被领用 |
+| 状态是否合法 | 未批准申请是否允许领用；重复归还如何处理 |
+| 一致性在哪里保证 | 申请与设备占用是否同事务；失败如何恢复 |
+| 外部依赖如何隔离 | API/Repository/Gateway 怎样映射而不篡改业务含义 |
+| 如何证伪设计 | 并发领用、无权限、重复请求的公开 seam 与预期结果 |
 
-## 评审前自检
+案例只是提问方向，答案由项目实际业务与工程条件决定。没有领域行为影响时按当前政策记录带原因的 not-applicable，不为简单页面硬造聚合。
 
-- [ ] 输入来自批准且版本当前的 `Strategic Design Handoff`。
-- [ ] 统一语言与 `CONTEXT.md` 一致，没有临时创造同义词。
-- [ ] 聚合根、Entity、Value Object 的身份和边界有理由。
-- [ ] 每个聚合的不变量和允许的状态转换都写清楚。
-- [ ] 一致性规则区分了立即成立与最终一致。
-- [ ] Application、Domain、Repository、Gateway 和 API 的职责没有混淆。
-- [ ] 领域事件表达业务事实，不暴露内部表结构。
-- [ ] 关键规则都有测试 seam 和失败场景。
-- [ ] 已判断轻量 `Tactical DDD Check` 是否足够；需要升级时写明原因。
-- [ ] 未决问题有负责人、后续 Ticket、验证计划和目标版本。
+## 从设计到实现
 
-## 与其他文档怎么分工
+综合项目由本仓生命周期继续路由，通用研发/后端由 Harness 流程承接。前端专职只消费上游规则、冻结接口并准备前端工程设计，不在本仓派发后端战术实现。
 
-- [用户手册索引](./用户手册索引.md)：所有入门手册的入口。
-- [战略设计子项目用户手册](../../submodules/yss-harness-design-agent/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-implementation-contract-compiler` 与后端 / 前端专项技能：批准后的实现合同、代码和验证规则。
+编译器起草当前合同，批准与可实现状态由本仓编排和门禁控制。实现前确认工程登记、冻结接口、测试 seam、允许路径与回滚点。战术评审通过不等于 ready-for-agent。
 
-本手册是模板源中的通用分发资产。真实项目应使用自己的术语、规则、合同版本和批准记录；不要把“客户合同审批”示例当成真实业务结论。
+过程示例见 [设备借用贯穿案例](设备借用贯穿案例.md)；项目选型见 [用户手册](用户手册.md)。