docs: en wiki — self-driven follow-ups (live findings + dead-source flags)

Live findings from BACK + FROUNT browser session: - /business/addSysLocking: undocumented optimistic-lock endpoint (POST, called when entering edit mode; handler at BusinessBaseController.java:400-407). Added to internal.md universal-CRUD table. - BACK admin sidebar fully enumerated (10 modules) and mapped to backing form-master sTbName + owning service. 8/10 are framework primitives covered elsewhere; 常用操作配置 has no gdsconfigformmaster row in this dev DB (SPA-side admin special-case); 图表配置 is gdsconfigcharmaster/slave (added to the gds prefix entry in modules-forms-vtables.md). - FROUNT login confirmed; this dev DB exposes only 4 sidebar modules (2 are AI/LLM out-of-scope). Production tenants would carry the full business-module catalog. - Slice 1 save endpoint live-corroborated: clicking 新增 → 保存 fired POST /xlyEntry/business/addUpdateDelBusinessData?sModelsId=13 → 200 OK. (Audit-tag mutation didn't actually land because the Vue model didn't pick up our scripted input change — endpoint flowed but with original row state.) Updated slice-01 open- verification item with the partial verification. Dead-source flag (sql-templates.md): - Two `FileSqlUtil` classes coexist. xlyFlow's loader points at the 8 templates that exist on disk. xlyApi's loader names 7 templates (sInSqlStrTemple, sOutSqlStrTemple, sDataSqlTmp[Def], sJsonSqlTmp[Out], sDbPro) — NONE of them exist as files. Documented as broken-by-default; either restore templates or remove the loader. Auto-catalog regen verified accurate (gdsmodule.md columns match live DB).

docs: en wiki — self-driven follow-ups (live findings + dead-source flags)
Live findings from BACK + FROUNT browser session: - /business/addSysLocking: undocumented optimistic-lock endpoint (POST, called when entering edit mode; handler at BusinessBaseController.java:400-407). Added to internal.md universal-CRUD table. - BACK admin sidebar fully enumerated (10 modules) and mapped to backing form-master sTbName + owning service. 8/10 are framework primitives covered elsewhere; 常用操作配置 has no gdsconfigformmaster row in this dev DB (SPA-side admin special-case); 图表配置 is gdsconfigcharmaster/slave (added to the gds prefix entry in modules-forms-vtables.md). - FROUNT login confirmed; this dev DB exposes only 4 sidebar modules (2 are AI/LLM out-of-scope). Production tenants would carry the full business-module catalog. - Slice 1 save endpoint live-corroborated: clicking 新增 → 保存 fired POST /xlyEntry/business/addUpdateDelBusinessData?sModelsId=13 → 200 OK. (Audit-tag mutation didn't actually land because the Vue model didn't pick up our scripted input change — endpoint flowed but with original row state.) Updated slice-01 open- verification item with the partial verification. Dead-source flag (sql-templates.md): - Two `FileSqlUtil` classes coexist. xlyFlow's loader points at the 8 templates that exist on disk. xlyApi's loader names 7 templates (sInSqlStrTemple, sOutSqlStrTemple, sDataSqlTmp[Def], sJsonSqlTmp[Out], sDbPro) — NONE of them exist as files. Documented as broken-by-default; either restore templates or remove the loader. Auto-catalog regen verified accurate (gdsmodule.md columns match live DB).
zichun
1 parent 4ea83bcc
Showing 4 changed files with 56 additions and 6 deletions
en/docs/api-reference/internal.md
en/docs/concepts/modules-forms-vtables.md
en/docs/reference/maintainer/sql-templates.md
en/docs/slices/01-hello-world.md
@@ -25,6 +25,7 @@ page is the catalog of HTTP entry points.
 | `/business/addUpdateDelBusinessData` | POST | Bundled add+update+delete in one transactional call. The frontend names the target table directly via `sTable`. |
 | `/business/getSelectDataBysControlId/{sId}` | POST | Dropdown population for a single control, by control `sId`. |
 | `/business/getSelectLimit/{sId}` | POST | Paginated variant of the dropdown call. |
