feat(onlineDev): 补齐 onlineDev 78 条 + 在线报表 23 条端点并同步契约三处

契约面(面 B):从 487 涨到 588 条,官方端点覆盖 474/580 -> 574/580。

实现
- platform/compat/online_dev.rs:表单设计 / 门户 / 短链 / 在线数据 / 个人化 /
  日志 / 分享 / OCR / 行政区划 / 仪表盘 共 78 条
- platform/compat/report.rs:在线报表 23 条(模板 / 版本 / 菜单)
- 报表元数据就地落库(report_template + report_version,官方 DDL 逐字导入):
  官方 /api/Report/* 属独立部署的第三方报表服务,主后端无对应 Controller

契约与尺子
- 新增 scripts/gen-contract-endpoints.py:从代码真实路由自动生成 [ENDPOINT] 与
  [OFFICIAL] 两段(守卫复用扫描器同一套推导,幂等、不覆盖已登记条目)
- check-contract-scan.py 修复守卫推导:三段路径解析、compat 文件纳入 plat_files、
  跨文件常量回落、「无守卫」判据(原先 compat 模块守卫全部推不出,CC6 静默失效)
- docs/contract.md 三处同步:+101 条端点、+101 条官方台账、面 B 计数 457 -> 558

修复的真 bug(集成测试抓到,静态闸门看不出来)
- 3 处 SQL 引用官方 DDL 里不存在的列:base_visual_release.f_platform_release、
  base_system.f_app_key/f_app_name、base_notice.f_full_name(官方是 f_title)
- 3 处官方契约形状偏差:getReleaseMenu 返裸对象(非 ListVO)、
  systemFilter 按官方 SystemListVO 投影(且官方忽略 category 入参)、
  Dashboard/Notice 返 ListVO 且入参 typeList 是数组
- visual_dev_list 计数 SQL 参数个数与 $N 不匹配;visual_dev_update 漏写
  f_last_modify_user_id;report_save_version 模板 id 兼容 id 且返 data:null

测试
- 新增 tests/batch17_it.rs:11 个集成测试(含 101 条端点逐条打一遍防 matchit
  参数名冲突)

数字:check-contract PASS=10 FAIL=0;cargo test --workspace 全绿 0 failed;
fe-gap 541/900(onlineDev 100/101、permission 137/137、system 196/196)
This commit is contained in:
admin committed 2026-11-02 16:01:24 +08:00
1 parent 1a41aed3b7
commit cf154d50ff
13 files changed
+6495 -52

No files matched your search

+170 -23
View File
@@ -351,17 +351,37 @@ React 模板的加模块成本 = **改/加 8 个文件、15~20 分钟**(`HOWTO
---
## 1. 一句话现状(2026-11-02 批次 16 收尾)
## 1. 一句话现状(2026-11-02 批次 17 收尾 + 契约对齐补修)
**📌 当前数字(以此为准,下面各批的「当时数字」仅存档)**:
- 契约端点 **487 条**(面 A 28 + 面 B **457** + 两面共用 2);`tables` → **65**
(`BASE_TABLES` 62:有 3 张表只在 `schema.sql` 里、不进自检清单;批次 16 复用既有表,**未新增表**)。
- `cargo test --offline --workspace` = **620 passed / 0 failed**(41 个测试二进制)。
- 十二道闸门全绿;`check-contract` `PASS=10 FAIL=0`,官方端点覆盖 **473/479**
(implemented 399 / partial 74 / absent 6;oos 4 单列)。
- `python3 scripts/fe-gap.py`:合计 **441 / 900(49.0%)**,**`permission` 137/137(100%)**、
**`system` 196/196(100%)**、**`systemData` 103/106(97.2%)**。
- 契约端点 **588 条**(面 A 28 + 面 B **558** + 两面共用 2);`tables` → **67**
(`BASE_TABLES` 64;批次 17 新增 `report_template` + `report_version` 两张**官方 DDL 逐字导入**的表)。
- `cargo test --offline --workspace` = **全绿 0 failed**(主 lib 105 passed;
`batch17_it` **11 passed**)。
- 十二道闸门全绿;`check-contract` `PASS=10 FAIL=0`,官方端点覆盖 **574/580**
(implemented 469 / partial 105 / absent 6;oos 4 单列)。
- `python3 scripts/fe-gap.py`:合计 **541 / 900(60.1%)**、**`onlineDev` 100/101(99.0%)**、
**`permission` 137/137(100%)**、**`system` 196/196(100%)**、**`systemData` 103/106(97.2%)**。
- 🔴 **批次 17 收尾补修:3 处「引用了官方 DDL 里不存在的列」的 SQL 已修**
(`base_visual_release.f_platform_release` / `base_system.f_app_key`+`f_app_name` /
`base_notice.f_full_name`)⇒ 这 3 条**静态闸门全绿时也是坏的**,只有真跑才炸
⇒ 已补 3 个集成测试(`release_menu_returns_bare_object_not_list` /
`system_filter_returns_official_system_list_vo_shape` /
`dashboard_notice_returns_list_vo_and_accepts_type_list`)把形状钉住。
同批还修了 3 处**官方契约形状偏差**(详见 §5「批次 17 新增的坑」末 3 条)。
- 🔴 **批次 17 把 onlineDev 收尾了**(101 条里的最后 78 条)+ **Report 23 条**
⇒ 契约端点从 487 涨到 588,官方覆盖从 473/479 涨到 574/580。
`fe-gap` 的 `onlineDev` 列从 22/101(批次 16 时)跳到 **100/101**。
剩的 1 条是 `docs/fe/endpoints.tsv` 的**旧记录**(官方实际是 `/api/visualdev/ShortLink/Config`,
**无路径参数**,已在本仓实现)⇒ **不是待办**。
- 🔴 **契约面实现按「官方模块名」分文件**(不再有 `face_b` / `face_c` 那一层):
`platform/compat/{core,helper,message,online_dev,permission,report,scheduletask,system}.rs`
⇒ 路由注册写成 `compat::<模块>::<handler>`。
🔴 **这个改动让契约扫描器的守卫推导一度全失效**(`HANDLER_RE` 只认一段 `::`
⇒ `compat::online_dev::x` 被解析成 `compat` ⇒ 推出不了守卫 ⇒ CC6 静默退化成全是 WARN)
—— 已修,详见 §5「批次 17 新增的坑」。
🔴 **`permission` 也清零了**:批次 16 把最后 26 条(角色绑定/在线用户/自定义范围/工作详情/第三方账号/导入导出)补齐,
其中 **12 条导入导出 + socials 两条 = 明确业务失败**(本仓无文件服务/无第三方登录配置),**没有一条假数据**。
`fe-gap` 的 `permission` 列从 111/137 跳到 137/137。
@@ -1008,6 +1028,48 @@ CRUD 落 `base_time_task`(数据真实、可编辑、重启不丢),`runCou
指纹非 token、按指纹精确删除、SelectedList `--` 保留与顺序、OrganizeCondition `$` 明确失败、getWorkByUser
`flow` 空/`app` 真、socials 两条失败、ImportData 真落库 + 判重 + `type=true` 拒绝、12 条导出拒绝。
### 批次 17(2026-11-02)—— onlineDev 收尾(78 条)+ 在线报表(23 条)+ 契约三处同步
**101 条面 B 端点**(新增表 2 张:`report_template` + `report_version`,**官方 DDL 逐字导入**):
- **onlineDev 78 条**(`platform/compat/online_dev.rs`):`visualdev/Base` 全族(14)、
`visualdev/Generater`(4)、`visualdev/OnlineDev`(15)、`visualdev/ShortLink`(8)、
`visualdev/Personal`(5)、`visualdev/OnlineLog`(1)、`visualdev/share`(4)、
`visualdev/ocr`(1)、`visualdev/Portal`(15)、`visualdev/Dashboard`(2)、
`system/PortalManage`(5)、`system/atlas`(2)、`blade-visual/visual/Selector`(1)。
- **Report 23 条**(`platform/compat/report.rs`):`/api/Report/*` 全族。
🔴 **Report 在官方是「独立部署的第三方服务」**(`jnpf-java-datareport-univer`,端口 32000,
`ReportDomain: http://127.0.0.1:32000`)—— 主后端 `jnpf-java-boot` 里**没有** `/api/Report`
的 Controller,也**没有任何** `report_version` 的 Java 实体(只有 `ReportExportUtil.java:29` 拼远程 URL)
⇒ 本仓把报表**元数据就地落库**(表结构照官方 DDL 逐字导入)。
🔴 **`data` 的形状逐条照官方前端的消费点定**(这一族最容易做错,四种形状并存):
| 形状 | 端点 | 官方消费点 |
|---|---|---|
| `PageListVO` `{pagination,list}` | `GET /api/Report` | `adapter/vxe-table.ts` 的 `proxyConfig.response` |
| **裸数组** | `GET /api/Report/Version/{id}` | `components/Report/src/index.vue:127` `state.versionList = res.data \|\| []` |
| **裸对象** | `GET /api/Report/{id}`、`GET /api/Report/Info/{id}` | `state.dataForm = res.data` |
| **裸字符串**(id) | `POST /api/Report`、`POST /api/Report/Info/{id}` | `state.dataForm.id = res.data` |
| **裸对象** `{queryList:"<JSON 串>"}` | `GET /api/Report/data/{id}/getQueryList` | 官方自己 `JSON.parse(res.data.queryList)` ⇒ **不能返解析后的数组** |
| `ListVO` `{list:[…]}` | `GET /api/Report/Selector` | `views/permission/menu/Form.vue:392` `state.reportData = res.data.list` |
🔴 **诚实失败原则**(沿用批次 14/15/16):本仓无文件服务 / 无 Univer 渲染器 / 无数据引擎 / 无代码生成器
⇒ 一律 `code=400` + `data:null` + 人话,**不返假 URL、不返空数组**。批次 17 的 101 条里
**31 条是 `partial`**(`[OFFICIAL]` 台账已标注原因)。
🔴 **审计列语义**(本仓特有,踩过):`f_creator_user_id` 存**账号**(`seed.rs` 的 `ADMIN_ACCOUNT`)
**不是 id** ⇒ 写审计列一律用 `user.account`;`f_last_modify_time` 用 SQL `now()` **不占参数位**。
🔴 **契约三处同步(101 条)**:新增 `scripts/gen-contract-endpoints.py` ——
从**代码真实路由**自动生成 `[ENDPOINT]`(5 列)与 `[OFFICIAL]`(5 列)登记行,
守卫直接调用扫描器的 `guard_of_platform`(与 CC6 **同一套**规则)⇒ **不可能手抖**。
**幂等**:再跑一次报 `+0 条`。已登记的条目**不覆盖**(人工写的 note 不会被冲掉)。
🔴 **官方出处的三种形态**(`[OFFICIAL]` 的 `src` 列):
① 官方 Java Controller 的 `@XxxMapping` 行号(`VisualdevController.java:134` 这种);
② 官方 Java **没有**对应映射 ⇒ 指官方前端 `api/onlineDev/portal.ts:84`;
③ Report 整族 ⇒ 指官方前端 `api/onlineDev/report.ts:14`(官方后端是**独立服务**)。
---
## 2. 运行中的现场(断了就按这里重启)
@@ -1187,20 +1249,33 @@ xop run --secret GU=git_local_user --secret GP=git_local_pass -- bash -c '
**create 用 `fieldRule!=0`、update 用 `fieldRule==1`**;delete 比对用**带前缀**的码。
🔴 **方案列表只需登录**(官方没加 `@SaCheckPermission`)。
🔴 `FieldList` / 表字段端点依赖低代码表单与数据库内省 ⇒ **诚实返回空**(不假装)。
12. 🔴🔴 **【批次 12 = 下一轮优先做】框架固定包 + 业务模块链接就好**
—— 不是补端点,是**改「加业务的成本结构」**:加一个业务模块从现在的
**改 6~8 处**(两份 spec 拷贝 + 手抄 DDL + 手抄契约表 + 改 `schema.sql` +
改 `main.rs` BASE_TABLES + 改 `sspf-store/db.rs` 两处表数断言)
降到 **写 1 个包文件 + 改 2 处**。
🔴 **四件事**:① `sspf-sdk` 补 `routes()` + 新建 `crates/sspf-plugin`(L2 静态装载器)
② 打通两份拷贝(`modules/asset.rs` 改 re-export)+ **补 PACK1 闸门**
③ 业务 DDL 跟着包走(不再手抄 `schema.sql`)+ 表数断言去写死
④ 契约登记**自动生成** + 静态闸门**增量提速** + 新增 `scripts/verify.sh` 一条命令。
🔴 **明确不做**:L3 dylib 动态库 / WASM 执行器 / `pack export-import` 双向迁移
(见该节「明确不做」)。完整方案见下方「批次 12」小节。
⚠️ **前端**:本仓 `src/frontend` **是空的**(后端-only)⇒ vue 前端那条诉求
**不在本仓范围**;官方 JNPF monorepo **本身就是那个「固定包」**(前端零改跑在本仓后端上)。
⇒ 若要做前端侧「页面脚手架」,需**先确认产品边界**(候选:仿 `new-pack.sh` 做 `new-page.sh`)。
12. 🔴🔴 **【批次 12 = 下一轮优先做】框架固定包 + 业务模块链接就好**
—— 不是补端点,是**改「加业务的成本结构」**:加一个业务模块从现在的
**改 6~8 处**(两份 spec 拷贝 + 手抄 DDL + 手抄契约表 + 改 `schema.sql` +
改 `main.rs` BASE_TABLES + 改 `sspf-store/db.rs` 两处表数断言)
降到 **写 1 个包文件 + 改 2 处**。
🔴 **四件事**:① `sspf-sdk` 补 `routes()` + 新建 `crates/sspf-plugin`(L2 静态装载器)
② 打通两份拷贝(`modules/asset.rs` 改 re-export)+ **补 PACK1 闸门**
③ 业务 DDL 跟着包走(不再手抄 `schema.sql`)+ 表数断言去写死
④ 契约登记**自动生成** + 静态闸门**增量提速** + 新增 `scripts/verify.sh` 一条命令。
🔴 **明确不做**:L3 dylib 动态库 / WASM 执行器 / `pack export-import` 双向迁移
(见该节「明确不做」)。完整方案见下方「批次 12」小节。
⚠️ **前端**:本仓 `src/frontend` **是空的**(后端-only)⇒ vue 前端那条诉求
**不在本仓范围**;官方 JNPF monorepo **本身就是那个「固定包」**(前端零改跑在本仓后端上)。
⇒ 若要做前端侧「页面脚手架」,需**先确认产品边界**(候选:仿 `new-pack.sh` 做 `new-page.sh`)。
13. ~~`onlineDev`(101) + `Report`(23)~~
✅ **批次 17 做完(实际 101 条:onlineDev 78 + Report 23)**——
新表 `report_template` + `report_version`(官方 DDL 逐字导入);
`fe-gap` 的 `onlineDev` 列 22/101 → **100/101(99.0%)**。
🔴 剩的 1 条是 `docs/fe/endpoints.tsv` 的**旧记录**(官方实际无路径参数)⇒ **不是待办**。
🔴 契约登记已**自动生成**(`scripts/gen-contract-endpoints.py`)⇒ 以后加端点不用手抄。
14. 🔴 **`core` 22 条**(`fe-gap` 现在 `core` 5/27 = 18.5%)—— 下一批优先。
15. 🔴 **`workFlow` 104 条**(`fe-gap` 现在 0/104)—— 官方在 `jnpf-flowable`,
依赖 **Flowable 引擎** ⇒ 大概率需要一批「诚实失败」端点 + 流程定义元数据落库。
16. ⏸️ **暂缓**(用户 2026-11-02 决定):`aiCenter` 75 / `extend` 64 / `msgCenter` 50 / `teamwork` 40。
17. ⏸️ **onlineDev 集成测试**(`tests/batch17_it.rs` 尚未写)—— 静态尺子已全绿,
但 **`matchit` 同位置参数名冲突**这类错静态看不出来(批次 12 踩过)⇒
新端点族落地后**必须**跑一次集成测试。
### 🔴🔴 批次 12(下一轮优先做)—— 「框架固定包 + 业务模块链接就好」
@@ -1698,7 +1773,6 @@ ENC_BIN="$PWD/target/debug/ssw-platform" bash scripts/perm-smoke-jnpf.sh
本仓沿用既有约定(create 回 `{id}`)—— 改的时候要**连前端消费点一起看**。
### 批次 13 新增的坑
- 🔴 **`query_json_params` 只认 SELECT**:它内部把 SQL 包成
`SELECT row_to_json(q)::text AS _row FROM (<你的 SQL>) AS q`
⇒ INSERT / UPDATE 塞进去报 **`syntax error at or near "INTO"`**(报错位置很误导)。
@@ -1720,6 +1794,79 @@ ENC_BIN="$PWD/target/debug/ssw-platform" bash scripts/perm-smoke-jnpf.sh
`cargo test --workspace` 红两条(`schema_sql_has_expected_table_count` /
`ddl_tables_parses_every_create_table`)—— 这是**有意的护栏**,不是过时的硬编码。
### 批次 17 新增的坑
- 🔴🔴 **契约面按官方模块名分文件 ⇒ 契约扫描器的守卫推导会**静默全失效**:
路由注册写成 `compat::online_dev::visual_dev_list`(三段 `::`)⇒
旧 `HANDLER_RE` 只认**一段** ⇒ 取到 `compat`(一个**目录**,不是文件)⇒
`plat_files.get("compat")` 落空 ⇒ **所有 compat 端点的守卫都「推不出」**
⇒ CC6 退化成**全是 WARN**(**不红**)⇒ 契约里写错守卫也没人抓。
**三个配套修改缺一不可**:
① `HANDLER_RE` 支持三段;② `scan_code` 把 `platform/compat/*.rs` 以
`compat__<名>` 收进 `plat_files`;③ `guard_of_platform` 用 **`mod_path` 含 `::`**
判断走 `compat__<名>` 还是根目录的 `<名>`。
🔴 **判据**:CC6 报「推不出」的条数突然变多 ⇒ 一定是这个坏了。
- 🔴 **守卫常量集中在 `compat/helper.rs` ⇒ `resolve_const` 只在当前文件找会只认出第一个**:
`guard_any(&[EN_AUTH, EN_ORGANIZE, EN_ROLE])` 里 `EN_ORGANIZE`/`EN_ROLE` 是
`use super::helper::{…}` 导入的 ⇒ 当前文件只有 `EN_AUTH` ⇒ 推出 `permission.auth`
而契约写 `permission.auth|permission.organize|permission.role` ⇒ **假漂移**。
修法:`scan_code` 收一张**平台层全局常量表**(`{名: (来源文件, 值)}`),
`resolve_const` 找不到时回落查表;**同名但值不一致** ⇒ 置 `None`(宁可推不出也不假推)。
- 🔴 **「无守卫」端点要单独判**:登录页要用的公开端点(`compat/core.rs::get_login_config`
—— 登录**前**就要拉 ⇒ 不能要 token)**一次鉴权调用都没有** ⇒ CC6 报「推不出」。
判据必须是「**没有任何** `guard`/`guard_any`/`require_login`/`require_module`」
而不是「没匹配到上面几种」。
- 🔴 **契约 `[ENDPOINT]` 的 `[PACK:BEGIN]~[PACK:END]` 段是 `pack-sync.py` 的生成物**:
手工往 `[ENDPOINT]` **末尾**追加行 ⇒ 生成段被挤到后面 ⇒ `pack-sync --check` 报
「`docs/contract.md` 不一致」⇒ `verify.sh` 第一步就红。
⇒ 追加后**必须**跑一次 `python3 scripts/pack-sync.py` 把生成段挪回去
(它会幂等重排);或者用 `scripts/gen-contract-endpoints.py`(它也踩过这个坑,已修)。
- 🔴 **`scripts/gen-contract-endpoints.py` 幂等**:再跑一次报 `+0 条`;
**已登记的条目不覆盖**(人工写的 note / 状态不会被冲掉)⇒ 可以放心重跑。
- 🔴 **官方 `/api/Report/*` 在官方是独立部署的第三方服务**(`jnpf-java-datareport-univer`,端口 32000):
主后端 `jnpf-java-boot` 里**没有** `/api/Report` 的 Controller,也**没有** `report_version` 实体
⇒ 查官方 Java 找不到出处 ⇒ `[OFFICIAL]` 的 `src` 只能指**官方前端** `api/onlineDev/report.ts`。
🔴 同理:`/api/visualdev/OnlineDev/{model_id}/Template` 与 `.../Actions/Export`
官方前端声明了但**官方 Java 没有**对应 `@XxxMapping`(Controller 里只有 `TemplateDownload`)
⇒ 记 `api/onlineDev/visualDev.ts:137` / `:141`。
- 🔴 **`f_creator_user_id` / `f_last_modify_user_id` 存的是「账号」不是 id**
(本仓 `seed.rs` 的 `ADMIN_ACCOUNT`)⇒ 写审计列一律用 `user.account`;
`f_last_modify_time` 用 SQL `now()` **不占参数位**(占了就错位)。
- 🔴 **`data` 的形状不是统一的「对象」**:Report 一族并存**五种**形状
(`PageListVO` / 裸数组 / 裸对象 / 裸 id 字符串 / `{queryList:"<JSON 串>"}`)
⇒ 返 `{list:[…]}` 或返解析后的数组 ⇒ 官方前端直接崩。
**判据**:每个端点的 `data` 形状看**官方前端的消费点**,不看 Java 返回类型。
- 🔴🔴 **SQL 里引用了官方 DDL 里根本不存在的列 ⇒ PG 运行时才炸**:
批次 17 的集成测试日志抓出 3 处:
① `base_visual_release.f_platform_release`(**官方 `base_visual_release` 没这列**,
只有 `base_visual_dev` 有)② `base_system.f_app_key` / `f_app_name`
(官方 `base_system` 只有 `f_portal_id`/`f_app_portal_id`/`f_property_json`…)
③ `base_notice.f_full_name`(官方 `NoticeEntity` 的标题列是 **`f_title`**)。
🔴 **这类错静态闸门看不出来**(表名对、列名错 ⇒ 只在真查库时炸)⇒
**必须跑集成测试并看日志**,不能只看 `code=200`(断言过了、日志里是 PG ERROR)。
🔴 查列的快捷法:`python3` 扫 `src/backend/db/schema.sql` 的 `CREATE TABLE` 块,
官方 DDL 在 `~/Desktop/workspace/jnpf/jnpf-database/`(逐字对齐的官方 PostgreSQL DDL)。
- 🔴 **官方 `getReleaseMenu` 返的是 `base_visual_dev` 的单条,不是 release 表的列表**:
官方 `VisualdevController.java:738` 是 `visualdevService.getById(id)` ⇒
`ActionResult<VisualFunctionModel>`;官方消费点
`CreateMenuModal.vue:56-59` 是 `state.record = res.data` ⇒ **裸对象**。
本仓原先查 `base_visual_release` 返 `ListVO` ⇒ 双重错(形状 + 列)。
🔴 官方 `VisualFunctionModel` 里 `pcIsRelease/appIsRelease/pcReleaseName/appReleaseName`
来自「菜单发布记录」表 ⇒ 本仓无该表 ⇒ 如实给 `0` / 空串。
- 🔴 **官方 `systemFilter` 的 VO 是 `SystemListVO`(不是本仓编的那几个字段)**:
官方 `jnpf.base.model.base.SystemListVO` 字段 =
`id/fullName/enCode/icon/sortCode/backgroundColor/userId/hasUpdate/hasDelete/isTop`。
🔴 官方 `PortalServiceImpl.java:229` 的 `systemFilterList` **直接忽略**
`id` 和 `category` 两个入参(`systemApi.getList(null, true, true)`)
⇒ 本仓也**不按 category 过滤**(照抄官方口径,不是偷懒)。
- 🔴 **官方 `Dashboard/Notice` 返 `ListVO` 不是 `PageListVO`,入参 `typeList` 是数组**:
官方 `DashboardController.java:45`(`ActionResult<ListVO<NoticeVO>>`)+
消费点 `components/VisualPortal/Design/hooks/useTable.ts:136-137`(`res.data.list || []`);
入参官方 `NoticeModel { typeList: List<String> }`(`useTable.ts:135` 传 `{ typeList }` 数组)。
🔴 官方 `NoticeVO` 字段 = `id/fullName/creatorTime/creatorUser/releaseUser/releaseTime/
category/coverImage/excerpt/lastModifyTime/lastModifyUserId`
⇒ `base_notice.f_description` 要投影成 **`excerpt`**(官方 `NoticeEntity.f_description` ⇒ `excerpt`)。
---
## 6. 收工前(每一轮都要做)