role-user/docs/C_EMPLOYEE_APP_REQUIREMENTS.md

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 后清理会话并回到登录页。
• 密码不会出现在前端持久化存储中。
• 没有任何明文密码查询或展示接口。
• 管理后台重置出的临时密码仅显示一次，并有审计记录。