文件

T

wangsli dff1aabc26 feat(server): 完成 F19~F19d pg-boss 作业系统迁移\n\n- 引入 pg-boss（JOB_DRIVER=pgboss）并保留 cron 回滚\n- OCR/委派回收/超期归档改由 pg-boss schedule + work 执行\n- OCR_PROVIDER=off 自动 unschedule ocr.tick\n- 更新 trialrun env/compose/runbook 与 README，并推进 CSV 状态为 DONE

2026-02-09 20:05:01 +08:00

postman

feat(server): 完成 P0+P1 后端能力（工作流、RBAC、付款归档）

2026-02-07 16:43:31 +08:00

prisma

feat(server): 站内通知基础设施与关键事件触发(F14,F30)

2026-02-09 17:45:17 +08:00

scripts

feat(server): 票据增强闭环（F9/F10/F11/F12/F13/F28）

2026-02-09 17:09:34 +08:00

src

feat(server): 完成 F19~F19d pg-boss 作业系统迁移\n\n- 引入 pg-boss（JOB_DRIVER=pgboss）并保留 cron 回滚\n- OCR/委派回收/超期归档改由 pg-boss schedule + work 执行\n- OCR_PROVIDER=off 自动 unschedule ocr.tick\n- 更新 trialrun env/compose/runbook 与 README，并推进 CSV 状态为 DONE

2026-02-09 20:05:01 +08:00

.env.example

feat(server): 票据增强闭环（F9/F10/F11/F12/F13/F28）

2026-02-09 17:09:34 +08:00

package-lock.json

2026-02-09 20:05:01 +08:00

package.json

2026-02-09 20:05:01 +08:00

prisma.config.ts

feat(server): 完成 P0+P1 后端能力（工作流、RBAC、付款归档）

2026-02-07 16:43:31 +08:00

README.md

2026-02-09 20:05:01 +08:00

README.md

hyb-oa Server Runbook (P0/P1)

1. 环境准备

Node.js: >=20
Docker + Docker Compose
本地工具：curl、jq
配置文件：从 server/.env.example 复制为 server/.env 并按需修改

cd /home/shunli/Projects/hyb-oa/server
cp .env.example .env

2. Gate 基线命令（必须顺序执行）

2.1 启动数据库

cd /home/shunli/Projects/hyb-oa
docker compose up -d db

2.2 应用迁移

cd /home/shunli/Projects/hyb-oa/server
npm run prisma:migrate:deploy

2.3 执行 seed（幂等）

cd /home/shunli/Projects/hyb-oa/server
npm run seed:dev

开发环境默认账号（仅用于本地 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

说明：

以上账号可通过 SEED_* 环境变量覆盖（见 server/src/scripts/seed-dev.js）。
生产/试运行环境默认采用“管理员重置密码”，不建议启用默认弱口令。

试运行管理员引导（E20）：

cd /home/shunli/Projects/hyb-oa/server
TRIALRUN_ADMIN_EMAIL="[email protected]" \
TRIALRUN_ADMIN_PHONE="13800000000" \
TRIALRUN_ADMIN_PASSWORD="" \
npm run seed:trialrun

说明：

TRIALRUN_ADMIN_PASSWORD 为空时会生成并打印一次性口令（请立刻保存）。
若管理员已存在，脚本只确保其为 active 且具备 admin+employee 角色，不会改动密码。

2.3.1 认证安全说明（P5）

POST /api/auth/login 成功响应包含 mustChangePassword：
- true：表示该账号处于“首次登录/管理员重置密码后”状态；前端应强制引导改密后再进入业务页。
- 改密接口：POST /api/auth/change-password（需要 authorization: Bearer <token> + x-device-fingerprint）。
登录失败锁定（默认）：
- 15 分钟内失败 5 次会锁定 30 分钟，返回 423 AUTH_002（含 lockedUntil）。
- 解锁：POST /api/users/:id/unlock（权限：system.users）。
弱密码拦截：
- 采用 zxcvbn 评分，默认 score < 2 拒绝（返回 VALID_001.details.password）。
可通过 WEAK_PASSWORD_CHECK_ENABLED=false 关闭（不建议生产关闭）。

