Initial role user app

2026-06-02 14:46:39 +08:00
commit 003dc60111
62 changed files with 7835 additions and 0 deletions
@@ -0,0 +1,100 @@
+# role-user
+
+员工端 C 端工作台，基于 `access-manage` 后端和 `role-admin` 管理后台建设。
+
+当前已搭建 React + Next.js App Router + TypeScript 前端骨架，采用移动优先、PWA 友好的工作台形态。
+
+## 启动
+
+```bash
+pnpm install
+cp .env.example .env.local
+pnpm dev
+```
+
+默认访问：
+
+- 登录页：http://localhost:3210/login
+- 工作台：http://localhost:3210/dashboard
+- 任务：http://localhost:3210/tasks
+- 排班：http://localhost:3210/schedule
+- 公告：http://localhost:3210/announcements
+- 门店：http://localhost:3210/store
+- 我的：http://localhost:3210/me
+
+## 环境变量
+
+```bash
+ACCESS_MANAGE_API_BASE_URL=http://localhost:3500/api
+ROLE_USER_SESSION_COOKIE=role_user_session
+```
+
+`ACCESS_MANAGE_API_BASE_URL` 指向 `access-manage` 服务端 API 根路径。员工登录会调用后端 `POST /api/auth/employee/login`，登录成功后只把 JWT 写入 Next.js 服务端 HttpOnly Cookie，不写入 `localStorage`。
+
+## 可用命令
+
+```bash
+pnpm dev
+pnpm typecheck
+pnpm lint
+pnpm build
+```
+
+## 当前实现范围
+
+- Next.js App Router 项目结构、TypeScript、ESLint、`@/*` 路径别名和基础样式。
+- BFF Route Handlers：
+  - `POST /api/auth/login`
+  - `POST|GET /api/auth/logout`
+  - `GET /api/auth/me`
+  - `PATCH /api/auth/me/password`
+  - `GET /api/permissions/me`
+  - `GET /api/mobile/tasks`
+  - `GET /api/mobile/tasks/:id`
+  - `POST /api/mobile/tasks/:id/start`
+  - `POST /api/mobile/tasks/:id/complete`
+  - `POST /api/mobile/tasks/:id/comment`
+  - `GET /api/mobile/announcements`
+  - `GET /api/mobile/announcements/:id`
+  - `POST /api/mobile/announcements/:id/read`
+  - `GET /api/mobile/shifts`
+  - `GET /api/mobile/shifts/today`
+  - `GET /api/mobile/store`
+  - `GET /api/mobile/store/employees`
+- 页面：
+  - `/login`
+  - `/dashboard`
+  - `/tasks`
+  - `/tasks/:id`
+  - `/schedule`
+  - `/announcements`
+  - `/announcements/:id`
+  - `/store`
+  - `/me`
+- 首页已消费正式 `mobile/bootstrap` 的 `latestAnnouncements`、`tasks`、`overdueTaskCount`、`todayShift/todayShifts`。
+- `/announcements` 支持全部、未读、已读筛选；公告详情进入后通过 BFF 标记已读。
+- `/tasks` 支持全部、待处理、处理中、已完成筛选；任务详情支持开始、完成和追加备注。
+- `/schedule` 支持今日、未来、全部排班筛选。
+- `/me` 已接入本人修改密码表单，前端不持久化密码或 token。
+- `/dashboard`、`/tasks`、`/announcements`、`/schedule` 会在后端临时不可用或 5xx 时保持基础资料和业务空态。
+- `/store` 会尝试读取当前门店详情和本店员工列表；后端权限或接口不可用时保持门店基础信息和空态。
+- 移动端底部导航、加载态、空态、会话缺失跳登录、401 清理 Cookie 的服务端路径。
+- PWA manifest、应用图标、基础 service worker、安全响应头和参照 SeaCloud 的移动端工作台视觉系统。
+
+## 文档
+
+- `docs/C_EMPLOYEE_APP_REQUIREMENTS.md`: C 端员工工作台需求文档。
+- `docs/FULLSTACK_BACKEND_GAP_ANALYSIS.md`: C 端员工工作台三端缺口与改动范围分析。
+- `RTK.md`: 本项目 Codex/Agent 协作规则。
+
+## 关联项目
+
+- `/Users/mac033/Desktop/my-project/access-manage`: 服务端 API。
+- `/Users/mac033/Desktop/my-project/role-admin`: 管理后台。
+
+## 安全边界
+
+- 不展示任何明文密码。
+- 不把密码、JWT 或权限 token 持久化到前端存储。
+- 员工端修改密码已通过 BFF 接入后端 `PATCH /api/auth/me/password`。
+- 公告、任务、排班已按正式后端接口接入列表、筛选、详情和员工端操作；后端临时不可用时页面保留业务空态。