# 飞书审批自动填表

**Repository Path**: mrjkchen/feishu-approval-base-sync

## Basic Information

- **Project Name**: 飞书审批自动填表
- **Description**: 将飞书审批抄送记录按财务可维护规则幂等同步到多个团队的飞书 Base
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-19
- **Last Updated**: 2026-11-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 飞书审批抄送自动填表

本工具通过官方 `lark-cli` 读取飞书“抄送我”的已通过审批，再按财务在控制面板中保存的**手动入表配置**写入各团队的正式 Base。

## 当前工作方式

系统把上一版已验证的字段解析能力作为可选“基础填表模板”，审批类型、团队、目标表、日期口径、品类条件、优先级、必填字段及字段覆盖全部保存在人工规则中。财务界面对所有团队和审批统一显示四个常用选项、“适用条件”和“写入内容”；只有基础模板、优先级和必填项折叠在“高级设置”中。每条审批只有命中优先级最高且唯一的一条已启用规则时才会进入候选列表。

每条手动规则由财务配置：

- 规则名称、团队、飞书审批类型、目标表。
- 日期口径：审批提交时间或抄送到达时间。
- 可选的上一版基础填表模板，也可选择“完全手动填写”。
- 规则优先级；更具体的人工修正规则可以覆盖基础规则。
- 零到多个匹配条件，支持“完全等于”“属于任一值”“不属于这些值”。
- 目标表每个字段的取值：审批表单字段、系统字段、固定值或留空。
- 字段格式：自动、文本、金额或日期。
- 字段是否必填，以及哪些审批值（例如“无”）按空值处理。

旧版业务配置仍保存在 `config/mapping.json`，只在人工规则明确选择对应基础模板时用于字段解析。`npm run rules:restore-preview` 会把上一版完整系统配置和 `config/matching-rules.legacy.json` 中的人工修正转换成版本 2 规则，输出到 `config/matching-rules.restored.json`，不会直接覆盖当前规则。

恢复时如果线上目标表暂不可用，可追加 `--disable-route 团队:routeKey`。生成的相关规则会保留在面板中但默认停用，并带“目标表待修复”前缀；修好表结构后由财务预览并重新启用。

## 永久安全约束

以下约束不属于财务业务规则，不能在面板中关闭：

- 默认只预览；只有点击“确认并同步”或命令行传入 `--apply` 才写入。
- 只处理状态为 `APPROVED` 的审批。
- “编号”或目标路由配置的去重字段始终由系统写入飞书审批单号，不能手动覆盖。
- 读取历史数据时仍兼容旧编号、旧实例号和旧备注中的同步标记，避免升级后重复录入。
- 目标表缺少去重字段、必填值、字段或下拉选项时，阻止该条写入并显示原因。
- 同一审批命中多条同优先级规则时阻止写入；不同优先级只使用最高的一条。
- 规则保存使用版本校验和原子替换，两个窗口不能互相覆盖。
- App Secret、access token 和 Cookie 不写入项目配置或同步历史。

## 财务配置步骤

1. 打开控制面板，点击“财务分类与入表配置”。
2. 选择负责的团队，并搜索审批名称。
3. 修改现有规则点“配置规则”；同一审批需要分情况处理点“新建分支”；新增相似审批点“复制新审批”。
4. 确认团队、审批名称、目标表和日期。费用报销通常按抄送到达时间，其他审批通常按提交时间。
5. 如为新审批，点击“使用推荐设置”带出同名基础模板；无法推荐时应复制相似规则，或由维护人员配置高级字段。
6. 业务调整统一使用“适用条件”和“写入内容”。例如把“其它、其他、软件费/剪映/美图等”记为均摊费用：新建分支，条件填“报销类型属于这些值”，写入内容填“科目固定为均摊费用”。其他审批同样配置，不需要专用入口。
7. 保存这条规则，回到首页先“预览待同步数据”，核对目标表、日期、金额、科目和人工审查项。
8. 预览正确后再正式同步。

完整说明见 [财务手动配置使用说明](./docs/财务手动配置使用说明.md)。控制面板内也提供“查看使用说明”和在线完整说明页。

没有配置任何规则时，所有审批都会安全跳过。编号由系统维护，财务不需要配置。

## 规则数据结构

配置保存在 `config/matching-rules.json`，当前版本为 2。核心结构：

