feat(admin): 补齐管理员账号与客服运营长尾页

2026-10-30 16:16:37 +08:00
parent a54680f59a
commit a39a504b81
10 changed files with 2482 additions and 5 deletions
@@ -0,0 +1,142 @@
+# Phase 2 验收报告（后台长尾四页）
+
+> 日期：2026-10-30  
+> 项目：解忧商行（hfb_jysh）  
+> 范围：管理员账号、手工录单、快捷回复、推广追踪  
+> 结论：**四个页面已完成并接入菜单；只读接口与路由回归全部通过；写操作未在验收中执行**
+
+---
+
+## 1. 管理员账号
+
+- 页面：`frontend/src/features/admin/AdminStaffAccountsPage.tsx`
+- 路由：`/console-jy8k3m/admin-users`
+- 权限：`admin_user:manage`
+- 接口：
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET | `/api/admin/admin-users` | 分页列表（`page` / `page_size`） |
+| GET | `/api/admin/admin-users/:id` | 单个账号 |
+| POST | `/api/admin/admin-users` | 新建（用户名 + 初始密码） |
+| PUT | `/api/admin/admin-users/:id` | 修改昵称与状态 |
+| DELETE | `/api/admin/admin-users/:id` | 删除 |
+| PUT | `/api/admin/admin-users/:id/roles` | 覆盖式分配角色 |
+| PUT | `/api/admin/admin-users/:id/password` | 重置密码 |
+
+- 能力：
+  - 列表展示账号、状态、角色标签、角色说明、最后登录与创建时间，服务端分页。
+  - 新建时校验密码强度：至少 8 位且同时包含字母与数字（与后端 `passwordStrongEnough` 一致）。
+  - 角色分配复用 `GET /api/admin/roles` 的缓存数据，多选后整体覆盖提交。
+  - 前端拦截「删除当前登录账号」，并禁用对应按钮；后端仍会二次校验自身删除与最后一个超级管理员。
+  - 重置密码后提示该账号需重新登录（后端会提升 `token_version` 使旧会话失效）。
+
+## 2. 手工录单
+
+- 页面：`frontend/src/features/admin/AdminManualEntriesPage.tsx`
+- 路由：`/console-jy8k3m/manual-entries`
+- 权限：`cs_manual_entry:view/create/update/delete/option_manage`
+- 接口：
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET | `/api/admin/manual-entries` | 列表（`entry_no`/`keyword`/`admin_id`/`start_date`/`end_date`/分页） |
+| POST | `/api/admin/manual-entries` | 新建录单，客服身份取登录上下文 |
+| PUT | `/api/admin/manual-entries/:id` | 修正录单 |
+| DELETE | `/api/admin/manual-entries/:id` | 删除录单 |
+| GET | `/api/admin/manual-entries/today-stats` | 今日按客服统计 |
+| GET/POST | `/api/admin/manual-entries/options` | 选项查询 / 新增 |
+| PUT/DELETE | `/api/admin/manual-entries/options/:id` | 选项重命名 / 删除 |
+
+- 能力：
+  - 顶部展示今日录单总数与参与客服，按客服聚合打标签，60 秒自动刷新。
+  - 筛选支持编号、关键字与日期区间（北京时间闭区间，按 `YYYY-MM-DD` 传参）。
+  - 平台与操作人从选项表中取值，同时允许手工填写选项外的值。
+  - 选项管理弹窗支持新增、点击标签重命名、删除；不影响历史录单记录。
+
+## 3. 快捷回复
+
+- 页面：`frontend/src/features/admin/AdminQuickRepliesPage.tsx`
+- 路由：`/console-jy8k3m/chat-quick-replies`
+- 权限：查看 `chat:view`，增删改 `chat:send`
+- 接口：`GET/POST /api/admin/chats/quick-replies`、`PUT/DELETE /api/admin/chats/quick-replies/:id`
+- 能力：标题、内容（1000 字上限）、排序（0–9999）、全局/个人可见开关；列表按排序值升序展示，内容支持展开与省略。
+
+## 4. 推广追踪
+
+- 页面：`frontend/src/features/admin/AdminTrackingLinksPage.tsx`
+- 路由：`/console-jy8k3m/tracking-links`
+- 权限：`ad_tracking:manage`
+- 接口：
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET | `/api/admin/tracking-links` | 列表（关键字 / 渠道 / 状态 / 分页） |
+| GET | `/api/admin/tracking-links/overview` | 大盘统计 |
+| POST | `/api/admin/tracking-links` | 创建 |
+| PUT | `/api/admin/tracking-links/:id` | 编辑 |
+| PUT | `/api/admin/tracking-links/:id/status` | 启用 / 停用 |
+
+- 能力：
+  - 顶部 6 个统计：累计 PV/UV、注册、成交订单、成交金额、今日 UV。
+  - 成本按元录入、按分提交：`cost_cent = Math.round(cost_yuan * 100)`，展示统一走 `formatMoney(cents)`。
+  - 列表展示点击/注册/下单/转化率/成交金额/成本，支持复制短链与启停切换。
+  - 编码创建后不可修改（与后端 `UpdateTrackingLinkRequest` 不含 `code` 保持一致）。
+
+## 5. 菜单与路由
+
+- `frontend/src/layouts/AdminLayout.tsx`
+  - 运营组新增：`/tracking-links` → 推广追踪（`ad_tracking:manage`）。
+  - 客服组新增：`/manual-entries` 手工录单（`cs_manual_entry:view`）、`/chat-quick-replies` 快捷回复（`chat:view`）。
+  - 系统组新增：`/admin-users` 管理员账号（`admin_user:manage`）。
+  - `sectionMeta` 同步补齐四页标题与描述。
+- `frontend/src/app/AppRouter.tsx`：四个页面均以 `lazy()` 懒加载。
+
+## 6. 只读回归
+
+```text
+前端 http://localhost:5289
+后端 http://127.0.0.1:18089
+Cookie /tmp/jysh-admin-cookie2.txt（HttpOnly + withCredentials）
+```
+
+| 检查项 | 状态 |
+|---|---|
+| `GET /console-jy8k3m/admin-users` | 200 |
+| `GET /console-jy8k3m/manual-entries` | 200 |
+| `GET /console-jy8k3m/chat-quick-replies` | 200 |
+| `GET /console-jy8k3m/tracking-links` | 200 |
+| `GET /api/admin/admin-users?page=1&page_size=5` | 200（含测试站长账号与 `ops` 角色） |
+| `GET /api/admin/manual-entries` | 200（空列表） |
+| `GET /api/admin/manual-entries/options` | 200（平台/操作人均为空） |
+| `GET /api/admin/manual-entries/today-stats` | 200（空数组） |
+| `GET /api/admin/chats/quick-replies` | 200（空数组） |
+| `GET /api/admin/tracking-links` | 200（空列表） |
+| `GET /api/admin/tracking-links/overview` | 200 |
+
+本轮未执行任何创建、修改、删除或密码重置写操作。
+
+## 7. 类型检查与构建
+
+```bash
+cd frontend && npx tsc --noEmit   # 通过
+cd frontend && npm run build      # 通过
+```
+
+构建结果（无超大包告警）：
+
+```text
+dist/assets/index-D8usHbzZ.js             494.74 kB │ gzip: 156.18 kB
+dist/assets/vendor-mobile-eCXS5uji.js     307.07 kB │ gzip: 103.63 kB
+dist/assets/vendor-react-BKj2bk8R.js      282.79 kB │ gzip:  90.00 kB
+dist/assets/Table-BCzDIoX2.js             144.26 kB │ gzip:  47.07 kB
+dist/assets/vendor-antd-icons-CZjfKEFT.js 103.46 kB │ gzip:  30.05 kB
+```
+
+修复项：移除 `AdminManualEntriesPage.tsx` 未使用的 `dayjs` 默认导入、`AdminTrackingLinksPage.tsx` 未使用的 `LinkOutlined`（均为 `TS6133`）。
+
+## 8. 仍未覆盖
+
+- 四个页面的写操作（新建、编辑、删除、重置密码、启停）均未做端到端验证。
+- 手工录单的日期区间筛选依赖后端按北京时间解析，尚未用真实数据验证边界。
+- 推广短链跳转与埋点统计链路未验证（需要真实访问流量）。
@@ -410,12 +410,14 @@ hfb_jysh/

 - 财务看板、资金明细、运营支出。
 - 申诉仲裁、手工订单、提号、客服群、快捷回复。
