jianghaifeng
7513ac06bc
用户口径：specs 仓库今后只拉取、由项目负责人维护，我们不再向其提交；工作留痕与 指令队列改放本仓库 docs/plans/ 下，避免本地领先提交与上游 INBOX 反复冲突。 本文件包含双 Agent 协作红线（含"验收归用户""门禁口径"），以及当前待处理条目 I1：后台管理端商品（金币包）配置 + 系统公告管理（后端接口 + ReelShortWeb 页面）。
78 lines
8.3 KiB
Markdown
78 lines
8.3 KiB
Markdown
# 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. **不要连着抢做下一批。**
|