2.3.2 邮件通知（可选，F15）

默认关闭：EMAIL_ENABLED=false
开启后支持触发邮件（失败降级不阻塞主流程）：
- 新待办分配（workflow.task_assigned）
- 审批结果（approved/rejected/returned）
- 付款完成（reimbursement.paid）
- 密码重置（forgot-password / reset-password）
需要配置 SMTP：
- SMTP_HOST、SMTP_PORT（默认 587）、SMTP_SECURE（465 通常为 true）
- SMTP_USER、SMTP_PASS（按 SMTP 服务要求）
- EMAIL_FROM（发件人地址）
- EMAIL_BASE_URL（可选，邮件内“查看详情”链接的站点前缀；为空则尝试使用 APP_ORIGIN 的第一个值）

2.3.3 作业系统（cron vs pg-boss）（F19~F19d）

默认：JOB_DRIVER=cron（同进程 node-cron 调度）
可选升级：JOB_DRIVER=pgboss（Postgres 队列，适配单机/多进程；避免引入 Redis）
- PG_BOSS_SCHEMA（默认 pgboss）
- JOBS_ENABLED=false 可整体关闭作业（仅用于排障/紧急回滚）
目前迁移的作业：
- ocr.tick（受 OCR_PROVIDER 控制，off 时不调度）
- delegation.revoke-expired
- invoice.archive-unused
回滚策略：
- 将 JOB_DRIVER 切回 cron（无需 schema 迁移回滚，风险低）

2.4 启动服务

cd /home/shunli/Projects/hyb-oa/server
npm run dev

2.5 冒烟验证

cd /home/shunli/Projects/hyb-oa/server
./scripts/smoke-test.sh

2.6 本地最小门禁（P1-b）

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

说明：

该脚本只做静态/构建级门禁，不启动服务与数据库。
全量回归仍通过 server/scripts/regression-all.sh 执行。

3. 1 分钟快速验证

cd /home/shunli/Projects/hyb-oa/server
./scripts/smoke-test.sh

也可直接探活：

curl -fsS http://127.0.0.1:3000/health
curl -fsS http://127.0.0.1:3000/ready

说明：

/health：liveness（不查 DB）
/ready：readiness（SELECT 1 探活 DB，失败返回 503）

4. 回归入口

4.1 脚本回归（推荐）

cd /home/shunli/Projects/hyb-oa/server
BASE_URL=http://127.0.0.1:3000 ./scripts/smoke-test.sh

4.2 判重专项回归（dedup）

cd /home/shunli/Projects/hyb-oa/server
DATABASE_URL='postgresql://hyboa_user:[email protected]:5432/hyb_oa?schema=public' \
BASE_URL=http://127.0.0.1:3000 ./scripts/regression-dedup.sh

4.3 工作流动作回归

cd /home/shunli/Projects/hyb-oa/server
./scripts/regression-workflow-actions.sh

可选并发校验：

cd /home/shunli/Projects/hyb-oa/server
RUN_DELEGATION_CONCURRENCY_CHECK=1 ./scripts/regression-workflow-actions.sh

覆盖场景：

reject：实例=rejected，报销=rejected
return：实例=terminated，报销=draft
withdraw：审批未处理前可撤回
return 后二次 submit：创建新实例
PERM_002：非 assignee 无法操作
no_actionable_approver：全链无可执行审批人阻断
negative_not_allowed：负金额防御
manager skip：直属上级缺失时跳过并记录
transfer：转审成功（任务改派 + 任务/转审记录/history 三处证据）
transfer 参数校验：reason<10 返回 VALID_002
transfer 同人转审：返回 VALID_001（same_assignee_not_allowed）
transfer 链路上限：同 task 第 4 次转审阻断（chain_limit_exceeded）
transfer 目标校验：目标审批人须 active 且具备 expense.approve
pay：财务付款成功（approved -> paid，发票 bound -> archived(used_complete)）
pay 权限：非财务返回 PERM_001
pay 状态校验：非 approved/paid 返回 VALID_001
pay 幂等：重复付款返回 200（archivedInvoiceCount 可为 0）
pay 幂等冲突：已付款后提交冲突凭证字段返回 409 VALID_001（already_paid_conflict）
delegation：有效期内可代办并在 history 写入 delegation 证据
delegation 过期：代理人返回 PERM_002，自动回收任务可撤销过期委派
delegation 并发回收（可选）：RUN_DELEGATION_CONCURRENCY_CHECK=1 时双并发只回收一次并仅写一条自动回收审计

