feat(ops): ECR-007 行为分析与 ECR-008 内容运营后台

落地埋点 ingest/数据看板、首页宫格 CMS 与测评上下架；含账号引导、问答流式与免责声明去重，以及 review P1 审计同事务修复。 Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-07 02:26:16 +08:00
parent 7e9023f0a8
commit 7ab9add5dd
132 changed files with 8276 additions and 491 deletions
@@ -0,0 +1,128 @@
+# Backend Design: ECR-008 运营内容 Ops-C
+
+> Architect 产出；Engineer 只消费本文件。  
+> 项目分层：Handler → Service → Repository
+
+| Field | Value |
+|-------|-------|
+| ID | BD-2026-008 |
+| ECR | ECR-008 |
+| Change Level | L2 |
+| Status | Approved（2026-08-07 Human） |
+| Author | Architect |
+| Date | 2026-08-07 |
+| Risk | Medium |
+
+---
+
+## Context
+
+- 目标：首页宫格可运营配置；scales 可上下架。  
+- 非目标：Feeds CMS、题目编辑器、外链图标、RBAC。  
+- 无新 ADR。
+
+## Architecture Change
+
+- 分层边界：No  
+- 层：API · Application · Infrastructure · UI（user-h5 home · admin-h5 内容）
+
+## Module Changes
+
+| Module | Layer | Change | Must NOT |
+|--------|-------|--------|----------|
+| `repository/home_tools` | Infra | CRUD / ReplaceAll | 泄漏到 UI |
+| `repository/scale` | Infra | ListAll · UpdateStatus | |
+| `service/home` 或 content | App | 白名单校验 · 事务替换 | 直连 gin |
+| `handler` home + admin | API | 绑定鉴权 | SQL |
+| `user-h5` useHomePage | UI | GET tools | 直写 DB |
+| `admin-h5` ContentPage | UI | 编辑保存 | 裸绝对 URL |
+
+## Data Flow
+
+```text
+admin-h5 内容页
+  → PUT /admin/home/tools  → service → ReplaceAll + audit
+  → PATCH /admin/scales/:id → UpdateStatus + audit
+
+user-h5 首页
+  → GET /home/tools → enabled 列表 → HomeToolGrid
+  失败 → homeCatalog.ts 静态回退
+
+C 端测评
+  → GET /scales（既有 ListPublished）
+```
+
+## API Changes
+
+- `GET /api/v1/home/tools` → `{ items: [{ id, row_index, sort_order, path, icon, label, badge?, badge_tone? }] }`  
+- `GET /api/v1/admin/home/tools` → 含 `enabled`  
+- `PUT /api/v1/admin/home/tools` body `{ items: [...] }` 整表替换  
+- `GET /api/v1/admin/scales` → 全量含 status  
+- `PATCH /api/v1/admin/scales/{id}` body `{ status: published|draft }`  
+
+## Database
+
+```sql
+home_tools (
+  id uuid PK,
+  row_index smallint NOT NULL,  -- 1 or 2
+  sort_order int NOT NULL,
+  path text NOT NULL,
+  icon varchar(32) NOT NULL,
+  label varchar(32) NOT NULL,
+  badge varchar(8) NULL,
+  badge_tone varchar(8) NULL,
+  enabled boolean NOT NULL DEFAULT true,
+  updated_at timestamptz NOT NULL DEFAULT now()
+)
+```
+
+Migration：`000014_ops_content.up.sql` / `.down.sql`
+
+## Validation
+
+- icon ∈ 既有 HomeToolIcon 名集合  
+- path 匹配 `^/[a-zA-Z0-9_./-]{1,120}$` 且不含 `..`  
+- row_index ∈ {1,2}；label 1–16 字；items ≤ 24  
+- status ∈ {published, draft}  
+- 非法整批 400  
+
+## Failure Handling
+
+- Admin 无 token：401  
+- scale 不存在：404  
+- DB：500；H5 拉 tools 失败静默回退静态  
+
+## Test Plan
+
+- Unit：path/icon 校验  
+- Integration：seed → PUT 改 enabled → GET home 少一项；PATCH draft → ListPublished  
+
+## Rollback
+
+见 ECR。
+
+---
+
+## Backend Change Boundary
+
+```text
+Change Level: L2
+Change: home_tools CMS + scales status admin
+
+Affected:
+  Domain: HomeTool
+  Application: service/home · admin scales
+  Infrastructure: HomeToolsRepo · ScaleRepo · 000014
+  API: /home/tools · /admin/home/tools · /admin/scales
+  Migration: Required
+  Tests: integration content ops
+  Risk: Medium
+```
+
+## Architecture Regression Check
+
+- [ ] 无 Handler 直连 DB  
+- [ ] Admin / Device 鉴权隔离  
+- [ ] 未引入非默认中间件  
+- [ ] 未简化分层