# 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. 不存在明文密码查看接口。