Files
ssw-jnpf-lite-rust/CLAUDE.md
T
admin bef326ad2f feat(dep): 方案 C —— 消费平台预编译 rlib,零重编平台/axum
- Cargo.toml: [workspace.dependencies] 清空(sspf/axum/tokio/serde/serde_json
  全部改由平台包 lib/ 经 --extern 喂入);release profile lto=false
  (预编译 rlib bitcode-free,开 LTO 会 failed to get bitcode for LTO)
- src/backend/Cargo.toml: 去掉 axum/tokio;packs/*: 去掉 sspf workspace 依赖
- scripts/fetch-platform.sh: 解包前 mv 走旧包目录(避免旧 hash rlib 残留);
  为 sspf/axum/tokio/serde/serde_json/http/bytes 生成 --extern(保证与 sspf
  同一 crate 实例,否则跨 API 边界 E0308 mismatched types);修 channel 解析
- .gitignore: 忽略 .cargo/config.toml(含本机绝对路径,跨机无效)
- rust-toolchain.toml: 新增(锁 rustc 1.95.0)
- 文档同步 SKILL/README/CLAUDE/HANDOFF

实测: cargo build 5.7s / --release 11s,只编本仓 5 个 crate,平台 17 crate 与
axum/tokio 零重编。
2026-11-05 11:41:19 +08:00

31 KiB
Raw Blame History

AGENTS.md

本文件是 ssw-jnpf-lite-rust 的项目级 agent 指引。内容必须与代码同步;改代码后回头核对本文件是否还成立。

详细设计、决策记录、实施顺序、验收门 ⇒ 见 HANDOFF.md。

项目定位

ssw-jnpf-lite-rust = JNPF 兼容契约的 Rust 业务样板(单二进制、零外部服务)。

🔴 平台不在本仓(2026-11-04 → 2026-11-05 架构变更):登录 / 权限 / 面 A·B / 低代码 / MCP / 177 张 base_* 表在已发布的 sspf 包里——平台仓每版本 bash scripts/release.sh 打出自包含发布包, 本仓 bash scripts/fetch-platform.sh vX.Y.Z 解包到 vendor/sspf-vX.Y.Z/,生成 .cargo/config.toml 用 --extern 直喂包内预编译 rlib(方案 C,零重编平台;Cargo.toml 不声明外部依赖, release profile 必须 lto = false)。 本仓只有 业务包 packs/ + 面 A 适配器 modules/ + 薄装配 main.rs + 前端产物 + 两把尺子。 以前这里有一份 4000 行的平台实现(src/backend/src/platform/ + routes.rs),已整体删除 —— 不要把它抄回来:python3 scripts/check-scaffold.py 的 SC1 会立刻红。

它的存在意义只有一条:让"用 Rust 写业务"和"迁回官方 JNPF(Java)"之间是机械翻译,而不是重写。 为此本仓的数据模型(表名/列名/语义)与 HTTP 契约从第一天就锁死成官方 JNPF 的形状。

命名沿用用户指定的 ssw-jnpf-lite-rust(与 ssw-jnpf-lite / ssw-jnpf-lite-react 同族的轻量垫片), 不要把它理解成 tdc-rs 那个「数据接入连接器」——两者无继承关系。 🔴 正式名称 = ssw-jnpf-lite-rust(2026-10-26 用户改定):crate / package / bin / lib 名全部同名 (ssw-jnpf-lite-rust / ssw_jnpf_lite_rust),二进制落在 target/release/ssw-jnpf-lite-rust。

三个参照物(各司其职,别混)

参照物 路径 地位
官方 JNPF 源码 + DDL ~/Desktop/workspace/jnpf/ 数据模型真源:base_* 表名/列名/陷阱以官方 DDL 为准
ssw-jnpf-lite-react 技能 ~/Desktop/workspace/skills/ssw-jnpf-lite-react/ 行为真源:NestJS 版把契约"跑起来了",本仓逐条对齐它
tdc-rs 兄弟项目 ~/Desktop/workspace/tdc-rs/ 只抄工程手法(pglite 单实例、row_to_json 投影、axum 0.8 坑位)。不共享代码、不共享端口、不共享数据目录

🔴 tdc-rs 与本仓无依赖关系。别 import 它的代码、别改它、别把两边的数据目录指到同一处。 它已经占了 :30000,本仓后端默认 :30010。

交付形态

当前形态(2026-11-04 起)= 示例业务仓: 4 个业务包(demo · shop · books · asset)+ 面 A 适配器 + 薄装配 + 前端产物 + 两把运行时尺子(面 A 32 条 / 面 B 18 条)+ 6 条静态判据(check-scaffold.py)。

  • 平台能力由 sspf 包提供:登录 / CurrentUser / 5 组 base_* 管理 CRUD / 统一授权 / 四源权限合并 / 两段式种子 / 面 B 官方形状 / 低代码 / MCP / 177 张平台表。
  • 本仓负责:业务表 + 列 + 菜单 + 面 B 路由(在 packs/<app>/)、面 A 适配器、 把两者交给 sspf::Platform、以及证明「业务真的能跑」的尺子。

判据(两类,别按旧的「六道闸门」理解)

命令 判据
静态 python3 scripts/check-scaffold.py(+ --self-test) 本仓只准有业务(SC1–SC6,自证 6/6)
静态 python3 scripts/pack-sync.py --check 生成物不漂移
测试 cargo test --workspace 包自检 + 应用装配
运行时 bash scripts/perm-smoke.sh 面 A 32 条
运行时 bash scripts/perm-smoke-jnpf.sh 面 B 18 条(覆盖 N/18)
一键 bash scripts/verify.sh / --fast 上面全部

🔴 旧的 check-module.sh / check-boundary.sh / check-contract.sh / check-citations.sh 已删除: 它们测的是本仓那份平台实现(分层 / 契约对账 / 引文),平台搬走后没有测量对象, 留着只会假绿。

技术栈

层 选型 说明
后端 Rust 2021 + axum 0.8 + tokio 单二进制
数据库 pglite-rs 0.2(进程内原生 PostgreSQL) 零服务/零 Docker/零 WASM;数据落盘 src/backend/data/lite.pg
前端 react 技能的前端产物,逐字复用(React + Vite) 唯一改动 = vite 代理端口 30000 → 30010;vite 代理 /api → 后端
密码学 aes 0.8 + ecb 0.1 + md-5 0.10 与 react 技能 cipher.ts 逐字节等价
其它 serde / serde_json / serde_urlencoded 0.7 / uuid v4 / rand 0.8

🔴 pglite-rs ≠ 浏览器 PGlite。crate 名 pglite-rs、import 名 pglite; 它把 postgres-pglite 编译成原生静态库链进二进制 ⇒ 真实 PostgreSQL 语义(类型/MVCC/事务/扩展/线协议), 进程内单 backend。不是 @electric-sql/pglite(那是 WASM + IndexedDB,本仓禁止引入)。

目录速览(当前形态)

ssw-jnpf-lite-rust/          # 【仓根 = 技能根】三处软链 ~/.agents · ~/.claude · ~/.workbuddy 都指向这里
├── SKILL.md                 # 【技能入口】是什么 / 何时用 / 契约红线 / 判据
├── README.md                # 选型 / 运行 / 验收门 / 已知限制
├── HOWTO_MODULE.md          # 加一个业务模块(一条命令 + 四个文件)
├── PERMISSION.md            # 权限模版:表结构 / 四源合并 / 码表
├── MIGRATION.md             # 迁移指南(Rust ⇄ NestJS ⇄ 官方 JNPF Java)
├── JNPF_SOURCE_AUDIT.md     # 官方源码逐行核对报告
├── JNPF_COMPAT_SURFACE.md   # 面 B 规格书 + 落地顺序 S1–S6
├── Cargo.toml               # 【workspace 根】members = ["src/backend", "packs/*"],exclude = ["vendor"]
│                            #   🔴 方案 C:不声明外部依赖;fetch-platform.sh 生成 .cargo/config.toml
│                            #      (--extern 喂 vendor/…/lib 预编译 rlib,零重编平台)
├── CLAUDE.md / HANDOFF.md   # 本文件 / 交接文档
├── run.sh                   # install / build / dev / backend / frontend / stop / logs
├── packs/                   # 【业务真源】整目录可搬;每个包只依赖 sspf 门面
│   └── {demo,shop,books,asset}/
│       ├── Cargo.toml       #   只依赖 sspf(出现 axum/tokio/pglite ⇒ SC4 红)
│       ├── pack.toml        #   清单:app_code / 表 / 契约版本区间
│       ├── schema/001_init.sql  # 建表(带 f_tenant_id + 复合主键;不许建 base_*)
│       └── src/lib.rs       #   列 + spec + 菜单 + 面 B 路由 + impl BusinessPack for Pack
├── src/
│   ├── backend/             # 示例应用(薄壳,~500 行)
│   │   ├── src/main.rs      #   --enc/--help + ssfp::Platform 装配 + serve
│   │   ├── src/lib.rs       #   pub mod modules; pub mod packs_gen;
│   │   ├── src/packs_gen.rs #   业务包清单(生成物:load_static + manifest 快照)
│   │   ├── src/modules/     #   面 A 适配器(生成段 + 3 个 handler/模块)
│   │   └── data/            #   pglite 数据目录(gitignore)
│   └── frontend/            # React + Vite(含已打好的 dist/,后端直接托管)
├── scripts/
│   ├── verify.sh            # 一键验收(7 步 / --fast 4 步)
│   ├── check-scaffold.py    # 静态判据 SC1–SC6 + --self-test 6/6
│   ├── pack-sync.py         # 四处派生位置的生成器(--check 防漂移)
│   ├── new-pack.sh/.py      # 造包脚手架
│   ├── perm-smoke.sh        # 面 A 尺子(32 条)
│   ├── perm-smoke-jnpf.sh   # 面 B 尺子(18 条)
│   ├── smoke_backend.sh     # 隔离后端自启动助手(被两把尺子 source)
│   ├── contract_expect.py   # 读 docs/contract.md 附录 A(尺子的唯一期望源)
│   ├── reap-ipc-leaks.sh / ipc-reap.c   # macOS SysV 信号量回收
├── references/              # BaseCrudController.java(**非** JNPF 官方类)+ README
├── template-boot-jnpf/      # JNPF 标准栈最小可运行骨架(Java)
└── docs/                    # contract.md(契约真源)/ runbook / decisions / known-limitations / ddl

架构红线

  1. 🔴 契约优先于实现。 任何端点的路径、入参、返回形状、错误码,必须与 ssw-jnpf-lite-react 逐字一致。不确定时先读 react 技能源码,别凭印象。

  2. 🔴 业务失败一律 HTTP 200 + {code,msg,data}。 成败只看 body 的 code。 例外只有一个:未知路由保留 HTTP 404(body 仍是 ActionResult 形状)。 🔴 鉴权失败也是 HTTP 200(code=600 未登录 / code=403 无菜单权限)—— 与 tdc-rs 的 401/403 裸 body 相反,别把 tdc-rs 的形状抄过来。

  3. 🔴 base_* 表名与列名逐字对齐官方 DDL(含两个官方陷阱,见下)。 不允许自创表名/列名——迁移期靠 --data-only 导数据,列名差一个字符就导不进去。

  4. 🔴 四源权限合并 + 管理员短路 + 未映射放行。

    • 管理员(f_is_administrator=1)在任何 SQL 之前短路放行;
    • 权限 = 用户直授 + 角色 + 组织 + 岗位,只查角色会漏授权;
    • 菜单未映射到 base_module ⇒ 放行(对齐 SswPermissionGuard 的 warn 路径), 不是拒绝。这条最容易写反,且静默(不报错),所以必须有测试钉住。
  5. 🔴 口令不得外泄。 库内存 md5(明文);对外响应手工挑字段(用户列表要去掉 password)。 密文只在请求体里出现,永不回显。

  6. 🔴 前端不直接持有数据库。 一切访问经 /api/**。

  7. 🔴 DDL 绝不可从 HTTP 下载。 平台 DDL 已 include_str! 进 sspf 二进制(不在任何 web root); 业务 DDL 在 packs/<app>/schema/ 里,同样不许放进 src/frontend/ 或任何静态目录。

  8. 🔴 同一文件的多个 Edit 必须串行(并行 Edit = last-writer-wins 静默覆盖)。 改完必须 grep 复核全部改动点。

  9. 🔴 面 A / 面 B 的判别头是 Vue-Version: 3,不是 Jnpf-Origin: pc。 官方前端必带 App-Code / Jnpf-Origin: pc / Vue-Version: 3 三个头, 而本仓前端 src/frontend/src/api/request.ts 也发前两个(与官方同款)、 只不发 Vue-Version ⇒ 判别只能用后者。 🔴 本仓前端禁止发 Vue-Version(发了 ⇒ 面 A 请求被误判成面 B ⇒ 契约整体错位)。 面 B 尺子(scripts/perm-smoke-jnpf.sh)必须带该头;本仓前端不发该头是硬约束 (改了 request.ts 就会让面 A 请求被判成面 B ⇒ 两把尺子同时红)。

  10. 🔴 两套权限判据并存,别混。

    • 面 A 守卫按菜单路径(base_module.f_url_address,见红线 4);
    • 面 B 守卫按点权限编码(base_module.f_en_code,官方 @SaCheckPermission("permission.user"))。 两套结构相同但数据源不同:管理员短路 → 查授权 → 查不到 ⇒ 放行 → 四源成员判定 → DB 出错 ⇒ 拒绝。 🔴 同一用户可能在面 A 通、面 B 拒(这不是 bug,是两套判据)——改动任一套都不许动另一套。
  11. 🔴 面 B 未登录返 code=602,不是 600。官方前端 request.ts 只对 601/602 清 token ⇒ 返 600 会让官方前端卡死不跳登录页。面 A 仍是 600(冻结)。

  12. 🔴 平台 / 业务分离(靠仓库边界,不靠目录纪律)。

    • 平台 = 已发布的 sspf 包(本仓 vendor/sspf-vX.Y.Z/,由平台仓出包、本仓 fetch-platform.sh 解包)—— 不在本仓。 它自带登录 / 权限 / base_* / 面 B / CRUD 引擎 / 177 张表。
    • 业务 = packs/<app>/(真源:表 DDL + 列 + 菜单 + 面 B 路由)+ src/backend/src/modules/<app>.rs(面 A 适配器,只 pub use 转发 spec)。
    • 加一个业务模块只碰业务 ⇒ 平台一个字都不改(它根本不在这里)。 唯一接头是 main.rs 的 Platform::new().packs(reg).router(modules::router())。
    • 🔴 业务菜单不要传给 .menus():.packs(reg) 已把 PackRegistry.menus 带进种子, 给两次会在种子里撞主键。
    • 🔴 不许把平台抄回来:出现 platform/ / routes.rs / crates/ / base_* 建表语句 ⇒ check-scaffold.py 的 SC1/SC2 红。这是本仓最重要的一条判据 —— 抄回来不会报错,只会让平台再也升不动。
    • 🔴 引擎不许按 app_code 分支:业务差异由 spec 声明(EntitySpec.creator_fixed)。
  13. 🔴 生产档弱口令守卫(SSW_PROFILE=prod 才生效)。

    • 六条判据:① 键不在本部署清单里 ⇒ 跳过 ② 空/空白 ③ 精确等于已知弱值 ④ 含已知弱值(反绕过)⑤ 命中弱标记词(整体词,administrator 不误伤)⑥ 长度 < 12。
    • 🔴 两道检查:配置级(本次用的种子口令)+ 库内级(回读 base_user 的 admin 行)。 库内级是必须的:种子口令只对空库生效 ⇒ 生产库里那个可能是当初种下的 123456。
    • 🔴 不做误伤:管理员合法改过口令 ⇒ 库里那个不等于任何已知弱值 ⇒ 放行。
    • 🔴 协议共享值不受管:cipher.rs 的 CIPHER_KEY 是契约的一部分(前端要用它加密口令) ⇒ 改它会让整个登录链路当场报废 ⇒ 不在守卫清单里。

官方 DDL 的两个"故意不修正"的陷阱

陷阱 事实 后果
base_role_relation 用户 id 存在 f_object_id(配 f_object_type='user'),没有 f_user_id 写错列 ⇒ 角色授权永远不生效
base_user_relation 组织/岗位关系在另一张表,那里才有 f_user_id 写错表 ⇒ 组织/岗位授权永远不生效

另:base_module.f_type 是 INTEGER(1-目录 2-页面),f_category 是 VARCHAR(分类)—— 早期 MVP 曾写反,本仓以官方 DDL 为准。

关键实现细节(改代码前必读)

  1. cipher 的 key 是"hex 串当 ASCII 用": md5_hex("EY8WePvjM5GGwQzn") 得到 32 个 hex 字符 ⇒ 把这 32 个 ASCII 字节当 key ⇒ AES-256(不是 AES-128)。src 同理 = md5_hex(明文) 的 32 个 ASCII 字节。 输出 hex。上游检验向量:encryptPassword('123456') == d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b。 tdc-rs/src/cipher.rs 有逐字对齐的 Rust 实现可读作参考(但不共享代码)。
  2. 口令比对:base_user.f_password 存 md5(明文) 的小写 hex; 登录时 decrypt(密文) 得到 md5(明文) ⇒ 大小写不敏感比较。
  3. numeric 列必须序列化成 JSON 字符串("9.90",不是 9.9)。 手段:在 SQL 投影里就 cast 成 text(f_price::text AS price)—— row_to_json 直接给数字会被 serde_json 变成 f64 再输出 9.9 ⇒ 契约破。 int 列(f_delete_mark / f_stock / f_is_administrator)保持数字。
  4. 主键是 36 位 UUID v4(带连字符),列 varchar(50) 装得下。不是 tdc-rs 的雪花十进制。
  5. JSON 键名 = 列名去 f_ 前缀后 camelCase:f_id→id、f_real_name→realName、 f_url_address→urlAddress、f_is_administrator→isAdministrator、f_delete_mark→deleteMark、 f_creator_time→creatorTime。请求体去前缀名(title 不是 fTitle)。
  6. pglite 单 backend 串行化:所有 DB 访问必须持进程级 db_lock (OnceLock<Arc<tokio::Mutex<()>>>)。同时一个数据目录只能被一个进程打开 ⇒ 集成测试要么串行、要么各自用独立数据目录。
  7. 查询结果序列化:沿用 tdc-rs 的手法 SELECT row_to_json(q)::text AS _row FROM (<sql>) q ⇒ 取单列文本 ⇒ serde_json::from_str。 不要另起逐列类型映射分支。
  8. 标识符白名单:任何拼进 SQL 的表名/列名都要过白名单 ([A-Za-z][A-Za-z0-9_]*),并在启动时自检全部拼接点,不过白名单 ⇒ 秒退。
  9. include_str! 路径相对 src/platform/db.rs:写 ../../db/schema.sql(平台层比原来深一级)。
  10. axum 0.8 语义:Router<S> 的 S 是"还缺什么状态" ⇒ with_state 必须是链条最后一步。
  11. Form<T> 在 axum 0.8.9 只实现 FromRequest(没有 OptionalFromRequest) ⇒ Option<Form<T>> 编译不过 ⇒ 需要"解析失败也走业务信封"的表单端点, 取原始 body 自己用 serde_urlencoded::from_bytes 解析。 (/api/oauth/Login 正是这种端点,且 grant_type 不能加 camelCase。)
  12. 405 的 JSON 兜底用响应改写中间件(挂在链尾),不要用 axum 的 method_not_allowed_fallback(后者只对调用那一刻已注册的路由生效,且丢 Allow 头)。
  13. schema 初始化:启动时探测 base_user 是否存在,不存在才按 ; 拆分执行 schema.sql (拆分要字面量感知,别把字符串里的 ; 当语句边界)。
  14. 路径与 cwd 解耦:resolve_project_dir() 从可执行文件向上找锚点文件, static/ 与 data/ 都基于它 —— 后台启动时 cwd 会漂移,改成相对 cwd ⇒ 500。
  15. 未知路由 = HTTP 404(body 仍是 {code:404,msg:'接口不存在',data:null})。 不要用"全局 404 兜底"把它变成 200。
  16. CRUD 引擎的三个 handler 是 pub(crate)(handle_list / handle_save / handle_delete) ⇒ 业务模块在 modules/ 里调它们,平台层不反向依赖业务层。
  17. 菜单的 f_url_address 与 f_en_code 必须一字不差地一致: MenuSpec.url_address == EntitySpec.module_key == 前端 <Route path="…">(去前导斜杠)—— 三者任一不一致 ⇒ 菜单显示了但守卫不命中(或反过来)⇒ 静默失败。 modules/mod.rs 的单测钉住前两者;perm-smoke.sh 的菜单断言钉住实际树形状。
  18. 加一个业务模块 = 一条命令: bash scripts/new-pack.sh <app> <Entity> --name "中文名" --columns "a:VARCHAR(200)" ⇒ 建 packs/<app>/(表 + 列 + 菜单 + 面 B 路由)+ modules/<app>.rs(面 A), 并自动补齐 packs_gen.rs / modules/mod.rs 五段 / Cargo.toml 的 GEN:PACK_DEPS。 平台一个字都不用改(它不在本仓)。手改生成段 ⇒ pack-sync.py --check 红。

数据模型

src/backend/db/schema.sql —— 10 张表。

base_* 7 张(官方 DDL 逐字,复合主键 (f_id, f_tenant_id),单租户固定 '0')

表 官方 DDL 行号 用途
base_authorize 812 授权(f_object_type/f_object_id/f_item_type/f_item_id)
base_module 2209 菜单(f_url_address = 前端 Route path 去前导斜杠)
base_organize 3178 机构(f_parent_id 树)
base_role 3686 角色(f_en_code 唯一性应用层保证)
base_role_relation 3729 用户↔角色(⚠️ 用户 id 在 f_object_id)
base_user 4479 用户(f_password=md5,f_is_administrator,f_account 无 UNIQUE)
base_user_relation 4707 用户↔组织/岗位(⚠️ 这里才有 f_user_id)

行号出处:~/Desktop/workspace/jnpf/jnpf-database/PostgreSQL/JNPF-PostgreSQL.sql (同目录还有 jnpf_db_init.sql 等 9 个 init 文件,只读)。

业务表 3 张(与 react 技能同名 ⇒ 两版后端可开同一个库)

表 实体 列
demo_item DemoItem f_id / f_title / f_status / f_creator_user_id / f_creator_time / f_delete_mark
shop_product Product f_id / f_title / f_price numeric(12,2) / f_creator_user_id / f_creator_time / f_delete_mark
book_shop_book Book f_id / f_title / f_author / f_isbn / f_category / f_price numeric(12,2) / f_stock int / f_creator_user_id / f_creator_time / f_delete_mark

🔴 只有 base_* 的表名/列名是契约;业务表名只是为了数据模型可移植(两版后端能开同一个库)才故意对齐。

端点全表

🔴 src/backend/src/routes.rs 里逐条注册 32 条路径(axum 0.8.9 用 matchit 0.8.4, 不支持 {a,b} 这种「一段里多个参数」的写法 ⇒ 必须逐条注册)。 其中 27 条 = 面 A(ssw 形状,冻结)、5 条 = 面 B(官方 JNPF 形状,新增)。

🔴 面 A 的 12 条业务路由不在平台里 —— 它们由业务层自带 (src/backend/src/modules/<app>.rs 的 router()),main.rs 只 .router(modules::router()) 一次 ⇒ 加业务模块不动平台。 (本表逐字照旧;「注册位置」在业务层。)

🔴 机器可读版在 docs/contract.md 附录 A 的 [ENDPOINT] 区段(一行一条端点: face / method / path / guard / owner)。平台搬走后本仓不再做静态路由对账 (那些路由在 sspf 里,静态扫描器看不进来)⇒ 改由两把运行时尺子打真实 HTTP 验证 (perm-smoke.sh / perm-smoke-jnpf.sh)——比静态对账更硬,但要求服务能起。

📊 官方端点台账在同一份附录 A 的 [OFFICIAL] 区段(53 行: method / path / status / src / note)⇒ 记的是本仓对官方 JNPF 契约面的覆盖 (四态 implemented / partial / absent / oos)⇒ CC10 与代码真实路由双向对账 ⇒ 打印「官方端点覆盖 N/M」。面 B / 共用的每条路由都必须在账上。

面 A(27 条,冻结)

方法 路径 守卫 说明
GET /api/health 无 非契约探活 ⇒ {ok, tables, version};永远有响应(查不到表也返 200)
POST /api/oauth/Login 无 form-urlencoded:account / password(密文 hex) / grant_type=password;成功返回 {token, expiresIn:7200, tokenTypeName:'bearer'}
GET /api/oauth/CurrentUser 登录 🤝 共用(按头分流,见下)。面 A:{userInfo:{userId,userAccount,userName,isAdministrator}, menuList};未登录 code=600
GET/POST/DELETE /api/ssw/sys/User/{List,Save,Delete?id=} 登录 + 菜单 system/User 列表去掉 password,附 roleIds/roleNames
GET/POST/DELETE /api/ssw/sys/Role/{List,Save,Delete?id=} 登录 + 菜单 system/Role
GET /api/ssw/sys/Role/Modules?roleId= 登录 返 string[](菜单 id)
GET/POST/DELETE /api/ssw/sys/Organize/{List,Save,Delete?id=} 登录 + 菜单 system/Organize 有子机构时拒删(code=400)
GET/POST/DELETE /api/ssw/sys/Module/{List,Save,Delete?id=} 登录 + 菜单 system/Module
PUT /api/permission/Authority/Data/{objectId} 登录 🤝 共用(按头分流,见下)。面 A body {objectType:'role', module:['m1','m2']} —— objectType 必须小写、module 是一维数组
GET /api/permission/Authority/RoleModules?roleId= 登录 返 string[]
GET/POST/DELETE /api/ssw/demo/DemoItem/{List,Save,Delete?id=} 仅登录 业务模块模板
GET/POST/DELETE /api/ssw/shop/Product/{List,Save,Delete?id=} 登录 + 菜单 shop/Product
GET/POST/DELETE /api/ssw/books/Book/{List,Save,Delete?id=} 登录 + 菜单 books/Book

面 B(5 条,官方 JNPF 形状)

🔴 全部在 src/backend/src/platform/jnpf.rs 实现;规格见 JNPF_COMPAT_SURFACE.md。 🔴 未登录一律 code=602(官方前端只对 601/602 清 token ⇒ 返 600 会卡住不跳登录)。

方法 路径 守卫(按 f_en_code 点权限) 说明
GET /api/permission/Users permission.user data = {pagination:{currentPage,pageSize,total}, list:[…]};列表项无 password/secretkey,isAdministrator 是数字
GET /api/permission/Role permission.role 同上 PageListVO 形状
GET /api/permission/Organize/AsyncList/{id} permission.organize 按父 id 逐层取;data 是 PageListVO
GET /api/system/Menu/ModuleBySystem permission.menu data = {list:[…]}(官方 ListVO,不是裸数组);节点 15 字段
POST /api/permission/Authority/Data/{objectId}/Values 仅登录 body {type, objectType, moduleIds}(type 空 ⇒ code=400);返 {list, ids, all}

共用路由(按判别头 Vue-Version: 3 分流):

  • GET /api/oauth/CurrentUser —— 面 A 返 2 字段形状 / 未登录 600;面 B 返 PcUserVO 5 字段 / 未登录 602。
  • PUT /api/permission/Authority/Data/{objectId} —— 面 A 未登录 600 / 面 B 未登录 602(require_login_any)。

其它(两面通用):未知路由 → HTTP 404 + {code:404,msg:'接口不存在',data:null}。 (routes.rs 有两个路由表钉子测试:route_table_is_pinned(面 A 平台 18 条

  • 业务 9 条,后者取自 modules::ALL_ROUTES)与 jnpf_route_table_is_pinned(面 B 5 条), 都用「错方法 ⇒ 405」逐条证明已注册。)

命令速查

# 编译(仓库根是 cargo workspace,成员 = src/backend + packs/*)
cargo build                      # debug
cargo build --release            # 发布版(release profile 写在根 Cargo.toml)
cargo test --workspace           # 全量测试

# 工程脚本(仓库根 run.sh;退出码 0 成功 / 1 运行期失败 / 2 用法错)
bash run.sh install              # cargo fetch + npm --prefix src/frontend install
bash run.sh build                # cargo build --release + vite build
bash run.sh dev                  # 后台起后端(30010) + 前端(5173),日志 .logs/、PID .run/
bash run.sh backend / frontend / stop / logs

# 运行(后端)
PORT=30010 ./target/release/ssw-jnpf-lite-rust
PGLITE_DIR=memory:// PORT=30010 ./target/release/ssw-jnpf-lite-rust   # 临时库(一次性数据目录)
SSW_PROFILE=prod SEED_ADMIN_PASSWORD='<强口令>' PORT=30010 ./target/release/ssw-jnpf-lite-rust

# 判据(一键 / 分项)
bash scripts/verify.sh                           # 全量 7 步
bash scripts/verify.sh --fast                    # 静态 + 测试 4 步
python3 scripts/check-scaffold.py                # SC1–SC6:本仓只准有业务
python3 scripts/check-scaffold.py --self-test    # 反自证 6/6
python3 scripts/pack-sync.py --check             # 生成物漂移
bash scripts/new-pack.sh blog Post --name "文章" --columns "title:VARCHAR(255)"
bash scripts/perm-smoke.sh                       # 面 A:32 条(后端不用先起,自起隔离实例)
B=http://127.0.0.1:30010 bash scripts/perm-smoke.sh   # 显式指定 B ⇒ 不自起
bash scripts/perm-smoke-jnpf.sh                  # 面 B:18 条
bash scripts/reap-ipc-leaks.sh                   # 回收 macOS 泄漏的 SysV 信号量
python3 scripts/contract_expect.py dump          # 打印契约附录 A 的全部期望值
./target/release/ssw-jnpf-lite-rust --enc 123456 # cipher 自证(免 node)

本机 curl 走系统代理,测 localhost 必须加 --noproxy '*'。 后台常驻进程用 Bash 工具的 run_in_background 托管;nohup … & 在工具返回后会被回收。 起服务时 stdout 不要指向 /dev/null(进程会以 100 退出)。

已知踩坑清单

症状 根因 处理
登录必失败(400 账号或密码错误) cipher key 当成了 16 字节原始摘要 ⇒ AES-128 key = md5_hex 的 32 个 ASCII 字节 ⇒ AES-256 ✅本仓已修(cipher.rs 按此实现,上游检验向量单测钉死)
f_price 回显 9.9 而不是 "9.90" row_to_json 把 numeric 给了数字 投影里 f_price::text AS price ✅本仓已修(冒烟断言比的是原始 JSON 文本,字符串与数字能分出来)
角色授权写了不生效 写进 base_role_relation.f_user_id(不存在此列) 用户 id 写 f_object_id + f_object_type='user' ✅本仓已修
组织/岗位授权不生效 写进 base_role_relation 写 base_user_relation(有 f_user_id) ✅本仓已修
授权接口返 200 但一行没写 objectType 传了 'Role'(大写) 必须小写 'role';module 传一维数组 ✅本仓已修(冒烟断言覆盖一维/二维两种写法)
非管理员拿到了全部菜单 只查了角色授权 四源合并(直授+角色+组织+岗位) ✅本仓已修(冒烟断言「菜单已按授权收窄」+「访问 User/List ⇒ 403」)
菜单授权没生效但接口放行 菜单 f_url_address ≠ 前端 Route path 三处(urlAddress / Route path / 守卫 key)必须一字不差 ✅本仓已修(scripts/check-module.sh 的第 9 条接触点逐模块钉住)
Option<Form<T>> 编译不过 axum 0.8.9 的 Form 无 OptionalFromRequest 取原始 body 自己 serde_urlencoded 解析 ✅本仓已修(登录端点即此写法)
405 返回 HTML / 丢 Allow 头 用了 axum 的 method_not_allowed_fallback 用响应改写中间件(链尾) ✅本仓已修(routes.rs 测试断言 405 + 保留 Allow 头)
DDL 能从 HTTP 下载 DDL 落在 web root 移到 db/ + 兜底守卫 ✅本仓已修(测试断言两条 DDL 路径都返 404)
第二个实例起不来 pglite 单实例独占数据目录 换数据目录/端口
集成测试互相撞车 pglite 独占 + 种子账号唯一 串行跑 或 各用独立数据目录
账号能建重复 官方 f_account 无 UNIQUE(故意的) 唯一性应用层保证;只比 delete_mark=0 的行
data/ 里的库改了不生效 schema 只在首次建表时执行 改 schema ⇒ 清空 data/ 重建

明确不在 v1 范围

  • 低代码引擎(JNPF 的表单/流程/代码生成)—— 官方能力,本仓不碰。
  • 多租户(jnpf-tenant*)—— 单租户固定 f_tenant_id='0'。
  • 按钮/列/表单/数据范围级授权(base_module_button / _column / _form / _data)—— 官方 DDL 里都有,但 v1 只做 item_type='module'(菜单)一类。
  • Redis / Sa-Token —— 内存 token 表即可(进程重启即失效,与 JNPF 的 Sa-Token 内存模式同代)。
  • 分页 —— 契约里的 List 就是全量(前端不分页)。要分页是 JNPF 稳定期的 SuperServiceImpl.page。
  • base_user.secretkey / f_role_id 的 JNPF 真实算法(官方是 md5(md5(raw)+secretkey))—— 本仓留位待迁移补;本仓用 md5(明文) 即可(登录比的是同一个值)。

记忆约定

  • 踩坑清单与长 traceback → docs/<子系统>/<topic>.md(本文件表格即其索引)。
  • 工作日志 → .workbuddy/memory/YYYY-MM-DD.md。
  • 本文件只留「原则 + 决定 + 一句话摘要」。改代码后回头核对本文件是否还成立。