docs: freeze WAVE0 domain foundation and contract governance

Mark WAVE0 FROZEN CANDIDATE for Human Review; docs + .ai domain/product only — no apps or migrations. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-07 16:20:11 +08:00
parent d33c8fdfe9
commit 27f27a1cb2
16 changed files with 1322 additions and 3 deletions
@@ -0,0 +1,111 @@
+# OPS Contract Template（L0–L4 · Loop 强制）
+
+> Wave 0 · 每张实现向 ECR / Feature Spec **编码前**必须填满  
+> 路径：`docs/WAVE0/contracts/OPS-CONTRACT-TEMPLATE.md`
+
+复制为：`docs/PRODUCT_SPEC/ECR-xxx-<slug>.md` 或 Feature Spec 内嵌同等章节。
+
+---
+
+## Meta
+
+| 字段 | 值 |
+|------|-----|
+| ECR | |
+| Status | Draft \| Approved |
+| Capability (L0) | 例：`AdminGovernance` |
+| Bounded Context (L1) | 例：`Admin_RBAC` |
+| Change Level | L2 \| L3 |
+
+---
+
+## L0 Capability
+
+| 字段 | 内容 |
+|------|------|
+| Capability ID | |
+| Purpose（一句话业务能力） | |
+| Why now | |
+| Non-goals | |
+
+禁止写页面/按钮清单。
+
+---
+
+## L1 Bounded Context
+
+| 字段 | 内容 |
+|------|------|
+| Primary BC | |
+| owns / does_not_own | 引用或摘录 `boundary-rules.md` |
+| allowed / forbidden deps | |
+
+---
+
+## L2 Domain
+
+| Entity | 不变式 / 状态机 |
+|--------|-----------------|
+| | |
+
+Glossary 词必须已在 `.ai/domain/glossary.yaml` 登记。
+
+---
+
+## L3 API Contract
+
+| Method | Path | 语义 |
+|--------|------|------|
+| | | |
+
+- OpenAPI：`proto/openapi.yaml` 同步意图  
+- BD：`docs/BACKEND_DESIGN/BD-*-*.md`  
+- **必交** [`contract_diff` 模板](contract_diff.template.yaml) → 实例：`docs/CONTRACT_DIFF/ECR-xxx.yaml`
+
+信封：`{code,message,data}`。Admin ≠ DeviceAuth。
+
+---
+
+## L4 Acceptance Criteria
+
+每个 AC 必须有稳定 ID（如 `AC-F-01`）。
+
+### Functional AC
+
+| ID | Given | When | Then |
+|----|-------|------|------|
+| AC-F-01 | | | |
+
+### Security AC
+
+| ID | Given | When | Then |
+|----|-------|------|------|
+| AC-S-01 | Admin 无权限 | 调用 API | 403 且 AuditLog 有记录 |
+
+### Performance AC
+
+| ID | Given | When | Then |
+|----|-------|------|------|
+| AC-P-01 | N=（写明） | 打开 admin 列表 | P95 &lt;（写明）ms |
+
+### Observability AC
+
+| ID | Given | When | Then |
+|----|-------|------|------|
+| AC-O-01 | 状态迁移发生 | — | AuditLog 存在；若有 trace 则含 trace_id |
+
+危机类另加 **Safety AC**（独立节，不在本通用表省略生命安全）。
+
+---
+
+## Evidence（实现后）
+
+- TEST_REPORT 映射全部 AC-ID  
+- contract_diff.breaking_change 解释完毕  
+- Reviewer 核对 boundary-rules  
+
+---
+
+## Forbidden（本切片）
+
+显式列出：真支付 / UGC / 其他 Capability 偷渡项。
@@ -0,0 +1,34 @@
+# contract_diff — template (P0 · required per implement ECR)
+
+# Copy to: docs/CONTRACT_DIFF/ECR-xxx.yaml
+# Guardian / Reviewer: reject coding Approve if missing or breaking without migration notes.
+
+ecr: ECR-XXX
+capability: ""          # L0 id
+bounded_context: ""     # L1 id
+change:
+  type: additive        # additive | breaking | deprecate
+breaking_change: false
+migration_required: false
+compatibility_notes: ""
+
+entities:
+  - name: ExampleEntity
+    before: null
+    after:
+      fields:
+        - id
+        - name
+
+apis:
+  - method: GET
+    path: /api/v1/admin/example
+    change: added       # added | modified | removed
+    request_delta: null
+    response_delta: null
+
+security_impact:
+  - "AdminAuth required"
+
+observability_impact:
+  - "writes AuditLog on mutate"