wangsli/hyb-oa
1
0
派生 0
代码 工单 合并请求 工作流 8 软件包 项目 发布 百科 活动
文件
5cd960cf90f41d8e28f82e92f5a40750f096e8ed
hyb-oa/docs/管理员手册.md
T

45 KiB
原始文件 Blame 文件历史

hyb-oa 管理员手册（10 人以下团队版）

当前状态（2026-05-19 / WARCH1 实现后）：R7E、PRELAUNCH、财务闭环、ATTV1、HR-WECOM-DIRECTORY-V1、WAPI、WOUA-FIX、WRV1/WRA1、WMSG1、WAPC1/WAPC2、WPROC1/WPROC2、WAPC2F dry-run、WAPC2FLIVE、WCBK1、WEGOV1、WACP3/WACP3R、WREAD1/WREAD1F、WADM1 和 WARCH1 均已收口到当前开发阶段；SYSTEM-COMPLETE-GATE 结论为 GO_TO_USE。WAPI 后固定企微 API 能力目录和 Secret 矩阵：通讯录使用 WECOM_CONTACT_SECRET，人事助手/打卡/消息/OAuth/审批读取使用 WECOM_AGENT_SECRET，运行时代码不得靠多个 Secret 试错。WAPC2FLIVE 已创建 OA-POC 请假/补卡测试模板和低风险测试审批单，报告 /app/artifacts/qa-flow/wecom-approval-fixtures-20260519T053400Z/summary.json 为 PASS_FIXTURE_CREATED，自动复跑 WAPC2 为 PASS_APPROVAL_POC；测试模板和审批记录保留审计，不自动删除。WCBK1 已部署只读回调端点和 runner，远端完成回调 URL 验证并收到一条由 SMOKE101 同意现有 OA-POC 补卡测试单触发的真实审批状态事件，报告 /app/artifacts/qa-flow/wecom-approval-callback-poc-20260519T092648Z/summary.json 为 PASS_CALLBACK_EVENT_CONFIRMED。WACP3R 已新增自动发现模板 ID 路径并公网只读复跑，报告 /app/artifacts/qa-flow/wecom-approval-compensation-poc-20260519T115944Z/summary.json 为 PASS_WITH_FINDINGS；WREAD1F 新样例后，用户确认请假/补卡在企业微信消息卡片、列表和详情页均可看清，远端报告 /app/artifacts/qa-flow/wecom-approval-readability-gate-20260519T133628Z/summary.json 为 PASS_READABLE。WARCH1 已新增并部署请假/补卡最小审批历史留存：回调事件默认入 OA DB，补偿拉取可在 --persist-to-db + WECOM_ARCHIVE_WRITE=1 双开关下写 OA 留存，离线 runner 可不调用企微 API 读取已保存历史摘要；公网报告 /app/artifacts/qa-flow/wecom-approval-compensation-poc-20260519T160306Z/summary.json 和 /app/artifacts/qa-flow/wecom-approval-archive-20260519T160330Z/summary.json 均为 PASS_WITH_FINDINGS，2 条请假/补卡历史可离线读取，finding 是旧回调未入库历史 gap。同意单击即通过风险已进入归档审计事实，后续正式历史页和操作规程继续突出动作来源与补偿一致性。采购、费用、合同、项目、报销、付款、AP、代账交接和高敏附件继续 OA 主办，企业微信只做脱敏提醒和 OA deeplink。公网 payment_batch_v1=force_on，erp_sync=force_off。公司当前无 ERP/独立财务系统，且 ERP 未来不接入 OA；财务闭环以 OA 内审批、台账、付款批次、银行对公付款回单和月度代账交接为准。

1. 适用范围

  • 适用于 small_team_internal 工作区模式。
  • 适用于单公司、少部门、全员账号密码登录的小团队。
  • 目标是把财务、报销、采购、合同、项目、审计、镜像和接管能力收口到 hyb-oa；企业微信优先承担通讯录、人事助手、打卡、HR/考勤员工日常审批和移动入口。

2. 管理员每周固定动作

  • 周一：查看 审批待办、报销/OCR 异常、企微 HR/考勤审批镜像、项目风险和本周关键付款/归档事项。
  • 周中：处理报销退回、重复发票例外、企业微信绑定异常、人员权限和审批规则缺口。
  • 周五：复核未完成审批、未付款报销、待归档合同/附件、采购/费用申请和下周请假安排。

3. 首次上线最小配置

  1. 进入 工作区设置，确认产品模式为 small_team_internal。
  2. 首批主路径优先保留：Portal、审批待办、报销、票据/OCR、项目、采购/费用、合同/附件、企微 HR/考勤镜像和 OA 应急接管状态。请假、补卡、外出、加班的正常提交入口后续迁往企业微信。
  3. 团队状态、周报、待办、公告、人员、资产 可按真实试运行需要开启；支付批次 和 AP 运营 已作为财务闭环正式能力面向出纳、财务和管理员开放，普通员工不显示该入口；预算、AI、完整差旅能力仍作为备用或历史能力，ERP 不再规划接入。
  4. 在 用户管理 中按推荐预设配置：老板 / 管理员 / 主管 / 员工。
    • 正式审批组织口径：majianyong 配置为员工可见直属主管和 manager；wangshunli 配置为后台公司负责人 ceo + admin，不配置为普通 manager。
    • 普通员工和专用测试员工的直属主管配置为 majianyong；majianyong 的直属领导配置为 wangshunli。
    • admin 只代表系统管理权限，不代表业务审批权；需要业务审批时必须配置 manager、ceo、finance、hr 等正式业务角色。
    • 缺直属主管、主管停用、主管链断裂或审批节点解析到申请人本人时，应先修正组织或审批规则，不要用管理员账号代批。
  5. 检查功能开关：
    • 建议开启：portal_home_v1、企业微信入口相关开关、报销/OCR、审批待办、请假、项目基础能力和 payment_batch_v1。
    • 按需开启：announcements_v1、presence_board_v1、weekly_report_v1、employee_lifecycle_v1、hr_wecom_directory_sync_v1、todo_board_v1、global_search_v1。
    • 已实现并部署验证：wecom_hr_master_sync_v1，默认和最终 force_off；启用和生产 apply 需单独确认。
    • QA-only 运行门禁：npm run check:wecom-runtime-ready -- --live --format=json；默认不发送真实消息，低风险消息验证必须额外设置 WECOM_RUNTIME_TEST_SEND=1 并传 --send-test-message。
    • 后续按独立合同评估：wecom_attendance_approval_mirror_v1（承接旧口径 wecom_native_approval_mirror_v1）、oa_hr_emergency_mode_v1、wecom_recovery_writeback_v1、wecom_ruleops_v1。
    • 建议保留备用：cutover_console_v1、预算、AI 和完整差旅相关开关；erp_sync 保持关闭且不再作为后续接入目标。

