hyb-oa/deploy/trialrun/runbook.md

# hyb-oa 试运行 Runbook（单机）

> 目标：按本文档在一台新机器完成 **启动 → 迁移 → 初始化管理员 → 验收 → 备份 → 恢复 → 回滚** 演练。

## 0A. 如果官网 `hyb-web` 已在同机运行（推荐方案）
- 官网继续保持 `hyinda.com / www.hyinda.com` 静态托管，不要改官网目录和配置。
- OA 新增独立二级域名，例如 `oa.hyinda.com`。
- OA 推荐部署目录：`/opt/hyb-oa-trialrun`。
- OA 推荐访问方式：`Caddy(443) -> 127.0.0.1:3000 -> docker-compose(server)`。
- 首次初始化时：
  1. 服务器以 root 执行 `bash deploy/trialrun/setup-server.sh`
  2. 手工创建 `deploy/trialrun/.env`
  3. 手工更新 OA 的 `Caddyfile` 站点块并确认 TLS 正常
  4. 本地执行 `bash scripts/qa/run-release-gate.sh all`（或至少执行 `bash deploy/trialrun/deploy.sh`）

## 0B. 当前已核实的 `118.89.77.218` 部署基线（2026-05-04）
- SSH 用户：
  - 常规部署：`[email protected]`
  - 系统配置：`[email protected]`
  - `shunli` 当前不可免密登录
- 反向代理：`caddy` 正在运行，`oa.hyinda.com` 已反代到 `127.0.0.1:3000`
- 部署目录：`/opt/hyb-oa-trialrun`
- 远端目录当前不是 git 工作树；发布应优先从本地执行 `bash deploy/trialrun/deploy.sh`，由脚本 `rsync` 到服务器
- 远端容器编排当前实际为 `docker-compose 1.29.2`；本 runbook 命令以 `docker-compose` 为准
- 当前公网 `.env` 已确认：`APP_ORIGIN=https://oa.hyinda.com`、`COOKIE_SECURE=true`、`PUBLIC_SECURITY_HARDENING_ENABLED=true`，但 `WECOM_*` 仍为 `false`，`OCR_PROVIDER=mock`

## 0. 前置条件
- Docker + Docker Compose（v1/v2 任一可用）
- 机器时间正确（影响 token / cron / OCR）

## 1. 首次启动（推荐：单域托管）

### 1.1 准备环境变量
```bash
cd /path/to/hyb-oa
cp deploy/trialrun/.env.example deploy/trialrun/.env
```

必须修改：
- `JWT_SECRET`
- `APP_ORIGIN`（建议与对外域名一致，例如 `https://oa.example.com`）

环境变量约束：
- `deploy/trialrun/.env` 现在是 trialrun 部署事实源，`server / worker / init` 统一通过 `env_file` 注入。
- 推荐使用无引号值，例如 `COOKIE_SECURE=true`、`PORT=3000`。
- 历史上已经写成带引号的 `.env` 当前仍兼容，但建议后续逐步改成无引号。
- 正式部署前可先执行 `node deploy/trialrun/validate-env-contract.js` 做静态契约检查。

作业系统建议：
- 试运行默认 `JOB_DRIVER=pgboss`（基于 Postgres 的队列调度，单机/多进程语义更稳）
- 如需快速回滚作业调度：将 `JOB_DRIVER` 改回 `cron`
 - 可选 Worker 拆分（F20）：将 `JOBS_ENABLED=false` 并启用 `--profile worker`（worker 进程会强制跑作业）

存储建议：
- 默认 `STORAGE_DRIVER=local`（票据文件落到 `deploy/trialrun/data/storage`）
- 可选启用 MinIO（F21）：`STORAGE_DRIVER=s3` 并启用 `--profile minio`

### 1.2 启动数据库与服务
```bash
cd /path/to/hyb-oa
node deploy/trialrun/validate-env-contract.js
docker-compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env up -d db
docker-compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env up -d --build server
```

可选：启用 MinIO（对象存储，F21）：
```bash
cd /path/to/hyb-oa
docker-compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env --profile minio up -d minio minio_init
```

可选：启用 Worker 进程（推荐在试运行/多进程模式使用）：
```bash
cd /path/to/hyb-oa
# 1) 在 deploy/trialrun/.env 中设置：JOBS_ENABLED="false"
# 2) 启用 worker profile（会额外启动 worker 容器）
docker-compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env --profile worker up -d --build server worker
```

