docs: 同步批次 14/15 收尾(HANDOFF + memory)

This commit is contained in:
admin committed 2026-11-02 10:04:46 +08:00
1 parent c82a7d1f3d
commit 454caa5e29
2 files changed
+145 -7

No files matched your search

+43
View File
@@ -64,3 +64,46 @@
- `fe-gap`:**345/900(38.3%)**;`system` 141 → **155**(79.1%),
`systemData` 仍 74/106 —— 因为 fe-gap 按**路径前缀**归类,这两族路径是 `/api/system/*`。
- `verify.sh` 全量 **全 ✅ 113.7s**。
## 批次 15 收尾(2026-11-02):系统服务 39 条 + 修掉清单生成器根因
### 做了什么
- 39 条面 B 端点:`BaseLang`(7) / `Kit`(8) / `CacheManage`(4) / `scheduletask`(7) /
`imreply`(3) / `MenuData`(3) / `Variate`(3) / `Monitor`(1) / `HomeData/mySystem`(1) /
三处 `Actions/Export`(3)。`schema.sql` 57 → **65**,`BASE_TABLES` 54 → **62**。
- 新增 `platform/monitor.rs`(真实宿主机指标)与 `platform/variate_catalog.rs`(生成物)。
- 新增 `tests/batch15_it.rs` 12 条(11 绿 → 补第二用户后 12 绿)。
### 三条定调(会反复用到)
1. **能力不存在 ⇒ 明确业务失败**,不假装成功:三处 `Export`、`DataSync`、`BaseLang` 模板/导入。
尤其 `Kit/{id}/Actions/Export` **不能返 `data:null`**(官方前端直接 `res.data.url` ⇒ JS 异常)。
2. **本仓没有 Redis ≠ 不实现 CacheManage**:缓存对象 = 内存会话表,
`DELETE` **真的踢下线**、`ClearAll` **保留操作者自己**、**不把 token 放进响应**、
`overdueTime` 恒 null(会话不过期,编时间是撒谎)。
3. **调度只登记不执行**:`runCount`/`lastRunTime`/`nextRunTime` 不编;`TaskMethods` 返 `{list:[]}`(200,
返错会让新建表单整体红条)。
### 修掉尺子的两个真 bug(不是业务代码)
🔴 **`fe-api-inventory.py` 解析嵌套模板串会截断** ⇒ 产出 `…/${encryption`、`…${interfaceId` 这类
**畸形路径**,在缺口报表里变成永远修不完的假缺口(`system` 最后那 2 条就是它)。
两处根因:① 找结束反引号时被**内层反引号**截断(`${a ? `?x=${b}` : ''}`);
② 用 `\$\{[^}]*\}` 替换时停在**内层 `}`** 上。改成**深度配对**(`find_template_end`),
并把「拼查询串的三元片段」整段丢掉(判据:片段内字符串字面量以 `?` 开头)。
修完 `system` 缺口 **41 → 0(196/196)**,连带修掉 `ShortLink` 5 条畸形行,清单零附带漂移。
🔴 **另一批 3 条 `systemData` 缺口是「死声明」**:`Dataset/Selector`、`DatasetLog/{id}`、
`InterfaceOauth/saveInterfaceList` —— 官方前端 `api/**/*.ts` 声明了,但**全仓 Java 没有任何
`@*Mapping` 能拼出该路径**、官方前端**也没有调用点**。已记进契约 `[OFFICIAL]` 的 `oos`
(带判据),**不是待办**。下次看到 fe-gap 报这 3 条别再重查。
### 数字
- 契约端点 **461**(A 28 + B 431 + 共用 2);`check-contract` `PASS=10 FAIL=0`,
官方覆盖 **447/454**(impl 398 / partial 49 / absent 7;oos 9)。
- `cargo test --workspace` = **610 passed / 0 failed**(40 个二进制)。
- `fe-gap`:**415/900(46.1%)**;`system` **196/196(100%)**、`systemData` 103/106、
`permission` 111/137(下一个批次 16 就是它,26 条)。
- `verify.sh` 全量 **全 ✅ 142.7s**。
### 契约坑(新)
🔴 **手写端点行末尾别留空行**:`pack-sync.py` 会把它当格式漂移,`--check` 直接红。
本批第一版插完多了一个空行 ⇒ `pack-sync --check` 红(幸好它在 verify 第一步)。
+102 -7
View File
@@ -351,16 +351,22 @@ React 模板的加模块成本 = **改/加 8 个文件、15~20 分钟**(`HOWTO
---
## 1. 一句话现状(2026-11-02 批次 13 收尾)
## 1. 一句话现状(2026-11-02 批次 15 收尾)
**📌 当前数字(以此为准,下面各批的「当时数字」仅存档)**:
- 契约端点 **393 条**(面 A 28 + 面 B **363** + 两面共用 2);`tables` → **53**。
- `cargo test --offline --workspace` = **588 passed / 0 failed**(47 个测试二进制)。
- 十二道闸门全绿;`check-contract` `PASS=10 FAIL=0`,官方端点覆盖 **379/386**
(implemented 352 / partial 27 / absent 7;oos 6 单列)。
- `python3 scripts/fe-gap.py`:合计 **345 / 900(38.3%)**,`permission` 111/137(81.0%)、
`system` 155/196(79.1%)、**`systemData` 74/106(69.8%)**。
- 契约端点 **461 条**(面 A 28 + 面 B **431** + 两面共用 2);`tables` → **65**
(`BASE_TABLES` 62:有 3 张表只在 `schema.sql` 里、不进自检清单)。
- `cargo test --offline --workspace` = **610 passed / 0 failed**(40 个测试二进制)。
- 十二道闸门全绿;`check-contract` `PASS=10 FAIL=0`,官方端点覆盖 **447/454**
(implemented 398 / partial 49 / absent 7;oos 9 单列)。
- `python3 scripts/fe-gap.py`:合计 **415 / 900(46.1%)**,`permission` 111/137(81.0%)、
**`system` 196/196(100%)**、**`systemData` 103/106(97.2%)**。
🔴 **`system` 已经清零**:本轮之前最后 2 条是**扫描器自己**造的畸形路径
(官方前端的嵌套模板串被截断),修的是尺子不是代码 —— 见 §1「批次 15」末段。
🔴 **`systemData` 剩下的 3 条是「死声明」**:官方前端 `api/**/*.ts` 里声明了,
但官方后端**从来没有**对应映射、官方前端也**没有任何调用点** ⇒ 已记进契约
`[OFFICIAL]` 的 `oos`(带判据),**不是待办**。
(批次 9 收尾时此处写的 252/28.0% 是**批次 8 的旧数**,批次 9 实测 291/32.3%,此处已更正。)
🔴 **批次 13 的 14 条端点算进了 `system` 而不是 `systemData`**:`fe-gap.py` 按**路径前缀**归类,
而这两族的路径是 `/api/system/Area|Variate`(页面在 `sysData/area|variate`、点权限码是 `sysData.*`)。
@@ -381,6 +387,11 @@ React 模板的加模块成本 = **改/加 8 个文件、15~20 分钟**(`HOWTO
—— 见 §1「批次 11」小节。
- 🔴 **系统数据两族落地了**(批次 13):行政区划(树 + 懒加载标志 + 子树排除)与
公有变量(分页 + type 是字符串 + 11 个函数分类)共 14 条端点 —— 见 §1「批次 13」小节。
- 🔴 **数据中心五族 + 系统服务一族落地了**(批次 14/15,共 68 条端点):
基准类型/控件映射/数据库/字段类型映射/常用字段、多语言/表单套件/缓存管理/任务调度/
IM 会话/收藏菜单/公式目录/系统监控。**其中四条「能力不存在」的按明确业务失败处理**
(`DataSync`×4、三处 `Export`、`BaseLang` 模板与导入),**没有一条是假数据**。
见 §1「批次 14」「批次 15」两小节。
- ✅ **「业务包」已经接上了**(批次 12 治好;下面括号里是**历史口径**,别再按它排期):
(旧)`packs/asset` 能独立编译,但内核没装载它 —— `routes.rs` 只 merge `modules::router()`,
且 `sspf-sdk` 的 `BusinessPack` 没有 `routes()`,spec 在 `modules/asset.rs` 与
@@ -847,6 +858,90 @@ React 模板的加模块成本 = **改/加 8 个文件、15~20 分钟**(`HOWTO
变量 `type` 是字符串 + `creatorUser` 真填上、列表 type+keyword+分页、
变量名判重 + **局部更新只 SET 出现的键**、selector 大小写不敏感 + 11 个函数分类、未登录 602。
### 批次 14(2026-11-02)—— 数据中心五族(基准类型 / 控件映射 / 数据库 / 字段类型映射 / 常用字段)
**29 条面 B 端点**:`BasicDataType`(4) + `DataTypeMapping`(5) + `DataBase`(5) +
`DataTypeRelation`(5) + `CommonFields`(4) + `DataSync`(4) + `DataInterfaceVariate/Selector`(1)。
新表 4 张(官方 DDL 逐字):`base_data_type_mapping` / `base_data_base` /
`base_data_type_relation` / `base_data_interface_variate`,`tables` 53 → **57**;
`BASE_TABLES` 50 → **54**。
🔴 **五族形状一致 ⇒ 抽声明式 `Flat`**(一份声明 + 五个薄壳),别逐族手抄 ——
手抄五份的下场是「改了一处漏四处」,而这几族的判重/白名单/更新语义**本来就一样**。
🔴 **判重是「每列各自唯一」,不是「联合唯一」**:官方 `enCode` / `dbType` 各自
`existByXxx` 单独查 ⇒ 抄成 `WHERE a = $1 AND b = $2` 会**放过多组重复**。
🔴 **列表把 `typeId` 覆盖成名称,详情必须返真 id**(批次 14 的控件映射、批次 15 的
`Kit` 是同一个坑,第三次遇到了):前端列表要显示人话、编辑表单的 `Select` 绑的是 id
⇒ 两条 SQL **故意不同**,别为了「一致」把列表也改成 id(页面会显示 uuid)。
🔴 **`DataSync` 四条一律明确业务失败**:官方走 JDBC 真连两个库,本仓是进程内嵌 PG
(pglite/WASM,无驱动层)⇒ **能力不存在就不假装成功**(同 `DataSource/Actions/Test`)。
- 回归测试 `tests/batch14_it.rs`(**7 条**)。
- 🔴 **顺手修掉扫描器两个同源缺陷**:`check-contract-scan` 与 `fe-gap` 都只认每条
`.route()` 的**第一个**方法 ⇒ 链式 `get(a).post(b)` 的后半段**静默消失**
(契约写 implemented、代码却被判「没有这条路由」)。现在按 `.route(` 切块取全部方法。
### 批次 15(2026-11-02)—— 系统服务(多语言 / 套件 / 缓存 / 调度 / IM / 常用 / 监控)
**39 条面 B 端点**:`BaseLang`(7) + `Kit`(8) + `CacheManage`(4) + `scheduletask`(7) +
`imreply`(3) + `MenuData`(3) + `Variate`(3) + `Monitor`(1) + `HomeData/mySystem`(1) +
三处 `Actions/Export`(3)。
新表 8 张(官方 DDL 逐字):`base_language` / `base_visual_kit` / `base_time_task` +
`base_time_task_log` / `base_im_reply` + `base_im_content` / `base_module_data` +
`base_module_use_num`,`tables` 57 → **65**;`BASE_TABLES` 54 → **62**。
🔴 **多语言是「一行 = 一个语种」,靠 `f_group_id` 聚组**(不是一行存一个 JSON):
列表按组出一行、`id` 是 **groupId**;`f_en_code` 上**没有唯一约束**(同组必然重复)⇒
判重必须跨组做。`PUT` 时 `map` 里**没有的语种要删掉**(官方 `BaseLangMapper.update`
逐字语义,不是「只加不删」)。
🔴 **`tableHead` 的真源是字典 `Language`**:缺了它列表只剩「翻译标记」一列 ⇒
`seed.rs::ensure_language_dict` 按官方初始库种子化(type id / 两个语种 id 逐字)。
🔴 **`CacheManage` 是本批最需要定调的一条**:官方面对 Redis 键空间,本仓没有 Redis,
但有**真实的内存会话表**。⇒ **不拒绝、也不假装**:`name = lite:session:<账号>`、
`overdueTime = null`(会话不过期,**编时间是撒谎**)、`cacheSize` 是真实字节数;
`DELETE` **真的把人踢下线**(后续请求 `code=602`);`ClearAll` **保留操作者自己**
(对齐官方「跳过 token 前缀那几个键」)。🔴 **绝不把 token 本身放进响应**。
🔴 **`scheduletask` 只登记不执行**(官方全部转发 XXL-JOB,本仓没有调度器):
CRUD 落 `base_time_task`(数据真实、可编辑、重启不丢),`runCount` 恒 0、
`lastRunTime`/`nextRunTime` 恒 null —— **不编执行痕迹**;`startTime`/`endTime` 要
从 `f_execute_content` 的 JSON 里**提到顶层**(否则前端那两列永远空);
`TaskMethods` 返 `{list:[]}`(**200**,返错会让新建表单整体红条)。
🔴 **三处 `Actions/Export` 一律明确 `fail`**(本仓无文件服务)。`Kit` 那条尤其
**不能返 `data:null`**:官方前端 `templateCenter/kit/index.vue:130-131` 是
`downloadByUrl({url: res.data.url})` ⇒ null 抛 JS 异常(比红条更难查)。
🔴 **Monitor 必须采真实指标**:官方 `MonitorUtil` 为算 CPU 占空比**在主线程 sleep 1 秒**,
本仓不这么干(监控页每 2 秒轮询):Linux 用 `/proc/stat` **两次采样差分**、macOS 用
`getloadavg()[0] / 逻辑核数`(**近似**,精确占空比要 mach port 并负责
`mach_port_deallocate`,不划算)⇒ 契约标 `partial`。内存/磁盘/型号/核数全是真读。
- 🔴 **公式目录用生成物** `variate_catalog.rs`(35 函数 / 18 变量 / 11 分类,
`scripts/gen-function-catalog.py` 生成):`variate_sys_func_category` 原来手抄的
11 个分类常量已换成同一份生成物,**消除第二份真源**。
- 🔴 **`sysfunc` 的 `ALL` 本仓返全量**(官方返空)—— 有意偏差,契约标 `partial`;
官方 `type` 路径参数其实**不生效**(真正生效的是 `?category=`)⇒ 本仓两个都认。
- 🔴 **axum 同一个 path 只能 `.route()` 一次** ⇒ 「列表 GET + 新建 POST」必须写成
`get(a).post(b)`;静态段(`Kit/Selector`、`MenuData/useModuleNum/{id}`)在 matchit 里
优先于 `{id}`,可共存。
- 🔴 **测试夹具坑**:种子库只有 `admin` 一个用户,而 `imreply` 列表要 `JOIN base_user`
⇒ 测试必须自己插一个**启用未删除**的对方(固定 id + `ON CONFLICT DO NOTHING`,
因为全文件共用一个临时库)。
- 回归测试 `tests/batch15_it.rs`(**12 条**)。
🔴 **顺手修掉清单生成器的根因(`fe-api-inventory.py`)**:官方前端有
`` `${Prefix}/getConfig/${id}${enc ? `?e=${enc}` : ''}` `` 这种**套两层模板**的写法,
旧解析器 ① 找结束反引号时被**内层反引号**截断、② 用 `\$\{[^}]*\}` 替换时停在内层 `}` 上
⇒ 产出 `…/${encryption` 这种**畸形路径**,在缺口报表里变成永远修不完的假缺口
(`system` 那 2 条就是这么来的)。现在改成**深度配对**,并把「拼查询串的三元片段」整段丢掉
(它不是路径段)。修完 `system` 缺口 **41 → 0**(196/196),连带修掉 `ShortLink` 5 条畸形行。
### 🔴 批次 11 踩到并解决的 5 个真 bug(跨批次,顺手修掉的)
1. 🔴 **`b10_insert` 把 `None` 当 `now()` 绑定** ⇒ 整型列直接类型错