3.1 ORG8 组织账号与角色边界

WFOC 后，企微/人事助手是员工主数据源，OA 是员工镜像、账号权限、财务业务、接管状态和审计事实源。管理员维护组织账号时，先确认企微通讯录、人事助手和员工绑定状态，再检查 OA 员工镜像、角色、账号状态和应急接管配置。

最小必填主数据：

字段 用途 缺失影响
员工账号和姓名 登录、单据归属、审批历史 无法稳定追踪责任人
部门和职位 列表筛选、组织展示、权限判断辅助 财务和负责人扫读困难
直属主管 请假、报销、采购等默认审批链 审批人缺失或错误回退
账号状态 登录、入口、通知和禁用拦截 离职或停用人员可能继续进入
业务角色 审批、财务、HR、系统管理入口 权限过大或无法处理待办
企业微信通讯录/绑定状态 手机入口、免登、通知 deeplink、打卡采集身份 企业微信入口无法直达、误绑定或离职后未禁用

角色边界：

角色 允许能力 禁止或高风险边界
员工 提交本人报销、请假、采购，查看本人单据和通知 不得查看他人财务、审批待办或管理员入口
直属主管 / 审批人 处理分配给自己的审批待办，查看必要的单据摘要和历史 不得处理未分配给自己或超出角色范围的待办
财务 复核报销、处理付款标记、导出授权范围内财务数据 不默认拥有系统管理权限，不处理非财务系统配置
管理员 / HR 维护员工、部门、角色、主管链、入口配置和绑定异常 admin 不等于业务审批人，不应用管理员账号代批
系统管理员 维护部署、备份、配置、日志和企业微信应用密钥 不处理业务审批，不查看无关财务明细
老板 / 负责人 处理高风险或大额审批，查看授权管理摘要 不替代员工直属主管的日常组织配置

不兼容或需确认的组合：

  • admin-only 账号不得作为报销、请假或采购的业务审批人。
  • 财务和系统管理员混授属于高风险组合，必须有人工确认、审计记录和可回退路径。
  • 直属主管、审批人或财务账号停用后，不得继续接收新待办；历史审批记录保留只读。
  • 新员工账号创建必须同时确认直属主管、初始角色、账号状态、企业微信通讯录同步状态和绑定路径。
  • 离职或停用账号必须阻断登录、企业微信入口和新业务处理；离职完成后默认禁用企业微信成员，不删除成员，不删除历史单据和审批记录。

只读审计口径：

所有 ORG8 主数据审计只允许使用只读账号执行 SELECT，输出仅保留工号、姓名、状态、角色摘要、业务类型和数量；不得导出手机号、邮箱、银行卡、身份证号、密码哈希、token 或企业微信真实标识。发现问题后只记录摘要和责任归属，不在审计 SQL 中修数据。

直属主管缺失：

WITH role_summary AS (
  SELECT employee_id, string_agg(role_code::text, ',' ORDER BY role_code::text) AS roles
  FROM employee_roles
  GROUP BY employee_id
)
SELECT e.employee_no, e.name, e.status, COALESCE(r.roles, '') AS roles
FROM employees e
LEFT JOIN role_summary r ON r.employee_id = e.id
WHERE e.status = 'active'
  AND e.direct_manager_id IS NULL
  AND COALESCE(r.roles, '') !~ '(^|,)(ceo|admin)(,|$)'
ORDER BY e.employee_no;

主管停用或主管链断裂：

SELECT e.employee_no, e.name, m.employee_no AS manager_no, m.name AS manager_name, m.status AS manager_status
FROM employees e
LEFT JOIN employees m ON m.id = e.direct_manager_id
WHERE e.status = 'active'
  AND e.direct_manager_id IS NOT NULL
  AND (m.id IS NULL OR m.status <> 'active' OR m.archived_at IS NOT NULL)
ORDER BY e.employee_no;

待办分配给停用审批人或无有效角色持有人：

SELECT t.id AS task_id, wi.entity_type, a.employee_no AS assignee_no, a.name AS assignee_name, a.status AS assignee_status
FROM workflow_tasks t
JOIN workflow_instances wi ON wi.id = t.instance_id
LEFT JOIN employees a ON a.id = t.assignee_id
WHERE t.status = 'pending'
  AND t.assignee_id IS NOT NULL
  AND (a.id IS NULL OR a.status <> 'active' OR a.archived_at IS NOT NULL)
ORDER BY t.created_at;

SELECT t.assignee_role, count(*) AS pending_count
FROM workflow_tasks t
WHERE t.status = 'pending'
  AND t.assignee_role IS NOT NULL
  AND NOT EXISTS (
    SELECT 1
    FROM employee_roles er
    JOIN employees e ON e.id = er.employee_id
    WHERE er.role_code = t.assignee_role
      AND e.status = 'active'
      AND e.archived_at IS NULL
  )
GROUP BY t.assignee_role
ORDER BY t.assignee_role;

admin-only 误用为业务审批：

WITH role_summary AS (
  SELECT employee_id, string_agg(role_code::text, ',' ORDER BY role_code::text) AS roles
  FROM employee_roles
  GROUP BY employee_id
)
SELECT t.id AS task_id, wi.entity_type, e.employee_no, e.name, r.roles
FROM workflow_tasks t
JOIN workflow_instances wi ON wi.id = t.instance_id
JOIN employees e ON e.id = t.assignee_id
JOIN role_summary r ON r.employee_id = e.id
WHERE t.status = 'pending'
  AND r.roles ~ '(^|,)admin(,|$)'
  AND r.roles !~ '(^|,)(manager|ceo|finance|finance_mgr|hr)(,|$)'
