root/dealerhub
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b3f3095d53d6da2cced5891ec921d97c0a13f691
dealerhub/PROGRESS_PHASE3_FINANCE.md
T

9.8 KiB
Raw Blame History

dealerhub · 阶段 3 完整财务（总账系统 + 业财一体化）实施与验收报告

目标：实现对标管家婆“财贸双全”的核心总账与业务一体化财务系统，涵盖会计科目、会计期间、记账凭证、借贷校验、往来核销、自动记账、期末结转损益与结账、财务三大主表（科目余额表、资产负债表、利润表）及明细分类账。

一、架构设计与核心模型

本模块由两大部分深度融合构成：

  1. 往来管理（AR / AP）：支持销售应收、采购应付、收款单、付款单、跨单及部分核销明细。
  2. 总账核算（General Ledger）：支持会计准则科目树、月度会计期间、借贷平衡复式记账凭证、凭证过账/作废状态机、期末损益结转、反结账以及实时报表生成。

1. 数据模型（apps/finance/models.py）

模型 表名 说明
Account finance_account 会计科目（资产/负债/所有者权益/收入/费用 5 大类，借/贷正常余额方向，客户/供应商辅助核算，系统预置保护）
Period finance_period 会计期间（YYYY-MM，起止日期，未结 open / 已结账 closed 状态流转）
Voucher finance_voucher 记账凭证（编号 V{YYYYMM}{seq:04d}，期间关联，业务来源追溯，借贷合计校验，草稿 draft / 已过账 posted / 已作废 cancelled）
VoucherEntry finance_voucher_entry 凭证分录（科目外键、借方/贷方金额、摘要、客户/供应商辅助核算外键）
Receivable finance_receivable 应收单（客户关联、单号 RC...、总额、已收、剩余未收 balance）
Payable finance_payable 应付单（供应商关联、单号 PY...、总额、已付、剩余未付 balance）
Receipt finance_receipt 收款单（客户关联、收款方式、过账状态）
Payment finance_payment 付款单（供应商关联、付款方式、过账状态）
Allocation finance_allocation 核销明细（收款冲应收、付款冲应付的多对多核销关系）

二、业财一体化（业务单据自动过账生成凭证）

当租户初始化会计科目后，业务流程中的确认动作会自动生成并过账记账凭证，实现业务数据与财务总账的实时同步：

  1. 销售单确认（apps/sales/services.py:confirm_sales_bill）：
    • 扣减库存，生成应收单
    • 自动生成销售收入凭证：
      • 借：1122 应收账款（辅助核算：对应客户）
      • 贷：6001 主营业务收入
    • 自动根据出库加权平均成本结转销售成本凭证：
      • 借：6401 主营业务成本
      • 贷：1403 库存商品
  2. 进货单确认（apps/purchase/services.py:confirm_purchase_bill）：
    • 增加库存，生成应付单
    • 自动生成采购入库凭证：
      • 借：1403 库存商品
      • 贷：2202 应付账款（辅助核算：对应供应商）
  3. 收款单核销（apps/finance/services.py:allocate_receipt）：
    • 校验核销金额一致性与应收单余额
    • 自动生成收款凭证：
      • 借：1002 银行存款（或 1001 现金）
      • 贷：1122 应收账款（按核销单据逐笔挂客户）
  4. 付款单核销（apps/finance/services.py:allocate_payment）：
    • 校验核销金额一致性与应付单余额
    • 自动生成付款凭证：
      • 借：2202 应付账款（按核销单据逐笔挂供应商）
      • 贷：1002 银行存款（或 1001 现金）

三、期末处理与财务报表

1. 期末损益结转与结账（close_period）

  • 自动汇总当期所有已过账业务凭证中的收入科目与费用科目。
  • 将收入科目贷方发生额借记转出，费用科目借方发生额贷记转出。
  • 差额结算本期净利润（盈利贷记 4103 本年利润，亏损借记 4103 本年利润）。
  • 生成并在当期自动过账 period_close 凭证，使损益科目期末余额归零。
  • 将期间置为 closed。已结账期间严格禁止新增、修改或过账凭证。

2. 反结账（reopen_period）

  • 必须按倒序反结账（不存在更晚已结期间）。
  • 自动作废当期期末结转损益凭证，恢复期间为 open 状态。

3. 财务三大报表与明细账

  • 科目余额表（试算平衡表 trial_balance）：
    • 输出期初借/贷、本期发生借/贷、期末借/贷。
    • 自动校验试算平衡：期初借==贷，本期发生借==贷，期末借==贷。
  • 资产负债表（balance_sheet）：
    • 累计统计至指定期间期末的资产、负债和所有者权益。
    • 动态计算未结转损益（unclosed_profit = 累计收入 - 累计费用），保证在期末结账前后始终严格满足会计恒等式： \text{资产总计} = \text{负债总计} + \text{所有者权益} + \text{未结转本期损益}
  • 利润表（income_statement）：
    • 统计期间营业收入、主营业务成本（COGS）、毛利润、期间费用、净利润。
  • 明细分类账（account_ledger）：
    • 查询指定科目（如 1002 银行存款、1122 应收账款）的期初余额、每笔凭证发生额、辅助核算对象和连续滚动余额。

