# PROJECT_CONTEXT — 公司财务报销与走账系统重构

更新时间：2026-06-12（打款核销 + 合同/应收应付/资金管理/个人账/财务总览模块全部上线）

## 任务背景

用户说明：现在电脑上应该有一套关于“我们自己财务系统、报销、公司走账”的大系统。之前一版做在飞书多维表上，也设计过一套数据库，但用户认为那两版都是在自己还没有完全想清楚时做的。当前目标是先复盘旧设计、整合材料，再新开项目重新梳理。

## 已执行的检索

1. 按 AI工作区规则，先查：
   - `/Users/bot1/Volumes/root_for_ai/AI工作区/00_AI工作区项目索引/AI工作区项目映射表.md`
   - 项目索引卡片目录；
   - 本地共享 RAG；
   - 旧 `/Users/bot1/AI Work` 作为只读兜底。
2. 命中旧系统：
   - `/Users/bot1/Volumes/root_for_ai/AI工作区/公司财务_系统开发_财务管理平台_20260530_1748`
3. 本轮新建项目：
   - `/Users/bot1/Volumes/root_for_ai/AI工作区/公司财务_业务梳理_报销走账系统重构_20260603_2006`

## 旧项目状态概览

旧项目不是只有概念文档，已经有代码和验证：

- Node/TypeScript monorepo；
- Prisma/PostgreSQL schema；
- 财务计算核心 `packages/core/src/finance-engine.ts`；
- 飞书多维表读取器 `apps/api/src/bitable-reader.ts`；
- 原 Excel 模板导出器；
- 飞书审批模板字段和审批回调映射草稿；
- 本地测试曾通过：8 个测试文件、24 个测试、typecheck、build；
- 曾验证真实 Base：13 个 sheet、1950 个模板单元格、真实 API snapshot 非空。

## 复盘后的新方向

这次不要直接沿用“多维表事实源”或“照旧 Excel 复刻”作为目标。建议把新系统分成三层：

1. **业务事件层**：报销申请、付款、收款、个人垫付、公司代付、项目收入、项目成本、内部调整、发票状态。
2. **账本与余额层**：资金账户余额、权益账户余额、项目利润池、个人/项目组可支配余额、公司主体往来。
3. **输出层**：看板、月结快照、报销/付款待办、原 Excel 格式导出、审计追溯。

## 当前系统口径（2026-06-09 更新）

当前 source of truth 是本项目内的后端/前端代码与云端 PostgreSQL `company_finance`，旧飞书多维表、旧云数据库/Prisma 设计、旧 `/finance/` 看板仅作历史参考。

报销闭环口径：

- “帮我报销”进入系统后，先形成公司财务系统草稿/报销单；飞书审批是审批流和审计边界，不是唯一数据源；
- 后端以当前飞书会话确认提交的用户作为审批发起人；审批、通知、webhook 使用公司财务专用飞书 App，不与 Hermes 聊天机器人 App 混用；
- 报销单状态按系统侧状态机管理：`APPROVAL_PENDING`=发起审批/审批中，`REJECTED`=被拒绝/已打回，`APPROVED`=审批通过/待打款，`PAID`=已打款；
- `APPROVED → PAID` 由打款核销接口流转（2026-06-12 实现）：`POST /api/reimbursements/:id/payments` 创建 `fund_transaction` 资金流水并经 `reimbursement_payment` 核销，付清后自动到 `PAID`；支持部分付款、合并打款（一笔流水核销多单）、幂等防重复；资金流水是真实主账，“已付金额”由核销加和派生；
- 飞书 callback endpoint 已部署并完成真实自动回调验证：`https://wwyl.yipeng.online/finance-reimbursement/api/approval/feishu/callback`；
- 2026-06-09 已用三张真实测试审批验证系统入库、飞书实例创建、自动 webhook 回写和状态守卫：`RB20260609-97CB911E`、`RB20260609-F392C5DA`、`RB20260609-CC5EAD97` 最终均为 `APPROVED`；
- 飞书会在通过后推送无状态 `approval` 事件；系统记录为 `UNKNOWN` 审计事件，但不得让 `UNKNOWN` 覆盖已终态的 `APPROVED`、`REJECTED`、`PAID`。

详细验证记录见：`docs/2026-06-09_报销审批自动回调闭环验证.md`。

前端口径：

- 报销审批看板已用 Vite + React + Semi Design 重做；
- 线上入口仍为 `https://wwyl.yipeng.online/finance-reimbursement/dashboard/`；
- 登录页保留轻量原生 HTML，仍通过 `FINANCE_API_TOKEN` 换取 HttpOnly Cookie；
- 后端优先托管 `frontend/dist/index.html` 与 `frontend/dist/assets/*`；
- 云端实际前端托管目录为 `/srv/company-finance/frontend`，当前构建产物已同步并验证：health/login/dashboard/JS/CSS/API 均返回 200。

## 当前边界

- 不写入飞书多维表；
- 不提交 Git/Gitee，除非用户明确要求版本管理；
- 不写 NAS 归档区；
- 不接触/输出密钥；
- 飞书 approval template 与 callback 已真实联调通过；打款核销到 `PAID` 已于 2026-06-12 部署云端并用三张 0.01 测试单真实验证通过（见 `docs/2026-06-12_报销打款核销上线验证.md`）；后续仍需补真实发票结构化解析、拒绝/撤回异常分支回归；
- 2026-06-12 已上线合同台账（`commercial_order`）、应收应付（`receivable`/`payable` + 核销）、资金流水直接登记、个人账派生看板、财务总览看板；个人账为派生口径（+报销待打款+个人注资+个人代付−公司还个人），详见 `docs/个人账派生与财务总览口径.md`；
- 前端看板中心为多视图：财务总览 / 报销审批 / 个人帐 / 资金流水 / 应收应付 / 合同台账；
- 用户口径（2026-06-12）：当前云端数据均为测试数据，全部验证做完后整体清理。

## 下一步建议

1. 先让用户确认 `docs/待确认问题清单.md` 里的业务口径；
2. 确认后再画一版“新系统对象模型 + 流程图”；
3. 再决定是否基于旧项目代码重构，还是只复用旧项目的概念和导出器；
4. 一期优先做：报销/付款/收款/资金账户对账/个人垫付核销，而不是完整大 ERP。