# 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 |