---
name: module-development-spec
version: 1.0.0
description: 开发「业务模块」（Python 包）时必读——模块目录结构（包目录=模块名，非 src）、模块无独立 app.py/端口/Dockerfile/build.sh（那些是应用级的，模块带 app.py 就是错的）、取库名用 get_module_dbname 禁止硬编码 DBNAME、models/json/dspy 四段式。开发「应用脚手架」（app/{应用名}.py + conf/config.json + build.sh）时不要用本技能，改用 web-application-spec。
trigger_conditions:
  - 开发业务模块（Python 包）时加载我，否则会产出带 app.py 的错误模块结构
  - Task involves implementing a component with bricks-framework frontend and sqlor database backend
  - Development follows the documented directory structure with wwwroot, models, json, and init directories
  - Task involves creating read-only/dashboard modules that display data without CRUD (no models/json needed)
---

## Work Logs / Delivery Archive

For production module/application development, update a dated work log (use the REAL current system date; late-night follow-up fixes go under their real date or are labeled next-day follow-ups) before finishing, e.g. `docs/work-log-YYYY-MM-DD.md`. Entry should include: scope/background + repo/module name; timeline/commit list; key technical decisions and pitfalls; verification performed (incl. environment-limited checks that couldn't run); current branch/commit state. Do NOT mark a task done without this archive when deliverables must be retained.

This skill defines the complete workflow for standardized modules: ahserver ecosystem + bricks-framework frontend + sqlor database backend.

## Module Philosophy — Host-Agnostic

- A module is a self-contained unit ANY host can load (pipeline-app / sage / future apps). It depends ONLY on: ① foundation packages (sqlor, ahserver ServerEnv, appPublic utilities); ② its own data tables (or shared tables like sage's appcodes); ③ other modules it explicitly imports.
- It does NOT depend on any host entry point, host-specific config files, or host wwwroot paths.
- `load_{module}()` is the ONLY integration point — it registers functions to ServerEnv; the host decides how to wire it in.
- **A module is NOT an independently deployable unit.** It has NO standalone `app.py` entry point, NO own port, NO own Dockerfile/service, NO own deploy script. It only runs because a host application calls `load_{module}()`. A module that carries its own `app.py` / port / deploy script is wrongly built — fix the module, don't deploy it separately.
- **Interaction-layer modules** (e.g. pipeline-task) have NO data tables — pure thin wrappers calling other modules' functions via ServerEnv; they provide .dspy + .ui only.

## 模块本地仓库位置

在 pipeline 产线机构工作空间中，模块本地仓库在机构 `modules/{模块名}/`（见 project-directory-spec）。模块是应用内的功能模块（Python 包），不是独立部署单元。

**部署测试前必须给模块仓库设置远程仓库**（`git remote add origin <远程地址>`），否则部署时无法 git pull 拉取最新代码。

## Directory Structure

```
mymodule/                 # module root (replace with actual name)
├── mymodule/             # Python package: __init__.py (required), init.py, *.py
├── wwwroot/              # frontend: .ui / .dspy / .js / .css
├── models/               # {tablename}.json database table definitions
├── json/                 # {alias}.json CRUD operation definitions
├── init/                 # data.json / data.yaml initial data
├── scripts/              # supporting scripts (load_path.py RBAC registration)
├── skill/SKILL.md        # MANDATORY agent-facing spec (data model, endpoints, pitfalls)
├── pyproject.toml        # Python packaging
└── README.md             # module documentation
```

## Core Implementation Requirements

### 1. Module Initialization (init.py)

- Purpose: register ALL module functions with ServerEnv so .ui/.dspy can call them directly. NOT for route registration (wwwroot files auto-routed via `/{module_name}/filename.ext`).
- **CRITICAL: export functions in `__init__.py`** — all async functions defined in init.py MUST be imported in the package `__init__.py`; otherwise dspy calls fail `NameError: name 'xxx' is not defined`.
- **Pitfall: Triple-place function registration** — adding/removing a function requires updating THREE files in sync: ① implementation (`mymodule/mymodule.py`); ② `__init__.py` import line; ③ `init.py` `env.xxx = xxx` in `load_{module}()`. Missing ② → ImportError/AttributeError at init; missing ③ → NameError in .dspy/.ui; removed from ① only → ImportError at load. Cleanup check: `grep -rn 'function_name' mymodule/ --include='*.py'` must hit exactly those three places.
- **Pitfall: CRUD dspy wrappers use PLURAL table names** — xls2ui generates wrappers (`add_suppliers.dspy`) calling `create_suppliers/update_suppliers/delete_suppliers`, while init.py usually defines singular names (`create_supplier`). Register BOTH: `env.create_supplier = create_supplier; env.create_suppliers = create_supplier` (same for update/delete). Symptom: CRUD "add" returns 500 `function not found`.
- **Pitfall: Subagent delegation for module creation — ALWAYS validate after** (subagents consistently err even with correct specs; observed 2/3 failure rate). Consistent errors: ① init.py/__init__.py misplaced at module ROOT instead of package dir; ② model JSON `{"table":...,"fields":{...}}` instead of `{"summary":[...],"fields":[...],"indexes":[...],"codes":[...]}`; ③ CRUD JSON `{"table":...,"list":{...}}` instead of `{"tblname":...,"params":{"browserfields":{...},"editable":{...}}}`; ④ hallucinated sqlor APIs (`sqlor.save/list/one/delete/insert/query` DO NOT EXIST — only `sor.C/U/D/R/I/sqlExe`). Mandatory validation: move misplaced files to package dir; check model JSONs have `summary` (array primary); check CRUD JSONs have `tblname` + `params.editable`; grep for fake sqlor APIs → fix to sor.C/U/D; dspy audit (no imports/print/uuid); py_compile all .py. See `references/bulk-module-creation-pattern.md` "Subagent Validation Checklist".
- **Pitfall: `debug()` in .dspy has NO filename** — logs show `[sage][debug][<string>:N]` (framework injects dspy code into a `<string>` context). Always prefix manually: `debug(f'product_category_create.dspy: START params_kw={dict(params_kw)}')` — essential when several dspy run in sequence (add → refresh).
- **Pitfall: DSPY API handlers must forward ALL client params — never hardcode dispatch fields** — e.g. read `task_type = params_kw.get('task_type', 'separate')` and forward `output_dir` if present; do NOT build `{'task_type': 'separate', ...}`. Symptom: client sends `separate_full` but worker log shows `separate`; hours to trace because the worker is correct — the DSPY silently drops the param. Audit: grep API dspy for hardcoded `'task_type'`/`'mode'` dispatch strings inside payload construction.
- **Pitfall: py_compile is INVALID for .dspy files** — dspy is injected into an async function at runtime (top-level `return`/`await` are correct); py_compile gives false positives (`'return' outside function`). Use py_compile only for .py; validate .dspy with the dspy audit script (grep-based).
- **CRITICAL: dspy MUST use explicit `return`** — ahserver wraps code in `async def myfunc(request, **ns):` and awaits it; a bare `result` expression returns None. See `references/dspy-execution-and-module-structure.md` (execution model, pre-loaded globals, Tree widget data format, module symlink patterns).
- **Pitfall: Sage startup requires environment variables** (e.g. `ALIPAY_PUB`) read at import time in `app/sage.py` — cannot full-start locally (FileNotFoundError). Validate with py_compile (.py) + dspy audit instead of startup.
- **Pitfall: Raw SQL column names — ALWAYS verify against models/{table}.json, never guess.** Check first: `python3 -c "import json; cols=[f['name'] for f in json.load(open('models/table.json'))['fields']]; print(cols)"`. Known wrong guesses → correct: permission `permcode/permname` → `path/name`; users `created_date` → `created_at`; organization `org_name` → `orgname`.
- **Pitfall: `{{id}}` in uapi response templates resolves to Python built-in `id()`** — renders `<built-in function id>` instead of the field. NEVER use `{{id}}`; map to a different name: `'{"taskid":"{{taskid}}","status":"{{status}}"}'`. Affects any uapi whose upstream response has an `id` field.
- **Pitfall: uapiio `input_fields` MUST be a JSON array** — bricks.js LlmIO calls `this.input_fields.forEach(...)`; an object `{"field":{...}}` throws `TypeError: this.input_fields.forEach is not a function`. Use array form: `[{"name":"prompt","label":"用户输入","uitype":"text","required":true}]`. Canonical reference: existing `ktv_asr_transcribe_io` record.
- **Pitfall: `json.dumps()` in uapi data templates → `data=None`** — `{{json.dumps(prompt, ensure_ascii=False)}}` can render silently to None (logs `body=None`). Use plain string interpolation `"{{prompt}}"` and HARDCODE the upstream model ID (`"model":"hy-image-v3.0"`), don't pass `{{model}}`. Source real model IDs from provider `/v3/models` (ARK) or `/v1/models` (tokenhub).
- **Pitfall: `return` inside `async with` → silent NoneType** — returning inside `async with db.sqlorContext(...) as sor:` returns None → `return data type error, <class 'NoneType'>`. Collect results inside the block, `return` AFTER it exits. Minimal repro: `return {'ok': True}` inside async with also fails.
- **Pitfall: `sor.C()` silently drops records when `created_at` missing** — sqlor does NOT auto-set timestamps; with `created_at TIMESTAMP NOT NULL` the insert silently vanishes. Always set `ns['created_at'] = curDateString()` (and `ns['org_id'] = (await get_userorgid()) or '0'`). Symptom: dspy returns `{"success": true}` but SELECT returns zero rows.
- **Pitfall: Bash heredoc `\$` escapes corrupt sqlor placeholders** — `cat > f.dspy << 'EOF'` with `\${pid}\$` writes the backslash literally; sqlor fails silently on the unrecognized placeholder. Never escape `$` in single-quoted heredocs — write `${pid}$` as-is. Verify: `grep 'project_id' file.dspy | cat -A` must show no `\$`.
- **Pitfall: Do NOT name module functions `get_module_dbname`** — that name is already a ServerEnv-provided global used by .dspy; registering it overwrites the global. Use a private prefix (`_get_dbname()`).

### 2. Frontend Development

- **Mandatory**: bricks-framework for all frontend; .ui files as PURE JSON (NOT HTML/CSS) in wwwroot/; auto-routed `/{module_name}/filename.ext` — no manual route registration. See `references/bricks-ui-pitfalls.md` (id at widget level not options, Button click, Popup/Form patterns, script actiontype Jinja2 limits).
- **ahserver auto-serves .css/.js from wwwroot/** — DO NOT add `<link>`/`<script>` tags in .ui files (common mistake → unnecessary 403 with RBAC). BUT auto-served files are STILL subject to RBAC: every .css/.js MUST be registered in load_path.py; pre-auth files (theme CSS) use `any` role.
- build.sh links module wwwroot into the main app's wwwroot.

#### 2.0 Module Entry Point (index.ui) — MANDATORY

- Every business module MUST have `wwwroot/index.ui` (exempt: foundation/reference modules rbac, appbase, accounting, apppublic, sqlor, ahserver). It integrates ALL .ui/.dspy into one navigation page: ResponsableBox with clickable card widgets (VBox + binds click → urlwidget) per feature; default content area VBox with `id: "app.<module>_content"` for urlwidget targets.
- **ALL url values MUST use `{{entire_url('filename.ui')}}` / `{{entire_url('api/xxx.dspy')}}`** (converts server-relative paths to the correct runtime URL prefix). Pattern:

```json
{"widgettype":"VBox","options":{"width":"100%","height":"100%","padding":"20px"},"subwidgets":[
  {"widgettype":"Text","options":{"label":"模块名称","fontSize":"24px"}},
  {"widgettype":"ResponsableBox","options":{"gap":"16px","minWidth":"250px"},"subwidgets":[
    {"widgettype":"VBox","options":{"backgroundColor":"#FFFFFF","padding":"20px","cursor":"pointer"},
     "binds":[{"wid":"self","event":"click","actiontype":"urlwidget","target":"app.module_content",
               "options":{"url":"{{entire_url('feature_page.ui')}}"},"mode":"replace"}],
     "subwidgets":[{"widgettype":"Text","options":{"label":"功能名称"}}]}]},
  {"widgettype":"VBox","id":"module_content","options":{"width":"100%","flex":"1","marginTop":"20px"}}]}
```

#### 2.1 URL Path Rules — MANDATORY

- ALL url fields (Menu items, Button url, Form url, Iframe url, urlwidget targets, any url property) MUST use `{{entire_url(url)}}`. WRONG: `"url": "/module/page.ui"` or `"url": "feature.ui"`. CORRECT: `"url": "{{entire_url('/module/page.ui')}}"`.
- Do NOT wrap: `data:` URIs, `#` anchors, `http(s)://` URLs, `${var}` variable references.

#### 2.2 JSON CRUD File URL Rules — MANDATORY

- CRUD definitions in `json/` referencing SAME-module aliases MUST use `../` prefix: `"url": "{{entire_url('../handover_items_list')}}"` (json/ is a subdir; the .dspy CRUD files and generated .ui live at wwwroot root, so URLs must step out of json/). Applies to `subtables[].url`, `browserfields` `dataurl`, etc. Cross-module aliases (e.g. `appcodes_list`) need NO `../` — resolved via inter-module routing.

#### 2.2a CRUD `new_data_url` — Do NOT Pass `editexclouded` Fields as Query Params

- If `new_data_url` passes a field as query param (`?supplier_id=...`) that is also in `editexclouded`, form POST body + URL params merge into `params_kw` as a LIST → `sor.C` gets a list → MySQL `Operand should contain 1 column(s)`. Fix: remove the query param from `new_data_url`; if the field must be pre-set (subtable context), add it as a hidden form field instead. CORRECT: `"new_data_url": "{{entire_url('../api/create.dspy')}}"`.

#### 2.3 JSON CRUD `editable` Section — MANDATORY

- All DataViewer/Tabular list JSON configs MUST include an `editable` segment, else 新增/编辑/删除 buttons can't submit. It defines three target URLs pointing at `wwwroot/api/` .dspy scripts.
- **`new_data_url`/`update_data_url`/`delete_data_url` MUST be at `params` TOP LEVEL — NOT nested inside `editable`.** xls2ddl reads them from params top level (`{% if new_data_url %}`); nesting silently generates the default `add_{tablename}.dspy`, bypassing any custom create logic. Real case (2026-07-13): discount module nested them → `created_by` never set by custom handler; fixed by moving to params top level with `/module/api/` absolute paths.
- `wwwroot` is the web root and invisible in URLs — paths must NOT contain `wwwroot/`; from json/ context use `../api/` → `"new_data_url": "{{entire_url('/module/api/tablename_create.dspy')}}"` etc.
- The three .dspy files (`xxx_create.dspy`, `xxx_update.dspy`, `xxx_delete.dspy`) MUST exist in `wwwroot/api/`. Missing `editable` → `build_add_form()`/`build_update_form()` fail on undefined `this.editable.new_data_url`. `_edit.json` (form edit page) needs editable too. Templates: `references/json-config-pattern.md`, `references/crud-json-toolbar-bind-pattern.md`.

#### 2.3b bricks Toolbar Bind — Only 5 Valid Actiontypes

- Valid `actiontype`: `urlwidget`, `script`, `url`, `datawidget`, `event`. `dspy` and `function` are NOT valid. Toolbar → dspy pattern: `{"actiontype":"urlwidget","target":"PopupWindow","popup_options":{"title":"标题","height":"200px","width":"400px"},"params_mapping":{"mapping":{"id":"target_param"},"need_other":false},"options":{"method":"POST","url":"{{entire_url('../api/xxx.dspy')}}"}}` — dspy return renders in the PopupWindow; if it returns a DataViewer widget, the url must carry `_webbricks_=1`.
- **禁止**: `fetch()` / `bricks_fetch()` / setInterval inside `script` actiontype — bricks explicitly forbids fetch/setInterval in script.

#### 2.3c Module-Internal `entire_url()` Must Use Absolute /module/ Paths

- `entire_url('supply_contracts_list')` may resolve WITHOUT the module prefix (`/supply_contracts_list` instead of `/supplychain/supply_contracts_list`) → RBAC 403. Use `{{entire_url('/supplychain/supply_contracts_list')}}` in index.ui/menu.ui. Check: `grep "entire_url(" wwwroot/index.ui wwwroot/menu.ui | grep -v '/supplychain/'`.

#### 2.3d dspy-Returned DataViewer URL Must Be Absolute

- dspy has NO `entire_url()` (Jinja2-only). Return an absolute path in the widget: `'url': f'/supplychain/supply_contracts_list?supplier_id={supplier_id}&_webbricks_=1'` (relative `../...` resolves wrong inside PopupWindow context).

#### 2.4 Menu Widget — Do NOT use binds

- Menu handles clicks internally — no extra binds for itemclick. Just set `url: "{{entire_url('page.ui')}}"` on items.

#### 2.5 DSPY File Guidelines

- ahserver supports GET and POST (framework distinguishes). ALL params (query string AND POST body; nested JSON objects/arrays preserved) auto-parsed into `params_kw` (dict-like): `params_kw.get('key')` / `params_kw.key`. Do NOT read POST via `os.environ`/`os.read()`/`sys.stdin`.
- Return consistent JSON: `status`, `data`, optional `message`/`total`. Validate inputs; call business logic from init.py-registered functions.
- Logging: use `debug_params('name', dict_obj)` instead of `debug(f'{dict_obj=}')` (dumps whole objects). To add a new global available in ALL .dspy, inject via `self.y_env` in `ahserver/processorResource.py` (see `references/web-app-and-dspy-spec.md`).

#### CRITICAL: ServerEnv() is NOT needed in .dspy scripts

- DO NOT write `env = ServerEnv()` in .dspy. All ServerEnv-registered functions are direct globals: `get_module_dbname()`, `get_user()`, `get_userorgid()`, `DBPools()`, `password_encode()`, `getID()`, module functions like `create_user_apikey`. CORRECT: `dbname = get_module_dbname('dapi')`; `org_id = (await get_userorgid()) or '0'`. `ServerEnv()` only in .py module files.
- **Pitfall: `ServerEnv()` is a process-level singleton** — every call returns the SAME instance; `env.get_module_dbname = ...` set anywhere is visible everywhere. Do NOT assume a new instance per call.
- **Pitfall: `ServerEnv()` ≠ `request._run_ns` — NEVER use `ServerEnv()` for per-request user/session context.** `get_user()/get_userid()/get_userorgid()` are registered on `request._run_ns` (a.k.a. `self.y_env`, a plain DictObject set in processorResource.py:347-349), NOT on the singleton — `await env.get_user()` silently returns None → created_by/org_id NULL. CORRECT in .py: `env = request._run_ns; user_id = await env.get_user()`. `ServerEnv()` is correct only in `load_{module}()` (startup) and for startup-time globals with no request. Detection: `grep -n 'env = ServerEnv()' module/init.py` and check the next 6 lines for get_user/get_userorgid/get_userid. Real case (2026-07-13): discount `create_marketing` → created_by always NULL, 7 functions affected (sibling `generate_promo_code` correctly used `request._run_ns`).
- **Pitfall: Module pkgs go under the HOST app's `pkgs/`, not cross-applications** — e.g. tenant module at `/d/apitest/sage/pkgs/tenant/` with symlink `sage/wwwroot/tenant -> ../pkgs/tenant/wwwroot`; NOT under `/d/apitest/pipeline-app/pkgs/tenant/`. Each application installs modules into its OWN `pkgs/` — cross-app placement breaks module independence.

#### sqlor method argument counts — `sor.I` is special

| Method | Args | Pattern |
|--------|------|---------|
| sor.C / sor.R / sor.U / sor.D | 2 | `sor.C('table', ns)` |
| sor.I | 1 | `sor.I(ns)` — table name resolved from the sqlor context |

`sor.I('table', data)` → `TypeError: I() takes 2 positional arguments but 3 were given`.

## Read-Only / Dashboard Modules

Not all modules need tables/CRUD — `models/` and `json/` can be omitted entirely. Preferred pattern: `load_XX.py` exposes async data functions via ServerEnv → individual .ui files use Jinja2 `{{get_data(request)}}` → `RefreshWidget` wraps each card for auto-refresh (NO .dspy files or JS polling). See `references/read-only-module-pattern.md`: Jinja2+RefreshWidget architecture (preferred), legacy .dspy+JS polling (deprecated), ECharts ChartBar/ChartLine with inline data or data_url, cross-table queries via the shared `sage` database, concurrent-user detection.

## Database Integration

- **Mandatory**: use sqlor-database-module for all relational operations. Table definitions as `{tablename}.json` in models/; CRUD definitions as `{tablename_or_alias}.json` in json/.
- **Bulk xlsx→json conversion**: `scripts/xlsx2json_models.py` converts all `.xlsx` model files across Sage modules to JSON in one pass.
- **CRITICAL: 模块取库名禁止硬编码 DBNAME** —— 库名由宿主应用决定，不是模块自己写死。模块取库名统一用 `get_module_dbname('模块名')`（.dspy 里直接调用，是 ServerEnv 注入的全局，无需 import）或 `ServerEnv().get_module_dbname('模块名')`（.py 模块文件里）。**禁止**在模块里写 `DBNAME = 'hrs6'` / `DBNAME = 'sage'` / `dbname = 'xxx'` 之类硬编码——同一模块可被多个应用挂载，各应用的库名不同，硬编码会查错库或 table-not-found。宿主应用在 `app/{appname}.py` 里定义 `get_module_dbname(m)` 并挂到 ServerEnv（见 web-application-spec）。

### 4. Initialization Data (init/data.json or init/data.yaml — three formats)

- **硬性约束：init/data.json 必须是合法 JSON 的真实种子数据，禁止占位符文本**。写「8 组 appcodes 编码种子」这类纯描述文字（不是 JSON）会导致部署时 `json.load` 失败（`JSONDecodeError`）→ 建表/插种子中断 → 应用起不来。每个模块的 init 数据必须写完整真实数据（appcodes 组 + 每个 k/v），不能只写「应该有几组」的描述。交付前用 `python3 -c "import json;json.load(open('init/data.json'))"` 自验 JSON 合法性。

- **Format A — Direct table seeding** (JSON): `{"table1": [{"field1":"value1", ...}, ...]}`
- **Format B — Appcodes registration** (JSON): `{"appcodes":[{"parentid":"sc_relation_type","parentname":"供销关系合作类型","items":[{"k":"distribution","v":"分销"},{"k":"agency","v":"代理"}]}]}`
- **Format C — Appcodes registration** (YAML, used by accounting etc.): `appcodes:` entries use `{id, name, hierarchy_flg}`; `appcodes_kv:` entries are FLAT records `{id, parentid, k, v}` (not nested under items). `parentid` in appcodes_kv must match an `appcodes.id`. When adding a code group, add BOTH the appcodes parent AND all appcodes_kv children.
- **Pitfall: parentid too long → appcodes_kv.id exceeds VARCHAR(32)** — the loader generates `id = {parentid}_{k}`; both `id` and `parentid` are `VARCHAR(32)`. `supplier_settlement_cycle` (27) + `quarterly` (9) = 37 chars → `DataError: Data too long for column 'id'`. Rule: `len(parentid) + 1 + len(longest_k) ≤ 32` → keep parentids ≤ 22 chars. If already referenced in `models/*.json` codes `cond`, update BOTH init/data.json and all referencing model files.
- **Pitfall: YAML `hierarchy_flg：0` fullwidth colon** — pre-existing quirk in some data.yaml files (fullwidth `：` instead of ASCII `:`). Do NOT "fix" unless the user asks — it may break the loader expecting the original format.

### 5. Encoding Management

- Encodings live in appbase tables: `appcodes` (id str(32) PK, name, hierarchy_flg str(1) — '0'=single-level, '1'=multi-level); `appcodes_kv` (id str(32) PK, parentid str(32), k str(32), v str(255)).

### 5b. Codes Referencing Future Modules

- Even when a field references a module that doesn't exist yet (e.g. `productid` → future `products`), STILL add the codes entry now: `{"codes":[{"field":"productid","table":"products","valuefield":"id","textfield":"product_name"}]}`. Safe — codes only affect UI dropdown rendering and are ignored if the table is missing. Do NOT defer until the referenced module exists.

## pyproject.toml Configuration

- Package `name` MUST match the module directory exactly (e.g. `name = "customer_management"`).
- Dependencies: only DIRECT code deps — `"sqlor"` (NOT `"sqlor-database-module"`), `"bricks_for_python"` (NOT `"bricks-framework"`). Do NOT list foundation packages (`ahserver`, `appbase`, `rbac`, `apppublic`) — installed by build.sh separately, not on PyPI. `pip install .` must succeed locally without fetching non-PyPI packages.

```toml
[build-system]
requires = ["setuptools>=45", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "mymodule"
version = "1.0.0"
requires-python = ">=3.8"
dependencies = ["sqlor", "bricks_for_python"]

[tool.setuptools.packages.find]
where = ["."]
include = ["mymodule*"]
```

## Project Files

- **README.md**: purpose, features, data tables, installation, integration in plain language — never empty or boilerplate-only.
- **skill/SKILL.md (MANDATORY per module repo)**: YAML frontmatter (name, description) + markdown covering module architecture, data model (note when no tables), key DSPY endpoints, module-specific pitfalls. Concise — consumed by AI agents.
- **build.sh**: module build script integrated into the main application's build process.

## Build Process Integration

build.sh processes ALL modules with models/ or json/: ① install `xls2ddl`; ② models/ with .xlsx → `xls2ddl mysql . > mysql.ddl.sql`; ③ models/ with .json → `json2ddl mysql . > mysql.ddl.sql`; ④ json/ → `xls2ui -m ../models -o ../wwwroot ${modulename} *.json` (generates CRUD UI); ⑤ symlink module wwwroot → main app wwwroot.

### CRITICAL: Symlink Generated CRUD Directories

- xls2ui generates **subdirectories** per CRUD alias (`wwwroot/{alias}/` with index.ui, get_/add_/update_/delete_*.dspy). These are NOT covered by individual-file symlink rules — link whole directories: `ln -sf /path/to/module/wwwroot/{alias}/ .` (in build.sh: auto-link all wwwroot subdirs except `api|styles|scripts`).
- Symptoms: CRUD pages 404 even though xls2ui ran (dir exists in module wwwroot but not linked); `processorResource.py: raise Exception(f'{str(request.url)=} invalid path')` = URL path not in ahserver's route table ≈ file/dir not symlinked to deployment target's wwwroot.

### CRITICAL: CRUD-Generated Directories Are READ-ONLY — Never Modify Files Inside

- Every file in `wwwroot/{alias}/` (index.ui, get_/add_/update_/delete_*.dspy) is AUTO-GENERATED — never edit directly. WRONG: editing them; CORRECT: edit `json/{alias}.json` (CRUD definition) / `models/{table}.json` (table definition) → re-run build.sh (xls2ui regenerates and overwrites).
- **JSON manipulation safety**: complex .ui files are error-prone to string insertion (one missing comma silently breaks the page). ALWAYS read with `json.load()` → modify dict → write with `json.dump()`.
- **Pitfall: xls2ddl `data_new_tmpl` `{{summary[0].pkey}}` → `WHERE None = %s`** — model JSONs use `primary` (an array), NOT `pkey`; Jinja2 renders the missing attr as None → `OperationalError: (1054, Unknown column 'None' in 'WHERE')` on EVERY add across all CRUD tables (xls2ddl commit fc91486, June 2026). Fix: `{{summary[0].primary[0]}}` in `xls2ddl/xls2ddl/tmpls.py` line 308.
- When json/ config cannot express needed logic: ① create custom dspy in `wwwroot/api/` (e.g. api/add_user.dspy); ② point `new_data_url`/`update_data_url`/`delete_data_url` at it; ③ register paths in `scripts/load_path.py` (RBAC) + `sage/load_path.py` (routing); ④ re-run xls2ui — generated index.ui uses the custom URLs.
- **Pitfall: bricks Tabular code fields submit values as LISTS** — root cause: the field appears in BOTH `new_data_url` query params AND `editexclouded` → ahserver merges URL + body into a list. The correct fix is the JSON config (drop the duplicate query param), NOT list-unwrap workarounds in every dspy.
- Common api/ dspy customizations: set defaults (`ns['created_at'] = curDateString()`); auto-generate business codes like `contract_code` (see `references/custom-create-dspy-required-fields.md`); clean `_text` suffix fields before sor.U/C (Tabular sends these from code lookups); preserve password on update (pop empty password from ns); `try/except` with `format_exc()` + `str(e)` to show real errors to frontend.
- **CRITICAL: Model JSON changes require xls2ui rebuild** — changing models/*.json (codes/fields/indexes) does NOT auto-update generated CRUD .ui. Re-run build.sh after ANY model change, else dropdowns/forms/views keep the old model. #1 cause of "I changed the model but the page still shows old data". See `references/model-change-rebuild-pitfalls.md` (.xlsx/.json load order, get_code.dspy module.table resolution failure, collation mismatch).
- **Pitfall: post-rebuild THREE checks** — ① files exist: `ls wwwroot/<module>/<alias>/index.ui` (rebuild can fail silently); ② symlinks intact for root-level alias URLs: `ls -la sage/wwwroot/<alias>` → should point to `sage/wwwroot/<module>/<alias>`; ③ RBAC refreshed: new index.ui has new dataurl/get_code.dspy calls → verify permissions exist AND restart Sage (RBAC cache has 10-min TTL; load_path.py inserts permissions but doesn't assign roleperm for existing ones).
- **Pitfall: xls2ui strips code-type fields from generated editexclouded** — a field in BOTH `browserfields.alters` (uitype `code` + dataurl) AND `editexclouded` is stripped from generated index.ui's editexclouded → bricks renders a UiCode widget calling `.build_options()` on undefined. Symptom: `TypeError: Cannot read properties of undefined (reading 'length')` at `bricks.UiCode.build_options` on Add/Edit. Fix: add missing fields back to the generated index.ui editexclouded (`.gitignore`'d → `git add -f`); the fix is undone if xls2ui re-runs, so deploy with `git pull` only, skipping build.sh. Long-term: fix xls2ui. Verification (per alias): compare source `json/{alias}.json` `params.editexclouded` vs generated `wwwroot/{alias}/index.ui` `row_options.editexclouded`.
- **Pitfall: `cheight` on CRUD index.ui makes title row fill viewport** — generated files contain `"cheight":40` on both outer VBox and Tabular options; remove ALL `cheight` properties (Tabular sizes itself). Check: `grep -rn 'cheight' wwwroot/*/index.ui`.

### CRITICAL: Do NOT Replace Framework-Generated Code with Custom Scripts

- CRUD framework endpoints are base functionality (handle RBAC, `logined_userorgid`, `confidential_fields` redaction, DBFilter parsing). Do NOT hand-write replacements — e.g. creating `api/llm_list.dspy` to replace generated `get_llm.dspy` just for `_text` display; instead fix the `dataurl` API to return `[{field_name, field_name_text}]`. Custom scripts often violate .dspy conventions and create maintenance burden. Propose custom scripts ONLY for genuine special requirements — and **discuss the approach FIRST**. Zero tolerance for unsolicited replacement of stable framework code.

### CRITICAL: Hand-written list .dspy SHADOWS framework auto-generated endpoints

- If `json/{alias}_list.json` exists, the framework auto-generates `wwwroot/{alias}/get_{table}_list.dspy`. A hand-written `wwwroot/api/get_{table}_list.dspy` SHADOWS it → 500s (filters like org_id on missing fields), 403s (bypasses framework RBAC/logined_userorgid), silent data leakage (misses confidential_fields redaction). **Rule**: if `json/{alias}_list.json` exists, do NOT create `api/get_{table}_list.dspy`. Hand-write only: custom business-logic endpoints (create/update/delete beyond simple CRUD) and client dropdown data APIs returning `[{value, text}]` (NOT list endpoints). Detection: list endpoint 500/403 + both files exist → delete the hand-written one.

### CRITICAL: CRUD-Generated wwwroot Directories Must NOT Be Git-Tracked

- They are build artifacts, regenerated by build.sh on every deployment. Add .gitignore entries per alias (`wwwroot/llm/`, `wwwroot/llmusage/`, ...). WRONG: `git add wwwroot/`; CORRECT: `git add wwwroot/index.ui wwwroot/api/ wwwroot/*.js wwwroot/*.css` (hand-written only).

### CRITICAL: Selective `git add` in Module Repos

- NEVER `git add -A` or `git add wwwroot/` — module repos contain generated content: `build/`, `*.egg-info/`, `__pycache__/`, CRUD-generated wwwroot subdirs, `*.swp`/`*.swo`. Use selective adds: `git add mymodule/__init__.py mymodule/init.py`; `git add wwwroot/index.ui wwwroot/api/ wwwroot/*.js wwwroot/*.css`; `git add json/ models/`.

### CRITICAL: Manual Symlink for New Files During Development

- New .ui/.dspy/.js/.css are NOT available until linked: `ln -sf <module>/wwwroot/new_page.ui sage/wwwroot/<module>/`, `ln -sf <module>/wwwroot/api/new_api.dspy sage/wwwroot/<module>/api/` (or re-run build.sh). **.js/.css MUST be linked at module wwwroot ROOT level** (not `scripts/`/`styles/` subdirs) — Sage's header.tmpl only scans the root of each linked wwwroot. Symptom: 500 with `fpath is None` / `invalid path` — file exists in module but isn't linked.

### CRITICAL: build.sh SAGE_ROOT Detection

- Standalone module repos (e.g. `~/repos/mymodule/`) are NOT nested under Sage — do NOT assume `$SCRIPT_DIR/../..` is Sage root. Search candidates:

```bash
for candidate in "$SCRIPT_DIR/../.." "$HOME/repos/sage" "$HOME/sage"; do
    if [ -d "$candidate/wwwroot" ] && [ -d "$candidate/py3/bin" ]; then
        SAGE_ROOT="$(cd "$candidate" && pwd)"; break
    fi
done
```

## Sage System Integration — Four Wiring Points

New modules need FOUR changes in the Sage repo before appearing in the UI (missing any one → functions not registered / not installed on fresh deploy / 403 on access / no menu item):

1. **`app/sage.py`**: `from mymodule.init import load_mymodule` at top; `load_mymodule()` inside `init()`.
2. **`build.sh`**: add module to install loop (`for m in appbase rbac ... mymodule; do cd $cdir/pkgs; git clone https://git.opencomputing.cn/yumoqing/$m; pip install .; done`).
3. **`load_path.py` (RBAC)**: explicit entries. Roles: `any` — no login (menu.ui, static JS/CSS, public resources); `logined` — authenticated (.ui pages, .dspy APIs); `owner.superuser` / `owner.operator` — role-restricted admin features. Run: `cd ~/repos/sage && ./py3/bin/python load_path.py`. **load_path.py is the centralized declarative source of truth; `set_role_perm.py` is for ad-hoc fixes only and does NOT survive a fresh database restore.**
4. **`global_menu.ui`** — add to `items` array in `sage/wwwroot/global_menu.ui`:
```json
,{"name":"modulename","label":"模块名称","icon":"fa fa-icon-name","url":"{{entire_url('/modulename/index.ui')}}","target":"app.sage_main_content"}
```
**CRITICAL: NO conditional menu items** — do NOT wrap items in `{% if get_user() %}` or role checks: Sage's dynamic menu loading does not work, items inside conditionals are never rendered. Place ALL module items unconditionally at items top level. Only exception: `dashboard` (always visible by design) and explicitly role-hidden items. Access control is RBAC (403 on click is correct behavior), not menu hiding.

### CRITICAL: load_path.py Wildcards are FORBIDDEN

- NEVER use `%` or `*` wildcards in any load_path.py — hard policy, not a suggestion. Every path explicit: every .dspy, every CRUD subdir file, every .ui, every image. CRUD subdir standard pattern (5 entries per alias, generated by xls2ui from json/*.json): `/{MOD}/{alias}`, `/{MOD}/{alias}/index.ui`, `/{MOD}/{alias}/get_{alias}.dspy`, `/{MOD}/{alias}/add_{alias}.dspy`, `/{MOD}/{alias}/update_{alias}.dspy`, `/{MOD}/{alias}/delete_{alias}.dspy`.
- Maintenance: adding .dspy files ⇒ add to `PATHS_LOGINED`/`PATHS_ANY`; removing files ⇒ remove entries. Cross-module audit: `find ~/repos -name "load_path.py"` + `grep -rn '%' --include="load_path.py"` — all modules must be wildcard-free.

### CRITICAL: Dual-Layer RBAC (per-module script + central fallback)

- Per-module `scripts/load_path.py` (calls `set_role_perm.py` directly) can FAIL SILENTLY — observed `ModuleNotFoundError: No module named 'appPublic.event_dispatcher'` for cpcc, product_management, pricing, etc. So ALWAYS ALSO add entries to the central `~/repos/sage/load_path.py` (different code path, reliable fallback). Symptom if only the per-module script exists and fails: module shows in menu but every click returns 403. Verify: `grep -c '/modulename' ~/repos/sage/load_path.py` → > 0.

### 5. Execute per-module `scripts/load_path.py` (if it exists)

```bash
cd ~/repos/sage && ./py3/bin/python ~/repos/<module>/scripts/load_path.py
```

### RBAC Permission Setup (preferred: per-module)

- Each business module should own `scripts/load_path.py`: auto-find Sage root; paths by role tier (any/logined/role-specific); call set_role_perm.py per path; register BOTH directory path (`/module/crud_alias` — auto-matches index.ui) AND file path (`/module/crud_alias/index.ui`). **Maintenance rule**: 每次代码变更如有新 path 出现，需同步更新此脚本. Templates: `references/per-module-rbac-pattern.md`, `references/per-module-load-path-pattern.md`. NOTE: some modules (e.g. llmage) use the CENTRAL `~/repos/sage/load_path.py` instead — check before creating a per-module script.
- Legacy central approach: add entries to `paths=""` in `~/repos/sage/load_path.py` (`/module_name logined`, `/module_name/index.ui logined`, `/module_name/menu.ui any`, `/module_name/api/xxx.dspy logined`, `/module_name/xxx.js any`), run `./py3/bin/python load_path.py`, restart `./stop.sh && ./start.sh`. Both set_role_perm.py and load_path.py must use explicit paths — no wildcards in either.
- Do NOT reference .css/.js via `<link>`/`<script>` in .ui — ahserver auto-serves them, but they still need RBAC registration in load_path.py.

## Multi-Tenant Reseller Module Pattern

Core principle: every table, CRUD definition, and API endpoint scoped by `org_id` — resellers never share categories/products/configs.

- **Table design**: every table MUST have `org_id VARCHAR(32) DEFAULT '0'`; composite unique indexes `(org_id, business_key)` e.g. `UNIQUE(org_id, product_code)`; FK lookups include org in JOIN: `JOIN t2 ON t1.cat_id = t2.id AND t1.org_id = t2.org_id`.
- **Dynamic attributes**: `product_type` = STRING identifier (NOT a physical table name) + `extra_json` (TEXT/LONGTEXT) for reseller-specific attrs (no schema changes); category tables store `product_type` + `product_type_title` for display (not `product_table_name`); standardized APIs (`product_detail`, `product_use`) parse extra_json → return `extra_parsed`.
- **CRUD**: `logined_userorgid: "org_id"` on ALL list CRUD definitions (auto org-scoped filtering); category dropdown dataurl → API filtering by current user's org; `subtables[].url` uses `../` prefix and respects org boundaries.
- **.dspy**: get org via `org_id = (await get_userorgid()) or '0'` (or with override: `org_id = params_kw.get('org_id', None) or (await get_userorgid()) or '0'`); NEVER `env = ServerEnv(); getattr(env,'orgid',...)`. ALL SQL MUST include org_id in WHERE; create/update/delete MUST verify record ownership; category trees MUST verify parent belongs to same org; dropdown APIs filter `WHERE org_id = ${org_id}$`.
- **Operator config**: `product_type_config` table with unique `(org_id, operator_id, category_id, config_name)`; `config_json` TEXT → parse to `config_parsed`; fallback query `WHERE operator_id = ${user_id}$ OR operator_id = '0'` (0 = global default).
- **Pitfalls**: ① NO `product_table_name` physical routing — breaks across resellers; use `product_type` + `extra_json`. ② Do NOT preset global category data in `init/data.json` — categories are per-reseller; init data only for appcodes/encodings. ③ JOIN without org_id = DATA LEAK (`LEFT JOIN pc ON p.category_id = pc.id` needs `AND p.org_id = pc.org_id`). ④ `UNIQUE(product_code)` without org_id = cross-reseller conflicts. ⑤ `DBPools()` is a `@SingletonDecorator` singleton — never `db.databases = config.databases` or `DBPools(config.databases)`; just `DBPools().sqlorContext(dbname)`. ⑥ In .py module files get org_id via `env = ServerEnv(); org_id = getattr(env, 'orgid', None) or getattr(env, 'org_id', '0')` — DIFFERENT from .dspy files (await get_userorgid()).

## Multi-Module Changes: PR Isolation

When changes span multiple Sage modules, EACH module gets its own feature branch + independent PR (`accounting: feat/dataviz-accounting → PR#1`, `llmage: feat/dataviz-llmage → PR#2`, ...). Do NOT combine multi-module changes into one branch — keeps review focused, allows partial merges, prevents blocking unrelated modules.

## Cross-Module Changes: Where to Make Changes

- All modules are independent git repos at `~/repos/<module>/` — edit/commit/push there. There is NO `sage/pkgs/` directory (deleted May 2026). For cross-module changes, check each affected repo separately; after each round verify no stale patterns: `grep -rn 'old_pattern' ~/repos/<module>/ --include='*.py' --include='*.dspy'`. **Restart Sage after all code changes** (reloads modules from disk).

## Database Schema Migration

See `references/database-migration-pattern.md`: adding tables / changing relationships (1:N → M:N), idempotent migration scripts with safety checks, RBAC for new CRUD endpoints, safe column removal.

**Intermediate table removal** (e.g. `uapiset` between `upapp` and `uapi`): ① `ALTER TABLE child ADD COLUMN parent_id ...`; ② move intermediate-table fields (e.g. `auth_apiname`) to parent; ③ update model JSON (remove old FK, add new FK, update indexes, drop codes references to removed table); ④ update ALL Python code — remove JOINs in every .py of the module repo AND any other referencing modules; ⑤ delete `models/{intermediate}.json` + `json/{intermediate}.json`; ⑥ data migration for shared records (pattern: `~/repos/uapi/scripts/migrate_uapi_upappid.py`); ⑦ verify `grep -rn 'intermediate_table' ~/repos/{mod}/ --include='*.py'` returns nothing. Details: `references/intermediate-table-removal-pattern.md`, `references/uapi-uapiset-removal-detail.md`.

## Development Workflow

### CRITICAL: Repos First, Test Second

1. Modify source in `~/repos/` FIRST (canonical, version-controlled) → 2. git commit immediately → 3. sync to test env (`~/test/` or deployment dir) → 4. NEVER modify test env directly (changes lost/untracked, vanish on redeploy). Zero tolerance for "I fixed it in test but didn't update repos".
- **scp/sed directly to servers is FORBIDDEN** (tokentest, production): never scp files or `sed -i` on deployment servers. Always: local repos → commit → push → server git pull → pip install. Direct edits bypass version control and get overwritten next deploy. Only exception: one-off read-only diagnostics (grep, mysql queries, log inspection).

**Standard development order for a new module**: ① create directory structure; ② table definitions in models/; ③ CRUD definitions in json/; ④ backend functions in `{module}/init.py` — one async function per CRUD op per table, registered via `load_{module}()` + ServerEnv; ⑤ generate `wwwroot/api/*.dspy` thin wrappers delegating to init.py functions (bulk generation script in `references/bulk-module-creation-pattern.md`); ⑥ frontend in wwwroot/ (index.ui + menu.ui first; CRUD UI auto-generated by xls2ui); ⑦ init/data.json if needed; ⑧ pyproject.toml + build.sh; ⑨ README.md with Sage integration steps; ⑩ wire into Sage (4 points above) + run per-module scripts/load_path.py; ⑪ skill/ with SKILL.md + references/assets/scripts.

## Parameter Access: .py vs .dspy/.ui

- **.dspy/.ui**: `params_kw` is a global — `discountid = params_kw.get('discountid')` / `{{params_kw.discountid}}`.
- **.py functions called from Jinja2**: `request._run_ns.params_kw` — `env = request._run_ns; val = (request._run_ns.params_kw or {}).get('key', '')`.
- **Wrong attribute names — do NOT use**: `request._run_env` (doesn't exist; it's `_run_ns`); `request._run_ns.param_kw` (singular — it's `params_kw`); `request._params_kw` (may be empty at Jinja2 render time); `request.rel_url.query` / `request.query` (unnecessary — already parsed into `_run_ns.params_kw`).

### sqlExe: No Hardcoded ORDER BY / LIMIT / OFFSET

sqlor handles pagination via `sqlPaging()` — do NOT hardcode `ORDER BY`/`LIMIT`/`OFFSET` in SQL strings: `ns = {"page":1,"sort":"name","order":"desc","rows":20}; recs = await sor.sqlPaging("SELECT * FROM t", ns)` → returns `{"total": N, "rows": [...]}`.

### Pitfall: sqlExe returns DictObject — NOT dict-convertible

`dict(r)` fails: `ValueError: dictionary update sequence element #0 has length 1; 2 is required`. Access attributes directly: `rows = [{"id": r.id, "name": r.name} for r in recs]`.

### dspy Database Access: get_sor_context, NOT DBPools().sqlorContext

In .dspy use `async with get_sor_context(request._run_ns, "tenant") as sor:` — routes to the correct database per the app's `module_dbname` config (resolves to `pipeline` in pipeline-app, `sage` in Sage). Do NOT hardcode `DBPools().sqlorContext("pipeline")`.

## Bricks HBox Column Widths: cwidth vs width%

**`cwidth` in HBox is NOT proportional** — it sets fixed pixel width (`charsize × cwidth`, e.g. cwidth=3 ≈ 42px); differs from Tabular's DataRow where cwidth=10 is the default. For proportional HBox columns use `"width": "22%"` / `"width": "34%"` (with HBox `"width":"100%"`). WRONG: fixed `cwidth` columns that don't scale. Applies to any hand-built HBox/list row — only Tabular's DataRow handles cwidth proportionally.

## Git Initialization & First Push (new module)

- **Gitea "Push to create" is DISABLED** — create the empty repo on the Gitea web UI (git.opencomputing.cn) BEFORE pushing, else: `Gitea: Push to create is not enabled for users. fatal: Could not read from remote repository.`
- **Auto-generated README → rebase conflict**: Gitea's initial README.md vs your local commit → `CONFLICT (add/add)`. Fix: `git checkout --ours README.md && git add README.md && GIT_EDITOR="true" git rebase --continue && git push -u origin main`.
- **`git rebase --continue` opens nano and hangs** in non-interactive terminals — always prefix `GIT_EDITOR="true"`.
- Sequence: ① write .gitignore FIRST (template: `references/module-gitignore.md`); ② `git init && git add -A && GIT_EDITOR="true" git commit -m "feat: initial commit message"`; ③ `git remote add origin git@git.opencomputing.cn:yumoqing/{module}.git`; ④ `git pull origin main --rebase` (resolve README conflict as above); ⑤ `git push -u origin main`.

### CRITICAL: Never Fabricate Pricing or Config Data

Pricing data (元/次, 元/秒, 元/token, etc.) MUST come from official vendor sources only — guessing, estimating, or stale memorized values is a production incident ("生产事故"). If the official pricing page/docs are inaccessible (SPA, login required), tell the user honestly you cannot find it. Do NOT: estimate from similar-tier models, extrapolate from older versions, use memorized pricing that may be stale, or pull from earlier-session skill references (those were guesses too). How to get pricing: ask the user for screenshots/text from the official console/pricing page, or an accessible vendor URL. Applies to: SQL pricing values, YAML price_factors, unit_prices in pricing_program_timing, unit_price in P4 migration scripts — anywhere a wrong number has real billing consequences.

## Verification Steps

### CRITICAL: Self-Testing Before Commit — MANDATORY

User has zero tolerance for untested code. Before committing: ① deploy to a test environment (venv, deps, app on test port); ② exercise EVERY endpoint (curl/browser each .dspy API and .ui page); ③ watch `tail -f logs/*.log` during testing for import errors/AttributeErrors/500s; ④ cross-validate against working Sage code (`~/repos/sage/wwwroot/` real .dspy files). If you cannot set up a test environment, say so explicitly and do NOT commit. Pattern: write → self-deploy → self-test → fix → commit only when verified.

### CRITICAL: dspy Batch Audit Before Commit — MANDATORY PRE-COMMIT GATE

Run before EVERY commit touching .dspy; fix violations FIRST, then commit (do not commit-and-fix-later). Pre-loaded globals in dspy context (NO import needed): `json`, `datetime`, `time`, `os`, `debug/exception/error/info/warning/critical` (appPublic.log), `DBPools`, `get_sor_context`, `DictObject`, `get_user`, `params_kw`, `format_exc`, `password_encode`, `password_decode`, `curDateString`, `timestampstr`, `getID`, `functools.partial`, `ahserver.filestorage.FileStorage`, `RegisterFunction`, `DBFilter`, `ArgsConvert` (sqlor.filter), plus ALL ServerEnv-registered functions from every module's `load_*()`.
- **Module-internal imports MUST go through `load_*()`**: `from mymodule.utils import foo` in dspy is NOT allowed — export via `env.foo = foo` in `load_mymodule()`.
- Audit command (output MUST be empty): `grep -rn "^import\|^from" wwwroot/ --include='*.dspy' | grep -v "sqlor.filter"` — remaining imports must be removed (pre-loaded) or moved to load_*() export.
- Workflow: write/edit → audit → fix → re-audit (zero violations) → only then git add → commit. See `references/dspy-batch-fix-pattern.md`.
- 500/NoneType with a stack trace: **read the file named in the error FIRST** — do not chase tangential issues. Real case: 3× `currency_stats.dspy NoneType` "fixed" in init.py try/except, etl.py, SQL columns — all irrelevant; root cause was a JSON-format DSPY where a Python-script was expected.

### CRITICAL: Database Name Consistency Check

模块取库名不硬编码，统一从宿主应用获取。验证点：① 模块内（.py）用 `ServerEnv().get_module_dbname('模块名')`，.dspy 里直接 `get_module_dbname('模块名')`（全局，无需 import）——**不要**在模块里写 `DBNAME = "xxx"`；② 宿主应用 `app/{appname}.py` 定义 `get_module_dbname(m)` 返回模块 m 的真实库名，并在 init() 里挂到 ServerEnv（`env.get_module_dbname = get_module_dbname`，见 web-application-spec）；③ 应用入口的 `get_module_dbname()` 返回值必须匹配实际库名。Pitfalls: 模块硬编码 `DBNAME = "entcms"` 而实际库是 `"ocai_cms"` → 所有查询 table-not-found；应用 `get_module_dbname()` 返回 `'sage'` → dspy 查错库。

### Post-Deployment Testing (equally mandatory)

Login for a session cookie, then curl every affected endpoint expecting 200 (not 403/500); never say "可以测试了" without running these yourself:
```bash
curl -s -c /tmp/cookies.txt -X POST 'http://localhost:9180/rbac/user/login.ui' \
  -H 'Content-Type: application/x-www-form-urlencoded' -d 'username=test&password=test123'
for path in /module/page /module/api/endpoint.dspy /imgs/icon.svg; do
  code=$(curl -s -o /dev/null -w '%{http_code}' -b /tmp/cookies.txt "http://localhost:9180$path")
  echo "$code $path"   # must be 200
done
```
Pre-commit pattern checks: `async with db.sqlorContext(dbname) as sor:` (NOT `sor = DBPools().sqlorContext(dbname)`); no imports in dspy except `from sqlor.filter import DBFilter`; `return` not `print(json.dumps(...))`; `getID()` not `uuid()`; `await get_user()` not `get_user()`; Python module DBNAME constants match config.json; `get_module_dbname()` return value matches the app's actual database.

### Final Deployment Checklist

- [ ] Module loads via load_{modulename}(); imported in `app/sage.py`; in build.sh install loop
- [ ] RBAC permissions in load_path.py and loaded via `python load_path.py`; menu item in global_menu.ui (NOT inside {% if %} conditionals)
- [ ] wwwroot symlinked to `sage/wwwroot/{modulename}/`; all exposed functions work in frontend scripts
- [ ] DB ops follow sqlor; JSON configs have `editable` with top-level new/update/delete_data_url; same-module `entire_url()` refs use `../`
- [ ] Init data loads; pyproject.toml builds; skill/SKILL.md complete with references/assets/scripts organized

## References / Scripts Index

- `references/bricks-ui-pitfalls.md` — id placement (widget level), Button click, Popup/Form, script actiontype Jinja2 limits
- `references/dspy-execution-and-module-structure.md` — dspy execution model, pre-loaded globals, Tree widget data format, module symlink patterns
- `references/json-config-pattern.md` — full CRUD JSON config template
- `references/crud-json-toolbar-bind-pattern.md` — custom toolbar buttons + PopupWindow bind pattern
- `references/web-app-and-dspy-spec.md` — debug output best practices (debug_params), injecting new functions into .dspy execution env via self.y_env
- `references/read-only-module-pattern.md` — read-only/dashboard module template
- `references/custom-create-dspy-required-fields.md` — custom create dspy with auto-generated business codes
- `references/model-change-rebuild-pitfalls.md` — .xlsx/.json load order, get_code.dspy module.table resolution failure, collation mismatch
- `references/bulk-module-creation-pattern.md` — ordered creation sequence, bulk .dspy generation script, init.py templates, cascade delete, subagent validation checklist
- `references/independent-web-app-pattern.md` — standalone ahserver web apps (own venv/port/config.json)
- `references/rbac-init-pattern.md` — bootstrapping org types/roles/users/role-permissions for independent apps
- `references/test-env-module-deployment.md` — deploying modules from ~/test into Sage test env (pip install, symlink, RBAC, restart, git push)
- `references/public-endpoint-cron-pattern.md` — dspy endpoints without auth for cron/background jobs
- `references/hub-dashboard-pattern.md` — hub entry page (stat cards + nav buttons + urlwidget content area)
- `references/registry-table-pattern.md` — registry/mapping table + dynamic table routing
- `references/llmage-openai-endpoint-pattern.md` — OpenAI-compatible endpoints on llmage (/v1/chat/completions, /v1/video/generations, /v1/image/generations)
- `references/llmage-data-model.md` — llmage key tables, JOIN patterns, apiname in llm_api_map NOT llm, subquery alias scoping
- `references/api-integration-pattern.md` — uapi/llmage 4-table API integration (no code changes)
- `references/tencent-hunyuan-api.md` — Tencent Hunyuan model specs, pricing, Sage integration
- `references/external-api-integration-module-pattern.md` — third-party API integration modules
- `harnessed-module-development` skill → `references/vendor-callback-pattern.md` — vendor webhook/callback endpoints
- `references/rbac-tables.md` — RBAC table chain (organization→role→userrole→rolepermission→permission) + init order
- `references/volcengine-ark-api.md` — Ark real-person portrait asset API: AK/SK signing, asset group/workflow, hybrid module (own client + uapi)
- `references/downapp-proxy-api-pattern.md` — vendor proxy API: centralized vendor config table, org→resource mapping, ownership validation, multi-vendor factory
- `references/configurable-rule-engine-pattern.md` — registry-based dynamic rule engine (discounts/permissions/workflows)
- `references/platform-cross-org-table-pattern.md` — cross-org (platform-level) tables without resellerid isolation, unified supplier mapping, menu grouping with separators
- `references/cache-control-pattern.md` — config.json `module_cache` toggle for per-module in-memory caching
- `references/sage-deployment-pitfalls.md` — site-packages sync, DSPY async limitations, CRUD before_insert hooks, browser testing requirement
- `references/pipeline-app-deployment-pitfalls.md` — umbrella repo recovery, bricks dist build, dspy return-outside-async-with, RBAC static file permissions
- `references/feature-enablement-three-layer-pattern.md` — unlocking features gated behind hardcoded UI/dspy/backend limits
- `references/cross-database-query-pattern.md` — cross-db JOIN with fully-qualified names (e.g. `product_management.product` from `discount` db)
- `references/social-platform-pattern.md` — content/social module: counters (R+U), toggle likes, nested comments (parent_id+reply_count), view counting, paid downloads, media classification, paginated feeds
- `references/ai-compute-service-pattern.md` — GPU services (4090 → ahserver HTTP API + nginx IP whitelist → llmage+uapi → Hermes skill)
- `references/dspy-error-handling.md` — IntegrityError handling, UPSERT, form `id` management in .dspy
- `references/dspy-nonetype-defense.md` — mandatory try/except wrappers on all DSPY-called functions
- `references/dspy-pitfalls.md` — return format, sqlor API signatures, param cleaning, return-inside-async-with, dbname naming, $placeholder escaping
- `references/module-extraction-pattern.md` — extracting embedded modules from umbrella repos via `git subtree split`
- `references/bricks-dist-build.md` — mandatory bricks `dist/` build + symlink after fresh clone/restore
- `references/crud-list-query-optimization-pattern.md` — exclude TEXT/LONGTEXT from SELECT, composite indexes on (filter_field, sort_field)
- `references/sage-config-and-db-export.md` — non-standard config.json (bare objects), RC4 password decryption, table discovery from models/*.json, mysqldump export
- `references/i18n-merge-pattern.md` — consolidating translations into `wwwroot/i18n/` via `scripts/merge_i18n.py` (uses build.sh module list, ~/repos paths)
- `references/popup-form-refresh-pattern.md` — refresh parent content after Popup Form submit (target: app.sage_main_content)
- `references/bricks-tabular-code-field-pattern.md` — Tabular code fields: static `data` vs dynamic `dataurl`+`valueField`/`textField`, undefined.length errors
- `references/feature-page-addition-checklist.md` — 7-step new feature page workflow (dspy → ui → menu → RBAC → CSS → commit per repo → deploy)
- `references/supplychain-attachment-pattern.md` — filemgr attachments + drag-drop Form upload (Form submit_url + UiFile multiple)
- `references/marketing-discount-setting.md` — product discount override with base-comparison validation and flag pattern
- `references/toolbar-ensure-pattern.md` — one-click toolbar check-or-create (`actiontype: "dspy"` + params_mapping) to ensure a related record exists
- `references/subtable-fk-auto-populate.md` — auto-populating FKs in subtable add forms (editexclouded + new_data_url query params)
- `references/database-migration-pattern.md` — full schema migration workflow
- `references/intermediate-table-removal-pattern.md` — junction table removal with SQL examples
- `references/uapi-uapiset-removal-detail.md` — concrete session example (uapiset removal from uapi module)
- `references/per-module-rbac-pattern.md` — per-module load_path.py script template
- `references/per-module-load-path-pattern.md` — per-module template with role-tier separation
- `references/module-gitignore.md` — .gitignore template for module repos
- `references/dspy-batch-fix-pattern.md` — systematic dspy audit-fix approach
- `references/umbrella-repo-module-extraction.md` — extracting embedded modules with preserved git history
- `references/app-level-wwwroot-pattern.md` — unified app-level wwwroot (frontend files centralized; modules keep Python code, move static files)
- `scripts/dspy_audit.sh` — pre-commit dspy audit (run before any commit touching .dspy)
- `scripts/module_compliance_audit.py` — batch compliance audit (init/data.json format, load_path.py existence, model codes parentid compliance) across module repos