### 1.3 初始化（迁移 + 配置 seed + 试运行管理员）
```bash
cd /path/to/hyb-oa
docker-compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env run --rm init
```

说明：
- `init` 是一次性任务：`migrate:deploy + seed:config + seed:trialrun`。
- 若 `TRIALRUN_ADMIN_PASSWORD` 为空，seed 会生成一次性口令并输出到控制台（请立刻保存）。
- 正式启用前，推荐先保持“空基线 + 默认种子”，不要直接导入开发库、测试库或旧 OA 整库备份。
- 如确需导入，仅导入最小必要主数据：部门、员工、角色、在用资产、活跃项目、合同元数据。
- 历史审批单、通知历史、审计日志、聊天记录以及涉密正文/附件继续保留在原系统、文件盘或离线档案中。

### 1.4 验收
```bash
curl -fsS http://127.0.0.1:3000/health
curl -fsS http://127.0.0.1:3000/ready
curl -fsS http://127.0.0.1:3000/metrics | head
docker-compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env exec -T server node src/scripts/smoke-trialrun-runtime.js
```

说明：
- `deploy/trialrun/deploy.sh` 现已自动执行 `validate-env-contract.js`、`/ready` 探活、`smoke-external-deps.js` 与 `smoke-trialrun-runtime.js`。
- 若本地存在完整 `LIVE_SMOKE_*` 环境变量，部署脚本会继续执行 `client npm run test:e2e:live`，用于公网只读 smoke。
- 推荐直接执行 `bash scripts/qa/run-release-gate.sh all`，让 static / local smoke / full-local / deploy / live smoke 形成单一放行链。
- 若再出现“数据库开了但功能被环境硬关”的情况，部署会直接失败，不再等到手工点页面才发现。
- 2026-05-04 公网只读巡检显示：`smoke-external-deps.js` 可以通过，但前提是 `WECOM_*` 未启用且 `OCR_PROVIDER=mock`；`smoke-trialrun-runtime.js` 当前会因 `announcements_v1` 为 `force_off` 失败。

浏览器访问：
- `http://127.0.0.1:3000`（单域托管前端）

## 1.5 备份与恢复演练（强烈建议至少做一次）
> 备份建议做到“DB + 文件存储（票据上传目录）”双份齐全。

### 1.5.1 备份
```bash
cd /path/to/hyb-oa
set -a
source deploy/trialrun/.env
set +a

./scripts/backup-db.sh
./scripts/backup-storage.sh
```

输出默认在：
- `deploy/trialrun/backups/`

### 1.5.2 恢复（到同一台机器或新机器）
1) 先停止 server：
```bash
docker-compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env stop server
```

2) 恢复 DB：
```bash
set -a
source deploy/trialrun/.env
set +a

./scripts/restore-db.sh deploy/trialrun/backups/<hyb-oa-db-*.dump>
```

3) 恢复文件存储：
```bash
./scripts/restore-storage.sh deploy/trialrun/backups/<hyb-oa-storage-*.tar.gz> deploy/trialrun/data/storage
```

4) 重启并验收：
```bash
docker-compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env up -d server
curl -fsS http://127.0.0.1:3000/ready
```

### 1.5.3 R66 小团队上线前演练记录
上线前至少记录一次演练结果：

- 演练日期：
- 执行人：
- DB 备份文件：
- 文件存储备份文件：
- 恢复目标机器或目录：
- 恢复后 `/ready` 结果：
- 上个可回滚 tag：
- 回滚负责人：

需要人工配合的事项：

- 提供或确认真实 `deploy/trialrun/.env`，特别是 `JWT_SECRET`、`APP_ORIGIN`、`COOKIE_SECURE`、`OPENAPI_DOCS_ENABLED`。
- 确认备份文件保存位置和保留周期。
- 准备独立 smoke 账号，避免使用老板、管理员或真实员工账号跑自动化。

## 2. 升级流程（试运行）
建议版本化方式：
- 每次发布打 tag，例如 `trialrun-2026-02-08-01`

