Files
ssw-platform/HANDOFF.md
T
admin ca8abf9cc9 docs: v0.3.0 发布口径同步 —— 决策 D 变更为直接推送
- 需求稿 §7.4/§7.5/§11.1/§11.4/§11.6 改按已发布口径,补仓外 tag 探针实测
- HANDOFF 0-bis 同步发布范围;工作日志记离线模式无法 checkout file:// git 依赖
2026-11-04 18:27:56 +08:00

2882 lines
224 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-03(面 B **批次 24** —— 官方移动端 39 条;前一批 21–23 = aiCenter 75 + extend 64 + teamwork 40),
> 底部保留 2026-11-01 19:00 的「批次 12 方向决策」与
> **20:10 的「前端 MVP 用 React 模板、除了认证其它都留给集成阶段」**。**开工先读这一页**
> (尤其 **§0-bis 的「下一轮的优先级改了」**),再读 `CLAUDE.md`(硬约定),
> 最后看 `.workbuddy/memory/` 最近一天的日志(踩过的坑)。
> 无人值守时不要问用户,选最保守可行的方案继续,并把决策写回本文件。
---
## 0-bis. 2026-11-04 `v0.3.0`:业务自带状态的可组合装配(P1 交付,**已推送 `origin`:`main` + tag**)
需求与实施记录:`docs/SSPF-BUSINESS-COMPOSITION.md`(含 §11 四项评审决策)。
1. **`Db.pg` 改 `Arc<PGlite>` + `pub fn pg()`**(`crates/sspf-store/src/db.rs`):业务仓拿**同一个**库句柄造自己的状态层,不必另开 PGlite。`begin()` 里改 `self.pg.as_ref().transaction()`;其余 `self.pg.*` 调用经 Deref 一行没动。
2. **两阶段装配**(`crates/sspf/src/platform.rs`):`Platform::assemble() → Assembled::{finish, serve}`,`Finish { router, fallback, layers }`。`build_app()` / `serve()` / `serve_mcp()` 内部统一走 `assemble() → finish(Finish::default())` ⇒ **v0.2.0 签名与默认行为逐字不变**。
3. **`Extras` 三个注入点 + 前移 `with_state`**(`src/backend/src/routes.rs`):`router_owned: Option<Router<()>>` / `fallback: Option<Router<()>>` / `layers: Vec<LayerFn>`;唯一兜底由 if/else 互斥两分支挂。S25 的 `fallback` 仍在两个平台 layer 之前。
4. **探针 + 闸门**:`crates/tests/tests/business_composition_it.rs`(1 个测试 / 7 组断言,两个监听共用同一个 AppState);`check-arch.sh` 加 AR19(唯一装配链),反自证 13 → 14 条。
5. **文档**:新建 `CHANGELOG.md`;`docs/known-limitations.md` 加章节 L;P0 需求稿加 v0.3.0 注记;`docs/contract.md` 核查后无需改(没有「with_state 在链尾」的表述)。
**🔴 三条必须记住的结论**:
- **`with_state` 现在有两次,都要保留**:`build_router_with` 末尾原有一次(状态烤进平台 endpoint、类型仍标 `Router<AppState>`),`build_app_with` 里前移的是**第二次**(只做类型降级到 `Router<()>`)。删任何一处都会让默认路径偏移。
- **`Finish.layers` 是全局层**(挂在 merge 完成后的总 Router)⇒ 只许放 CORS / 日志等无差别件;业务鉴权、405 改写必须挂在业务 Router 的 `route_layer`(merge 之前),否则面 B 登录会被业务三道门拦住。探针用 `x-biz-guard` / `x-global` 两个响应头钉住这条边界。
- **`on_ready` 不回传产出**(返回 `Result<(), String>`):业务引导身份要在 `assemble()` 之后用 `state.db.pg()` 自己跑,结果直接进业务状态。
- 已知局限(本轮接受):`Db::pg()` 绕过 `Db.lock` ⇒ 两把锁并行,跨平台/业务的多语句事务可能交错;业务 413 会被平台 `m_status_rewrite` 改成信封。见 `docs/known-limitations.md` §L。
- **发布范围(决策 D 变更)**:原定「只打本地 tag、不 push」,交付后提出方要求**直接推送** ⇒
`main` 与 annotated tag `v0.3.0` 均已到 `origin`,`git ls-remote --tags origin` 可见 `v0.3.0` 与 `^{}`。
业务仓按 `http://127.0.0.1:13300/ssw/ssw-platform.git` + `tag = "v0.3.0"` 锁依赖(仓外探针实测通过)。
---
## 0. 2026-11-04 标准平台包 `v0.2.0`:门面 crate `sspf` + 示例包选装(P0 交付)
**做了什么**(需求原文 `docs/SSPF-PLATFORM-PACKAGE.md`,实施记录见其 §10):
1. **新增 `crates/sspf`(0.2.0)= 业务仓唯一依赖**。`Platform::new().packs/ddl/menus/router/static_dir/on_ready` +
`build_app()` / `serve()` / `serve_mcp()`;契约与运行时类型全部**原样重导出**(业务仓不碰 19 个 `sspf-*`)。
2. **内核 4 个示例包降为 `example-packs` feature**(默认不链接):`src/backend/Cargo.toml` 依赖全部 `optional = true`
+ 生成段 `[features]`;`packs_gen.rs` / `modules/mod.rs` 的生成段改成 **feature / not-feature 各一份**(同名常量与函数)。
生成器 `pack-sync.py` 同步改(`--check` 绿),`new-pack.sh` 无需改(它只调生成器)。
3. **进程级启动动作搬出门面**:七步在 `crates/sspf/src/platform.rs` 的 `boot()`;绑端口 / 停机 / 关库在 `runtime.rs`。
认识平台表清单的原语(`BASE_TABLES` 123 张 / 白名单对账 / 开库 / 停机)落在内核 **`src/backend/src/boot.rs`**(参数化:
spec 与包 DDL 由调用方给)。`crates/sspf-admin/src/main.rs` **1111 行 → 381 行**,只留 CLI。
4. **`routes::build_app_with(state, extras)`** 承载注入(包路由 / 业务路由 / SPA 目录);`build_app` 是 `Extras::kernel()` 薄封装
⇒ **704 个测试一行没改**。`bootstrap::{ensure_base_with, ensure_schema_all_with}` 参数化,旧签名保留。
5. **探针** `crates/tests/tests/external_consumer_it.rs`(只 `use sspf::{Config, Db, Platform}`):同时证明
①平台表已建 ②注入 DDL 进**同一个库** ③示例包表/路由**不存在** ④面 B 登录 200 ⑤注入端点同端口。
6. **新闸门 AR17 / AR18**(`check-arch.sh`,反自证 **11 → 13 条**,全部通过):AR17 = 平台包零业务依赖;
AR18 = 门面源码零业务字面量(连注释一起扫)。
**🔴 两条必须记住的结论**:
- **门面一次都不读 `bootstrap::packs()` 那个 `OnceLock`**。理由是 feature 统一:`sspf-tests` 开 `example-packs` 的构建里,
内核也带着示例包 ⇒ 门面若读单例就会**静默**把示例包带进业务仓进程,而测试全绿。现在默认装配**恒零业务**。
- **`#[cfg]` 只能加在项上**:`ALL_SPECS` 的数组元素不能单独 cfg ⇒ 生成器产出「两份同名定义」。
整段 cfg 会让 `all_specs()` / `router()` 在默认 feature 下**不存在** ⇒ `routes.rs` / `bootstrap.rs` 编译不过。
- **`.packs()` ≠ 业务全进去了**:面 A(`/api/ssw/**`)来自内核 `modules::router()`,门面默认不认识
⇒ `sspf-admin` 必须显式 `.router(modules::router())`,否则面 A 全 404(本批 perm-smoke 29 条红过)。
- **包菜单必须自动种**:只种 `.menus()` 而漏 `PackRegistry.menus` ⇒ `module_key` 守卫查不到菜单
⇒ 该 403 的请求**静默 200**(本批 perm-smoke 6 条红过)。现在 `.packs()` 自动把包菜单带进种子。
**出口判据(实测)**:`cargo test --workspace` **710 passed / 0 failed**(基线 704,只增不减);
`cargo tree -p sspf | grep sspf-pack` **无输出**;`cargo tree -p ssw-platform` 同;
`check-arch.sh` **29/29**、`--self-test` **13/13**;`verify.sh --fast` 八步全绿;
运行时尺子 perm-smoke **43/43**、perm-smoke-jnpf **23/23**、lowcode-smoke 15/15、baseline-smoke 10/10、mcp-smoke 14/14;
仓外探针(只依赖 `sspf`)起服务后 `/api/health` = `{"ok":true,"tables":177}`。
🔴 **177 不是 181**:181 = 177 张平台表 + 4 张示例包表(asset/books/demo/shop);平台包默认不带示例包
⇒ 业务仓看到 177 + 自己的表。本仓 `sspf-admin`(开 `example-packs`)仍是 **181**,别把 181 写进业务仓的断言。
**已发布**:注记标签 `v0.2.0` → commit `9083394`,`main` 与 tag 都已推 `origin`。
**git 依赖实测过**(需求 §6 那个 ⚠️ 已消):仓外项目只写
`sspf = { git = "http://127.0.0.1:13300/ssw/ssw-platform.git", tag = "v0.2.0" }`,
`cargo check` **37.95s 通过**,依赖全标 `?tag=v0.2.0#9083394b` ⇒ 与 path 依赖等价,workspace 根解析正常。
**⏭ 业务仓(tdc-rs)P1 必做**(平台侧代劳不了):① 自带 `rust-toolchain.toml` 锁 1.95.0;② **删掉
`[profile.release] panic = "abort"`**(否则 catch-all 失效、契约 §6.5 破);③ `[profile.dev] incremental = false`;
④ 依赖写 `sspf = { path = "../ssw-platform/crates/sspf" }`(发布期换 git tag `v0.2.0`)。
---
## 0-0-pre-pre. 2026-11-04 11:20 结构三改:onlinedev 正名 / 测试剥离 / 默认装配 `sspf-admin`
- `crates/sspf-compat-online_dev` → **`crates/sspf-compat-onlinedev`**(包名 / 模块 / 文件名 / `compat::onlinedev::` 全同步)。理由:与官方 `onlineDev` 拼写一致,也与同族 `sspf-compat-{system,ext}` 的「去分隔符」惯例一致。
- **37 个集成测试**从 `src/backend/tests/*.rs` → **`crates/tests/tests/`**(package `sspf-tests`,全部走 `[dev-dependencies]`)。它们测的是「装配好的平台」,不该登记成内核包的实现细节。跑法:`cargo test -p sspf-tests`。
- **`src/backend/src/main.rs` → `crates/sspf-admin/src/main.rs`**,bin 名 **`sspf-admin`**;`src/backend` 只剩 lib ⇒ `cargo run -p sspf-admin` 自己就能跑。🔴 **产物路径变了**:`target/{debug,release}/sspf-admin`(`run.sh` / 4 个冒烟脚本 / 文档已同步;`run.sh stop` 仍兜底收旧名 `ssw-platform`)。
- 新增 **AR16** 钉住三条边界:内核不许 `[[bin]]`、`src/backend/tests/` 不许回流 `.rs`、`crates/sspf-admin` 必须产出 bin(含反自证 11/11)。
- 回归:`cargo test --workspace` **695 passed / 0 failed**;`check-arch.sh` **21/21**;其余五把闸门全绿;`/api/health` = `{"ok":true,"tables":181}`。
- 已知残留(**故意没动**):技能目录 `~/.agents/skills/ssw-jnpf-lite-rust` 仍是旧形状(内核带 bin、tests 挂内核包)——本仓已与它**分叉**,技能要跟就得单独同步,改本仓不会改到技能。
---
## 0-0-pre-pre-pre. 2026-11-04 12:4x 示例搬成业务包(demo / shop / books)+ 修好一个静默洞
- 三个示例模块的 **spec / 菜单 / DDL / 面 B 路由**全部搬进 `packs/{demo,shop,books}`(各 4 个文件,只依赖 `sspf-sdk`);内核 `src/backend/src/modules/*.rs` 缩成「面 A 适配器 + `pub use` 转发」⇒ **内核里再没有任何 spec**,示例可整目录搬去技能。
- **面 B 新增 9 条端点**:`/api/{demo,shop,books}/{DemoItem,Product,Book}` + `/{id}`。面 A(`/api/ssw/...`)**一字未改**,前端零改动。
- DDL 从 `db/schema.sql` 移走(177 张表,比之前少 3 张),并**按平台规则**补 `f_tenant_id DEFAULT '0'` + 复合主键 —— 这是包 DDL 的硬闸门。spec 列清单**没加** tenant ⇒ JSON 键与响应零变化;react 侧多一列有默认值的列,仍可同库。
- 🔴 **顺带修掉一个静默洞**:`is_builtin_table` 原来只认 `schema.sql`,而批次 12 之后业务表 DDL 跟着包走 ⇒ **`asset_data_resource` 一直能被建模页删掉**。现在 `sspf_store::db::is_protected_table` = 平台 DDL ∪ 包表(装配根在 `ensure_pack_schema` 里登记,`OnceLock` 只写一次)。两个集成测试(`batch7_it`)当场抓到,不是测试写错。
- `pack-sync.py` 补两个判据:`module_key: None` 的包要按「唯一菜单」落 `urlAddress/menuId`(否则 CP6 假红);`apiFile` 改成**查文件是否存在**(否则 demo 假红)。
- 回归:`cargo test --workspace` **704 passed / 0 failed**(+9 条包内单测);`verify.sh --fast` 全绿;运行时 `/api/health` = 181 张表,四个包的面 A / 面 B 全部 200。
---
## 0-0-pre. 2026-11-03 12:15 打 tag `v0.1.0` + 制定「平台能力全迁 crates/」计划
**做了什么**:① 在 `b957a11` 上打**迁移前基线 tag** `v0.1.0`(已推 `origin`);
② 写出完整迁移计划 `docs/CRATES-MIGRATION.md`。
**为什么打 tag**:这次迁移是「纯搬迁、零功能收益」的大改 ⇒ 必须有可一键回滚的锚点。
**基线绿灯(打 tag 时实测)**:
`cargo test --workspace` = **695 passed / 0 failed**;`check-arch.sh` = **12/12**;
`cargo build --workspace` = 成功。**这三个数是整个迁移的回归基准。**
### 🔴 迁移前必读:`docs/CRATES-MIGRATION.md`
**关键结论(都是实测,不是推断)**:
| 项 | 数据 |
|---|---|
| 壳只占 | `src/backend/src` 90,471 行里 **5,664 行(6%)** 是装配 + 转发 |
| 要搬走的 | `platform/compat` 48,980 + `platform/` 6,598 + `lowcode_*` 2,674 + `mcp_*` 3,283 ≈ **61,500 行** |
| 现有 crates | 7 个 / 17,174 行 |
| 目标 crates | **15 个** |
**🔴 三处循环依赖(跨 crate 前必须先解开,否则编译不过)**:
| 环 | 涉及 | 解法 | 状态 |
|---|---|---|---|
| A | `platform/auth.rs` ↔ `compat/helper.rs` | ✅ `sspf_contract::headers::is_face_b` **已存在** ⇒ 判定边改一行;面 B `current_user` 的**分流点上移到装配根 `routes.rs`** | ✅ M1 已解 |
| B | `compat/helper.rs` ↔ `compat/system.rs` | ✅ `menu_node` / `official_view_path` **搬进 helper** | ✅ M1 已解 |
| C | `compat/helper.rs` ↔ `compat/permission.rs` | ✅ `USER_DETAIL_COLUMNS` / `organize_name_of` **搬进 helper** | ✅ M1 已解 |
**✅ 已验证 `platform/` 内部 17 个文件无环**(依赖全单向向下)⇒ **M2 核心下沉不受环影响**,可独立推进。
**🔴 闸门是最大的坑**:`check-contract-scan.py:827/839` 与 `check-boundary-scan.py`
把 `src/backend/src/platform` **路径写死** ⇒ 代码搬走后脚本**扫不到文件 ⇒ 永远"通过"**
⇒ **虚假安全感**(`check-arch.sh` 的 AR9 自证注释里已警告过这一点)。
**M4 之后必须同步改这些脚本,并重跑 `--self-test`。**
**批次划分**:M1 解耦 → M2 `sspf-core` → M3 `sspf-compat-core` → M4 六个 compat 包
→ M5 `sspf-lowcode-exec` → M6 `sspf-mcp-adapter` → M7 收口 + AR12–AR13。
**每批次独立 commit + 独立 tag(`v0.1.N-mX`),不合绿不进下一批。**
---
## 0-0-pre2. 2026-11-03 12:55 **M1 完成**:三处循环依赖全部解开(tag `v0.1.1-m1`)
**做了什么**:解开 `auth ↔ compat/helper`、`helper ↔ system`、`helper ↔ permission` 三处环,
并加 **AR10/AR11 两条防回退闸门**(带反自证)。
**🔴 实际做法与原计划有出入(两处,都是「更简单」)**:
1. **不用运行期注册表**(原计划第 3 项)⇒ 改为把**分流点上移到装配根 `routes.rs`**。
`CLAUDE.md` §4 本来就写明「共用两条路由按判别头分流」⇒ 分流点本就该在壳。
而且**没有 `OnceLock` 静态槽位、没有注册时机、没有漏注册的风险**。
平台层与契约面从此**互不知道对方**,壳负责接线。
2. **不用新建 `compat_base/` 目录** ⇒ 4 个符号**直接搬进 `helper` 本身**:
`menu_node` / `official_view_path`(从 system)、`USER_DETAIL_COLUMNS` / `organize_name_of`(从 permission)。
**🔴 环 B/C 的方向修正**:原计划说「把符号搬**回** system / permission 侧」—— **错**。
helper 被 14 个模块依赖 ⇒ 符号在 helper 里大家都能用;
符号在 system/permission 里 ⇒ helper 又得依赖它们 ⇒ **环还在**。
**改动清单**:
- `platform/auth.rs`:`is_face_b` 改用契约层;面 B 分流移出;`resolve_user` `pub(crate)` → `pub`
- `routes.rs`:`CurrentUser` 路由按判别头分流(面 A → `auth::current_user`;面 B → `compat::helper::current_user`)
- `compat/helper.rs`:接收 4 个符号
- `compat/system.rs` / `compat/permission.rs`:移除 4 个符号 + 改 import
- `scripts/check-arch.sh`:**新增 AR10/AR11** + **反自证从 4 条扩到 6 条**
**出口判据(全部达成)**:
`cargo build` **零警告**;`cargo test --workspace` = **695 passed / 0 failed**(与基线一致);
`check-arch.sh` = **14/14**;`--self-test` = **6/6**;`check-boundary` 11/11;`check-contract` 10/10;
`check-module` 123/123;`check-citations` 4/4;`check-naming` 3/0;
`verify.sh --smoke` **14 步全绿**(478s)。
**⏭ 下一步 = M2(`sspf-core` 平台核心下沉)**。M2 的关键是**保留 `platform/` 转发壳**
(`pub use sspf_core::*`)⇒ 上层零感知、695 测试不用改 import。
---
## 0-0-pre3. 2026-11-03 14:50 **M2 完成**:平台核心 19 模块下沉 `crates/sspf-core/`(tag `v0.1.2-m2`)
**做了什么**:`platform/` 下 19 个模块 `git mv` 进 `crates/sspf-core/src/`(保留历史),
`src/backend/src/platform/*.rs` 全部改成 `pub use sspf_core::<mod>::*;` 转发壳
⇒ **上层零感知**(routes / modules / 695 个测试的 import 一个没改)。
**🔴 最大风险不是代码,是闸门(又一次验证了这个判断)**:
搬迁后 `platform/` 只剩转发壳(`pub use`,无函数体)⇒ 闸门扫空壳 = **虚假安全感**。
实测**当场暴露**:
- `check-contract.sh` 反自证报警「守卫写错**没**被 CC6 抓到」—— `plat_files` 收不到函数体 ⇒ 守卫推不出
- `check-boundary.sh` CP6 报「BUILTIN_MENUS 有 0 条」—— 读空壳的 `seed.rs`
- `check-module.sh` 8 项软删检查全 ❌ —— `crud.rs` 里没有 SQL 可 grep
**闸门改造(6 处,都要求「两处都扫」= 真源 `crates/sspf-core/src/` + 转发壳)**:
| 闸门 | 改造 |
|---|---|
| `check-arch.sh` AR9/AR10 | 扫描目录改两处;**反自证 2/6、5/6 两处都注入探针,且按路径分别验**(单点注入会漏判) |
| `check-boundary.sh` | 新增 `PLATFORM_CORE`;CP1/CP2 两处扫;CP6 的 `seed.rs` 改读真源 |
| `check-contract-scan.py` | `plat_files` 两处都收,重名键**拼接**(覆盖会丢函数 ⇒ 推不出守卫) |
| `check-module.sh` | `CRUD` 改读 `crates/sspf-core/src/crud.rs`(软删契约要看 SQL) |
| `gen-function-catalog.py` | `OUT` 改写 `crates/sspf-core/src/variate_catalog.rs`(否则**覆盖转发壳**) |
| `check-arch.sh` 头部注释 | 判据说明同步 M2 路径现实 |
**反向验证**(证明闸门真在扫真源):只往 `crates/sspf-core/src/` 塞违规 ⇒ AR9/AR10 **都报红**;探针已清干净。
**🔴 实际做法与原计划的差异**:
1. **`pub(crate)` → `pub`(10 处)**:跨 crate 后失效 —— `crud::{handle_list,handle_save,handle_delete,handle_*_face_b,value_to_text}` / `auth::{client_ip,parse_user_agent}` / `sys::query_param`。
2. **测试归属跟着依赖走**:`crud.rs` 3 个测试原依赖 `crate::modules::all_specs()`(业务层)⇒ core 不能反向依赖业务层 ⇒ 改用**契约层合成 spec** 参数化测试(断言强度不降)。顺带发现**技术债**:`write_cast` 的 numeric 映射是**列名枚举**(`f_price`/`f_stock`)而非 spec 声明 ⇒ 新表带 `f_amount` 会静默缺 `::numeric`(现有列名恰好都叫 `f_price` 未暴雷)。
3. **`registry.rs` 测试自建库**:改 `seed::ensure_base(db, &[])`(不经 `bootstrap`,那是装配根、认识业务层)。
4. **`test_support.rs` 留壳层**:依赖 `bootstrap::ensure_schema_all`(业务 DDL)⇒ 不进 core。
5. **路径改写**:crate 内 `crate::platform::X` → `crate::X`(`compat` 除外)。
**出口判据(全部达成)**:
转发壳每文件 ≤ 10 行;`cargo build` **零警告**;`cargo test --workspace` = **695 passed / 0 failed**(与基线一致);
`check-arch.sh` = **14/14**;`--self-test` = **6/6**;`check-boundary` 11/11;`check-contract` 10/10(反自证 12 例全过);
`check-module` 123/123;`check-citations` 4/4;`check-naming` 3/0/1;
`verify.sh --smoke` **14 步全绿**(512.3s)。
**⏭ 下一步 = M3(`sspf-compat-core` 契约面公共底座)**:迁 `compat/helper.rs`(902) + `compat/res.rs`(460)。
M2 的「转发壳 + 闸门扫真源 + 反自证两处注入」套路**直接复用**。
⚠️ M4 之后必须做 `check-contract-scan.py` 的 compat 包收编 + 重跑 `--self-test`。
---
## 0-0-pre4. 2026-11-03 16:00 **M3 完成** + 四个决策拍板(tag `v0.1.3-m3`)
**四个决策已拍板**(写入 `docs/CRATES-MIGRATION.md` §11):
① `platform/` 转发壳**最后删**(M7);② compat **拆 6 个包**;③ `mcp_compat.rs` **放 crates**;④ `tests/` **跟着拆**(单元测试随代码进 crate、集成测试留壳测装配)。
**M3 做了什么**:`compat/helper.rs`(994) + `compat/res.rs`(460) `git mv` 进 `crates/sspf-compat-core/src/`,
壳留 `pub use sspf_compat_core::<mod>::*;` ⇒ **14 个契约面模块的 `use super::helper::{…}` 零感知**。
**实际做法**:① 路径改写 `crate::platform::X` → `sspf_core::X`(独立 crate 不能用 `crate::X`);
② **`pub(super)` → `pub`(54 处)** —— 转发壳的 `pub use …::*` 只转发 `pub` 项,不提权则 14 个模块找不到
`EN_USER`/`Paging`/`MenuRow`(含 struct 字段);③ helper 的 8 个单测自足 ⇒ 随迁,总数仍 695。
**闸门改造(同「两处都扫」纪律)**:
- `check-arch.sh` AR11 扫真源 + 壳,**新增 Cargo.toml 级判据**(`sspf-compat-core` 不许依赖 `sspf-compat-*`);反自证 6/6 两处注入、按路径分别验
- `check-contract-scan.py` 的 `plat_files` 对 `compat__<mod>` **收真源 + 壳同键拼接** —— 守卫常量(`EN_ROLE` 等)在 helper 真源里,漏收则 CC6 假漂移
- 修 1 条引文(旧壳 `compat/helper.rs` 的 89-92 行 → `crates/sspf-compat-core/src/helper.rs:87-91`)
**反向验证**:只往真源 helper 塞 `use crate::res::Res;` ⇒ AR11 报红;清理后恢复绿。
**🔴 踩坑(已记入工作区记忆)**:反向验证后用 `git checkout -- <file>` 清理探针 ⇒ **把 M3 改写一并回退到暂存区**
(`crate::platform`×14、`pub(super)`×54 复活)。**教训:有未暂存改动的文件绝不能用 `git checkout --`** ⇒ 用 Python 精确删探针行。
**出口判据(全部达成)**:
`cargo build` 零警告;`cargo test --workspace` = **695 passed / 0 failed**;`check-arch` 14/14;`--self-test` 6/6;
`check-boundary` 11/11;`check-contract` 10/10(CC6 零漂移 ⇒ 守卫推导仍有效);`check-module` 123/123;
`check-citations` 4/4;`verify.sh --smoke` **14 步全绿**(561.3s)。
**⏭ 下一步 = M4(六个契约面包并行下沉)**:`sspf-compat-{system,permission,msg,workflow,ext,online-dev}`。
⚠️ M4 必须同步做 `check-contract-scan.py` 六包收编 + 重跑 `--self-test`。
---
## 0-0-pre5. 2026-11-03 18:40 **M4 完成**:六个契约面包下沉(tag `v0.1.4-m4`)
**做了什么**:`src/backend/src/platform/compat/` 下 **14 个模块 / ~49,000 行**下沉到 6 个 crate,
原路径全部变成 5 行转发壳(`pub use sspf_compat_<域>::<模块>::*;`)⇒ **上层零感知**。
| crate | 模块 | 行数 | 额外依赖 |
|---|---|---|---|
| `sspf-compat-system` | system + scheduletask + core | 19,764 | store + chrono |
| `sspf-compat-permission` | permission | 6,266 | **system**(4 符号)+ store + chrono |
| `sspf-compat-msg` | message + msg_center | 6,053 | chrono |
| `sspf-compat-workflow` | workflow + report + visualdata | 8,729 | chrono + aes/ecb/hex |
| `sspf-compat-ext` | extend + teamwork + ai + mobile | 8,142 | **system + msg**(2 函数)+ chrono |
| `sspf-compat-onlinedev` | onlinedev | 3,175 | — |
**实际做法与原计划的差异**(实测依赖图,非拍脑袋):
- ① 计划的分组按「官方模块名」切,实测后把**无跨包依赖**的 `scheduletask`/`core` 并进 system ⇒ 少两条 crate 边;
- ② 🔴 **`sspf-compat-online-dev` → `sspf-compat-onlinedev`** —— Rust 包名不能带连字符(`use sspf-compat-online-dev::…` 编译不过);官方拼写 `onlineDev` 去分隔符即 `onlinedev`(2026-11-04 由中间态 `online_dev` 统一回来);
- ③ 跨包依赖只有 **3 条**,全是单向 ⇒ 不成环:`permission→system`、`ext→system`、`ext→msg`。
**闸门改造**:
- `check-arch.sh` 新增 **`PLAT_SRC_DIRS`**(动态 glob:core + 7 个 compat 包 + 壳)⇒ AR9/AR10 都扫真源;
- `check-arch.sh` 新增 **AR12**(契约面各包彼此独立,白名单 3 条单向边,**Cargo.toml 级**判据);
- `check-contract-scan.py` 动态收编所有 `crates/sspf-compat-*/src`(**不写死列表**);
- `check-boundary.sh` 新增动态 `COMPAT_DIRS` ⇒ CP1/CP2 纳入契约面包;
- 修 8 条引文(路径改到新真源;**行号 1:1 未变** ⇒ M4 迁移是纯搬运)。
**🔴 本批踩的三个坑(都是「尺子是假的」)**:
1. **CC6 守卫推导静默失效** —— M4 搬迁后 `check-contract.sh` **首次跑就 10/10 全绿**(M2/M3 都报红)⇒ 可疑。
核实 `check-contract-scan.py` 的 `compat_dirs` **只收了 `sspf-compat-core`** ⇒ 守卫推导读的是转发壳(无函数体)⇒ 尺子已废。
**反向验证**:改坏真源 `permission.rs:135` 的 `EN_ROLE`→`EN_ACTION` ⇒ CC6 精确报出;还原后恢复 10/10。
2. **CP1 业务标识符未扫契约面包** —— **反向验证**:往 `crates/sspf-compat-msg/src/msg_center.rs` 插
`const LEAK_PROBE: &str = "demo_item";` ⇒ CP1 精确报出该行;还原后恢复 11/11。
3. 🔴 **macOS 的 BSD grep 不支持 `\s`**(POSIX ERE)—— AR11/AR12 的 Cargo.toml 级判据都写成
`grep -E '^\s*sspf-compat-...'` ⇒ **永远匹配不到 ⇒ 永远"通过"**。
是 **AR12 反自证第一次跑就失败**暴露的。修复:全部改成 `[[:space:]]`;全仓扫过 `scripts/*.sh`,只有这一处。
**🔴 教训(已写进计划文档 §12)**:① 闸门判据里的正则**必须用反自证验证过一次**才敢信
(`grep` 不报错 + 退出码 0 + 打印 `ok` = 三重「看起来正常」);② 收编新目录一律用 **glob**,
写死路径列表必然在某次新增包时漏掉 ⇒ 尺子静默失效;③ 搬迁后第一反应不该是「全绿」而是「可疑」——
M2/M3 搬迁后闸门都报红(正常),M4 首次跑就 10/10 ⇒ 反而是尺子坏了的信号。
**出口判据(全部达成)**:
`cargo build --workspace` 零警告;`cargo test --workspace` = **695 passed / 0 failed**(与 M1 基线完全一致);
`check-arch` **15/15**;`--self-test` **7/7**(新增 AR12 反自证);`check-boundary` 11/11;
`check-contract` 10/10(反自证 12 例全过);`check-module` 123/123;`check-citations` 4/4;
`check-naming` 3 通过 / 0 失败 / 1 提示;`verify.sh --smoke` **14 步全绿**(300.9s)。
**⏭ 下一步 = M5(`sspf-lowcode-exec`)**:迁 `lowcode_{crud,ddl,check,seed}.rs`(2,674 行),
新 crate `crates/sspf-lowcode-exec`(依赖 sspf-lowcode + core + store + mcp)。
⚠️ M5 必须同步加 **AR13**(依赖白名单)+ 重跑全部 `--self-test`。
---
## 0-0-pre6. 2026-11-03 20:10 **M5 完成**:低代码执行层下沉(tag `v0.1.5-m5`)
**做了什么**:`src/backend/src/lowcode_{crud,ddl,check,seed}.rs`(2,674 行)下沉到 `crates/sspf-lowcode-exec/`,
原路径全变 5 行转发壳(`pub use sspf_lowcode_exec::<mod>::*;`)⇒ **CLI(`--seed-lowcode-demo`)与 MCP 适配器零感知**。
| 依赖 | 为什么 |
|---|---|
| `sspf-lowcode` | 纯计算层(解析/校验/SQL 生成)—— **AR7 白名单不动** |
| `sspf-core` | `Db` / `ids::new_uuid` / `config::Profile` / `registry::MAIN_SYSTEM_ID` |
| `sspf-store` | `Db` / `pglite` 的**真源**(`sspf-core::db` 只是转发壳) |
| `sspf-mcp` | `ToolError` —— 执行失败要能变成给 AI 看懂的结构化错误 |
| `pglite-rs` + `chrono` + `serde_json` | 真实库 / `now_iso()` 时间戳 / JSON payload |
**与原计划的差异**:计划写依赖 `{lowcode, core, store, mcp}`,实际多了 `pglite-rs` + `chrono` + `serde_json`
—— ① `pglite::ToSql` / `pglite::Error` 是**直接用**的(不只经 `Db`);② `now_iso()` 用 `chrono::Local::now()`;③ JSON payload 转换。
另外**未提权任何 `pub(crate)`**(与 M3/M4 不同:这四个模块的对外接口**本来就是 `pub`** ⇒ 一行可见性改动都没有)。
**闸门改造**:
- `check-arch.sh` 新增 **AR13**(两层:依赖白名单 + 源码不许 `use sspf_pack_*`);反自证 **8/8**
(**两处都注入**:越界依赖 `axum` + 业务包引用 `use sspf_pack_asset::…`,且**按路径分别验**)。
- `check-boundary.sh` 新增 `LOWCODE_EXEC` ⇒ **CP1**(业务标识符)/ **CP2**(`use crate::modules`)纳入执行层真源。
**反向验证**:往 `crates/sspf-lowcode-exec/src/lowcode_check.rs` 插 `const LEAK_PROBE: &str = "demo_item";`
⇒ CP1 报红(PASS=10/FAIL=1);还原后恢复 11/11。
- `check-contract-scan.py` **不用改** —— 契约里**零 lowcode 端点**(低代码是 MCP 工具不是 HTTP 路由)
⇒ 本批不影响 CC1–CC10。
**🔴 本批的坑(改写规则要分清两件事)**:改写时把 `use crate::lowcode_ddl;` 一并改成了 `use crate::ddl;`
⇒ 编译报 `cannot find module or crate lowcode_ddl`。
**教训**:搬 crate 只改**跨 crate 的前缀**(`crate::platform::` → `sspf_core::`),
**模块名一律不动**(新 crate 里模块仍叫 `lowcode_crud` / `lowcode_ddl` / `lowcode_check`);
文档内链(``[`crate::lowcode_crud`]``)也不能跟着改(改了就变死链)⇒ 已单独修回。
**出口判据(全部达成)**:
`cargo build --workspace` 零警告;`cargo test --workspace` = **695 passed / 0 failed**(与 M1 基线完全一致);
`check-arch` **17/17**;`--self-test` **8/8**;`check-boundary` 11/11;`check-contract` 10/10(反自证 12 例全过);
`check-module` 123/123;`check-citations` 4/4(**零条引文**指向 lowcode 旧路径);`check-naming` 3/0/1;
`verify.sh --smoke` **14 步全绿**(377.6s)。
**⏭ 下一步 = M6(`sspf-mcp-adapter`)**:迁 `mcp_adapter.rs`(2,652) + `mcp_compat.rs`(631),
新 crate 依赖 sspf-mcp + sspf-core + **所有 compat 包**(决策③)⇒ 它是依赖图里**唯一高扇入节点**。
⚠️ M6 必须同步做:① 新增 **AR14**(`sspf-mcp-adapter` 之外不许依赖 compat 包);
② `check-contract-scan.py` 的 `plat_files` 必须收 `crates/sspf-mcp-adapter/src/`(守卫常量在里面,漏收 ⇒ CC6 假漂移);
③ `check-boundary.sh` 的 CP1/CP2 纳入 MCP 适配层真源;④ 重跑全部 `--self-test`。
---
## 0-0-pre7. 2026-11-03 20:40 **M6 完成**:MCP 适配层下沉(tag `v0.1.6-m6`)
**做了什么**:`src/backend/src/mcp_{adapter,compat}.rs`(共 3,283 行)下沉到 `crates/sspf-mcp-adapter/`,
原路径全变 5 行转发壳(`pub use sspf_mcp_adapter::<mod>::*;`)⇒ **`--mcp` 启动路径与集成测试零感知**。
| 依赖 | 为什么 |
|---|---|
| `sspf-mcp` | `PlatformAdapter` / `ToolError` / `EnvInfo` —— 工具契约层 |
| `sspf-core` | `AppState` / `Db` / `ids::new_uuid` / `cipher::md5_hex` / `envelope::ActionResult` |
| `sspf-compat-{system,permission,workflow,onlinedev}` | `mcp_compat.rs` **直调它们的 handler**(与 HTTP 路由同一个函数 ⇒ 语义零漂移) |
| `sspf-lowcode` + `sspf-lowcode-exec` | 动态 CRUD 工具:解析设计稿(纯计算)+ 连库执行 |
| `axum` | handler 的 extractor(`State` / `Path` / `RawQuery` / `HeaderMap`)与 `Json<ActionResult>` |
| `pglite-rs` | `ToSql` 参数绑定(把 JSON 值转成 SQL 参数) |
**与原计划的差异**:原计划写「依赖 sspf-mcp + sspf-core + sspf-compat-*」,
实际只依赖**四个** compat 域包(`system` / `permission` / `workflow` / `onlinedev`)——
`mcp_compat.rs` 真正调到的就这四个域,`msg` / `ext` / `compat-core` **不必依赖**(少三个边 ⇒ 依赖图更瘦)。
另外**未提权任何 `pub(crate)`**(两个文件的对外接口本来就是 `pub`)。
**跨 crate 路径改写**(🔴 只改**前缀**、模块名不动 —— M5 的教训):
- `crate::platform::db::valid_table` → `sspf_core::db::valid_table`
- `crate::platform::state::AppState` → `sspf_core::state::AppState`
- `crate::platform::compat::workflow::…` → `sspf_compat_workflow::workflow::…`(**多一段模块名**)
- `crate::lowcode_crud::…` → `sspf_lowcode_exec::lowcode_crud::…`
- `crate::mcp_compat::…` **不动**(同 crate 内)
**闸门改造**:
- `check-arch.sh` 新增 **AR14**(两层:依赖白名单 + 源码不许 `use sspf_pack_*`);反自证 **9/9**
(**两处都注入**:越界依赖 `sspf-contract` + 业务包引用 `use sspf_pack_asset::…`,且**按路径分别验**)。
- `check-boundary.sh` 新增 `MCP_ADAPTER` ⇒ **CP1**(业务标识符)/ **CP2**(`use crate::modules`)纳入适配层真源。
**另加 CP1'' 扫描面反自证**:往新 crate 注入业务包真实表名 ⇒ 必须被抓到(抓不到 = 扫描面漏了新 crate = 尺子已废)。
- `check-contract-scan.py` **不用改** —— 契约面 handler 的真源仍在 `sspf-compat-*` 各包,
适配层只是**调用方**(不是端点实现方)⇒ CC1–CC10 不受影响(实测 10/10,反自证 12 例全过)。
**🔴 本批的发现(闸门暴露的既有问题)**:
把新 crate 纳入 CP1 扫描面后,CP1 **立刻抓到 5 处业务标识符泄漏**
(`permission.asset.dataResource` × 2 / `asset/DataResource` × 2 / `asset_data_resource` × 1)——
它们在 `mcp_adapter.rs` 的 **hint 提示语**与**单测断言**里,此前**不在扫描面内**所以一直隐形。
⇒ 已改成**通用形态**(`permission.<模块>.<资源>` / `<模块>/<资源>` / `data_resource`)。
**这正是「闸门必须与迁移同步改」的价值**:不扩扫描面 ⇒ 这 5 处会跟着代码搬进 crates 继续潜伏。
**出口判据(全部达成)**:
`cargo build --workspace` 零警告;`cargo test --workspace` = **695 passed / 0 failed**(与 M1 基线完全一致);
`check-arch` **19/19**;`--self-test` **9/9**;`check-boundary` **12/12**(契约登记已同步改为 12);
`check-contract` 10/10(反自证 12 例全过);`check-module` 123/123;`check-citations` 4/4;`check-naming` 3/0/1。
**⏭ 下一步 = M7(收口)**:删 `platform/` 转发壳、全仓 import 改成 `sspf_core::…` / `sspf_compat_<域>::…`、
拆 `tests/`(单元测试随代码进 crate、集成测试留壳测装配)、补全最终闸门。
⚠️ M7 是**大爆炸改动**(编译器会报几百处)⇒ 必须先打 tag、可回滚。
## 0-0-pre8. 2026-11-03 21:30 **M7 完成**:删转发壳,壳瘦身收口(tag `v0.1.7-m7`)
**做了什么**:`src/backend/src/platform/` 的 **38 个转发壳整体删除** ⇒ 平台能力**只有真源**
(在 `crates/`),壳层不再存在。
| 项 | 数量 | 说明 |
|---|---|---|
| 删除 `src/backend/src/platform/` | **38 个壳** | 平台层从「真源 + 壳」变成「只有真源」 |
| 改写 `crate::platform::X` | 44 处 / 9 文件 | → `sspf_core::X` |
| 改写 `ssw_platform::platform::X` | 229 处 / 38 文件 | → `sspf_core::X`(含 37 个集成测试文件) |
| 新增 `src/backend/src/compat.rs` | 1 个**别名表** | 16 个契约面域聚成 `compat::<域>::<handler>` |
| 移动 `platform/test_support.rs` | 1 个文件 | → `src/backend/src/test_support.rs` |
**🔴 为什么 `test_support.rs` 必须留壳侧**:它调用**装配根**的
`crate::bootstrap::ensure_schema_all`(把平台表 + 业务包的表一起建好)
⇒ 它**认识业务层** ⇒ 下沉到 `crates/sspf-core` 会让平台核心反向依赖业务包 ⇒ **破 AR9**。
⇒ 它属于**装配根**的一部分,不是平台能力。
**🔴 关键决策:保留 `compat::<域>::` 这条路径(而不是 1,010 处全改)**
`routes.rs` 里 `compat::<域>::<handler>` 有 **1,010 处**。逐处改成
`sspf_compat_system::system::<handler>` 看着更干净,但会连带:
- 契约扫描器的 `plat_key` 推导规则(**尺子的命脉**);
- 契约文档里的路径;
- 风险面放大 10 倍。
⇒ 改用**别名表**(`src/backend/src/compat.rs`,16 个域各一条 `pub use`):
**只改 1 个文件**,1,010 处路由注册**一字不动** ⇒ 尺子的推导规则不变。
**🔴 M7 的核心技术风险(已提前修掉)**
契约扫描器原本用「**路径段数**」判定「是不是契约面」(两段 ⇒ 契约面,一段 ⇒ 平台核心)。
M7 把平台核心也变成两段(`sspf_core::sys::user_list`)⇒ 旧规则会把它误判成契约面
⇒ `plat_key` 从 `sys` 变成 `compat__sys` ⇒ **守卫推不出来** ⇒ CC6 静默退化成「全是 WARN」
⇒ **尺子变瞎**(实测已验证:`sspf_core::sys::user_list` ⇒ `plat_key=compat__sys`)。
⇒ 新规则改为**按 crate 名判定**(`derive_plat_key`):第一段是 `sspf_compat_*` ⇒ 契约面;
否则 ⇒ 平台核心。⇒ 与路径深度**无关** ⇒ 改写前后推导结果**一致**。
⇒ 加了 **20 条断言式反自证**(14 条推导自证 + 6 条等价自证):
`sys` ≡ `sspf_core::sys`、`compat::system` ≡ `sspf_compat_system::system`……
(CC6 的反自证是「改契约」型的,**证不到推导规则本身** ⇒ 必须直接断言。)
**🔴 新增闸门 AR15(防删掉的东西复活)**
删壳之后**没有编译器兜底**了:只要有人重建 `platform/` 壳目录 + 把 import 改回去
⇒ **一切照常编译、测试照常全绿**,而 M2–M7 的架构收益**全部蒸发**,且无闸门报红。
⇒ AR15 钉住三层:① 不许 `crate::platform::`;② 不许 `ssw_platform::platform::`;
③ `src/backend/src/platform/` 目录不许有 `.rs` 文件(**空目录不算** —— git 不跟踪空目录)。
**🔴 本批踩到的两个真 bug(都是闸门自证抓出来的)**:
1. **AR11 自证失败**:删掉壳路径后,AR11 的判据 `grep -n` 只剩**一个文件** ⇒ 输出**不含路径**
⇒ 自证里 `grep -q "sspf-compat-core/src/helper.rs"` **永远匹配不到**
⇒ 尺子明明抓到了违规,自证却报「尺子是假的」。⇒ 改用 `grep -H`(强制带路径前缀)。
2. **AR15 假红**:自证里 `mkdir -p` 出来的空目录 `rmdir` 失败后残留 ⇒ 主检查报「目录复活」
⇒ 判据改成「目录里**有** `.rs` 文件」。
**出口判据(全部达成)**:
`cargo build --workspace` 零警告;`cargo test --workspace` = **695 passed / 0 failed**(与 M1 基线完全一致);
`check-arch` **20/20**;`--self-test` **10/10**;`check-boundary` **12/12**;
`check-contract` 10/10(反自证 **12 例 + 20 条推导断言**全过);`check-module` 123/123;
`check-citations` 4/4;`check-naming` 3/0/1。
**✅ 迁移全部完成**:M1–M7 七个批次走完 ⇒ `crates/` 现有 **17 个包**,
`src/backend/src/` 只剩**装配**(bootstrap / routes / compat 别名表 / modules)+ **业务层**。
---
## 0-0. 2026-11-02 23:13 验证修复轮(官方前端 + dacli 真跑后修的)
用官方 vue 前端 + dacli + 586 条端点探针做过一轮真实系统性验证(报告:
`docs/verify-report-2026-11-02.md`)。**已修**(都有回归测试):
| 编号 | 修了什么 |
|---|---|
| P0-1 | `ResetPassword` 改读官方 `userPassword`(**已是 md5,原样落库,不再二次哈希**);兼容 `password`;改密后吊销该用户会话 |
| P0-2 | 三个 `code=500`(`visualdev/OnlineLog`、`visualdev/share/Selector`、`message/Monitor/{id}/RecordList`)—— count SQL 与参数对齐;`RecordList` 同时补上 `f_monitor_id=$1`(原先会串所有监控的记录) |
| P1-1 | `updatePasswordMessage` 改 `200 + data:null`(官方前端每页无条件调用且不 catch) |
| P2-3 | `ensure_schema_all` 不再用 `if let Ok(reg)=packs()` 吞掉装载错误 |
| P3-1 | `ModuleDataAuthorizeLink` 路径参数改手工解析,非法值返信封 400(不再吐纯文本) |
**有意没修**:① WebSocket `/api/message/websocket/{token}`(要真推送通道,静默挂起=假装连上);
② 四个业务菜单在官方 vue 里仍是死链(缺 views,属集成阶段;React MVP 需要这些菜单)。
⇒ 复验:`cargo test --workspace` **667 passed / 0 failed**;`verify.sh --smoke` **14 步全绿**;
586 探针 **0 个 404/405/500**;OPTIONS 765 条全 405。
---
## 0-0-bis. 2026-11-02 23:40 MCP 扩面:26 → 52 个业务工具
参考 dacli 的命令面,把 MCP 从「26 个工具」扩到 **52 个**(4 元工具不变,仍是分层加载):
| 域 | 新增 |
|---|---|
| workflow | `template.list/info/create/update/delete/selector` + `task.list`(7) |
| form | `form.create / update / delete` + `form.selector`(**release 本仓未支持,刻意不注册**) |
| ops | `ops.health / logs / online / schedule.list / db.stats`(5) |
| dict | `type.update / type.delete / data.create`(3) |
| menu | `menu.info / menu.update`(2) |
| permission | `role.create / role.delete / user.delete` + `organize.tree`(4) |
| context | `context.app.list`(1) |
🔴 **实现方式**:不重写 SQL,`src/backend/src/mcp_compat.rs` **进程内直调契约面 handler**
(与 HTTP 注册同一个函数),只负责造管理员请求头 + 把 `ActionResult` 转成 `ToolError`。
⇒ 校验/默认值/软删语义只有一份。代价:MCP 适配器构造 `admin` 会话,**只适用于本地开发**。
🔴 新增 `src/backend/tests/mcp_tools_it.rs`(6 条)覆盖 CRUD 闭环与结构化失败;
`scripts/mcp-smoke.sh` 仍全绿(4 元工具 + 分层加载未被破坏)。
---
## 0-0-ter. 2026-11-03 批次 21–23:官方前端端点补到 **900/900**
按 `scripts/fe-gap.py` 的缺口表,把最后三族做完(另收尾 4 条零散缺口):
| 批 | 族 | 条数 | 落地 |
|---|---|---|---|
| 21 | `aiCenter` | 75 | 智能体 / 供应商 / 模型 / 知识库 / 文档 / MCP / 提示词 / 服务 / 技能 / 工具 / 会话历史 **真落库**(官方 `base_ai_*` 表);文档切片 + 关键词召回真做 |
| 22 | `extend` | 64 | CRM / 销售订单 / 员工 / 甘特 / 控件示例 / 邮件 / 大数据 **真落库**(新增 `ext_*` 15 张) |
| 23 | `teamwork` | 40 | 文件**元数据**(目录 / 移动 / 复制 / 分享 / 回收站 / 标签 / 空间)+ 日程 **真落库**(`ext_document*` 3 张 + 官方 `base_schedule`) |
| 收尾 | systemData / onlineDev | 4 | `Dataset/Selector`、`DatasetLog/{id}`(如实空分页)、`InterfaceOauth/saveInterfaceList`、`ShortLink/{id}/Config`(与旧 `getConfig/{id}` 同 handler) |
🔴 **实现方式**:新增 `src/backend/src/platform/compat/res.rs` **通用资源引擎**
(`Res{table, fields, keyword, order, scope}` ⇒ list / info / create / update / delete),
三族里约 150 条是薄封装;有业务语义的动作(版本、复制、分享、回收站、切片/召回、日程)手写。
🔴 **新增表的登记**:`ext_*` 18 张既不是 `base_*` 平台表、也不是业务包表 ⇒
在 `sspf_store::db::{EXTEND_TABLES, TEAMWORK_TABLES}` 登记,并在 `crates/sspf-admin/src/main.rs` 的
**孤儿 DDL 闸门**里放行(与 `REPORT_TABLES` / `WORKFLOW_TABLES` 同一套机制)。
🔴 **诚实失败**(见 `docs/known-limitations.md` §I):LLM 推理、供应商连通性、MCP 同步、
SMTP/IMAP、Excel 导入导出、文件上传/打包/预览 —— 一律 `400` + 人话,**不返假成功**。
⇒ 复验:`cargo test --workspace` **673 passed / 0 failed**;`verify.sh --smoke` **14 步全绿**;
723 条端点探针 **0 个 404/405/500**;OPTIONS **948 条全 405**;
`check-contract` PASS=10(契约 948 条 / 官方台账覆盖 **934/940**,implemented 742 / partial 192 / absent 6);
`fe-gap` **900/900(100%)**。
---
## 0-0-quater. 2026-11-03 批次 24:**官方移动端**端点(39 条)
用户提「有个移动端版本,你扫描一下api,一起做掉吧」⇒ 补官方移动端
(`jnpf/7.0-jnpf-app-vue3`)那批**只在移动端出现**的端点。
🔴 **为什么 Web 前端 900/900 时没覆盖到**:移动端与 Web 前端**共用同一套后端**,
但**端点集合不同** —— 移动端多出「App 菜单 / App 用户 / 版本号 / 扫码登录 / 工作日志 /
常用菜单 / 移动端首页 / 移动端日程 / 移动端流程引擎 / 审批前后动作」等一族,
这些**不在官方 Web 前端 `src/api/**` 里** ⇒ `fe-gap.py` 天然扫不到。
🔴 **真源与三方交叉校验**:官方移动端 `api/**`(22 个文件 / 238 处调用)×
官方 Java 控制器(`@XxxMapping` 1197 处)× 本仓 `routes.rs` 真实注册路由
⇒ 差集从「看似 40 条」收敛到 **44 条路径缺失 + 10 条 method 差异**,最终补齐 39 条
(另 1 条归一化假阳性已被既有路由覆盖)。
| 族 | 端点 |
|---|---|
| App 菜单 | `/api/app/Menu`、`/sys`、`/getMenuList`、`/getChildList/{id}` |
| App 用户 / 版本 | `/api/app/User/{id}`、`/api/app/Version` |
| 工作日志 | `/api/extend/WorkLog`(CRUD)+ `/Send` + `/Receive` |
| 扫码 / 第三方登录 | `/api/oauth/confirmLogin/{ticket}`、`/api/oauth/socials/{render,app/callback}/{source}`、`/api/permission/socials/login`、`POST /api/oauth/logoutCurrentUser` |
| 组织用户 | `/api/permission/Users/getOrganization`、`/UserCondition`、`/GetListByAuthorize/{organizeId}` |
| 首页 / 常用 / 日程 | `/api/system/HomeData/app`、`/MenuData/{getAppDataList,getDataList}`、`/Schedule/AppList`、`/Location/regeo`、`/tenant/saas/inviteurl` |
| 消息 / 待办 | `/api/message/getUnReadMsgNum`、`/SendMessageConfig/getSendConfigList`、`/api/visualdev/Dashboard/MyFlowTodo` |
| 流程引擎 / 审批动作 | `/api/workflow/template/CommonFlowTree`、`/api/workflow/Engine/flowTemplate*`、`/api/workflow/Engine/FlowBefore/{RecordList,RejectList,SubFlowInfo}/{id}`、`/Cancel/{id}` |
🔴 **新增**:`src/backend/src/platform/compat/mobile.rs`(39 个 handler)、
`ext_work_log` 表(登记进 `sspf_store::db::EXTEND_TABLES` ⇒ 孤儿 DDL 闸门自动放行)、
`src/backend/tests/mobile_it.rs`(11 条集成测试)、
`scripts/official-mobile-sources.json`(39 条出处台账,供 `gen-contract-endpoints.py` 生成 `[OFFICIAL]` 行)。
官方移动端仓库落位 `~/Desktop/workspace/jnpf/7.0/frontend/app` ⇒ 引文闸门能解析
`api/<file>.js:<行号>`。
🔴 **判别头不变**:移动端 `utils/request.js` 同样带 `Vue-Version: 3` ⇒ 仍走**面 B**。
另外 `/api/oauth/Login/socials` 补了 **GET**(官方 `LoginController.java:117` 的
`method={GET,POST}` 通配同收;Web 前端用 POST、移动端 `api/common.js:563` 用 GET)。
### 🔴 本批次踩到的三个真 bug(都是写完测试才暴露的,值得记住)
| # | 坑 | 真相 | 怎么发现的 |
|---|---|---|---|
| 1 | **`user.account` ≠ `user_id`** | 官方 `f_creator_user_id` / `f_to_user_id` 存的是 **user id**(`UserProvider.getUser().getUserId()`),不是账号 ⇒ 用 account 会让「我发出的」永远为空 | `mobile_it.rs` 断言 `creatorUserId == userInfo.userId` |
| 2 | **`f_handle_status` 口径** | 官方 `FlowNature.java:231/235`:**NULL=待办 / 0=拒绝 / 1=通过**。用 `COALESCE(...,0)=0` 会把「已拒绝」也算进待办 ⇒ 待办必须判 `IS NULL`;驳回落库写 **0**(不是 3) | `flow_before_cancel_writes_official_status_codes` 逐项断言 |
| 3 | **常用菜单的真源是 `base_module_data`** | 官方 `ModuleDataServiceImpl.getAppDataList` 走 `base_module_data`(`f_module_type='App'`,即 `JnpfConst.APP`),**不是** `base_app_data`;后者 `f_object_type` 是 VARCHAR,被当数字用会**运行期 SQL 报错** | `mobile_it.rs` 打 `/api/system/MenuData/getAppDataList` 时 Postgres 报 `COALESCE types character varying and integer cannot be matched` |
⇒ 复验:`cargo test --workspace` **684 passed / 0 failed**(基线 673 + 11);
`verify.sh --smoke` **14 步全绿**;`check-contract` PASS=10(契约 **988** 条 /
官方台账覆盖 **974/979**);`check-citations` PASS=4(1202 条引文全定位);
`[ENDPOINT]` 面 B **958** 条(+40)。
🔴 **顺手修的既有 bug**:`scripts/mcp-smoke.sh` 两处 `"$RC(期望 0)"` —— bash 变量后紧跟
全角括号会被并入变量名 ⇒ `RC(` unbound variable(正是 `MEMORY.md` 记的那个坑)。
已改成 `"${RC}(期望 0)"` / `"${BIN}(先 cargo build)"`。
---
## 0-0-quinque. 2026-11-03 批次 25:**官方大屏**(blade-visual,53 条)
用户提「大屏 你也对照 数据库 前端 api 后端源码 做了吧」⇒ 补官方**大屏设计器**
(`jnpf-visualdata`)这一族。**这一族本仓此前只有 1 条占位**(`visual/Selector`,
而且是「恒失败」实现)⇒ 真实缺口 **52 条**。
🔴 **这一族必须三源对照**(用户明确要求,且三者缺一不可):
| 源 | 位置 | 作用 |
|---|---|---|
| 后端源码 | `jnpf-java-boot/jnpf-visualdata/**`(**8 个 Controller**) | 路径 / 方法 / 返回形状 |
| 数据库 | `7.0/database/PostgreSQL/JNPF-PostgreSQL.sql`(**9 张 `blade_visual*` 表**) | 列名 / 类型 / 主键 |
| 前端 api | `7.0-jnpf-web-datascreen-vue3/src/api/*.js`(**9 个文件**) | 请求形状 / 入参位置(query vs body) |
🔴 **前端仓只在 git-code MCP 里**(`jnpf/7.0-jnpf-web-datascreen-vue3`),本地没有
⇒ 已浅克隆到 `~/Desktop/workspace/jnpf/7.0/frontend/web/jnpf-web-datascreen-vue3`
(引文闸门能解析 `src/api/<file>.js:<行号>`)。`axios.js:68` 正是
`config.url = configUrl + '/visual/proxy'` —— 行号已核对。
🔴 **列族是 Blade 系,不是本仓的 JNPF 系**(**故意不改名**,好让「逐列对照官方 DDL」成立):
| | 本仓其它契约面 | 官方大屏 |
|---|---|---|
| 主键 | `f_id` | `id` |
| 软删 | `f_delete_mark` | `is_deleted`(**只有 3 张表有**) |
| 审计时间 | `f_creator_time` | `create_time` |
⇒ **不能复用 `compat::res` 通用资源引擎**(那套写死了 `f_` 列族)⇒ 新建
`BRes` 专用层(`src/backend/src/platform/compat/visualdata.rs`,约 2000 行)。
🔴 **官方形状不统一是既有事实,照抄不改**:
| 端点 | 官方返回 |
|---|---|
| `GET /visual/list` 等分页族 | **`VisualPageVO`** = `{records, current, size, total, pages}`(**不是** `PageListVO`) |
| `GET /category/list` / `GET /visual/category` / `GET /db/db-list` | **裸数组** |
| `GET /map/lazy-list` | **裸数组** |
| `GET /map/data` | **裸字符串**(官方 Java 返回类型是 `String`,不是 `ActionResult`) |
| `POST /visual/GetApiData` / `POST /visual/proxy` | **裸字符串** |
| `GET /visual/Selector` | **`ListVO`** = `{list:[…]}`(分类 → 大屏**两级树**) |
| `POST /visual/save` | `{id}` |
| `POST /visual/copy` | **裸 id 字符串** |
🔴 **分页入参名也是官方的**:`size`(默认 **10**)/ `current`(默认 1)
(`VisualPagination.java:21/24`)—— **不是**本仓常用的 `pageSize`(20) / `currentPage`。
🔴 **两处 Java 字段名 ≠ 物理列名**(投影时显式改名):
- `blade_visual_map.map_level` ⇒ VO 字段 **`level`**
- `blade_visual_record.fsql` ⇒ VO 字段 **`sql`**
🔴 **删除走 query**(`ids` 逗号分隔,**不在 body**)—— 前端 `delObj(id)` 是
`params: {ids: id}`,官方 Java 是 `@RequestParam("ids")`。
软删只对 `blade_visual` / `blade_visual_category` / `blade_visual_db` 三张表,
其余 6 张官方是**物理删**。
🔴 **新增**:`src/backend/src/platform/compat/visualdata.rs`(52 个新 handler)、
`src/backend/tests/visualdata_it.rs`(**11 条**集成测试)、
`scripts/official-visualdata-sources.json`(53 条出处台账)、
`src/backend/db/schema.sql` 追加 9 张 `blade_visual*` 表(DDL **逐字照官方**)、
`crates/sspf-store/src/db.rs` 新增 `VISUALDATA_TABLES`(9 张,孤儿 DDL 闸门自动放行)。
### 🔴 本批次踩到的三个真 bug(写完测试才暴露)
| # | 坑 | 真相 | 怎么发现的 |
|---|---|---|---|
| 1 | **`INSERT has more expressions than target columns`** | `create()` 里 `cols` 写了 `id` 但 `slots` 从第 2 个值开始 ⇒ 列数比值数多 1;另外 `create_time` 只 push 了 slot 没 push column | `visualdata_it.rs` 全线 `code=500` |
| 2 | **`syntax error at or near "COALESCE"`** | 软删谓词写成裸表达式,却被拼在 `WHERE id = $1` **后面**(没 `AND`)⇒ PG 把 `COALESCE` 当关键字起始 | `visualdata_bare_array_shapes` 报 500 |
| 3 | **官方 `title` 是 `like` 不是 `eq`** | 官方 `VisualServiceImpl.java:49` 是 `queryWrapper.lambda().like(...)`;`assetsName` / `globalName` / `name` 全部同款 ⇒ 过滤必须 ILIKE + 两端 `%` | 写「按 title 过滤命中 0 行」时发现 |
🔴 **一个口径澄清**(`paging_of` 的注释曾与代码不符,已改注释):
官方 `VisualPaginationModel` **没有** `pageSize` / `currentPage` 字段
⇒ 本仓**只认** `size` / `current`(收了别的名字反而让「照抄官方」失真)。
⇒ 复验:`cargo test --workspace` **695 passed / 0 failed**(基线 684 + 11);
`verify.sh --smoke` **14 步全绿**(793.9s);`check-contract` **PASS=10**
(契约 **1040** 条 / 官方台账覆盖 **1026/1031**,implemented 815 / partial 211 / absent 5);
`check-citations` **PASS=4**(1258 条引文全定位);`[ENDPOINT]` 面 B **1010** 条(+52)。
---
## 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)**;
剩下体量最大的仍是 `aiCenter`(75) / `extend`(64) / `msgCenter`(50) / `teamwork`(40)
—— **基本都属于「本仓没这个模块」**(`workFlow`(104) 与 `onlineDev`(101) 已分别在
批次 19 / 17 清零)。
(🔴 批次 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-03 批次 21–23 —— aiCenter / extend / teamwork 收尾)
**📌 当前数字(以此为准,下面各批的「当时数字」仅存档)**:
- 契约端点 **948 条**(面 A 28 + 面 B **918** + 两面共用 2);`tables` → **171**
(`schema.sql` **170** 张 + 业务包 1 张;平台表 `BASE_TABLES` **123** +
`WORKFLOW_TABLES` **24** + `REPORT_TABLES` **2** + 内嵌业务表 3 +
`EXTEND_TABLES` **15** + `TEAMWORK_TABLES` **3**)。
- `cargo test --offline --workspace` = **全绿 0 failed**(**673 passed**;主 lib 105;
`batch19_it` **7**、`batch20_it` **6**、`verify_fixes_it` **7**、`mcp_tools_it` **6**、
`ext_batches_it` **6**)。
- 闸门全绿;`check-contract` `PASS=10 FAIL=0`,官方端点覆盖 **934/940**
(implemented 742 / partial 192 / absent 6;oos 1 单列)。
- `python3 scripts/fe-gap.py`:合计 **900 / 900(100%)** —— **`aiCenter` 75/75、
`extend` 64/64、`teamwork` 40/40、`msgCenter` 50/50、`workFlow` 104/104、
`core` 27/27、`system` 196/196、`permission` 137/137 全部 100%;
`systemData` 106/106、`onlineDev` 101/101**。
- 🔴 **批次 21–23 把官方前端的最后 183 条缺口做完了**(179 + 收尾 4):
见 §0-0-ter 与 `docs/known-limitations.md` §I。真落库 158 条、诚实失败 21 条
(LLM / SMTP / IMAP / MCP / 文件服务 / Excel 一律 `400` + 人话)。
- 🔴 **批次 20 把 msgCenter 做完了**(用户 2026-11-02 指示「msgCenter 50 去做完吧」):
官方前端 `src/api/msgCenter/**` 的**全部 50 个接口** ⇒ 落 **51 条面 B 端点**
(50 条前端接口 + 1 条**动态路径别名**,见下),新增 `platform/compat/msg_center.rs`。
**真落库 44 条**(消息账号 / 发送配置 / 模板(含参数、变量两张子表)/ 敏感词 /
接收配置 / 监控记录 / 供应商,落官方 `base_msg_*` + `base_intg_supplier*` 表,DDL 逐字照官方)、
**诚实失败 7 条**(本仓**无 HTTP 客户端** ⇒ 接不了任何消息服务商:
测试发信 3 + 测试连接 1 + 同步模板 1 + 重发 1 + 动态路径别名 1)。
**没有一条返假数据**(不返假发送结果、不返假模板、不返假连通性)。
- 🔴 **批次 19 把 workFlow 做完了**(官方 `jnpf-flowable` + `api/workFlow/**` 共 **104 条**):
**真实现 62 条**(流程模板/版本/节点/任务/评论/委托/监控的**元数据**面,
落在**官方 24 张 `workflow_*` 表**上,DDL 逐字导入)、
**诚实失败 42 条**(引擎动作 **27** + 无文件服务 **2** + 无在线表单设计器 **13**)。
**没有一条返假数据**(不返假流程号、不返假 URL、不返假表单)。
🔴 官方流程引擎是**独立 HTTP 服务**(`FlowAbleUrl` = `<flowDomain>/api/Flow/*`),
本仓没有它 ⇒ **一切「动作类」端点一律 `400` + 人话**。
- 🔴 **批次 18 把 core 族做完了**(官方 `api/core/{auth,common,user}.ts` 共 **27 条**
⇒ 本仓落 **22 条端点**;`fe-gap` 的 `core` 列 **100%**)。
三类落地:**真实现 6 条**(锁屏解锁 / 免密票据 / 扫码凭证 4 条)、
**诚实失败 16 条**(文件族 4 + 导入族 4 + 地图族 3 + 改密通知 1 + SaaS 族 3 + socials 1),
**没有一条返假数据**(不返假 URL、不返假坐标、不假装发成功)。
🔴 **票据是本仓新增的内存表**(`platform/session.rs` 的 `TicketStore`):
官方存 Redis ⇒ 本仓无 Redis ⇒ 照 `SessionStore` 同款做进程内表(进程重启即失效)。
**两种票据不能串用**(`tkt-` / `scc-` 前缀)—— 官方也是两张不同的 Redis key。
同批还修掉一个**真偏差**:`Login/saas` 原先写成 `let _ = require_login_face_b(..)`
⇒ **丢弃了 `Err` ⇒ 实际不拦**,但静态闸门把它推成「登录」⇒ 契约标签与运行时行为不符
⇒ 已改成 `if let Err(resp) = .. { return resp; }`(官方 `TenantSaasGranter.checkTenantUser`
明确要求已有登录态)。详见 §5「批次 18 新增的坑」。
- 🔴 **批次 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`、`crates/sspf-admin/src/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` + `crates/sspf-admin/src/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`(官方后端是**独立服务**)。
### 批次 19(2026-11-02)—— workFlow 全族(104 条)+ 24 张 `workflow_*` 表
**104 条面 B 端点**(新增 `platform/compat/workflow.rs`;新增 **24 张 `workflow_*` 表**,
**官方 DDL 逐字导入**):
- **真实现 62 条** —— 流程**元数据**面:模板 CRUD / 版本 / 节点 / 任务 / 评论 / 委托 /
监控读 / 触发器读 / 事件日志读。
- **诚实失败 42 条** —— **引擎动作 27**(发起 / 审批 / 转审 / 加签 / 催办 / 撤销 /
批量审批 / 暂停 / 终止 / 复活 / 重试 …)、**无文件服务 2**(两处 `Export`)、
**无在线表单设计器 13**(本仓**没有 `visualdev_*` 表** ⇒ 表单本体查不到)。
🔴 **官方流程引擎是独立 HTTP 服务**(官方前端把引擎地址配在 `FlowAbleUrl`,
= `<flowDomain>/api/Flow/*`)—— 跟批次 17 的 Report 同款形态(官方把能力放在独立服务里)。
⇒ 本仓**只导元数据、不导 Flowable 的 `act_*` 引擎表** ⇒ 一切「动作类」端点
**`code=400` + `data:null` + 人话**,**不返假流程号、不返假 URL**。
🔴 **104 条的来源分两半**(官方 `jnpf-flowable-controller` 有 **12 个 Controller**,
本仓只登记**有官方映射**的 8 个):
- **91 条** = 8 个 Controller 的 `@XxxMapping`(`TemplateController` 25 +
`OperatorController` 25 + `TaskController` 13 + `WorkflowMonitorController` 10 +
`DelegateController` 9 + `TriggerTaskController` 4 + `CommentController` 3 +
`TriggerWebHookController` 3);
- **13 条** = 官方前端**独有**(`api/workFlow/formDesign.ts` 的 11 条 `/api/flowForm/Form/*`
+ `task.ts:51` / `flowMonitor.ts:17` 两条 `EventLog`)——
官方**整个 `jnpf-java-boot` 树里没人声明过 `/api/flowForm/Form`** ⇒ 这 13 条
`[OFFICIAL]` 的 `src` 指**官方前端行号**。
🔴 **多应用隔离只有 `workflow_template` 挂 `f_system_id`**(官方 DDL 如此)⇒
任务 / 评论的隔离**只能透传**:用 `EXISTS (SELECT 1 FROM workflow_task t
JOIN workflow_template tpl ON tpl.f_id = t.f_template_id
WHERE t.f_id = c.f_task_id AND tpl.f_system_id = $1::text)` 子查询。
🔴 **`f_type` 撞车(批次 9 的同款坑,第 N 次)**:种子列里放了 `f_type`,
`TEMPLATE_WRITE_FIELDS` 又把 JSON 键 `type` 映射到同一列 ⇒ INSERT 报
`column "f_type" specified more than once` ⇒ **要么去掉显式列,要么去掉写字段映射**。
本批的修法是「去掉显式列 + body 没带 `type` 时补默认值 `0`」。
- 回归测试 `tests/batch19_it.rs`(**7 条**):104 条路径逐条打(防 `matchit` 冲突)、
模板 CRUD 落官方表、评论/委托落库、**27 条引擎端点逐条断言「诚实失败」**、
多应用隔离、未登录 602。
### 批次 20(2026-11-02)—— msgCenter 全族(前端 50 条)
**范围**:官方前端 `src/api/msgCenter/**`(`accountConfig` / `sendConfig` / `msgTemplate` /
`sensitive` / `receive` / `monitor` / `supplier`)**全部 50 个接口**
⇒ 新增 `platform/compat/msg_center.rs` + **51 条面 B 端点**
(50 条前端接口 + 1 条**动态路径别名**,见下)。
**落地分类(一条假数据都没有)**:
- **真落库 44 条** —— 消息账号(`base_msg_account`)、发送配置(`base_msg_send` +
`base_msg_send_template`)、模板(`base_msg_template` + **两张子表**
`base_msg_template_param` / `base_msg_variable`)、敏感词(`base_msg_sensitive`)、
接收配置(`base_msg_receive`)、监控(`base_msg_monitor` / `base_msg_record`)、
供应商(`base_intg_supplier`)。🔴 **本批没加表** —— `base_msg_*` /
`base_intg_supplier*` 早就在 `schema.sql` + `BASE_TABLES` 里(官方 DDL 逐字)。
- **诚实失败 7 条** —— 本仓**没有 HTTP 客户端**(`reqwest`/`ureq` 都没有)⇒
接不了任何消息服务商 ⇒ `400` + `data:null` + 人话:
`Account/testSendMail`、`Account/{testType}`(别名)、`Send/testSendConfig`、
`Template/testSendMail`、`Monitor/{id}/Retry`、`Supplier/SyncTemplate`、
`Supplier/TestConnect`。
**本批定下的口径(都写进了契约 `[OFFICIAL]` 的 note)**:
- 🔴 **密钥字段照官方返明文**(`smtpPassword` / `secretKey`):官方 DDL 就是**明文**存
(`base_msg_account.f_smtp_password` / `base_intg_supplier.f_secret_key`),
且官方前端**要拿回来编辑** ⇒ 本仓**照官方**。
(与「用户登录口令不得外泄」是**两条不同的红线** —— 那条只管 `base_user.f_password`。)
- 🔴 **供应商的新增 / 更新跳过连通性检查**(官方落库前会**真连服务商**做「测试连接」)
⇒ 本仓**写库照做**、名称 / 编码 / 密钥重复校验全做,只跳过连通性 ⇒ 状态 `implemented`。
- 🔴 **`msgSendType` 没有官方字典表** ⇒ `Monitor/Info` 的 `msgTypeInfo.msgTypeList`
由官方 `MessageTypeEnum`(8 项)推出来。
- 🔴 **`f_category` 有三种语义**:`base_msg_account` / `base_intg_supplier` = **供应商类别码**
(`SMTP` / `TencentCloud` / …,列表按 `MessageEnum` 翻中文名,`SMTP` 原样保留);
`base_msg_send` / `base_msg_template` / `base_msg_monitor` = **业务分类 id 的 JSON 数组**。
- 🔴 **创建人 / 修改人列存的是「登录账号」不是 UUID**(仓库既有约定,`docs/contract.md:2092`)
⇒ 列表要显示名字就得 **JOIN `base_user` ON `f_account`**(`f_id` 兜底)。
- 🔴 **msgCenter 不做应用隔离**:`base_msg_*` / `base_intg_supplier*` **没有 `f_system_id` 列**
⇒ `App-Code` 头**不影响**这一族(不是漏做,是官方 DDL 如此)。
- 🔴 **复制账号不复制 `f_is_default`**(官方 `entity.setIsDefault(...)` 会复制出**两个默认账号**)
⇒ 本仓**保守不复制**(保留 `setDefault` 不变量),复制件 `f_enabled_mark=0`;
复制模板的 `f_template_type` 硬编码 `"0"`(官方 `MessageTemplateConfigController.java:583`)。
- 🔴 **模板复制要抄两张子表**,而**两张子表的列不一样**
(官方是两个实体:`TemplateParamEntity` / `MsgVariableEntity`)⇒ 各写各的显式列,
**禁 `SELECT *`**(`base_msg_variable` 根本没有 `f_field_name` 列)。
- 🔴 **`GET /api/message/Receive` 与 `GET /api/message/Supplier` 返 ListVO**
(`{list:[…]}`,**不是** `{pagination,list}`)—— 官方就是 ListVO。
- 🔴 **`POST /api/message/Monitor/{id}/Retry` 的能力判定排在数据判定之前**:
本仓**永远**发不出去 ⇒ 先报「未接入消息服务商」,比「数据不存在」更说明问题。
- 🔴 **官方前端 `testConfig` 声明的是动态路径** `${Api.Prefix}/${data.testType}`
(`api/msgCenter/accountConfig.ts:33`)⇒ 静态抽端点器把最后一段记成**路径参数**
⇒ 尺子 `fe-gap.py` 会报缺口。官方 Java **只有静态端点**
`POST /api/message/Account/testSendMail`,而前端**唯一调用点**
(`src/views/integrationCenter/email/Test.vue:59`)把 `testType` 写死成 `'testSendMail'`
⇒ 运行期 URL 就是那个静态端点(**已实现**)。
⇒ 本仓**加一条同语义别名** `POST /api/message/Account/{id}`(参数名必须是 `{id}`,
见 §5「批次 20 新增的坑」)⇒ `fe-gap` 的 `msgCenter` 列 **50/50(100%)**。
**🔴 官方 Java 多暴露 12 条、官方前端从不调的端点 ⇒ 本期不做**(记在已知限制):
Account 的 `detail/{id}` / `unable/{id}` / `Action/Export` / `Action/Import`、
Template 的同 4 条、Send 的 `/Selector` / `getInfoByEnCode/{enCode}` / `detail/{id}`、
Monitor 的 `POST /Monitor`。
- 回归测试 `tests/batch20_it.rs`(**6 条**):51 条路径逐条打(防 `matchit` 冲突)、
账号 CRUD + 复制 + 设默认 + 删默认必须失败、模板 CRUD(含两张子表)+ 发送配置 CRUD、
敏感词 / 接收配置 / 供应商 CRUD(**两个 ListVO 形状**钉住)、
**7 条诚实失败逐条断言**(`code=400` + `data:null` + msg 含「消息服务商」)、
面 B 未登录 `602`。
---
## 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/sspf-admin > /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/sspf-admin --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/sspf-admin > /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` +
改 `crates/sspf-admin/src/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 条~~
✅ **批次 18 做完(实际 22 条端点,`fe-gap` 的 `core` 列 5/27 → **27/27 = 100%**)**——
真实现 6 条(锁屏解锁 / 免密票据 2 条 / 扫码凭证 3 条)+ **诚实失败 16 条**
(文件族 4 + 导入族 4 + 地图族 3 + 改密通知 1 + SaaS 族 3 + socials 1)。
🔴 新增 `TicketStore`(进程内内存票据表,官方用 Redis ⇒ 本仓无 Redis ⇒ 进程重启即失效);
**两种票据不串用**(`tkt-` / `scc-` 前缀)。
🔴 同批修掉一个**真偏差**:`Login/saas` 原先 `let _ = require_login_face_b(..)`
⇒ **丢弃 `Err` ⇒ 实际不拦**,但静态闸门推成「登录」⇒ 已改成真拦(官方
`TenantSaasGranter.checkTenantUser` 要求已有登录态)。
15. ~~`workFlow` 104 条~~ ✅ **批次 19 做完(实际 104 条端点,`fe-gap` 的 `workFlow` 列
0/104 → **104/104 = 100%**)**——真实现 62 条 + **诚实失败 42 条**
(引擎动作 27 + 无文件服务 2 + 无在线表单设计器 13)。
🔴 新增 **24 张 `workflow_*` 表**(官方 DDL **逐字**导入,`WORKFLOW_TABLES` 常量),
只导元数据、**不导 Flowable 的 `act_*` 引擎表**。
🔴 官方流程引擎是**独立 HTTP 服务**(`FlowAbleUrl` = `<flowDomain>/api/Flow/*`),
本仓没有它 ⇒ 一切「动作类」端点一律 `400` + 人话。
16. ⏸️ **暂缓**(用户 2026-11-02 决定):`aiCenter` 75 / `extend` 64 / `teamwork` 40。
🔴 **`msgCenter` 50 已按用户指示做完**(批次 20,见 §1「批次 20」小节)——
它**不是**「本仓没这个模块」:官方 `base_msg_*` / `base_intg_supplier*` 表本来就在,
只是端点没接。**做之前先查表存不存在**,别按「没模块」下结论。
17. ✅ **onlineDev 集成测试已写**(`tests/batch17_it.rs`,**11 passed**)——
`matchit` 同位置参数名冲突这类错静态看不出来(批次 12 踩过)⇒
新端点族落地后**必须**跑一次集成测试。
18. ✅ **workFlow 集成测试已写**(`tests/batch19_it.rs`,**7 passed**)——
逐条打一遍 104 条路径防 `matchit` 冲突 + 模板 CRUD 落库 + 评论/委托 +
**27 条引擎端点逐条断言「诚实失败」** + 多应用隔离 + 未登录 602。
19. ✅ **msgCenter 集成测试已写**(`tests/batch20_it.rs`,**6 passed**)——
逐条打一遍 51 条路径防 `matchit` 冲突(**同位置参数名冲突就是靠它抓的**)+
账号 / 模板 / 发送配置 / 敏感词 / 接收 / 供应商 CRUD 落库 +
**两个 ListVO 形状**(`Receive` / `Supplier`)+ **7 条诚实失败逐条断言** + 未登录 602。
### 🔴🔴 批次 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 + `crates/sspf-admin/src/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`(`crates/sspf-compat-system/src/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`**
(`crates/sspf-admin/src/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/sspf-admin &
# 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/sspf-admin" 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/sspf-admin`**,不是 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`)。
### 批次 18 新增的坑(core 族 22 条)
- 🔴🔴 **「丢弃 `Err` 的守卫」会让静态标签与运行时行为不一致**:
`let _ = require_login_face_b(&state, &headers).await;` —— **编译过、闸门全绿**,
静态闸门把这条推成「登录」,但**运行时其实不拦**(`Err` 被丢了)。
⇒ 契约里写着「登录」,实际却是公开端点 ⇒ **契约在骗人**。
🔴 本批在 `Login/saas` 上撞上了(官方 `TenantSaasGranter.checkTenantUser` 里
`UserProvider.getUser().getUserId()` 为空 ⇒ 直接抛 `LoginException(GT105)`
⇒ **官方确实要求已有登录态**)⇒ 已改成
`if let Err(resp) = require_login_face_b(..).await { return resp; }`。
🔴 **`Logout` 是另一种情况**(官方 `logout` 是 `@NoDataSourceBind` ⇒ 未登录也返成功;
前端 `store/auth.ts:86` 把返回值完全忽略、但 404 会弹红条)
⇒ 本仓**刻意**丢弃 `Err`(恒 200)—— 这条已用测试
`logout_succeeds_without_login_state` 钉住,**别再当 bug 改掉**。
🔴 **判据**:想让某端点**不拦**,就**别调**守卫函数(而不是调用后丢 `Err`)。
- 🔴 **官方 `ActionResult.success(msg, data)` 是「先 msg 后 data」**:
官方 `LoginController.java:383-390` 的 `getTicket` 是
`ActionResult.success(ticketModel.getTicketTimeout().toString(), ticket)`
⇒ **有效期进 `msg`、票据进 `data`** —— 与本仓 `envelope::ok(data)` 恒 `msg="成功"` **相反**。
⇒ 这种端点**不能**用 `ok(..)`,得**自己造信封**
(`Json(ActionResult { code, msg: expires_at_ms.to_string(), data: Value::String(ticket) })`)。
- 🔴 **官方票据存 Redis ⇒ 本仓做进程内内存表**(`platform/session.rs` 的 `TicketStore`):
照 `SessionStore` 同款做法(`Arc<RwLock<HashMap<..>>>`)—— 进程重启即失效,
**不假装能跨重启**。
🔴 **两种票据不能串用**(官方也是两张不同的 Redis key)⇒ `TicketKind::Login`(`tkt-`)
与 `TicketKind::ScanCode`(`scc-`)**带前缀**、查表时**种类不符当作不存在**。
🔴 混在一起的后果:「注销会话」会误删票据;拿扫码凭证查免密票据会**真的**查到。
- 🔴 **官方 `LoginTicketModel` 恰好 4 个字段**(`status`/`value`/`theme`/`ticketTimeout`)
⇒ **不要多给字段**(前端按 `ticketTimeout` 判断过期,多给反而误导)。
🔴 **查不到票据 ⇒ 返 `status=1`(INVALID)而不是报错** —— 官方
`LoginController.java:398-404` 是**照常返回**一张空模型,不是 `fail`。
- 🔴 **官方 core 族在官方前端全是「只有声明、没有消费点」**
(`api/core/{auth,common,user}.ts` 里声明了,两个前端版本里都搜不到调用点)
⇒ **形状只能以官方 Java 为准**,不能照前端消费点猜。
- 🔴 **官方 `/api/oauth/Login/socials` 没有独立的 `@XxxMapping`**:
它走 `LoginController.java:117` 的 `@RequestMapping(value="/Login/**")` **通配**
⇒ 由 `grant_type` 分流(`password` / `saas` / `socials` / `scancode`)。
⇒ `[OFFICIAL]` 的 `src` 只能记 **`LoginController.java:117`**(那个通配行)。
- 🔴 **官方 `/api/file/Uploader/Preview` 是有 Java 出处的**(`UtilsController.java:277`
⇒ `preview(PreviewParams)`)—— 别信「前端声明了后端就没有」的直觉,
**逐条 grep 官方 Java**。
- 🔴 **导入族是「一份路径、多份 Controller」**:
官方前端用 `/api/${url}/TemplateDownload` 拼(`url` 是**模块名**)⇒
官方**每个模块的 Controller 各有一份同路径的映射**
(`BaseLangController.java:142` / `VisualdevModelDataController.java:944` /
`EmployeeController.java:208` / `OrganizeController.java:464` …)
⇒ `[OFFICIAL]` 的 `src` **指其中一份即可**,不必逐个模块登记。
🔴 本仓实现用**单段通配** `/api/{prefix}/Xxx`(`prefix` = 模块名)。
- 🔴 **本仓 `Cargo.toml` 里**没有任何 HTTP 客户端**(无 `reqwest` / `ureq`)
⇒ 地图族(官方 `LocationController` 转发高德 REST API)**转发不了**
⇒ 只能**明确失败**(**不返编出来的坐标**)。
- 🔴 **本仓的口令存储口径 ≠ 官方**:官方存 `md5(明文 + secretkey)`;
本仓存 `md5(明文)`(`platform/auth.rs` 的 `decrypt_to_md5`)
⇒ 锁屏解锁**按本仓口径**做等价校验。
🔴 **口令错与账号不存在要统一文案**(官方分两种码,但前端只弹一句
⇒ 本仓统一给一句,避免账号枚举)。
- 🔴 **axum 的 `matchit` 在同一位置有两个参数名 ⇒ 启动即 panic**:
静态闸门看不出来、编译也过,只有真把 router 建起来才炸
⇒ 新端点族**必须**有「逐条打一遍」的集成测试(`batch18_it` 的
`core_all_22_endpoints_are_registered_without_matchit_conflict`)。
- 🔴 **契约里 §6 头的「**132** 条 / **53 行**」是没人校验的散文数字 ⇒ 一直在漂**:
实际已到 610 条 / 607 行。本批顺手改成真值。
🔴 **教训**:凡是不被尺子读的**数字**,迟早会说谎 —— 要么让尺子读它,要么别写它。
### 批次 19 新增的坑(workFlow 104 条)
- 🔴🔴 **pglite 的参数类型推断(本仓最阴的一条)**:本仓所有参数都按 `Option<String>`
绑定 ⇒ 手写 SQL 里写 `$1::integer` 会让 **PG 把参数本身**推成 `int4`
⇒ pglite 报 `cannot convert between the Rust type Option<String> and the Postgres type int4`。
🔴 **正确写法是 `$1::text::integer`**(`::text` 在前,**先固定成 text 再转**)——
仓库的 `placeholder()` 就是这么发的。**手写 SQL 绕过 `placeholder()` 时最容易踩**。
本批在 `workflow.rs` 改了 **21 处**,`report.rs` 改了 **3 处**(后者是批次 17 的**潜伏 bug**,
静态闸门全绿时也是坏的 ⇒ 只有真跑才炸)。
- 🔴 **漏 JOIN ⇒ `missing FROM-clause entry for table "u"`**:
`workflow_task_info` 的投影里有 `u.f_real_name` / `u.f_account`(官方要显示「发起人」),
FROM 却只有 `workflow_task t` ⇒ 必须补 `LEFT JOIN base_user u ON u.f_id = t.f_creator_user_id`。
🔴 **`LEFT JOIN` 不能写成 `LEFT JOIN … ON … OR …`**(批次 13 踩过:撞上会把**列表行翻倍**,
分页静默错乱)。
- 🔴 **种子列 + 写字段表撞车**(批次 9 的同款坑,第 N 次):`f_type` 既在种子列里、
又被 `TEMPLATE_WRITE_FIELDS` 从 JSON 键 `type` 映射过来 ⇒ INSERT 报
`column "f_type" specified more than once`。本批修法:**去掉显式列**,
body 没带 `type` 时**补默认值 `0`**(官方默认也是 0)。
- 🔴 **官方 `Info/{id}` 收的是「版本 id」不是模板 id**(`TemplateController.templateJsonInfo`)
⇒ 拿模板 id 去查会查不到版本 JSON。
- 🔴 **官方 `CommentController.list` 是「任务作用域」**(`getTaskUserList(pagination.getTaskId())`)
⇒ 没有任务就**空列表**(不是 bug)。本仓的隔离子查询要求「任务 → 模板 → 系统」链路存在
⇒ 测试里**直接插一行 `workflow_task`**(引擎才会产生的数据)才查得到。
- 🔴 **官方 `TemplateController` 的路径段名是 `{formId}`**(`getFlowByFormId`),
官方前端却按 `/{id}/FlowList` 调 ⇒ **同一条路由** ⇒ 本仓按**表单主键**查
`workflow_node.f_form_id` → 版本 → 模板。(契约 `[OFFICIAL]` 保留官方的 `{formId}`,
CC10 归一后对账。)
- 🔴 **版本列表返「裸数组」不是 PageListVO**(官方 `ActionResult<List<...>>`)——
和本仓多数列表不同,写成 `{pagination,list}` 前端会拿到 `undefined`。
- 🔴 **委托的入参形状**:`toUserId` 是**数组**(被委托人列表)、`userId` 是**委托人**;
`startTime`/`endTime` 返**epoch 毫秒数字**(不是字符串)。
- 🔴 **契约的 `[FACE]` 计数是「派生值」** ⇒ **别手改** `docs/contract.md` 的 `[FACE]` 行
(`scripts/pack-sync.py` 会从 `[ENDPOINT]` 行重算)⇒ 手改必然被
`pack-sync --check` 判红(**这正是它该做的**)。
- 🔴 **契约生成器加一族要登记四张表**(`scripts/gen-contract-endpoints.py`):
① 官方 Java 控制器映射表 ② **官方前端独有**路径表 ③ 引擎类 partial 路径表
④ 文件类 / 表单类 partial 路径表 —— 少登记一张 ⇒ 生成器直接 `SystemExit`
(**宁可不生成,也不生成没有出处的行**)。
- 🔴 **axum 的 handler 参数顺序**:body 提取器(`Bytes`)**必须放最后**,
`RawQuery` / `Path` / `HeaderMap` 是 `FromRequestParts`、必须排在它前面
⇒ 顺序反了**编译不过**(这条比 `matchit` 冲突友好 ⇒ 编译期就能发现)。
### 批次 20 新增的坑(msgCenter 51 条)
- 🔴🔴 **axum/matchit:同一位置不允许两个不同的参数名** —— 本批想给官方前端那条
**动态路径**(`${Api.Prefix}/${data.testType}`)注册 `POST /api/message/Account/{testType}`,
结果**启动即 panic**:
`Invalid route "/api/message/Account/{testType}": Insertion failed due to conflict with
previously registered route: /api/message/Account/{id}`。
🔴 **静态闸门看不出来、编译也过**(路由冲突是**建 router 时**才炸)⇒
**只有真把 router 建起来才炸** ⇒ 路由扫描测试(`batch20_it` 的 51 条路径逐条打)必须留着。
⇒ **同一位置只留一个参数名**(本批用 `{id}`,段内容其实是前端的 `testType`)。
- 🔴🔴 **写库助手的三组长度必须一致**(列 / CAST / 值)—— 不一致会把值写进**别的列**
且**不报错**。本批真踩到:`account_copy` 写了 **25 个列名但只有 24 个 CAST**
⇒ panic `index out of bounds: the len is 25 but the index is 25`(这条路径此前从没跑过)。
⇒ 已给 `insert_row` 加**运行时形状校验**:不一致就**明确失败**
(宁可不写,也不静默写坏数据)。
- 🔴 **抄子表禁 `SELECT *`** —— 模板的**参数表**与**变量表**是官方两个实体
(`TemplateParamEntity` / `MsgVariableEntity`),**列不一样**
(`base_msg_variable` **没有** `f_field_name` 列)⇒ 抄错列会**静默写坏数据**。
🔴 `check-arch` 的 MEM1(禁 `SELECT *`)会当场把这种写法判红 —— 照做即可。
- 🔴 **静态抽端点器分不清「动态段」和「路径参数」** —— 官方前端
``url: `${Api.Prefix}/${data.testType}` `` 里那最后一段**其实是常量**
(唯一调用点写死 `'testSendMail'`)⇒ 抽端点器记成 `{param}` ⇒ 尺子 `fe-gap.py` 报缺口。
⇒ 两种收法:① 加一条**同语义别名**把「声明的路径形状」也接住(本批选的);
② 在契约/交接里写明「这是抽取器的产物,官方后端只有静态端点」。
🔴 别为了让尺子变绿去**改尺子的判定**。
- 🔴 **创建人 / 修改人 / 删除人列存的是「登录账号」不是 UUID**(仓库既有约定)⇒
列表要显示人名得 **JOIN `base_user` ON `f_account`**(`f_id` 兜底),
直接拿它当 `f_id` 去 JOIN 会**查不到**(结果是空名,不是报错)。
- 🔴 **官方 DDL 就是明文存密钥**(`f_smtp_password` / `f_secret_key`)且前端要拿回来编辑
⇒ 照官方返明文。**「口令不得外泄」那条红线只管 `base_user.f_password`**,
两者别混(混了就等于把用户口令的口径套到第三方服务商密钥上)。
- 🔴 **`f_category` 有三种语义**(账号 / 供应商 = 供应商类别码;
发送配置 / 模板 / 监控 = 业务分类 id 的 JSON 数组)⇒ 同一列在不同表里**读法不同**,
写反了前端看到的是「分类名列表」或「编码」,不会报错。
- 🔴 **列表形状有两种**:`GET /api/message/Receive` 与 `GET /api/message/Supplier` 返
**ListVO**(`{list:[…]}`)⇒ 写成 `{pagination,list}` 前端拿到的 `pagination` 是 `undefined`。
- 🔴 **能力判定要排在数据判定之前**:`POST /api/message/Monitor/{id}/Retry` —— 本仓**永远**
发不出去 ⇒ 先报「未接入消息服务商」;先查数据会让用户以为「id 写错了」。
- 🔴 **官方复制账号会复制出「两个默认账号」**(官方把 `isDefault` 一起复制)
⇒ 本仓**保守不复制** `f_is_default`(保住 `setDefault` 不变量),并把复制件置为**停用**。
---
## 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 | 与本仓无关 |
🔴 **2026-11-02 批次 20 收尾时实查:本会话没有挂任何定时任务**(`CronList` = 空)⇒
**没有下一次自动续跑**。理由:面 B 剩下三族(`aiCenter` 75 / `extend` 64 /
`teamwork` 40)是**用户 2026-11-02 明确暂缓**的
⇒ **不该自己续跑**(续跑等于推翻用户的暂缓决定)。
⇒ 若要恢复自动续跑,需**先拿到用户的新指示**(或用户改口「继续做暂缓的那三族」)。
(🔴 `msgCenter` 50 是**用户当天单独点名要做的**(「msgCenter 50 去做完吧」)⇒ 批次 20 已做完。)