hyb-oa/docs/产品口径.md

产品口径文档

来源：2026-03-25 产品需求梳理会话 适用版本：R35 之后

---

平台边界

P0-1 企微优先 + OA 镜像/接管

• WFOC 起，能用企业微信成熟能力的 HR/考勤员工日常审批优先使用企业微信；OA 做按域镜像、人工接管、恢复回写、财务闭环和审计中台。
• DBWFOC 后固定数据边界：企业微信成熟功能可作为流程、字段、交互和规则参考，但不默认成为高敏业务数据托管处。
• OA 正式定位为本公司 5–10 人使用的财务与低频台账后台：报销、费用、票据/OCR、审批、财务付款、AP 台账和代账交接由 OA 主办并推动真实使用；采购、合同、资产作为低频高失败成本台账保留冻结；审计和敏感附件继续由 OA 留痕。项目主域当前无真实使用证据，保持冻结，不作为日常主流程扩建。
• 财务主办口径限定为付款准备、付款批次、回单留痕、AP 状态、票据/OCR 状态和代账交接摘要；真实付款继续在线下银行或既有财务/代账流程完成，OA 不做银行直连、银行流水自动导入、ERP/总账、凭证生成、自动对账或税务申报。
• 请假、补卡、外出、加班等 HR/考勤员工日常审批优先在企业微信原生审批中提交和处理，OA 同步按域镜像；企业微信不可用时由管理员人工开启 OA 应急模式。
• 企业微信作为手机工作台入口、免登/绑定、通讯录身份、消息通知、打卡、人事助手和 HR/考勤员工日常审批主操作端；OA 主办审批通过企业微信个人应用消息发送脱敏提醒并 deeplink 回 OA 处理。
• WEGOV1 后固定 OA 自建留存目标：OA 数据库保存企微关键历史、完整外部关联键和必要业务快照，用于历史查看、对账、补偿拉取和后续恢复；企微不可用时先保证能查看以前数据，不承诺 V1 完整替代企微继续办理。
• 采购单附件、合同正文、报价、供应商资料、发票、银行回单和代账资料不上传到企业微信原生审批或企业微信附件。
• 简写口径：采购不进企微原生审批，合同不进企微原生审批，附件不进企微附件；企微只做提醒、入口和免登录回 OA。
• WAPI/WRRA/WOUA-FIX 后固定“运行优先 + 差异收口先行”：近期先用入口、免登/绑定、脱敏消息、deeplink、通讯录 userid 清单、人事助手花名册读取和打卡读取；WOUA-FIX 已清零 OA active 缺企微测试账号差异，但 PASS_WITH_FINDINGS 剩余缺字段和归档绑定不直接放行深度镜像。WMSG1 已证明企业微信应用消息和 Deeplink 可用；WAPC1 只固化审批配置准备清单，不代表审批镜像或真实回调已实现。

P0-2 企业微信打卡与 OA 考勤口径

• 企业微信打卡用于原始采集，保留其定位、人脸、Wi-Fi、规则与设备能力。
• OA 后续同步企业微信打卡规则、排班、记录、日报、月报和 HR/考勤审批镜像，形成正式考勤口径。
• 请假、补卡、外出、加班等考勤修正正常在企业微信完成；OA 只在应急模式下接管，并在企微恢复后 dry-run 和自动回写。
• wecom_hr_master_sync_v1 已本地实现并部署公网完成受控验证；最终保持 force_off。WOUA-FIX 已按用户确认软归档 7 个缺企微测试账号，复检 OA active 5、企微 active 5、匹配 5、OA active 缺企微 0；剩余企微缺字段先接受不补，归档绑定保留审计。WCBK1 已完成审批回调 URL 验证和一条真实测试审批事件确认。WACP3R 已自动发现 OA-POC 请假/补卡模板并复跑补偿拉取到 PASS_WITH_FINDINGS，当时 finding 为回调证据文件未持久化；WARCH1 已补齐最小历史留存入库和离线读取能力。WEGOV1 后，后续考勤/审批完整镜像、应急接管、恢复回写或 RuleOps 仍必须另建 wecom_attendance_approval_mirror_v1（承接旧口径 wecom_native_approval_mirror_v1）、oa_hr_emergency_mode_v1、wecom_recovery_writeback_v1 或 wecom_ruleops_v1 合同。

