From 382fb3fd5a2caadf1ff4c42ea6431b04a6e904a4 Mon Sep 17 00:00:00 2001
From: yumoqing <yumoqing@gmail.com>
Date: Mon, 7 Sep 2026 11:42:17 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=A8=20README(4=E5=BC=A0?=
 =?UTF-8?q?=E8=A1=A8/=E4=B8=9A=E5=8A=A1=E6=97=A5=E6=9C=9F=E6=9C=BA?=
 =?UTF-8?q?=E5=88=B6/businessdate.py=E5=9B=9B=E5=87=BD=E6=95=B0/=E6=9C=80?=
 =?UTF-8?q?=E5=85=88=E5=8A=A0=E8=BD=BD=E9=A1=BA=E5=BA=8F)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 88 ++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 81 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index f49cf56..be7e853 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,84 @@
-# appbase
-基本应用包，主要是提供代码管理和系统参数管理能力
+# appbase — 基础应用包（代码管理 + 系统参数/业务日期）
 
-## 参数管理
-应用系统的参数集中管理，为系统提供可动态维护的参数
-业务日期，应用的业务日期存储在参数表中，并提供函数用于获得系统日期和设置心业务日期
+产线平台/Sage 系应用最底层的基础模块，提供两项全平台共用的能力：
 
-## 代码管理
-提供系统键值对管理和维护能力
+1. **代码管理（编码/键值对）**：appcodes + appcodes_kv 两级编码表，全平台下拉框、状态字典、机构类型（org_type）等键值数据统一存放于此，rbac/dapi 及所有业务模块的 models `codes` 关联都指向它。
+2. **系统参数与业务日期**：params 表集中管理可动态维护的参数；其中 `business_date`（业务日期）是记账/计费等业务的时间基准——**账单日期取业务日期而非自然日期**，由本模块提供读取/推进函数，另含 svgicon 图标表。
 
