docs(ECR-013B): 启动 AccountLifecycle 契约定义

Human Start Authorization：UserStatus 状态机 Spec/BD/contract_diff；禁止 coding，待 Approve + coding Start Authorization。 Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-07 17:23:04 +08:00
parent b5a05941d9
commit f75b42397f
17 changed files with 549 additions and 9 deletions
@@ -0,0 +1,106 @@
+# Backend Design: ECR-013B AccountLifecycle
+
+> Architect 产出；**Contract Definition** — Status Draft；Approve 前禁止实现。  
+> Parent: WAVE0-FROZEN · Predecessor: ECR-013A Closed
+
+| Field | Value |
+|-------|-------|
+| ID | BD-2026-013B |
+| ECR | ECR-013B |
+| Change Level | L2 |
+| Status | Draft |
+| Author | Architect |
+| Date | 2026-08-07 |
+| Risk | Medium |
+
+---
+
+## Context
+
+- 目标：UserStatus 状态机 + 运营迁移 + C 端拒绝非 active  
+- 非目标：soft-delete；UGC；真支付；AdminAccount 启停深化  
+- Spec：`ops-account-lifecycle.md` · boundary-rules `Identity_Profile`
+
+## Architecture Change
+
+- 分层边界：**No**  
+- 受影响层：API(admin) · Application(account/lifecycle 或 admin 协作服务) · Middleware(DeviceAuth) · Infrastructure(repo+migration) · UI(admin-h5 最小)
+
+## Module Changes
+
+| Module | Layer | Change | Must NOT |
+|--------|-------|--------|----------|
+| account / user status service | App | 迁移 + 边校验 + 事务 | soft-delete |
+| DeviceAuth / session | API | 拒绝非 active | 改 Visitor 创建语义 |
+| admin handlers | API | POST status · GET transitions | Handler SQL |
+| admin_rbac seed | Infra | additive permission | 重做 RBAC |
+| admin-h5 | UI | 用户详情 CTA | 直连 DB |
+
+## Data Flow
+
+```text
+Admin POST /users/:id/status
+  → RequirePermission(admin.users.status.write)
+  → validate edge
+  → tx: UPDATE users.status + INSERT transition + AuditLog
+  → 200
+
+C-end request
+  → DeviceAuth / Bearer resolve user
+  → if status != active → 401/403
+```
+
+## API Changes
+
+- 契约意图见 Spec；实现轮写 `proto/openapi.yaml`  
+- 兼容：additive；既有 status 字段语义收紧（非 active 开始拒绝）
+
+## Database Changes
+
+- Migration **Required: YES**（实现轮）  
+- 表：`account_state_transitions`  
+- Permission 种子：`admin.users.status.write`  
+- Wave 0 / Contract 轮：**不写 migration 文件**
+
+## Failure Handling
+
+- 非法边 / 同状态：400  
+- 无权限：403  
+- 无会话：401  
+- 用户不存在：404  
+
+## Test Plan
+
+- Integration：AC-F/S/O；AC-P-01 本机抽样  
+- 禁止跳过 Security AC（含 C 端拒绝）  
+
+## Rollback Plan
+
+- down migration；DeviceAuth 去掉 status 检查；permission 行可留（无害）
+
+---
+
+## Backend Change Boundary
+
+```text
+Change Level: L2
+Change: UserStatus transitions + C-end reject non-active
+
+Affected:
+  Domain: UserStatus, AccountStateTransition
+  Application: account lifecycle service
+  Infrastructure: migration + repo
+  API: /admin/users/:id/status*
+  Middleware: DeviceAuth / session gate
+  Migration: Required at implement — NOT in contract phase
+  Tests: integration admin status + device reject
+  Risk: Medium
+```
+
+## Architecture Regression Check
+
+- [ ] 无 Handler 直连 DB  
+- [ ] Admin / Device 鉴权隔离  
+- [ ] UserStatus 归属 Identity_Profile  
+- [ ] 不拥有 Payment / UGC  
+- [ ] 符合 boundary-rules