junhong_cmp_fiber/openspec/changes/deliver-july-iteration-confirmed-scope/specs/wecom-approval-integration/spec.md

ADDED Requirements

Requirement: 管理员绑定系统账号与企微成员

系统 SHALL 从已配置自建应用的可见通讯录分页查询成员，并允许管理员将系统账号绑定到 (corp_id, userid)；列表和详情 SHALL 返回 userid、姓名及绑定状态，手机号和邮箱不得作为绑定前置条件，不得提供用户扫码自助绑定流程。

Scenario: 从通讯录选择成员绑定账号

• WHEN 管理员在账号列表为系统账号选择一个应用可见的企微成员
• THEN 系统保存 corp_id、userid 和展示快照，后续审批可使用该 userid 作为申请人

Scenario: 绑定不可见成员

• WHEN 管理员提交不在当前企微应用可见范围内的 userid
• THEN 系统返回参数或权限错误且不保存绑定

Requirement: 业务场景绑定企微后台模板

系统 SHALL 允许管理员配置业务类型、企微 template_id 和业务字段到控件 ID/类型/选项 key 的映射；模板必须已在企微后台创建，系统 MUST 通过模板详情接口校验映射，不得在本系统创建审批节点或审批人规则。

Scenario: 发布有效场景配置

• WHEN 管理员提交的模板存在且所有必填业务字段均能映射到有效控件
• THEN 系统启用该场景并保存模板结构校验结果

Scenario: 模板控件已经变化

• WHEN 模板详情与已配置的控件 ID、类型或选项 key 不一致
• THEN 系统阻止新审批提交并返回明确配置错误，不影响存量审批同步

Requirement: 使用绑定成员发起模板审批

退款和员工线下代充值 SHALL 通过现有 Approval Port 创建通用审批实例和提交 Outbox；企微 Adapter MUST 对已绑定的内部员工使用本人 userid，对代理等非企微账号使用应用已配置且当前可见的默认发起人 userid，并使用 template_id、use_template_approver=1 和映射后的控件值调用 oa/applyevent。成功后保存 sp_no，业务 Domain/Application 不得解析企微 DTO 或状态码；通用实例中的真实业务提交人不得被默认企微发起人覆盖。

Scenario: 成功发起审批

• WHEN 提交人已绑定企微成员、场景有效且业务申请校验通过
• THEN 系统原子保存业务单、通用审批实例和提交事件，并最终把企微 sp_no 关联到该实例

Scenario: 发起前置不完整

• WHEN 内部提交人未绑定且应用未配置可用默认发起人、代理提交时默认发起人不可见、模板无效或 Adapter 未配置
• THEN 系统在写入业务单、审批实例和 Outbox 前失败关闭

Scenario: 代理发起退款审批

• WHEN 代理账号提交退款且应用已配置当前可见的默认发起人
• THEN 企微审批以默认成员作为 creator_userid 发起，但本地业务申请和通用审批实例仍记录代理为真实提交人

Scenario: 提交结果未知

• WHEN 调用企微超时且无法判断审批是否创建成功
• THEN 系统标记结果未知并进入查询恢复，不得直接创建第二张审批单

Requirement: 回调和轮询共同同步审批结果

系统 MUST 验证并解密 sys_approval_change 回调、快速响应，再按 sp_no 获取审批详情并幂等翻译为标准决策；系统 MUST 周期性查询未终态审批并通过批量单号/详情接口补偿回调遗漏。

Scenario: 重复审批回调

• WHEN 同一审批状态变化被企微重复推送
• THEN 系统只产生一次对应标准终态和一次业务终态处理

Scenario: 回调丢失

• WHEN 企微审批已终态但系统未收到回调
• THEN 轮询任务通过审批详情发现终态并驱动相同的标准决策同步用例

Requirement: 审批人员只做可选读取映射

系统 SHALL 从已同步审批详情的流程节点取得审批人 userid，并批量映射系统账号；能映射时返回审批人 ID/名称，不能映射时返回空值，不得为展示字段实时逐条调用企微或建立本地审批人规则。

Scenario: 审批人已绑定系统账号

• WHEN 列表关联的企微审批详情包含已绑定 userid
• THEN 列表返回对应系统账号 ID 和名称