湛兮
210 lines
7.1 KiB
Markdown
210 lines
7.1 KiB
Markdown
# C 端员工工作台三端缺口分析
|
||
|
||
生成时间：2026-06-01
|
||
|
||
## 1. 结论
|
||
|
||
当前三端已经开始围绕 C 端员工工作台建设，但还没有完全闭环。
|
||
|
||
| 端 | 项目 | 当前状态 | 是否需要改 |
|
||
| --- | --- | --- | --- |
|
||
| 后端 | `access-manage` | 已新增公告、任务、排班、移动端、凭据审计模块，但首屏聚合、审计筛选、部分数据字段和业务校验还缺 | 是 |
|
||
| 后台 | `role-admin` | 已新增公告、任务、排班、凭据审计页面，但 API 类型仍按早期命名设计，和后端正式字段不一致 | 是 |
|
||
| 前台 | `role-user` | 已有移动端页面、BFF 和空态，但缺任务/公告详情、任务操作、改密表单、门店详情和首屏聚合字段消费完善 | 是 |
|
||
|
||
优先级建议：
|
||
|
||
1. 先补齐 `access-manage` 合同，保证 API 返回稳定。
|
||
2. 再修正 `role-admin` API 适配，保证运营内容能创建出来。
|
||
3. 最后完善 `role-user` 的员工端交互，消费这些正式接口。
|
||
|
||
## 2. 后端缺口
|
||
|
||
### 2.1 首屏聚合 `/api/mobile/bootstrap` 数据不足
|
||
|
||
现状：
|
||
|
||
- 已返回 `user`、`store`、`permissions`、`counters.unreadAnnouncementCount`、`counters.pendingTaskCount`、`todayShifts`。
|
||
- 没有返回首页需要直接展示的 `latestAnnouncements`、`tasks`。
|
||
- 没有返回 `overdueTaskCount`。
|
||
- `todayShifts` 是数组，员工端当前兼容数组，但接口语义应明确。
|
||
|
||
建议：
|
||
|
||
- 增加最近公告列表，最多 3 条。
|
||
- 增加待办任务列表，最多 5 条。
|
||
- 增加逾期任务数量。
|
||
- 明确返回 `todayShift` 或 `todayShifts`，前端统一消费。
|
||
|
||
### 2.2 凭据审计接口筛选和字段不完整
|
||
|
||
现状：
|
||
|
||
- `GET /api/admin/credential-audits` schema 只接收 `targetEmployeeId`、`page`、`pageSize`。
|
||
- `role-admin` 页面已经提交 `operatorId`、`storeId`、`startDate`、`endDate`，但后端没有完整接收。
|
||
- 返回值缺 `targetEmployeePhone`、`storeName`，后台页面正在展示这些字段。
|
||
|
||
建议：
|
||
|
||
- 后端 query schema 增加 `operatorId`、`storeId`、`startDate`、`endDate`。
|
||
- repository join `stores`，返回目标员工手机号和门店名。
|
||
- 明确操作者筛选对超级管理员和员工操作者的匹配规则。
|
||
|
||
### 2.3 后台运营字段合同与 `role-admin` 不一致
|
||
|
||
后端当前正式字段：
|
||
|
||
- 公告：`level`、`targetType`、`targets`。
|
||
- 任务：`dueAt`、`assignees`、`CANCELLED`。
|
||
- 排班：`roleName`、`CANCELLED`。
|
||
- 凭据审计：`actorName`、`createdAt`。
|
||
|
||
`role-admin` 当前字段：
|
||
|
||
- 公告：`importance`、`targetScope`、`targetStoreIds`、`targetRoleIds`、`targetEmployeeIds`。
|
||
- 任务：`deadlineAt`、`assigneeIds`、`assigneeNames`、`CANCELED`。
|
||
- 排班：`position`、`CANCELED`、`COMPLETED`。
|
||
- 凭据审计：`operatorName`、`operatedAt`、`targetEmployeePhone`、`storeName`。
|
||
|
||
建议：
|
||
|
||
- 优先在 `role-admin/src/api/access.ts` 做请求/响应适配，避免改动多个页面。
|
||
- 后端只补真正缺失的字段和筛选，不为了旧前端命名反向污染 API。
|
||
|
||
### 2.4 任务业务闭环还需加强
|
||
|
||
现状：
|
||
|
||
- 后台任务创建要求 `assigneeIds` 至少 1 个。
|
||
- C 端只能查到分配给自己的任务。
|
||
- 需求文档提到“个人和门店任务”，但后端还没有店铺级任务被所有本店员工可见的明确规则。
|
||
|
||
建议：
|
||
|
||
- 第一版若只做员工分配任务，应更新文档说明。
|
||
- 若要支持门店任务，需要允许 `assigneeIds` 为空，并把 `store_id` 命中的本店任务纳入 `/api/mobile/tasks`。
|
||
|
||
### 2.5 排班冲突校验缺失
|
||
|
||
现状：
|
||
|
||
- 已校验员工属于门店、结束时间晚于开始时间。
|
||
- 需求文档要求“同一员工同一时间段不能重复排班”，后端还没有冲突检测。
|
||
|
||
建议：
|
||
|
||
- `create` 和 `update` 时检测同一员工未取消班次时间段重叠。
|
||
- 更新时排除当前排班 ID。
|
||
|
||
### 2.6 文档与实现需要同步
|
||
|
||
现状：
|
||
|
||
- `access-manage/docs/API.md` 已写入新增接口，但部分字段仍偏概要。
|
||
- `docs/ROLE_USER_BACKEND_REQUIREMENTS.md` 是目标合同，未标注当前缺口状态。
|
||
|
||
建议：
|
||
|
||
- 后端实现完成后补充 `bootstrap` 响应示例。
|
||
- 补充凭据审计筛选参数和返回字段。
|
||
|
||
## 3. 后台改动范围
|
||
|
||
项目：`/Users/mac033/Desktop/my-project/role-admin`
|
||
|
||
需要改：
|
||
|
||
- `src/api/access.ts`
|
||
- 把公告表单字段转换为后端 `level`、`targetType`、`targets`。
|
||
- 把后端公告返回转换为页面使用的 `importance`、`targetScope`、目标 ID 数组。
|
||
- 把任务 `deadlineAt` 转为 `dueAt`，`assignees` 转为 `assigneeIds` 和 `assigneeNames`。
|
||
- 统一 `CANCELLED` 与页面当前 `CANCELED` 的枚举。
|
||
- 把排班 `position` 转为 `roleName`。
|
||
- 把凭据审计 `actorName/createdAt` 转为 `operatorName/operatedAt`，并接收新增字段。
|
||
- 视图页面只在必要时微调，优先不大面积重写。
|
||
- `README.md` 同步新增模块和接口适配说明。
|
||
|
||
## 4. 前台改动范围
|
||
|
||
项目：`/Users/mac033/Desktop/my-project/role-user`
|
||
|
||
需要改：
|
||
|
||
- `src/lib/mobile-data.ts`
|
||
- 适配后端正式 `bootstrap` 的最新公告、任务、逾期数。
|
||
- 明确 `todayShift/todayShifts` 消费策略。
|
||
- BFF Route Handlers
|
||
- 增加公告详情、标记已读。
|
||
- 增加任务详情、开始、完成、备注。
|
||
- 增加本人修改密码。
|
||
- 可选：当前门店详情和本店员工列表代理。
|
||
- 页面
|
||
- `/announcements/:id` 公告详情并标记已读。
|
||
- `/tasks/:id` 任务详情、开始、完成、备注。
|
||
- `/me` 改密表单。
|
||
- `/store` 接入门店地址、电话和本店员工列表。
|
||
|
||
## 5. 拆分给子进程的任务
|
||
|
||
### 子进程 A：后端 `access-manage`
|
||
|
||
目标：
|
||
|
||
- 补齐 `mobile/bootstrap` 的首页数据。
|
||
- 补齐凭据审计筛选和返回字段。
|
||
- 增加排班冲突校验。
|
||
- 根据选择决定是否支持门店级任务。
|
||
- 更新 `docs/API.md`。
|
||
|
||
写入范围：
|
||
|
||
- `src/modules/mobile/*`
|
||
- `src/modules/tasks/*`
|
||
- `src/modules/shifts/*`
|
||
- `src/modules/credentials/*`
|
||
- `docs/API.md`
|
||
- 必要时新增迁移，但优先复用现有表结构。
|
||
|
||
### 子进程 B：后台 `role-admin`
|
||
|
||
目标：
|
||
|
||
- 修正 `src/api/access.ts` 与后端正式合同的字段适配。
|
||
- 保持页面现有交互不大改。
|
||
- 修正枚举值和凭据审计展示。
|
||
- 更新 `README.md`。
|
||
|
||
写入范围：
|
||
|
||
- `src/api/access.ts`
|
||
- 必要时 `src/views/announcements/index.vue`
|
||
- 必要时 `src/views/tasks/index.vue`
|
||
- 必要时 `src/views/shifts/index.vue`
|
||
- 必要时 `src/views/credential-audits/index.vue`
|
||
- `README.md`
|
||
|
||
### 子进程 C：前台 `role-user`
|
||
|
||
目标：
|
||
|
||
- 完成员工端详情和操作闭环。
|
||
- 接入本人修改密码。
|
||
- 接入门店详情和本店员工列表。
|
||
- 更新 `README.md`。
|
||
|
||
写入范围：
|
||
|
||
- `src/lib/*`
|
||
- `src/app/api/*`
|
||
- `src/app/(app)/*`
|
||
- `src/components/*`
|
||
- `README.md`
|
||
|
||
## 6. 验收顺序
|
||
|
||
1. 后端 `pnpm typecheck` 或现有检查命令通过。
|
||
2. 后台能用超级管理员创建公告、任务、排班，重置密码并看到审计。
|
||
3. 前台员工登录后能看到首页列表数据，进入详情并完成任务/公告操作。
|
||
4. 401 会清理员工端会话，不在浏览器存储 JWT 或密码。
|
||
5. 不存在明文密码查看接口。
|