P0-3 按域镜像定义

• 企微主办域镜像到 OA：通讯录/人事助手、打卡、请假、补卡、外出、加班、假期余额和 HR/考勤规则。
• OA 主办域不反向全量镜像到企微：报销、采购、费用、合同、资产、付款批次、AP、代账交接和审计只发送脱敏消息、状态和 OA 链接；项目主域冻结期间不新增企微镜像或日常入口。
• “无痛接管”长期目标只针对必要业务连续性，不承诺把所有 OA 高敏附件和财务资料复制到企业微信。

P0-4 WFDG 设计门禁

• WFDG 后，后续企微/OA 改造必须先按业务域判定主办方、主事实源、操作端、镜像方向、附件归属和审计责任，再拆实现合同。
• PC 和移动页面需要区分三种状态：OA 主办、企微镜像、OA 应急接管；不得把企微镜像页面误做成员工日常新建入口。
• 企业微信同步、镜像和回写必须具备幂等、重试、脱敏日志、审计记录和 SKIP/BLOCKED_BY_EXTERNAL_CONFIG 状态；缺 Secret、权限、模板或可信 IP 时不得伪造成成功。
• 企微能力不清楚时先读 企微 API 能力目录，输出 CAN_REUSE_NOW、NEEDS_CONFIG、NEEDS_API_POC、KEEP_OA_PRIMARY、NOT_SUPPORTED_BY_API 能力矩阵，再进入正式开发。

P0-5 WDRG 开发路线图门禁

• WDRG 后采用“路线图门禁 + 单功能 Trellis task”：路线图只控制阶段顺序、准入/退出门禁、并行规则和禁止跳阶段，具体功能仍单独方案、单独 Trellis task、单独验证。
• 当前企微优先 HR/考勤路线顺序固定为：WECOM-CAPABILITY-POC-V1 -> 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/WARCH2 最小留存和正式只读查询 -> WROAD2/WARCH3/WCHECK1/WEXT1/WOPS1/WAPPR1/WRULE1 -> WTCLOSE2/WREMOTE1/WFULLSMOKE2 远端收口 -> WEXT1-FORMAL 正式模板外出/加班测试 -> WREAL1 小范围真实试用 -> wecom_attendance_approval_mirror_v1 -> oa_hr_emergency_mode_v1 -> wecom_recovery_writeback_v1 -> wecom_ruleops_v1。
• WECOM-CAPABILITY-POC-V1 已由 WCPC 收口，WHMS/WHMSLIVE 已完成 HR 主数据镜像实现和受控公网验证，WOUA-FIX 已完成测试账号差异收口；WRV1/WRA1/WMSG1 固定运行入口、OAuth/绑定、脱敏消息、Deeplink、通讯录、人事助手和打卡只读门禁；WACP3R 已证明请假/补卡补偿拉取和详情读取可用。后续不得跳过审批可读性门禁、镜像数据模型设计、最小历史留存、远端收口、正式模板外出/加班测试和真实小范围试用，直接开发考勤/审批镜像、OA 应急接管、恢复回写或 RuleOps 正式写入。
• 线上缺陷、正式使用阻断、真实反馈扫尾和 QA-only 脚本维护可以另开合同并行；采购、合同、报销、付款、AP、代账和高敏附件继续 OA 主办，不混入企微 HR/考勤路线。
• 路线图事实源为 企微优先开发路线图；该路线图不代表任何运行时迁移能力已完成。
• API 和 Secret 事实源为 企微 API 能力目录：通讯录用 WECOM_CONTACT_SECRET；人事助手、打卡、消息和 OAuth 默认用 WECOM_AGENT_SECRET；不得在运行时代码里轮询多个 Secret 试错。

P0-6 WCP1 企业微信能力 POC 结论

