jackyu66gitandCursor
879bf70cb7
新增独立鉴权的 /api/v1/admin 与 Vue 控制台；会员授予与审计同事务，并补集成/单测。 Co-authored-by: Cursor <cursoragent@cursor.com>
130 lines
3.8 KiB
Markdown
130 lines
3.8 KiB
Markdown
# 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 |
|