Files
ssw-platform/HANDOFF.md
T

221 KiB
Raw Blame History

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.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)

$ 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)

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):

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 步只在坏了时重跑。

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 存活:

# 前端
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)

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

验收判据(做完必须全绿才算完成)

# 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 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. 每批实现的固定动作(缺一不可)

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 已做完。)