• WCP1 已完成 QA-only 只读 POC，历史结论为 PAUSE_FOR_CONFIG；该阻断已由 WCPC 复跑收口。
• 已可复用：工作台应用 token、核心配置、HCLT 通讯录 create/update/disable 证据、通讯录部门读取、人事助手字段配置读取；WCPC 又确认既有在职测试号的通讯录成员读取、人事助手花名册读取、打卡短窗口记录/规则读取和假期余额读取可用。
• WCP1 初始缺口已留痕：通讯录测试成员读取 wecom_errcode_48009、人事助手测试员工读取 wecom_errcode_60021、打卡同步开关、审批模板 ID、测试审批单号、假期权限 wecom_errcode_301062、回调 URL/Token/AESKey。WAPC2FLIVE 已解决请假/补卡 OA-POC 模板和低风险测试审批单样例；WCBK1 已解决请假/补卡范围内的真实回调 URL 与事件确认；WACP3R 已解决请假/补卡范围内的补偿拉取只读 POC。当前仍未补齐的是正式模板外出/加班测试、真实小范围试用、最小完整镜像，以及 HR 写接口 POC。
• WCP1 报告继续作为初始配置缺口证据保留，当前 HR 主数据镜像准入以 WCPC 结论为准。

P0-7 WCPC 配置复跑口径

• WCPC 只做企业微信后台配置收口和只读 POC 复跑，不改业务代码、不部署、不持久写服务器 .env。
• 已按用户要求自动查找并使用既有在职低风险测试号 SMOKE002/测试员工 复跑；报告和文档只记录脱敏企业微信 userid 前缀 oa_smoke***，不得使用已离职/禁用的 HRWDTEST-20260517214548 作为主测试号。
• 复跑报告为远端 /tmp/wecom-capability-poc-wcpc-smoke002/summary.json，结论 GO_TO_HR_MASTER_SYNC，nextStageAllowed=true，blockingCapabilities=[]。
• WCPC 已由 WHMS 承接；请假/补卡审批模板 ID、测试审批单号 sp_no、真实回调和补偿拉取已由 WAPC2FLIVE/WCBK1/WACP3R 验证；镜像数据模型、最小历史留存、正式模板外出/加班测试和 HR 写接口仍需后续独立合同处理。WAPC1/WAPC2 已固定配置准备和只读 POC，但不得据此直接跳到考勤/审批镜像、OA 应急接管、恢复回写或 RuleOps。

P0-8 WHMS 企微 HR 主数据镜像口径

• WHMS 已本地实现并部署验证 wecom_hr_master_sync_v1，默认和最终均为 force_off，未执行生产真实员工批量 apply。
• 企微/人事助手作为 HR 主数据源；OA 同步员工档案、部门、主管、职位、手机号、邮箱、默认角色、企业微信绑定和审计。
• dry-run 只生成差异和同步记录，不写员工主数据；apply 需要管理员确认，生产真实员工批量 apply 需单独批准。
• 缺姓名、手机号、邮箱或部门时记录 missing_required_field 并跳过，不生成占位数据；企微不在职状态记录 needs_offboarding_confirmation，不自动禁用 OA 账号。
• WHMSLIVE 公网验证中，SMOKE002/测试员工（脱敏 oa_smoke***）因企微侧缺手机号、邮箱和部门按 missing_required_field 跳过，证明缺字段不会写入占位数据；普通员工访问同步 API 已验证为 403。
• 已有 OA 员工只更新安全主数据字段，不覆盖银行账户、身份证、工资、合同附件或历史审批。
• WAPI 后 WHMS/WOUA 读取策略修正为通讯录 user/list_id + 可选成员详情 + 人事助手 get_staff_info，通讯录用 WECOM_CONTACT_SECRET，人事助手用 WECOM_AGENT_SECRET，不再靠 fallback 试错。
• WHMS/WOUA-FIX 不代表考勤/审批镜像、OA 应急接管、恢复回写或 RuleOps 已完成；WRA1 后 WRV1 的 PASS_WITH_CONFIG_GAPS 只代表运行优先主链路可用且曾有审批/回调配置缺口；WMSG1 只证明消息和 Deeplink 可用；WAPC1 只证明审批配置准备清单已固化；WAPC2 只证明只读 runner 已具备；WAPC2FLIVE 只证明 OA-POC 样件可创建并可读；WCBK1 已证明真实回调 URL 验证、验签/解密和一条现有 OA-POC 测试审批单事件脱敏留证；WACP3R 已证明补偿拉取和审批详情读取可用但曾发现回调证据文件未持久化；WEGOV1 只修正路线和治理；WADM1/WARCH1 已补齐最小自建留存设计和实现。WROAD2-BIZ1 只补充测试账号业务冒烟，WAPPR1 只固定审批人自动带出和禁止申请人任意选审批人的真实试用前门禁。后续仍不能直接扩大到完整 wecom_attendance_approval_mirror_v1，需另建远端收口、正式模板外出/加班测试、真实小范围试用、打卡细项、审批规则和权限验收合同。

