# 真实飞书多维表读取器 + 原模板全量覆盖导出

更新时间：2026-05-31

## 目标

让系统支持：

```text
飞书多维表真实记录
→ 本地 FinanceInput / FinanceSnapshot
→ 原 Excel 模板全量格式覆盖
→ 每月导出同样 sheet/样式/结构的 .xlsx
```

## 本轮实现

### 1. 真实 Bitable 读取器

新增：

```text
apps/api/src/bitable-reader.ts
```

能力：

- 通过官方 `lark-cli base +table-list` / `+record-list` 读取真实飞书 Base；
- 支持分页读取，避免 `原表导出映射表` 这种大表只读第一页；
- 自动把 lark-cli 的 `fields + data + record_id_list` 行数组转成系统已有的 `BitableTableRecords`；
- 支持读取财务结构表：项目表、权益账户表、收入明细表、支出明细表、利润分配规则表、报销单表、资金账户表、收付款流水表、个人账内部周转流水表；
- 支持读取 `原表导出映射表` 并转换为模板单元格记录。

### 2. 原模板全量单元格覆盖

扩展：

```text
packages/exporter/src/template-writer.ts
```

新增 `templateCells` 入参。导出时会：

1. 读取原始 Excel 模板；
2. 物化共享公式缓存，避免 ExcelJS 写出失败；
3. 用 `原表导出映射表` 的单元格记录覆盖模板值；
4. 再用系统计算结果覆盖已实现的关键财务单元格；
5. 写出 xlsx。

这保证导出的 workbook 保留原模板 13 个 sheet、样式、列宽、结构，并覆盖当前 `原表导出映射表` 中的全部非空单元格。

### 3. API 接入

扩展：

```text
apps/api/src/cli.ts
apps/api/src/server.ts
```

当环境变量提供 Base token 时，API 会启用真实读取：

```text
FEISHU_BASE_TOKEN=<base_token>
FINANCE_DEFAULT_YEAR=2026
FEISHU_TEMPLATE_MAPPING_TABLE=原表导出映射表
```

接口保持不变：

```text
GET  /api/snapshot
GET  /api/export/original.xlsx
POST /api/workflow/export
```

### 4. 真实 Base 验证

验证脚本：

```text
scripts/verify-real-bitable-export.ts
```

本轮真实 Base 验证结果：

```json
{
  "templateCells": 1950,
  "workbookSheets": 13,
  "inputCounts": {
    "months": ["2026-01"],
    "projects": 1,
    "equityAccounts": 7,
    "incomes": 4,
    "expenses": 8,
    "allocationRules": 4,
    "reimbursements": 2,
    "cashAccounts": 2,
    "cashFlows": 4
  },
  "snapshotCounts": {
    "allocations": 4,
    "projectMonthRollups": 1,
    "cashAccountBalances": 2
  }
}
```

生成验证文件：

```text
exports/财务原表格式导出_真实飞书读取器验证.xlsx
```

### 5. 本地 API 验证

用真实 Base 启动本地 API 后：

```text
GET /health -> 200, workbookSheets=13
GET /api/snapshot -> months=2026-01, equityAccounts=7, allocations=4
GET /api/export/original.xlsx -> 200, 生成 xlsx
```

## 重要边界

已实现的是“真实飞书数据读取 + 原模板全量格式覆盖 + 已编码财务口径覆盖关键单元格”。

仍需继续补的是“每个业务 sheet 的所有业务计算口径都从结构化明细自动推导”，尤其：

- 小蒋、木雨、妹妹项目组、自研产品组、AIGC组、电商渠道组等 sheet 的细分支出/调整明细；
- 公共账户税费、人工、其他费用的更细分类行；
- 元浪公共账户、个体户账户等资金/主体账户的完整月度口径；
- 每月新增真实业务记录时，`原表导出映射表` 与结构化明细表之间的更新规则。

当前“不改变线上服务器、不改飞书记录、不启用飞书 workflow”。线上部署和 workflow 启用应另行确认。

## 验证命令

```bash
npm test -- --run
npm run typecheck
npm run build
npx tsx scripts/verify-real-bitable-export.ts
```

本轮结果：

```text
8 个测试文件通过
24 个测试通过
typecheck 通过
build 通过
真实 Base 导出验证通过
```