# 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 鉴权隔离  
- [ ] 未引入非默认中间件  
- [ ] 未简化分层