# 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 / 代码生成 | 官方能力,本期不碰 | | 文件 / 消息 / 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(数据资源,本体对齐) │ │ │ │ └── .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 ``` **核心不变量**: - **平台层 / 业务层分离**:加业务模块只碰 `src/modules/`(新文件 + `mod.rs` 登记),平台层一个字不改。 两层唯一接头点是 `bootstrap.rs`。 - **双面契约同一进程**:面 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`** | **32 条:4 元工具上限 / 分层加载 / 自提示 / 业务失败不误报协议错 / 结构注入防护 / 写工具校验 / 授权闭环 / prompts 模板 / stdout 纯 NDJSON** | **32/32 已绿** | | **契约尺子·低代码** | **`scripts/lowcode-smoke.sh`** | **8 条:真实样例解析(主表 6 字段/子表 8 字段)/ 同构保序 / inline 校验 / 缺参拦截 + 两条反自证(改坏字段必被抓、未知控件不阻断)** | **8/8 已绿** | | **契约尺子·双后端** | **`scripts/baseline-smoke.sh`** | **10 条:基线适配器自动登录 / health 裸对象 / 形状归一化(list→menus、organize→organizeId、裁剪多余键)/ 不支持的 op 发请求前拦下** | **10/10 已绿** | | **运行时·内存** | **`scripts/mem-budget.sh`** | **空载物理内存(vmmap `Physical footprint`)是否 ≤ 预算** | **7 MB / 40 MB 预算 已绿** | 🔴 期望值只有一处:`docs/contract.md` 附录 A(机器可读 `[ENDPOINT]` / `[OFFICIAL]` 等),由 `scripts/contract_expect.py` 解析。 每把尺子结尾比对「实际断言数 vs 契约登记数」,对不上即失败 —— 尺子不会被悄悄改弱。 **加任何业务模块 / 改任何契约 / 加任何 crate 依赖 / 改任何内部标识 / 加任何表,十二道闸门必须全绿才算完成。** 🔴 **`cargo test --workspace` 当前 344 条**(内核 + contract 13 + store 17 + sdk 2 + pack-asset 5 + mcp 45 + adapter-baseline 19 + lowcode 38 + 集成测试)—— 拆 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)。 10. **同一文件多 Edit 必须串行 + 改完 grep 复核**。 --- ## 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 # 单测(当前 344 条) 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 工具层契约 32 条(4 元工具 + 分层加载 + 授权闭环 + prompts) bash scripts/lowcode-smoke.sh # 低代码 8 条(表单解析 + 校验 + 反自证) 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/<子系统>/.md`。 - 工作日志 → `.workbuddy/memory/YYYY-MM-DD.md`。 - 本文件只留「原则 + 决定 + 一句话摘要」;改代码后回头核对是否还成立。