ORDER BY t.created_at;

SELECT id, name, level1_role, level2_role, level3_role
FROM approval_rules
WHERE enabled = true
  AND 'admin' IN (level1_role::text, COALESCE(level2_role::text, ''), COALESCE(level3_role::text, ''))
ORDER BY priority;

财务和系统管理员混授：

WITH role_summary AS (
  SELECT employee_id, string_agg(role_code::text, ',' ORDER BY role_code::text) AS roles
  FROM employee_roles
  GROUP BY employee_id
)
SELECT e.employee_no, e.name, e.status, r.roles
FROM employees e
JOIN role_summary r ON r.employee_id = e.id
WHERE e.status = 'active'
  AND r.roles ~ '(^|,)admin(,|$)'
  AND r.roles ~ '(^|,)(finance|finance_mgr)(,|$)'
ORDER BY e.employee_no;

3.2 WFOC 企微优先与 OA 接管

正常运行时：

  1. HR 先在企业微信通讯录或人事助手维护员工、部门、主管、职位、手机号、邮箱和在职状态。
  2. OA 后续通过 wecom_hr_master_sync_v1 同步员工镜像，自动生成或更新 OA 员工档案、账号、角色、企业微信绑定和审计记录。
  3. 员工请假、补卡、外出、加班优先在企业微信原生审批中提交和处理。
  4. OA 后续先通过 WARCH1 保存企微审批、打卡和人事关键历史，再通过 wecom_attendance_approval_mirror_v1 增强审批详情、审批历史、附件、状态回调、打卡规则、排班、记录、日报、月报和异常摘要查询；该命名承接旧口径 wecom_native_approval_mirror_v1。
  5. 报销、PDF OCR、付款批次、银行回单、AP 台账和代账交接仍在 OA 内完成，不迁移到企业微信。
  6. 采购、费用、合同、项目、报销、付款、AP、代账交接和高敏附件继续 OA 主办；采购单附件、合同正文、报价、供应商资料、发票、银行回单和代账资料不进入企业微信原生审批或企业微信附件。
  7. OA 主办审批仍可向企业微信个人应用发送脱敏消息；消息点击后通过免登录或账号绑定回到 OA 目标审批页，审批动作仍在 OA 完成。

WARCH1 后的管理员关注点：

  1. WARCH1 已实现最小历史留存：先保存请假/补卡审批历史、回调事件、补偿拉取记录和必要员工映射，保证企微 API 不可用时仍可查看已保存历史摘要。
  2. 回调 Token、EncodingAESKey、Secret 和 access token 只配置在部署环境，不写入文档、Issue、聊天或报告。
  3. OA 数据库可保存完整 sp_no、template_id 和企微 userid 以便补偿和审计；对外报告、日志和导出默认脱敏。
  4. 同意单击即通过是企业微信端交互特性，管理员应通过操作规程要求审批人先看详情再同意；OA 后续通过历史留存、审批轨迹和补偿对账提供追溯。

企微不可用时：

  1. 管理员人工判断故障后开启 oa_hr_emergency_mode_v1，不得因短时 API 异常完全自动切换。
  2. 开启时必须填写原因、影响范围、预计结束时间和责任人。
  3. OA 临时开放请假、补卡、外出、加班提交和审批，所有单据带 EMERGENCY 标记。
  4. 故障结束后关闭应急入口，执行恢复对账。
  5. wecom_recovery_writeback_v1 先 dry-run，再对无冲突应急数据自动回写企微；冲突、权限不足、API 不支持或风险过高时进入人工确认。

RuleOps：

  • wecom_ruleops_v1 允许 AI 草拟企微审批模板、打卡规则、排班、假期余额和人事字段配置建议。
  • 正式写入前必须人工确认；每次写入保存前后快照、确认人、API errcode、失败原因、回滚建议和审计记录。
  • 不得在报告、日志或截图中暴露 Secret、access token、完整位置、人脸数据、身份证号、完整手机号或原始密钥材料。

WCP1/WCPC/WHMS 后续推进：

  1. 继续先读取 企微优先开发路线图 和 WCP1 报告，再判断能否进入下一阶段。
  2. WCP1 历史结论为 PAUSE_FOR_CONFIG；WCPC 已用既有在职测试号完成远端只读复跑，报告 /tmp/wecom-capability-poc-wcpc-smoke002/summary.json，结论 GO_TO_HR_MASTER_SYNC。
  3. WCPC 已证明 HR 主数据镜像准入项可用：通讯录成员读取、人事助手花名册读取、打卡短窗口记录/规则读取和假期余额读取均达到可复用状态；审批模板、审批实例和回调配置仍是后续考勤/审批镜像前置项。
  4. WHMS 已实现并部署验证 wecom_hr_master_sync_v1，包括同步批次、逐员工结果、dry-run/apply、People 管理入口和 QA-only runner；公网验证后最终保持 force_off。
  5. 正式开发仍按 wecom_hr_master_sync_v1 -> runtime_first_wecom_enablement -> WOUA-FIX / WECOM-RUNTIME-READY-V1 -> WAPC1 审批配置准备 -> WAPC2 请假/补卡只读 POC -> WAPC2F 自动生成 POC 样件 -> WAPC2FLIVE live 创建与 WAPC2 自动复跑 -> WCBK1 回调只读 POC -> WEGOV1 企微主办治理与自建留存路线修正 -> WACP3/WACP3R 补偿拉取 POC -> WREAD1 审批可读性与误审批防护门禁 -> WADM1 自建留存/镜像数据模型设计 -> WARCH1 最小自建历史留存实现 -> wecom_attendance_approval_mirror_v1 -> oa_hr_emergency_mode_v1 -> wecom_recovery_writeback_v1 -> wecom_ruleops_v1 分合同实施；WOUA-FIX 已收口测试账号差异和处理决策，WRV1/WRA1/WMSG1 已验证运行入口、OAuth/绑定、脱敏消息、Deeplink、通讯录、人事助手和打卡读取主链路。WAPC2FLIVE 已生成请假/补卡低风险样例，WCBK1 已证明真实审批回调 URL、验签/解密和事件脱敏留证，WACP3R 已证明请假/补卡补偿拉取和详情读取可用，WREAD1 已确认请假/补卡可读性，WADM1 已明确自建留存模型，WARCH1 已实现最小请假/补卡历史留存；后续仍不得跳过正式查询、外出/加班、打卡细项等独立合同直接进入深度考勤/审批镜像。
  6. 任何生产写接口、企微规则写入、应急模式开启或恢复回写都必须有单独批准、dry-run 或可审计记录。

