FruitServer/docs/plans/INBOX.md

INBOX — 给 Codex 的指令队列（FruitServer 仓库内）

Codex 每次开始任务前必须先读本文件（2026-10-16 起指令通道从 specs 仓库迁到本仓库）。 按条目顺序执行，处理完的条目标记 [已处理]。指令来源：项目经理（Trae）。有异议在条目下留言，不要静默跳过。

规范以 specs 仓库为准（AGENTS.md、CODING_STANDARDS.md、GIT_WORKFLOW.md、docs/01~20、docs/plans/codex-研发任务清单.md）—— specs 现在只拉取、由项目负责人更新，我们不再往它提交。工作留痕写在本仓库 docs/plans/PROGRESS.md。

⚠️ 双 Agent 协作红线（Trae + Codex 共守）

1. 单一写者：同一时刻只有一个 agent 在改代码/写 PROGRESS/跑门禁。
2. 留痕：谁干活谁写 docs/plans/PROGRESS.md（命令 + 原始输出 + 解读，逐动作追加）。Trae 接手时用「【Trae 接手】」标记。
3. git 不冲突：提交前先 git status/git log；只 git add 自己的文件，禁止 git add -A/.；不夹带对方改动。
4. 文件不覆盖：写 INBOX/PROGRESS 前先读最新，追加不覆盖。
5. 求助通道：遇到阻塞/不确定，在本文件顶部写「【待 Trae 协助】+ 问题描述」。
6. 禅道同步：任务「开始/完成」时同步更新禅道任务状态。
7. 验收归用户：每批做完停在干净交接点，由用户亲自验证；回执必须含「用户可照做的验证步骤 + 每步预期结果」。
8. 门禁（不达标不提交）：后端 = mvn test 全过（核心接口须有契约测试）；Web = pnpm build:pro 通过 + eslint 零错误；Flutter = dart analyze lib test 零告警 + flutter test 全过。
9. 分支：在 develop 提交并 git push origin develop；绝不动 main（dev→main 走 PR，由用户操作）。

---

[待处理] 2026-10-16 17:30 | I1 后台管理端：商品（金币包）配置 + 系统公告管理（后端接口 + Web 页面）

用户指令（2026-10-16 17:10）：「现在做后台管理端，规范还是按照 specs」+「ReelShortWeb 就是这个项目」→ 后台管理端 = ReelShortWeb（Vue3 + Element Plus），本批后端接口与页面一起做。

一、PM 已勘察的两个缺口（实测证据，直接用）

#	缺口	证据
1	商品/金币包配置：后台完全没有入口	product 表 16 个字段已建（code/name/type/platform/store_product_id/coin_amount/bonus_coin/price_amount/currency/display_price/region_codes/vip_days/sort/status/effective_at/expire_at）、已有 3 行种子数据、C 端 /app/orders/verify 依赖 store_product_id 对齐商店商品（错误码 200002 该商品未在后台配置 就是为它留的）；但 admin-api 29 个 Controller 里没有任何商品 CRUD 接口（grep 只命中 WalletAdminController /coins 的发币补偿）→ 运营改商品只能改库。PRD §09 明确要求「商品配置与价格分层」
2	系统公告：有读没写	ops_notice 表 0 行；E1 已交付 C 端 GET /app/notices（匿名只读）；契约 §2.7 原话「系统公告 ops_notice 目前没有产出方，等有公告功能再接」→ 后台没有公告管理接口，运营发不了公告

除这两项外，admin-api 对照契约 §2.1–§2.10 全部已实现，不要重做。

二、后端（FruitServer / admin-api）

1. 契约先行（依据 12-上线检查清单 §一）：先在 docs/api-phase1.md 写清两个模块的接口、字段、错误码、权限点（放在 §2.6 订单与权益之后，或新增一节），再动代码。
2. 商品配置 /admin/products：
   • GET /admin/products/page（筛选：type / status / platform / keyword，分页沿用既有口径）、GET /admin/products/{id}
   • POST /admin/products、PUT /admin/products/{id}、PUT /admin/products/{id}/status（上下架）、DELETE /admin/products/{id}
   • 字段按 product 表现有结构，不要改表
   • 必须有校验：code 在全局唯一、store_product_id 在同一 platform 下唯一（否则同一商店商品被重复配置 → 发币口径混乱）；type=COIN 时 coin_amount > 0；type=VIP 时 vip_days > 0
   • ⚠️ VIP 商品口径：B1-1 已定「VIP 订阅本轮不做」→ 允许建但不允许启用（启用报明确错误）或直接拒绝创建，二选一由你定，写进契约并在回执里说明；拿不准就写「【待 Trae 协助】」
   • 权限点命名沿用现有习惯（参考 commerce:*），并落 sys_permission + sys_menu