```json
{
  "version": 2,
  "revision": "每次保存自动更新",
  "rules": [
    {
      "id": "稳定 ID",
      "name": "费用报销到报销账户",
      "enabled": true,
      "team": "叁只狸",
      "routeKey": "reimbursement",
      "approvalType": "费用报销",
      "dateBasis": "arrival",
      "priority": 100,
      "legacyRuleName": "费用报销",
      "requiredTargets": ["日期", "摘要", "金额"],
      "conditions": [
        { "sourceKind": "form", "source": "报销类型", "operator": "in", "values": ["软件费", "其他"] }
      ],
      "mappings": [
        { "target": "日期", "valueKind": "system", "source": "businessDate", "transform": "date", "required": true, "blankValues": [] },
        { "target": "金额", "valueKind": "form", "source": "费用汇总", "transform": "money", "required": true, "blankValues": [] },
        { "target": "三级科目", "valueKind": "fixed", "fixedValue": "均摊费用", "transform": "auto", "required": true, "blankValues": [] },
        { "target": "三级科目（运营人/法人）", "valueKind": "template", "source": "三级科目（店铺运营人）", "transform": "text", "required": true, "blankValues": [] }
      ]
    }
  ]
}
```

`valueKind` 可选 `form`（审批字段）、`system`（系统字段）、`template`（上一版基础模板已经解析出的字段）、`fixed`（固定值）或 `blank`（清空）。当不同团队的 Base 列名不同，但仍需复用同一基础模板时，使用 `template` 把模板字段显式映射到目标列，避免在代码中写死团队字段别名。

## 运行与验证

推荐双击 [启动控制面板.cmd](./启动控制面板.cmd)，浏览器会打开 `http://127.0.0.1:3765`。

首次从源码部署时，先复制 `config/mapping.example.json` 为 `config/mapping.json`，填写自己的团队、Base、表和部门信息；复制 `config/schedule.example.json` 为 `config/schedule.json`。真实业务配置、部署记录和同步数据均被 Git 忽略，不进入公共源码仓库。

```powershell
npm test
npm run rules:restore-preview
npm run panel
npm run sync
node src/index.js --teams 叁只狸 --target-date 2026-09-16
node src/index.js --apply --teams 叁只狸 --target-date 2026-09-16
```

`npm run sync` 和不带 `--apply` 的命令只预览，不写飞书。每次正式同步追加到 `data/sync-history.jsonl`。

## 团队与表格

`config/mapping.json` 保存团队识别、Base 地址和目标路由。控制面板支持新增或修改团队，并检查 Base、目标表的去重字段和飞书部门。新增团队不再按“总账户/广告账户”等固定表名识别：先读取 Base 中全部包含“编号”字段的表，再由财务勾选正式目标表并选择“总账格式”或“广告账户格式”。未勾选的副本或辅助表不会进入规则配置。某一张表失效时只阻止该路由，不影响其他健康路由。

首次添加团队前，飞书用户授权必须包含通讯录基础读取、应用身份通讯录访问和部门搜索权限。控制面板的“切换授权账号”会显式申请这些权限；若飞书开放平台提示应用未开通权限，需要管理员先在应用后台启用对应权限后再扫码授权。

手动规则保存时会检查团队和目标路由仍存在。打开配置界面只渲染紧凑的规则摘要，并默认显示一个团队；同团队、同审批的规则会合并为一个分组，明确区分“默认处理”和“条件分支”，摘要会显示适用条件和写入内容。所有规则使用相同的“配置规则”“新增条件分支”“复制新审批”操作。只有点击配置时才渲染单条规则，高级设置默认折叠。保存和删除只提交当前规则及配置版本号，服务端仍会对完整规则集重新校验并原子替换，避免规则数量增加后整份配置请求过大。目标字段仅在点击字段输入框、添加内容或切换目标表时按需读取，因此规则数量较多时也不需要一次加载全部表结构。读取失败时仍可手工输入字段名，但必须在预览中确认。

## 定时同步

定时配置保存在 `config/schedule.json`。每天按北京时间处理昨天，具体审批按提交时间还是抄送到达时间由各自命中的手动规则决定。定时任务和手动任务不会并行。

在重新启用自动同步前，应至少完成一组规则并通过预览。关闭控制面板进程后，定时同步会停止。

## 安装包

运行 `npm run build:installer` 会在 `dist` 生成 Windows 安装包和 SHA256 文件。安装包不会携带开发机的飞书登录状态、App Secret、token、Cookie、二维码或同步历史。升级安装会保留目标电脑自己的团队配置、手动规则、定时设置和历史记录。