### 2.1 网页自动化门禁（R28）
发布前后统一使用三层网页自动化：
- `bash scripts/qa/run-web-gates.sh smoke-local`：本地/PR 快速门禁，只覆盖登录、Portal、导航、企微入口 UI。
- `bash scripts/qa/run-web-gates.sh full-local`：本地/main/夜间全量门禁，串联 server 回归、client build 与全部 Playwright E2E。
- `bash scripts/qa/run-web-gates.sh smoke-live`：发布后公网只读 smoke，只检查 `/ready`、登录、Portal、团队、请假、项目、公告、个人设置、管理页只读入口与企微配置状态。

约束：
- live smoke 必须使用独立账号：`smoke-admin`、`smoke-employee`。
- live smoke 禁止新建报销、提交审批、付款、导入、资产流转、项目写操作。
- 若本地已配置完整 `LIVE_SMOKE_*`，`bash deploy/trialrun/deploy.sh` 会在远端部署完成后自动补跑 live smoke。

步骤：
1) 先做备份（见 E14 脚本）  
2) 从本地仓库执行 `bash deploy/trialrun/deploy.sh`（推荐）；该脚本会把当前工作树 `rsync` 到 `/opt/hyb-oa-trialrun`，不依赖远端 `git pull`  
3) 构建并重启：
```bash
docker-compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env up -d --build server
docker-compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env run --rm init
```

发布/回滚 Checklist：
- `deploy/trialrun/checklist.md`

## 3. 回滚流程（试运行）
> 回滚分两类：仅回滚代码（无迁移），或需要 DB 回滚（恢复备份）。

### 3.1 仅回滚代码
```bash
# 远端目录不是 git 工作树，推荐在本地切到目标 tag 后重新执行 deploy.sh
# git checkout <previous-tag>
docker-compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env up -d --build server
```

### 3.2 需要 DB 回滚（推荐做法）
1) 停止服务：
```bash
docker-compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env stop server
```
2) 按 E14 恢复 DB + 文件存储备份  
3) 启动服务并验收 `/ready` 与登录

## 4. 日志与排障
- server 容器日志：
```bash
docker logs -f hyb-oa-trialrun-server
```
- `/ready` 失败通常为 DB 不可达或连接串错误。

## 5. 优雅停机（E21）
说明：
- `docker-compose stop server` 会发送 `SIGTERM`，server 会尝试在 10s 内完成：
  - 停止 OCR/委派回收定时任务
  - 关闭 HTTP 监听
  - 断开 Prisma/PG 连接
- 超时会强制退出（避免卡死导致升级失败）。


## 6. R12-lite 试点切换 Runbook

### 6.1 打开本轮功能前置条件
- 执行 `cd server && DATABASE_URL=postgresql://hyboa_user:[email protected]:5432/hyb_oa_r12?schema=public npm run seed:config`，确保 R12-lite 开关与默认配置落库。
- 在运行环境启用对应 env：`BUDGET_PRECHECK_ENABLED=true`、`PAYMENT_BATCH_ENABLED=true`、`PORTAL_HOME_ENABLED=true`、`GLOBAL_SEARCH_ENABLED=true`、`ANNOUNCEMENTS_ENABLED=true`、`WORKFLOW_DEFINITION_ADMIN_ENABLED=true`、`CUTOVER_CONSOLE_ENABLED=true`。
- 登录系统后在“功能开关”页将对应开关切到 `inherit` 或 `force_on`；仅设置 env 不会自动放开 DB 中的 `force_off` 记录。

### 6.2 旧 OA 主数据导出与 dry-run
1. 从旧 OA 导出人员、部门、预算或主数据 CSV。
2. 进入“切换控制台”，按 `employees | departments | budgets | masterdata_validation` 上传 CSV 执行 dry-run。
3. 只接受 `dry_run_ok` 结果进入下一步；若为 `dry_run_failed`，先修正列头和差异。
4. 以 `docs/migration-mapping.md` 为准完成人工差异核对。

### 6.3 试点切换步骤
1. 确认旧 OA 未完结事项已人工清空或冻结。
2. 在旧 OA 宣布“新单停用时间点”。
3. 在新系统创建 `CutoverScope`，粒度仅允许 `department | legal_entity | domain`。
4. 按试点范围打开对应 `CutoverScope`，先开 `portal`，再按域逐步打开 `expense / leave / procurement / travel / asset`。
5. 观察 Portal、待办、支付批次、AP 运营和消息深链是否正常。

