- 物理移出 packs/{asset,books,demo,shop}、modules/ 四个面 A 适配器、纯技能副本、
纯业务测试 crud_it.rs 与 new-pack 脚手架(v0.3.0 tag 完整保留旧形态)。
- 删 example-packs feature / example_packs() / sspf-pack-* 依赖 / packs/* member;
packs_gen.rs 与 modules/mod.rs 生成段降级为恒空的注入点,装配链一条不删;
pack-sync.py 把「零包」钉成合法目标态。
- 尺子不再「跳过」:CP1 防回流清单、check-module 三条、AR2/PACK1 正向断言、
AR17 升级为零业务依赖判据(含注入式反自证)、契约反自证换平台锚点、FACE 零包重算。
- 面 A 冒烟 43→21 条(17 条平台权限闭环 + 4 条业务端点 404);pack_smoke_it 改
运行时防回流探针;auth/db/batch7/permission/seed/routes 单测换平台内置夹具。
- 契约 [MENU_TREE] 收成 5 条系统菜单、[RULER] 改 21/3;README/CLAUDE/HANDOFF/
CHANGELOG/contract §5.1/schema.sql/db.rs 注释同步。
验收:cargo test --workspace --no-fail-fast 649 passed / 0 failed / 6 ignored;
verify.sh --smoke 14/14;check-arch 24/24 + 反自证 14/14;
cargo tree -p sspf 无 sspf-pack-*。前端 src/frontend 按要求保留。
2941 lines
228 KiB
Markdown
2941 lines
228 KiB
Markdown
# 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. 2026-11-04 晚:平台包零业务清理(第一批,**基于 v0.3.0,新提交**)
|
||
|
||
需求:`@docs/SSPF-BUSINESS-COMPOSITION.md` 之后的追加要求 —— 「示例部分拿到外面去做,
|
||
技能依赖**打好的包及说明**而不是整个 sspf 源码仓,前端留着;一次做清理,一次改技能」。
|
||
`v0.3.0` tag 一字不动,清理全走新提交;旧形态在 tag 里完整可回溯。
|
||
|
||
**做了什么**
|
||
|
||
1. 物理移出:`packs/{asset,books,demo,shop}`、`src/backend/src/modules/{asset,books,demo,shop}.rs`、
|
||
纯技能副本(`template-boot-jnpf/`、`references/`、`JNPF_*`、`PERMISSION.md`、`HOWTO_MODULE.md`、
|
||
`MIGRATION.md`、`docs/README-project.md`)、纯业务测试 `crud_it.rs`、
|
||
`scripts/new-pack{,-gen}`。备份在 `/tmp/sspf-cleanup-backup/`(供第二批改技能用)。
|
||
**前端 `src/frontend/` 与前端脚本按用户要求原样保留。**
|
||
2. 解绑:`example-packs` feature、`example_packs()`、`packs/*` workspace member、
|
||
`sspf-pack-*` 依赖(Cargo.lock 与 `cargo tree -p sspf` 均无)、`sspf-admin` 的 feature 开关。
|
||
`packs_gen.rs` / `modules/mod.rs` 生成段降级为**恒空的注入点**(装配链一条不删),
|
||
`pack-sync.py` 把「零包」钉成合法目标态,出现任何业务包直接报错。
|
||
3. 尺子全部改造成**防回流**,不是「跳过」:CP1 用固定 `ANTI_REFLUX_TOKENS`、
|
||
`check-module` 零业务三条、`check-arch` AR2/PACK1 正向断言 + **AR17 升级为
|
||
「5 个 Cargo.toml 无业务包依赖 / GEN 段恒空 / packs/ 不存在」**、
|
||
契约反自证锚点换成平台路由行、`FACE` 计数零包时重算。
|
||
4. 运行时尺子:面 A `perm-smoke.sh` 43 → **21 条**(17 条平台权限闭环 + 4 条业务端点 404);
|
||
面 B 23 条不变(授权夹具 `m_demo` → 平台菜单 `m_menu`);`pack_smoke_it` 改成
|
||
「清单恒空 + 平台端点 200 + 4 个示例端点 404」的运行时探针;
|
||
`auth_it` / `batch7_it` / `db_it` / `permission_it` / `seed_it` / `routes.rs` 单测
|
||
全部换成平台内置夹具(5 菜单 / `base_role` / `base_module` / 常量投影)。
|
||
5. 文档:`README` / `CLAUDE.md` / `CHANGELOG.md` / `docs/contract.md` §5.1 /
|
||
`schema.sql` / `db.rs` 注释同步;契约 `[MENU_TREE]` 收成 5 条系统菜单,
|
||
`[RULER]` 改 21 / 3。
|
||
|
||
**🔴 回归与坑(下轮别再踩)**
|
||
|
||
- `cargo test` 遇到第一个失败二进制就**停** ⇒ 必须 `cargo test --workspace --no-fail-fast`
|
||
才能一次拿全失败清单。本轮依次暴露:`crud_it`(编译)→ `auth_it` → `db_it` →
|
||
`batch7_it` → `pack_smoke_it` → `permission_it` → `seed_it` + `routes.rs` 单测。
|
||
- **跳过 ≠ 判据**:零业务后 `check-arch` 的 AR2/PACK1 原本各 `skip` 一条,
|
||
AR17 的反自证 12/14 因「没有 pack 依赖行可改」**静默假红**。已全部换成正向断言 +
|
||
注入式探针(造一条 `sspf-pack-probe` 依赖)。反自证 1/14 的 `mkdir -p packs/...`
|
||
会留下**空 `packs/`**,必须用 `rmdir` 收干净,否则 AR2/AR17 当场红。
|
||
- CP1 扫的是**平台层源码里的字面量** ⇒ 新写的防回流单测若直接写
|
||
`/api/ssw/<app>/...` 会把自己判红;路径要运行时用 app/entity 两段拼。
|
||
- `query_json` 对原生 numeric 列给 JSON **数字**(9.9),只有 `::text` 才是字符串 "9.90"
|
||
⇒ `db_it` 现在两种形态都钉。
|
||
- 运行时尺子默认读 `target/release/sspf-admin`;改完源码**必须**
|
||
`cargo build --release -p sspf-admin`,否则打的是旧二进制(本轮被它骗过一次)。
|
||
- 契约 `[RULER]` 条数 / `[MENU_TREE]` 是尺子的单一真源,改断言必须同步;
|
||
`[MENU_TREE]` 从 9 菜单收成 5 菜单后,`perm-smoke` 断言 13 的形状变成 `菜单管理:`。
|
||
|
||
**验收**:`cargo test --workspace --no-fail-fast` **649 passed / 0 failed / 6 ignored**
|
||
(清理前 711 ⇒ 下降 62,全是随示例搬走的纯业务测试,未造业务夹具冒充零业务);
|
||
`verify.sh --smoke` **14/14 步全绿**(6 道静态闸门 + 全量测试 + 5 把运行时尺子);
|
||
`check-arch.sh` 24/24 / 0 跳过,`--self-test` 14/14;`cargo tree -p sspf | grep sspf-pack` 无输出。
|
||
|
||
**待办(第二批)**:技能仓 `~/.agents/skills/ssw-jnpf-lite-rust` 接收示例,改成
|
||
`sspf = { git=…, tag=… }` 的薄脚手架,删掉旧的 `src/backend` 自研实现,重写
|
||
`SKILL.md` / `README.md`,前端随发布包保留。版本号(打 `v0.4.0` 还是只提交)需用户拍板。
|
||
|
||
---
|
||
|
||
## 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 已做完。)
|