jack/digital-psychology
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(ECR-006): 落地运营后台 Phase A（admin API + admin-h5）
ci / h5 (push) Canceled after 0s
Details
ci / api (push) Canceled after 0s
Details
ci / ess-docs (push) Canceled after 0s
Details

Browse Source 
新增独立鉴权的 /api/v1/admin 与 Vue 控制台；会员授予与审计同事务，并补集成/单测。

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
jackyu66git
2026-08-06 18:35:53 +08:00
co-authored by Cursor
parent 4a583c9480
commit 879bf70cb7
59 changed files with 2462 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/BACKEND_DESIGN/.gitkeep
View File
docs/BACKEND_DESIGN/ECR-006-ops-admin-phase-a.md
+129
View File
@@ -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 |
docs/CHANGELOG.md
+5
View File
@@ -1,5 +1,10 @@
# CHANGELOG — ESS process artifacts
## 2026-08-06
- ESS 升级后接入 `docs/BACKEND_DESIGN/`（BACKEND_STANDARD 闭环）
- **ECR-006** Closed：运营后台 Phase A（Spec `ops-admin` · BD-2026-006 · admin API + admin-h5）
## 2026-08-05
- Bind ESS v1.0（`--bind-only`）：`docs/` 流程目录 + script wrappers
docs/CODE_REVIEW/ECR-006.md
+30
View File
@@ -0,0 +1,30 @@
# CODE_REVIEW — ECR-006
**Verdict:** Approve（Feature Complete · Ops-A）
Date: 2026-08-06 · Re-review after P1/P2 fixes
## Checklist
- [x] Handler → Service → Repository；admin 路由未挂 DeviceAuth
- [x] Feature Spec Active + BACKEND_DESIGN BD-2026-006
- [x] OpenAPI 增补 `/admin/*`
- [x] 文件 ≤400；integration 绿
- [x] Grant + Audit **同事务**（`GrantMembershipWithAudit`）
- [x] Logout 复用 `middleware.BearerToken`（大小写无关）
- [x] Bootstrap 失败打 `log.Printf`
## Prior findings — resolved
| Was | Fix |
|-----|-----|
| P1 grant/audit 非原子 | `AdminRepo.GrantMembershipWithAudit` 单事务 |
| P2 logout Bearer 大小写 | 共享 `BearerToken` |
| P2 bootstrap 静默失败 | router 记录 `admin bootstrap failed` |
## Residual（不阻断）
- session token 明文落库（后置 hash）
- bootstrap 多实例 TOCTOU
- admin 未进 `@yuxingu/sdk`
- RBAC / CMS → Phase B+
docs/ECR/ECR-006-ops-admin-phase-a.md
+31
View File
@@ -0,0 +1,31 @@
# ECR-006
**Title:** 运营后台 Phase A（登录 · 用户/订单只读 · 会员授予 · 审计 · admin-h5）
**Status:** Closed
**Date:** 2026-08-06
**Change Level:** L2（新能力；栈不变）
## Change
1. Active Feature Spec：`.ai/product/feature-spec/ops-admin.md`
2. 新增表 `admin_accounts` / `admin_sessions` / `admin_audit_logs`
3. Admin API：`/api/v1/admin/*`（与 DeviceAuth 隔离）
4. `apps/admin-h5` 从占位落地 Vue3 壳 + 登录/用户/订单/审计页
5. 架构文档：`admin-h5` 由 Deferred → Phase A Active
## Non-goals
UGC · 达人 · CMS · 推送 · RBAC 分角色 · 真支付配置 · 封禁注销
## Acceptance
- [x] Spec T1–T5
- [x] `go test ./...` · admin integration
- [x] `npm run build -w @yuxingu/admin-h5`
- [x] BACKEND_DESIGN Approved 已落地
- [x] TRACEABILITY / STATE / Review Report
## Linked
PRODUCT_SPEC / ENGINEERING_SPEC / BACKEND_DESIGN / HANDOFF / TASK / STATE / TEST_REPORT / CODE_REVIEW under ECR-006
Feature Spec：`ops-admin.md`
docs/ENGINEERING_SPEC/ECR-006-ops-admin-phase-a.md
+28
View File
@@ -0,0 +1,28 @@
# ENGINEERING_SPEC — ECR-006 运营后台 Phase A
权威设计：`docs/BACKEND_DESIGN/ECR-006-ops-admin-phase-a.md`
产品：`.ai/product/feature-spec/ops-admin.md`
## Implement order
1. Migration `000010_admin_ops` + ERD 同步
2. `repository/admin_repo.go`
3. `service/admin`（auth · users · orders · grant · audit）
4. `middleware.AdminAuth` + `handler` 注册（**独立** Group，勿挂 DeviceAuth）
5. config bootstrap + `config.example.yaml`
6. OpenAPI `/admin/*` 最小路径
7. `apps/admin-h5` Vite Vue3：login + shell + 四页
8. root scripts：`dev:admin` / `build:admin`
9. 测试：service 或 integration
10. 更新 architecture / go-services / feature-map / TRACEABILITY
## Constraints
- 函数 ≤50 行 · 文件 ≤400 行
- 密码 bcrypt；session token 随机 opaque
- admin-h5 禁止页面内裸拼绝对 API URL
- 不提交 `config.local.yaml`
## Done when
ECR Acceptance 勾完 + DoD Review Report
docs/HANDOFF/ECR-006-architect-to-engineer.md
+23
View File
@@ -0,0 +1,23 @@
# HANDOFF — ECR-006 Architect → Engineer
## Consume
1. `.ai/product/feature-spec/ops-admin.md`（Active）
2. `docs/ECR/ECR-006-ops-admin-phase-a.md`
3. `docs/BACKEND_DESIGN/ECR-006-ops-admin-phase-a.md`（**BD-2026-006**）
4. `docs/ENGINEERING_SPEC/ECR-006-ops-admin-phase-a.md`
5. `$ESS_ROOT/technology-governance/BACKEND_STANDARD.md`（分层纪律；目录名从项目既有）
## Do
按 ENGINEERING_SPEC Implement order 落地 Phase A。
## Do not
- 扩到 UGC / CMS / RBAC
- Handler → DB
- 用 DeviceAuth 保护 admin 路由
## Return
HANDOFF engineer→reviewer + TEST_REPORT + CODE_REVIEW 勾选；STATE.owner → reviewer
docs/HANDOFF/ECR-006-engineer-to-reviewer.md
+17
View File
@@ -0,0 +1,17 @@
# HANDOFF — ECR-006 Engineer → Reviewer
## Done
- Migration `000010_admin_ops`
- `service/admin` · `AdminRepo` · `AdminHandler` · `AdminAuth`
- `apps/admin-h5` Phase A pages
- OpenAPI admin paths
- TEST_REPORT / integration `TestAdminOpsPhaseA`
## Evidence
`docs/TEST_REPORT/ECR-006.md` · `docs/CODE_REVIEW/ECR-006.md`
## Ask
Reviewer 勾选 Approve；可 Closed ECR-006。
docs/PRODUCT_SPEC/ECR-006-ops-admin-phase-a.md
+22
View File
@@ -0,0 +1,22 @@
# PRODUCT_SPEC — ECR-006 运营后台 Phase A
对齐 Feature Spec：`.ai/product/feature-spec/ops-admin.md`
## Outcome
内部 Admin 可登录 `admin-h5`，查询用户与订单，授予成长会员并查看审计。
## Actors
Admin（单一角色 Phase A）
## Acceptance（产品）
1. 无终端用户可访问 admin API
2. 管理员可完成 Spec §4 主路径
3. 授予会员后用户侧权益与既有 membership 规则一致
4. 每次授予可在审计页追溯
## Out of scope
见 Spec In/Out · ECR Non-goals
docs/PROJECT_PROFILE.md
+3 -2
View File
@@ -14,6 +14,7 @@
| Product · Domain · Lexicon · Feature Spec · DoD | **`.ai/`** | `.ai/product/` · `.ai/domain.md` · `.ai/definition-of-done.md` |
| Architecture · Forbidden · ADR | **`.ai/`** | `.ai/architecture.md` · `.ai/forbidden.md` · `.ai/adr/` |
| Change process · ECR · Task · Handoff · Roles | **ESS** | `docs/ECR/` · `docs/TASKS/` · `docs/HANDOFF/` · `docs/STATE/` |
| Backend change design（涉后台） | **ESS** | `docs/BACKEND_DESIGN/` + `$ESS_ROOT/.../BACKEND_STANDARD.md` |
| Stack lock (mirror) | ESS + `.ai/` | 本文 + `.ai/tech-stack.md` |
冲突时：领域与完成标准以 `.ai/` 为准；变更分级与角色门禁以 ESS 为准。
@@ -45,9 +46,9 @@
## Active anchors
- ECR: **ECR-005** H5/OpenAPI hygiene（Approved）；ECR-001–004 Closed / shipped
- ECR: **ECR-006** 运营后台 Phase A（Closed）；ECR-001–005 Closed / shipped
- EXP: （无）
- STATE: `docs/STATE/ECR-005.md`
- STATE: `docs/STATE/ECR-006.md`
- TRACEABILITY: `docs/TRACEABILITY.md`
- ADR: `.ai/adr/0007-ess-ai-dual-track.md`
- Product status: `.ai/product/p1-status.md`（**P1 Complete**）
docs/PROJECT_RULES.md
+1 -1
View File
@@ -8,7 +8,7 @@ Product/DoD 权威：`.ai/`（不在此复制长文）
1. 语言契约：只用 `.ai/product/lexicon.md` 中的愈心谷用词；禁止竞品品牌词与恐吓/吉凶话术。
2. API 信封固定为 `{code,message,data}`；不发明表名、端点、领域同义词。
3. 调用链：UI → `@yuxingu/sdk` → Handler → Service → Repository → DB。
4. 新功能 / 扩行为：必须有 Active `.ai/product/feature-spec/<id>.md`；L2+ 另须 Approved `docs/ECR/`。
4. 新功能 / 扩行为：必须有 Active `.ai/product/feature-spec/<id>.md`；L2+ 另须 Approved `docs/ECR/`；**涉后台**另须 Approved `docs/BACKEND_DESIGN/`。
5. 本地默认：本机 `go run` + Vite；compose 只起 DB。
6. Done ≠ build 通过：须过 `.ai/definition-of-done.md` 并输出 Review Report。
docs/STATE/ECR-006.md
+14
View File
@@ -0,0 +1,14 @@
# STATE — ECR-006
| Field | Value |
|-------|-------|
| ECR | ECR-006 |
| Status | Closed |
| Owner | — |
| Phase | done |
| Spec | `.ai/product/feature-spec/ops-admin.md` |
| BACKEND_DESIGN | BD-2026-006 Approved |
| Review | PASS · CODE_REVIEW/ECR-006.md |
| Updated | 2026-08-06 |
Phase A shipped: admin API + admin-h5.
docs/TASKS/TASK-006-ECR006.yaml
+18
View File
@@ -0,0 +1,18 @@
id: TASK-006-ECR006
ecr: ECR-006
title: Ops admin Phase A implementation
role: engineer
status: open
change_level: L2
inputs:
- docs/HANDOFF/ECR-006-architect-to-engineer.md
- docs/BACKEND_DESIGN/ECR-006-ops-admin-phase-a.md
- .ai/product/feature-spec/ops-admin.md
outputs:
- apps/api admin package + migration
- apps/admin-h5 Vue shell
- docs/TEST_REPORT/ECR-006.md
acceptance:
- Spec T1-T5
- go test ./...
- admin-h5 build
docs/TEST_REPORT/ECR-006.md
+36
View File
@@ -0,0 +1,36 @@
# TEST_REPORT — ECR-006 Ops Admin Phase A
Date: 2026-08-06
## Commands
```bash
cd apps/api && go test ./internal/middleware/ ./internal/service/admin/ ./internal/integration/ \
-count=1 -run 'TestBearerToken|TestPlanDays|TestAdminOps'
npm run build:admin
```
## Results
| Check | Result |
|-------|--------|
| `TestBearerToken` | PASS |
| `TestPlanDays` | PASS |
| `TestAdminOpsPhaseA`（401 · login · grant+audit 原子 · lowercase logout） | PASS |
| `npm run build:admin` | PASS（既有） |
## Spec mapping
| Spec | Evidence |
|------|----------|
| T1 无 token → 401 | TestAdminOpsPhaseA |
| T2 登录 | login 200 |
| T3 列表 users | list users len>0 |
| T4 grant + audit | membership.active + audit target_id |
| T5 admin-h5 | build 绿 |
## Follow-up fixes（review）
- Grant/Audit 单事务
- Logout `bearer`/`Bearer` 一致
- Bootstrap 失败日志
docs/TRACEABILITY.md
+1
View File
@@ -11,3 +11,4 @@
| ECR-003 | outlook JSON hygiene（删 fortune / lucky→boost） | review PASS | TEST_REPORT · CODE_REVIEW/ECR-003.md |
| ECR-004 | Synastry 再拆 · Scale 测 · Membership 守卫 · OpenAPI · CI | review PASS | TEST_REPORT · CODE_REVIEW/ECR-004.md |
| ECR-005 | Ask/Decode/Portrait 再拆 · composable 外提 · OpenAPI `$ref` | review PASS | TEST_REPORT · CODE_REVIEW/ECR-005.md |
| ECR-006 | 运营后台 Phase A（admin API + admin-h5） | **Closed** | Spec ops-admin · BD-2026-006 · TEST_REPORT · CODE_REVIEW |