Files
ssw-platform/CLAUDE.md
T
admin e0c1904a0e docs: 同步面 B 批次 11 收尾(HANDOFF/PLAN/CLAUDE + memory 日志)
- HANDOFF §1 现状:端点 376(面 B 346)/ tables 52 / 测试 550 / 官方覆盖 365-372
- HANDOFF 新增 §1「批次 11」小节:表名≠控制器名、enCode 前缀化(create 用 !=0、
  update 用 ==1,delete 比对用带前缀的码)、conditionJson 三层结构、方案列表
  只需登录、SYS020/SYS021、3 处诚实降级
- HANDOFF 新增「本批踩到并解决的 5 个真 bug」+ §5「批次 11 新增的坑」6 条
- HANDOFF §3 待办:划掉批次 11,补批次 12 指引(缺口 system 55 / permission 26 / systemData 32)
- HANDOFF 修正「八道闸门」为「十二道闸门」(旧措辞与 CLAUDE.md 不一致)
- PLAN 差距表:面 B 331 → 346,base_* 49 → 52
- CLAUDE.md:cargo test 545 → 550(两处写死值)
- memory 日志追加批次 11 段落:结论 / 9 个坑 / 数字(均已复验)
2026-11-01 19:18:17 +08:00

26 KiB
Raw Blame History

CLAUDE.md — 尚数网 Rust 后端开发框架(ssw-platform)

本文件是项目级红线 / 当前阶段范围文件。 代码级「契约唯一真源」在脚手架自带的各项文档里 (docs/contract.md / JNPF_COMPAT_SURFACE.md / PERMISSION.md / MIGRATION.md 等)。

🔴 长期架构与路线(定位 / 分层 / 动态加载 / MCP / 迁移 / P0–P5)见 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

核心不变量:

  • 平台层 / 业务层分离:加业务模块只碰 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 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 整个技能目录,会灌入技能噪音):

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                # 单测(当前 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。
  • 本文件只留「原则 + 决定 + 一句话摘要」;改代码后回头核对是否还成立。