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

更新时间：2026-06-09 19:49 CST

## 任务背景

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

## 已执行的检索

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`=已打款；
- 飞书 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`。

## 下一步建议

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