3. 系统公告 /admin/notices：
   • GET /admin/notices/page、GET /admin/notices/{id}、POST、PUT /admin/notices/{id}、PUT /admin/notices/{id}/status（发布/下架）、DELETE /admin/notices/{id}
   • 字段按 ops_notice 表现有结构，不要改表
   • 与 C 端 GET /app/notices 的筛选口径必须严格对齐（E1 已定：status=1 且 target ∈ {ALL, USER}、publish_at <= now、expire_at 为空或未过期、按 publish_at desc, id desc）—— 后台发布后 C 端能查到、过期/下架后查不到
   • 权限点 + 菜单同上
4. 菜单与权限点落库：写进 sql/data-phase1.sql（幂等），注意沿用既有保留段、不要与现有 id 冲突（现有菜单到 id 30）。建议：商品配置挂 订单与权益(id 22) 下；系统公告可挂新的运营分组，具体由你按现有约定定。超管必须可见且可授权。
5. Swagger 中文注解按 S1 规范补齐（@Tag / @Operation）。
6. 门禁：mvn test 存量 91 条不得跑红 + 新增契约测试，至少覆盖：store_product_id 同平台唯一、code 唯一、type 校验、公告发布后 C 端可见 / 过期或下架后不可见、越权（无权限点被拒）。

三、后台页面（ReelShortWeb）

挂载机制（PM 已勘察）：路由是静态注册在 src/router/index.ts（component: () => import('@/views/...')），而菜单树来自 DB sys_menu，其中 component 字段必须与视图路径一致（例：views/contentManagement/DramaManagementView）。两边都要加。

1. 新增两个页面（放在与现有页面同级的目录，命名沿用 XxxManagementView.vue 风格）：
   • 商品配置：列表（分页/筛选）+ 新建/编辑弹窗 + 上下架 + 删除；表单字段按 product 表；金额/金币用数字输入并做前端校验
   • 系统公告：列表 + 新建/编辑（标题/正文/类型/目标/发布时间/失效时间）+ 发布/下架 + 删除
2. 按现有约定写：API 封装放 src/api/admin/（新增如 product.ts / notice.ts）；权限码走现有的 can(code)；表格状态列用接口返回的 status / statusText，不要在前端写死中文；大数值用 formatCount。
3. src/router/index.ts 静态注册路由（route_name 与 DB sys_menu.route_name 一致，注意不要与既有 route_name 重名 —— 之前踩过 CreatorCenter 重名导致白屏/404 的坑）。
4. 不要改动已对接的既有页面（避免与其他人正在做的改动冲突）。
5. 门禁：pnpm build:pro 通过 + eslint 零错误。

四、git

• FruitServer：在 develop 提交并推送；不动 main。
• ReelShortWeb：现在是 main 分支且与远端分叉（本地 4564aa8 领先 1、远端 1fd0b8b 全量补充作者标识 领先 1）。请先 git fetch 并把远端合进来，然后按 specs 的 GIT_WORKFLOW 新建 develop 分支，在 develop 上提交并 git push origin develop；不动 main（合并走 PR、由用户操作）。远端是 jianghaifeng/ReelShortWeb.git（有写权限）。
• 作者的署名规范：// Author: fruit.com.cn（Vue/TS 文件首行）。

五、节奏（红线第 7 条）

1. 先写计划文件 docs/plans/2026-10-16-I1.md（后端 + 前端两部分、步骤、风险、待确认）。
2. 做，跑门禁。
3. 停在干净交接点写回执：逐项列出改了什么；给你和用户可照做的验证步骤 + 每步预期结果（含「后台登录 → 菜单里能看到这两个新页面 → 建一个商品 → 用该商品在 C 端 verify 能对上」这样的端到端链路）。
4. 不要连着抢做下一批。