hyb-oa/deploy/trialrun/runbook.md

hyb-oa 试运行 Runbook（单机）

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

0A. 如果官网 hyb-web 已在同机运行（推荐方案）

• 官网继续保持 hyinda.com / www.hyinda.com 静态托管，不要改官网目录和配置。
• OA 新增独立二级域名，例如 oa.hyinda.com。
• OA 部署目录由受控环境中的 REMOTE_DIR 指定，不在仓库固化机器路径。
• OA 推荐访问方式：Caddy(443) -> 127.0.0.1:3000 -> docker-compose(server)。
• Caddy 必须覆盖客户端传入的 X-Forwarded-For。OA 站点的 reverse_proxy 中应设置 header_up X-Forwarded-For {remote_host}，不得保留不可信客户端链。
• 首次初始化时：
  1. 服务器以 root 执行 bash deploy/trialrun/setup-server.sh
  2. 手工创建 deploy/trialrun/.env
  3. 手工更新 OA 的 Caddyfile 站点块并确认 TLS 正常
  4. 本地通过受控配置显式提供 DEPLOY_SERVER、REMOTE_DIR，再执行 bash scripts/qa/run-release-gate.sh all（或至少执行 bash deploy/trialrun/deploy.sh）

0B. 历史部署基线（基础设施信息已脱敏）

• SSH 目标、部署账号和机器地址只保存在受控运维配置中，通过 DEPLOY_SERVER 显式传入。
• 反向代理：caddy 正在运行，oa.hyinda.com 已反代到 127.0.0.1:3000
• 部署目录通过 REMOTE_DIR 显式传入。
• 远端目录当前不是 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
• 企业微信与 OCR 已进入公网试运行配置。核查时只检查开关、长度和 smoke 结果，不在日志、Issue 或文档中输出 secret 明文。

0. 前置条件

• Docker + Docker Compose（v1/v2 任一可用）
• 机器时间正确（影响 token / cron / OCR）

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

1.1 准备环境变量

cd /path/to/hyb-oa
cp deploy/trialrun/.env.example deploy/trialrun/.env

必须修改：

• JWT_SECRET
• AUTH_CODE_PEPPER（独立随机秘密，至少 32 字节，不得沿用示例占位符或 JWT secret）
• TRUST_PROXY_HOPS=1（当前单跳 Caddy/Nginx 部署固定为 1）
• APP_ORIGIN（建议与对外域名一致，例如 https://oa.example.com）

环境变量约束：

• deploy/trialrun/.env 现在是 trialrun 部署事实源，server / worker / init 统一通过 env_file 注入。
• BUILD_SHA / VITE_BUILD_SHA 由发布入口按已批准提交临时注入，不写入长期 .env；前者供后端运行时核对，后者只允许 12 位短 SHA 进入公网 bundle。
• 推荐使用无引号值，例如 COOKIE_SECURE=true、PORT=3000。
• 历史上已经写成带引号的 .env 当前仍兼容，但建议后续逐步改成无引号。
• 正式部署前可先执行 node deploy/trialrun/validate-env-contract.js 做静态契约检查。
• EXTERNAL_GATED：涉及认证安全迁移时，发布或回滚前必须由操作人先在边缘暂停 /api/auth/forgot-password、/api/auth/reset-password、/api/auth/email-login/code、/api/auth/email-login/verify 四个 challenge 端点，再执行“新镜像配置预检 -> additive migration -> 新应用切换”。部署脚本不会自动修改边缘配置；未人工确认四端点已关闭不得发布或回滚开放。仅在安全版本及 smoke 全部通过后人工恢复；若回滚到旧认证代码，四端点必须继续关闭。

作业系统建议：

• 试运行默认 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 启动数据库与服务

cd /path/to/hyb-oa
node deploy/trialrun/validate-env-contract.js
export BUILD_SHA="<approved-full-commit>"
export VITE_BUILD_SHA="<matching-12-char-commit>"
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 build init
docker-compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env run --rm init
docker-compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env up -d --build server

以上直接 Compose 命令仅用于首次初始化或受控应急；正式发布优先使用 deploy/trialrun/deploy.sh，由脚本从 clean、已进入 upstream 的提交自动注入两个构建标识。缺少任一标识时 Compose 必须拒绝解析。