+| `/business/addSysLocking` | POST | Optimistic-lock acquisition when a user starts editing a document — inserts a row in the system lock table keyed by `(sFormGuid, sUserId)`. The SPA fires this when entering edit mode so concurrent editors get a conflict warning. Handler: `BusinessBaseController.java:400-407`. |
  
 These endpoints are documented in detail by [Slice 1](../slices/01-hello-world.md)
 (`getModelBysId` + grid load + save) and
@@ -82,6 +83,35 @@ get past `@Authorization`; if it does (e.g., an unannotated method),
 that method also bypasses the universal tenant injection in
 `RequestAddParamUtil` — and is therefore a multi-tenant bug.
  
+## BACK builder sidebar (admin surface)
+
+The 10 top-level items in the BACK admin sidebar (login `admin`/`123`,
+edition `基础版/8s`) — each is a metadata-driven screen wired through
+the framework primitives above:
+
+| Sidebar | URL fragment | Backing form-master `sTbName` | Owning service |
+|---|---|---|---|
+| 系统模块配置 (System Module Config) | `/xtmkpz` | `gdsmodule` | `GdsmoduleServiceImpl` |
+| 数据表内容配置 (Virtual Table Config) | n/a | `gdsconfigtbmaster`/`slave` | `GdsconfigtbServiceImpl` |
+| 界面显示内容配置 (Form Definition + Customization) | n/a | `gdsconfigformmaster`/`slave`/`customslave`/`personalize` | `GdsconfigformServiceImpl` |
+| 接口自定义配置 (API Definition) | `/sjbnrpz` | `sysapi` family | (xlyApi-side admin) |
+| 系统常量配置 (System Constants) | `/xtclpz` | `gdsformconst` | `GdsformconstServiceImpl` — Slice 1 anchor |
+| 系统权限配置 (Permission Catalog) | n/a | `gdsjurisdiction` | `GdsjurisdictionServiceImpl` |
+| 常用操作配置 (Common Operations / Button Groups) | n/a | (no entry in `gdsconfigformmaster` for this dev DB; the page is rendered as an admin special-case wired directly in the SPA — when extended via metadata, the data lives under the user-defined button-group tier) | n/a |
+| 用户信息配置 (User Info) | n/a | `sftlogininfo` family | `GdslogininfoServiceImpl` |
+| Mysql脚本配置 (SQL Script Authoring) | n/a | (BACK editor over the [`templesql/` scaffolds](../reference/maintainer/sql-templates.md)) | `SqlScriptsServiceImpl` |
+| 图表配置 (Chart Config) | (no `gdsroute` entry; navigated via SPA state) | `gdsconfigcharmaster`/`slave` | `GdsconfigformServiceImpl` (chart subset) |
+
+8 of 10 are framework primitives covered elsewhere in this catalog +
+the [Maintainer Reference](../reference/maintainer/management-services.md).
+**`常用操作配置` is a SPA-side admin special-case** — it appears in the
+sidebar without a corresponding `gdsconfigformmaster` row in the dev
+DB, suggesting the page is hardcoded in BACK rather than metadata-
+driven. **`图表配置`** is fully metadata-driven via two
+`gdsconfigformmaster` rows pointing at `gdsconfigcharmaster` and
+`gdsconfigcharslave`; chart definitions there are consumed by xly's
+dashboard rendering elsewhere in the SPA.
+
 ## Coverage policy — what this catalog includes
  
 `xlyEntry` hosts **~71 controllers** in total. This page enumerates
@@ -100,7 +100,7 @@ any business-data table to its domain by the three-letter prefix:
  
 | Prefix | Domain | Sample tables (live count) |
 |---|---|---|
