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