+## 模块定位
+
+- 加载顺序上位于所有模块**之前**（rbac 的注册开关读 params 表、dapi/业务模块用编码表），宿主入口第一个调用 `load_appbase()`。
+- 无独立认证逻辑，页面/dspy 端点经 rbac 按 logined 权限保护。
+- 数据库名解析：`ServerEnv().get_module_dbname('appbase')`。
+
+## 表清单（models/*.json）
+
+| 表 | 标题 | 字段 | 说明 |
+|---|---|---|---|
+| `appcodes` | 应用编码表 | id, name(编码名称), hierarchy_flg(多级标志) | 编码组，如 `user_status`、`org_type` |
+| `appcodes_kv` | 编码键值表 | id, parentid(父id→appcodes), k(键), v(值) | 组内键值对；rbac 的 orgtypes/role 的 orgtypeid 下拉即取 `parentid='org_type'` |
+| `params` | 参数表 | id, params_name(参数名称), params_value(参数值) | 已知参数：`business_date`（业务日期）、`register_open`（rbac 注册开关，1=开放 0=关闭，superuser 可在参数管理界面修改） |
+| `svgicon` | 图标 | id, icon(svg内容) | 平台内嵌 SVG 图标库 |
+
+`json/` 为同名 bricks CRUD 页面定义。
+
+## 业务日期参数机制（重点）
+
+业务日期存储在 `params` 表的 `business_date` 行，代表"系统当前处于哪一业务日"，与自然日期解耦（支持补账、日切前处理跨天业务）。
+
+`appbase/businessdate.py` 提供（均为 async，可传入已有 sor 复用事务，不传则自行开连接）：
+
+| 函数 | 作用 |
+|---|---|
+| `get_business_date(sor=None)` | 读当前业务日期；params 无 `business_date` 行时抛 `BusinessDateParamsError` |
+| `new_business_date(sor=None)` | **日切**：业务日期 +1 天并写回 params |
+| `previous_business_date(sor=None)` | 当前业务日期 -1 天（只读计算） |
+| `next_business_date(sor=None)` | 当前业务日期 +1 天（只读计算） |
+
+`appbase/params.py` 提供通用参数读取 `_get_params(sor, name)`（按 params_name 查 params_value）。
+
+**消费方示例**：accounting 记账链路 `bill.bill_date = await get_business_date(sor)`（账单落业务日期）；rbac 注册开关读 `register_open`。定时日切走 `wwwroot/cron/switch_bizdate.dspy`：把 `business_date` 重置为当天自然日期，**只允许本机（127.0.0.1/::1/localhost）调用**，其他 IP 一律返回中性拒绝信息（不回显探测结果）。
+
+## 对外 API / dspy 端点（wwwroot/）
+
+- 编码查询：`get_code.dspy`（通用代码下拉查询：传 table/valueField/textField/cond，自动注入 userid/userorgid 变量）、`get_appcodes_kv.dspy`（专查 appcodes_kv）
+- 图标：`show_icon.dspy`（按 id 返回 svgicon.icon 内容）
+- 编码 CRUD：`api/appcodes_create.dspy`、`api/appcodes_update.dspy`、`api/appcodes_delete.dspy`、`api/appcodes_kv_create.dspy`、`api/appcodes_kv_update.dspy`、`api/appcodes_kv_delete.dspy`
+- 图标 CRUD：`api/svgicon_create.dspy`、`api/svgicon_update.dspy`、`api/svgicon_delete.dspy`
+- 日切：`cron/switch_bizdate.dspy`（配套 `cron/index.ui` 管理页）
+- UI：`menu.ui`
+
+## load 注册函数
+
+入口 `appbase/init.py` 的 **`load_appbase()`**：
+
+```python
+g = ServerEnv()
+g.get_business_date = get_business_date   # 来自 appbase.businessdate
+g.new_business_date = new_business_date
+```
+
+业务模块通过 `get_serverenv('get_business_date')` 或 `ServerEnv().get_business_date(sor)` 获取业务日期，不直接 import 本模块，保证跨宿主可移植。
+
+## 宿主集成
+
+宿主启动入口（sage.py、pipeline_app.py、cpcc.py、fileMGR.py 等）中**最先**加载：
+
+```python
+from appbase.init import load_appbase
+...
+load_appbase()   # 第一个：rbac/dapi/业务模块都依赖 params 与编码表
+load_rbac()
+load_dapi()
+```
+
+依赖：ahserver（ServerEnv）、sqlor（DBPools）、appPublic（timeUtils.strdate_add/jsonConfig）。被依赖方：rbac（register_open、org_type 编码）、dapi、accounting（bill_date/consume 取业务日期）、以及一切使用 appcodes_kv 下拉的业务模块。
+
+## 部署注意
+
+1. **初始化种子**：params 表必须预置 `business_date` 行（当天日期），否则 `get_business_date` 直接抛异常、记账链路全断；`register_open` 决定是否开放用户注册。
+2. **权限注册**：运行 `scripts/load_path.py`（`cd 宿主目录 && ./py3/bin/python ../appbase/scripts/load_path.py`）登记 /appbase 各端点为 logined 权限；它 import `rbac.rbac.set_path_perm`，因此须在 rbac 建表完成后执行。
+3. **switch_bizdate 定时任务**：仅供本机 cron 调用；若经 nginx 反代转发，注意 client_ip 取值不是回环地址会被拒。日切语义是"重置为当天自然日期"，手工推进用 `new_business_date()`（+1 天）。
+4. **编码表是全局字典**：新增下拉字典在 appcodes 建组、appcodes_kv 建键值，业务模块 models 的 `codes` 用 `cond: parentid='xxx'` 关联即可，勿在业务库重复造字典表。
+5. svgicon 的 icon 字段存原始 SVG 文本，`show_icon.dspy` 直接回显；图标内容属可信管理端录入，勿开放任意用户写入。
+6. 版本号见 `appbase/version.py`（当前 0.0.1）。