accounting — 记账模块

模块定位

Sage 平台的核心记账引擎：以复式记账（借/贷双腿）为基础，围绕 「科目（subject）→ 账户（account）→ 明细（acc_detail）/ 余额（acc_balance）/ 流水 （accounting_log）」的账务体系，向上提供开户、充值、消费、账单、总账、日结、信用额度、 多币种汇率等能力。

记账的定义 = 写分录明细 + 写账务日志 + 修改账户余额，三步缺一不可，且余额更新与 透支/信用额度校验必须和明细写入在同一数据库事务上下文内完成（原子性铁律）。

模块形态：Python 包 accounting（业务逻辑）+ models/（表定义）+ json/（CRUD 定义）

• wwwroot/（页面/dspy 端点）+ init/data.json（种子数据）+ scripts/（RBAC 注册）。 宿主应用（sage 主应用）通过 load_accounting() 把所有类与函数注入 ServerEnv， 供其他模块（product、supplychain、unipay 等）跨模块调用。

核心业务文件：accounting_config.py（Accounting 配置类）/ openaccount.py（开户）/ recharge.py（充值 RechargeBiz）/ consume.py（消费记账）/ bill.py（write_bill 账单）/ ledger.py（总账）/ dayend_balance.py(日结) / settle.py+settledate.py（结算）/ creditlimit.py（信用额度）/ exchange.py（多币种汇率换算）/ stats.py（统计）/ order_to_bill.py（订单转账单）。

