# 飞书审批回调接入设计

## 目标流程

```text
用户在飞书发起审批
→ 审批人审批
→ 飞书事件回调到 /finance-api/feishu/events
→ 系统验签/解密/去重
→ 读取 approval instance 表单字段
→ 根据 templateCode 转成本地入库指令
→ 写入业务表 + audit log
→ 看板和 Excel 导出从本地库重新计算
```

## 回调处理规则

1. **快速 ACK**：Feishu 回调接口 3 秒内返回成功，重处理放后台队列。
2. **事件去重**：按 `event_id` 或 v1 `uuid` 去重，避免重复入账。
3. **只处理终态**：`APPROVED` 才生成业务入账；`REJECTED/CANCELED/DELETED` 只记录事件。
4. **保留审计**：保存 instance_code、approval_code、templateCode、原始表单、转换后的 commands。
5. **幂等入账**：同一 instance_code 不重复创建 Income/Expense/Reimbursement/CashFlow。

## 本轮已实现的代码边界

- `listApprovalTemplates()`：列出 6 个财务审批模板。
- `buildFeishuApprovalDefinitionDraft()`：生成可提交给 Feishu `approval/v4/approvals` 的定义草稿。
- `mapApprovedFinanceFormToCommands()`：审批通过后把表单字段转成本地财务入账指令。

## 后续部署需要配置

- Feishu app scopes：至少需要 approval definition / instance / event 相关权限。
- 公开回调 URL：建议 `https://wwyl.yipeng.online/finance-api/feishu/events`。
- 回调 verification token / encrypt key：只放服务器环境变量，不写进仓库。
- 审批人 user_id：创建真实模板前需要确认审批人列表。

## 本轮没有做的事

- 没有在飞书后台真实创建审批定义。
- 没有配置事件订阅。
- 没有部署回调接口。
- 没有写云端数据库。

原因：真实创建审批模板需要确定审批人、表单权限、审批节点和 Feishu app 权限；当前先把“模板字段 + 本地映射逻辑”落到代码层。