### 6.4 验收证据
- 保留 dry-run 结果截图或导出记录。
- 保留切换范围配置、启停时间和操作人审计。
- 保留回归结果：`server/scripts/regression-all.sh`、`client npm run build`、`client npm run test:e2e`（如环境可用）。
- 保留试点部门首批新单在新系统流转与付款的样例单据编号。

### 6.5 回退步骤
1. 在“切换控制台”关闭目标 `CutoverScope`。
2. 恢复旧 OA 对应入口并重新开放新单。
3. 若需要代码/数据回退，按本文第 3 节恢复到最近备份。
4. 新系统中试点期间新建单据保留审计，不做 destructive 回写到旧 OA。

## 7. R17 小团队内部管理上线 Runbook

### 7.1 默认目标形态
- 工作区模式：`small_team_internal`
- 主导航：`Portal`、`团队`、`请假`、`报销`、`资产`、`周报`、`待办`、`公告`
- 入口策略：账号密码主入口，站内通知主通道，桌面优先

### 7.2 推荐环境开关
- 建议打开：`PORTAL_HOME_ENABLED=true`、`GLOBAL_SEARCH_ENABLED=true`、`ANNOUNCEMENTS_ENABLED=true`、`PRESENCE_BOARD_ENABLED=true`、`WEEKLY_REPORT_ENABLED=true`、`EMPLOYEE_LIFECYCLE_ENABLED=true`、`TODO_BOARD_ENABLED=true`
- 建议保留备用：`PAYMENT_BATCH_ENABLED=false`、`CUTOVER_CONSOLE_ENABLED=false`
- OCR 回归环境建议：`OCR_PROVIDER=mock`

### 7.2A 本地 Playwright 辅助复核门禁
1. 本地 HTTP 辅助复核先执行：
```bash
cd server
TRIALRUN_RUNTIME_MODE=local node src/scripts/smoke-trialrun-runtime.js
```
2. 该命令会同时检查 trialrun 所需 env、feature flag、workspace setting 与导航基线。
3. `local` 模式允许 `APP_ORIGIN` 为空、`COOKIE_SECURE` 为空或 `false`；HTTPS / 真实部署仍按 `deploy` 模式要求 `APP_ORIGIN=https://...` 且 `COOKIE_SECURE=true`。

### 7.2B 本地深层辅助回归命令
```bash
cd client
PLAYWRIGHT_MANUAL=1 \
R70_TRIALRUN_DEEP_ASSIST=1 \
E2E_BASE_URL=http://127.0.0.1:3001 \
npm run test:e2e -- tests/e2e/manual/r70-trialrun-deep-assist.spec.ts
```

### 7.2C 批量真实腾讯 OCR 辅助回归命令
```bash
cd client
PLAYWRIGHT_MANUAL=1 \
PLAYWRIGHT_OCR_LIVE=1 \
PLAYWRIGHT_OCR_LIVE_BATCH=1 \
PLAYWRIGHT_OCR_LIVE_DIR=/abs/path/to/invoices \
E2E_BASE_URL=http://127.0.0.1:3001 \
npm run test:e2e -- tests/e2e/manual/live-invoice-ocr-batch.spec.ts
```

### 7.3 上线前整理事项
1. 补齐员工账号、部门、直属上级与员工档案。
2. 核对资产卡片与实际领用关系。
3. 为老板 / 管理员 / 主管 / 员工分配推荐角色预设。
4. 在 `工作区设置` 确认模块显隐，收敛主导航。
5. 准备一条公告，验证全员登录后 `Portal` 可见。

### 7.4 首周启用顺序
1. 打开 `Portal + 公告 + 团队状态`
2. 第二天开始要求全员更新今日状态
3. 当周启用 `周报 + 待办`
4. 同步启用 `入职 / 离职 / 资产交接`
5. 报销和请假保持可用，但不再作为首页主叙事

### 7.5 4 周观测建议
- 每周记录：
  - 周报提交人数
  - 团队状态更新人数
  - 公告阅读反馈
  - 入职/离职/资产交接演练情况
- 建议统一使用 `deploy/trialrun/observation-template.md` 填写每周结论与阻塞。
- 可执行 `cd server && npm run report:small-team-observation -- --out ../deploy/trialrun/observations/week-01.md` 导出当周快照，再补充人工结论。
- 若连续两周无人使用某入口，考虑继续降级模块可见性。

