Files
ssw-platform/HANDOFF.md
T
admin cf154d50ff 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)
2026-11-02 16:01:24 +08:00

1885 lines
146 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# HANDOFF —— 交给下一个 session 的现场交接
> 更新于 2026-11-01 19:00(面 B 批次 11 收尾 + **批次 12 方向决策**),
> **20:10 追加「前端 MVP 用 React 模板、除了认证其它都留给集成阶段」**。**开工先读这一页**
> (尤其 **§0-bis 的「下一轮的优先级改了」**),再读 `CLAUDE.md`(硬约定),
> 最后看 `.workbuddy/memory/` 最近一天的日志(踩过的坑)。
> 无人值守时不要问用户,选最保守可行的方案继续,并把决策写回本文件。
---
## 0. ⚠️ 修正上一版口径(很重要)
上一版说「跑 pnpm 必须 `dangerouslyDisableSandbox`」。**这条不完整**:真正拦住 fs 的是
`NODE_OPTIONS` 里注入的 `node-language-shim.cjs`(brokered-fs),退沙箱它仍在,末尾报
`CODEBUDDY_BROKER_OUTCOME_UNKNOWN — Broker request timed out`。**正确做法见 §2,用
`env -u NODE_OPTIONS pnpm ...`** —— 实测 2169 包 46.5s 装完。
---
## 0-ter. 🔴🔴 两阶段开发路线(这是全局路线,先看这条)
**用户定的路线**(2026-11-01 19:39 明确):
```
┌─ MVP 阶段 ─────────────────────────────┐ ┌─ 规范集成阶段 ──────────────────┐
│ 用 ssw-jnpf-lite-rust 技能开发 │ │ 迁到标准 JNPF 框架集成开发 │
│ 「AI 怎么快怎么来」 │ → │ 遵守官方规范 │
│ 后端 = Rust(axum) 单二进制 │ │ 后端 = 标准 JNPF Java │
│ 前端 = React 模板(AI 友好薄壳) │ │ 前端 = 官方 JNPF vue(原生) │
│ └ 只做「认证 + 业务规则原型」 │ │ └ 补齐权限配置/低代码/建模等全套 │
│ └ 其它全部留给集成阶段 │ │ │
│ 目的:把业务快速跑通、把业务规则试出来 │ │ 目的:按官方规范固化、可维护 │
└────────────────────────────────────────┘ └─────────────────────────────────┘
↘ 仅「部分终端设备不佳」的场景保留 Rust 后端
```
🔴 **前端 MVP 用 React、不是 Vue**(2026-11-01 用户纠正):
「你看看 `ssw-jnpf-lite-react` 的模版,这个就是前端 MVP 阶段 AI 友好的方向,
**除了认证,其它都留给集成阶段**」。
⇒ **官方 vue 是集成阶段的事**;MVP 前端是 **React 薄壳**(两个技能的 React 前端**逐字节相同**)。
详见下面「🔴 前端在两阶段分别是什么」。
🔴 **两阶段的分界线不是「时间」,是「契约忠实度」**:
MVP 阶段允许**形状有偏差**(官方前端能跑、能试业务就行)⇒ 换来速度;
集成阶段要求**逐字对齐官方规范** ⇒ 换来可维护性。
⇒ **MVP 阶段的每一处「快」,都要在集成阶段还债。** 本文件就是那本账。
### 🔴 MVP 阶段「快」的真实代价(2026-11-01 19:40 实测,非推测)
官方端点台账(`docs/contract.md` 附录 A 的 `[OFFICIAL]`,379 条)的忠实度分布:
| status | 条数 | 含义 | 集成阶段怎么办 |
|---|---|---|---|
| `implemented` | **338** | 已落地且**形状对齐** | ✅ 直接搬 |
| `partial` | **27** | 已落地但**形状有偏差** | 🔴 **要还债**(下面逐条列) |
| `absent` | **7** | 未实现 | 集成时补(官方现成) |
| `oos` | **6** | 明确不做 | 集成时按官方做 |
⇒ **MVP 阶段真正的债 = 那 27 条 `partial`**。它们分三类:
| 类 | 条数 | 特征 | 集成时的动作 |
|---|---|---|---|
| **① 临时欠**(本仓没这能力,官方有) | **14** | 导出/导入/测试连接/打印渲染 —— **恒 `400` + 人话**(本仓无文件服务 / 无外部驱动 / 无渲染引擎) | **删掉本仓实现,用官方的** ⇒ 几乎零成本 |
| **② 形状欠**(语义对,VO 不逐字) | **9** | 如 `CurrentUser` 的 `sysConfigInfo` 返 `{}`、按钮级权限恒空、`permissionList` 粒度不同 | 🔴 **要真对齐**(前端依赖这些字段)⇒ 这类是**主要工作量** |
| **③ 自造**(本仓自己发明的) | **4** | 如 `f_en_code` 用本仓自定占位(`permission.demo` 等)、`deleteAllTable` 有意收窄 | 🔴 **改成官方编码 / 官方语义** |
⚠️ **②③ 共 13 条是真债**(要写代码),**① 14 条是假债**(删了换官方的就行)。
⇒ **MVP 阶段真正该盯的是那 13 条**,不是 27 条。这是「快」能快到什么程度的**精确边界**。
### 🔴 MVP 阶段的四条红线(违反了 = 集成时返工)
1. 🔴 **业务表的 `base_*` 列名不许自创** —— 官方 `base_*` DDL 逐字(`JNPF-PostgreSQL.sql` 13227 行 / 331 张表,本机已有)
⇒ 业务表 DDL 从一开始就照官方列名写 ⇒ 集成时**只导数据不导结构**。
2. 🔴 **业务表的 `f_tenant_id` 不许省**(值恒 `"0"`,但列 `NOT NULL` 且参与复合主键 `(f_id, f_tenant_id)`)。
3. 🔴 **接口路径从第一天就用官方形状**(面 B 的 `/api/xxx/...`)⇒ 集成时**前端零改**。
⚠️ 面 A 路径(`/api/ssw/...`)是本仓自造的 ⇒ **集成时全部作废**,只留给 Rust 终端场景。
4. 🔴 **返回形状宁可少字段,不许返错形状** ⇒ 官方前端遇到缺字段会**静默降级**(按钮恒显、树空)。
### ✅ 已经到位的部分(集成时直接搬,别重做)
| 项 | 证据 | 集成时 |
|---|---|---|
| `base_*` 表名/列名逐字对齐官方 | `schema.sql` 48 张 `base_*` | ✅ 只导数据 |
| 口令 cipher 逐字节等价 | `cipher.rs` 检验向量 + 官方 `DesUtil` | ✅ 换算一次(`MIGRATION.md` §7) |
| 响应信封 `ActionResult{code,msg,data}` | `envelope.rs` ↔ `jnpf.base.ActionResult` | ✅ 零改 |
| 实体 spec ↔ Java 实体 | `EntitySpec` 的列清单 ≈ 一个实体类 | ✅ 照 `MIGRATION.md` §2.1 翻译表 |
| 权限判据 | 面 B 已按 `f_en_code`(官方 `@SaCheckPermission` 的判据) | ✅ 零改 |
| 官方前端能直连本仓 | 面 B 契约 + `Vue-Version: 3` 判别头 | ✅ 集成时**前端几乎零改** |
| 官方前端加页面的机制 | `router/routes/index.ts` 用 `import.meta.glob('./modules/**/*.ts')` + `mergeRouteModules`(读 `default` 导出)⇒ **放文件进目录即注册**,不改配置 | ✅ 集成期把打磨期的页面搬进 `modules/` 目录即可 |
### 🔴 前端在两阶段分别是什么(2026-11-01 19:39 修正 + 20:10 按 React 模板重写)
> 🔴 **上一版这里写错了**:当时写「MVP 阶段前端 = 官方 JNPF vue(零改直连面 B)」。
> **用户已纠正**(原话:「你看看 `ssw-jnpf-lite-react` 的模版,这个就是前端 MVP 阶段 AI 友好的方向,
> **除了认证,其它都留给集成阶段**」):
> **MVP 阶段的前端 = React 技能模板,不是官方 vue**。官方 vue 是**集成阶段**的事。
| | MVP 阶段(AI 怎么快怎么来) | 集成阶段(按官方规范) |
|---|---|---|
| 前端代码 | **React + Vite**(`ssw-jnpf-lite-react` / `ssw-jnpf-lite-rust` 技能里的 `src/frontend`) | **官方 JNPF Vue**(`~/Desktop/workspace/jnpf/jnpf-web-apps-main`) |
| 后端对接 | 面 A `/api/ssw/...`(Rust/NestJS 自造约定)⇒ **前端零改直连** | 面 B `/api/{模块}/{资源}/...`(官方形状)⇒ **前端零改直连** |
| 认证 | ✅ **MVP 就做**(见下「认证为什么例外」) | ✅ 换成官方 `jnpf-oauth`,**路径/返回同形** |
| 业务页面 / 权限配置 UI / 低代码表单 / 数据建模页 | ❌ **不做**(只留最小原型) | ✅ 全做(官方有现成的) |
| 价值 | 业务规则能马上试出来、改一行刷新就看到 | 按官方规范固化、可维护 |
🔴 **一句话**:**MVP 前端 = 「能登录 + 能试业务规则」的薄壳**,
不是「一个 JNPF 前台」。**除了认证,其余全部留给集成阶段**。
#### 🔴🔴 认证为什么是唯一的例外(2026-11-01 20:10 实测,证据链完整)
认证是**唯一不能推迟**的部分——没有它就**连业务都试不了**(登录不进 ⇒ 看不到列表 ⇒ 试不了规则)。
而认证恰好也是**迁移时最不容易出错**的部分,因为它**契约已经完全对齐官方**:
| 环节 | MVP(React 模板) | 官方 | 结论 |
|---|---|---|---|
| 登录端点 | `POST /api/oauth/Login`(`x-www-form-urlencoded`) | `api/core/auth.ts`:`Api.Login = '/api/oauth/Login'` + `ContentTypeEnum.FORM_URLENCODED` | ✅ **一字不差** |
| 登录参数 | `account` / `password`(密文 hex) / `grant_type=password` | `AuthApi.LoginParams`:同样三个字段 | ✅ **一字不差** |
| 口令密文 | `cipher.ts`:`md5(plain)` → AES-256-ECB-PKCS7(key=`md5("EY8WePvjM5GGwQzn")`) → hex | 官方 `DesUtil` + `SecurityProperties` | ✅ **逐字节等价**(检验向量 `encryptPassword('123456')` = `d4958348e...cdc02b`) |
| 登录返回 | `{ token, expiresIn, tokenTypeName }` | 官方同形 | ✅ |
| 登出码 | `600/601/602` → 清 token 跳 `/login` | 官方 `ResultEnum.TOKEN_ERROR / TOKEN_LOGGED / TOKEN_TIMEOUT` 分支 | ✅ **语义 1:1** |
| 响应信封 | `ActionResult{code,msg,data}`,`code!==200` → reject | 官方 `transformResponseHook`:`{code,msg}` + `code===ResultEnum.SUCCESS` 才过 | ✅ **1:1** |
| 请求头 | `App-Code` / `Jnpf-Origin: pc` | 官方 `client.addRequestInterceptor`:三个头 + `K1`(RSA 加密的 aesKey) | ⚠️ MVP 少 `K1`(无 body 级 AES) |
⇒ **认证层在 MVP 阶段就照官方契约写** ⇒ 集成时**认证这块几乎零改**,
只需要把 `K1` 头和 body 级 `useCipher` 补上(官方 `AesEncryption` 走 `requestOptions.useCipher` 开关)。
#### 🔴 关键实测:**两个技能的 React 前端逐字节相同**(2026-11-01 20:05)
```bash
$ diff -rq skills/ssw-jnpf-lite-react/src/frontend/src skills/ssw-jnpf-lite-rust/src/frontend/src
# 无输出 ⇒ 完全一致
$ diff react/src/frontend/vite.config.ts rust/src/frontend/vite.config.ts
# 唯一差异:proxy 端口 30000(NestJS) vs 30010(Rust)
```
⇒ **「React 前端 MVP 模板」是独立资产,与后端选 Rust 还是 NestJS 无关**:
换后端栈**前端一个字都不用动**(契约同形)。
⇒ **这不是巧合,是设计**:两个技能刻意共用同一套前端,
就是为了让「先 NestJS 后 Rust」或「先 Rust 后官方 Java」的迁移路径上,前端永远零改。
⇒ **本仓(ssw-platform)的选择**:**MVP 后端用 Rust(axum),前端用这套 React 模板**
⇒ 直接从 `ssw-jnpf-lite-rust` 复制 `src/frontend` 即可(与 React 技能逐字节相同)。
#### 🔴 认证之外的「9 个接触点」在 React 模板里的位置(集成期要搬到 Vue)
React 模板的加模块成本 = **改/加 8 个文件、15~20 分钟**(`HOWTO_MODULE.md` §〇.5):
| # | 文件 | React 模板 | 集成期搬到官方 Vue |
|---|---|---|---|
| 1 | `src/backend/src/{app}/xxx.entity.ts` | ✅ MVP 做 | 翻译成 Java 实体(`@TableName` + `SuperEntity`) |
| 2 | `src/backend/src/{app}/xxx.service.ts` | ✅ MVP 做 | 翻译成 `SuperServiceImpl` |
| 3 | `src/backend/src/{app}/xxx.controller.ts` | ✅ MVP 做 | 翻译成 `BaseCrudController`(`references/BaseCrudController.java`) |
| 4 | `src/backend/src/{app}/xxx.module.ts` | ✅ MVP 做 | 换 Maven 多模块 `ssw.{appCode}.xx.xx` |
| 5 | `src/backend/src/app.module.ts`(**两处**) | ✅ MVP 做 | ❌ 集成期删除 |
| 6 | `src/frontend/src/api/xxx.ts` | ✅ MVP 做(3 个 export) | 翻译成 `api/<模块>.ts`(`defHttp.get/post/delete`) |
| 7 | `src/frontend/src/views/Xxx.tsx` | ✅ MVP 做(原型) | 翻译成 `views/<模块>/index.vue` |
| 8 | `src/frontend/src/App.tsx`(+1 `<Route>`) | ✅ MVP 做 | ❌ 集成期删除(官方按菜单自动注册路由) |
| 9 | `src/backend/src/sys/seed.service.ts`(`menus[]` +1 行) | ✅ MVP 做 | 数据 ETL 导进 `base_module` |
⇒ **「除了认证其它都留给集成阶段」的准确含义**:
**MVP 只做 #1~#5(后端)+ #6~#7(前端薄壳)**,
**#8/#9 的官方等价物(路由自动注册、菜单挂载)集成期才做**,
**权限配置 UI / 低代码表单 / 数据建模页这些官方现成能力,MVP 完全不碰**。
⚠️ **注意**:`check-module.sh` 的前端 4 个接触点在本仓**全打 `⏭`** ⇒
**前端目前没有任何闸门保护** ⇒ 集成前必须补(见 §3「批次 12」的 ④)。
---
## 0-bis. 📊 缺口全景(2026-10-31 05:00 全量摸底,看这里决定下一步)
用 `/tmp/fe-scan/scan.py` 扫前端 `src/api/**`(741 条端点定义,先解 `enum Api` 再解析
模板串),跟后端 `routes.rs` 做差集。**只看本仓该有的 6 个前缀**:
| 前缀 | 已覆盖 | 缺口 | 缺口主要是什么 |
|---|---|---|---|
| `permission` | 54 | 62 | 个人设置 `Users/Current/*`(14)、`Standing`(6)、`PermissionGroup`(6)、`Action`(3)、导入导出 |
| `system` | 29 | 208 | **大半是本仓没这个模块**:printDev(15)/Dataset(16)/DataModel(11)/DataInterface(10)/InterfaceOauth(9)/DataSource(5)/PortalManage(4)/BusinessCategory(5)/Area(6)/BillRule(6)… |
| `oauth` | 3 | 11 | 扫码登录、锁屏、验证码证书 |
| `message` | 0 | 53 | 消息中心(本仓无表) |
| `file` | 0 | 32 | 文件/网盘(本仓无表) |
| `extend` | 0 | 53 | 示例模块 + 邮件 + 甘特图(本仓无表) |
| **合计** | **86** | **419** | |
🔴 **判断**:419 里约 **250 条属于「本仓没这个模块」**,真做也只是恒空 stub。
剩下的真价值集中在 `permission` 那 62 条。所以**下一轮按这个顺序做**:
1. `permission/Users/Current/*` 个人设置(14 条,个人中心要用)—— ✅ 批次 1(实际 23 条)
2. `permission/Standing` / `PermissionGroup` / `Action`(15 条)—— ✅ 批次 2(实际 21 条)
3. ~~`system/System` + `system/SysConfig`(17 条,系统配置页)~~ —— ✅ 批次 3(实际 25 条)
4. ~~`message`(53) / 低代码模块 ⇒ 批量恒空 stub~~
✅ **批次 4 做完(实际 19 条)**——新表 `base_business_category` / `base_message` /
`base_notice`;业务分类(官方 38 行种子)+ 站内消息(列表/已读/回执/删除)+
公告(增删改查 + **发布即逐收件人落消息**)。
⚠️ 只做了 `api/system/message.ts` 那 14 条(消息记录页 / 公告管理页用的),
`api/msgCenter/*`(发送配置/账号配置/供应商/模板/监控/敏感词 —— 共 36 条)
是「消息中心运维后台」,本仓没这个产品 ⇒ **仍待定**(见下条)。
**被最多页面共用的接口**(`python3 scripts/fe-page-deps.py` 的实测排序,按这个做收益最高):
`DataModel/{}/Tables`(12 页) / `visualdev/OnlineDev/{}/Config`(10) / `ai/AiSupplier/Selector`(10) /
`BusinessCategory/treeList`(9 ✅批次4) / `Log`(9) / `workflow/operator/List`(9) /
`Dataset/{}/Actions/InfoByIds`(9) / `BasicDataType`(9) / `extend/TableExample` 四个(9) / `Tag/selector`(8 ✅批次3)。
~~**下一个(批次 5)建议**:`system/Log`(5) + `system/CommonWords`(6) + `system/BillRule`(8)~~
✅ **批次 5 做完(实际 21 条)**——新表 `base_sys_log` / `base_common_words` / `base_bill_rule`;
登录即落日志(`Log` 页与个人中心「登录日志」同一份数据)、审批常用语 CRUD + 使用计数、
单据规则 CRUD + **单号生成器**(时间/随机/UUID 三分支 + 跨天归零 + 回写流水)。
顺手把 `DictionaryData/All` 从「恒空」改成真读字典 + 灌 `businessType` 13 行种子。
详见 §1「批次 5」小节。
~~**下一个(批次 7)建议**:数据建模的**写面**(`POST/PUT/DELETE /DataModel/{linkId}/Table…`
+ `addFields` + `Copy` + `Export`/`Import`,共 8 条)—— 这批要动**真 DDL**
(`CREATE TABLE` / `ALTER TABLE` / `DROP TABLE`),必须先立两条护栏:
① `base_*` 平台表**禁止** ALTER/DROP(只允许看);② 表名/列名一律过白名单再拼 SQL。~~
✅ **批次 7 做完(实际 8 条)**——两条护栏都立了,且**判据取 DDL 真源**:
- ① `db_ident` 白名单(`[A-Za-z_][A-Za-z0-9_]*` + 双引号包裹)—— 唯一能拼字符串进 DDL 的入口;
- ② `is_builtin_table` = `sspf_store::db::ddl_tables()` ⇒ **`schema.sql` 里定义过的 35 张全部只给看**
(不写死清单,加表自动受保护,不会「加了表忘了加护栏」)。
- 官方 `checkTab` 的两道闸照抄:内置表 `DB101/DB102`、**表里有数据** `DB201/DB202`。
- 🔴 `update` 是**重建表**(官方也是),所以「有数据就拒」这条闸**不能省** —— 省了就是「改个注释,数据全没」。
- 🔴 `addFields` **不要求主键**(主键早在表上):要求了会让「加一列」永远失败;
且只 `ADD COLUMN IF NOT EXISTS`,新列一律可空(给非空表加 `NOT NULL` 列必失败)。
- 🔴 `Copy` 用 `LIKE … INCLUDING ALL`(官方按字段清单重建会**丢自增**);
`type=1` 的数据搬运写成**显式列清单** —— `INSERT … SELECT *` 会被 `check-arch` MEM1 判成整表载入。
- `deleteAllTable` **有意收窄**:只删「不在 `schema.sql` 里」的表(官方全删,含系统表 ⇒ 在这仓等于自杀)。
- `Export`/`Import` 恒 `400` + 人话(没有文件服务 / 没启 multipart),**不返假下载地址**。
做完这三页(`/dataCenter/dataModel`、`/dataCenter/dataSource`、`/dataCenter/basicField`)
就真正可用了。再往后是 `systemData` 的 `Dataset`/`DataInterface` 其余族。
~~**批次 8 候选**:`systemData` 的 `Dataset`(16) / `DataInterface`(10) / `InterfaceOauth`(9)
+ `system/printDev`(15)。~~ ✅ **批次 8 做完 `Dataset`(实际 18 条)**——见 §1「批次 8」小节。
- 它是全仓**唯一执行用户手写 SQL** 的地方 ⇒ 三道护栏(只 `select/with`、不许分号、
按词边界扫危险动词)+ 变量全走 `$N` 绑定。
- `Dataset` 是 `AutoComplete` / `PopupSelect` / `InputTable` / `SelectModal` / 报表 / 打印 /
大屏的**共同底座**(`fe-page-deps` 里 `Actions/InfoByIds` 被 9 个页面共用)⇒ 收益比条数大。
- ⚠️ 只做 `sqlType=1`(手写 SQL);图形化配置式(`sqlType=2`)/ HTTP / 静态数据一律 `400` + 人话。
- **下一个(批次 9)**:`DataInterface`(12) + `InterfaceOauth`(11) + `system/printDev`(17)。
`printDev` 是本仓没有打印设计器 ⇒ 多半只能恒空 stub(先看 `onlineDev/printDev/Form.vue` 再定)。
~~✅ **批次 9 做完(实际 39 条)**——见 §1「批次 9」小节。~~
- **批次 10 候选**:从「本仓确有官方 `base_*` 表支撑」的候选族里挑,选了**权限配置族**:
`Signature`(7) + `ModuleButton`(7) + `ModuleColumn`(6) + `ModuleForm`(6) + `AdvancedQuery`(5)。
~~✅ **批次 10 做完(实际 31 条)**——见 §1「批次 10」小节。~~
- **批次 11 候选**:继续沿权限族往下挑,选了**数据权限三件套**:
`ModuleDataAuthorize`(6) + `ModuleDataAuthorizeScheme`(5) + `ModuleDataAuthorizeLink`(4)。
~~✅ **批次 11 做完(实际 15 条)**——见 §1「批次 11」小节。~~
**2026-11-01 实测**(`python3 scripts/fe-gap.py`):合计 **331 / 900**(36.8%);
`permission` 111/137(81.0%)、`system` **141/196(71.9%,批次 4 47→66、批次 5 66→84、
批次 9 84→101、批次 10 101→132、批次 11 132→141)**、
**`systemData` 74/106(69.8%,批次 6 从 0 起、批次 7 29→35、批次 8 35→52、批次 9 52→74)**;
剩下体量最大的仍是 `workFlow`(104) / `onlineDev`(101) / `aiCenter`(75) /
`extend`(64) / `msgCenter`(50) —— **基本都属于「本仓没这个模块」**。
(🔴 批次 9 收尾时此处写的 252/28.0% 是**批次 8 的旧数**,实测 291/32.3%,此处已更正。)
### 🔴🔴 下一轮的优先级改了(2026-11-01 19:00 决策,19:39 补充两阶段路线)
**批次 12 不再是「补端点」,改成「把框架打成固定包 + 业务模块链接就好」。**
理由:端点补到 331/900 后,剩下的**大半是「本仓没这个模块」**(做了也是恒空 stub);
而**每加一个业务模块要改 6~8 处、手抄两份 spec、手抄 DDL、手抄契约表** —— 这个成本
才是「成熟框架 + 极简业务代码」的真实瓶颈。
⇒ 详见 §3「批次 12」的完整方案(4 项交付物 + 7 条护栏 + 5 条验收判据)。
🔴 **19:39 补充**:用户明确了**两阶段路线**(MVP 用 Rust 技能「AI 怎么快怎么来」→
业务定型后迁标准 JNPF 集成开发,Rust 只在「部分终端设备不佳」的场景保留)。
⇒ **这改变了批次 12 的优先级排序**:批次 12 的四项交付物**全部服务于 MVP 阶段的速度**,
但**每做一项都要留下「集成时能还债」的痕迹** ⇒ 详见 §0-ter 的「四条红线」与 §3「批次 12」
的「集成期友好性」验收项。**不是「先快后补」,是「快的同时记账」。**
🔴 **20:10 补充(前端方向定案)**:用户指明 **`ssw-jnpf-lite-react` 模板就是前端 MVP 阶段 AI 友好的方向**,
并划定了边界:**「除了认证,其它都留给集成阶段」**。
⇒ **前两版关于前端的表述都是错的**(先写「官方 vue 零改直连面 B」,后写「前端全程在官方 monorepo」)
⇒ 现在定案:**MVP 前端 = React 模板**(**认证做全套**,业务页面只做薄壳原型),
**官方 vue / 权限配置 UI / 低代码 / 数据建模 = 全部留给集成阶段**。
⇒ 🔴 **实测支撑**:两个技能的 `src/frontend` **逐字节相同**(仅 vite proxy 端口不同)
⇒ 前端是**独立资产**,与后端选 Rust 还是 NestJS 无关 ⇒ 换后端栈前端零改。
⇒ 详见 §0-ter 的「🔴 前端在两阶段分别是什么」。
**同时测出「快验证」的成本分布**(2026-11-01 19:00 实测,勿凭印象改):
| 类别 | 闸门 | 耗时 | 备注 |
|---|---|---|---|
| 静态 | `check-contract.sh` | **66.6s** 🔴 最慢 | 静态解析 659 个路由 ⇒ 提速首要目标 |
| 静态 | `check-module.sh` | 25.8s | |
| 静态 | `check-boundary.sh` | 7.2s | |
| 静态 | `check-citations.sh` | 5.2s | |
| 静态 | `check-naming.sh` | 3.6s | |
| 静态 | `check-arch.sh` | 1.6s | |
| 运行时 | `perm-smoke.sh` | 6.0s | 起隔离后端 |
| 运行时 | `perm-smoke-jnpf.sh` | 4.8s | |
| 运行时 | `baseline-smoke.sh` | 3.3s | |
| 运行时 | `mcp-smoke.sh` | 2.9s | 34 + 14 两段 |
| 运行时 | `lowcode-smoke.sh` | 1.9s | |
⇒ **静态闸门合计 ~110s,运行时合计 ~19s** ⇒ 「快速验证」的瓶颈在**静态闸门**,
不在起后端。批次 12 的 ④ 就是治这个(增量扫描 + `scripts/verify.sh` 一条命令)。
### 🔴 2026-11-01 22:00 复核:上面那张表**大半是「转发壳」的错**(结论已修正,别再按它排优先级)
同一套闸门在**普通终端**里只要表里数字的 **1/2 ~ 1/20**。原因不在代码,在**执行环境**:
沙箱 / AI 助手的 bash 会把 `grep` `sed` `cat` `wc` 换成一个**转发壳**
(PATH 指向 `…/shim/brokered-bin/<命令>`,**每次启动 ≈0.19s**)。而本仓闸门正是
「几百次 grep」的形态 ⇒ 0.19s × N 被逐条累加,看起来像「脚本写得慢」。
| 闸门 | 旧表(转发壳环境) | 普通终端实测 | 倍数 |
|---|---|---|---|
| `check-contract.sh` | 66.6s | **3.2s** | 21× |
| `check-module.sh` | 25.8s | **1.4s** | 18× |
| `check-boundary.sh` | 7.2s | **1.5s** | 4.8× |
| `check-citations.sh` | 5.2s | **4.0s** | 1.3× |
| `check-naming.sh` | 3.6s | **2.0s** | 1.8× |
| `check-arch.sh` | 1.6s | **1.7s** | 1× |
⇒ 旧表里「`check-contract` 66.6s→55.0s→8.2s」那几轮优化,**有一半是壳的功劳**,
换台普通终端重跑就没了。**只有纯算法改动才是真的**——2026-11-01 晚做掉的两处:
| 改动 | 真实收益 | 原理 |
|---|---|---|
| `check-contract-scan.py`:**函数体位置索引** `_fn_positions` | 1.4s → 0.15s(单次分析) | 原来「查一个 handler 就在**整份文件**上跑一遍 `re.search`」(362 次)⇒ 改成每份文件只扫一遍、建 `名字 → 位置` 表 |
| `check-citations-scan.py`:**引文后缀倒排表** `_lookups` | 1008 万次 `endswith` → 0 | 原来「每条引文遍历该根下**全部文件**做 `rel.endswith("/"+路径")`」⇒ 建成 `后缀 → 文件` 倒排表,查询 O(1) |
⇒ **教训(已写进 `scripts/verify.sh`)**:`verify.sh` 现在会先探测 `command -v grep`
是否落在 `*/shim/*` / `*/brokered-bin/*`,命中就打印醒目告警——
**「耗时不标注环境 = 假数据」**,假数据会让人去优化根本不存在的问题。
**当前真实数字(普通终端,`bash scripts/verify.sh --fast`)**:
```
契约生成段同步(pack-sync --check) 0.1s
编译(cargo build --offline) 0.3s
静态闸门 check-arch 1.7s
静态闸门 check-boundary 1.5s
静态闸门 check-naming 2.0s
静态闸门 check-module 1.4s
静态闸门 check-contract 3.2s
静态闸门 check-citations 4.0s
──────────────────────────────────────────
总耗时 14.6s(8 个步骤,全 ✅) ⇒ 批次 12 的「≤15s」目标**达成**
```
⚠️ **同一台机上 4 次实测是 14.6 / 14.7 / 15.2 / 15.5s**(机器负载不同,差 1s 量级)
⇒ 引用时说 **≈15s**,别把 14.6 当恒定值;也**别**为了「好看」去砍 `check-citations`
的断言——它 4.0s 里 2.6s 是**沙箱代理的文件读**(`socket.recv`),代码侧只剩 0.6s,
再优化就是跟执行环境较劲,不是跟算法较劲。
`--lib`(外加 `cargo test --workspace --lib`)= **23.5s**(单测 8.8s,103 passed)。
⚠️ 同一个 `verify.sh` 在转发壳环境里仍会打印 36.1s —— 但开头会先警告「本环境的 grep
被转发壳接管」,看到这行就别拿那个数字做判断。
---
## 1. 一句话现状(2026-11-02 批次 17 收尾 + 契约对齐补修)
**📌 当前数字(以此为准,下面各批的「当时数字」仅存档)**:
- 契约端点 **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。
🔴 **`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.*`)。
⇒ 看缺口表别以为「系统数据没动」,它动的是 `system` 那一列(141 → 155)。
- 🔴 **数据建模三页(`/dataCenter/dataModel` / `dataSource` / `basicField`)现在真能用了**:
建表 / 改表 / 加字段 / 删表 / 复制 / 预览 / 导出(明说不支持)全通,
平台表(`schema.sql` 里的 52 张)与「有数据的表」一律禁改禁删。
- 🔴 **数据集(`/dataCenter/dataset`)真能跑 SQL 了**:这是全仓**唯一**执行用户手写 SQL 的地方,
三道护栏 + 变量全走 `$N` 绑定。它是 `AutoComplete` / `PopupSelect` / `InputTable` /
`SelectModal` / 报表 / 打印 / 大屏的**共同底座** —— 这一批之后那批通用组件不再是空壳。
- 🔴 **数据接口(`/dataCenter/dataService`)真能取数了**:复用数据集那套执行面(SQL 只读 +
`$N` 绑定),`Export` 明说不支持。接口认证(`/integrationCenter/openApi`)与
打印模板(`/onlineDev/printDev`)也落地了;打印模板**只存设计 JSON、不渲染**
(本仓无渲染引擎 ⇒ `Export`/`BatchData` 恒 `400` + 人话)。
- 🔴 **权限配置族落地了**(批次 10):电子签章、按钮权限、列表权限、表单权限、
高级查询方案共 31 条端点 —— 这是「权限」页配权限的后端地基,见 §1「批次 10」小节。
- 🔴 **数据权限三件套落地了**(批次 11):数据权限字段 / 数据权限方案 / 数据连接共 15 条端点
—— 见 §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` 与
`packs/asset/src/lib.rs` 里两份逐字拷贝、**没有任何闸门比对**(PACK1 当时未实现)。
(今)`sspf-plugin` + 生成的 `packs_gen.rs` 负责装载、`pack-sync.py` 从包生成契约段、
`PackRoute` 的守卫对齐面 B、`tests/pack_smoke_it.rs` 真发请求冒烟、`new-pack.sh` 一条命令加包。
详见 §3「批次 12」。
**✅ 后端已拆成 workspace 多 crate,业务包可独立编译;十二道闸门全绿;空载内存 8 MB。**
- 新增 `crates/sspf-contract`(契约层,无 axum)、`crates/sspf-sdk`(业务包唯一依赖)、
`packs/asset`(样板业务包,只依赖 sdk,能 `cargo test -p sspf-pack-asset` 独立跑)。
🔴 业务包与内核的接线是**批次 12**做的(`sspf-plugin` + `packs_gen.rs` + `pack-sync.py`),
见 §3「批次 12」;上面「业务包目前是死的」那段是 2026-11-01 的历史口径。
- `rust-toolchain.toml` 全仓锁 **1.95.0**(L3 动态库 ABI 一致性强依赖;本机代理限速装不上 1.99)。
- 新增两道闸门:`scripts/check-arch.sh`(AR1–AR7 + MEM1–MEM2,带 `--self-test`)、
`scripts/mem-budget.sh`(空载内存实测,用 `vmmap`,**本机沙箱禁 ps/top**)。
- 内核 `platform/{envelope,entity,menu,ids}.rs` 已改为 re-export 契约层 ⇒ 引用路径零变化。
- `cargo test --workspace` = **240 条**(不是 221/230 了,拆 crate 后数字会变,别写死)。
- 长期架构与路线看 **`PLAN.md`**(尤其判断 ⑥ 内存约束、判断 ⑦ 执行器、§4.5 动态库 ABI)。
**前端侧(未变):✅ 浏览器里真跑起来了,用户管理页可渲染、列表/新增/编辑/删除全部可用。**
- 登录 `admin/123456` → 进 `/home` → `/permission/user` 正常渲染,左侧分组树 + 右侧表格有数据,
**整页零非 200 请求**(fetch/XHR 双钩子实测 `[]`)。
- 机构管理 `/permission/organize` 也正常渲染(空状态,零报错)。
**第二波(04:00–05:00)当时的数字(已过期,仅存档):**
- 契约端点 **207 条**(面 B **177** 条);`tables` → **26**(新增 `base_group`、
`base_position`、`base_dictionary_type`、`base_dictionary_data`、`base_user_extra`、
`base_sign_img`、`base_standing`、`base_permission_group`、`base_action`)。
- 六闸全绿:`check-module 114` / `check-boundary 11` / `check-contract 10` /
`check-citations 4` / `perm-smoke 43` / `perm-smoke-jnpf 23`,`cargo test` **230 全过**。
- 官方端点台账覆盖 **165/172**(implemented 160 / partial 5 / absent 7)。
- 浏览器实测 5 个页面**零非 200**:用户管理、机构管理、角色管理、菜单管理、岗位。
菜单管理页能正常显示树(系统管理 → 用户/角色/机构/菜单管理)。
### 批次 2(2026-10-31 08:00–09:00)做了什么
`permission/Standing`(8) + `permission/PermissionGroup`(8) + `permission/Action`(5) = **21 条面 B 端点**,
新增官方表 `base_standing`(15 列) / `base_permission_group`(16 列) / `base_action`(15 列)。
**官方 DDL 逐字对齐**(行号已核对 `JNPF-PostgreSQL.sql`):
`base_action`:1 / `base_permission_group`:3278 / `base_standing`:4071。
🔴 **官方陷阱已照抄**:`base_action.f_enabled_mark` 是 **VARCHAR(11)**(不是 INTEGER)⇒
投影用 `COALESCE(f_enabled_mark,'0')`,**不加 integer CAST**。
🔴 **官方语义已对齐**:
- `base_standing.f_is_system`:**1=系统身份 / 2=自定义** ⇒ 新建默认写 **2**,投影归一化成 `isSystem` 0/1。
- `base_action.f_type`:**1=自定义** ⇒ 新建强制写 1(前端 `record.type == 1 ? '自定义' : '系统'`)。
- `PermissionGroupController.list` 会用 `userService.getFullNameByIds` 把 `f_permission_member`
的 **id 串换成用户名串** ⇒ 本仓用子查询 `string_agg(...)` 做同样的替换。
### 🔴 本轮踩到并解决的 4 个真 bug(都有回归测试 + 反自证)
| # | 症状 | 根因 | 修法 |
|---|---|---|---|
| ① | `GET /PermissionGroup/PermissionMember/{id}` → 500 / `data:null` | `f_id = ANY($1::text[])` ⇒ pglite-rs 把 `$1::text[]` 当成 PG 数组类型 `_text` | 改 `ANY(string_to_array($1::text, ','))`(**函数在 SQL 里做** ⇒ 参数仍是 text) |
| ② | `DELETE /PermissionGroup/{id}` → 500 `42P18` | 软删 `base_authorize` 的 SQL 带了 `$1` 但 WHERE/赋值里**没用到** ⇒ PG 拒「无法确定 $1 类型」 | 把 `f_delete_user_id = $1::text` 写进 SET(既是审计列,也用掉参数) |
| ③ | `DELETE /Standing/{id}` 后**关联残留**(静默) | 软删关联的**占位符与参数顺序错位**(SQL `$1`=item_type、`$2`=item_id,参数传 `[account, id]`) | `rel = [item_type, id, account]` + SQL 改 `$1/$2/$3` 对齐 |
| ④ | 权限组列表 `permissionMember` 返**uuid 串** | 漏了官方的 `getFullNameByIds` 替换 | 子查询 `string_agg` 换成人名串 |
回归测试:`src/backend/tests/batch2_it.rs`(**4 条**,每个钉一个 bug)。
**反自证全部做过**:逐个把修复回退 ⇒ 测试精确复现原始报错(`cannot convert between String and _text` /
`42P18` / 关联残留 n=1 / uuid 串)⇒ 恢复后 4 条全过。
### 批次 3(2026-10-31 21:40–22:10)—— 应用中心 + 系统配置
**31 条面 B 端点**:`/api/system/System`(13:列表/详情/新建/改/删/复制/置顶/偏好/开发者授权×3/Selector/userAuthList)
+ `/api/system/SysConfig`(8:参数读写/第三方配置读写/管理员列表/设置/企业微信·钉钉连通性测试)
+ `/api/system/SynThirdInfo`(4:同步/统计/清空/失败清单)
+ `/api/system/Tag`(6:列表/详情/新建/改/删/selector —— 应用中心页一进来就拉 `selector?enCode=AppTags`)。
- 新表三张(官方 DDL 逐字):`base_system_top`(置顶按 `f_user_id + f_type` 记账)、
`base_sys_config`(`f_category + f_key → f_value` 的键值表)、`base_tag`(标签)。
- 🔴 **老库补表**:`Db::ensure_schema` 原先见到 `base_user` 就早退 ⇒ 后加的表在老库上
**永远不存在**。现在会按 `schema.sql` 逐表探 `to_regclass`,缺哪张补哪张
(DDL 仍以 `schema.sql` 为唯一真源,不另写迁移脚本);单独测试见
`tests/schema_upgrade_it.rs`。
- 🔴 **尺子自身的 bug 修了**:`check-contract-scan.py` 判面 B 守卫时只认模块名
`jnpf` 与函数 `require_login_jnpf` —— 文件早已改名 `face_b.rs` / `require_login_face_b`
⇒ 整片面 B 的 CC6 守卫检查**静默失效**(只打 warning)。两个名字都认之后恢复生效。
- 复制应用**只复制应用行**(菜单/表单资源不复制)⇒ `[OFFICIAL]` 记 `partial`;
应用授权的 `devUsers` 存 `f_user_id` 逗号串、不写 `base_authorize` ⇒ 也记 `partial`。
- 企业微信/钉钉连通性测试**恒业务失败**(未接 SDK)—— 刻意不假装成功。
### 批次 4(2026-10-31)—— 消息业务分类 + 站内消息 + 公告
**19 条面 B 端点**:`/api/system/BusinessCategory`(7:树/详/增/改/删/`treeList`/`selector`)
+ `/api/message`(5:列表/全部已读/读消息/删记录/回执)
+ `/api/message/Notice`(7:列表/增/详/改/删/发布/回执人列表)。
- 新表三张(官方 DDL 逐字):`base_business_category` / `base_message` / `base_notice`;
tables 26 → 29。
- 🔴 **业务分类是平台字典,不是用户数据**:官方初始库灌 89 行(一级 + 二级 + 三级)。
本仓在 `platform/seed.rs::BUSINESS_CATEGORIES` 灌 **38 行**(5 个一级 + 33 个二级),
**id 沿用官方雪花 id**(`f_category` 存的就是这些 id 串,改 id 官方历史消息就错位)。
三级是「消息事件」粒度(`flow_todo_remind` 之类),没有消息行时展示不到 ⇒ 暂不灌。
- 🔴 **`base_message` 一行 = 一个收件人**(`f_user_id` 是收件人,发件人在 `f_creator_user_id`)
⇒ 所有查询必须带 `f_user_id = 当前用户`,漏了就是串号。
- 🔴 **公告发布是全链路的唯一消息来源**:`PUT /Notice/{id}/Actions/Release` 置
`f_enabled_mark=1` 后**逐收件人插 `base_message`**(收件人为空 ⇒ 全体启用用户),
`f_category` 拼「公告一级 id,公告提醒二级 id」⇒ 消息记录页按二级页签过滤、
按一级 `enCode` 显示类型名,两者同时成立。不落这一步,消息记录页永远是空的。
- 🔴 **`ReadInfo` 会写库**(`f_is_read` 0⇒1),且 `f_is_read=2`(已回执)时不回退 ——
前端「点开就变已读」全靠它,别当纯查询。
- 🔴 **用户标签要按 `f_id` 与 `f_account` 双键查**:本仓写 `f_creator_user_id` 存的是**账号**
(`seed.rs` 的 `ADMIN_ACCOUNT`),官方历史数据里是 **id** ⇒ 只查一种另一种永远显示空。
- 已知 `partial`:`POST /message/Notice/List` 的**时间区间过滤未做**
(`releaseTime`/`creatorTime`/`expirationTime` 三个区间参数接受但忽略);
分类删除是**软删**(官方物理删,本仓偏保守)。
- 回归测试 `tests/batch4_it.rs`(**3 条**):分类树/裁剪/两段式 selector/判重、
发布扩散、读+回执+删除(含「已回执不回退」与「只删自己的」)。
### 批次 5(2026-11-01)—— 系统日志 + 审批常用语 + 单据规则
**21 条面 B 端点**:`/api/system/Log`(6:列表/详情/删一条/按类型清空/清登录日志/模块名)
+ `/api/system/CommonWords`(7:列表/selector/详/增/改/删/使用计数)
+ `/api/system/BillRule`(10:列表/selector/详/增/改/启停/删/导出/导入/生成单号)。
- 新表三张(官方 DDL 逐字):`base_sys_log`(30 列)/ `base_common_words` / `base_bill_rule`;tables 29 → **32**。
- 🔴 **登录日志此前根本不存在**:`self_system_log`(个人中心「登录日志」)是手写的恒空分页。
本轮在 `auth.rs::login_handler` 里落一行 `f_type=1`(成功 `f_login_mark=1`、失败 `=0` 且 `f_description` 存失败原因),
**失败只打 stderr 绝不冒泡**(日志写坏了不能把登录搞挂)⇒ `Log?category=1` 与 `Users/Current/SystemLog`
共用同一个 `log_page(.., 1, Some(uid))`,两处同时变真。
- 🔴 **`DELETE /Log/{type}` 的 `{type}` 是分类号不是 id**(官方 `deleteLoginLog` 就是删 `f_type=1` 全部)。
实现成「删某一条」的话,管理员点「一键清空」会静默什么都不做。路由上 `/Log/{id}` 的 GET(详情)与 DELETE(清空)
共用同一段名 `{id}`(matchit 不允许同位置两个参数名),handler 内部按分类号解析。
- 🔴 **`to_char` 的占位符不能照搬官方**:PG 的 `HH` 是 12 小时制、毫秒叫 `MS` 不叫 `SSS`
⇒ 单独写 `to_char_pattern()` 把小写官方格式映射成 PG 格式,否则会生成「下午 03 点」的错号。
- 🔴 **改单据规则时只有四个条件变了才清流水**(前缀/后缀**长度**、位数、日期格式)——
照抄官方这段判断,不然「改个描述」也会把 `f_this_number` 清掉,已发出的号就重号了。
- 🔴 **`f_this_number` / `f_output_number` 只由 `BillNumber` 回写**,不在 `*_WRITE_FIELDS` 里(14 列不含这两个);
规则被发过号(`f_output_number` 非空)就**禁删**(`400 单据已经被使用,不允许被删除`)。
- 🔴 **常用语判重按 `文本 + 类型` 同档**(公共/个人各一套),且 `CommonWordsController` 官方**一个
`@SaCheckPermission` 都没有** ⇒ 故意不挂 `guard()`,只做 `require_login_face_b`。
- 已知 `partial`:`DELETE /Log/{id}` 的 `dataInterfaceId` 收窄未做;`BillRule` 的 `Export`/`Import`
恒业务失败(本仓没有文件服务,**刻意不假装成功**)。
- 顺手修:`GET /api/system/DictionaryData/All` 原先**恒空**(`businessType` 之类下拉全空且不报错)
⇒ 改为真读两张字典表 + `seed.rs` 灌 `businessType` 13 行(`isTree=0`)。
- 回归测试 `tests/batch5_it.rs`(**6 条**):登录落日志双读者一致、三条删除路径语义不同、
常用语 CRUD + 计数、单号时间格式 + 跨天归零、规则守卫、随机/UUID 分支。
### 批次 6(2026-11-01)—— 数据连接 + 数据建模只读面
**16 条面 B 端点**:`/api/system/DataSource`(8:列表/分组/下拉树/详/增/改/删/测试连接)
+ `/api/system/BasicDataType`(1:基准类型列表)+ `/api/system/CommonFields`(1:常用字段列表)
+ `/api/system/DataModel/**`(6:表清单 / 表+视图 / 表信息 / 字段 / 字段下拉 / 数据预览)。
- 新表三张(官方 DDL 逐字):`base_db_link`(22 列)/ `base_data_type` / `base_common_fields`;tables 32 → **35**。
- 两张**平台字典**照官方初始库逐字灌(`seed.rs`):`DATA_TYPES` 7 行 + `COMMON_FIELDS` 10 行。
🔴 前者是数据建模表单的**类型下拉唯一数据源**,空了表单虽能开但**建不出表**(不报错)。
- 🔴 **`DataSource/Selector` 的第一组第一项必须是合成的「默认数据库」(`id="0"`)**:
`dataCenter/dataModel/index.vue:158-166` 取 `list[0].children[0]` 当默认连接,
少了它 `dbType` 是 `undefined` ⇒ 建表表单判不出库类型。本仓只有一个库 ⇒ **`linkId` 一律忽略**。
- 🔴 **`Preview` 绝对不能写 `SELECT *`**:`query_json_params` 会把 `f_*` 列名归一成 camelCase
(`f_en_code` ⇒ `enCode`),而 `Preview.vue:62` 取的是 `record[column.field.toLowerCase()]`
(**原样列名**)⇒ 整张表会**空白且不报错**。必须逐列 `"col" AS "col"`(双引号别名是权威名)。
- 🔴 **`hasTableData` 必须真探测**(`EXISTS(SELECT 1 …)`):前端据此把已有字段**锁成不可改**
(`Form.vue:113-115`),给 `false` 会让用户在**有数据**的表上删列 ⇒ 直接丢数据。
- 🔴 **详情不回明文密码**(`password` 恒空串);`update` 传空串 = **不改密码**(前端编辑时密码框本来就空)。
`Actions/Test` **恒业务失败**(本仓没有外部驱动层)—— 刻意不假装连上了。
- 表名/列名收窄成 `[A-Za-z_][A-Za-z0-9_]*`([`db_ident`],比 `valid_table` 宽一点:官方允许 `_` 开头),
只有 `Preview` 会把表名拼进 SQL ⇒ 这段白名单 + 双引号是唯二的注入防线。
- 已知 `partial`:`dbType` 保持编码原样(官方换字典中文名,本仓没灌「系统数据连接」字典);
`CommonFields` 只校验登录(官方要 `dataCenter.dataModel|dataCenter.basicField` 任一,
本仓后者还没登记成点权限);`tableName`/`fieldName` 取 PG 注释,**本仓 schema.sql 没写
`COMMENT ON` ⇒ 全是空串**(数据建模页「说明」列会空,想改就补 `COMMENT ON`)。
- 🔴 **尺子也改了一处**:`check-contract-scan.py` 原先只认 `guard(&state,&headers,CONST)`,
新增 `guard_any(&state,&headers,&[A,B])` 的推导(契约里写 `A|B`,**顺序即代码里的顺序**)
—— 官方 `@SaCheckPermission(..., mode=OR)` 那几处就靠它,否则整条只能打「推不出」警告。
- 回归测试 `tests/batch6_it.rs`(**5 条**):连接的增删改查 + 默认库契约 + 软删三处一致、
两张字典的 7/10 行与 `dataTypeName` 联查、表清单分页/关键词/字段归一/`hasTableData`、
预览分页与单字段模糊、未登录 602。
### 批次 7(2026-11-01)—— 数据建模**写面**(真 DDL)
**8 条面 B 端点**:`POST/PUT /DataModel/{linkId}/Table`(建表 / 改表)
+ `PUT …/addFields`(加字段)+ `DELETE …/Table/{tableName}`(删表)
+ `DELETE …/deleteAllTable` + `POST …/Table/{t}/Actions/Copy` + `GET …/Actions/Export` + `POST …/Actions/Import`。
- 🔴 **两条护栏,缺一不可**:
① [`db_ident`] 白名单(`[A-Za-z_][A-Za-z0-9_]*` + 双引号)—— 全仓唯一能把字符串拼进 DDL 的入口;
② [`is_builtin_table`] = `sspf_store::db::ddl_tables()` ⇒ **`schema.sql` 里定义过的 35 张全部只给看**。
🔴 判据**取 DDL 真源**而不是在 handler 里再抄一份清单 —— 抄一份的后果是「加了表忘了加护栏」,
新表能被用户在建模页一键删掉。
- 🔴 **`update` 是重建表**(官方 `creTable`→`dropTable`→`reTableName`)⇒「表里有数据就拒」(`DB202`)
这条闸**不能省**:省了就是「改个表注释,数据全没」。本仓实现成
`DROP TABLE old; CREATE TABLE new …` **同一批**交给 `Db::exec`(simple protocol ⇒ 隐式事务),
比官方那三步少一个「删了旧表但新表没建起来」的中间态。
- 🔴 **`addFields` 不要求主键**:主键早在表上,还要求「必须选一个主键」会让**「加一列」永远失败**。
这条是实测踩到的(第一版照抄 create 的校验 ⇒ 400「请选择一个字段作为主键」)。
且只 `ADD COLUMN IF NOT EXISTS`、新列一律可空(给非空表加 `NOT NULL` 列必失败)。
- 🔴 **`Copy` 用 `CREATE TABLE … (LIKE … INCLUDING ALL)`**:主键 / `NOT NULL` / `DEFAULT` /
`IDENTITY` 一起带过去。官方是「读字段清单再重建」⇒ **复制出来的表丢自增**。
`type=1` 的数据搬运写**显式列清单**(`INSERT INTO dst (c1,c2) SELECT c1,c2 FROM src`)——
写 `SELECT *` 会被 `check-arch` 的 MEM1 判成「整表载入内存」。
- 🔴 **`deleteAllTable` 有意收窄**:官方删 `getTableList` 的**全部**表(含系统表,
在这仓等于把平台自己拆了 —— `base_user` 一没就再也登不回来,种子只在空库上跑)
⇒ 本仓只删「不在 `schema.sql` 里」的表,也就是用户自己从建模页建的。
- 🔴 **`dataLength` 对 `decimal` 必须带小数位**(`18,4` 而不是 `18`):只给精度的话,
前端编辑一次表就把 `numeric(18,4)` 改成 `numeric(18,0)`,**静默丢精度**。
改的是 `db_field_rows` 的 `numeric_precision || ',' || numeric_scale`。
- `Export`/`Import` 恒 `400` + 人话(没有文件服务 / 没启 `axum/multipart`),
**不返假下载地址**(前端会拿它去 `location.href`,得到一个 404 页面)。
- 回归测试 `tests/batch7_it.rs`(**8 条**):建表往返 + 重名、五类非法 schema、
内置表禁改禁删、改表重建 + 改名、加字段只追加、有数据的表冻结、
复制守卫 + 清空只删非内置、导出导入诚实失败。
### 批次 8(2026-11-01)—— 数据集(真执行 SQL)
**18 条面 B 端点**:`/Dataset` 的 `GET`/`POST`/`PUT`/`DELETE` + `getList` + `previewSql`
+ `fields` + `GetParam/{id}` + `{id}/get` + `{id}/save` + `{id}/Actions/{Export,Copy,Preview,List,InfoByIds,getRes}`
+ `Actions/Import`。新表 `base_data_set`(26 列)/ `base_data_set_relation`(13 列),`tables` 35 → 37。
- 🔴 **这是全仓唯一执行用户手写 SQL 的地方**(数据连接那条只是存配置)。三道护栏见
[`dataset_sql_guard`]:① 去尾分号后必须 `select`/`with` 开头;② 全文不许再有 `;`
(pglite 的 `exec` 走 simple protocol,多语句会**一起跑**);③ 按**词边界**扫危险动词
(`insert/update/delete/drop/truncate/alter/create/grant/revoke/copy/vacuum/merge`)与
文件/延时函数(`pg_read_file` / `pg_ls_dir` / `lo_import` / `pg_sleep` / `dblink` …)。
- 🔴 **按词边界而不是子串**:`update_time` / `create_id` 这种别名必须放行 —— 子串匹配会把
一批正常的业务 SQL 全拒掉(测试里专门钉了这一条)。
- 🔴 **变量只走绑定**:`${xxx}` / `@xxx` 一律转成 `$N` + 参数数组,**绝不拼进文本**。
与官方两处**有意不同**:官方找不到值时原样保留变量名(结果是一条非法 SQL,用户看到
PG 的语法错);本仓直接 `400 缺少参数 xxx`。官方空集合替换成一个空格(`in ( )` 语法错);
本仓替换成 `NULL`。
- 🔴 **`getRes` 用的是 body 里的 `dataConfigJson`**,不是库里的 —— 设计器边改边试跑,
读库永远是上一次保存的 SQL。
- ⚠️ **列名靠「执行 1 行」反推**:`row_to_json` 没有行就没有键 ⇒ **空结果集拿不到列名**,
`fields` 返回空数组(官方走 JDBC 元数据,本仓做不到)。写进 `[OFFICIAL]` 的 `implemented` 备注里。
- 🔴 **列表与详情的形状不同**:列表 `DataSetListVO` 的 `type`/`returnType` 是**中文名**
(`SQL语句` / `列表数据`),详情 `DataSetForm` 里是**数字**。同一份投影,两个整形函数。
- 🔴 **`{id}/save` 的 `variateJson` 收下不落库**(本仓没有 `base_data_interface_variate` 表),
`{id}/get` 恒回 `"[]"` —— 形状对上,内容为空,**不假装存了**。
- 🔴 **`SELECT *` 会被 `check-arch` MEM1 判红**(终端内存预算 120MB)。而这里列名由用户 SQL
决定、拿不到清单 ⇒ 写成 `jnpfs.*`(带表别名,语义等价,且每句都自带 `LIMIT`)。
- **`InfoByIds` 的 `propsValue` 过 `db_ident` 白名单** —— 它要拼进 SQL 的列名位,
不过白名单就是一个注入口(测试里用 `code" ; drop table base_user --` 钉住了)。
- `previewSql` 只支持 `sqlType=1`(原样回 SQL);图形化配置式 / HTTP / 静态数据一律 `400` + 人话。
- 回归测试 `tests/batch8_it.rs`(**6 条**):形状与 CRUD(含「只改名称不误判重」)、
`getList` 剔 `isSystem` 参数、绑定执行(含引号注入串 ⇒ 0 行)、护栏五拦一放、
设计器往返 + `getRes` 用 body、`InfoByIds` 顺序对齐 + 导出导入诚实失败。
### 批次 9(2026-11-01)—— 数据接口 + 接口认证 + 打印模板
**39 条面 B 端点**:`DataInterface`(12) + `InterfaceOauth`(10) + `printDev`(17)。
新表 6 张:`base_data_interface` / `base_data_interface_oauth` / `base_data_interface_user` /
`base_data_interface_log` / `base_print_template` / `base_print_version`,`tables` 37 → 43。
🔴 **DDL 名 ≠ 实体名**(照抄官方时踩的坑):`PrintDevEntity` → **`base_print_template`**
(不是 `base_print_dev`);`PrintVersionEntity` → `base_print_version`;
`InterfaceOauthEntity` → `base_data_interface_oauth`。
- 🔴 **点权限编码三套并存**(判据都是 `base_module.f_en_code`):
`dataCenter.dataService`(数据接口)/ `integrationCenter.openApi`(接口认证)/
`onlineDev.printDev`(打印模板)。**官方没加 `@SaCheckPermission` 的那几条**
(`getList` / `GetParam` / `Preview` / `Selector` / `WorkSelector` / `getListOptions` /
`BatchData`)在本仓只要求**登录**(`require_login_face_b`)—— 与官方一致。
- 🔴 **数据接口的 `Preview` 复用数据集那套执行面**(SQL 只读 + `$N` 绑定 + 三道护栏),
官方另有 API / 静态数据两种类型 ⇒ 本仓 `400` + 人话(不假装支持)。
- 🔴 **`GetParam` 是裸数组**(官方 `ActionResult<List<DynamicForm>>`)—— 不是 `{list:[…]}`。
- 🔴 **接口认证的 `SaveUserList` 是本仓拆出来的独立端点**:官方是在 `create`/`update`
里**内联**保存用户清单(`InterfaceOauthController.java:125`),本仓为了让前端
`saveUserList` 能单独调用而拆开(等价语义,`[OFFICIAL]` 备注里写明了)。
- 🔴 **打印模板没有渲染引擎** ⇒ `Export` / `BatchData` 恒 `400` + 人话
(**不返假下载地址、不返空数据**);`Save` / `Version/*` **只存设计 JSON**。
- 🔴 **打印版本的发布语义**:`Save` 的 `type=1` 即发布 ⇒ 旧的已发布版本**归档(state=2)**、
新版本 `state=1`、模板 `state=1`;`type=0` 只存 JSON 不发布。
- 🔴 **版本删除的三道闸,顺序照抄官方**(`PrintDevController.java:332`):
① 只剩一个 ⇒ `至少保留一个版本`(官方 SYS043);
② `state=1` ⇒ `已发布版本不可删除`(SYS044);
③ `state=2` ⇒ `已归档版本不可删除`(SYS045)。
⇒ **顺序不能换**:只剩 1 个时先命中①,测不到②③(测试里专门复制出第二个版本再测)。
- 🔴 **`Selector` 是「分类节点 + 模板叶子」的树**(官方 `PrintDevTreeModel`),
且**只含 `state=1`(已发布)的模板** ⇒ 草稿模板不该出现在下拉里。
- 🔴 **版本列表 `fullName` = `打印版本V{n}`**(官方 `versionList` 逐字),
返回**裸数组**(官方 `ActionResult<List<PrintVersionListVO>>`)。
- 🔴 **复制模板要连版本一起复制**(官方 `copyPrintdev` 也复制版本);
副本名加「副本」+ 5 位 uuid 前缀,编码也换掉(撞名/撞码靠 uuid 天然避开)。
- 回归测试 `tests/batch9_it.rs`(**9 条**):数据接口双判重 + 只改名称不误判重 + 软删、
`GetParam` 裸数组 + 导出诚实失败、接口真取数 + 禁用后拒绝、接口认证判重 + `getAppId`
UUID + `interfaceSelector` 两棵树、打印建模板带首版本、`Save` 发布归档、版本删除三闸、
`Selector` 树只含已发布 + `Export`/`BatchData` 诚实失败、复制带版本。
### 🔴 本批踩到并解决的 2 个真 bug
1. **`interface_oauth_create` 的 INSERT 报 `42701 column "f_app_id" specified more than once`** ——
种子列里放了 `f_app_id`,而 `io_write_fields` 又把 body 的 `appId` 映射到同一列 ⇒
列出现两次。**修法**:`appId` 只走写字段路径(body 没给才补 uuid),不再单独塞列。
(这类「种子列 + 写字段表撞车」的坑,`data_interface_create` / `print_dev_create` 也有同款结构,
写新表时要一起检查。)
2. **`sspf-store` 的表数断言停在 37** ⇒ `cargo test --workspace` 直接红 2 条
(`schema_sql_has_expected_table_count` / `ddl_tables_parses_every_create_table`)。
🔴 **加表必须同时改三处**:`schema.sql`、`main.rs` 的 `BASE_TABLES`、
**`crates/sspf-store/src/db.rs` 的两处断言**(后者容易漏 —— 它在另一个 crate 里)。
### 批次 10(2026-11-01)—— 权限配置族(电子签章 / 按钮 / 列表 / 表单 / 高级查询)
**31 条面 B 端点**:`Signature`(7) + `ModuleButton`(7) + `ModuleColumn`(6) +
`ModuleForm`(6) + `AdvancedQuery`(5)。
新表 6 张:`base_signature` / `base_signature_user` / `base_module_button` /
`base_module_column` / `base_module_form` / `base_advanced_query_scheme`,
`tables` 43 → 49。
🔴 **点权限有两种形态,判据都是 `base_module.f_en_code`(管理员在 SQL 前短路)**:
- **OR 两码**(`guard_any`):`ModuleButton` / `ModuleColumn` / `ModuleForm` 三族官方是
`@SaCheckPermission(value={"permission.resource","appConfig.appResource"}, mode=OR)`
⇒ **满足其一**即可。
- **无点权限、只需登录**(`require_login_face_b`):`Signature` 与 `AdvancedQuery`
官方控制器**根本没加** `@SaCheckPermission` ⇒ 与官方一致,不要自作主张加权限。
🔴 **`enCode` 有「写时前缀化 / 读时剥除」的对称语义**(官方 `ModuleColumnController.java:184-195`):
- `fieldRule == 1` ⇒ 落库值 = `jnpf_` + `bindTable` + `_jnpf_` + `enCode`
- `fieldRule == 2` ⇒ 落库值 = `childTableKey` + `-` + `enCode`
- **单条路径只在「菜单存在」时套前缀**(官方判据 `moduleService.getInfo(moduleId) != null`);
**批量路径无条件套前缀**(官方批量不看菜单是否存在)—— 两条路径行为不一样,别统一。
- 读回时剥掉前缀还原成原始 `enCode`(`-` 取其后;再去 `jnpf_<bindTable>_jnpf_`)。
🔴 **官方常量**(`JnpfConst.java:170,175`):`SIDE_MARK_PRE = "jnpf_"`、
`SIDE_MARK = "_jnpf_"` —— 就是上面那个前缀的来源。
🔴 **「批量落库要么全成要么全败」是两族共有的语义**:
- `ModuleButton/selectActions`:逐条判重,**任一撞 ⇒ 整体失败且一条都不落库**;
落库时 `parentId = "-1"`(官方 `selectActions` 把 parentId 置 `"-1"` 表示根)、
`enabledMark = 1`、新 id。
- `ModuleColumn/ModuleForm` 批量创建:**批内撞码也失败**(HashSet 去重),同样一条都不落库。
🔴 **形状差异容易踩**:
- `Signature` 列表的 `userIds` 是**字符串**(多个授权人用 `;` 连接,官方 `StringJoiner`),
**详情**的 `userIds` 是**数组** —— 同一字段两种形状,别写混。
- `Signature` 的**名称与编码是两次独立判重** ⇒ 分别报「名称不能重复」「编码不能重复」。
- `Signature` 的 `userIds` 变化 ⇒ **先全删后全插**(官方 `signatureUserMapper.delete(id)` 后重建)。
- `AdvancedQuery` 的列表是 **`ListVO`(`{list:[…]}`)不是 `PageListVO`**;
且 `getList`/`getInfo`/`delete` **都按 `f_creator_user_id = 当前用户` 过滤**
⇒ 别人的方案看到的是「数据不存在」/「删除失败,数据不存在」。
但官方 `update` 是 `updateById`(**不校验归属**)⇒ 本仓同样「存在即可改」。
🔴 **官方消息码**(`MsgCode.java`)本批直接采用:
`EXIST001="名称不能重复"` / `EXIST002="编码不能重复"` / `FA001="数据不存在"` /
`FA002="更新失败,数据不存在"` / `FA003="删除失败,数据不存在"` /
`SYS050="只能输入字母、数字、点、横线和下划线,且以字母开头"`。
- 回归测试 `tests/batch10_it.rs`(**9 条**):签章判重 + `userIds` 形状、改签章重建授权人、
Selector/ListByIds/软删、按钮判重 + `selectActions` 原子性、`enCode` 前缀与剥除、
批量撞码整体失败、表单前缀与默认值、高级查询归属隔离 + ListVO、高级查询必填校验。
### 🔴 本批踩到并解决的坑
1. 🔴 **契约扫描器只认 `face_b` 这一个 mod 名**(`scripts/check-contract-scan.py:252`:
`if mod in ("jnpf", "face_b")`)⇒ 守卫的静态推导**只对内联在 `face_b.rs` 里的 handler 生效**。
本批一度想拆独立文件 `face_b_batch10.rs`,会直接让 CC6 守卫静默失效 ——
**拆文件前先读扫描器,别让「守卫没跑」变成绿灯**。
⇒ 解法:临时文件 → Python 脚本插入 `face_b.rs` 的 PRINT DEV 段之后 → 删临时文件。
2. 🔴 **`LIMIT/OFFSET` 也必须 `::text::integer`**(本仓参数一律按 text 绑定):
`LIMIT $N OFFSET $M` 会报 `protocol error: cannot convert between ... Option<String>
and the Postgres type int8` ⇒ 写成 `LIMIT ${}::text::integer OFFSET ${}::text::integer`。
3. 🔴 **`base_module_form.f_sort_code` 是 `BIGINT`** —— 抄 DDL 时手误写成 `BIGIG` 会被 PG 直接拒。
4. 🔴 **加表仍然是三处**(批次 9 已经踩过一次,这里再确认):
`schema.sql` + `main.rs` 的 `BASE_TABLES` + `crates/sspf-store/src/db.rs` 的两处断言。
本批 43 → **49**,另加 `src/backend/tests/batch6_it.rs` 与 `routes.rs` health 测试里的表数断言。
### 批次 11(2026-11-01)—— 数据权限三件套(字段 / 方案 / 数据连接)
**15 条面 B 端点**:`ModuleDataAuthorize`(6) + `ModuleDataAuthorizeScheme`(5) +
`ModuleDataAuthorizeLink`(4)。
新表 3 张:`base_module_authorize` / `base_module_scheme` / `base_module_link`,
`tables` 49 → 52。
🔴 **表名 ≠ 控制器名 ≠ 实体名**(抄官方时最容易错的一处):
控制器叫 `ModuleDataAuthorize*`,但实体 `@TableName` 是 `base_module_authorize` /
`base_module_scheme` / `base_module_link` —— **不是** `base_module_data_authorize_*`。
🔴 **点权限**:除「方案列表」外全部 OR 两码 `{"permission.resource","appConfig.appResource"}`
(`guard_any`);**方案列表只需登录**(官方 `ModuleDataAuthorizeSchemeController.java:62`
那个 `list` **没加** `@SaCheckPermission`)。
🔴 **`enCode` 前缀化是「写时加、读时剥」**(与批次 10 的 `ModuleColumn` 是**两套不同前缀**):
| 动作 | 判据 | 落库值 | 读回 |
|---|---|---|---|
| create | `module.type==3` && `fieldRule != 0` && `bindTable` 非空 | `bindTable + "." + enCode` | 剥掉 `bindTable.` 前缀 |
| update | `module.type==3` && `fieldRule == 1` && `bindTable` 非空 | `bindTable + "." + enCode` | 同上 |
- 🔴 **create 是 `!=0`、update 是 `==1`** —— 官方两处判据**不一样**,别统一成 `!=0`。
- 🔴 **delete 的方案引用比对用「原始带前缀」的 enCode**(官方
`ModuleDataAuthorizeController.java:297` 比的是 `entity.getEnCode()`,库里那个值带前缀)
⇒ 拿剥过的码去比会**失配** ⇒ 永远拦不住。
🔴 **`conditionJson` 结构是「数组 → groups 数组 → item.field」**(三层):
```
[ { "groups": [ { "field": "demo_item.f_name" } ] } ]
```
🔴 **官方消息码**(`MsgCode.java`):`EXIST001="名称不能重复"` / `EXIST002="编码不能重复"` /
`FA002="更新失败,数据不存在"` / `FA003="删除失败,数据不存在"` /
`SYS020="该字段在方案{0}中已被使用"` / `SYS021="修改失败,该方案不允许编辑"`。
🔴 **两处「诚实降级」(本仓无对应能力,不假装成功)**:
- `GET /ModuleDataAuthorize/{moduleId}/FieldList` ⇒ 官方靠 `visualdevServiceImpl` 解析
低代码表单字段 ⇒ 本仓**返回空数组**(不是 404、不是假数据)。
- `GET /ModuleDataAuthorizeLink/{linkId}/Tables/{tableName}/Fields/{menuType}/{dataType}` ⇒
官方靠 `dbTableService.getFieldList` 做**数据库内省** ⇒ 本仓**返回空 PageListVO**。
- 另:`getVisualTables` 对低代码菜单(type **3/9/11**)官方走表单解析 ⇒ 本仓返回
`{linkId:"", linkTables:[]}`;其余 type 按 `menuId + type` 查 `base_module_link`。
- 回归测试 `tests/batch11_it.rs`(**5 条**):字段 enCode 前缀化 + 剥除 + FieldList 空数组 +
condition 解码、update 前缀化 + 「更新失败,数据不存在」、delete 的 SYS020 拦截 + 软删 +
「删除失败,数据不存在」、方案双判重 + PageListVO + SYS021 + 软删、连接新建/更新 +
getVisualTables 低代码空/非低代码查表 + getInfo 命中/未命中 + 表字段空 PageListVO。
### 批次 13(2026-11-02)—— 系统数据两族(行政区划 + 公有变量)
**14 条面 B 端点**:`Area`(7) + `Variate`(7)。
新表 2 张(官方 DDL 逐字):`base_province` / `base_common_variate`,`tables` 52 → **53**;
`BASE_TABLES` 48 → **50**。
🔴 **表名 ≠ 控制器名**(批次 11 同一个坑,又踩一次):`AreaController` ⇒ `base_province`、
`CommonVariateController` ⇒ `base_common_variate`。抄之前先去官方
`database/PostgreSQL/JNPF-PostgreSQL.sql`(331 张)里 grep **实体名**,别按控制器名猜。
🔴 **`f_type` 是「层级序号」不是枚举**(`base_province`):根 = `"1"`、子 = 父 + 1,
**服务端推导**(官方 `create` 就是算出来的)⇒ body 传了**不作数**;`update` 也不改它。
🔴 **列表是「扁平 + 两个标志」,不是嵌套树**:官方 `ProvinceListVO` 带 `isLeaf` / `hasChildren`,
前端 `sysData/area` 靠标志懒加载下一层。官方算这两个标志是**逐行 `getList(id).isEmpty()`**(N+1)
⇒ 本仓用一条 `SELECT DISTINCT COALESCE(f_parent_id,'-1')` 拿全集再判,一次查询。
🔴 **`Selector` 的三条口径**(少一条前端就选错上级):
1. 只出 `f_enabled_mark = 1` 的子节点(停用的不出现);
2. `{ids}` 不是 `"0"` 时**递归排除该节点及其整棵子树**(防止把上级选成自己的下级)—— 递归 CTE;
3. 每个节点的 `isLeaf` **恒 `false`**(官方也写死,前端靠它显示「展开」箭头)。
🔴 **`GetAreaByIds` 必须按输入顺序回填**:入参 `{idsList:[[id…],[id…]]}`、出参**二维名称**
(`[[名称…],[名称…]]`)—— `IN (...)` 的返回顺序由数据库决定,直接用会乱序;查不到的 id 丢弃。
- `enCode` 判重**排除自己**(改自己没改码 ⇒ 放行);**有未删子节点 ⇒ 拒绝删除**
(`该节点存在子节点,无法删除`),叶子节点软删。
- 🔴 **Variate 族零 `@SaCheckPermission`**(官方 `CommonVariateController` 一处都没写)
⇒ 守卫只 `require_login_face_b`,**不能顺手加 `guard()`**(加了官方前端反而 403)。
- 🔴 **`type` 在 VO 里是 `String`(DB 是 `INTEGER`)** ⇒ 投影必须 `::text`,
否则前端 `=== '1'` 之类的判断全翻车。
- 🔴 **`creatorUser` 的查找条件容易写错**:本仓 `f_creator_user_id` 存的是**账号**
(裁决 S22,不是 uuid)⇒ 查找必须**同时认 `f_id` 与 `f_account`**,只认 `f_id` 会恒空串。
用**标量子查询 + `LIMIT 1`**,别写 `LEFT JOIN … OR …`(撞上会把**列表行翻倍**,分页静默错乱)。
- `Variate/sysfunccategory` 只回**分类目录**(官方 `FunctionCategory` 的 11 个固定枚举)
⇒ 不需要表达式引擎也能真实现,不是假数据。
- 🔴 **契约里 `GET /api/system/Area/{nodeId}` 写成 `{id}`**:matchit 不允许同位置两个参数名
(同批次 9 的 `Log/{id}`);`[OFFICIAL]` 保留官方 `{nodeId}`,CC10 归一后对账。
- 🔴 **CC7 重新划界**(闸门自身的改造):面 B 的钉子测试改成**直接从契约 `[ENDPOINT]` 读路径**
(`routes.rs::face_b_paths_from_contract`),删掉 255 行手抄清单 `FACE_B_REGISTERED` ——
手抄漏一行则断言**仍然全绿**(假闸门),而「加了端点没注册」正是它该抓的错。
`check-contract-scan.py` 的 CC7 相应只守面 A 的 `REGISTERED`(18 条),并加了
「`FACE_B_REGISTERED` 若回来 ⇒ 判失败」的**回归闸门**(防止手抄清单再长回来)。
- 回归测试 `tests/batch13_it.rs`(**12 条**):树建/读 + 层级序号推导 + 列表两标志、
编码判重(建撞码 / 改撞码 / 改自己放行)、有子拒删 + 叶子软删、下拉停用过滤 + 子树排除 +
`isLeaf` 恒 false、详情 `parentName` + 不存在、`GetAreaByIds` 顺序 + 空入参、
变量 `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()` 绑定** ⇒ 整型列直接类型错
(`column "f_all_data" is of type integer but expression is of type timestamp`)。
触发点:可选整型字段缺省时传了 `None`。本批改了 `f_all_data` / `f_type`,
**顺手发现批次 10 的 `f_field_rule` 有两处同样的雷**(列表权限批量 / 表单权限批量)
⇒ 一并改成「缺省按官方默认 0」。**以后写 `b10_insert` 整型列一律不许传 `None`。**
2. 🔴 **查 `int4` 列必须写 `$N::text::integer`** —— 本仓参数**一律按 text 绑定**
(`params_of` 统一 `Option<String>`)⇒ `f_type = $2` 报
`cannot convert between ... Option<String> and the Postgres type int4`。
同批的 `LIMIT/OFFSET` 已在批次 10 踩过同一个坑(那时是 int8)。
3. 🔴 **写路径要「只 SET body 里出现的键」** —— 官方是 `updateById(entity)`,
Mybatis **只 SET 实体里非 null 的字段** ⇒ body 没带的键**保持原值**。
本批补齐了 `ModuleDataAuthorize` 的 `enCode` 与 `ModuleDataAuthorizeLink` 的
`linkId`/`linkTables`/`dataType`(之前一律 SET ⇒ 会把没传的字段清空)。
4. 🔴 **批次 10 有个「跨用例污染」的假绿/假红**:`module_column_batch_rejects_duplicate_in_batch`
断言列表权限「一条都不许落库 ⇒ count == 0」,但**同一文件共用一个 pglite 临时库**、
`any_menu_id()` 对每个测试都返回**同一个**菜单 ⇒ 别的测试已建过 2 行 ⇒ 必然红。
已改成**基线相对**(`before` → `before + 2`)。**教训:共用库的测试不要写死绝对条数。**
5. 🔴 **裸 `exec_params` 绑整型会炸** —— pglite-rs 按 `&str` 推断参数类型,
绑 `int4` 列要写成 `$N::text::integer`;测试里插行**优先走端点**(顺带覆盖了端点)。
### 🔴 上一批(第一批)踩到并解决的 4 个真 bug
1. `CurrentUser` 的 `preferenceJson` 必须是**字符串** `"{}"` —— 给对象会让前端
`handleUpdatePreferences` 抛异常 ⇒ 登录后立刻跳 Logout(表现为「登录无效原地打转」)。
2. 菜单 `urlAddress` 走的是**面 B 路径** `permission/user`,不是面 A 的 `system/User` ⇒
之前直接访问 `/system/User` 必然 404。
3. `Users` 列表的 `keyword` 压根没进 SQL(搜索框形同虚设)⇒ 已补三列 ILIKE。
4. 空关键词时把 `like` 塞进参数数组 ⇒ PG 报「bind supplies 1 params, statement requires 0」
⇒ **必须** `if keyword.is_empty() { Vec::new() }`。
---
### 批次 16(2026-11-02)—— 权限关系族(角色绑定 / 在线用户 / 自定义范围 / 工作详情 / 第三方账号 / 导入导出)
**26 条面 B 端点**(均未新增表,复用 `base_user`/`base_organize`/`base_position`/`base_role_relation`):
`RoleRelation`(2) + `OnlineUser`(3) + `Group/GroupCondition` + `Organize/SelectedList` +
`Organize/OrganizeCondition` + `Users/getWorkByUser` + `socials`(2) +
三实体(`Users`/`Organize`/`Position`)× `TemplateDownload`/`ImportPreview`/`ImportData`/`ExportData`/`ExportExceptionData`(15)。
🔴 **四条判据(沿用批次 14/15 的「能力不存在 ⇒ 明确失败」)**:
1. **`f_object_type` 必须全小写 `user`/`organize`/`position`**(官方 `PermissionConst` 逐字):
`role_relation_list` 与 `role_relation_add` 都按小写写库;授权引擎 `permission.rs` 只认小写。
**写成首字母大写会让绑定「成功但权限永不生效」**(静默失效)—— 这是本轮抓到的真 bug,已修 + 测试钉死。
2. **在线用户 `userId` 是会话指纹 `md5(token)`,绝不外泄真 token**(官方把 Sa-Token 的 token 当
id 直接返回 ⇒ 管理员能拿到所有人凭据):删除按指纹精确踢人;`loginAddress` 恒空(无归属地库)。
3. **`Organize/SelectedList` 的 id 形如 `<组织id>--<后缀>`,原样带回且按入参顺序**;
`Organize/OrganizeCondition` 遇 `$`/`@` 数据接口变量**明确失败**(本仓未建模)。
4. **导入导出 15 条 = 3 条真落库(`Users/ImportData` 的 `type=false`:`type=true` 按文件服务读 Excel ⇒ 拒绝)
+ 12 条文件服务缺失一律拒**(尤其不返 `data:null`,否则前端 `downloadByUrl(undefined)` 崩)。
`socials` 两条也是明确失败(本仓无第三方登录配置,返空数组会让页面显示「没有可绑定的平台」= 撒谎)。
🔴 **角色绑定逐条对齐官方 `RoleRelationServiceImpl.roleAddObjectIds`**:空 ids / 角色不存在 /
停用用户过滤 / 已绑跳过 / **超管不能添加** / 三态返回(部分成功)/ 绑完把用户踢下线。
🔴 **`getWorkByUser`**:`flow`/`flowTask` 恒空(无工作流引擎),`app` 真查(复用 `SYSTEM_LIST_PROJECTION` /
`load_system_tops` / `shape_system_list_item`),`isAppShow` 跟随。
🔴 **回归测试 `tests/batch16_it.rs`(10 条)**:覆盖小写 `f_object_type`、三态返回、超管拒加、踢下线、
指纹非 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. 运行中的现场(断了就按这里重启)
### 后端(端口 30000)
```bash
cd ~/Desktop/workspace/ssw-platform
RUSTC_WRAPPER=sccache cargo build --manifest-path src/backend/Cargo.toml # 改代码后
# 🔴 **尺子跑的是 release 产物** ⇒ 跑尺子前必须 `cargo build --release`
RUSTC_WRAPPER=sccache cargo build --release --manifest-path src/backend/Cargo.toml
nohup env PORT=30000 ./target/debug/ssw-platform > /tmp/ssw-backend.log 2>&1 & # 后台起
curl -s http://127.0.0.1:30000/api/health # 期望 {"ok":true,"tables":43,...}
```
拿 token(面 B):
```bash
ENC=$(./target/debug/ssw-platform --enc 123456)
curl -s -X POST http://127.0.0.1:30000/api/oauth/Login \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Vue-Version: 3' -H 'App-Code: mainSystem' \
--data-urlencode account=admin --data-urlencode "password=$ENC"
# → data.token(lite- 前缀)。Authorization 头是**裸 token,没有 bearer 前缀**
```
### 前端(`~/Desktop/workspace/jnpf/7.0/frontend/web/jnpf-web-monorepo-framework`)
🔴 **必须 `env -u NODE_OPTIONS`**:否则被 brokered-fs shim 逐次拦截(0.15 包/s,末尾
`ERR_PNPM_CODEBUDDY_BROKER_DENY` / `CODEBUDDY_BROKER_OUTCOME_UNKNOWN`)。依赖**已经装好**,
下面第 1 步只在坏了时重跑。
```bash
cd ~/Desktop/workspace/jnpf/7.0/frontend/web/jnpf-web-monorepo-framework
env -u NODE_OPTIONS pnpm install --prefer-offline --reporter=append-only # 断了才需要重跑,约 47s
pnpm -r run stub --if-present # 已由 postinstall 跑过
env -u NODE_OPTIONS nohup pnpm dev:main > /tmp/vite-main.log 2>&1 & # vite, 3000, /dev → 30000
```
- 成功标志:`node_modules/.modules.yaml` 存在(✅ 已存在)、vite 打印 `ready in ~7s`
- 打开 `http://localhost:3000/`(根路径 App-Code 为空 ⇒ 后端回退主系统,已支持)
- 登录:`admin` / `123456`(登录框自己加密,不要手填密文)
⚠️ **后台进程会随 turn 结束被回收**(`run_in_background` 起的东西在回复完就没了)。
🔴 **2026-10-31 实测修正**:`run_in_background` **不可靠**(上下文压缩那一轮 vite 就被回收了,
日志里明明 `ready in 5188ms`)。用 **`nohup ... &`** 起,实测能跨 turn 存活:
```bash
# 前端
cd ~/Desktop/workspace/jnpf/7.0/frontend/web/jnpf-web-monorepo-framework
env -u NODE_OPTIONS nohup pnpm dev:main > /tmp/vite-main.log 2>&1 &
# 后端
cd ~/Desktop/workspace/ssw-platform
nohup env PORT=30000 ./target/debug/ssw-platform > /tmp/ssw-backend.log 2>&1 &
```
两个都起好后,浏览器会话 `aix --session ssw` 可以直接复用(登录态在 localStorage)。
⚠️ **后端一重启,token 就失效**(session 是进程内内存表)⇒ 每轮开工必须重新登录拿 token。
### 代码仓库(本机 Gitea)
```bash
cd ~/Desktop/workspace/ssw-platform
git status -sb # main...origin/main,工作区应干净
# 推送(凭据只在 xop 注入的环境里存在,脚本不落盘)
xop run --secret GU=git_local_user --secret GP=git_local_pass -- bash -c '
export GIT_ASKPASS=/tmp/askpass-ssw.sh GIT_TERMINAL_PROMPT=0
git -c http.proxy= -c https.proxy= push origin main' < /dev/null
```
- 远端:`http://127.0.0.1:13300/ssw/ssw-platform.git`(Gitea 1.26.1,私有,默认分支 main)
- `ssw` 是**用户命名空间**不是组织(`/api/v1/orgs/ssw` 返 404),建仓用 `POST /api/v1/user/repos`
- `/tmp/askpass-ssw.sh` 若不存在,重建:`case "$1" in *[Uu]sername*) echo "$GU";; *) echo "$GP";; esac`
- 🔴 xop 会把输出里等于密钥值的串打码(`ssw` → `ss****【xop禁止将密钥泄漏】`),日志别扭但无害
- 每批做完建议 `git add -A && git commit`(一晚上至少留一个可回滚点)
---
## 3. 待办(按优先级,做完一条划一条)
### ~~P0 —— 用户管理页剩余接口~~ ✅ **2026-10-31 全部做完**
| 端点 | 状态 |
|---|---|
| `GET /api/permission/Group` | ✅ 左侧分组树(ListVO)。**表是官方 `base_group`**(不是 `base_user_group`,官方 DDL `JNPF-PostgreSQL.sql:1758` 只有 `base_group`) |
| `GET/POST/PUT/DELETE /api/permission/Group/{id}` | ✅ CRUD 全通,端到端实测(建→详情→改→加成员→移出→删) |
| `POST /api/permission/Group/{id}/Actions/AddUser` / `DeleteUser` | ✅ 走 `base_user_relation`(f_object_type='Group'),幂等插 |
| `POST /api/permission/Users/{id}/SetPosition` + `/SetPositionBatch` | ✅ 405 已修(单独注册 `/Users/SetPositionBatch`) |
| `GET /api/permission/Users/{id}/SelectorByUserPosId` | ✅ |
| `GET /api/system/System/getDevUser` | ✅ |
| `DELETE /api/permission/socials/{id}` | ✅ 本仓无 `base_socials_users` ⇒ 恒成功 |
| `POST /api/permission/Users/workHandover` | ✅ 置 `f_handover_mark=1` |
**另外顺手补了 5 条页面级 404**(都是「不补就弹红条」的):
`GET /api/system/DictionaryData/All`(恒 `{list:[]}`,**不能是裸数组**)、
`GET /api/system/HomeData`(恒 `[]`,前端读 `res.data.length`)、
`POST /api/system/MenuData/useModuleNum/{id}`(恒成功)、
`GET /api/oauth/getLoginConfig` + `getConfig/{account}`(**登录前调用 ⇒ 无守卫**,恒 `{}`)。
### ~~P1 —— 让页面真跑起来~~ ✅ **2026-10-31 达成**
可复现步骤(实测有效):
1. `nohup` 起后端 + vite(命令见 §2)
2. `aix open "http://localhost:3000/login" --session ssw` → `aix snapshot` 拿 `@eN`
→ fill 账号/密码 → click 登录 → 约 9s 后落到 `/home`
3. `aix open "http://localhost:3000/permission/user"` ⇒ 期望:左侧「全部用户」+ 分组节点,
右侧表格有 admin 行,零报错
4. 零非 200 的查法(比看控制台准):进页面前先注入 fetch/XHR 双钩子收集 `window.__net`,
再 filter `x[0]!==200`。**控制台看不到 404 的 details 时就用这招**
### ~~P2 —— 机构管理 `Organize` CRUD + `Selector`~~ ✅ **2026-10-31 做完**
`GET/POST /api/permission/Organize`、`GET/PUT/DELETE /api/permission/Organize/{id}`、
`GET /api/permission/Organize/Selector` 共 6 条。
端到端实测:建父 → 建子(`organizeIdTree` = 父树+自己,`orgNameTree` 同理)→ 详情 →
改(只发 `fullName`,`enCode` 不动)→ Selector 2 行 → 删 → 剩 0 行。
⚠️ 删机构**不级联**(只软删本行)⇒ 已记为已知限制 `(ak)`。
### ~~P3 —— 菜单管理 / 角色授权~~ ✅ **2026-10-31 05:00 做完**
| 批次 | 端点 | 备注 |
|---|---|---|
| 岗位 `Position` | 12 条 | 新表 `base_position`(官方 23 列逐字)。CRUD + Selector/SelectorTree/Condition/SelectedList/DutyPosition/DutyUser |
| 角色 `Role` | 6 条 | `base_role` 已有。CRUD + Selector + RoleCondition |
| 菜单 `Menu` | 13 条 | `base_module` 已有。CRUD + 四种 Selector + Export/权限组 |
| 字典 `DictionaryType`/`Data` | 14 条 | 新表 2 张。分类 CRUD + 数据 CRUD + 两种下拉 |
| 用户选人 / 授权 / 关系 | 16 条 | `Users/Selector`、`getUserList`、`getSelected*`、`getAllPermission`、`Authorize`、`Authority/{kind}/{id}`、`RoleRelation/*`、`UserRelation/*` |
### P4 —— 剩下的(按 §0-bis 的全景表,从上往下做)
1. ~~`permission/Users/Current/*` 个人设置 14 条(BaseInfo/改密码/主题/语言/头像/签名/saas)~~
✅ **批次 1 做完(实际 23 条)**——新表 `base_user_extra` / `base_sign_img`
2. ~~`permission/Standing`(6) / `PermissionGroup`(6) / `Action`(3)~~
✅ **批次 2 做完(实际 21 条)**——新表 `base_standing` / `base_permission_group` / `base_action`
3. ~~`system/System`(11) + `system/SysConfig`(6) 系统配置页~~ ← **下一个**
✅ **批次 3 做完(实际 31 条,含 Tag)**——新表 `base_system_top` / `base_sys_config`;
应用中心 CRUD + 置顶 + 应用授权 + 系统参数/第三方配置键值表 + 管理员设置 + 同步统计。
4. ~~`message`(53) 里的 `api/system/message.ts` 那 14 条~~
✅ **批次 4 做完(实际 19 条,含 BusinessCategory)**——新表 `base_business_category` /
`base_message` / `base_notice`。`api/msgCenter/*`(36 条运维后台)仍未定。
5. ~~`system/Log`(5) + `system/CommonWords`(6) + `system/BillRule`(8)~~
✅ **批次 5 做完(实际 21 条)**——新表 `base_sys_log` / `base_common_words` / `base_bill_rule`;
登录落日志 + 常用语 CRUD + 单据规则与单号生成器。
6. ~~`DataModel/{}/Tables`(12 页共用) + `DataSource` + `BasicDataType` + `CommonFields`~~
✅ **批次 6 做完(实际 16 条)**——新表 `base_db_link` / `base_data_type` / `base_common_fields`;
数据建模**只读面**(表清单/字段/预览)+ 数据连接 CRUD。**写面(真 DDL)留给批次 7**。
7. ~~`DataModel` 写面 8 条(`CREATE/ALTER/DROP TABLE` + `addFields` + `Copy` + `Export`/`Import`)~~
✅ **批次 7 做完(实际 8 条)**——真 DDL + 两道护栏(`db_ident` + `ddl_tables` 内置表清单)
+ 官方 `checkTab` 的「内置表 / 有数据」双闸。数据建模三页现在**真能用**。
8. ~~`systemData` 的 `Dataset`(16)~~ ✅ **批次 8 做完(实际 18 条)**——新表
`base_data_set` / `base_data_set_relation`;CRUD + 设计器 `get`/`save` + 六条取数
(`Preview`/`List`/`InfoByIds`/`getRes`/`previewSql`/`fields`)+ 下拉 + 恒失败的导出导入。
**真执行 SQL**,三道护栏 + `${xxx}`/`@xxx` 全绑定。
9. ~~`DataInterface`(12) + `InterfaceOauth`(11) + `system/printDev`(17)~~
✅ **批次 9 做完(实际 39 条)**——新表 6 张(`base_data_interface` /
`base_data_interface_oauth` / `base_data_interface_user` / `base_data_interface_log` /
`base_print_template` / `base_print_version`);数据接口**复用数据集执行面真取数**、
接口认证 CRUD + 用户清单、打印模板模板/版本两套 CRUD + 发布归档语义。
🔴 打印**无渲染引擎** ⇒ `Export`/`BatchData` 恒 `400` + 人话。
10. ~~权限配置族 `Signature`(7) + `ModuleButton`(7) + `ModuleColumn`(6) +
`ModuleForm`(6) + `AdvancedQuery`(5)~~
✅ **批次 10 做完(实际 31 条)**——新表 6 张(`base_signature` / `base_signature_user` /
`base_module_button` / `base_module_column` / `base_module_form` /
`base_advanced_query_scheme`);电子签章 + 按钮/列表/表单权限 + 高级查询方案。
🔴 **OR 两码点权限**(`permission.resource` | `appConfig.appResource`);
`Signature`/`AdvancedQuery` 官方无点权限 ⇒ 只需登录。
🔴 `enCode` **写时前缀化 / 读时剥除**(单条按「菜单存在」,批量无条件)。
11. ~~数据权限三件套 `ModuleDataAuthorize`(6) + `ModuleDataAuthorizeScheme`(5) +
`ModuleDataAuthorizeLink`(4)~~
✅ **批次 11 做完(实际 15 条)**——新表 3 张(`base_module_authorize` /
`base_module_scheme` / `base_module_link`);数据权限字段 + 方案(双判重 / SYS021 /
引用校验 SYS020)+ 数据连接。
🔴 表名 ≠ 控制器名(`ModuleDataAuthorize*` ⇒ `base_module_authorize` 等)。
🔴 `enCode` 前缀化用 **`bindTable + "."`**(与批次 10 的 `jnpf_<bind>_jnpf_` 是**两套**);
**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`)。
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(下一轮优先做)—— 「框架固定包 + 业务模块链接就好」
> **这一批不是补端点,是改「加业务的成本结构」。** 目标形态:
> **平台层(面 A/B 契约 + 权限 + 低代码 + MCP)打成一块相对固定的底座**,
> **新业务模块只写 spec + 一行注册**,不碰平台层、不重复拷贝、不手抄 DDL、不手抄契约表。
> 完成后「加一个业务模块」从现在的**改 6~8 处**降到**写 1 个文件 + 改 2 处**。
🔴 **本批必须同时满足两个目标(2026-11-01 19:39 追加)**:
**MVP 阶段**(Rust 技能,AI 怎么快怎么来)**要快** ⇒ 上面四项交付物;
**集成阶段**(迁标准 JNPF,规范开发)**不能欠债** ⇒ 每项交付物都要**留下可还债的痕迹**。
⇒ **判据不是「这批做完没」,是「集成时要还的债有没有变少」。**
本批**直接消灭的债**:那 **27 条 `partial`** 里,属于「自造」的 **4 条**会随 ①③ 的重构消失
(`f_en_code` 自定占位 → 改官方编码;`deleteAllTable` 收窄 → 改官方语义)。
#### 现状体检(2026-11-01 19:00 实测,勿凭印象改)
| 事实 | 证据 | 影响 |
|---|---|---|
| 业务 spec **有两份逐字拷贝** | `src/backend/src/modules/asset.rs`(178 行)vs `packs/asset/src/lib.rs` | 改一处忘另一处 ⇒ **静默**不一致 |
| 两份拷贝**没有比对闸门** | `check-arch.sh` 只有 AR1–AR7 + MEM1–MEM2,**没有 PACK1** | `packs/asset/src/lib.rs` 注释里写的「PACK1 会比对(P3 加)」**至今没加** |
| `packs/asset` **根本没被内核装载** | `routes.rs` 只 `merge` 了 `modules::router()`(1 处 merge);`sspf-sdk` 的 `BusinessPack` **没有 `routes()` 方法**(只有 manifest/entities/menus/metadata/hooks) | 业务包是**死的**样板,`PLAN.md` §4.4 写的 `routes()` 未实现 |
| 契约扫描器**只扫 `modules/*.rs`** | `check-contract-scan.py:369` 只遍历 `src/backend/src/modules/`(除 `mod.rs`) | 业务包若搬到 `packs/`,路由**不在扫描范围** ⇒ CC2/CC3 判「契约多 / 代码少」⇒ **假漂移** |
| 静态闸门**最慢 66.6s** | 实测 `check-contract.sh` 66.6s(静态解析 659 个路由);`check-module` 25.8s | 每次改代码都等 ⇒ 「快速验证」体感差 |
| 运行时尺子**都很快** | `perm-smoke` 6.0s / `perm-smoke-jnpf` 4.8s / `lowcode` 1.9s / `baseline` 3.3s / `mcp` 2.9s | **「快验证」的成本在静态闸门,不在运行时** |
| 业务 DDL 要**手抄进 schema.sql** | `schema.sql:879/888/897/920` 四张业务表 | 加一张表要改 schema.sql + `main.rs` BASE_TABLES + `sspf-store/db.rs` **两处**断言(批次 9/10 各踩一次) |
| 业务表数**写死 52** | `crates/sspf-store/src/db.rs:1226,1233` | 加表必红 ⇒ 又一处「记得改」 |
#### 本批交付物(4 件事,按依赖顺序做)
**① `sspf-sdk` 补 `routes()` + `crates/sspf-plugin`(L2 静态装载器)**
- `BusinessPack` 加 `fn routes(&self) -> &'static [PackRoute]`(**默认空** ⇒ 纯元数据包 L0 仍零改动)。
`PackRoute` = `{ method, path, entity }` —— **不是 axum Handler**,只是**声明**。
🔴 **理由**:业务包不许依赖 axum(AR2 钉死)⇒ 路由**声明**在 sdk(纯数据),
**注册**在内核(唯一认识 axum 的地方)。这与 `EntitySpec` 已是同一模式。
- `crates/sspf-plugin`(新 crate,依赖 ⊆ {sspf-sdk, sspf-contract, serde, serde_json}):
扫 `packs/*/pack.toml` ⇒ 读清单 ⇒ 校验 `kernel_req` 区间 ⇒ 收集 entities/menus/routes。
🔴 **AR8 新增**:本 crate 依赖 ⊆ {sspf-sdk, sspf-contract, serde, serde_json}(不许碰 axum/tokio/pglite)。
- 内核接线:**只改 `bootstrap.rs` 一处** —— 平台层 `crud.rs` 补一个
`crud_router(spec) -> Router<AppState>`(把现有 `handle_list/save/delete` 包成 3 条路由),
业务包给出 `routes()` ⇒ 插件层按 `{method, path, entity}` 查 spec ⇒ 生成路由 ⇒ merge。
⇒ **业务包自带路由,平台层零改动**(这才是「链接就好」的含义)。
- 🔴🔴 **【集成期友好性】包声明的路由路径必须从第一天就用「官方形状」,不许用面 A 的 `/api/ssw/...`**:
- 面 A(`/api/ssw/{appCode}/{Entity}/{List|Save|Delete}`)是**本仓自造**的 ssw 约定
⇒ **集成到官方 JNPF 时全部作废**(官方路径见 `MIGRATION.md` §2.3)。
- 面 B(官方 JNPF 的 `/api/{模块}/{资源}/...`)才是能直接搬的形状。
- ⇒ **业务包默认只声明面 B 形状的路由**;面 A 那套**留给 Rust 终端场景**(保留在 `modules/` 里不动)。
- ⇒ **验收**:新加的包,`pack.toml` 里的路径在官方 `JNPF-PostgreSQL.sql` 对应的 Controller 里
**能一一对上**(用 `MIGRATION.md` §2.1 的逐件翻译表反查)。
**② 打通「两份拷贝」⇒ 单一真源 + `PACK1` 闸门**
- `modules/asset.rs` 的 spec **改为从 `packs/asset` re-export**(`pub use sspf_pack_asset::DATA_RESOURCE_SPEC;`)
⇒ **只留一份**。内核 `Cargo.toml` 加 `sspf-pack-asset = { path = "../../packs/asset" }`。
- 🔴 **AR2 会因此破**(`packs/*` 只能依赖 sdk/serde;内核依赖 packs 是**反向**,不违反 AR2)⇒
需给 `check-arch.sh` 加 **AR9**:内核**只允许**依赖 `packs/<app>` 这类业务包,且**不得**在
平台层(`platform/`)出现 `use sspf_pack_*` ⇒ 业务知识不许漏进平台层。
- **PACK1 闸门**(新增,`check-arch.sh`):`packs/<app>/src/lib.rs` 声明的 entities/menus
与 `modules/<app>.rs` 声明的**逐字一致** ⇒ 不一致就红。有了 re-export,这道闸变成
「**模块文件只允许 re-export,不许自己写 spec**」的形状检查。
**③ 业务 DDL 跟着包走 ⇒ 不再手抄 `schema.sql`**
- 每个包带 `schema/*.sql`(`pack.toml` 的 `[[pack.tables]].ddl` 已预留这个字段);内核启动时
**按包顺序**执行 + 幂等(`CREATE TABLE IF NOT EXISTS`)。
- 🔴 **`sspf-store` 的两处表数断言必须改成「不写死」**(`db.rs:1226,1233`)——
写死 52 是批次 9/10 各踩一次的坑,改成「base 表数写死 + 业务表数 ≥ N」或直接读 `ddl_tables()` 对账。
- 🔴 **`is_builtin_table`(`platform/compat/system.rs:5879`)取 `ddl_tables()`** ⇒ 业务包建的表会**自动变成内置表**
⇒ 数据建模页**看不到**用户自己建的表了。这条要**重新想**(本批至少要保证行为不回退)。
- 🔴 `main.rs::whitelist_self_check` 的**双向对账**(孤儿 DDL / 漏建表)要改成
「DDL = base 表 + **所有包**的表」,否则包表会被判成孤儿 DDL ⇒ 启动失败。
- 🔴🔴 **【集成期友好性】包的 DDL 必须按官方规范写,集成时才能「只导数据」**:
- 列名照官方习惯:`f_` 前缀 + `f_id VARCHAR(50)`(36 位 UUID)+ `f_delete_mark INTEGER DEFAULT 0`
+ **`f_tenant_id VARCHAR(50) NOT NULL`**(值恒 `"0"`,**参与复合主键 `(f_id, f_tenant_id)`** ——
单租户也不许省,见 CLAUDE.md 红线 12)。
- **业务表的 `f_` 列不许自创语义**(如把金额叫 `f_money` 而官方叫 `f_price`)⇒ 集成时列名映射是纯人工活。
- 🔴 **包的 `pack.toml` 要补 `baseline_table`**(`[[pack.tables]]` 已有该字段)⇒ 集成时表名不同可自动映射,
不靠人记。
- **验收**:拿一个包,把它的 `schema/*.sql` 对着官方 `JNPF-PostgreSQL.sql` 的同名表逐列比,
差异只允许出现在「官方没有这个业务表」这一项上(业务表本就要新建,但**列的形状**要对齐官方同类表)。
**④ 契约登记自动化 + 让静态闸门变快**
- 契约表 `docs/contract.md` 附录 A 的 `[MODULE]` / `[MENU]` / `[ENDPOINT]` 三段,
现在**手写** ⇒ 加包必须手抄三处。⇒ 改成**从包生成**:`scripts/pack-sync.py`
读 `packs/*/pack.toml` + `src/lib.rs` ⇒ 追加到 contract.md 附录 A(幂等)。
🔴 **不要手改生成段**(否则下次同步被覆盖)⇒ 生成段用 `<!-- PACK:BEGIN -->` / `<!-- PACK:END -->` 包起来。
- 🔴 **扫描器要认识 `packs/`**:CC2/CC3 现在只扫 `modules/*.rs` ⇒ 业务包搬走后会判假漂移。
⇒ `check-contract-scan.py` 改成扫 `packs/*/src/lib.rs` + `modules/*.rs` **两处**。
- **提速**(`check-contract.sh` 66.6s 是瓶颈):扫描器目前每次全量解析 659 个路由。
⇒ 加**增量**:按文件 mtime 缓存解析结果(`scripts/.scan-cache.json`)⇒ 改一个文件只重扫一个。
目标:**改一个模块后静态闸门总耗时 ≤ 15s**(现状 ~110s)。
- 🔴 **「快速验证」的新命令**:`bash scripts/verify.sh` —— 一条命令跑完
`build → 静态闸门 → 单测 → 尺子`,末尾打印**总耗时**与**哪道最慢**(Top 3)。
这是「快速打包 / 快速验证」的**用户可见入口**。
- 🔴🔴 **【集成期友好性】前端触点也要进闸门**(现在前端**完全没有保护**,见 §0-ter):
- 🔴 **本批的前端 = React 模板**(`ssw-jnpf-lite-rust` 的 `src/frontend`,与 React 技能**逐字节相同**)
⇒ **本仓要把 `src/frontend` 建起来**(当前是空的,CLAUDE.md §2.2 写的是「后端-only」——
🔴 **这条要改**:新路线下前端在 MVP 阶段就有,且**必须**是 React 模板)。
- ⇒ **本批产出 `scripts/new-page.sh <app> <Entity>`**:生成 **React 三件套**:
`src/frontend/src/api/<lc>.ts`(3 个 export)+ `src/frontend/src/views/<Ent>.tsx`(列表+弹窗表单+删除确认)
+ `src/frontend/src/App.tsx` 的 `<Route path="/<app>/<Entity>" />` 一行
+ 提醒菜单登记(`urlAddress` == Route path 去前导斜杠 == `guardModule` 的 key,**三处一字不差**)。
⇒ 模板直接抄 React 技能的 `views/DemoItem.tsx`(101 行,含弹窗表单)+ `api/product.ts`(7 行)。
- ⇒ **前端闸门**:把 React 技能的 `scripts/check-module.sh`(11 KB,**9 个接触点**,
支持 `--all` 自动探测 / `--live` 实跑后端)**移植**过来 ⇒ 前端 4 个接触点**从 `⏭` 变成真检查**。
🔴 **移植时只改后端路径**(React 技能指 NestJS `src/backend/src/` ⇒ 本仓指 Rust `src/backend/src/`),
**前端路径零改**(`src/frontend/src/...` 两边同名)。
- 🔴 **集成期才做官方 Vue 那一套**:`views/<模块>/index.vue` + `api/<模块>.ts`
+ `router/routes/modules/<模块>.ts`(官方 `import.meta.glob` **放文件即注册,不用改配置**)。
⇒ **本批不做**(明确不做清单里),集成期再写 `new-page.sh --vue` 或另一个脚本。
- ⚠️ **不要现在就把官方 monorepo 的路径写进脚本**:`jnpf-web-monorepo-framework`(7.0 前端框架)
与 `jnpf-web-apps-main`(官方应用)是**两个目录**,实际业务代码在**后者**
(`~/Desktop/workspace/jnpf/jnpf-web-apps-main`,其 `src/api/request.ts` = `defHttp` 定义处)。
⇒ 集成期做 `--fe-root` 时要指对目录。
#### 本批护栏(缺一不可)
| # | 护栏 | 落地位置 |
|---|---|---|
| 1 | 业务包**不许依赖 axum/tokio/pglite** | AR2(已有)+ 新 AR8 |
| 2 | 平台层**不许出现业务包**(业务知识隔离) | 新 AR9 |
| 3 | spec **单一真源**(不许两份拷贝) | PACK1 + re-export 改造 |
| 4 | 路由**声明**在 sdk、**注册**在内核 | `PackRoute` + `bootstrap.rs` |
| 5 | 包表数**不许写死** | `sspf-store/db.rs` 两处断言 |
| 6 | 包 DDL 幂等 + 不许碰 `base_*` | 内核执行时过滤 `base_` 前缀 |
| 7 | 契约登记**生成**而非手写 | `pack-sync.py` + BEGIN/END 标记 |
| 8 | 🔴 **包的路由路径只许官方形状**(面 B),**不许面 A** | `pack-sync.py` 校验 + 评审 |
| 9 | 🔴 **业务表 DDL 列名不许自造语义**,必带 `f_tenant_id` | `new-pack.sh` 模板 + 评审 |
| 10 | 🔴 **前端三处一字不差**(`urlAddress` == `guardModule` key == Route path) | `new-page.sh` + 移植的 `check-module.sh` |
#### 验收判据(做完必须全绿才算完成)
```bash
# 1) 新建一个空业务包,只写 spec,不碰任何平台层文件 ⇒ 全链路自动通
bash scripts/new-pack.sh ledger Ledger # 脚手架:生成 packs/ledger/{Cargo.toml,pack.toml,src/lib.rs,schema/001_init.sql}
# 2) 十二道闸门全绿 + 单测不减少
bash scripts/verify.sh # 新命令:build → 静态闸门 → 单测 → 尺子,打印耗时
# 3) 业务包可独立构建(不依赖内核)
cargo test -p sspf-pack-asset
# 4) 「加包不碰平台层」有钉子测试:git diff --name-only 只应出现 packs/<app>/ + 契约生成段
# 5) 加包后**没有手抄**痕迹:contract.md 的 [MODULE]/[ENDPOINT] 段是生成物
# 6) 🔴【集成期友好性】包的路径/列名能被官方侧对上(详见下面「集成期 checklist」)
```
#### 🔴🔴 集成期 checklist(不是本批做,是**现在就要能回答**的问题)
> 这张表的用途:**MVP 阶段每加一个业务包,就顺手填一遍** ⇒ 集成期不返工。
> 填不完的**当场就还债**(宁可现在多写 20 分钟,别集成时返工一天)。
| 检查项 | 怎么答 | MVP 期成本 | 不做的后果 |
|---|---|---|---|
| 包的端点在官方是**哪个 Controller 哪个方法**? | 用 `MIGRATION.md` §2.1 翻译表反查官方 Java 源码(本机 `~/Desktop/workspace/jnpf/jnpf-java-boot`) | 查 5 分钟 | 🔴 集成时**路径全要改** |
| 业务表的列名官方叫什么? | 对着官方 `JNPF-PostgreSQL.sql` 的同类表比 | 查 10 分钟 | 🔴 集成时**列名映射全靠人工** |
| 这个表的 `baseline_table` 叫什么? | 填进 `pack.toml` 的 `[[pack.tables]]` | 1 分钟 | 🔴 集成时记不住 |
| 业务表的 `f_tenant_id` 带了没? | 看 `schema/*.sql` | 0(模板自带) | 🔴 **复合主键缺列 ⇒ 导不进官方** |
| 这个业务要不要**按钮级/列级权限**? | 官方 `@SaCheckPermission` 的判据是什么 | 想 10 分钟 | 🔴 集成时**权限体系要重做** |
| 返回的 VO 形状官方长什么样? | 对着官方 `XxxListVO` / `XxxInfoVO` 抄字段清单 | 抄 10 分钟 | 🔴 集成时**前端读不到字段 ⇒ 静默降级** |
| 涉及文件上传/导出吗? | 是 ⇒ 记下来(官方走 `jnpf-file` 服务) | 标记 1 分钟 | 🔴 集成时**功能缺失** |
| 前端页面要接的接口清单 | `api/<模块>.ts` 里逐个列 | 已有 | 🔴 集成时**前端要返工** |
🔴 **一条经验**:上面 8 项里,**后 4 项(权限 / VO 形状 / 文件 / 接口清单)就是那 27 条 `partial`
里「形状欠」那 9 条 + 「自造」4 条的来源** ⇒ **在 MVP 阶段就把 VO 字段清单抄全**,
是整个两阶段路线里**性价比最高**的一件事(抄一次,省掉集成期逐条 debug)。
#### 明确不做(本批不碰,别偷跑)
- ❌ **L3 dylib 动态库**(`PLAN.md` §4.5):六条铁律(内存所有权 / catch_unwind / ABI 校验 / 热替换…)
是**另一个量级**的工作力,本批**只做 L2 静态链接**。
🔴 理由:PLAN.md §4.6 写得很清楚 ——「L2 是静态链接(编 30s),L3 才是运行期 dlopen」;
「不要对外承诺什么都能热更」。先把「链接就好」在 **L2** 做到真,再谈 L3。
- ❌ **WASM 执行器**(PLAN.md P3 交付项之一):低代码沙箱已有 Rhai,WASM 是第二实现,不急。
- ❌ **`pack export/import --format=baseline`**(双向迁移):属于 P3 的后一半,本批只做「包内声明 → 内核装载」这一半。
🔴 **但 `pack.toml` 的字段(`baseline_table` / `[[pack.tables]].ddl`)要按最终格式设计好**
⇒ 集成期做 export/import 时**不用改包格式**。
- ❌ **官方 Vue 前端的页面脚手架**(`views/<模块>/index.vue` + `api/<模块>.ts`
+ `router/routes/modules/<模块>.ts`)—— 那是**集成阶段**的事。
⇒ 本批只做 **React 三件套** 的 `new-page.sh` + 移植 React 技能的 `check-module.sh`。
⇒ 🔴 **不改官方 monorepo / 官方应用的任何文件**(`jnpf-web-apps-main`),那是集成期的事。
#### 🔴 前端在两阶段分别怎么办(2026-11-01 19:39 修正 → 20:10 按 React 模板再修正)
> ⚠️ **19:39 这一版仍然写错了**:当时说「前端**全程**都在官方 monorepo 里,两阶段的差别不在有没有前端,
> 而在前端的代码规范等级」。
> **20:10 用户纠正**:「你看看 `ssw-jnpf-lite-react` 的模版,这个就是前端 MVP 阶段 AI 友好的方向,
> **除了认证,其它都留给集成阶段**」。
> ⇒ **MVP 前端 = React 模板**(不是官方 vue);**官方 vue 是集成阶段的事**。
> ⚠️ **两次都写错同一个点** ⇒ 这条在下一轮开工时**先复核再动手**。
| | MVP 阶段(AI 怎么快怎么来) | 集成阶段(按官方规范) |
|---|---|---|
| 前端代码放哪 | **React + Vite**:`src/frontend/src/`(从 `ssw-jnpf-lite-rust` 复制,与 React 技能逐字节相同) | 官方 `~/Desktop/workspace/jnpf/jnpf-web-apps-main/src/`(Vue 3) |
| 认证 | ✅ **MVP 就做**(端点/参数/密文/返回/登出码**全部照官方契约**) | 换官方 `jnpf-oauth`(**同形 ⇒ 零改**) |
| 业务页面 | ✅ **只做薄壳原型**(列表 + 弹窗表单 + 删除)⇒ 够试业务规则 | ✅ 补齐全套(类型、权限控制、国际化、组件用法) |
| 权限配置 UI / 低代码表单 / 数据建模页 | ❌ **不做**(官方有现成的,MVP 不重复造) | ✅ 全做 |
| 加一个业务页面 | React 三件套:`api/<lc>.ts` + `views/<Ent>.tsx` + `App.tsx` 加一行 `<Route>` | Vue 三件套:`api/<模块>.ts` + `views/<模块>/index.vue` + `router/routes/modules/<模块>.ts` |
| 路由注册 | React Router 显式声明(`App.tsx`) | 🔴 **不用改配置** —— 官方 `import.meta.glob('./modules/**/*.ts')` + `mergeRouteModules`(读 `default` 导出)⇒ **放文件即注册** |
| 后端对接 | 面 A `/api/ssw/...` ⇒ **前端零改**直连本仓 Rust | 面 B `/api/{模块}/{资源}/...` ⇒ **前端零改**直连官方 Java |
| ⚠️ 缺口 | **前端完全没闸门**(`check-module.sh` 的 4 个前端接触点全打 `⏭`)⇒ 改错三处不一致**没人拦** | 同 ⇒ 集成前必须补 |
⇒ **本批(批次 12)对前端的动作**(在 ④ 里,已写入):
① `scripts/new-page.sh <app> <Entity>` —— 生成 **React 三件套** + 菜单登记提示;
② **移植** React 技能的 `scripts/check-module.sh`(9 个接触点,`--all` / `--live`)
⇒ 把「三处一字不差」这条从人工检查变成机器检查;
③ 🔴 **不碰官方 Vue 那一套**(集成期的事)。
🔴 **为什么这条值得单独做**:React 侧 `urlAddress` / `guardModule` key / Route path 三处不一致的后果是
**静默放行**(菜单显示了但守卫不命中)⇒ **不报错,只是权限失效** ⇒ 这是最该上闸门的一类。
🔴 **集成期搬 React → Vue 的对应关系**(React 技能 `MIGRATION.md` §「前端:React 原型 → jweb (Vue)」已写明):
- `cipher.ts` ↔ 官方 `defHttp` 拦截器(登出码 / ActionResult 解包)**1:1**;
- `api/<lc>.ts` 的 `request.get('/ssw/...')` ↔ `defHttp.get({ url: '/api/ssw/...' })`(**只差 baseURL 前缀**);
- ⚠️ **React 的 `<Route path>` 在 jweb 不存在** —— jweb 靠菜单挂载(`base_module.f_url_address`)自动注册路由;
- ⚠️ **jweb 请求头要多补 `Vue-Version: 3`**(官方 `addRequestInterceptor` 必发,本仓面 B 也靠它分流)。
#### ✅ 批次 12 完成状态(2026-11-01 22:00 实测)
| 交付物 | 状态 | 落地物 / 证据 |
|---|---|---|
| ① `sspf-sdk` 补 `routes()` + `crates/sspf-plugin` | ✅ | `PackRoute` 纯数据声明(包不依赖 axum);插件层按 `packs/*` 装载 |
| ② 两份拷贝打通 + PACK1 | ✅ | `modules/<app>.rs` 改 re-export;`check-arch` 新增 **PACK1 / AR8 / AR9**,4 例反自证全过 |
| ③ 业务 DDL 跟着包走 | ✅ | `packs/asset/schema/001_init.sql` + `include_str!` 编进二进制 ⇒ **单二进制部署**(运行时无 `packs/`) |
| ④ 契约登记自动生成 + 静态闸门提速 + `verify.sh` | ✅ | `scripts/pack-sync.py`(幂等,两次 md5 一致)+ `scripts/verify.sh`(**≈15s**) |
| ⑤ **前端三件套**(本轮新增) | ✅ | `src/frontend`(React MVP 模板)+ `scripts/new-page.sh` |
**加一个业务模块现在的实际成本(批次 12.5 之后 = 一条命令)**:
```bash
bash scripts/new-pack.sh crm Customer --name "客户" \
--columns "name:VARCHAR(200),level:VARCHAR(50)" --with-frontend
bash scripts/verify.sh --fast # 纯静态:文件与接线一致(含尺子自证)
bash scripts/verify.sh --lib # + 单测 + **包冒烟**(真起库、真打 List)
```
⚠️ **不在这里写耗时**:`verify.sh` 每次运行自己打印总耗时 + Top 3 最慢
(判据是「耗时必须可见」,写在文档里的数字一定会烂)。
它产出的东西(**全部从「业务决策」推导,不猜**):
| 产出 | 谁生成 |
|---|---|
| `packs/<app>/{Cargo.toml,pack.toml,schema/001_init.sql,src/lib.rs}` | `new-pack-gen.py`(真源:app / 实体名 / 列清单) |
| `src/backend/src/modules/<app>.rs`(面 A 适配器) | 同上(**MVP 前端走面 A**,没有它页面就是空的) |
| `src/backend/src/packs_gen.rs`(内核包清单) | `pack-sync.py`(**生成物**) |
| `modules/mod.rs` 的 5 个登记段 | `pack-sync.py`(**生成物**) |
| `src/backend/Cargo.toml` 的包依赖段 | `pack-sync.py`(**生成物**) |
| `docs/contract.md` 的 `[MODULE]` / `[MENU]` / `[ENDPOINT]` | `pack-sync.py`(**生成物**) |
| `src/frontend/src/{api,views}/…` + `App.tsx` 路由 | `new-page.sh`(`--with-frontend`) |
| `[RULER]` 的断言条数 | 实跑一次 `check-module` 登记(**只允许变大**,见下) |
⇒ 见 §「✅ 批次 12.5 完成状态」。
🔴 **前端接入的两个坑(已修,别再踩)**:
1. **端口**:React 技能模板的 vite proxy 指 NestJS `:30000`,本仓 Rust 后端是 **`:30010`**
(`main.rs` 的 `PORT` 缺省值)⇒ 照抄会在浏览器里表现成 `Network Error`,
最容易误判成「跨域 / 认证」,其实只是端口抄错。
2. **api 文件名**:`check-module.sh` 用 `lower(Entity)` 推文件名 ⇒ `DataResource` 要的是
`api/dataresource.ts`(**全小写**,不是 `dataResource.ts`)。`new-page.sh` 已按此生成。
要改这个约定**必须同时改尺子**,否则尺子会报「缺 export」而文件明明在那儿。
**前端闸门已转真检查**:`check-module.sh` 的前端接触点从 `⏭` 变成真断言 ⇒ 条数
**114 → 123**(契约 `[RULER]` 已同步)。这正是「尺子自证」在起作用——条数对不上就报
「尺子被改弱了(少了/多了断言)」,逼你把新条数**显式**登记,而不是悄悄绿灯。
**未做(明确留下,不是忘了)**:
- 前端**没有运行时闸门**:`npm run build` / `tsc --noEmit` 不在 `verify.sh` 里。
`verify.sh` 的定位是「零 node 依赖的静态闸门」,塞 node 会把它拖慢一个量级;
要验类型请单独跑 `cd src/frontend && npx tsc --noEmit`。
- 官方 **Vue 那一套一行没碰**(集成期的事)。
#### ✅ 批次 12.5 完成状态(2026-11-01 23:40 实测)—— 「加包 = 一条命令,漏接 = 直接报错」
**问题**:批次 12 把 spec 搬进包之后,加一个模块仍要手抄 **5 个后端文件**
(`packs/<app>/` 四个 + `modules/<app>.rs`),再带动 **4 处内核登记**
(`packs_gen` / `Cargo.toml` / `modules/mod.rs` 5 段 / 契约 3 段)。而其中两类漏接
**不报错**:漏 `merge` ⇒ 面 B 静默 404;漏 `ALL_MENUS` ⇒ 菜单不种 ⇒ 守卫查不到菜单
⇒ **越权放行**。
**做法**:把「内核怎么知道有这个包」从**手写**改成**生成** ——
| 派生位置 | 生成器 | 漏了会怎样(改之前) |
|---|---|---|
| `src/backend/src/packs_gen.rs` | `pack-sync.py` | 🔴 面 B 静默 404,无日志 |
| `modules/mod.rs` 的 5 段(`pub mod` / `ALL_SPECS` / `ALL_ROUTES` / `ALL_MENUS` / `router()`) | `pack-sync.py` | 🔴 面 A 静默 404 + 菜单不种 |
| `src/backend/Cargo.toml` 包依赖段 | `pack-sync.py` | 编译报错(响亮) |
| `docs/contract.md` 三段 | `pack-sync.py` | `check-contract` 红(响亮) |
- 新增统一包出口约定:每个包导出 **`pub struct Pack`** + **`pub const DDLS: &[(&str,&str)]`**
⇒ 生成器只要知道「目录名 + crate 名」就能拼出装载调用,**不需要理解每个包的常量命名**。
- `sspf_plugin::load_static()`:把「manifest 解析 + `PackSource` + `merge`」这段样板收进插件层
(**为生成而设计**)⇒ `bootstrap.rs` 的 `load_packs()` 只剩一行。
- **`scripts/new-pack.sh`**(+ `new-pack-gen.py`):一条命令生成 5 个后端文件 + 跑 `pack-sync`
+ 可选 `new-page.sh`。列清单只从 `--columns` 或 `--from-ddl` 来,**没有就拒绝**(不猜类型)。
- **`[RULER]` 条数自动登记**:每加一个模块断言数 **+30**(实测 123 → 153)
⇒ `new-pack-gen.py` 实跑一次 `check-module` 把数字登记掉,**只允许变大**
(变小 = 有人删了断言 ⇒ 拒绝并打印)。
**端到端验证(在 `/tmp` 的仓库副本里做,不污染工作区)**:
```
bash scripts/new-pack.sh probe Widget --name "探针" \
--columns "name:VARCHAR(200),price:DECIMAL(18,2),memo:TEXT" --with-frontend
→ 写 5 个后端文件 + 契约三段的 probe 行 + packs_gen/Cargo/mod.rs + 前端三件套
→ ✅ 已登记 153 条(原 123,+30 来自新模块)
cargo build --offline ✅ 3.7s
cargo test -p sspf-pack-probe ✅ 13 passed
cargo test -p ssw-platform --lib ✅ 102 passed
python3 scripts/pack-sync.py --check ✅ 幂等
bash scripts/verify.sh --fast ✅ 全绿 17.2s
```
**反自证(证明新闸门真的会红,不是「改瞎了还全绿」)**:
| 造的漂移 | 结果 |
|---|---|
| 从 `packs_gen.rs` 删掉 probe 的装载块(模拟「忘了跑 pack-sync」) | `--check` **rc=1**,指名 `packs_gen.rs` |
| 从 `modules/mod.rs` 删掉 `probe::WIDGET_MENU`(模拟「漏登记菜单」) | `--check` **rc=1**,指名 `modules/mod.rs` |
**本轮抓到并修掉的 2 个真 bug**(都是「加第二个包」才显形):
1. 🔴 **`check-contract-scan.py` 的守卫回落取了「排序后第一个包」**
(`for pkg in sorted(pack_orig)`)⇒ 有 `asset` + `probe` 两个包时,probe 的面 A 守卫
被推成 `asset/DataResource` ⇒ **CC6 假飘移 3 条** ⇒ 人会去改**对的**契约。
修法:按 `app` 精确匹配包;查不到就返回「推不出」(人工核对),不再瞎猜。
2. 🔴 **加包会误报 3 个单测**(`asset_pack_loads` / `pack_router…` / `health…==52`)——
全是**写死计数**的假闸门,加包必须先改测试。改成**结构性/推导式**断言:
每个实体必须「有 DDL + 有菜单 + 3 条路由」;health 的表数 =
`ddl_tables().len() + packs.ddls.len()`。
**未做(明确留下)**:
- `new-pack.sh` **不跑 `cargo build`**:它只保证「文件和接线都齐」,编译留给 `verify.sh`
(生成器不该假装自己是编译器;但**编译失败一定是响亮的**)。
- **一个模块文件仍只能有 1 个实体**(`ALL_ROUTES` 与 `ALL_SPECS` 按「每模块 3 条」配对)。
要加第二个实体 ⇒ 另建一个模块文件。放宽它需要引入「模块 → (起点, 条数)」映射表
⇒ 又多一处会漂的结构,暂不做。
- 包**只支持静态链接**(`kind = "static"`);`dylib` 热插拔仍未做。
- 官方 **Vue 那一套一行没碰**(集成期)。
#### ✅ 批次 12.6 完成状态(2026-11-01 23:15 实测)—— 「接上了」≠「接的活能应答」
**问题**:12.5 之后,漏接会红(`pack-sync --check`),但**接错了仍然全绿**。
`routes.rs::route_table_is_pinned` 只用「错方法 ⇒ 405」证明**路径注册了**,
它证明不了 **handler 跑得通**。中间那段是静默失败的重灾区:
| 造的错 | 静态闸门 | 用户看到 |
|---|---|---|
| spec 有列、DDL 缺列(投影 SQL 报错) | 全绿 | 列表恒 `{"code":400}`,页面空着 |
| `module_key` 指向不存在的菜单 | 全绿 | 403,页面空着 |
| 面 B 路由没 merge 进总路由 | 全绿 | 404,页面空着 |
**做法**:`src/backend/tests/pack_smoke_it.rs` —— **一个测试、遍历全部包**
(`ALL_SPECS` / `ALL_ROUTES` / 包注册表,**一个条目都不写死**):
登录拿 token ⇒ 面 A 每个 `List` ⇒ 断言 `code==200` 且 `data` 是裸数组;
面 B 每条 List 路由 ⇒ 断言 `code==200` 且 `data.list` 是数组、`pagination.total` 非空。
失败时**一次列出全部坏条目**(加包场景常一坏一片,逐条重跑才能看全 = 浪费)。
- `verify.sh` 新增这一步,挂在 **`--lib`**(`full`/`smoke` 已由 `--workspace` 覆盖,不重复跑):
实测 **+2.4s**(起 pglite + 起 HTTP 服务 + 4 个包 × 2 面)。
- 🔴 **不放进 `--fast`**:内环的定位是「零 node、零起库的纯静态」,塞进去会把 20s 变成 25s
且多一个 flaky 面(端口 / 起库)。`--fast` 与 `--lib` 的分工现在很清楚:
**`--fast` = 该接的接上了;`--lib` = 接上的活真能应答**。
**反自证(两处,实测)**:
| 造的漂移 | 结果 |
|---|---|
| `packs/asset/schema/001_init.sql` 删掉 `f_category`(spec 还有这一列) | **FAILED**,一次列出两条:面 A `.../DataResource/List` 信封 code=400、面 B `/api/asset/DataResource` 信封 code=400(附 `column "f_category" does not exist` 的服务端日志) |
| `bootstrap::pack_router_or_empty` 改成恒 `Router::new()` | **FAILED**,指名 `面 B /api/asset/DataResource 状态 404 ≠ 200` |
**顺手修的两处文档失真**:
- `verify.sh` 头部写「45 个测试二进制」,实测(`cargo test --workspace --no-run` 的
`Executable` 行数)= **37** ⇒ 改成 37。这类数字没人核就一定是错的。
- `--lib` 的描述写「不起库」也是错的(`--lib` 里的 `routes.rs` 测试早就起 pglite 了)
⇒ 改成「lib 单测 + 包冒烟(起库)」。
**边界(有意不做)**:
- **不冒烟 Save / Delete**:Save 需要合法 body,而 `ColumnSpec` **有意不带类型**
(只有 `numeric: bool` + `default`)⇒ `VARCHAR` 与 `TIMESTAMP` 在 spec 里长得一样
⇒ 造不出对所有包都合法的 body。退一步用 `{}` 又要求「业务列全部可空」——
那是**业务决策**(`--columns` 允许写 `NOT NULL`),平台不该替包规定。
写 / 删留给各包自己的集成测试(`crud_it.rs` / `batch*_it.rs`)。
- **不在 `new-pack.sh` 里跑**:与「生成器不该假装自己是编译器」同一条边界
—— 它只管「文件和接线都齐」,能不能应答交给 `verify.sh`。
#### ✅ 批次 13 已完成(2026-11-02):行政区划 + 公有变量,见 §1「批次 13」小节
原计划的判据没变,**下一轮照它挑**:
`fe-gap` 余下的缺口 ⇒ `system` **41** / `permission` **26** / `systemData` **32**,里面挑
**有官方 `base_*` 表支撑**的;`workFlow`(104) / `onlineDev`(101) / `aiCenter`(75) /
`extend`(64) / `msgCenter`(50) / `teamwork`(40) 基本都是「本仓没这个模块」⇒
**先确认产品边界再动手**,做也只是恒空 stub(做了等于给前端一个假绿)。
**实现模板(照抄就行)**:`ORGANIZE_WRITE_FIELDS` / `POSITION_WRITE_FIELDS` /
`AREA_WRITE_FIELDS` 那一套 —— 列白名单 + `now()` 不占参数位 + 只 SET body 里出现的键 +
读回不选 `f_password`。**写语句走 `exec_params`、整型参数写 `$N::text::integer`**
(本仓 `query_json_params` 只认 SELECT,见 §5 批次 13 的坑)。
`docs/contract.md` 三处登记必须同步(`[ENDPOINT]` 手写段**在 `PACK:BEGIN` 之前**、
`[FACE]` 计数、`[OFFICIAL]` 台账),否则 CC9 / CC10 / CIT2 会红。
---
## 4. 每批实现的固定动作(缺一不可)
```bash
cd ~/Desktop/workspace/ssw-platform
# 1) 实现 → 编译
RUSTC_WRAPPER=sccache cargo build --manifest-path src/backend/Cargo.toml
# 2) 重启后端(老进程先 kill)
PORT=30000 ./target/debug/ssw-platform &
# 3) 运行时验证(比静态比对权威)
python3 scripts/probe-page.py docs/fe/page-user.tsv
# 4) 单测 + 六闸
RUSTC_WRAPPER=sccache cargo test --manifest-path src/backend/Cargo.toml
# 🔴 **尺子跑的是 release 产物** ⇒ 跑尺子前必须先 build --release
RUSTC_WRAPPER=sccache cargo build --release --manifest-path src/backend/Cargo.toml
for s in check-module check-boundary check-contract check-citations; do bash scripts/$s.sh; done
bash scripts/perm-smoke.sh
ENC_BIN="$PWD/target/debug/ssw-platform" bash scripts/perm-smoke-jnpf.sh
```
新增/变更端点必须同步三处,否则闸门必红:
1. `docs/contract.md` 的 `[ENDPOINT]`(面 B 行首列写 `B`)与 `[OFFICIAL]`(`absent → implemented`)
2. `docs/contract.md` 的 `[FACE]` 计数 + `[RULER]` 里 `perm-smoke-jnpf.sh` 的断言数
3. `src/backend/src/routes.rs` 测试里的 `JNPF_REGISTERED`(按**路径**列,同路径多方法算一条)
---
## 5. 必踩的坑(都已踩过一次,别再踩)
- 🔴 **一条 `.route()` 只挂一个方法**:`check-contract-scan.py` 只解析每个 `.route()` 的第一个方法,
`get(a).post(b)` 会被判成「契约写 POST、代码是 GET」。同路径多次 `.route()` 在 axum 里是合并,不冲突。
- 🔴 **驼峰 ≠ 下划线机械转换**:`ranks` ↔ `f_rank`、`certificatesType` ↔ `f_certificates_type`。
列名只来自白名单常量(如 `USER_WRITE_FIELDS`),别用 `snake_case()` 猜。
- 🔴 `f_creator_time` 写 SQL `now()` 时**不占参数位**:`marks.push("now()")` 而非 `placeholder()`,
否则 `$n` 序号和 `columns` 错位(报 `column is of type timestamp but expression is of type text`)。
- 🔴 写路径只 `SET` **body 里出现过的键**,未出现的列必须保持原值(有断言钉住)。
- 🔴 读回**不选** `f_password` / `f_secretkey`(有断言钉住「详情无 password 键」)。
- 🔴 `{id}` 会吞掉 `Users/` 下未注册的静态 GET 子路径;matchit 静态段优先,所以那些路由
**一旦注册就自动优先匹配**,不需要改详情。
- 🔴 测试共用 `platform/test_support.rs` 的**单例 pglite**(进程内只能开一个实例),
别在测试里 `open_temp`。
- 🔴 `python` 脚本里递归取同目录 `.vue` 时用 `if seen is None:`,**不能写 `seen = seen or set()`**
(空 set 是 falsy ⇒ 每层新建 ⇒ 环形 import OOM 被 SIGKILL)。
- 🔴 jq 里 `$d|has(a) or $d|has(b)` 会被 `|` 抢结合 ⇒ 用 `[keys[]|select(.=="a" or .=="b")]|length`。
- 🔴 端口:前端 dev 3000,代理 `/dev` → **30000**,后端绝不能起在 3000。
- 🔴 **npm/pnpm 类命令一律 `env -u NODE_OPTIONS`**(见 §0);cargo 不受影响,不用加。
- 🔴 **后台进程随 turn 结束被回收**:起服务与验证必须同一 turn 内完成。
- 🔴 git 推送别把密码塞 remote URL:用 `GIT_ASKPASS` + `xop run --secret`,并加 `-c http.proxy=`。
- 🔴 `.gitignore` 已挡 `target/`(1.7G) 与 `src/backend/data/`(38M);`git add -A` 前先
`git diff --cached --name-only | wc -l` 确认没暴涨。
### 批次 2 新增的坑
- 🔴 **PG 数组参数一律不能写 `$N::text[]`**:pglite-rs 0.2.7 会把它当成 PG 数组类型 `_text`,
而本仓参数**一律按 text 绑定**(`Option<String>`)⇒ 协议错
`cannot convert between the Rust type String and the Postgres type _text`。
⇒ 改成 `= ANY(string_to_array($N::text, ','))`(**函数在 SQL 里做**)。
- 🔴 **PG 会拒「SQL 里有 $N 但没用它」**:`42P18: could not determine data type of parameter $1`。
⇒ 凡是留了 `$N` 的软删 SQL,都要把对应列写进 SET(`f_delete_user_id = $N::text`)。
- 🔴 **占位符顺序必须与参数追加顺序逐字对齐**(不是「大致对上」)⇒ 写完对着读一遍。
- 🔴 **`base_action.f_enabled_mark` 是 VARCHAR(11)**(官方 DDL 陷阱)⇒ 别按整数 CAST。
- 🔴 **`base_standing.f_is_system` 是 1=系统 / 2=自定义** ⇒ 新建写 **2**,不是 1。
- 🔴 **官方 `list` 端点常有「id 串换人名串」的后处理**(`getFullNameByIds`)⇒ 抄控制器别只抄模型。
- 🔴 **Bash 里写多层嵌套引号的 curl + python 验证脚本很容易引号不闭合**(`bash -n` 报
`unexpected EOF` 但**定位不到行**)⇒ **直接用 Python 写验证器**(`urllib` + `ProxyHandler({})`
绕过本机代理),别跟 bash 引号较劲。
- 🔴 **尺子用的是 `target/release/ssw-platform`**,不是 debug 产物 ⇒ 改完代码跑尺子前
**必须 `cargo build --release`**,否则尺子跑的是旧二进制(表现为「刚修好的端点还是 405」)。
### 批次 11 新增的坑
- 🔴 **`b10_insert` 的 `None` 不是「不写这列」,是「写 `now()`」** ⇒ 整型列直接类型错
(`column "f_all_data" is of type integer but expression is of type timestamp`)。
⇒ **写整型列一律给具体值**(缺省按官方默认补 `0`),**不要传 `None`**。
(这条已把批次 10 的 `f_field_rule` ×2 也炸出来了 —— 同一个雷,隔一批才被踩到。)
- 🔴 **查 `int4` 列必须 `$N::text::integer`**(本仓参数一律按 text 绑定)。
`f_type = $2` ⇒ `cannot convert between ... Option<String> and the Postgres type int4`。
- 🔴 **`updateById` 语义 = 只 SET body 里出现的键**:官方 Mybatis 只 SET 实体里**非 null** 的字段 ⇒
body 没带的键**保持原值**。⇒ 自己拼 SET 列表时**别把没传的键也 SET 上去**(会清空数据)。
- 🔴 **共用 pglite 的测试不要写死绝对条数**:同一测试文件里 `any_menu_id()` 对每个测试返回
**同一个**菜单 ⇒ 别的测试先建过行 ⇒ 「count == 0」必红。⇒ 一律**基线相对**(`before`/`before + n`)。
- 🔴 **`async fn` 忘了 `.await` 会静默不执行**(编译器只给 `unused_must_use` 警告)⇒
测试里「插了行却查不到」先查这个。
- 🔴 **官方 `ActionResult.success(String msg)` 是「msg 带提示、data 为 null」**,
与本仓 `ok(json!({...}))`(`msg="成功"`、data 透传)**不是同一个形状**。
本仓沿用既有约定(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"`**(报错位置很误导)。
**写语句(INSERT / UPDATE / DELETE)一律走 `exec_params`。**
(同一个 `Db` 上两个方法长得很像,只有这一个区别 —— 看代码时容易过。)
- 🔴 **写路径也要 `$N::text::integer`**(批次 11 只记了「查 int4 列」):
`INSERT … VALUES ($1::integer)` / `SET f_type = $1::integer` 会被 PG 把**参数本身**
推断成 `int4` ⇒ 绑 `Option<String>` 直接
`cannot convert between the Rust type Option<String> and the Postgres type int4`。
⇒ 一律「先 `::text` 再转」:`$N::text::integer` / `$N::text::bigint`。
- 🔴 **matchit 同位置不能有两个参数名 ⇒ 启动即 panic**:
`GET /api/system/Area/{nodeId}` 与 `PUT|DELETE /api/system/Area/{id}` 会让
`Router::route` 在**建路由时**炸:`Insertion failed due to conflict with previously
registered route`。**静态闸门(check-contract)看不出来,编译也过,只有真跑起来才炸**
⇒ 新一族端点必须跑一次集成测试。修法是**统一段名**(本仓约定 `{id}`),
`[ENDPOINT]` 跟着改;`[OFFICIAL]` 保留官方名(CC10 归一后对账)。
- 🔴 **加平台表要同时改三处**:`db/schema.sql` + `main.rs::BASE_TABLES` +
**`crates/sspf-store/src/db.rs::BASE_TABLE_COUNT`**。漏第三处 ⇒
`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. 收工前(每一轮都要做)
1. 追加 `.workbuddy/memory/YYYY-MM-DD.md`:结论 / 坑 / 数字(闸门通过数)
2. 更新本文件 §1 现状、§2 现场、§3 待办(划掉做完的)
3. 若还有未完成项,**确认下一次定时任务存在**(`automation_update` list 可查),没有就新建
**当前挂着的定时任务**(2026-11-01 19:23 实查):
| 任务 | id | 触发 | 覆盖范围 |
|---|---|---|---|
| **ssw-platform 批次 12:框架固定包 + 业务模块链接就好** | `68997e3d-b08a-4f12-b0d1-003733b381c1` | **2026-11-02 09:00 一次性** | 批次 12 全部 4 项交付物 + 护栏 + 验收判据(prompt 已写全,自包含) |
| ssw-platform P2-b 收尾 | `1dcb55af-…` | 已过期(一次性,未删) | P2-b 已完成 ⇒ **可删** |
| 每日积分 | `82c41449-…` | 每日 08:00 | 与本仓无关 |