4.4 一键全量回归

cd /home/shunli/Projects/hyb-oa/server
./scripts/regression-all.sh

串联 smoke-test.sh + regression-dedup.sh + regression-workflow-actions.sh + regression-audit.sh + regression-ocr.sh，适用于 CI 或发版前检查。

可选关闭审计/OCR：

cd /home/shunli/Projects/hyb-oa/server
RUN_AUDIT_REGRESSION=0 RUN_OCR_REGRESSION=0 ./scripts/regression-all.sh

可选打开组织/配置回归（org + settings）：

cd /home/shunli/Projects/hyb-oa/server
RUN_ORG_SETTINGS_REGRESSION=1 ./scripts/regression-all.sh

可选打开认证安全回归（auth security）：

cd /home/shunli/Projects/hyb-oa/server
RUN_AUTH_SECURITY_REGRESSION=1 ./scripts/regression-all.sh

独立执行：

cd /home/shunli/Projects/hyb-oa/server
./scripts/regression-audit.sh
OCR_PROVIDER=mock ./scripts/regression-ocr.sh
./scripts/regression-org-settings.sh
./scripts/regression-auth-security.sh

4.5 Postman 回归

Collection: server/postman/hyb-oa.postman_collection.json
Environment: server/postman/hyb-oa.postman_environment.json
核心链路：
1. Login Employee
2. Create Reimbursement
3. Upload Invoice
4. Bind Invoice
5. Submit Reimbursement
6. Login CEO
7. Approve Workflow Task
8. Get Signed URL

4.6 前端壳联调（P1-5）

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

说明：

前端开发地址默认 http://127.0.0.1:5173。
通过 Vite 代理将 /api 转发到 http://127.0.0.1:3000。
Access Token 仅保存在内存，Refresh Token 通过 HttpOnly Cookie 续签。

4.7 单域托管 client/dist（可选，试运行建议）

cd /home/shunli/Projects/hyb-oa/client
npm run build

cd /home/shunli/Projects/hyb-oa/server
SERVE_CLIENT_DIST=true npm run dev

说明：

