hyb-oa/client

hyb-oa Client Runbook (P1-5)

1. 前置条件

• Node.js >= 20
• 后端服务可用（http://127.0.0.1:3000）

2. 安装与启动

cd /home/shunli/Projects/hyb-oa/client
npm install
npm run dev

默认前端地址：http://127.0.0.1:5173

3. 本地联调建议顺序

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. 可用脚本

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：

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

执行：

cd /home/shunli/Projects/hyb-oa/client
npm install
npx playwright install --with-deps
npm run test:e2e

9. 仓库级最小门禁

cd /home/shunli/Projects/hyb-oa
./scripts/check-minimal.sh

说明：

• 会执行 client 的 typecheck/build 与 server 的静态检查。
• 不启动服务，不替代发版前的 server/scripts/regression-all.sh。