Initial role user app
This commit is contained in:
湛兮
@@ -0,0 +1,134 @@
|
||||
# role-user C 端员工工作台需求文档
|
||||
|
||||
## 1. 项目定位
|
||||
|
||||
`role-user` 是门店员工使用的 C 端工作台，和现有两个项目形成三端分工：
|
||||
|
||||
| 项目 | 定位 | 主要用户 |
|
||||
| --- | --- | --- |
|
||||
| `access-manage` | 服务端 API、鉴权、权限、门店数据和业务数据 | 所有前端 |
|
||||
| `role-admin` | 管理后台，维护门店、员工、角色、权限和 C 端运营内容 | 超级管理员、管理员、店长 |
|
||||
| `role-user` | 员工端 C 端应用，承载日常工作、通知、任务、排班和个人中心 | 店长、收银员、后厨、兼职 |
|
||||
|
||||
本项目不是另一个管理后台，也不是顾客下单端。第一版正式产品应聚焦“员工每天打开后能完成门店日常工作”。
|
||||
|
||||
## 2. 用户角色
|
||||
|
||||
| 角色 | 典型职责 | C 端能力 |
|
||||
| --- | --- | --- |
|
||||
| 店长 `store_manager` | 管理本店员工、查看门店任务和公告 | 查看本店员工、处理门店任务、查看排班和公告 |
|
||||
| 收银员 `cashier` | 收银、核对订单、基础会员操作 | 查看个人任务、公告、排班和门店信息 |
|
||||
| 后厨 `kitchen` | 出品、备货、库存协作 | 查看后厨任务、公告、排班 |
|
||||
| 兼职 `part_time` | 临时排班和基础任务 | 查看个人任务、排班、公告 |
|
||||
| 管理员 `admin` | 管理多门店业务 | 默认走 `role-admin`，如进入 C 端则展示员工视角 |
|
||||
|
||||
## 3. 功能范围
|
||||
|
||||
### 3.1 登录与会话
|
||||
|
||||
- 员工使用手机号和密码登录。
|
||||
- 登录接口走 `POST /api/auth/employee/login`。
|
||||
- 登录成功后读取 `GET /api/auth/me` 和 `GET /api/permissions/me`。
|
||||
- Next.js BFF 负责保存服务端会话，前端不直接把 JWT 放进 `localStorage`。
|
||||
- 后端没有 refresh token 时，401 直接清理会话并跳回登录页。
|
||||
|
||||
### 3.2 工作台首页
|
||||
|
||||
首页用于高频扫描，不做营销页：
|
||||
|
||||
- 今日身份卡：员工姓名、所属门店、角色、账号状态。
|
||||
- 今日排班：当前班次、上下班时间、岗位。
|
||||
- 待办任务：未完成、即将超时、已逾期数量和列表入口。
|
||||
- 最新公告：未读公告摘要。
|
||||
- 快捷入口：任务、排班、门店、我的。
|
||||
|
||||
### 3.3 公告中心
|
||||
|
||||
- 展示管理员或店长发布给当前员工、角色或门店的公告。
|
||||
- 支持未读、已读筛选。
|
||||
- 进入公告详情后标记已读。
|
||||
- 重要公告需要在首页突出显示。
|
||||
|
||||
### 3.4 任务中心
|
||||
|
||||
- 展示分配给当前员工或当前门店的任务。
|
||||
- 状态：待处理、处理中、已完成、已取消。
|
||||
- 支持按状态、截止时间筛选。
|
||||
- 员工可以更新自己的任务状态并填写处理备注。
|
||||
- 店长可以查看本店任务汇总；跨店管理仍放在后台。
|
||||
|
||||
### 3.5 排班
|
||||
|
||||
- 展示个人本周/本月排班。
|
||||
- 支持今日班次和未来班次。
|
||||
- 第一版只做查看，不做员工端自行换班。
|
||||
|
||||
### 3.6 门店信息
|
||||
|
||||
- 展示当前门店名称、地址、电话、状态。
|
||||
- 店长或有 `employee:view:store` 权限的员工可查看本店员工列表。
|
||||
- 不在 C 端提供门店新增、删除、角色分配等后台能力。
|
||||
|
||||
### 3.7 我的
|
||||
|
||||
- 展示个人资料、手机号、门店、角色、最近登录时间。
|
||||
- 支持修改自己的登录密码：旧密码 + 新密码。
|
||||
- 支持退出登录。
|
||||
- 不支持查看任何人的明文密码。
|
||||
|
||||
## 4. 密码与凭据安全要求
|
||||
|
||||
用户提出“超级管理员与管理员需要支持查看自身和下级用户密码”。正式实现不做明文密码展示，原因：
|
||||
|
||||
- 当前后端只保存 `password_hash`，技术上无法反查原密码。
|
||||
- 如果为了展示密码而保存明文或可逆密文，会扩大泄露面，不适合作为正式产品默认能力。
|
||||
|
||||
正式替代方案：
|
||||
|
||||
- 后台提供“重置下级用户密码”。
|
||||
- 重置后生成一次性临时密码，只在本次响应和后台弹窗中显示一次。
|
||||
- 员工下次登录后应被要求修改密码。
|
||||
- 所有密码重置行为写入审计日志：操作者、目标用户、时间、IP、User-Agent、原因。
|
||||
- 本人密码只支持“修改密码”，不支持“查看当前密码”。
|
||||
|
||||
## 5. 信息架构
|
||||
|
||||
底部导航：
|
||||
|
||||
| 路由 | 页面 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `/dashboard` | 工作台 | 默认首页 |
|
||||
| `/tasks` | 任务 | 个人和本店任务 |
|
||||
| `/schedule` | 排班 | 个人排班 |
|
||||
| `/announcements` | 公告 | 公告列表和详情 |
|
||||
| `/me` | 我的 | 个人资料、改密、退出 |
|
||||
|
||||
辅助路由：
|
||||
|
||||
| 路由 | 页面 |
|
||||
| --- | --- |
|
||||
| `/login` | 登录 |
|
||||
| `/store` | 当前门店 |
|
||||
| `/tasks/:id` | 任务详情 |
|
||||
| `/announcements/:id` | 公告详情 |
|
||||
|
||||
## 6. 技术要求
|
||||
|
||||
- 使用 Next.js App Router、React、TypeScript。
|
||||
- 移动优先，支持 PWA 安装。
|
||||
- 使用 Server Components 承载只读数据首屏，交互表单使用 Client Components。
|
||||
- 使用 Route Handlers 做 BFF：`role-user` 调自己的 `/api/*`，BFF 再访问 `access-manage`。
|
||||
- 会话 token 通过 HttpOnly Cookie 保存。
|
||||
- 服务端请求用户态接口时禁用共享缓存。
|
||||
- 首页独立数据并行请求，避免瀑布。
|
||||
- API 类型集中维护，不在组件里散落接口路径。
|
||||
|
||||
## 7. 验收标准
|
||||
|
||||
- 员工可以使用手机号和密码登录。
|
||||
- 登录后能看到自己的门店、角色、权限和基础信息。
|
||||
- 底部导航在移动端可用，桌面端布局不破。
|
||||
- 401 后清理会话并回到登录页。
|
||||
- 密码不会出现在前端持久化存储中。
|
||||
- 没有任何明文密码查询或展示接口。
|
||||
- 管理后台重置出的临时密码仅显示一次，并有审计记录。
|
||||
@@ -0,0 +1,209 @@
|
||||
# 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. 不存在明文密码查看接口。
|
||||
Reference in New Issue
Block a user