# 原 Excel 模板填值导出映射（MVP）

更新时间：2026-05-31

## 目标

本阶段采用“方案 A：模板填值型”。系统继续读取原始 Excel 作为模板，保留原 workbook/sheet/样式结构，然后把飞书多维表归一化后的 `FinanceInput` 重新计算成财务快照，并写入第一批可验收单元格。

入口代码：

```text
packages/core/src/feishu-input.ts
packages/exporter/src/template-writer.ts
apps/api/src/server.ts
```

验证测试：

```text
tests/feishu-input.test.ts
tests/template-export.test.ts
```

## 飞书表 → FinanceInput

当前已支持的表：

| 飞书表 | 关键字段 | 写入模型 |
|---|---|---|
| 项目表 | 项目名称 | `projects` |
| 权益账户表 | 账户名称、账户类型、期初余额/当前余额 | `equityAccounts` |
| 收入明细表 | 项目/账户、收入分类、金额、收入月份 | `incomes` |
| 支出明细表 | 费用项目、费用承担账户、费用分类、金额、实际扣款月份、应支付/归属月份 | `expenses` |
| 利润分配规则表 | 规则名称、适用项目/账户、分配对象、分配方式、比例、固定金额、状态 | `allocationRules` |
| 报销单表 | 费用承担账户、金额、状态、月份 | `reimbursements` |
| 资金账户表 | 账户名称、期初余额/当前余额、实际余额 | `cashAccounts` |
| 收付款流水表 | 资金账户、方向、金额、月份 | `cashFlows` |
| 个人账内部周转流水表 | 目标账户、金额、月份、备注 | `adjustments` |

月份口径：

- `收入月份` → 收入计算月份；
- `实际扣款月份` → 公共账户“实际扣款时间”sheet；
- `应支付/归属月份` → 公共账户“应支付时间”sheet；
- 只写 `1月` / `2月` 时，按调用参数 `defaultYear` 转成 `YYYY-MM`。

## 模板填值范围

### 1. 收入分配表

当前写入每月“合计列”，不是原表内每个项目明细列。2026 年原模板常用映射：

| 月份 | 写入列 |
|---|---|
| 1月 | F |
| 2月 | I |
| 3月 | L |
| 4月 | O |
| 5月 | R |
| 6月 | U |
| 7月 | X |
| 8月 | AB |
| 9月 | AE |
| 10月 | AH |
| 11月 | AK |
| 12月 | AN |

写入行：

| 行 | 含义 | 来源 |
|---|---|---|
| 4 | 项目收入 | `projectMonthRollups.projectIncome` |
| 5 | 项目支出 | `projectMonthRollups.projectExpense` |
| 6 | 项目第三方 | `projectMonthRollups.thirdPartyCost` |
| 7 | 可分配利润 | `projectMonthRollups.distributableProfit` |
| 权益账户对应行 | 个人/项目组/公共账户分配额 | `allocations` |

备注：当前 MVP 会把这些目标单元格写成数值，避免依赖 Excel 打开后重新计算。

### 2. 公共组收入支配情况（实际扣款时间）

月份列：`C:N` 对应 `1月:12月`。

写入行：

| 行/标签 | 含义 | 来源 |
|---|---|---|
| 公共可支配收入 | 公共账户分配收入 | 公共账户 `allocations` |
| 增值税 | 税费明细 MVP 行 | 公共账户支出里 `费用分类` 含“税/印花” |
| 税费合计 | 税费合计 | 同上 |
| 财务人工费 | 人工费用 MVP 行 | 公共账户支出里 `费用分类` 含“工资/人工/社保/公积金/法务/人事” |
| 人工费用合计 | 人工合计 | 同上 |
| 办公用品费用 | 其他费用 MVP 行 | 非税费、非人工的公共账户支出 |
| 其他费用合计 | 其他费用合计 | 同上 |
| 公共费用支出项目 | 公共支出合计 | 税费 + 人工 + 其他 |
| 公共余额 | 公共可支配收入 - 公共费用支出 | 计算值 |

费用按 `actualDeductionMonth ?? month` 汇总。

### 3. 公共组收入支配情况（应支付时间）

写入行同上，但费用按 `accrualMonth ?? month` 汇总。这样同一笔公共税费可以在实际扣款 sheet 落到 1 月，同时在应支付 sheet 落到 2 月。

### 4. 苏薇等个人/项目组提成支取表

当前会按账户名称寻找：

```text
<账户名>提成支取表
<账户名>提成支配表
<账户名>
```

MVP 写入行：

| 行/标签 | 含义 | 来源 |
|---|---|---|
| `<账户名>可支配收入` | 分配收入 | `allocations` |
| 其他内部调整收入 | 内部调整 | `adjustments` |
| `<账户名>可支配收入合计` | 分配收入 + 内部调整 | 计算值 |
| 工资 | 人工费用 MVP 行 | 账户支出里 `费用分类` 含工资/人工等 |
| 报销款合计 | 已付款报销 + 账户支出里的报销 | `reimbursements` + `expenses` |
| `<账户名>支配支出` | 工资 + 报销款 | 计算值 |
| `<账户名>可分配余额` | 可支配收入合计 - 支配支出 | 计算值 |

## 已知边界

1. 当前导出分两层：先用 `原表导出映射表` 全量覆盖 13 个 sheet 的 1950 个非空模板单元格，保证原表格式/结构完整；再用结构化计算结果覆盖已实现的关键财务单元格。
2. `apps/api/src/server.ts` 已支持 `inputLoader` 和 `templateCellsLoader`；设置 `FEISHU_BASE_TOKEN` 后可从真实飞书 Base 读取结构化表和原表映射表。
3. 当前结构化计算仍是分阶段补齐，不是所有 13 个 sheet 的每一行都已经由明细表自动推导。
4. 原表含共享公式，ExcelJS 在写回时可能因共享公式 master/clone 关系报错；代码会先把共享公式 clone 物化为静态缓存值，再写入本阶段负责的目标单元格。
5. 未改动云服务器、未写飞书多维表记录、未写 NAS 归档区。

## 下一步建议

1. 部署真实读取器到线上服务，确认线上 lark-cli 身份或改为服务端 OpenAPI app token。
2. 启用飞书 `导出请求表` workflow，完成“新增导出请求 → 调接口 → 回填下载链接”。
3. 扩展公共费用细分行：税费子类、人工子类、办公用品/AI/招待/固定资产等。
4. 逐步扩展到小蒋、木雨、妹妹项目组、自研产品组、AIGC组、电商渠道组、元浪公共账户、个体户账户等 sheet 的结构化计算。
5. 用真实新增月份做对账测试，再声明“每月全自动原表格式兼容”。