## R18-R22 公网 + 企微 + 项目域上线补充

### A. 公网安全基线
1. 为 OA 准备 HTTPS 域名并反向代理到 `server`。
2. 在 `deploy/trialrun/.env` 中至少设置：
   - `APP_ORIGIN=https://oa.example.com`
   - `COOKIE_SECURE=true`
   - `PUBLIC_SECURITY_HARDENING_ENABLED=true`
   - `OPENAPI_DOCS_ENABLED=false`
3. 重新执行：
```bash
docker-compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env up -d --build server
```
4. 验证浏览器和企业微信 WebView 都能正常登录、刷新 token 与退出登录。

### B. 企业微信工作台入口
1. 在企业微信自建应用中配置工作台地址，默认落到：`https://oa.example.com/portal`。
2. 在 `deploy/trialrun/.env` 中补齐：
   - `WECOM_ENABLED=true`
   - `WECOM_ENTRY_ENABLED=true`
   - `WECOM_CORP_ID`
   - `WECOM_AGENT_ID`
   - `WECOM_AGENT_SECRET`
   - `WECOM_OAUTH_ENABLED=true`
   - `WECOM_REDIRECT_URI=https://oa.example.com/api/auth/wecom/callback`
   - `WECOM_ALLOWED_RETURN_HOSTS=oa.example.com`
3. 管理员先在个人设置页完成企微绑定，再拉试点用户验证免登。
4. 企微消息只用于提醒与打开 OA，不新增第二套录入页面。

### C. 项目与合同最小导入
1. 先整理项目台账、项目成员、里程碑、风险、合同登记 CSV。
2. 按 `docs/migration-mapping.md` 的最小列准备字段。
3. 先在测试环境做 dry-run，再在试点环境 apply。
4. 涉密正文、附件、报价成本继续保留在内网资料库或离线档案。

### D. 试点验收新增观察点
- 企业微信进入 OA 的成功率
- 项目任务与里程碑更新率
- 报销 / 差旅 / 周报挂项目覆盖率
- 是否还存在第二套项目台账或 Excel 主表
- 企业微信通知是否发生敏感字段泄露

## 7. R23 试点收口准入步骤
1. 打开以下功能开关并确认 DB 记录不是 `force_off`：
   - `project_domain_v1`
   - `project_linking_v1`
   - `project_communication_log_v1`
   - `project_closure_checklist_v1`
   - `confidential_doc_refs_v1`
   - `global_search_v1`
2. 抽样创建或选择 1 个真实项目，验证：
   - 可以新增客户沟通回填
   - 项目收口清单会自动生成
   - 项目改为 `completed/archived` 时出现软告警而非硬阻断
3. 抽样验证 1 条涉密合同或资料引用：
   - 敏感摘要关键字无法通过全局搜索命中
   - 合同编号或资料编号可以命中
   - 企业微信消息只发“有项目待跟进 / 有项目待收口”脱敏提醒
4. 向全员宣导两条试点纪律：
   - 客户沟通影响项目时 `24h` 内回填
   - 私聊可继续发生，但项目状态不能只留在聊天里
5. 进入真实 4 周试点前，至少保留一次通过记录：后端测试、前端 build、E2E 全绿截图或日志。


## 8. R29 前端设计系统与工作台体验验收
### 8.1 视觉与交互核对顺序
1. 登录页：先确认当前场景只有一个主 CTA，并验证错误提示、企微回退文案可理解。
2. Portal：确认员工与管理员两套第一屏都先回答“今天要做什么”。
3. 导航：确认主导航 9 项稳定、管理入口独立、备用模块默认折叠。
4. 个人设置：确认只展示员工可理解的信息，企微绑定卡状态清晰。

### 8.2 自动化建议
- 本地快速验收：`bash scripts/qa/run-web-gates.sh smoke-local`
- 发版前完整验收：`bash scripts/qa/run-web-gates.sh full-local`
- 公网只读验收：`bash scripts/qa/run-web-gates.sh smoke-live`

### 8.3 设计 QA 口径
- 一个场景只允许一个主 CTA。
- 首页先动作，后报表；公告与最近访问降到第二阅读层。
- 空状态必须给下一步建议，不只显示“暂无数据”。
- 移动 / WebView 首屏避免横向滚动和过宽表格。
- 状态色只表达语义，不把品牌色滥用成所有强调色。