- 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 零重编。
31 KiB
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
架构红线
-
🔴 契约优先于实现。 任何端点的路径、入参、返回形状、错误码,必须与
ssw-jnpf-lite-react逐字一致。不确定时先读 react 技能源码,别凭印象。 -
🔴 业务失败一律 HTTP 200 +
{code,msg,data}。 成败只看 body 的code。 例外只有一个:未知路由保留 HTTP 404(body 仍是ActionResult形状)。 🔴 鉴权失败也是 HTTP 200(code=600未登录 /code=403无菜单权限)—— 与tdc-rs的 401/403 裸 body 相反,别把 tdc-rs 的形状抄过来。 -
🔴
base_*表名与列名逐字对齐官方 DDL(含两个官方陷阱,见下)。 不允许自创表名/列名——迁移期靠--data-only导数据,列名差一个字符就导不进去。 -
🔴 四源权限合并 + 管理员短路 + 未映射放行。
- 管理员(
f_is_administrator=1)在任何 SQL 之前短路放行; - 权限 = 用户直授 + 角色 + 组织 + 岗位,只查角色会漏授权;
- 菜单未映射到
base_module⇒ 放行(对齐SswPermissionGuard的 warn 路径), 不是拒绝。这条最容易写反,且静默(不报错),所以必须有测试钉住。
- 管理员(
-
🔴 口令不得外泄。 库内存
md5(明文);对外响应手工挑字段(用户列表要去掉password)。 密文只在请求体里出现,永不回显。 -
🔴 前端不直接持有数据库。 一切访问经
/api/**。 -
🔴 DDL 绝不可从 HTTP 下载。 平台 DDL 已
include_str!进sspf二进制(不在任何 web root); 业务 DDL 在packs/<app>/schema/里,同样不许放进src/frontend/或任何静态目录。 -
🔴 同一文件的多个 Edit 必须串行(并行 Edit = last-writer-wins 静默覆盖)。 改完必须 grep 复核全部改动点。
-
🔴 面 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 ⇒ 两把尺子同时红)。 -
🔴 两套权限判据并存,别混。
- 面 A 守卫按菜单路径(
base_module.f_url_address,见红线 4); - 面 B 守卫按点权限编码(
base_module.f_en_code,官方@SaCheckPermission("permission.user"))。 两套结构相同但数据源不同:管理员短路 → 查授权 → 查不到 ⇒ 放行 → 四源成员判定 → DB 出错 ⇒ 拒绝。 🔴 同一用户可能在面 A 通、面 B 拒(这不是 bug,是两套判据)——改动任一套都不许动另一套。
- 面 A 守卫按菜单路径(
-
🔴 面 B 未登录返
code=602,不是600。官方前端request.ts只对601/602清 token ⇒ 返600会让官方前端卡死不跳登录页。面 A 仍是600(冻结)。 -
🔴 平台 / 业务分离(靠仓库边界,不靠目录纪律)。
- 平台 = 已发布的
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)。
- 平台 = 已发布的
-
🔴 生产档弱口令守卫(
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 为准。
关键实现细节(改代码前必读)
- 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 实现可读作参考(但不共享代码)。 - 口令比对:
base_user.f_password存md5(明文)的小写 hex; 登录时decrypt(密文)得到md5(明文)⇒ 大小写不敏感比较。 - 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)保持数字。 - 主键是 36 位 UUID v4(带连字符),列
varchar(50)装得下。不是tdc-rs的雪花十进制。 - 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)。 - pglite 单 backend 串行化:所有 DB 访问必须持进程级
db_lock(OnceLock<Arc<tokio::Mutex<()>>>)。同时一个数据目录只能被一个进程打开 ⇒ 集成测试要么串行、要么各自用独立数据目录。 - 查询结果序列化:沿用
tdc-rs的手法SELECT row_to_json(q)::text AS _row FROM (<sql>) q⇒ 取单列文本 ⇒serde_json::from_str。 不要另起逐列类型映射分支。 - 标识符白名单:任何拼进 SQL 的表名/列名都要过白名单
(
[A-Za-z][A-Za-z0-9_]*),并在启动时自检全部拼接点,不过白名单 ⇒ 秒退。 include_str!路径相对src/platform/db.rs:写../../db/schema.sql(平台层比原来深一级)。- axum 0.8 语义:
Router<S>的S是"还缺什么状态" ⇒with_state必须是链条最后一步。 Form<T>在 axum 0.8.9 只实现FromRequest(没有OptionalFromRequest) ⇒Option<Form<T>>编译不过 ⇒ 需要"解析失败也走业务信封"的表单端点, 取原始 body 自己用serde_urlencoded::from_bytes解析。 (/api/oauth/Login正是这种端点,且grant_type不能加 camelCase。)- 405 的 JSON 兜底用响应改写中间件(挂在链尾),不要用 axum 的
method_not_allowed_fallback(后者只对调用那一刻已注册的路由生效,且丢Allow头)。 - schema 初始化:启动时探测
base_user是否存在,不存在才按;拆分执行schema.sql(拆分要字面量感知,别把字符串里的;当语句边界)。 - 路径与 cwd 解耦:
resolve_project_dir()从可执行文件向上找锚点文件,static/与data/都基于它 —— 后台启动时 cwd 会漂移,改成相对 cwd ⇒ 500。 - 未知路由 = HTTP 404(body 仍是
{code:404,msg:'接口不存在',data:null})。 不要用"全局 404 兜底"把它变成 200。 - CRUD 引擎的三个 handler 是
pub(crate)(handle_list/handle_save/handle_delete) ⇒ 业务模块在modules/里调它们,平台层不反向依赖业务层。 - 菜单的
f_url_address与f_en_code必须一字不差地一致:MenuSpec.url_address==EntitySpec.module_key== 前端<Route path="…">(去前导斜杠)—— 三者任一不一致 ⇒ 菜单显示了但守卫不命中(或反过来)⇒ 静默失败。modules/mod.rs的单测钉住前两者;perm-smoke.sh的菜单断言钉住实际树形状。 - 加一个业务模块 = 一条命令:
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 返PcUserVO5 字段 / 未登录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。 - 本文件只留「原则 + 决定 + 一句话摘要」。改代码后回头核对本文件是否还成立。