-  - 已落地：客服群组（`/chat-support-groups`，权限 `chat:manage`），角色权限矩阵（`/roles`，权限 `role:manage`）。
-  - 待落地：手工录单 `/api/admin/manual-entries`、快捷回复 `/api/admin/chats/quick-replies`、推广追踪链接 `/api/admin/tracking-links`。
+  - 已落地：客服群组（`/chat-support-groups`，权限 `chat:manage`），角色权限矩阵（`/roles`，权限 `role:manage`），手工录单（`/manual-entries`，权限 `cs_manual_entry:*`），快捷回复（`/chat-quick-replies`，权限 `chat:view` / `chat:send`）。
+  - 待落地：无（手工录单与快捷回复已迁移完毕）。
 - 分销站点、规则、订单、结算、二维码池、分销用户、公告。
 - 公告、邀请返利、推送、追踪链接。
+  - 已落地：公告管理、邀请返利、推广追踪（`/tracking-links`，权限 `ad_tracking:manage`）。
 - 系统配置、支付配置、备份、管理员管理。
-  - 待落地：管理员账号管理 `/api/admin/admin-users`。
+  - 已落地：系统配置、支付配置、管理员账号（`/admin-users`，权限 `admin_user:manage`）。
+  - 待落地：数据备份管理页。
 - 现有 React 分销后台仅做品牌主题、Logo、登录页、Shell 和文案轻改，不改功能。

 **验收：** 43 个后台页面全部可用，分销后台与主站视觉统一，分销业务流程不变。