role-user/docs/FULLSTACK_BACKEND_GAP_ANALYSIS.md

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