# 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`
- 统计 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 注册函数

宿主在初始化时调用：

```python
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）。