WCPC 配置复跑清单：

  1. 已完成：自动查找并指定已有在职测试号 SMOKE002/测试员工；未使用已离职/禁用的 HRWDTEST-20260517214548 作为主测试成员。
  2. 已完成：服务器复跑采用临时环境变量和既有容器配置，不持久写入 .env，不重启服务；报告落到远端 /tmp/wecom-capability-poc-wcpc-smoke002/summary.json。
  3. 已完成：复跑结论 GO_TO_HR_MASTER_SYNC，该准入已由 WHMS 承接并完成本地实现。
  4. 后续考勤/审批镜像前仍需补齐：外出/加班样例、批量补偿拉取、镜像数据模型和 HR 写接口单独 POC；请假/补卡 OA-POC 回调真实事件已由 WCBK1 验证。
  5. WAPC1 已固定首批审批配置准备范围：请假、补卡、外出、加班；每个模板需记录模板 ID、适用范围、字段项、审批人规则、可见范围和所属自建应用权限。
  6. 测试审批单不得上传采购、合同、报销、发票、银行回单或其他敏感附件；Secret、Token、EncodingAESKey 不在聊天中明文发送。

WHMS 管理操作口径：

  1. 当前 wecom_hr_master_sync_v1 已部署并完成受控公网验证，但最终默认保持 force_off；正式批量同步真实员工前必须另行批准。
  2. 在 人员管理 的“企微 HR 主数据镜像”卡片先执行 同步预检；预检只生成差异和同步记录，不写员工主数据。
  3. 确认差异后再执行 确认写入；生产真实员工批量 apply 必须另有批准，不在日常巡检中自动触发。
  4. 缺姓名、手机号、邮箱或部门时系统跳过并记录 missing_required_field，管理员应先回企微/人事助手补齐，不在 OA 造占位数据。
  5. 企微不在职或禁用状态只记录 needs_offboarding_confirmation，管理员按 OA 离职 checklist 处理，不由同步任务静默禁用账号。
  6. 同步报告、日志和审计只看脱敏摘要；不得导出完整手机号、邮箱、userid、Secret、access token 或企微原始 payload。
  7. WHMSLIVE 验证证据：SMOKE002/测试员工（脱敏 oa_smoke***）dry-run 和显式 userids apply 已在公网执行；因企微侧缺手机号、邮箱和部门按 missing_required_field 跳过，未写 OA 主数据；普通员工访问同步 API 返回 403。

WRV1 运行优先检查口径：

  1. 管理员或 QA 在服务器容器内执行 npm run check:wecom-runtime-ready -- --live --format=json，报告写入 artifacts/qa-flow/wecom-runtime-ready-<timestamp>/summary.json。
  2. 报告结论为 PASS_RUNTIME_READY 时，入口、OAuth、绑定、消息 dry-run、通讯录/人事助手/打卡只读链路和后续配置均可用。
  3. 报告结论为 PASS_WITH_CONFIG_GAPS 时，运行优先主链路可用，但审批模板、测试 sp_no、回调、补偿拉取或镜像模型等后续项仍可能缺配置；这不允许直接开发考勤/审批镜像。
  4. 报告结论为 SKIP/BLOCKED_BY_EXTERNAL_CONFIG 时，先检查对应 Secret、可信 IP、应用可见范围、授权、企微 API 权限或数据库只读能力，不能把 SKIP 记录为成功。WRA1 后，WECOM_CHECKIN_SYNC_ENABLED 仅控制正式考勤同步批次，不作为 QA-only 打卡只读探测的硬阻断。
  5. 默认不发送真实企微消息；如需低风险消息验证，必须同时设置 WECOM_RUNTIME_TEST_SEND=1 并传 --send-test-message，消息内容仅含标题、类型、编号、状态和 OA deeplink。

WAPC1 审批配置准备清单：

  1. 首批模板只准备 HR/考勤员工日常审批：请假、补卡、外出、加班。
  2. 每个模板准备模板 ID、适用范围、字段项、审批人规则、可见范围和所属自建应用权限；暂不创建 OA 镜像表或真实回调接收端。
  3. 测试审批单 sp_no 必须为低风险样例，不包含采购、合同、报销、发票、银行回单、高敏附件或真实敏感业务资料。
  4. 回调配置只在部署环境保存真实值；文档、Issue 和聊天只写配置项名称，如 WECOM_APPROVAL_CALLBACK_URL、WECOM_CALLBACK_TOKEN、WECOM_CALLBACK_ENCODING_AES_KEY。
  5. 后续进入 POC 前必须确认：模板详情读取、审批详情读取、回调 URL 验证、事件验签、解密、幂等键、重试语义和补偿拉取方案。
  6. 批量获取审批单号只作为补偿拉取候选，先标记 NEEDS_API_POC。

WCBK1 回调只读 POC：

  1. 当前公网 Callback URL 应配置为 https://oa.hyinda.com/api/wecom/approval/callback。
  2. 部署环境变量只写名称，不在文档或聊天保存真实值：WECOM_APPROVAL_CALLBACK_URL、WECOM_CALLBACK_TOKEN、WECOM_CALLBACK_ENCODING_AES_KEY。
  3. npm run check:wecom-approval-callback-poc -- --live 已在远端达到 PASS_CALLBACK_URL_VERIFIED，随后由 SMOKE101 在企业微信处理一条现有 OA-POC 补卡测试审批单，复跑达到 PASS_CALLBACK_EVENT_CONFIRMED。
  4. 后续如更换回调 URL、Token 或 EncodingAESKey，必须先同步部署环境并重启 server，再在企微后台保存；不得把真实密钥写入仓库、文档或聊天。
  5. 报告只保存事件类型、审批类型、状态摘要、脱敏 sp_no/模板前缀和幂等键摘要；不得截图、转存或粘贴 Token、EncodingAESKey、原始 XML、密文、完整 sp_no、完整 userid、表单值、附件或评论。

