feat(ECR-006): 落地运营后台 Phase A（admin API + admin-h5）

新增独立鉴权的 /api/v1/admin 与 Vue 控制台；会员授予与审计同事务，并补集成/单测。 Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-06 18:35:53 +08:00
parent 4a583c9480
commit 879bf70cb7
59 changed files with 2462 additions and 20 deletions
@@ -0,0 +1,129 @@
+# Backend Design: ECR-006 运营后台 Phase A
+
+> Architect 产出；Engineer 只消费本文件。  
+> 实现纪律：`$ESS_ROOT/technology-governance/BACKEND_STANDARD.md`  
+> 项目分层权威：`.ai/architecture.md` · `.ai/architecture/go-services.md`（Handler → Service → Repository）
+
+| Field | Value |
+|-------|-------|
+| ID | BD-2026-006 |
+| ECR | ECR-006 |
+| Change Level | L2 |
+| Status | Approved |
+| Author | Architect |
+| Date | 2026-08-06 |
+| Risk | Medium |
+
+---
+
+## Context
+
+- 问题 / 目标：P1 Complete 后缺少内部运维面；需可审计的用户/订单查询与会员授予。  
+- 非目标：UGC/达人/CMS/RBAC/真支付。  
+- 相关 Spec / ADR：`.ai/product/feature-spec/ops-admin.md`；无新 ADR（栈与分层不变）。
+
+## Architecture Change
+
+- 是否改变分层边界：No  
+- 受影响层：API · Application（新 `service/admin`）· Infrastructure（repo + migration）· UI（`apps/admin-h5`）
+
+## Module Changes
+
+| Module | Layer | Change | Must NOT |
+|--------|-------|--------|----------|
+| `handler/admin*.go` | API | bind/auth 头/调 service | SQL；权益规则细节堆在 handler |
+| `service/admin` | Application | 登录、列表、grant、审计 | 直连 gin |
+| `repository/admin_repo.go` | Infrastructure | SQL | 业务解锁语义外泄 |
+| `middleware/admin_auth.go` | API | 校验 admin session | 复用 DeviceAuth 冒充 |
+| `apps/admin-h5` | UI | Vue3 控制台 | 裸 fetch 拼完整 URL（走 thin api → sdk 或本地 client） |
+
+## Data Flow
+
+```text
+admin-h5
+  → POST /admin/auth/login → admin_accounts 校验 → 写 admin_sessions → token
+  → Bearer token → AdminAuth → service/admin
+       → AdminRepo / ReportRepo(memberships,orders) / ProfileRepo 摘要
+  → grant → UPDATE memberships + INSERT admin_audit_logs
+```
+
+## API Changes
+
+- 契约：`apps/api/proto/openapi.yaml` 增补 `/admin/*`  
+- 兼容：新增路径，不影响既有 user API  
+- 信封：项目既有 `{code,message,data}`
+
+## Database Changes
+
+- `admin_accounts` · `admin_sessions` · `admin_audit_logs`（见 ERD）  
+- Immutable observation：审计表只追加  
+- Migration：`000010_admin_ops.up.sql` / `.down.sql`
+
+## Migration Plan
+
+- Required：YES  
+- 步骤：expand（建表）→ 启动 bootstrap 种子（可选）→ 无 contract  
+- 回滚：down migration 删三表（开发环境可接受）
+
+## Failure Handling
+
+- 登录失败：统一模糊文案（不暴露是否用户存在细节过度）· 审计可选记 fail  
+- Token 无效/过期：401  
+- grant：用户不存在 404；plan 非法 400；DB 错 500  
+- 幂等：grant 非严格幂等；重复授予延长 expires_at 并再记审计
+
+## Test Plan
+
+- Unit：password verify · plan duration  
+- Integration：login → list users → grant → audit  
+- API：401 without token  
+
+## Rollback Plan
+
+- 代码回滚去掉 admin 路由注册  
+- down migration  
+- 配置去掉 bootstrap  
+
+---
+
+## Backend Change Boundary（mandatory）
+
+```text
+Change Level: L2
+Change: 新增 admin 鉴权面与运维读写 API + admin-h5
+
+Affected:
+  Domain:
+    - AdminAccount / AdminSession / AdminAuditLog（运维身份，非终端 User）
+  Application:
+    - service/admin（login, users, orders, grant, audit）
+  Infrastructure:
+    - AdminRepo · migration 000010
+  API:
+    - /api/v1/admin/*
+  Migration: Required
+  Tests:
+    - admin auth + grant path
+  Risk: Medium
+```
+
+## Architecture Regression Check
+
+- [x] 无重复业务逻辑（会员写入复用既有 memberships 语义）  
+- [x] 无绕过 Service  
+- [x] 无 Handler 直连 DB  
+- [x] 无 utility dumping  
+- [x] 无隐藏全局状态  
+- [x] bootstrap 配置可追踪（config.example.yaml）  
+- [x] 未简化既有分层  
+
+---
+
+## Trace
+
+| Field | Value |
+|-------|-------|
+| BACKEND_DESIGN-ID | BD-2026-006 |
+| Implementation Commit | （实现后填） |
+| Review | （实现后填） |
+| TRACEABILITY row | ECR-006 |