P0-9 企微成员资料单向维护边界

• 企业微信是成员账号和通讯录资料的主事实源。姓名、企微部门、企微直属关系、手机号、邮箱、启用/停用等成员资料，只由成员本人在企微允许的入口修改，或由企微管理员在管理后台修改。
• OA 可以读取管理员导出的通讯录或经批准的企微只读接口，把成员资料导入/镜像为 OA 员工并建立企微身份绑定；该动作只写 OA，不等于创建或修改企微成员。
• OA 内的 direct_manager_id 是 OA 工作流路由事实，不自动回写企微直属关系。两边需要一致时，企微管理员先在企微侧修正，再由 OA 重新读取或受控同步。
• 正式运行保持 OA → 企微成员 create/update/disable 写回关闭。任何未来确需反向写企微成员的能力都必须另建 Trellis task、逐字段说明副作用并再次获得生产写入批准；不能作为 OA 用户管理接口的隐式副作用。

P0-10 小团队 OA 采用度与开发决策门

• 2026-08-11 生产只读普查覆盖 20 个业务模块：聚合总行数 70（其中系统配置 26），13 个模块为零行；近 90 天只有 13 条可归属真人的创建/拥有记录证据，认证成功审计近 30/90 天均只观察到 1 个真人 actor。该证据说明 OA 整体采用度极低，不能描述为 5–10 人团队已经稳定使用。
• 13 是记录归属证据，不等于 13 次页面点击；认证审计 actor 也不能排除代理提交或覆盖外使用。工作台/通知没有真人交互证据，但本次未统计通知阅读字段，不据此声称“已证明没人看”。完整证据与口径见归档 task 08-11-internal-oa-usage-census-and-simplification。
• 产品范围和采用力度分开裁决：范围收缩为财务与低频台账后台；在报销、票据/OCR、审批、付款和 AP 等 OA 主办核心流程中要求团队真实使用。请假、考勤和适合在企微完成的日常协作不迁回 OA，也不以 OA 零使用判断业务未发生。
• 公告、普通待办、周报属于可逆关闭目标。这里的“关闭”不是仅隐藏导航：各自 API 同时停用，Portal/搜索按条件省略聚合；例如临时需要发布公告时，管理员须先重新开启公告 flag。项目主域同为零使用冻结候选，但本地验证已证明关闭会破坏报销详情的既有项目关联显示，因此继续保持开启；合同、采购、资产继续保留现有最小入口。任何 workspace、feature flag 或生产配置变更仍须独立 Trellis task 和生产写入批准。
• 绩效、薪资、ERP/集成、预算和 Cutover 只进入退役审查候选，不因本次定位直接关 flag、删入口、删代码或数据。二级导航也不预先建设；只有多名真人持续使用核心财务链并出现明确导航摩擦时才重新评估。
• 报销统一走 OA 是管理规则，不实现渠道封堵、强制提醒、入职向导或新通知功能。后续产品任务只能来自真实核心流程的最高优先级摩擦点；旧 R63–R66 扩建排期不再作为开发主线。

---

请假模块

L-1 团队日历可见性

• HR / Admin（具备 leave.view_all + leave.manage）：看全员
• 部门经理（具备 leave.view_all，仅限本部门）：看本部门
• 普通员工：不可见团队日历 Tab

