jackyu66gitandCursor
7ab9add5dd
落地埋点 ingest/数据看板、首页宫格 CMS 与测评上下架；含账号引导、问答流式与免责声明去重，以及 review P1 审计同事务修复。 Co-authored-by: Cursor <cursoragent@cursor.com>
129 lines
3.2 KiB
Markdown
129 lines
3.2 KiB
Markdown
# 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 鉴权隔离
|
||
- [ ] 未引入非默认中间件
|
||
- [ ] 未简化分层
|