Files
ssw-platform/CLAUDE.md
T
admin 21c69ee85d docs: 同步批次 12.6 收尾(HANDOFF + HOWTO + CLAUDE + memory)
记下:两档验证的分工(--fast 该接的接上了 / --lib 接上的活真能应答)、

两处反自证结果、以及「不同步 Save/Delete」「不在 new-pack.sh 里跑」两条边界。
2026-11-01 23:13:42 +08:00

335 lines
27 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# CLAUDE.md — 尚数网 Rust 后端开发框架(ssw-platform)
> **本文件是项目级红线 / 当前阶段范围文件。** 代码级「契约唯一真源」在脚手架自带的各项文档里
> (`docs/contract.md` / `JNPF_COMPAT_SURFACE.md` / `PERMISSION.md` / `MIGRATION.md` 等)。
>
> 🔴 **长期架构与路线(定位 / 分层 / 动态加载 / MCP / 迁移 / P0–P5)见 [`PLAN.md`](PLAN.md)。**
> 本文件只管**当前阶段的红线与范围**,范围表随阶段推进滚动;两者冲突时以 `PLAN.md` 的架构决策为准。
> 改代码后回头核对两文件是否还成立。
---
## 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` 系统级隔离(模块/菜单/授权按系统切分)。**本期只做注册表 + 路由 + 隔离**,不做 `SystemController` CRUD。见 §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-lowcode/ # (P2)元数据引擎 + Rhai 沙箱
│ ├── sspf-plugin/ # (P3)业务包加载器:静态 / dylib / wasm
│ └── sspf-mcp/ # (P1)MCP 2.0 元工具层
├── packs/ # 【业务包】整目录可搬(jnpf ⇄ sspf 双向)
│ └── asset/ # 样板:Cargo.toml + pack.toml + src/lib.rs
│ # 只依赖 sspf-sdk(AR2)⇒ 可独立 cargo build
├── src/
│ ├── backend/ # 内核 crate(package 名仍是 ssw-platform)
│ │ ├── Cargo.toml
│ │ ├── src/
│ │ │ ├── main.rs # 启动装配
│ │ │ ├── lib.rs # pub mod platform / modules / routes
│ │ │ ├── platform/ # 【平台层】契约实现,加业务模块一个字都不改
│ │ │ │ ├── cipher.rs # md5→AES-256-ECB(key=md5("EY8WePvjM5GGwQzn") 的 32 ASCII 字节)→hex
│ │ │ │ ├── envelope.rs# ActionResult{code,msg,data}
│ │ │ │ ├── auth.rs # 登录 / CurrentUser / 登录守卫(面 A/面 B 共用)
│ │ │ │ ├── face_b.rs # 【面 B】基线平台形状:判别头 / PcUserVO / PageListVO / 点权限守卫
│ │ │ │ │ # (P0 由 jnpf.rs 改名:内部标识必须剥离,前端不依赖)
│ │ │ │ ├── permission.rs # 四源合并 + 管理员短路 + 菜单树(全部按 f_system_id 隔离)
│ │ │ │ ├── seed.rs # ensureBase(含 ensure_systems)+ firstSeed
│ │ │ │ ├── system.rs # 【多应用】App-Code 头 → SystemRef{id,code};base_system 注册表
│ │ │ │ ├── sys.rs # 5 组 base_* 显式 handler
│ │ │ │ ├── crud.rs # spec 驱动通用 CRUD 引擎(不含业务表名/app_code)
│ │ │ │ ├── test_support.rs # 测试用**进程级共享** pglite(pglite 每进程只能开一次)
│ │ │ │ └── ...(config/db/ids/session/state/entity/menu/guard/mod)
│ │ │ ├── modules/ # 【业务层】加业务模块只改这里
│ │ │ │ ├── mod.rs # ALL_SPECS / ALL_MENUS / ALL_ROUTES / router() 汇总
│ │ │ │ ├── demo.rs / shop.rs / books.rs # 模板模块(不进生产)
│ │ │ │ ├── asset.rs # 🔴 真实业务:DataResource(数据资源,本体对齐)
│ │ │ │ └── <app>.rs # 尚数网业务模块(Phase 3 起)
│ │ │ ├── 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`(+ 单测 + 包冒烟 `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):
1. **`base_*` 表名/列名逐字对齐官方 DDL**(含两个故意不修正的官方陷阱:
`base_role_relation` 用户 id 在 `f_object_id`;组织/岗位关系在另一张 `base_user_relation`)。
2. **口令 cipher**:`md5(明文)` → `AES-256-ECB-PKCS7`(key = `md5("EY8WePvjM5GGwQzn")` 的 32 个 ASCII 字节)→ hex。
检验向量:`encryptPassword('123456')` ==
`d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b`。
3. **响应信封 + 主键 + JSON 键名**:`{code,msg,data}`(业务失败也 HTTP 200);主键 36 位 UUID v4 `varchar(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–AR7 + 内存红线 MEM1–MEM2(`--self-test` 反自证)** | **9/9 已绿** |
| **静态·命名** | **`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` 当前 550 条**(内核 + contract 13 + store 17 + sdk 2 + pack-asset 5 + mcp 52 + adapter-baseline 19 + lowcode 112 + 集成测试)——
拆 crate 后总数会变,**不许把断言数写死**,跑一遍看实际值。
cipher 自证(免 node):`./target/release/ssw-platform --enc 123456`。
---
## 7. 红线(摘要;细则见脚手架文档)
1. **契约优先于实现**:端点路径/入参/返回形状/错误码与官方/脚手架逐字一致;不确定先读源码,不凭印象。
2. **业务失败一律 HTTP 200 + `{code,msg,data}`**;唯一例外:未知路由 HTTP 404(body 仍是信封)。**鉴权失败也是 200**(`600`/`403`)。
3. **`base_*` 表名/列名逐字对齐官方 DDL**,严禁自创(迁移靠 `--data-only`,差一字导不进)。
4. **四源权限合并 + 管理员短路 + 未映射放行**:管理员在 SQL 前短路;权限 = 直授+角色+组织+岗位;菜单未映射到 `base_module` ⇒ 放行(静默,必须有测试钉住)。
5. **口令不得外泄**:库内存 `md5(明文)`;响应手工挑字段(去 `password`);密文只在请求体出现。
6. **平台层 / 业务层分离**:加模块只碰业务层;接线只在 `bootstrap.rs`。由 `check-boundary.sh` 钉死。
7. **判别头 `Vue-Version: 3`**:本仓前端禁止发该头(发了面 A 误判成面 B);面 B 必带。
8. **两套权限判据并存别混**:面 A 按菜单路径,面 B 按 `f_en_code`;同一用户两面可能一通一拒,不是 bug。
9. **暂缓项不偷跑**:tenant / SSO / 微服务 / 流程引擎 / 代码生成 不在本期(§2.2)。低代码**元数据 + 动态 CRUD** 已落地(P2-a/P2-b),但读 release / 单据号 / 乐观锁仍未做。
10. **同一文件多 Edit 必须串行 + 改完 grep 复核**。
11. **低代码表必须「建表即回写」**:`schema.table.create`(或种子)建完表要回写 `f_tables_data`,否则 CRUD 层在模型里找不到 `f_delete_mark` ⇒ 逻辑删除直接报 `LOGICAL_DELETE_UNSUPPORTED`。
12. **单租户也不省 `f_tenant_id`**:值恒为 `"0"`,但列 `NOT NULL` 且参与复合主键 `(f_id, f_tenant_id)`;建表/写入都必须带这一列。
13. **写工具默认 `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` 整个技能目录,会灌入技能噪音):
```bash
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. 命令速查
```bash
cargo build --release # 编译(workspace 根,含 crates/* 与 packs/*)
cargo test --workspace # 单测(当前 550 条)
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–AR7 + 内存红线 MEM1–MEM2
bash scripts/check-arch.sh --self-test # 反自证:造违规必须被抓到
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/ssw-platform --mcp # 起 MCP stdio 服务(供 AI 直接驱动,见 docs/mcp.md)
./target/release/ssw-platform --enc 123456 # cipher 自证
```
> 本机 curl 走系统代理,测 localhost 必须加 `--noproxy '*'`。
> 🔴 本机沙箱**禁止 `ps` / `top`**(Operation not permitted)⇒ 内存只能用 `vmmap`(`mem-budget.sh` 已处理)。
> 🔴 本机 rustup 下载受代理限速(~6 MB 卡死)⇒ 不要随手 `rustup update`,工具链以 `rust-toolchain.toml` 为准。
---
## 10. 待确认决策(开工前或 Phase 2 前定)
1. ~~**命名**~~ ✅ **已定**:项目 / crate / bin 一律 `ssw-platform`(`Cargo.toml` + 命令速查已改;脚本里的 `ssw-jnpf-lite-rust` 只剩「脚手架参照物」语义)。
2. **数据库形态**:MVP 用 pglite-rs 进程内(零服务);稳定期是否切真实 PostgreSQL?数据迁移/双写路径?
3. **Java 版实际契约差异**:拿尚数网 Java 版实跑一次面 B diff,确认 `18/18` 是否覆盖 Java 前端**全部必需**端点(mirror 只有上游 JNPF,缺公司 fork 定制)。若有缺口,记 `partial`/`absent` 排期补。
4. **首批业务模块**:尚数网首批要落哪些业务模块?(demo/shop/books 仅作模板,不进生产)
5. **文件/预览依赖**:Java 前端是否依赖 `jnpf-file` 的文件上传/预览?若依赖,Phase 2 需先补最小文件面 B。
6. **官方源码位置(`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`。
- 本文件只留「原则 + 决定 + 一句话摘要」;改代码后回头核对是否还成立。