访问 http://127.0.0.1:3000 即可打开前端（同域 cookie，减少 CORS 复杂度）。
SPA 路由（如 /dashboard）会回退到 index.html；/api/* 不参与回退。

4.8 试运行部署包（Docker Compose）

试运行/上线演练建议使用仓库内置部署包：

deploy/trialrun/runbook.md
deploy/trialrun/docker-compose.yml
deploy/trialrun/.env.example
deploy/trialrun/checklist.md

备份/恢复脚本（E14）：

cd /home/shunli/Projects/hyb-oa
./scripts/backup-db.sh
./scripts/restore-db.sh deploy/trialrun/backups/<db.dump>
./scripts/backup-storage.sh
./scripts/restore-storage.sh deploy/trialrun/backups/<storage.tar.gz> deploy/trialrun/data/storage

优雅停机（E21）：

docker stop / Ctrl+C 会触发 SIGTERM/SIGINT，server 会调用 app.close() 完成收敛关闭（定时任务/HTTP/DB）。

5. P2 API 摘要

5.1 付款标记（pay）

POST /api/reimbursements/:id/pay
权限：expense.finance.pay
可选请求体：paymentVoucherNo、paymentDate(YYYY-MM-DD)、paymentChannel(bank/alipay/wechat/cash/other)
语义：
- approved -> paid：返回 200，并归档关联 bound 发票
- 已 paid 重复同值：返回 200（payment.idempotent=true）
- 已 paid 重复冲突值：返回 409 VALID_001，details.payment=already_paid_conflict

5.2 委派管理

POST /api/delegations：创建委派（scope + validFrom/validTo）
GET /api/delegations/mine：查看我发起/我接收的委派
POST /api/delegations/:id/revoke：撤销委派
委派仅作用于 assignee_id 任务，不改写 assignee_role 语义。
自动回收实现采用 FOR UPDATE SKIP LOCKED + UPDATE ... RETURNING，多实例并发下确保同一委派仅回收一次。

5.3 OCR 异步状态查询

上传发票在 OCR 开启且 ocr_type=vat 时会进入 pending_ocr。
GET /api/invoice-pool/:id 可轮询 OCR 处理状态（pending_ocr/available/ocr_failed）。

5.4 审计日志查询

GET /api/audit-logs
权限：system.audit.view（finance_mgr/admin）
支持分页与筛选（actor/action/targetType/date range）。

5.5 工作流查询增强（P3）

GET /api/workflow/tasks：支持 status/page/pageSize，返回 page/pageSize/total/items。
GET /api/workflow/tasks/:taskId：任务详情（实例、报销摘要、可执行动作、处理历史）。
GET /api/workflow/approvers：转审候选人列表（active + 具备 expense.approve）。

5.6 部门管理（P5 蓝图 F26）

GET /api/departments：部门列表 + 树（登录即可；默认不含归档部门）
- 可选：GET /api/departments?includeArchived=1（包含归档部门）
POST /api/departments：创建部门（system.users）
PATCH /api/departments/:id：更新部门（system.users；已归档禁止修改；禁止形成父子环）
POST /api/departments/:id/archive：归档部门（system.users）
- 归档约束：有子部门/有在职员工则禁止归档
- 幂等：已归档重复调用返回 outcome=already_archived

5.7 列表查询接口（P3）

GET /api/reimbursements：支持 page/pageSize/status/scope。
GET /api/invoice-pool：支持 page/pageSize/status/ownerScope。

5.8 定时任务（可手动执行）

cd /home/shunli/Projects/hyb-oa/server
npm run job:revoke-expired-delegations
npm run job:ocr-once

5.9 账号与角色管理（E17，试运行运营）

GET /api/users：员工列表（分页/搜索）
POST /api/users：创建员工（含初始密码）
POST /api/users/:id/disable：禁用员工（tokenVersion+1 + 撤销 refresh）
POST /api/users/:id/enable：启用员工（tokenVersion+1 + 撤销 refresh）
POST /api/users/:id/reset-password：重置密码（返回一次性口令，tokenVersion+1）
POST /api/users/:id/roles：设置角色（tokenVersion+1 + 撤销 refresh）

权限：

system.users（hr/admin；admin 具备 *）

6. 关键环境变量

DATABASE_URL: PostgreSQL 连接串
JWT_SECRET: JWT & signed-url token 签名密钥
APP_TIMEZONE: 默认 Asia/Shanghai
STORAGE_DIR: 默认 generated/storage（相对 server/）
SERVE_CLIENT_DIST: 是否由 server 托管 client/dist（默认 false）
CLIENT_DIST_DIR: 前端构建产物目录（默认 ../client/dist，相对 server/）
SIGNED_URL_TTL_SECONDS: 默认 600
MAX_UPLOAD_SIZE_BYTES: 默认 10485760（10MB）
RATE_LIMIT_ENABLED: 是否启用关键接口限流（默认：production=true，其它环境=false）
RATE_LIMIT_LOGIN_MAX: /api/auth/login 等接口限流次数（默认 10）
RATE_LIMIT_LOGIN_WINDOW: 限流时间窗（默认 1 minute，支持 ms 格式如 30s/1m）
DELEGATION_REVOKE_CRON: 委派自动回收定时表达式（默认 0 * * * *）
OCR_PROVIDER: off / mock / tencent（默认 off）
OCR_BATCH_SIZE: 每轮 OCR 认领数量（默认 10）
OCR_LOCK_TTL_SECONDS: OCR 锁超时秒数（默认 300）
OCR_POLL_CRON: OCR 轮询 cron（默认 * * * * *）
OCR_MAX_ATTEMPTS: OCR 最大重试次数（默认 3）
OCR_TIMEOUT_MS: 腾讯 OCR SDK 超时（默认 5000）
TENCENT_SECRET_ID / TENCENT_SECRET_KEY / TENCENT_OCR_REGION: 腾讯 OCR 配置

安全基线（P4）：

安全头：默认启用 @fastify/helmet（CSP 默认关闭，避免误伤 SPA 本地调试）。
限流：/api/auth/login、/api/auth/forgot-password、/api/auth/reset-password 在 RATE_LIMIT_ENABLED=true 时启用限流。
日志脱敏：authorization/cookie/password/code/newPassword 等敏感字段会被 redaction。

回滚策略：

若限流误伤，可先设置 RATE_LIMIT_ENABLED=false（无需改代码）。
若安全头造成兼容性问题，可回退 server/src/app.js 中 helmet 注册逻辑。

生产提示：大表加索引需评估 CREATE INDEX CONCURRENTLY，避免锁表影响。

7. 常见失败排查

现象	可能原因	解决方案
`prisma migrate deploy` 失败	`DATABASE_URL` 未配置/不可达	检查 `server/.env` 与数据库容器状态
`npm run seed:dev` 重复执行报错	seed 脚本被改坏，未保持幂等	检查 `seed-config.js`/`seed-dev.js` 的 `upsert` / `skipDuplicates`
signed-url 接口返回 403	`JWT_SECRET` 不一致、token 过期、访问人无权限	统一服务密钥、确认 URL 在 TTL 内、检查账号角色
上传返回 `file_too_large`	文件超 `MAX_UPLOAD_SIZE_BYTES`	调整环境变量或使用更小文件
上传失败且报目录/权限错误	`STORAGE_DIR` 不存在或不可写	创建目录并修正权限；Docker 需确认 volume 挂载
OCR 长期停留 `pending_ocr`	`OCR_PROVIDER=off`、mock未开启或腾讯密钥无效	检查 OCR 环境变量，优先用 `OCR_PROVIDER=mock npm run job:ocr-once` 验证链路
委派过期后仍可操作	自动回收任务未运行	检查 `DELEGATION_REVOKE_CRON`，手动执行 `npm run job:revoke-expired-delegations`

8. 手工故障注入（非阻塞）

8.1 `STORAGE_DIR` 不可写路径

临时将 STORAGE_DIR 指向只读目录，执行上传接口，确认错误可观测（日志+返回码）。

8.2 磁盘空间不足（ENOSPC）

在受控环境中制造磁盘满条件后重试上传。
预期：错误路径可观测（日志中能定位到 I/O 错误），不要求纳入日常 CI 冒烟。

README.md Unescape Escape

hyb-oa Server Runbook (P0/P1)

1. 环境准备

2. Gate 基线命令（必须顺序执行）

2.1 启动数据库

2.2 应用迁移

2.3 执行 seed（幂等）

2.3.1 认证安全说明（P5）

2.3.2 邮件通知（可选，F15）

2.3.3 作业系统（cron vs pg-boss）（F19~F19d）

2.4 启动服务

2.5 冒烟验证

2.6 本地最小门禁（P1-b）

3. 1 分钟快速验证

4. 回归入口

4.1 脚本回归（推荐）

4.2 判重专项回归（dedup）

4.3 工作流动作回归

4.4 一键全量回归

4.5 Postman 回归

4.6 前端壳联调（P1-5）

4.7 单域托管 client/dist（可选，试运行建议）

4.8 试运行部署包（Docker Compose）

5. P2 API 摘要

5.1 付款标记（pay）

5.2 委派管理

5.3 OCR 异步状态查询

5.4 审计日志查询

5.5 工作流查询增强（P3）

5.6 部门管理（P5 蓝图 F26）

5.7 列表查询接口（P3）

5.8 定时任务（可手动执行）

5.9 账号与角色管理（E17，试运行运营）

6. 关键环境变量

7. 常见失败排查

8. 手工故障注入（非阻塞）

8.1 STORAGE_DIR 不可写路径

8.2 磁盘空间不足（ENOSPC）

README.md

8.1 `STORAGE_DIR` 不可写路径