# 公司财务管理平台 — 项目上下文

更新时间：2026-05-31

## 项目位置

```text
/Users/bot1/Volumes/root_for_ai/AI工作区/公司财务_系统开发_财务管理平台_20260530_1748
```

原始参考模板：

```text
source/万物有灵项目利润分配表2026_原始参考.xlsx
```

## 当前阶段

已在原“方案 A：模板填值型 MVP”基础上继续推进 **真实飞书读取器 + 原模板全量覆盖导出**：

```text
飞书/多维表真实记录
→ apps/api/src/bitable-reader.ts 分页读取 Base
→ packages/core/src/feishu-input.ts 转成 FinanceInput
→ packages/core/src/finance-engine.ts 重新计算
→ 原表导出映射表 1950 个非空单元格覆盖原 Excel 模板
→ packages/exporter/src/template-writer.ts 写回原 Excel 模板
→ apps/api/src/server.ts 导出 xlsx / 工作流下载链接
```

本地已验证真实 Base：13 个 sheet 保留、1950 个模板单元格读取覆盖、真实 API snapshot 非空。

2026-05-31 补充：新增可重复执行的实时导出脚本 `scripts/export-real-bitable-original-format.ts`，要求通过环境变量 `FEISHU_BASE_TOKEN` 传入 Base Token，不再在脚本中硬编码 Token；每次运行都会从飞书多维表实时读取数据并生成一个带时间戳的新 Excel，不覆盖旧导出。

最新端到端导出文件：

```text
exports/财务原表格式导出_飞书实时数据_20260531T062220Z.xlsx
```

## 本阶段新增/修改重点

### 新增

```text
apps/api/src/bitable-reader.ts
scripts/verify-real-bitable-export.ts
tests/bitable-reader.test.ts
tests/full-template-export.test.ts
packages/core/src/feishu-input.ts
tests/feishu-input.test.ts
packages/exporter/src/template-writer.ts
tests/template-export.test.ts
docs/EXCEL_EXPORT_MAPPING.md
docs/REAL_BITABLE_READER_AND_FULL_TEMPLATE_EXPORT.md
PROJECT_CONTEXT.md
```

### 修改

```text
packages/core/src/types.ts
packages/core/src/index.ts
packages/exporter/src/index.ts
apps/api/src/server.ts
```

关键变化：

1. `ExpenseItem` 增加：
   - `actualDeductionMonth`：实际扣款口径；
   - `accrualMonth`：应支付/归属口径。
2. 新增/扩展 `financeInputFromBitableTables()`：把多维表记录转换为 `FinanceInput`，并支持真实 Base 里的“历史结果导入”固定金额规则、缺失公共账户自动补齐。
3. 新增 `apps/api/src/bitable-reader.ts`：通过 `lark-cli` 分页读取真实飞书 Base，含 `原表导出映射表`。
4. 新增 `templateCells` 全量模板单元格覆盖：当前真实 Base 可读取 1950 个原表非空单元格，保留 13 个 sheet 的原格式。
5. API 支持 `inputLoader` 与 `templateCellsLoader`，设置 `FEISHU_BASE_TOKEN` 后可在导出时读取真实 Base。

## 当前支持的模板填值范围

1. `收入分配表`
   - 项目收入；
   - 项目支出；
   - 第三方成本；
   - 可分配利润；
   - 权益账户分配额。
2. `公共组收入支配情况（实际扣款时间）`
   - 公共可支配收入；
   - 税费/人工/其他 MVP 分类；
   - 公共支出合计；
   - 公共余额。
3. `公共组收入支配情况（应支付时间）`
   - 同上，但按应支付/归属月份汇总费用。
4. `<账户名>提成支取表`
   - 当前测试覆盖 `苏薇提成支取表`；
   - 代码按账户名可扩展到其他个人/项目组 sheet。

详细映射见：

```text
docs/EXCEL_EXPORT_MAPPING.md
```

## 验证结果

已执行：

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

结果：

```text
8 个测试文件通过
24 个测试通过
TypeScript typecheck 通过
build 通过
真实 Base 导出验证通过：13 个 sheet、1950 个模板单元格、API snapshot 非空
```

## 明确未做

- 未部署到云服务器；
- 未改 Nginx/systemd；
- 未写入或修改飞书多维表记录；
- 未启用飞书 workflow；
- 未写 NAS 归档区；
- 已做到 13 个 sheet / 1950 个非空单元格的原模板覆盖，但还未把每个业务 sheet 的所有细分计算口径都改成结构化明细自动推导；
- 未声明所有未来月份在无需补映射/补字段的情况下已经 100% 自动对账。

## 后续建议

1. 把真实读取器部署到线上服务环境，并确认线上 `lark-cli` 身份或改为服务端 OpenAPI app token；
2. 启用/手动配置飞书 `导出请求表` workflow，把 `POST /finance/api/workflow/export` 返回的下载链接回填；
3. 补齐小蒋、木雨、妹妹项目组、自研产品组、AIGC组、电商渠道组、元浪公共账户、个体户账户等 sheet 的细分结构化口径；
4. 用一个新的月份做端到端验收：飞书新增数据 → 导出同格式 Excel → 与预期单元格对账。