WEGOV1 自动化与人工边界：

  1. 我可以自动完成：Issue CSV、文档回写、runner、synthetic 测试、API 只读探测、回调验签/解密测试、补偿拉取测试、脱敏报告、受控部署、/ready、公网 runner 复跑、状态回填和中文提交。
  2. 管理员或用户必须人工处理：企微后台无法 API 化配置、Secret/Token/EncodingAESKey 填入部署环境、可信 IP/可见范围调整、正式写入批准、真机收到消息/点击/审批可读性确认、是否启用正式批量同步或应急模式的风险拍板。
  3. 企业微信自建应用没有完整隔离 sandbox 假设；后续测试默认使用真实企业内受控测试域：SMOKE002 -> SMOKE101、OA-POC 模板、低风险审批单和脱敏报告。
  4. OA 后续保存企微关键历史和完整外部关联键；V1 目标是企微不可用时能查看历史，不是完整替代企微继续办理。

WAPC2 请假/补卡只读 POC 操作口径：

  1. 优先用 WAPC2F runner 自动生成 OA-POC 请假/补卡测试模板和低风险测试审批单；当前 dry-run 已通过，真实创建模板/审批单前仍需管理员批准单次 live 写入。
  2. WAPC2F 默认申请人为 SMOKE002，审批人为 SMOKE101；两者必须 active、已绑定企微、可见、不是同一 OA 员工、不是同一企微 userid。SMOKE101 不可用时不自动换人，先问答确认。
  3. WAPC2F live 写入只能在单次命令同时包含 --live --create-templates --submit-test-approvals 且设置 WECOM_APPROVAL_FIXTURE_WRITE=1 时执行；默认 dry-run 不获取写入 token、不在企微后台留下 OA-POC 记录。WAPC2FLIVE 已执行一次批准的 live 创建，后续不得重复创建样件，除非另建 Issue CSV 并再次批准。
  4. 测试单 sp_no 不得包含采购、合同、报销、发票、银行回单、高敏附件或真实敏感业务资料。
  5. QA 在服务器容器内执行 npm run check:wecom-approval-poc -- --live --format=json，并通过 CLI 或临时 env 传入请假/补卡模板 ID 和 sp_no。
  6. 报告结论 PASS_APPROVAL_POC 只代表模板详情和审批详情只读链路可用；PARTIAL_APPROVAL_POC_NEEDS_CONFIG 代表缺模板 ID 或 sp_no；SKIP/BLOCKED_BY_EXTERNAL_CONFIG 代表 Secret、权限、可信 IP、可见范围或企微 API 阻断。
  7. 报告只看脱敏模板 ID/sp_no 前缀、字段类型计数、审批节点计数和错误分类；不得截图或转存完整 sp_no、表单值、附件、评论、Secret、token 或原始 payload。

3.3 正式财务闭环与代账交接

公司当前没有 ERP 或独立财务系统，OA 不生成 ERP 实时凭证，也不接真实支付接口。正式财务闭环如下：

  1. 员工在 OA 提交报销，发票/OCR 正式入口保持 PDF-only，图片只作为普通附件。
  2. 直属主管、财务或负责人按审批规则在 OA 内完成审批。
  3. wangzhiling 作为出纳，在付款批次中创建待付款批次，按批次准备对公银行付款。
  4. wangshunli 以管理员身份复核付款批次；管理员复核是当前明确业务选择，系统保留 maker-checker 和审计记录。
  5. 出纳在 OA 外通过网银或银行渠道付款，然后在付款批次详情上传银行回单附件，补齐凭证号、付款日期和付款渠道。
  6. 出纳执行 OA 已付款标记；系统将报销单置为 paid，票据归档为 archived，AP 台账变为已付款状态。

银行渠道付款必须至少有一份银行回单附件后才能在 OA 内执行付款标记。回单附件支持 PDF、JPG、PNG、WEBP，作为批次级付款证据保存；导出和报告中不复制回单原件内容。

月度代账交接按以下清单执行：

资料 来源 负责人 说明
AP 台账导出 OA AP 运营 出纳/财务 用于核对已付款、待付款和异常项；AP 台账不是银行流水
报销导出 OA 报销导出 出纳/财务 按月导出，必要时筛选已通过或已付款状态
票据中心导出 OA 票据/OCR 出纳/财务 用于核对 PDF 发票识别、绑定和归档状态
付款批次清单 OA 付款批次 出纳/财务 记录批次、复核、执行和对应报销单
银行回单附件清单 OA 付款批次详情 出纳 只交接清单和必要回单原件，不把真实回单提交到代码仓库
审计日志导出 OA 审计日志 管理员 覆盖导出、付款批次创建、复核、回单上传和执行动作
银行流水和回单原件 网银或银行渠道 出纳 由出纳从银行侧导出，交给代账人工核对；不导入 OA

交接建议：

  • 每月固定一个交接目录或压缩包，由出纳线下维护，命名建议为 YYYY-MM-海音达-代账交接。
  • OA 导出文件、银行流水、银行回单原件和异常说明分目录保存；仓库只记录流程和脱敏证据，不保存正式财务资料。
  • 代账如发现金额、收款方、日期或票据状态不一致，先回查 OA 报销单、付款批次、银行回单和审计日志，再决定是否由出纳补充说明。
  • 若代账方后续要求一键交接包，再另建开发合同，明确包内文件、权限、脱敏、审计和下载回滚规则。

3.4 首周正式使用运营

首周支持分工：

职责 负责人 处理范围
上线拍板和回滚决策 wangshunli 判断继续、暂停、回滚或另建修复合同
管理员复核 wangshunli 付款批次复核、权限和审计核查
出纳/付款执行 wangzhiling 银行对公付款、回单上传、付款标记和代账资料准备
问题登记 wangshunli 汇总问题、分级、每日收口和结论回写