可选：启用 MinIO（对象存储，F21）：

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 进程（推荐在试运行/多进程模式使用）：

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 + 试运行管理员）

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。
• 初始化必须发生在依赖新增列的新 server 切换之前；正式部署脚本会先用新 init 镜像校验生产配置并执行迁移，再替换 server。
• 若 TRIALRUN_ADMIN_PASSWORD 为空，seed 会生成一次性口令并输出到控制台（请立刻保存）。
• 正式启用前，推荐先保持“空基线 + 默认种子”，不要直接导入开发库、测试库或旧 OA 整库备份。
• 如确需导入，仅导入最小必要主数据：部门、员工、角色、在用资产、活跃项目、合同元数据。
• 历史审批单、通知历史、审计日志、聊天记录以及涉密正文/附件继续保留在原系统、文件盘或离线档案中。

1.4 验收

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 会先拒绝脏工作树、确认提交已进入 upstream，再从该提交生成 Git archive；随后自动执行环境契约、带 build SHA 的 /ready 核对、external deps smoke 与 runtime smoke。
• 标准发布会先刷新当前 branch 的 upstream remote-tracking ref，再判断目标提交是否已发布。
• 只有明确的离线灾备或已批准远端故障场景才可设置 DEPLOY_ALLOW_UNPUBLISHED_COMMIT=1，并同时提供 allowlist 原因码 DEPLOY_UNPUBLISHED_REASON=offline-disaster-recovery|remote-outage-approved|controlled-local-recovery；部署日志会醒目标记 override，该开关不放宽 clean-tree 要求。
• 若本地存在完整 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 失败。
• 2026-05-05 公网复核显示：OCR_PROVIDER=tencent 可用，真实发票上传后进入 available，provider 为 tencent；后续发布不能再把 OCR 回退到 mock 而不记录原因。

浏览器访问：

• http://127.0.0.1:3000（单域托管前端）

1.4.1 腾讯 OCR 试运行核查

远端 .env 是 OCR 配置事实源，禁止提交或复制密钥明文。只做以下脱敏检查：

cd /opt/hyb-oa-trialrun
set -a
source deploy/trialrun/.env
set +a

printf 'OCR_PROVIDER=%s\n' "$OCR_PROVIDER"
printf 'TENCENT_SECRET_ID length=%s\n' "${#TENCENT_SECRET_ID}"
printf 'TENCENT_SECRET_KEY length=%s\n' "${#TENCENT_SECRET_KEY}"
printf 'TENCENT_OCR_REGION=%s\n' "$TENCENT_OCR_REGION"

期望：

• OCR_PROVIDER=tencent
• TENCENT_SECRET_ID 和 TENCENT_SECRET_KEY 长度大于 0
• TENCENT_OCR_REGION 与腾讯 OCR 开通地域一致，例如 ap-beijing

发布后 smoke：

docker-compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env exec -T server node src/scripts/smoke-external-deps.js
docker-compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env exec -T server node src/scripts/smoke-trialrun-runtime.js

真实 OCR 辅助复核（本地执行，不提交发票文件）：

cd client
PLAYWRIGHT_MANUAL=1 \
PLAYWRIGHT_OCR_LIVE=1 \
PLAYWRIGHT_OCR_LIVE_FILE=/path/to/invoice.pdf \
E2E_BASE_URL=https://oa.hyinda.com \
npx playwright test tests/e2e/manual/live-invoice-ocr.spec.ts --workers=1 --reporter=list --timeout=360000

回滚到 mock 只允许作为应急降级：

1. 在远端 .env 将 OCR_PROVIDER=tencent 改为 OCR_PROVIDER=mock。
2. 执行 docker-compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env up -d server。
3. 在 Issue/发布记录中写明降级原因、预计恢复时间和影响范围。

1.5 备份与恢复演练（正式启用前必须完成）

数据库和文件存储必须使用同一批次成对备份；只有两份产物、完整性检查和 manifest 全部成功，才算一个可用恢复点。

1.5.1 备份

cd /path/to/hyb-oa
set -a
source deploy/trialrun/.env
set +a

DB_TOOL_MODE=docker \
DB_CONTAINER=hyb-oa-trialrun-db \
./scripts/backup-all.sh

输出默认在 deploy/trialrun/backups/hyb-oa-backup-<run-id>/，其中包含：

• database.dump
• storage.tar.gz
• manifest.json（相对文件名、大小和 SHA-256，不含连接串或源目录）

整批复制到获批的异机/异盘位置并记录保留周期；不能只复制 DB 或附件中的一份。

1.5.2 本地隔离恢复演练

开发机具备 Docker、PostgreSQL 客户端和 Node.js 时，使用合成数据运行：

./scripts/qa/run-backup-restore-drill.sh

该命令创建一次性 PostgreSQL 容器和临时附件目录，验证 DB/附件往返、manifest 校验和、错误数据库确认、损坏备份、非空目标目录和危险 tar 路径，结束后只清理本次创建的明确目标。它不读取 deploy/trialrun/.env，也不接触真实数据。