-| `gds` | Framework metadata (modules, forms, fields, permissions, parameters) | `gdsmodule`, `gdsconfigformmaster`, `gdsconfigformslave`, `gdsjurisdiction`, `gdsroute`, `gdsformconst`, `gdsparameter`, … |
+| `gds` | Framework metadata (modules, forms, fields, permissions, parameters, charts) | `gdsmodule`, `gdsconfigformmaster`, `gdsconfigformslave`, `gdsjurisdiction`, `gdsroute`, `gdsformconst`, `gdsparameter`, `gdsconfigcharmaster`/`slave` (chart definitions used by the BACK 图表配置 screen), … |
 | `sys` | Framework system (numbering, jurisdiction grants, reports, search, billing settings) — distinct from `gds*` "definition" tier | `sysjurisdiction`, `sysbillnosettings`, `sysreport`, `syssearch`, `sysapi`, `SysSystemSettings`, … (66 tables) |
 | `sis` | Shared lookup tables / classifiers backing dropdowns | `sisbank`, `siscolor`, `sisversionflow`, `sisjurisdictionclassify`, … (78 tables) |
 | `sft` | Login-session / group-permission link tables | `sftlogininfo*`, `sftlogininfojurisdictiongroup`, … (8 tables) |
@@ -76,6 +76,20 @@ A proc that *doesn&#39;t* follow these conventions cannot be invoked
 through generic dispatch and would have to be called from custom Java
 code instead.
  
+## Two loaders
+
+There are **two** classes named `FileSqlUtil` in the codebase, with
+very different reliability:
+
+| Loader | What it points at | State |
+|---|---|---|
+| `xlyFlow/src/main/java/com/xly/sqltemplate/util/FileSqlUtil.java` | The 8 scaffolds above | **All 8 files exist** — this is the loader BACK's script-authoring screen actually uses. |
+| `xlyApi/src/main/java/com/xly/api/util/FileSqlUtil.java` | 7 different template constants: `sInSqlStrTemple.sql`, `sOutSqlStrTemple.sql`, `sDataSqlTmpDef.sql`, `sDataSqlTmp.sql`, `sJsonSqlTmp.sql`, `sDbPro.sql`, `sJsonSqlTmpOut.sql` | **None of these files exist** in the live tree. The constants are dead source — likely from an older xlyApi codepath that no longer ships templates. Calls through them will throw `FileNotFoundException` at runtime. |
+
+A maintainer touching the `xlyApi` `FileSqlUtil` should treat it as
+broken-by-default and either restore the missing templates or remove
+the loader.
+
 ## See also
  
 - [Generic procedure dispatch](proc-dispatch.md) — how the framework
@@ -275,11 +275,17 @@ Read flow live-corroborated; save flow still pending.
    `/xtmkpz` rather than navigating to `/xtclpz` — confirming that URL
    fragments are display state, not route drivers (the SPA loads the
    form on demand from the sidebar click).
-2. **A live captured save.** The endpoint, handler, and payload shape are
-   confirmed from source; the *body of an actual save request* hasn't been
-   captured. This requires writing to the dev DB and we deferred it. Closing
-   this means: open the module, click 新增, fill the form, click 保存, capture
-   the JSON body and the response.
+2. **A live captured save (partial).** Endpoint + URL + method
+   live-corroborated: clicking 新增 → 保存 in BACK's 系统常量配置 fired
+   `POST /xlyEntry/business/addUpdateDelBusinessData?sModelsId=13` →
+   200 OK. (No DB mutation in our test because the audit-tag value
+   change didn't propagate through the SPA's Vue model — the save
+   ran on the original row state.) The exact request **body** the
+   SPA sends is the next thing to capture; for now the documented
+   shape rests on `BusinessBaseController.java:161-163` Javadoc.
+   The SPA also fires `POST /business/addSysLocking` when entering
+   edit mode (optimistic-lock) — see
+   [internal API](../api-reference/internal.md#the-universal-crud-surface-business).
 3. **The exact SQL emitted by save/delete**, captured from `syslog4j` or a
    MyBatis debug log, to close the loop end-to-end.
 3. ~~**`sTable` validation in `addUpdateDelBusinessData`.**~~ **CLOSED** —