首周每日巡检：

  1. 访问 https://oa.hyinda.com/ready，确认公网健康。
  2. 用管理员和普通员工各登录一次，确认 PC 和移动入口可达。
  3. 抽查审批待办、报销/PDF OCR、请假、采购、通知和企业微信入口。
  4. 抽查 payment_batch_v1 仍为开启、erp_sync 仍为关闭。
  5. 出纳查看待付款、付款批次、银行回单附件和 AP 台账导出。
  6. 管理员查看审计日志中是否有异常导出、权限拒绝或付款动作。
  7. 记录当天新增问题、影响等级、处理人、结论和是否需要暂停。

问题登记最小字段：

字段 说明
时间 发现时间，精确到日内即可
角色/账号 员工、审批人、财务、管理员或企业微信入口
页面/入口 PC、移动、企业微信、付款批次、报销、审批等
复现步骤 只写必要步骤，不记录密码、token、银行回单原件或完整票面
影响等级 阻断、高、中、低
处理结论 已解释、已修复、待修复、暂停、另建 Issue

暂停条件：

  • 无法登录、无法进入企业微信工作台或公网 /ready 异常。
  • 无法提交或审批报销、请假、采购任一主流程。
  • 付款批次状态错误、回单附件丢失、AP 导出异常或审计缺失。
  • 员工、审批人、出纳、管理员出现越权访问。
  • payment_batch_v1 意外关闭，或 erp_sync、图片 OCR、真实支付、银行流水导入被误开启。
  • 同一天出现多个高优先级问题且无法解释清楚。

首周不主动新增可选功能。UX8 只接真实反馈或自动化确定性失败；移动采购创建、通知扩展、合同/供应商/资产、图片 OCR、真实支付、银行流水导入、复杂 BPM、审批设计器和重预算都必须另建独立合同；ERP 不再作为后续合同候选。

4. 人员生命周期管理

4.1 入职

  1. 在 人员管理 创建员工账号。
  2. 打开员工详情页，补齐部门、职位、直属上级、试用期结束日、工作地点、紧急联系人。
  3. 若已开启 hr_wecom_directory_sync_v1 且企业微信通讯录配置完整，创建或发起入职时系统会尝试创建企业微信成员；HCLT 已验证公网真实写入闭环，缺 Secret、缺默认部门或无通讯录权限时记录 SKIP/BLOCKED_BY_EXTERNAL_CONFIG，OA 入职不回滚。
  4. 发起 入职，系统会自动生成 checklist：账号初始化、资产发放、制度确认。
  5. checklist 全部完成后，员工状态自动从 onboarding 进入 probation。
  6. 人员列表或员工详情中的“企业微信通讯录”状态若为同步失败或配置缺失，管理员可在配置修复后执行“重试同步”。

4.2 转正 / 调岗

  • 转正：记录事件并将员工状态改为 active。
  • 调岗：当前记录部门、直属上级、职位调整，同时生成调岗交接 checklist；WFOC 后目标是从企微/人事助手同步到 OA，OA 管理员修复需写原因和审计。
  • 这两个动作只做管理留痕，不引入复杂审批流。

4.3 离职

  1. 发起 离职 后，系统自动生成离职 checklist：资产归还、权限回收、费用与审批清理、交接说明。
  2. 若员工仍有名下资产或待处理审批任务，系统不会自动完成离职。
  3. checklist 完成且阻塞清零后，OA 账号会被停用并吊销现有会话，主业务入口对该账号不可再用。
  4. 当前离职完成后系统默认尝试禁用企业微信成员，不删除企业微信成员；WFOC 后目标是企微离职/禁用状态同步到 OA，OA 禁用账号并吊销会话。

5. 团队状态与考勤口径

  • 员工每天可在 Portal 或 团队 页更新状态：在岗 / 居家 / 外出 / 出差。
  • 已批准请假会自动覆盖当天状态为 请假。
  • 企业微信打卡作为原始采集和规则执行工具；定位、人脸、Wi-Fi、设备和排班规则不在 OA 内重造。
  • 当前 OA 已完成请假审批、补卡/外出/加班修正审批和月度考勤解释；WFOC 后这些能力默认作为历史查询和应急接管基础。
  • 历史 attendance_v1 是 OA 极简打卡和管理员补卡能力，不等同于企业微信打卡风控；该入口已关闭，旧写接口返回可解释 409，历史表保留。
  • OA 后续同步企业微信打卡规则、排班、记录、日报、月报和 HR/考勤审批镜像，形成正式考勤口径；缺企微打卡 Secret 或 API 权限时，同步批次按 SKIP 记录。
  • 请假、补卡、外出、加班正常在企业微信内完成；OA 仅在管理员开启应急模式时接管，恢复后 dry-run 并自动回写企微。

6. 周报与待办

  • 周报固定三段：本周完成 / 当前阻塞 / 下周计划。
  • 建议每周五下班前提交，周一老板看团队汇总。
  • 需要跟进的事项可从周报沉淀为待办。
  • 高优先级待办建议由老板或管理员统一看板跟进。

7. 公告与 Portal 使用建议

  • 公告只发公司级通知、制度更新、假期提醒，不做复杂 CMS。
  • Portal 首屏建议重点看：
    • 今日团队状态
    • 未提交周报人数
    • 需协助员工
    • 入/离职待办
    • 资产待归还
    • 审批待办

8. 备用模块治理

  • 采购/费用、合同/附件和项目轻管理属于 P1 轻量能力，可在 P0 报销/OCR、财务闭环、企微 HR/考勤镜像和企业微信入口稳定后逐步开放。
  • 支付批次和 AP 运营已作为正式财务闭环开放给出纳、财务和管理员；普通员工仍不显示财务运营入口。
  • 预算、AI、完整差旅、资产深度管理等保留代码和历史数据，但不作为当前 MVP 首批主路径；ERP 保持关闭，不再规划接入。
  • 若短期完全不用，保持管理员可见即可，不必删除。
  • 只有出现真实场景时，再恢复到主导航或单独扩展。

