wangsli和Claude Sonnet 5
cd01e4bf28
10-05 到期例外清单里已设计好的首批 4 个具体调用，现予落码（原方案见 implement.md §14「首批具体分支与验证要求」）： - ap_operations.feature_disabled（409）：AP 台账/明细查询功能关闭 - ap_operations.query_invalid（400）：AP 台账查询参数校验失败 - todo.feature_disabled（409）：待办功能关闭 - portal.feature_disabled（409）：工作台首页功能关闭 四处均改为调用 buildBusinessValidationError(reasonCode, details, statusCode)， 保留原 HTTP 状态码、featureFlag/reason 等既有 details 字段不变，仅新增精确 reasonCode；不改功能开关判断逻辑、不改权限校验顺序。 - server/src/constants/errorReasons.js + client/src/api/errorReasons.ts： 注册 4 条原因码及中文文案，服务端/客户端逐字一致。 - scripts/qa/error-reason-legacy-baseline.json：移除这 4 条已迁移的旧例外 记录（591 → 587），check-error-reason-contract.mjs 主检查与 self-test 均 PASS，无 new_legacy/stale_exception/unregistered_reason。 - apOperations.permissions.test.js：扩展"功能关闭"断言校验 reasonCode 与 原 details 字段共存；新增"查询参数非法（功能开启）"400 用例，断言零 台账业务查询；新增"合法查询仍 200"用例。 - portal.test.js：新增工作台关闭时 409+reasonCode+零业务查询断言（此前 完全没有覆盖这条路径）。 - todos.test.js：新建（此前 todos 路由零测试覆盖），聚焦 ensureFeatureEnabled 网关：关闭时 GET/POST 均 409+reasonCode+零 todoItem 查询；开启时正常放行。 验证：server 5 个相关测试文件 286/286 通过；client typecheck/build 通过； check-ui-design-rules.mjs --strict、check-trellis-governance.mjs、 git diff --check 通过。routes/ 全量回归 872/874（2 个失败为 paymentBatches BIFF8 导出的既有环境问题，已用 git stash 验证在改动前的 HEAD 上同样失败， 与本次改动无关，不在本次范围内处理）。 剩余 669 条例外记录不变，尚未处理；B/C 两档 57 文件仍需逐模块确认迁移或 提出延期理由，本次不扩大范围。 Co-Authored-By: Claude Sonnet 5 <[email protected]>
hyb-oa Client Runbook (P1-5)
1. 前置条件
- Node.js
>=22 <23 - 后端服务可用（
http://127.0.0.1:3000）
2. 安装与启动
cd client
npm install
npm run dev
默认前端地址：http://127.0.0.1:5173
3. 本地联调建议顺序
cd ..
export POSTGRES_PASSWORD="<local-only-db-password>"
export JWT_SECRET="<local-only-jwt-secret>"
docker compose up -d db
cd server
npm run prisma:migrate:deploy
SEED_DEV_ALLOW=1 SEED_DEV_DATABASE_CONFIRM=hyb_oa npm run seed:dev
npm run dev
cd ../client
npm run dev
根级 Compose 要求显式提供本地数据库口令和 JWT 密钥；不要把真实值写入仓库，并让 server/.env 的 DATABASE_URL 使用同一数据库口令。
3.1 试运行/单域托管部署（推荐）
试运行/上线演练建议使用仓库内置部署包（server 托管 client/dist，同域 cookie 更稳定）：
deploy/trialrun/runbook.mddeploy/trialrun/checklist.md
4. 鉴权与会话说明
- Access Token 仅保存在内存，不写入
localStorage/sessionStorage。 - Refresh Token 由后端通过 HttpOnly Cookie 维护。
- 前端在 401 时自动调用
/api/auth/refresh并重试一次请求。 - 登录与刷新请求都会附带
x-device-fingerprint。
4.1 开发账号（seed:dev）
seed:dev 仅用于本机开发库，必须显式允许并确认数据库名；账号与口令以本地受控 SEED_* 配置为准，脚本不输出口令。默认不会覆盖已有账号密码；新建账号和主动设置 SEED_DEV_RESET_PASSWORDS=1 后轮换的账号，首次登录都必须改密。
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 来源：
<design-source-repo>。 - 采用“复制到 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 ..
docker compose up -d db
cd server
OCR_PROVIDER=mock OCR_POLL_CRON="*/5 * * * * *" npm run prisma:migrate:deploy
SEED_DEV_ALLOW=1 SEED_DEV_DATABASE_CONFIRM=hyb_oa 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 ../client
npm install
npx playwright install --with-deps
npm run test:e2e
9. 仓库级最小门禁
cd ..
./scripts/check-minimal.sh
说明：
- 会执行 client 的
typecheck/build与 server 的静态检查。 - 不启动服务，不替代发版前的
server/scripts/regression-all.sh。