表清单（models/*.json）

表名	说明	关键字段
subject	科目表	name, balance_side(余额方向), subjecttype
account	机构账户表	accounting_orgid, orgid, org1id, currency, subjectid, balance_at, max_detailno
acc_balance	账户余额表	accountid, acc_date, balance
acc_detail	账户明细表（分录）	accountid, acc_no, acc_date, acc_timestamp, acc_dir(借/贷), summary, amount
accounting_log	账务流水表	accountid, acc_date, acc_timestamp, acc_dir, summary, amount, billid
account_config	账户配置表（参与方类型→科目）	subjectid, partytype, party1type
accounting_config	记账配置表（驱动分录双腿）	action, accounting_orgtype, accounting_dir, orgtype, org1type, subjectid, amt_pattern
bill	账单	customerid, resellerid, productid, resourceid, orderid, business_op, amount
bill_detail	账单明细	accounting_orgid, billid, description, participantid, participanttype, subjectname, accounting_dir
biz_order	业务订单	customerid, resellerid, order_date, order_status, business_op, amount, currency
biz_orderdetail	业务订单明细	orderid, productid, product_cnt, prod_config, list_amount, trans_amount, currency
ledger	总账表	accounting_orgid, subjectid, acc_date, d_balance(借方), c_balance(贷方), currency, exchange_rate
credit_limit	信用额度表	accountid, orgid, grant_orgid(授信方,多租户), credit_limit, used_credit, available_credit, valid_from
currency	币种	name, symbol, decimal_places, is_base, status
exchange_rate	汇率表	from_currency, to_currency, buy_rate, sell_rate, mid_rate, effective_date

种子数据（init/data.json）：appcodes/appcodes_kv 码表 + subject 科目 + account_config + accounting_config 记账配置 + currency + exchange_rate 初始汇率。 信用额度建表 SQL 另见 sql/credit_limit.sql；多币种迁移见 scripts/multi_currency_migration.sql。

对外 API / dspy 端点（wwwroot/）

api/（多币种管理端）：

• currency_create/update/delete.dspy — 币种维护
• exchange_rate_create/update/delete.dspy — 汇率维护
• fetch_forex_rates.dspy — 拉取外部外汇牌价

credit_limit/（信用额度管理）：

• add/update/delete/get_credit_limit.dspy — 额度 CRUD
• credit_manage.ui / credit_overview.ui / hub.ui — 管理/总览页面
• api/credit_summary.dspy、api/set_customer_credit.dspy(+set_credit_form.ui) — 额度汇总与客户授信设置

账务页面端点（wwwroot/ 根）：

• myaccounts.dspy/.ui、mybalance.dspy、accdetail.dspy/.ui — 我的账户/余额/明细
• billing.dspy/.ui、billing_download.dspy — 账单查询与下载
• get_user_balance.dspy、oca.dspy、usermenu.ui、error_accounting.ui
• 开户端点：open_owner_accounts.dspy / open_provider_accounts.dspy / open_reseller_accounts.dspy / open_reseller_provider_accounts.dspy / open_customer_accounts.dspy / open_customer_accounts_with_orgid.dspy
• 代充值：proxy_recharge.ui + proxy_recharge_submit.dspy
• 主题约定：账务页面（代客充值/我的信用额度/充值错帐处理）不得硬编码暗色配色 （#1E293B/#334155/#F1F5F9 等），卡片用 "css": "card"、嵌套小盒用 "css": "subcard"、 文字颜色继承主题，跟随宿主应用（pipeline-app/sage）的 data-theme 暗亮双主题切换； 语义色（状态徽章/阈值进度条）可保留。2026-09-08 已按此修复。
• 统计 widget：stat_account_count.ui / stat_month_consumption.ui / stat_today_consumption.ui / stat_total_balance.ui

CRUD 定义在 json/（account/acc_balance/acc_detail/accounting_log/accounting_config/ account_config/subject/credit_limit/currency_list/exchange_rate_list），其中 json/build.sh 用 xls2ui -m ../models -o ../wwwroot accounting *.json 从模型生成 wwwroot 页面——改 CRUD 走 json 定义重新生成，勿手改产物。

load 注册函数

宿主在初始化时调用：

from accounting.init import load_accounting
load_accounting()

load_accounting() 把以下能力注入 ServerEnv（跨模块可见）：

• 配置/业务类：Accounting（记账配置类）、RechargeBiz（充值业务）
• 记账函数：consume_accounting、recharge_accounting、write_bill
• 开户函数：openOwnerAccounts / openProviderAccounts / openResellerAccounts / openCustomerAccounts / openRetailRelationshipAccounts
• 查询函数：getAccountBalance、getCustomerBalance、getAccountByName、 get_account_total_amount、get_accdetail、all_my_accounts、get_accounting_stats
• 信用额度：get_credit_limit_for_account、update_used_credit、set_credit_limit、 get_credit_stats、get_my_credit_list、get_all_customer_credits + 三个 web 包装 （get_credit_stats_web / get_my_credits_web / get_all_credits_web，供 Jinja2 .ui 用）
• 多币种：get_exchange_rate、convert_currency、convert_to_base、 get_user_currency、BASE_CURRENCY

数据库名通过宿主注册的 get_module_dbname('accounting') 解析（跨宿主复用时表前缀/库名 映射的关键钩子）。独立调试可跑 app/acc.py（自带 webapp + RegisterFunction 的最小宿主）。

宿主集成（部署）

1. 安装：./py3/bin/pip install pkgs/accounting（setup.py 打包，包名 accounting， 版本见 accounting/version.py）。宿主 import_init.py 的 INIT_MODULES 需包含本模块 以导入 init/data.json 种子数据（码表/科目/记账配置）。
2. 入口调用：宿主初始化处 import 后显式调用 load_accounting()。
3. RBAC 注册：./py3/bin/python pkgs/accounting/scripts/load_path.py [--add-only] （自动定位宿主根：含 py3+wwwroot；把 wwwroot 全部 .ui/.dspy 路径注册进 permission 表并给角色授权）。注册后 redis db0 FLUSHDB 刷 RBAC 缓存即生效。
4. 建表：models/*.json 经 json2ddl 生成 DDL 部署期执行；运行期禁止 schema 变更。 信用额度增量见 sql/credit_limit.sql，多币种迁移见 scripts/multi_currency_migration.sql。
5. 菜单：新页面需在 sage 主仓库 wwwroot/global_menu.ui 加菜单入口。
6. i18n：词条在 i18n/{zh,en,jp,ko}，部署时合并进宿主。

新功能四件套核查（缺一即不可见/不可用）：init.py ServerEnv 暴露 → scripts/load_path.py RBAC 路径 → 宿主 global_menu.ui 菜单 → json/<表>.json CRUD 定义。

部署注意

1. 余额更新不是可选项：只写 acc_detail 不改 account/acc_balance 的实现按定义就是 不完整记账；透支/信用额度校验必须与明细写入同一事务上下文。
2. 数据隔离：查询类端点（如 get_accdetail）必须按 orgid 过滤，防止按 accountid 越权枚举他人账务——新增查询端点照抄该模式。
3. 信用额度多租户：grant_orgid 区分授信方；管理端读全部、客户端只读本机构视图， 迁移按 sql/credit_limit.sql 执行。
4. pip 非 editable 安装：改码后必须重新 pip install 到宿主 py3 再重启， 只 git pull 仓库不会更新 site-packages（可用文件 md5 对比确认加载版本）。
5. sage 核心记账引擎 vs sageapi 网关是两层：本仓库是核心引擎（复式记账/双腿/科目）， sageapi 只是轻量 API 网关；credit_limit 等逻辑两层都可能需要但实现方式不同，勿混淆。
6. 先读全模块再改：PFBiz → Accounting → leg_accounting 是完整既有体系，加功能前先读 accounting_config.py / creditlimit.py / consume.py，勿发明平行实现。
7. RBAC 精确 path 匹配，父路径不覆盖子路径；新增 dspy 必须逐条注册，否则 403。

设计文档见 docs/平台类系统记账子系统.docx；测试脚本见 test/ （open_account.py / recharge.py / run_test.py）。