9. 推荐上线顺序

  1. 先完成账号、角色、部门、企业微信自建应用入口和账号密码回退路径。
  2. 再启用 OA 统一审批中心 + 报销/发票/OCR/附件，跑通提交、审批、退回、查重、付款和导出闭环。
  3. 同步启用付款批次、AP 台账和银行回单附件，付款动作仍由出纳在 OA 外通过银行渠道完成。
  4. 先以企业微信作为请假、补卡、外出、加班和打卡主操作端；OA 侧按后续合同逐步启用 HR 主数据镜像、企微审批/考勤镜像、人工接管和恢复回写。
  5. 在 P0 稳定后开放 P1：采购/费用审批、合同/附件归档、项目轻管理。
  6. 最后按真实需要评估周报、团队状态、公告、资产、预算、AI 和完整差旅；ERP 不进入评估队列。

10. 试点验收口径

  • 全员都能账号密码登录；已绑定员工能从企业微信 海音达工作台 进入移动工作台。
  • 至少 1 笔报销完成：上传发票或附件 -> OCR/查重 -> 提交 -> OA 审批 -> 财务复核/付款标记 -> 导出。
  • 至少 1 个付款批次完成：出纳创建 -> 管理员复核 -> 出纳上传银行回单 -> 执行 OA 已付款标记 -> AP 台账和审计可查。
  • 后续 WFOC POC 至少 1 条企微请假和 1 条企微考勤修正完成：员工在企微提交 -> 企微审批 -> OA 镜像可查；应急模式另以测试窗口验证，不默认常开。
  • 至少 1 个审批待办从企业微信提醒 deeplink 回到 OA 页面处理。
  • P1 试点时，至少 1 条采购/费用申请、1 条合同台账、1 个项目关联事项可创建、审批或归档。
  • 正式使用前至少完成一次备份可用性核对；真实恢复演练必须另建批准合同，并记录恢复后的 /ready 结果。
  • 普通员工主导航不出现预算、AP、AI、完整差旅等当前首批不开放的备用模块；ERP 入口保持关闭。

11. 4 周观测操作法

  1. 每周一进入 Portal、审批待办 和 考勤 查看近 7 天登录覆盖率、审批积压、报销/OCR 异常、请假/考勤修正审批和企业微信入口错误；企微打卡同步缺已授权应用 Secret 或 API 权限时记录为 SKIP。
  2. 每周五记录本周结论、关键阻塞、是否需要调整审批规则、报销规则、企业微信入口或导航。
  3. 若某周出现员工未登录、报销长期停留、发票重复处理不清、审批积压或企业微信绑定异常，优先修正规则和入口，不额外维护表格作为正式记录。
  4. 连续 4 周都达到预期后，再扩大到 P1 采购/费用、合同归档和项目轻管理试点。

12. 企业微信入口与登录策略

  • 企业微信定位为 入口 + 免登 + 通知 + 打卡原始采集 + HR/考勤员工日常审批，不承载 OA 主办的采购、合同、项目、报销或财务审批。
  • 公司只维护一个企业微信自建应用，建议命名为 海音达工作台。
  • 默认工作台入口在企业微信手机端落到 /mobile；桌面浏览器和账号密码登录仍进入 /portal。OA 主办业务的真正操作仍在 hyb-oa 内完成。
  • 已上线的报销、采购、费用、合同、项目和财务类 OA 主办审批都在 OA 内提交和审批；企业微信消息只负责脱敏提醒并 deeplink 回 OA。请假、补卡、外出、加班后续按 WFOC/DBWFOC 迁往企业微信原生审批，OA 同步镜像并保留应急入口。
  • 企微免登建议先完成账号绑定，再逐步在试点部门开启；任何时候都保留账号密码回退。
  • 若 OA 部署到公网，生产建议同时满足：HTTPS、COOKIE_SECURE=true、登录失败锁定、限流、审计开启。

正式接入最小步骤

  1. 在企业微信管理后台创建或编辑唯一自建应用：海音达工作台。
  2. 将工作台入口配置为：https://oa.hyinda.com/api/auth/wecom/login?returnTo=%2Fmobile。
  3. 将 OAuth 回调地址配置为：https://oa.hyinda.com/api/auth/wecom/callback。
  4. 在 deploy/trialrun/.env 中补齐并开启：
    • WECOM_ENABLED=true
    • WECOM_ENTRY_ENABLED=true
    • WECOM_OAUTH_ENABLED=true
    • WECOM_CORP_ID=...
    • WECOM_AGENT_ID=...
    • WECOM_AGENT_SECRET=...
    • WECOM_REDIRECT_URI=https://oa.hyinda.com/api/auth/wecom/callback
    • WECOM_ALLOWED_RETURN_HOSTS=oa.hyinda.com
  5. 先让管理员用账号密码登录，在 个人设置 完成一次绑定，再测试企业微信工作台直达；已绑定用户从手机企业微信进入时应直接看到移动工作台。
  6. 若启用 OA 同步企业微信打卡数据，在企业微信打卡 API「可调用接口的应用」中授权 海音达工作台。OA 默认可复用 WECOM_AGENT_SECRET；只有单独创建考勤同步应用时才额外配置 WECOM_CHECKIN_SECRET。
  7. HR/考勤员工日常审批后续配置企业微信原生审批模板作为主流程；WAPC2FLIVE 已自动生成请假/补卡 OA-POC 低风险样件并复跑只读 POC，WCBK1 已完成真实回调事件确认，WACP3R 已完成补偿拉取，WREAD1 已确认请假/补卡在企微中可读，WADM1 已完成自建留存/镜像模型设计，WARCH1 已完成最小请假/补卡历史留存。同意单击即通过需继续纳入操作提示和审计设计。外出/加班模板仍需后续单独配置或 POC。报销、财务、采购、合同和项目类 OA 主办审批仍使用企业微信消息提醒并回到 OA 页面完成。

员工会看到的典型状态

  • 未绑定：登录页会提示“当前企业微信账号尚未绑定”，回退到账号密码登录。
  • 已绑定：从企业微信工作台进入后直接落到 /mobile，桌面或普通浏览器场景仍可进入 Portal。
  • 入口未开放：个人设置仍可绑定，但登录页不会把企业微信作为正式入口展示。
  • 配置不完整：个人设置会明确提示缺少 CorpID / AgentID / 回调地址 等原因。
  • 收到审批提醒：点击后进入 OA 审批页，在 OA 中同意、驳回、退回或转审。

