# CLAUDE.md — 尚数网 Rust 后端开发框架(ssw-platform) > **本文件是项目级红线 / 当前阶段范围文件。** 代码级「契约唯一真源」在脚手架自带的各项文档里 > (契约真源 = `docs/contract.md`;面 B 规格 / 权限 / 迁移说明在技能仓 `ssw-jnpf-lite-rust`)。 > > 🔴 **长期架构与路线(定位 / 分层 / 动态加载 / MCP / 迁移 / P0–P5)见 [`PLAN.md`](PLAN.md)。** > 本文件只管**当前阶段的红线与范围**,范围表随阶段推进滚动;两者冲突时以 `PLAN.md` 的架构决策为准。 > 改代码后回头核对两文件是否还成立。 > > 🔴 **「平台能力全部迁到 `crates/`、内核只留薄壳」的迁移计划见 [`docs/CRATES-MIGRATION.md`](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` 系统级隔离(模块/菜单/授权按系统切分)。**本期只做注册表 + 路由 + 隔离**,不做 `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-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/**(2026-11-04 清理):业务包属于业务仓 / 技能仓, # 本仓零业务;`pack-sync.py` 一旦发现 packs/ 会直接报错。 ├── src/ │ ├── backend/ # 内核 crate(package `ssw-platform`,**只有 lib 目标**) │ │ ├── Cargo.toml │ │ ├── src/ │ │ │ ├── lib.rs # pub mod bootstrap / compat / modules / routes │ │ │ ├── compat.rs # 【面 B 契约面**别名表**】M7 起:16 个域聚成 `compat::<域>::` │ │ │ │ │ # 真源在 `crates/sspf-compat-*/src/`;这里只做 `pub use` 名字映射 │ │ │ │ │ # ⇒ 路由注册的 1,010 处 `compat::<域>::` **一个字都不用改** │ │ │ │ │ # 🔴 不许在这里写实现(AR9/AR10 会红) │ │ │ ├── test_support.rs # 测试用**进程级共享** pglite(依赖装配根 ⇒ 留壳层) │ │ │ ├── modules/ # 【业务装配点】只剩 mod.rs;五个生成段恒空 │ │ │ │ └── mod.rs # ALL_SPECS / ALL_MENUS / ALL_ROUTES / router() 全为空 │ │ │ ├── forward.rs # 6 个转发壳(低代码 4 + MCP 2)—— 只有 `pub use` │ │ │ ├── routes.rs # 路由装配(平台 27 条 + 面 B 14 条 + merge 业务路由) │ │ │ └── bootstrap.rs # 【装配根】唯一同时认识两层;把业务菜单注入种子 │ │ ├── db/schema.sql # 平台 DDL(177 张表;无业务表) │ │ └── data/ # 运行期数据(gitignore) │ └── frontend/ # 本期暂不动;沿用 Java 版前端/移动端 ├── scripts/ # 六道闸门 + 运行时尺子 + pack-sync(见 §6) └── docs/ # contract / runbook / decisions / known-limitations / ddl ``` **核心不变量**: - 🔴 **平台包零业务**(2026-11-04 清理,本页最上面那条边界):本仓没有 `packs/`、 没有 `sspf-pack-*` 依赖、没有 `example-packs` feature、`modules/` 只留空壳。 业务仓只依赖门面 `sspf`,经 `Platform::packs / ddl / menus / router / static_dir / on_ready` (或 v0.3.0 的 `assemble() → Finish`)注入自己的业务。 - **四处派生位置恒空且是生成的**(`packs_gen.rs` / `modules/mod.rs` 五段 / `Cargo.toml` 的 `>>>GEN:PACK_DEPS` / `contract.md` 生成段),由 `scripts/pack-sync.py` 把「零包」钉成合法目标态。**手改会被覆盖**,`verify.sh` 第一步 `--check` 判红; 谁把业务包塞回 `packs/`,生成器直接报错 ⇒ 防回流。 - **两档验证,分工别混**:`verify.sh --fast`(纯静态)证明「生成段没漂移 + 六把闸门没被改弱」; `verify.sh --lib`(+ 单测 + 运行时探针 `crates/tests/tests/pack_smoke_it.rs`)证明 「平台真的是零业务且装配链还活着」:清单恒空、平台端点 200、4 个示例端点 404。 `verify.sh --smoke` 再叠 5 把运行时尺子(先 `cargo build --release -p sspf-admin`)。 - **双面契约同一进程**:面 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–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. 红线(摘要;细则见脚手架文档) 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 # 全量测试(当前 5xx 条,零业务清理后已下降) bash run.sh dev # 起后端(30010) + 前端(5173) bash scripts/perm-smoke.sh # 面 A 平台权限闭环 + 防回流 21 条 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 # 零业务防回流三条([MODULE] 有数据行 ⇒ 回到完整检查) bash scripts/check-arch.sh # crate 依赖纪律 AR1–AR19 + 内存红线 MEM1–MEM2(AR17 钉零业务) 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) ./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/deps` 45G + `debug/incremental` 12G), > 而磁盘已用 87%。根因是**增量编译让 sccache 全程空转**: > cargo 默认给 rustc 传 `-C 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 前定) 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/<子系统>/.md`。 - 工作日志 → `.workbuddy/memory/YYYY-MM-DD.md`。 - 本文件只留「原则 + 决定 + 一句话摘要」;改代码后回头核对是否还成立。