digital-psychology/docs/BACKEND_DESIGN/BD-2026-013B-account-lifecycle.md

Backend Design: ECR-013B AccountLifecycle

Architect 产出；Approved + Coding Start Authorization 2026-08-07。
Parent: WAVE0-FROZEN · Predecessor: ECR-013A Closed

Field	Value
ID	BD-2026-013B
ECR	ECR-013B
Change Level	L2
Status	Approved
Approved	2026-08-07（Human） · Coding authorized
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

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

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