13. 轻项目管理使用建议

  • 项目主档只做轻量管理：成员、里程碑、任务、风险、交付记录、合同台账与资料引用。
  • 不要把 hyb-oa 推成完整项目组合平台；甘特图、资源排产、CRM 仍不在本主线。
  • 员工日常动作建议统一挂项目：
    • 差旅申请挂项目
    • 报销单挂项目
    • 周报按项目拆分进展
    • 待办可直接挂项目
  • 管理层每周主要查看 项目 页中的逾期里程碑、高优任务、风险与费用/出差汇总，而不是再维护第二套项目台账。

14. 涉密边界

  • hyb-oa 只记录涉密合同或资料的元数据：编号、责任人、密级、归档位置、离线档案号。
  • 涉密正文、涉密附件、详细报价/成本/毛利、敏感客户资料不进入公网 OA。
  • 企业微信通知不得发送涉密正文，只保留最小必要信息和 deeplink。
  • 企业微信审批不作为涉密或财务审批载体，正式审批记录以 OA 审批历史和审计日志为准。
  • 采购单附件、合同正文、报价、供应商资料、发票、银行回单和代账资料不上传到企业微信原生审批或企业微信附件；企业微信只保留脱敏标题、编号、状态和 OA 链接。
  • 如项目被标记为涉密，管理员应要求正文继续保存在内网文件盘、NAS 或离线档案中。

15. 初始化与导入建议

  1. 首次上线先完成系统初始化：数据库迁移、配置种子、管理员种子。
  2. 不要直接把开发库、测试库或旧 OA 整库导入到生产。
  3. 如需导入，只导最小必要主数据：
    • 部门
    • 员工
    • 角色
    • 在用资产
    • 活跃项目
    • 合同元数据
  4. 不导入这些内容：
    • 历史审批单
    • 通知历史
    • 审计日志
    • 聊天记录
    • 涉密正文与附件
  5. 建议顺序：初始化系统 -> 管理员登录验证 -> 最小主数据导入 -> 小范围试点 -> 全员启用。

16. 公网部署最低建议

  1. 为 OA 配置独立 HTTPS 域名，例如 https://oa.example.com。
  2. 在 deploy/trialrun/.env 中设置：
    • APP_ORIGIN=https://oa.example.com
    • COOKIE_SECURE=true
    • PUBLIC_SECURITY_HARDENING_ENABLED=true
  3. 若启用企业微信入口，补齐：WECOM_* 与 WECOM_ALLOWED_RETURN_HOSTS。若启用 OA 驱动企业微信通讯录同步，还需补齐 WECOM_CONTACT_SYNC_ENABLED=true、WECOM_CONTACT_SECRET、WECOM_CONTACT_DEFAULT_DEPARTMENT_ID，并确认该 Secret 具备通讯录写权限。若启用企微打卡同步，确认 海音达工作台 已被授权调用打卡 API；WECOM_CHECKIN_SECRET 留空时复用 WECOM_AGENT_SECRET，单独考勤同步应用才需要填写独立 Secret。若启用企微 HR 主数据镜像，按 WAPI 口径确认通讯录读取使用 WECOM_CONTACT_SECRET、人事助手/花名册读取使用 WECOM_AGENT_SECRET；正式批量 apply 仍由 wecom_hr_master_sync_v1 feature flag 和单独批准控制。
  4. 将 OPENAPI_DOCS_ENABLED 保持为 false，不要在公网生产暴露文档入口。
  5. 定期检查审计日志中的登录失败、Refresh 来源不匹配与涉密资料查看记录。
  6. 准备独立 smoke 账号，不使用老板、管理员或真实员工日常账号跑自动化；smoke 账号的角色和直属上级应按正式审批链配置。
  7. 每次正式发布前记录备份文件名、恢复负责人和上个可回滚 tag。

17. 网页自动化门禁（R28/R30）

  • 推荐发布时直接执行：bash scripts/qa/run-release-gate.sh all。
  • 发布前至少执行一次：bash scripts/qa/run-web-gates.sh smoke-local。
  • 发版前或主分支合并前建议执行：bash scripts/qa/run-web-gates.sh full-local。
  • 发布到 https://oa.hyinda.com 后，使用独立 smoke 账号执行：bash scripts/qa/run-web-gates.sh smoke-live。
  • live smoke 只做只读检查，不允许提交审批、付款、导入或任何真实业务写操作。
  • 如果本机已配置 LIVE_SMOKE_*，bash deploy/trialrun/deploy.sh 完成远端部署后会自动补跑 live smoke。
  • 首次接入企微、SMTP 或证书变更可人工复核；日常发布不再要求手点页面验收。

18. R23 试点收口纪律

  • 客户沟通如果影响项目计划、交付、报价、风险或下一步动作，必须在 24h 内回填到 项目 -> 客户沟通。
  • 回填只写结果摘要、下一步动作和下次跟进日期，不粘贴完整聊天记录，不上传私人微信截图。
  • 项目经理每周至少检查一次 项目 -> 项目收口 面板，确认红黄灯来源是否已经处理。
  • 若某项收口任务选择 已豁免，必须填写理由；豁免不代表永久忽略，只代表本周软约束放行。
  • 试点期每周五复盘一次“仍靠聊天/表格补流程”的案例，并决定是补回填纪律还是补最小功能。

19. R29 设计与工作台治理口径

  • 首页不再做“模块超市”，而是先告诉员工今天该做什么。
  • 管理员不要把备用模块重新平铺到主导航，避免系统再次变成模块拼盘。
  • 员工入口默认认知应保持为：企业微信进入 -> OA 移动工作台 -> 进入审批/报销/请假等模块处理；PC 用户可直接登录 OA。
  • 如果未来新增页面，请优先复用统一骨架：
    • 首页：WorkbenchHero + MetricCard + SectionPanel
    • 列表页：PageHeader + FilterBar + 主列表
    • 详情页：概览 -> 执行 -> 留痕 -> 归档/合规
  • 若某页面出现两个以上竞争级主按钮，应视为设计回退并在上线前修正。
在新工单中引用 查看 Git Blame 复制永久链接