# I1 后台管理端：商品（金币包）配置 + 系统公告管理 —— 计划（2026-10-16）

> 依据：`FruitServer/docs/plans/INBOX.md` 17:30 条目。用户口径「现在做后台管理端，规范还是按照 specs」。
> **本轮=后端接口 + ReelShortWeb 页面一起做**。指令通道已迁到本仓库（`FruitServer/docs/plans/`），
> 留痕写 `FruitServer/docs/plans/PROGRESS.md`（本轮新建）；**specs 只读、不再写入**。

## 一、两个缺口（PM 已勘察，直接用）

1. **商品/金币包配置后台无入口**：`product` 表 16 字段已建、3 行种子、C 端 verify 依赖 `store_product_id` 对齐商店商品，但 admin-api 没有任何商品 CRUD。
2. **公告有读没写**：`ops_notice` 表 0 行，E1 交付了 C 端读，后台没有写入口。

## 二、勘察补充（影响做法，已实测）

1. **前端挂载机制**（与条目描述略有出入，已核实）：`src/utils/routerHelper.ts` 用
   `import.meta.glob('../views/**/*.{vue,tsx}')` + 后端菜单的 `component` 字符串**动态解析**；
   `src/router/index.ts` 的 `asyncRouterMap` 只静态声明了 dashboard/content/user/system 等早期分组，
   commerce/governance/board 这些都没有静态登记。→ 所以新增页面**只需**：① 新建 `.vue`；
   ② `sql/data-phase1.sql` 里加菜单且 `component` 与视图路径一致。**静态路由不必改**（改了也无害）。
   真正的坑是 `route_name` 唯一（曾因 `CreatorCenter` 重名导致 404），本轮命名会避开。
2. **id 保留段**：权限点已用到 1155、菜单已用到 30 → 权限点用 **1160-1163**、菜单用 **31/32/33**。
3. **前端既有约定**：api 封装在 `src/api/admin/*`（`import request from '@/axios'` + `PageResult`），
   页面用 `useRbac().can(code)` 控权、`dateCell` 格式化日期、`PageHeading` 标题；金额/金币这类大数值本项目
   没有 `formatCount`，实际用的是 `src/utils/format.js`，**我会用其中的数值格式化工具或 `toLocaleString`**，
   并在回执说明（不新造 util）。

## 三、口径决定（需在回执与契约里写清）

**VIP 商品**：**允许创建、不允许启用**（`PUT /{id}/status` 把 `type=VIP` 置为启用 → `400`）。
理由：运营可以先把 VIP 商品与商店 product id 录好，等 B2 订阅上线后一键启用；直接拒绝创建会让上线日重新补数据。
B1-1 已定「VIP 订阅本轮不做」，所以**启用**才是会产生误导的动作，拦在这里。

## 四、后端做法

1. **契约先行**：`docs/api-phase1.md` 新增一节（放在 §2.6 订单与权益之后的新编号），写清两个模块的
   接口、字段、校验、错误码、权限点。
2. **商品**（module-commerce 加 service/VO，admin-api 加 controller）：
   `GET /admin/products/page`（type/status/platform/keyword + 分页）、`GET /{id}`、`POST`、`PUT /{id}`、
   `PUT /{id}/status`、`DELETE /{id}`；字段按表结构；校验：`code` 全局唯一、`store_product_id` 同 `platform` 唯一、
   `type=COIN → coin_amount>0`、`type=VIP → vip_days>0`、**VIP 不可启用**。响应带 `statusText/typeText`（前端不写死中文）。
3. **公告**（module-system 加 `OpsNoticeService` + VO，admin-api 加 controller）：
   `GET /admin/notices/page`、`GET /{id}`、`POST`、`PUT /{id}`、`PUT /{id}/status`、`DELETE /{id}`。
   **筛选逻辑收敛到 `OpsNoticeService.pageForApp()` 一处**，C 端 `AppNoticeService` 改为委托它
   （改我自己 E1 写的文件），这样"后台发布 → C 端可见 / 过期或下架 → 不可见"用的是同一段条件，不会漂移。
4. **菜单与权限点**：`sql/data-phase1.sql` 幂等追加（权限点 1160-1163、菜单 31/32/33 与超管授权）。
   商品挂「订单与权益」(id 22) 下；公告新建「运营管理」(id 32) 分组 + 子菜单 (33)。
5. **Swagger**：两个新控制器按 S1 规范加 `@Tag`/`@Operation`，并把分组补进 admin-api 的 `@OpenAPIDefinition`。

## 五、前端做法（ReelShortWeb，develop 分支）

- `src/api/admin/product.ts`、`src/api/admin/notice.ts`（按 `commerce.ts` 的写法）
- `src/views/commerce/ProductManagementView.vue`（列表/筛选/新建编辑弹窗/上下架/删除）
- `src/views/operation/NoticeManagementView.vue`（列表/新建编辑/发布下架/删除）
- `sql/data-phase1.sql` 的菜单 `component` 写 `views/commerce/ProductManagementView`、`views/operation/NoticeManagementView`
- **不改既有页面**；`route_name` 用 `commerce-products` / `operation-notices`（先 grep 确认不重名）

## 六、门禁

- 后端：`mvn test` 存量 **91 条不得跑红** + 新增测试（商品三类校验、公告可见性委托、
  两个控制器的接入层契约、权限点注解检查）
- 前端：`pnpm build:pro` 通过 + eslint 零错误
- 端到端：后台登录 → 菜单出现两个新页面 → 建商品 → 用该商品在 C 端 `verify` 能对上
  （`store_product_id` 命中，不再是 `200002 该商品未在后台配置`）；公告发布 → C 端 `/app/notices` 可见 → 下架/过期 → 不可见

## 七、风险 / 待确认

1. **不新增静态路由**是否与条目"两边都要加"冲突：我按实测的加载机制做，若你要求同时静态登记，我再补（不影响正确性）。
2. `/app/orders/verify` 走真实 Google Play 才有完整链路；本机无商店凭据，端到端验证到"200002 消失、进入校验环节"为止。
3. 公告"发布时间"语义：`publish_at` 为空视为立即生效（C 端条件里已按"为空或 <= now"处理）。