digital-psychology/docs/BACKEND_DESIGN/ECR-006-ops-admin-phase-a.md

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

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）

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

• 无重复业务逻辑（会员写入复用既有 memberships 语义）
• 无绕过 Service
• 无 Handler 直连 DB
• 无 utility dumping
• 无隐藏全局状态
• bootstrap 配置可追踪（config.example.yaml）
• 未简化既有分层

---

Trace

Field	Value
BACKEND_DESIGN-ID	BD-2026-006
Implementation Commit	（实现后填）
Review	（实现后填）
TRACEABILITY row	ECR-006