手工影子恢复必须使用独立数据库和空附件目录，并显式确认实际数据库名：

RESTORE_SCOPE=shadow \
RESTORE_CONFIRM_DATABASE=<shadow_database_name> \
DB_TOOL_MODE=docker \
DB_CONTAINER=<shadow_postgres_container> \
DATABASE_URL=<shadow_database_url> \
POSTGRES_DB=<shadow_database_name> \
POSTGRES_USER=<shadow_database_user> \
POSTGRES_PASSWORD=<shadow_database_password> \
./scripts/restore-db.sh deploy/trialrun/backups/<batch>/database.dump

RESTORE_SCOPE=shadow \
./scripts/restore-storage.sh \
  deploy/trialrun/backups/<batch>/storage.tar.gz \
  <empty_shadow_storage_directory>

restore-db.sh 和 restore-storage.sh 默认只接受 shadow。影子库名必须包含独立的 shadow、drill 或 restore_test 标记；数据库确认不匹配、库名不安全、附件目录非空、目标为默认试运行附件目录或归档路径危险时均在写入前退出。

1.5.3 真实事故恢复

真实库/附件恢复不是普通脚本路径。必须另建或更新获批 Trellis task，记录停机窗口、恢复批次、实际目标、两名负责人、当前备份、回滚点和验证清单。当前恢复脚本不会接受 production 模式，不得通过修改环境变量或脚本临时绕过。恢复后必须验证 /ready、运行 commit、核心权限和 DB/附件关联完整性。

1.5.4 小团队上线前演练记录

上线前至少记录一次演练结果：

• 演练日期：
• 执行人：
• DB 备份文件：
• 文件存储备份文件：
• manifest 与 SHA-256 校验：
• 恢复目标机器或目录：
• 本地合成数据 RTO：
• 恢复后 /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. 从本地仓库执行 DEPLOY_SERVER=<ssh-target> REMOTE_DIR=<remote-dir> bash deploy/trialrun/deploy.sh（推荐）；脚本只同步已验证提交的 Git archive，不依赖远端 git pull，也不会把本地 ignored 文件带入发布。
   • artifacts/ 和 output/ 是运行期证据/截图目录，不作为源码发布输入，也不由 rsync --delete 清理远端历史证据。
3. 构建并重启：

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

2.2 前端部署一致性排障

当前 oa.hyinda.com 由 Caddy 反代到 127.0.0.1:3000，前端静态资源由 server 容器内的 /app/client/dist 提供，不是 /etc/caddy/Caddyfile 里的独立静态目录。

如果出现“本地源码已有功能，但公网仍显示旧 UI”，先按以下顺序核查：

# 1) 确认 Caddy 仍是反代到 3000
sudo sed -n '/oa.hyinda.com/,/}/p' /etc/caddy/Caddyfile

# 2) 比对公网首页引用的 asset hash
curl -fsS https://oa.hyinda.com/ | grep -o '/assets/[^" ]*' | head

# 3) 在容器内查构建产物是否包含关键 test id
docker exec hyb-oa-trialrun-server sh -lc \
  'for pat in invoice-pool-mobile-list reimbursements-mobile-list mobile-capture-file multiple:!0; do printf "%s " "$pat"; grep -Rao "$pat" /app/client/dist/assets /app/client/dist/index.html 2>/dev/null | wc -l; done'

若远端源码已更新但容器内 /app/client/dist 仍旧，重建并重启：

cd /opt/hyb-oa-trialrun
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 -T init </dev/null
curl -fsS http://127.0.0.1:3000/ready

重建后必须补做：

• smoke-external-deps.js
• smoke-trialrun-runtime.js
• 公网页面视觉检查：至少覆盖 /invoice-pool、/reimbursements、/mobile/capture 的 390px 视口

发布/回滚 Checklist：

• deploy/trialrun/checklist.md

3. 回滚流程（试运行）

回滚分两类：仅回滚代码（无迁移），或需要 DB 回滚（恢复备份）。

3.1 仅回滚代码

# 远端目录不是 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. 停止服务：

docker-compose -f deploy/trialrun/docker-compose.yml --env-file deploy/trialrun/.env stop server

2. 按 E14 恢复 DB + 文件存储备份
3. 启动服务并验收 /ready 与登录

4. 日志与排障

• server 容器日志：

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=<local-postgresql-url> 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 辅助复核先执行：

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 本地深层辅助回归命令

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 辅助回归命令

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. 重新执行：

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 首屏避免横向滚动和过宽表格。
• 状态色只表达语义，不把品牌色滥用成所有强调色。