- 内核只有 lib:启动装配 → crates/sspf-admin(bin sspf-admin);37 个集成测试 → crates/tests(package sspf-tests)。
- demo/shop/books 的 spec/菜单/DDL/面 B 路由搬进 packs/{demo,shop,books};内核 modules/*.rs 只剩「面 A 适配器 + pub use」⇒ 内核零业务知识,示例可整目录搬走。面 A 与前端零改动。
- 示例表 DDL 按平台规则补 f_tenant_id + 复合主键(spec 不加 ⇒ JSON 键与响应逐字不变)。
- 修 is_builtin_table 只认 schema.sql 的漏洞:包表(含 asset_data_resource)此前可被建模页删除/改;现为「平台 DDL ∪ 包表」。
- sspf-compat-online_dev → onlinedev(包名/模块/文件/路由别名同步);6 个 5 行转发壳合并为 forward.rs。
- 新增 AR16 闸门 + lib.rs「30 秒地图」+ src/backend/README.md;pack-sync 补两处判据(module_key=None 的 urlAddress、apiFile 查存在性)。
- 回归:704 tests / 6 道静态闸门全绿;health 181 表;四个包面 A/面 B 运行时全部 200。
30 KiB
CLAUDE.md — 尚数网 Rust 后端开发框架(ssw-platform)
本文件是项目级红线 / 当前阶段范围文件。 代码级「契约唯一真源」在脚手架自带的各项文档里 (
docs/contract.md/JNPF_COMPAT_SURFACE.md/PERMISSION.md/MIGRATION.md等)。🔴 长期架构与路线(定位 / 分层 / 动态加载 / MCP / 迁移 / P0–P5)见
PLAN.md。 本文件只管当前阶段的红线与范围,范围表随阶段推进滚动;两者冲突时以PLAN.md的架构决策为准。 改代码后回头核对两文件是否还成立。🔴 「平台能力全部迁到
crates/、内核只留薄壳」的迁移计划见docs/CRATES-MIGRATION.md(基线 tag =v0.1.0)。动手前先读它 —— 里面有实测的依赖图、三处循环依赖的解法、 闸门改造清单与逐批出口判据。
0. 一句话定位
尚数网 Rust 后端(ssw-platform)= 用 Rust 重写「尚数网 Java 版后台」,契约与数据库逐字兼容 Java 版(= JNPF v7.0 形状),从而前端 / 移动端 / 库原地不动,只换后端引擎。
- 后端先迁(单二进制、好部署、编译期类型安全)。
- 前端 / 移动端 / 数据库 本期不动,靠「双面契约 + 同一套
base_*schema + 同一把 cipher + 同一套 seed」做到兼容。 - 多租户 / SSO / 微服务 本期不迁(见 §2.2)。
技术底座 = 已验证的 ssw-jnpf-lite-rust 脚手架(axum 0.8 + pglite-rs 0.2 进程内 PostgreSQL,零外部服务)。
本仓库 = 该脚手架的实例化项目;脚手架文档即本项目的契约真源,升级从脚手架同步进来。
1. 三个参照物(各司其职,别混)
| 参照物 | 路径 | 地位 |
|---|---|---|
| JNPF v7.0 官方源码 + DDL | git-mirror jnpf/7.0-jnpf-java-boot + jnpf/7.0-jnpf-database(PostgreSQL/JNPF-PostgreSQL.sql) |
数据模型真源:base_* 表名/列名/陷阱以官方 DDL 为准 |
ssw-jnpf-lite-rust 脚手架 |
~/Desktop/workspace/skills/ssw-jnpf-lite-rust/(三处软链同仓) |
契约/工程真源:本项目的模板与绑定规范 |
| 尚数网 Java 版(公司 fork) | 当前生产系统(不在这些 mirror 里) | 兼容目标:其前端/移动端/库应由本后端无缝接管 |
🔴 关键判断:mirror 里只有上游 JNPF,没有公司 fork。因此「兼容 Java 版」在工程上
= 兼容官方 JNPF v7.0 契约(面 B)+ 同一套 base_* schema。Java 版若对官方有定制,
需要在 Phase 2 拿 Java 版实跑一次面 B diff(见 §8 待确认决策 ③)才能确认覆盖度。
2. 范围
2.1 本期必做(v1,= 脚手架已交付能力)
- 后端平台层:登录 /
CurrentUser/ 5 组base_*管理 CRUD / 统一授权 / 四源权限合并 / 两段式种子。 - 双面契约:面 A(ssw/react 形状,冻结)+ 面 B(官方 JNPF 形状,按
Vue-Version: 3分流)。面 B 让 Java 前端/移动端直连。 - 3 个示例业务模块(demo / shop / books)—— 作为「加业务模块」的模板,不进生产。
- 多应用(app):
App-Code请求头选定当前应用;base_system注册表 +f_system_id系统级隔离(模块/菜单/授权按系统切分)。本期只做注册表 + 路由 + 隔离,不做SystemControllerCRUD。见 §4.1。 - 数据库:复用 JNPF v7.0 官方
base_*DDL(8 张表,含多应用注册表base_system)+ 业务表;进程内 pglite-rs(真实 PostgreSQL 语义),后续可换真实 PG。
2.2 本期不做(明确暂缓,别偷跑)
| 项 | 官方对应 | 原因 |
|---|---|---|
| 多租户 | 7.0-jnpf-java-tenant / f_tenant_id |
单租户固定 '0',暂不切分 |
| SSO / OAuth | jnpf-oauth(jnpf-oauth-api/-biz/-controller/-entity) |
用内部账号密码会话 token,不做第三方登录 |
| 微服务拆分 | jnpf-public/jnpf-provider |
单进程 monolith,不做 RPC/服务注册 |
| 低代码引擎 | jnpf-flowable / visualdev / 代码生成 |
元数据引擎 + 动态 CRUD 已迁(P2-a/P2-b,见 PLAN.md §P2);流程引擎(flowable)与代码生成器仍不碰 |
| 文件 / 消息 / AI / 调度 / 扩展 / 应用中心 | jnpf-file / jnpf-message / jnpf-ai / jnpf-scheduletask / jnpf-extend / jnpf-app |
后续按需,不在 v1;注意 Java 前端可能依赖文件上传等,Phase 2 验证时确认 |
| 按钮/列/表单/数据范围级授权 | base_module_button/_column/_form/_data |
仅做 item_type='module'(菜单)一类 |
3. JNPF v7.0 模块取舍(java-boot 模块映射)
7.0-jnpf-java-boot 是 Maven 多模块,顶层模块如下(已逐模块判定):
| java-boot 模块 | 决策 | 映射到本后端 |
|---|---|---|
jnpf-system(jnpf-system-biz/-controller/-entity) |
✅ 移植 | 平台层:base_user/base_role/base_organize/base_module 管理及面 B 的 User/Role/Organize/Menu |
jnpf-permission |
✅ 移植 | 平台层:授权写入 + 面 B Authority/Data、Users、Role、Organize/AsyncList、Menu/ModuleBySystem |
jnpf-admin(聚合入口 + AOP/filter) |
🟡 部分 | 登录/CurrentUser/AuthFilter 已映射为面 A/面 B;tenant 过滤、多数据源、sharding 跳过 |
jnpf-public/jnpf-common-all |
🟡 部分 | base_* 实体与 DDL 已对齐;其余 common 工具用 Rust 自有实现 |
jnpf-public/jnpf-generater-base |
⛔ 跳过 | 代码生成器(低代码),不在 v1 |
jnpf-public/jnpf-provider |
⛔ 跳过 | RPC/微服务 |
jnpf-oauth |
⛔ 跳过 | SSO(§2.2) |
7.0-jnpf-java-tenant(独立仓) |
⛔ 跳过 | 多租户(§2.2) |
jnpf-flowable |
⛔ 暂不 | 工作流/低代码 |
jnpf-ai(jnpf-ai-v2/-v3) |
⏸ 暂缓 | AI 能力后续按需 |
jnpf-file |
⏸ 暂缓 | 文件上传/预览;Phase 2 确认 Java 前端是否依赖 |
jnpf-message / jnpf-scheduletask / jnpf-extend / jnpf-app |
⏸ 暂缓 | 消息/定时/扩展/应用中心 |
jnpf-example / jnpf-exception |
⛔ 不迁 | 示例 / 异常处理(Rust 自有) |
DDL 真源:jnpf/7.0-jnpf-database 仓的 PostgreSQL/JNPF-PostgreSQL.sql(经 git-mirror 取)。
脚手架已带 docs/ddl/base_ddl_raw.sql 与对齐后的 db/schema.sql(12 表:8 base_* + 4 业务)。
4. 架构
ssw-platform/
├── Cargo.toml # workspace 根;members = ["src/backend", "crates/*", "packs/*"]
├── rust-toolchain.toml # 🔴 全仓锁 1.95.0(L3 动态库强依赖,见 PLAN.md §4.5)
├── crates/ # 【平台侧 crate】业务包不许依赖这里的任何东西
│ ├── sspf-contract/ # 契约类型:信封 / 码表 / EntitySpec / MenuSpec / UUID / 判别头
│ │ # 依赖只允许 serde/serde_json/uuid/http(AR4)
│ ├── sspf-sdk/ # 🔴 业务包唯一依赖:BusinessPack trait + Manifest
│ │ # 依赖只能是 sspf-contract(AR1)
│ ├── sspf-store/ # (P0-b)DB 抽象:pglite ⇄ 真实 PG
│ ├── sspf-core/ # 🔴 平台核心(M2):auth/CRUD/权限/种子/cipher/信封/…
│ │ # `src/backend/src/platform/*.rs` 只是它的转发壳
│ ├── sspf-compat-core/ # 🔴 契约面底座(M3):helper/res(判别头/守卫/分页信封)
│ ├── sspf-compat-system/ # 🔴 契约面(M4):system + scheduletask + core
│ ├── sspf-compat-permission/# 🔴 契约面(M4):permission(单向依赖 system)
│ ├── sspf-compat-msg/ # 🔴 契约面(M4):message + msg_center
│ ├── sspf-compat-workflow/ # 🔴 契约面(M4):workflow + report + visualdata
│ ├── sspf-compat-ext/ # 🔴 契约面(M4):extend + teamwork + ai + mobile
│ ├── sspf-compat-onlinedev/# 🔴 契约面(M4):onlinedev(官方模块名 onlineDev)
│ ├── sspf-lowcode/ # (P2)元数据引擎 + Rhai 沙箱(**纯计算**,AR7)
│ ├── sspf-lowcode-exec/ # 🔴 低代码**执行层**(M5):连库/跑 SQL/校验/回写模型
│ │ # `src/backend/src/lowcode_*.rs` 只是转发壳
│ ├── sspf-plugin/ # (P3)业务包加载器:静态 / dylib / wasm
│ ├── sspf-mcp/ # (P1)MCP 2.0 元工具层
│ ├── sspf-mcp-adapter/ # (M6)MCP 适配层:NativeAdapter + 契约面 handler 直调
│ │ # 壳侧 `src/backend/src/mcp_{adapter,compat}.rs` 只是转发壳
│ ├── sspf-admin/ # 🔴 **默认装配**:bin `sspf-admin`(进程级的事都在这)
│ │ # 定位项目根 / 读环境 / 开库 / 种子 / 自检 / 绑端口 / 优雅停机
│ └── tests/ # 🔴 **集成测试宿主**(package `sspf-tests`):37 个 `*_it.rs`
│ # 测的是「装配好的平台」,不是内核的私有实现 ⇒ 不挂在内核包里
├── packs/ # 【业务包】整目录可搬(jnpf ⇄ sspf 双向)
│ └── asset/ # 样板:Cargo.toml + pack.toml + src/lib.rs
│ # 只依赖 sspf-sdk(AR2)⇒ 可独立 cargo build
├── src/
│ ├── backend/ # 内核 crate(package `ssw-platform`,**只有 lib 目标**)
│ │ ├── Cargo.toml
│ │ ├── src/
│ │ │ ├── lib.rs # pub mod bootstrap / compat / modules / routes
│ │ │ ├── compat.rs # 【面 B 契约面**别名表**】M7 起:16 个域聚成 `compat::<域>::<handler>`
│ │ │ │ │ # 真源在 `crates/sspf-compat-*/src/`;这里只做 `pub use` 名字映射
│ │ │ │ │ # ⇒ 路由注册的 1,010 处 `compat::<域>::` **一个字都不用改**
│ │ │ │ │ # 🔴 不许在这里写实现(AR9/AR10 会红)
│ │ │ ├── test_support.rs # 测试用**进程级共享** pglite(依赖装配根 ⇒ 留壳层)
│ │ │ ├── modules/ # 【业务层】**每个模块都是「面 A 适配器 + pub use 转发」**
│ │ │ │ ├── mod.rs # ALL_SPECS / ALL_MENUS / ALL_ROUTES / router() 汇总(生成段)
│ │ │ │ ├── asset.rs # 🔴 真实业务:DataResource(本体对齐)→ packs/asset
│ │ │ │ ├── demo.rs / shop.rs / books.rs # 示例包 → packs/{demo,shop,books}
│ │ │ │ └── <app>.rs # 尚数网业务模块(`new-pack.sh` 生成)
│ │ │ ├── forward.rs # 6 个转发壳(低代码 4 + MCP 2)—— 只有 `pub use`
│ │ │ ├── routes.rs # 路由装配(平台 27 条 + 面 B 14 条 + merge 业务路由)
│ │ │ └── bootstrap.rs # 【装配根】唯一同时认识两层;把业务菜单注入种子
│ │ ├── db/schema.sql # 完整 DDL(base_* 8 + 业务 N)
│ │ └── data/ # 运行期数据(gitignore)
│ └── frontend/ # 本期暂不动;沿用 Java 版前端/移动端
├── scripts/ # 六道闸门 + cipher 自证(见 §6)
└── docs/ # contract / runbook / decisions / known-limitations / ddl
核心不变量:
- 平台层 / 业务层分离:加业务模块一条命令
(
bash scripts/new-pack.sh <app> <Entity> --name "…" --columns "a:TYPE"),平台层一个字不改。 两层唯一接头点是bootstrap.rs,而它读的是生成的包清单src/backend/src/packs_gen.rs(真源是packs/*)。 - 四处内核接线是生成的(
packs_gen.rs/modules/mod.rs五段 /Cargo.toml依赖段 /contract.md三段),由scripts/pack-sync.py从packs/*+modules/*.rs推出。 手改会被覆盖,而verify.sh第一步pack-sync.py --check会把「忘了同步」判红 —— 因为漏同步的后果是静默 404 / 越权放行,不是编译错误。 - 两档验证,分工别混:
verify.sh --fast(纯静态)证明「该接的地方接上了」;verify.sh --lib(+ 单测 + 包冒烟crates/tests/tests/pack_smoke_it.rs)证明「接上的活真能应答」。 后者遍历全部包真打List(面 A + 面 B)—— 表没建出来 / 路由没 merge / 守卫指错菜单 这三种静态闸门全绿、页面空着,只有它会红。加包后两档都要跑。 - 双面契约同一进程:面 A(ssw 形状,冻结)+ 面 B(官方 JNPF 形状)。判别头 =
Vue-Version: 3(官方前端必带、本仓前端唯一不发)。 共用两条路由按头分流:GET /api/oauth/CurrentUser、PUT /api/permission/Authority/Data/{objectId}。 - 两套权限判据并存:面 A 按菜单路径(
f_url_address);面 B 按点权限编码(f_en_code)。两套数据源不同,别混。
4.1 多应用(app)模型 —— 本期 MVP
- 当前应用由
App-Code请求头选定(官方 JNPF 做法):system::app_code_of(&headers)→resolve_system(&db, app_code)→SystemRef { id, code }。 头缺失 / 未知应用 / 查库失败 一律回落主系统(绝不 panic,也不 500)。 - 注册表 =
base_system:f_en_code存 App-Code,f_id即 systemId,f_full_name是显示名,f_is_main标记主系统。 列定义与官方database/PostgreSQL/JNPF-PostgreSQL.sql:4243逐字一致(24 列)。 种子(ensure_systems,幂等):主系统mainSystem(= 官方JnpfConst.MAIN_SYSTEM_CODE,f_is_main=1;5 条内置菜单 + 全部业务菜单)+app-b(故意无菜单,专门用来验证隔离)。 - 隔离口径:所有菜单 / 授权查询都带
f_system_id(build_menu_list/load_menus/has_module/has_en_code_permission)。MenuSpec.system_en_code声明菜单归属哪个应用,种子经system_id_of()解析成f_system_id落库。 CurrentUser/userInfo的系统字段(currentSystemId/systemId/systemCode)由App-Code解析,不再硬编码;面 A、面 B 同一口径。- 🔴 多应用 ≠ 多租户:应用(app:
base_system+f_system_id)是「同一租户下的多个子系统」; 租户(f_tenant_id)是数据隔离维度,本期仍固定'0'(§2.2)。 - 本期不做:
SystemController增删改查端点、应用级授权包、前端跨应用切换 UI。 - 钉住它的测试:
platform::system::tests::registry_resolution_and_menu_isolation(默认/未知头 → 主系统;app-b→ 正确解析;两系统的菜单树互不可见)。
5. 契约与数据库「兼容 Java 版」策略(本期核心)
兼容不靠"重写一套一样的东西",而靠三件被刻意锁死、三方共用的契约(Rust ⇄ NestJS ⇄ 官方 Java):
base_*表名/列名逐字对齐官方 DDL(含两个故意不修正的官方陷阱:base_role_relation用户 id 在f_object_id;组织/岗位关系在另一张base_user_relation)。- 口令 cipher:
md5(明文)→AES-256-ECB-PKCS7(key =md5("EY8WePvjM5GGwQzn")的 32 个 ASCII 字节)→ hex。 检验向量:encryptPassword('123456')==d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b。 - 响应信封 + 主键 + JSON 键名:
{code,msg,data}(业务失败也 HTTP 200);主键 36 位 UUID v4varchar(50); JSON 键名 = 列名去f_前缀后 camelCase。
5.1 官方 DDL 行号表(check-citations.sh 的 CIT3 对账源)
官方结构 DDL = ~/Desktop/workspace/jnpf/jnpf-database/PostgreSQL/JNPF-PostgreSQL.sql
(公司 GitLab platform/jnpf-platform/7.0 的 database/PostgreSQL/,13227 行 / 331 张表)。
本仓只用到下面 8 张 + 4 张业务表;行号漂移(官方增删表)会被 CIT3 当场抓到:
| 表 | 官方 DDL 行 | 用途 |
|---|---|---|
base_authorize |
812 | 授权(角色/用户/岗位 × 菜单/按钮) |
base_module |
2209 | 菜单/模块(f_system_id 多应用隔离就在这张表) |
base_organize |
3178 | 组织机构树 |
base_role |
3686 | 角色 |
base_role_relation |
3729 | 角色—用户关系(用户 id 在 f_object_id) |
base_system |
4243 | 系统应用(多应用注册表,24 列,f_is_main 标主系统) |
base_user |
4479 | 用户 |
base_user_relation |
4707 | 用户—组织/岗位关系 |
由此得到三条兼容通道:
- 数据库兼容:Rust 后端读写与 Java 版同一套
base_*表(同连一个 PG,或pg_dump --data-only迁移)。列名差一个字符就导不进 —— 所以严禁自创表名/列名。 - 前端/移动端兼容:Java 前端发官方形状请求(带
Vue-Version: 3)→ 命中面 B → 返回官方PageListVO/PcUserVO等形状 → 前端零改。 - 鉴权兼容:内部账号密码登录链路(同一把 cipher)→ Java 前端登录/CurrentUser 直连 Rust 后端。
🔴 面 B 未登录返 code=602(不是 600):官方前端只对 601/602 清 token,返 600 会卡死不跳登录页。面 A 仍是 600(冻结)。
6. 验收闸门(十二道,缺一不可)
| 类别 | 脚本 | 测什么 | 当前状态 |
|---|---|---|---|
| 静态 | scripts/check-module.sh |
业务模块 10 接触点齐不齐(本仓后端-only ⇒ 前端 4 处打 ⏭,仍计入条数) |
114/114 已绿 |
| 静态 | scripts/check-boundary.sh |
分层红线 CP1–CP6(平台层不许有业务知识) | 已绿(11/11) |
| 静态 | scripts/check-contract.sh |
契约端点表 ↔ 代码真实路由(CC2–CC10,含官方端点台账 CC10) | 已绿(10/10) |
| 静态 | scripts/check-citations.sh |
文档引文 路径:行号 逐条核对 |
4/4 已绿(192 条引文全解析;CIT3 依赖官方 DDL,缺失则 ⏭) |
| 静态·架构 | scripts/check-arch.sh |
crate 依赖纪律 AR1–AR11 + 内存红线 MEM1–MEM2(--self-test 反自证 6 条) |
14/14 已绿 |
| 静态·命名 | scripts/check-naming.sh |
内部标识剥离 NM1–NM3 阻断 + NM4 注释量化(--strict 可升级) |
3/0 已绿(69 处注释技术债) |
| 契约尺子·面 A | scripts/perm-smoke.sh |
43 条(面 A 契约闭环 32 + 真实业务模块 asset 9 + 多应用 App-Code 路由 2) |
已绿 |
| 契约尺子·面 B | scripts/perm-smoke-jnpf.sh |
23 条(官方形状 18 + 多应用 App-Code 路由 1 + 用户 CRUD 4,诚实记 SKIP) |
23/23 已绿 |
| 契约尺子·MCP | scripts/mcp-smoke.sh |
48 条:4 元工具上限 / 分层加载 / 自提示 / 业务失败不误报协议错 / 结构注入防护 / 写工具校验 / 授权闭环 / prompts 模板 / stdout 纯 NDJSON + 阶段 B 低代码动态 CRUD(seed → 默认 dryRun 不落库 → 真写 → 查证 → 子表差集 → 删除 → 建表幂等 / 口令列不外泄) | 48/48 已绿 |
| 契约尺子·低代码 | scripts/lowcode-smoke.sh |
15 条:真实样例解析 / 同构保序 / inline 校验 / 缺参拦截 / 建表 DDL 规则(类型映射·复合主键·逻辑删除列·系统列视图类型)+ 四条反自证 | 15/15 已绿 |
| 契约尺子·双后端 | scripts/baseline-smoke.sh |
10 条:基线适配器自动登录 / health 裸对象 / 形状归一化(list→menus、organize→organizeId、裁剪多余键)/ 不支持的 op 发请求前拦下 | 10/10 已绿 |
| 运行时·内存 | scripts/mem-budget.sh |
空载物理内存(vmmap Physical footprint)是否 ≤ 预算 |
8 MB / 40 MB 预算 已绿 |
🔴 期望值只有一处:docs/contract.md 附录 A(机器可读 [ENDPOINT] / [OFFICIAL] 等),由 scripts/contract_expect.py 解析。
每把尺子结尾比对「实际断言数 vs 契约登记数」,对不上即失败 —— 尺子不会被悄悄改弱。
加任何业务模块 / 改任何契约 / 加任何 crate 依赖 / 改任何内部标识 / 加任何表,十二道闸门必须全绿才算完成。
🔴 cargo test --workspace 当前 695 条(内核单测 + 各 crate 单测 + crates/tests 的 37 个集成测试二进制)——
拆 crate 后总数会变,不许把断言数写死,跑一遍看实际值。
cipher 自证(免 node):./target/release/sspf-admin --enc 123456。
7. 红线(摘要;细则见脚手架文档)
- 契约优先于实现:端点路径/入参/返回形状/错误码与官方/脚手架逐字一致;不确定先读源码,不凭印象。
- 业务失败一律 HTTP 200 +
{code,msg,data};唯一例外:未知路由 HTTP 404(body 仍是信封)。鉴权失败也是 200(600/403)。 base_*表名/列名逐字对齐官方 DDL,严禁自创(迁移靠--data-only,差一字导不进)。- 四源权限合并 + 管理员短路 + 未映射放行:管理员在 SQL 前短路;权限 = 直授+角色+组织+岗位;菜单未映射到
base_module⇒ 放行(静默,必须有测试钉住)。 - 口令不得外泄:库内存
md5(明文);响应手工挑字段(去password);密文只在请求体出现。 - 平台层 / 业务层分离:加模块只碰业务层;接线只在
bootstrap.rs。由check-boundary.sh钉死。 - 判别头
Vue-Version: 3:本仓前端禁止发该头(发了面 A 误判成面 B);面 B 必带。 - 两套权限判据并存别混:面 A 按菜单路径,面 B 按
f_en_code;同一用户两面可能一通一拒,不是 bug。 - 暂缓项不偷跑:tenant / SSO / 微服务 / 流程引擎 / 代码生成 不在本期(§2.2)。低代码元数据 + 动态 CRUD 已落地(P2-a/P2-b),但读 release / 单据号 / 乐观锁仍未做。
- 同一文件多 Edit 必须串行 + 改完 grep 复核。
- 低代码表必须「建表即回写」:
schema.table.create(或种子)建完表要回写f_tables_data,否则 CRUD 层在模型里找不到f_delete_mark⇒ 逻辑删除直接报LOGICAL_DELETE_UNSUPPORTED。 - 单租户也不省
f_tenant_id:值恒为"0",但列NOT NULL且参与复合主键(f_id, f_tenant_id);建表/写入都必须带这一列。 - 写工具默认
dryRun=true:新增写工具不传dryRun就是演练。这不只是防误写 —— 也是 AI 先看后写的唯一抓手。
8. 实施路线图
| 阶段 | 目标 | 出口判据 |
|---|---|---|
| Phase 0 — 实例化 | 把脚手架本体(非技能噪音)rsync 进本仓库根的 src/ + scripts/ + Cargo.toml + .env.example + .gitignore;cp .env.example .env |
目录齐、可 ./run.sh install |
| Phase 1 — 基线门 | 编译 + 跑通六道闸门(默认全绿) | ✅ 已过:cargo test 221(lib 98 + 集成 123)、check-module 114/114、check-boundary 11/11、check-contract 10/10、check-citations 4/4、perm-smoke 43/43、perm-smoke-jnpf 23/23 |
| Phase 1.5 — 多应用 MVP | base_system 注册表 + App-Code 路由 + f_system_id 隔离(§4.1) |
✅ 已落地:registry_resolution_and_menu_isolation 绿;app-b 与主系统菜单互不可见 |
| Phase 2 — 兼容验证 | 用尚数网 Java 前端/移动端实连面 B,跑登录/CurrentUser/用户/角色/机构/菜单/授权闭环;与 Java 版做一次面 B diff |
Java 前端可登录、菜单/授权行为一致 |
| Phase 3 — 业务模块 | 按 HOWTO_MODULE.md 加尚数网业务模块(只碰 modules/) |
✅ 首个已落地:asset/DataResource(数据资源,字段对齐公司本体);每模块 check-module + 六闸门全绿 |
| Phase 4 —(后续) | 按需补文件/消息/AI;评估 SSO/租户/微服务;稳定后切真实 PG | 按业务优先级排期 |
Phase 0 复制清单(不要 cp -R 整个技能目录,会灌入技能噪音):
SKILL=~/Desktop/workspace/skills/ssw-jnpf-lite-rust
rsync -a --exclude node_modules --exclude dist --exclude target --exclude data --exclude .DS_Store \
"$SKILL"/src "$SKILL"/scripts "$SKILL"/run.sh "$SKILL"/Cargo.toml \
"$SKILL"/.env.example "$SKILL"/.gitignore "$SKILL"/README.md \
"$SKILL"/HOWTO_MODULE.md "$SKILL"/PERMISSION.md "$SKILL"/MIGRATION.md \
"$SKILL"/JNPF_COMPAT_SURFACE.md "$SKILL"/JNPF_SOURCE_AUDIT.md \
"$SKILL"/docs "$PWD"/
cp .env.example .env && ./run.sh install && ./run.sh dev
9. 命令速查
cargo build --release # 编译(workspace 根,含 crates/* 与 packs/*)
cargo test --workspace # 单测(当前 654 条)
bash run.sh dev # 起后端(30010) + 前端(5173)
bash scripts/perm-smoke.sh # 面 A 43 条
bash scripts/perm-smoke-jnpf.sh # 面 B 23 条
bash scripts/check-boundary.sh # 分层红线 CP1–CP6
bash scripts/check-contract.sh # 契约端点 ↔ 代码路由 对账
bash scripts/check-module.sh # 业务模块 10 接触点
bash scripts/check-arch.sh # crate 依赖纪律 AR1–AR11 + 内存红线 MEM1–MEM2
bash scripts/check-arch.sh --self-test # 反自证:造违规必须被抓到(6 条)
bash scripts/check-naming.sh # 内部标识剥离(NM1–NM3 阻断 / NM4 注释量化)
bash scripts/check-naming.sh --strict # 注释里的原厂名也算红(技术债清零时用)
bash scripts/mcp-smoke.sh # MCP 工具层契约 48 条(4 元工具 + 分层加载 + 授权闭环 + prompts + 低代码 CRUD)
bash scripts/lowcode-smoke.sh # 低代码 15 条(表单解析 + 校验 + 建表 DDL 规则 + 4 条反自证)
bash scripts/baseline-smoke.sh # 双后端契约 10 条(HTTP 适配器 + 形状归一化)
cargo build -p sspf-adapter-baseline --example probe # baseline-smoke 依赖的探针
bash scripts/mem-budget.sh # 空载内存实测(P0 出口判据,预算 40 MB)
cargo test -p sspf-pack-asset # 业务包独立可编(业务包剥离的硬证据)
./target/release/sspf-admin --mcp # 起 MCP stdio 服务(供 AI 直接驱动,见 docs/mcp.md)
./target/release/sspf-admin --enc 123456 # cipher 自证
本机 curl 走系统代理,测 localhost 必须加
--noproxy '*'。 🔴 本机沙箱禁止ps/top(Operation not permitted)⇒ 内存只能用vmmap(mem-budget.sh已处理)。 🔴 本机 rustup 下载受代理限速(~6 MB 卡死)⇒ 不要随手rustup update,工具链以rust-toolchain.toml为准。🔴🔴 磁盘占用:
target/已从 58G 降到 1.2G,别再让它涨回去2026-11-03 实测:
target/曾达 58G(debug/deps45G +debug/incremental12G), 而磁盘已用 87%。根因是增量编译让 sccache 全程空转: cargo 默认给 rustc 传-C incremental=<target/debug/incremental>, 而 sccache 遇到incremental直接拒缓存(server 日志CannotCache(incremental)) ⇒Cache hits恒为 0、Non-cacheable calls等于请求数 ⇒ 8.4G 缓存全是废的。修法(已在根
Cargo.toml的[profile.dev]落地incremental = false):
- 收益:清空
target后重建 走缓存命中 —— 实测 14s(vs 全量 63s), 日常改一处重编也走命中;- 代价:失去 cargo 自己的增量加速(由 sccache 命中替代,且跨
cargo clean仍有效)。⇒ 推论:
target/现在是「随时可清」的东西,清了重建只要十几秒。 真要清就cargo clean(别手rm -rf target/,让 cargo 自己收)。 清理前先pgrep -f "cargo (build|rustc|check)"确认没有构建在跑。 sccache 缓存实体在~/.cache/sccache(~/.cargo/config.toml已配rustc-wrapper), 它不是项目内的东西 ⇒ 不要跟着target/一起删。
10. 待确认决策(开工前或 Phase 2 前定)
命名✅ 已定:项目 / crate / bin 一律ssw-platform(Cargo.toml+ 命令速查已改;脚本里的ssw-jnpf-lite-rust只剩「脚手架参照物」语义)。- 数据库形态:MVP 用 pglite-rs 进程内(零服务);稳定期是否切真实 PostgreSQL?数据迁移/双写路径?
- Java 版实际契约差异:拿尚数网 Java 版实跑一次面 B diff,确认
18/18是否覆盖 Java 前端全部必需端点(mirror 只有上游 JNPF,缺公司 fork 定制)。若有缺口,记partial/absent排期补。 - 首批业务模块:尚数网首批要落哪些业务模块?(demo/shop/books 仅作模板,不进生产)
- 文件/预览依赖:Java 前端是否依赖
jnpf-file的文件上传/预览?若依赖,Phase 2 需先补最小文件面 B。 - 官方源码位置(
check-citations的前置):引文校验要读官方源码,默认根 =~/Desktop/workspace/jnpf。 已就位:jnpf-java-boot/jnpf-web-apps-main/jnpf-common(均从内网 Gitea 浅克隆)。 缺:jnpf-database(Gitea 上该 mirror 已 404)⇒ CIT3「DDL 行号表」只能⏭。 拿到PostgreSQL/JNPF-PostgreSQL.sql后放进~/Desktop/workspace/jnpf/jnpf-database/即可转真校验。
11. 记忆约定
- 踩坑与长 traceback →
docs/<子系统>/<topic>.md。 - 工作日志 →
.workbuddy/memory/YYYY-MM-DD.md。 - 本文件只留「原则 + 决定 + 一句话摘要」;改代码后回头核对是否还成立。