四、REST API 接口清单

所有接口位于 /api/v1/finance/ 命名空间下，天然支持 JWT 鉴权与 X-Tenant-Id 多租户隔离：

接口 方法 说明
/api/v1/finance/accounts/ GET / POST 会计科目列表与维护
/api/v1/finance/accounts/init-chart/ POST 一键初始化 22 个国家标准会计科目
/api/v1/finance/periods/ GET 会计期间列表
/api/v1/finance/periods/{id}/close/ POST 会计期间期末结转与结账
/api/v1/finance/periods/{id}/reopen/ POST 会计期间反结账
/api/v1/finance/vouchers/ GET / POST 凭证列表，POST 支持提交 entries 嵌套分录及自动借贷校验
/api/v1/finance/vouchers/{id}/post/ POST 凭证过账
/api/v1/finance/vouchers/{id}/cancel/ POST 凭证作废
/api/v1/finance/voucher-entries/ GET 凭证分录查询（只读）
/api/v1/finance/receivables/ GET 应收单列表（含 customer_code、balance 等字段）
/api/v1/finance/payables/ GET 应付单列表（含 supplier_code、balance 等字段）
/api/v1/finance/receipts/ GET / POST 收款单列表及录入
/api/v1/finance/payments/ GET / POST 付款单列表及录入
/api/v1/finance/allocations/ GET 核销流水明细
/api/v1/finance/reports/trial-balance/ GET 科目余额表（参数：period=YYYY-MM）
/api/v1/finance/reports/balance-sheet/ GET 资产负债表（参数：period=YYYY-MM）
/api/v1/finance/reports/income-statement/ GET 利润表（参数：period=YYYY-MM）
/api/v1/finance/reports/ledger/ GET 明细分类账（参数：account=1002&period=YYYY-MM）

五、验证与验收证据

1. 单元与集成测试套件（75 个测试 100% 通过）

$ python -m pytest tests apps/core/tests/ -p no:cacheprovider
======================= 75 passed, 100 warnings in 1.32s =======================
  • tests/test_full_finance.py：覆盖科目初始化、期间计算、凭证借贷平衡拒绝、辅助核算强制校验、凭证过账作废状态机、销售与成本自动凭证、采购与付款自动凭证、收款核销自动凭证、期末损益结转与反结账、试算平衡、资产负债表等式、利润表计算、明细账、所有 8 个 REST API 接口（10/10 通过）。
  • tests/test_finance.py：覆盖既有应收应付创建、部分付款核销、超额核销拒绝、金额不匹配拒绝（8/8 通过）。
  • tests/test_e2e.py：端到端全业务链（采购→付款→销售→收款→对账结清）（3/3 通过）。
  • tests/test_catalog.py, test_partner.py, test_inventory.py, test_purchase.py, test_sales.py：全量业务模块（54/54 通过）。
  • apps/core/tests/test_workflow.py：状态机服务（14/14 通过）。

2. 内网服务器（lan-19216857）容器化部署与全量冒烟

  • 服务器：192.168.5.7:18050
  • 运行环境：PostgreSQL 16 (pg-main 共享实例) + Granian 2.8.2 ASGI 服务器 (4 Workers)
  • 迁移状态：finance.0002_account_period_voucher_voucherentry_and_more... OK
  • 镜像状态：Docker 镜像 dealerhub-backend:latest 已在服务器本地完成构建并更新。
  • 冒烟脚本输出（bash /home/chunyu/dealerhub/smoke_full.sh）：
===== dealerhub 完整业务链冒烟 =====
[1] 创建测试实体
  product id=6, warehouse id=8, supplier id=6, customer id=6
[2] 在容器内创建进货单并过账（写库存 + 生成应付）
  purchase_bill: PB202609070003 state=confirmed total=160
[3] 检查库存 + 应付
  stocks: P094333/W094333 on_hand=20.0000 avg_cost=8.0000
  payables: PY202609070003 S094333 total=160.0000 status=open
[4] 在容器内创建销售单并过账（扣库存 + 生成应收）
  sales_bill: XS202609070003 state=confirmed total=84
[5] 检查应收（应该 7*12=84）
  receivables: RC202609070003 C094333 total=84.0000 balance=84.0000 status=open
[6] 检查财务凭证（业财一体化自动生成凭证）
  vouchers count = 6
    V2026090006 source=sale_cost 借/贷=56.0000/56.0000 [posted] 销售单 XS202609070003 结转成本
    V2026090005 source=sale      借/贷=84.0000/84.0000 [posted] 销售单 XS202609070003 确认
    V2026090004 source=purchase  借/贷=160.0000/160.0000 [posted] 采购单 PB202609070003 确认
[7] 检查科目余额表（试算平衡）
  trial_balance is_balanced = True  rows = 5
  期末借方合计 = 488.0  期末贷方合计 = 488.0
[8] 检查资产负债表与利润表
  balance_sheet balanced = True  资产总计 = 376.0  负债及权益 = 376.0
  income_statement 收入 = 168.0  成本 = 112.0  毛利 = 56.0  净利润 = 56.0
===== 全部通过 =====
Reference in New Issue View Git Blame Copy Permalink