digital-psychology/docs/BACKEND_DESIGN/ECR-008-ops-content.md

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

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

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

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