实现要点：前端 canViewAll 判断需区分"HR 全员视图"和"经理部门视图"，查询时经理视图需传 departmentId 过滤。

L-2 草稿与已驳回请假的编辑

• draft 和 rejected 状态的请假支持原单编辑后再提交
• 不要求"撤回再新建"；直接在已有单据上修改字段后重新 submit
• 实现时需要 leave.edit_own（或直接在现有权限下放开）并在 submit 路由内允许此两种状态

L-3 审批中请假的撤回

• 申请人可主动撤回 reviewing 状态的请假，撤回后状态回 draft
• approved 后不允许直接撤回，需走销假/更正流程（后续另立需求）
• 当前状态：撤回已实现，此条为确认口径，无需改代码

L-4 leave.approve vs leave.manage

• leave.approve：仅表示"处理分配给自己的审批任务"，不赋予查看全量的权利
• leave.manage：HR/行政运营权限，包括查看全量、人工纠偏/取消、余额与规则维护
• leave.manage 不允许静默改写历史申请内容（需留审计痕迹）

---

审批流 / 工作流

W-1 无直接经理时的阻断规则

• 正式员工必须配置直属主管；缺直属主管属于组织主数据错误。
• 缺直属主管、主管停用、主管链断裂或审批节点解析为申请人本人时，提交必须阻断并提示"未配置可审批人"或"当前审批规则未找到审批人"。
• 只有审批规则显式配置老板/总经理或兜底审批节点，且目标不是申请人本人时，才进入 CEO 或其他非本人兜底审批人。
• 不自动通过，不静默跳过，不用无条件升级 CEO 掩盖组织配置问题。
• 当前正式运行口径：majianyong 是公司负责人 ceo 且不配置直属主管；当前唯一 active manager 向其汇报。wangshunli 只承担系统开发/系统管理，不配置业务审批角色；admin 不代表业务审批权。生产规则已回填，CEO 本人三档报销均由唯一 active 非本人 finance 审批；无可用持有人或命中自审时仍阻断。

W-2 转审适用范围

• 产品目标：转审是通用审批能力，目标覆盖报销、请假、采购、差旅。
• 条件：只能转给具备对应单据审批权限的人，且不得绕过必经老板、财务或 HR/行政节点。
• 当前实现状态：转审路由仍使用 expense.transfer 前置权限，approvalTransfer 专门留痕仍以报销为主；跨域转审扩展不作为当前 R7 硬门禁。
• 后续若要覆盖请假、采购或差旅，拆 W2F follow-up，先评审权限、状态机、转审链路、通知和历史留痕。

W-3 转审次数上限

• 上限保留 3 次，超过后拒绝继续转审
• 超限后不自动转给固定角色；要求当前审批人自行处理或由管理员走代理机制

W-4 并行会签

• 当前阶段不做并行会签
• 大额采购等双签场景，优先做串行多节点（两步顺序审批），不引入并行会签模型

---

通知渠道

N-1 三渠道联动策略

• 产品目标：审批类高优先级事件可支持站内通知 + 企业微信个人应用消息 + 邮件。
• 当前 R7 验收口径：以站内通知 + 企业微信个人应用消息和 deeplink 为主；邮件通道是否进入验收另拆 Issue。
• 当前不做用户级"关某渠道"配置
• 后续通知量上来后再做订阅偏好管理

---

Portal 首页

P-1 经理视图判断逻辑

• 当前状态：Portal 经理/角色能力已通过 buildRoleCapabilities 类逻辑按角色和权限承载。
• 口径：有任一审批权限（*.approve）或域管理权限（*.manage 非 view_all）的用户进入经理视图
• 后续可选择提取 isManagerRole(permissions) 共享工具减少重复，但这不是当前 R7 阻断项。

---

权限模型

R-1 view_all vs manage 语义定义

• view_all：对应域全量数据只读可见
• manage：域内管理与运营动作权限（如人工纠偏、配置维护、取消操作）
• manage 不是 approve 的别名，也不等于"可任意改历史数据"

