wangsli
fc50ffc808
- 新增系统用户管理页（创建/禁用启用/重置密码/角色） - 引入 Playwright E2E：覆盖登录-报销-待办-票据-OCR-支付-登出 - 新增 ci-e2e 工作流（PR + nightly）
119 行
3.7 KiB
Markdown
119 行
3.7 KiB
Markdown
# hyb-oa Client Runbook (P1-5)
|
||
|
||
## 1. 前置条件
|
||
- Node.js >= 20
|
||
- 后端服务可用（`http://127.0.0.1:3000`）
|
||
|
||
## 2. 安装与启动
|
||
```bash
|
||
cd /home/shunli/Projects/hyb-oa/client
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
默认前端地址：`http://127.0.0.1:5173`
|
||
|
||
## 3. 本地联调建议顺序
|
||
```bash
|
||
cd /home/shunli/Projects/hyb-oa
|
||
|
||
docker compose up -d db
|
||
|
||
cd /home/shunli/Projects/hyb-oa/server
|
||
npm run prisma:migrate:deploy
|
||
npm run seed:dev
|
||
npm run dev
|
||
|
||
cd /home/shunli/Projects/hyb-oa/client
|
||
npm run dev
|
||
```
|
||
|
||
## 3.1 试运行/单域托管部署（推荐）
|
||
试运行/上线演练建议使用仓库内置部署包（server 托管 `client/dist`，同域 cookie 更稳定）：
|
||
- `deploy/trialrun/runbook.md`
|
||
- `deploy/trialrun/checklist.md`
|
||
|
||
## 4. 鉴权与会话说明
|
||
- Access Token 仅保存在内存，不写入 `localStorage/sessionStorage`。
|
||
- Refresh Token 由后端通过 HttpOnly Cookie 维护。
|
||
- 前端在 401 时自动调用 `/api/auth/refresh` 并重试一次请求。
|
||
- 登录与刷新请求都会附带 `x-device-fingerprint`。
|
||
|
||
## 4.1 开发环境默认账号（seed:dev）
|
||
仅用于本地联调（`cd server && npm run seed:dev`）：
|
||
|
||
| 角色 | 账号 | 密码 |
|
||
|---|---|---|
|
||
| employee | `[email protected]` | `EmployeePassword1234` |
|
||
| manager | `[email protected]` | `ManagerPassword1234` |
|
||
| finance | `[email protected]` | `FinancePassword1234` |
|
||
| finance_mgr | `[email protected]` | `FinanceMgrPassword1234` |
|
||
| admin | `[email protected]` | `AdminPassword1234` |
|
||
| ceo | `[email protected]` | `CeoPassword1234` |
|
||
|
||
忘记密码：试运行/生产建议采用“管理员重置密码”策略。
|
||
|
||
## 5. 菜单与权限（当前壳层）
|
||
- 仪表盘：登录即可访问。
|
||
- 我的报销：`expense.view_own` 或 `expense.view_all`。
|
||
- 待我处理：`expense.approve`。
|
||
- 票据中心：`invoice.upload` / `invoice.view_own` / `invoice.manage`。
|
||
- 审计工作台：`system.audit.view`（finance_mgr/admin）。
|
||
- 用户管理：`system.users`（hr/admin）。
|
||
- 个人设置：登录即可访问。
|
||
|
||
## 6. 页面现状（P3）
|
||
- 待我处理：列表 + 详情 + `approve/reject/return/transfer` 动作。
|
||
- 我的报销：分页列表 + 详情 + `submit/withdraw/pay` 联调入口。
|
||
- 票据中心：分页列表 + 上传 + OCR 轮询 + 绑定 + 签名预览。
|
||
- 审计工作台：分页筛选已落地。
|
||
|
||
## 7. 状态管理与错误语义
|
||
- 引入 `@tanstack/react-query` 统一查询缓存与失效策略。
|
||
- 错误文案统一映射在 `client/src/api/errorMessages.ts`。
|
||
- API 层保留后端错误码原文，前端仅做可读化。
|
||
|
||
## 6. 风格资源复用策略（锁定）
|
||
- 视觉 Token 来源：`/home/shunli/Projects/hyb-web`。
|
||
- 采用“复制到 client + 单向同步”，不做跨仓软链与自动联动。
|
||
- 如需同步风格，请记录来源 commit 并通过评审。
|
||
|
||
## 8. 可用脚本
|
||
```bash
|
||
npm run dev
|
||
npm run typecheck
|
||
npm run build
|
||
npm run preview
|
||
npm run test:e2e
|
||
```
|
||
|
||
## 8.1 Playwright E2E（E15）
|
||
前置：本地启动 DB + server（建议 `SERVE_CLIENT_DIST=true` 单域托管），并启用 mock OCR：
|
||
```bash
|
||
cd /home/shunli/Projects/hyb-oa
|
||
docker compose up -d db
|
||
|
||
cd /home/shunli/Projects/hyb-oa/server
|
||
OCR_PROVIDER=mock OCR_POLL_CRON="*/5 * * * * *" npm run prisma:migrate:deploy
|
||
OCR_PROVIDER=mock OCR_POLL_CRON="*/5 * * * * *" npm run seed:dev
|
||
OCR_PROVIDER=mock OCR_POLL_CRON="*/5 * * * * *" SERVE_CLIENT_DIST=true npm run dev
|
||
```
|
||
|
||
执行：
|
||
```bash
|
||
cd /home/shunli/Projects/hyb-oa/client
|
||
npm install
|
||
npx playwright install --with-deps
|
||
npm run test:e2e
|
||
```
|
||
|
||
## 9. 仓库级最小门禁
|
||
```bash
|
||
cd /home/shunli/Projects/hyb-oa
|
||
./scripts/check-minimal.sh
|
||
```
|
||
|
||
说明：
|
||
- 会执行 client 的 `typecheck/build` 与 server 的静态检查。
|
||
- 不启动服务，不替代发版前的 `server/scripts/regression-all.sh`。
|