R-2 报销/费用金额分层审批

• 当前三档规则固定为：小额 manager -> finance、中额 manager -> finance、大额 manager -> ceo -> finance；三档负责人本人 fallback 均为 finance，不引用无人持有的 finance_mgr。
• 普通员工按规则顺序审批；CEO 本人提交时移除本人 ceo 节点、替换不可解析的 manager 并去重，最终只有 active 非本人 finance 节点。
• 真正的职责分离继续保留在付款环节：finance 创建付款批次，ceo 复核，执行 maker-checker。
• 不因小团队规模放宽自审，也不通过 admin 代批或给现有财务追加权限更宽的 finance_mgr。

R-3 资产转移权限

• asset.transfer 只给 administration / 资产管理员
• finance_mgr 有 asset.manage 但不拥有实物调拨权限，这是有意设计

R-4 小团队财务处理与付款复核边界

• 日常财务处理角色使用 finance，付款复核角色使用 ceo；不得为了负责人本人报销兜底而顺带授予权限更宽的 finance_mgr。
• finance 除费用审批、财务付款和付款批次管理外，还包含 payroll.manage 与 employee.bank.read，因此会接触薪资数据和员工银行账号；这属于明确接受的财务职责范围，不是隐含副作用。
• ceo 通过 payment.batch.review 承担付款批次复核。maker-checker 只保证付款批次创建人与复核人不同，不代表费用审批、财务付款和全部财务操作已经按自然人完全分离。
• finance、finance_mgr 均不拥有 asset.transfer；实物调拨继续只属于 administration。

R-5 CEO 本人无主管报销限制

• ownerSelfFallbackRole 只允许 active、非本人的 finance 或兼容角色 finance_mgr；本公司新建默认和生产目标均为 finance。
• CEO 本人没有可解析直属主管时，只有存在 active 非本人 fallback 持有人才能提交；无持有人或 CEO 同时持有 fallback 角色时继续阻断。不得使用 admin 代批或恢复整库绕过。
• 既有审批快照不重路由，过去提交失败的单据也不会自动恢复。07-28-ceo-finance-fallback 已完成代码部署和生产三档规则原子回填，CEO 三档只读解析均为唯一 active 非本人 finance；尚未创建真实 CEO 报销，因此当前证据不等于真人业务验收。

R-6 单公司内部 OA 边界

• 系统只服务当前公司内部使用，不作为对外产品发布，不支持多公司、多租户、公司切换或集团工作区。
• 前端按单公司表达公司信息和企业银行账户：正常状态不要求用户选择公司，也不展示无业务价值的多公司配置复杂度。
• LegalEntity 及其外键继续作为成本中心、供应商、付款账户等内部账务和主数据关联锚点；单公司体验不等于删除后端关系模型或迁移历史数据。
• 异常存在多条启用公司信息时必须停止自动关联并提示管理员治理，不得静默选择、自动合并或删除记录。

R-7 报销费用类型与票据门禁

• “客户招待”统一为“业务招待费”；“培训会议”停止新选并拆为“会议费”“培训费”；“IT 硬件”停止新选，低值配件使用“办公用品”，需登记的选择“办公电子设备”。停用类型保留历史，不迁移旧明细语义。
• 办公用品与办公电子设备按单条明细金额 2,000 元作选类提示；该金额不等同于会计固定资产确认标准。达到金额仍选择办公用品时只提示员工和财务复核，不自动改类或阻断提交。
• 公司当前不要求 assets 类个人报销事前审批；员工应在明细说明中写清物品名称、实际使用人或责任人、存放位置，供管理员后续人工登记。当前不强制关联采购申请，也不自动建资产卡。
• 伙食补助费和市内交通补助费不要求发票；其他首期启用费用类型默认需要有效票据。免票不等于免除补助算式、业务说明、审批或必要附件。
• 票据—明细强关联和票面金额提交门禁使用独立双闸逐步启用。开启时每张有效发票必须明确选择明细，仅对需票明细校验缺票及申报金额高于票面合计；关闭只回退门禁，不删除已建立的关联数据。