Files
ssw-jnpf-lite-rust/HANDOFF.md
T
admin f8d2cf4cf5 feat(dep): 技能改纯 rlib 消费 —— fetch 只解 lib/,不再解包平台源码
- fetch-platform.sh: 解包加 --exclude=crates/src/frontend/Cargo.toml/Cargo.lock,
  只留 lib/ + rust-toolchain.toml + bin/ + docs/README(vendor 少解 ~62M 源码)
- 校验改为认 vendor/.../lib/libsspf-*.rlib,不再读 crates/sspf/Cargo.toml
- 所有「dev 回退 path 到 vendor 源码」改为「极端回退用 git tag 依赖」
- 文档同步 SKILL/README/HANDOFF

验证: cargo clean 后 dev 5.14s / release 9.34s,只编本仓 5 crate;
vendor 无任何平台源码;二进制 --help 正常(基于 sspf v0.5.0)。
2026-11-05 12:50:46 +08:00

641 lines
49 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# HANDOFF.md —— ssw-jnpf-lite-rust 交接文档
> **给下一个会话的你**:本文件 + `CLAUDE.md` 两份读完就能直接开工,**不需要**重新推导任何设计。
> 目标:把「JNPF 兼容契约的 Rust 实现」从零写到**验收全绿**。
---
## 0. 2026-11-05:升级为**方案 C —— 预编译 rlib,零重编平台**(**本次**)
> 背景:上一版(§0 第二批)是「解包源码 + path 依赖」,消费方每次仍要**重编平台 17 个 crate
> + axum/tokio 等**(首次 `cargo build` 数分钟)。目标是「其他用户首次构建也别重编平台」,
> 最终落地**方案 C**:平台包内含**预编译 rlib 完整闭包** `lib/`,本仓用 `--extern` 直接链接。
**现在的依赖模型(务必按这个理解;旧文档里「path 依赖」的写法已废弃——本仓只依赖 rlib)**
- **本仓 `Cargo.toml` 不声明任何外部 crate 依赖**(`[workspace.dependencies]` 为空)。
平台 `sspf`、`axum`、`tokio`、`serde`、`serde_json`、`http`、`bytes` 全部来自平台包 `lib/`。
- `scripts/fetch-platform.sh vX.Y.Z` 解包 `vendor/sspf-vX.Y.Z/` 后,生成 `.cargo/config.toml`:
`rustflags = ["--extern","sspf=…/lib/libsspf-<hash>.rlib", … axum/tokio/serde/serde_json/http/bytes …,
"-L","dependency=…/lib"]`,并复制包内 `rust-toolchain.toml` 到本仓根(锁 `rustc 1.95.0`)。
- `vendor/` 与 `.cargo/config.toml`(含本机绝对路径)**不进版本库**;`rust-toolchain.toml` 提交。
**实测结果**:`cargo build` **5.7s** / `cargo build --release` **11s**,只编译本仓 5 个 crate
(`packs/*` + `src/backend`),**零编译平台 17 crate、零编译 axum/tokio**。
**四个踩过的坑(平台侧/消费侧各修了,留作教训)**
1. **`lib/` 必须是构建产物 `deps/` 的整目录副本**(`.rlib` + `.rmeta` + proc-macro `.dylib`
+ 原生 `.a`)。只拷 `lib*.rlib` 会漏 `serde_derive`/`tokio_macros` 的 `.dylib` ⇒ `E0463 can't find crate for sspf`。
2. **rlib 必须 bitcode-free**:平台 `release.sh` 出包时 `cargo clean` 隔离目录 +
`--config profile.release.lto=false --config profile.release.embed-bitcode=false`。
否则 rlib 带 LLVM22 bitcode,macOS 系统 `ld`(libLTO 21)解析不了 ⇒ `could not parse bitcode object file`。
(顺带:clean 是必须的,否则旧 profile 的多 hash rlib 残留,`head -1` 会选到旧的那个。)
3. **消费方必须用平台那份 axum**:sspf 公共 API 带 `axum::Json`/`http::HeaderMap`/`bytes::Bytes`。
本仓若自己编 axum 就是「同名 crate 两实例」⇒ 跨边界 `E0308 mismatched types`。
⇒ 本仓 `[workspace.dependencies]` 清空、backend 去掉 axum/tokio,全部走 `--extern`。
4. **消费方 release profile 必须 `lto = false`**:预编译 rlib 无 bitcode,开 LTO 会
`failed to get bitcode from object file for LTO`。平台 rlib 已 opt-level=2,损失很小。
**本次改动文件**:根 `Cargo.toml`(清空 workspace.dependencies + `lto=false`)、
`src/backend/Cargo.toml`(去 axum/tokio)、`scripts/fetch-platform.sh`(整包移旧目录 + 生成多 `--extern`)、
`.gitignore`(忽略 `.cargo/config.toml`),新增 `rust-toolchain.toml`(提交)。
平台侧见 `ssw-platform` 仓 `scripts/release.sh` + `docs/SSPF-PLATFORM-PACKAGE.md` §6。
---
## 0. 2026-11-04 第二批:技能仓改为「依赖已发布的 sspf 包」(历史)
> 上一批(平台仓 `ssw-platform`)把示例搬出去并发布 `v0.4.0`;本批把**技能仓**改成消费者。
> 🔴 **2026-11-04 深夜**:平台发了 `v0.5.0`(`Db::query_json_raw` / `query_rows` / `lock_owned`),
> 本仓依赖随之升到 `v0.5.0`(业务侧无代码改动:本仓不直接碰 `PGlite`)。
**做了什么**
1. **删除自研平台**:`src/backend/src/platform/`(17 文件)、`routes.rs`(35K)、
`bootstrap.rs`、`db/schema.sql`、`tests/`(7 个集成测试,测的是被删的那份实现)。
备份在 `/tmp/skill-backup/backend-2216/`。
2. **平台改为依赖已发布包**:根 `Cargo.toml` 的
`[workspace.dependencies] sspf = { path = "vendor/sspf-v0.5.0/crates/sspf", version = "0.5" }`(**历史写法**:现已是方案 C 的 rlib 消费,`fetch-platform.sh` 不再解包平台源码),
成员一律 `sspf = { workspace = true }`。解析结果:
`sspf v0.4.0 (...?tag=v0.4.0#ff34ca50)`,**0 个 `sspf-pack-*` 被平台带进来**。
3. **示例业务包迁入**:`packs/{demo,shop,books,asset}/`(表 DDL + 列 + 菜单 + 面 B 路由),
依赖从 `sspf-sdk` 改为门面 `sspf`;`use sspf_sdk::…` → `use sspf::…`。
4. **应用瘦成薄壳**(`src/backend/` 从 ~4000 行降到 ~500 行):
- `main.rs`:`--enc` / `--help` + `Platform::new().config().packs().router().static_dir().serve()`;
- `lib.rs`:`pub mod modules; pub mod packs_gen;`;
- `packs_gen.rs`:4 个 `load_static` + manifest 快照(生成物);
- `modules/`:4 个面 A 适配器(spec 只 `pub use` 转发)。
5. **脚本重构**:
- 新增 `check-scaffold.py`(SC1–SC6「本仓只准有业务」+ `--self-test` 6/6);
- 新增 `pack-sync.py`(重写:4 处派生位置,`--check` 防漂移);
- 新增 `new-pack.sh` / `new-pack.py`(造包脚手架,端到端验证过);
- 新增 `verify.sh`(一键 7 步 / `--fast` 4 步);
- **删除** `check-module.sh` / `check-boundary{,-scan}` / `check-contract{,-scan}` / `check-citations{,-scan}`:
它们测的是**本仓那份平台实现**(分层 / 契约对账 / 引文),平台搬走后没有测量对象 ⇒ 留着就是假绿。
6. **契约同步**:`docs/contract.md` 补入 `asset` 包 —— `[MENU]` +1、`[MENU_TREE]` → 9 菜单
(`…|图书超市:|数据资源:`)、`[MODULE]` +1、`[ENDPOINT]` +3(面 A)、`[FACE]` A 25 → 28。
§8.4 的「值住在哪」改为「平台在 `sspf`,业务在 `packs/<app>/`」。
7. **文档**:`SKILL.md` / `README.md` / `CLAUDE.md` / `HOWTO_MODULE.md` / `docs/runbook.md`
全部按新架构重写关键章节(「自包含」→「依赖已发布包 + 锁 tag」;「六道闸门」→「两类判据」)。
**验收(全部实际跑过)**
| 项 | 结果 |
|---|---|
| `cargo build` / `cargo build --release` | ✅ 通过(平台来自 `vendor/sspf-v0.5.0/lib/` 的**预编译 rlib**,零重编;无需 Gitea) |
| `cargo test --workspace` | ✅ 全绿(4 个包各自 14/14/3/3 条包自检 + 应用单测) |
| `python3 scripts/check-scaffold.py` | ✅ PASS=6 FAIL=0 |
| `python3 scripts/check-scaffold.py --self-test` | ✅ 反自证 6/6 |
| `python3 scripts/pack-sync.py --check` | ✅ 4 个包 / 4 个模块,无漂移 |
| `bash scripts/perm-smoke.sh` | ✅ **PASS=32 FAIL=0** |
| `bash scripts/perm-smoke-jnpf.sh` | ✅ **PASS=18 FAIL=0 SKIP=0**(覆盖 18/18) |
| `new-pack.sh probe Widget` 端到端 | ✅ 生成 → 编译 → 起服务 → 面 A `600` / 面 B `602` / 表数 182(177 + 5)→ 删包 |
**踩过 / 别踩**
- 🔴 **`pack-sync.py` 的 `ROOT` 不能用脚本自身路径**:反自证在临时树里跑时,
它会把「真实仓库」当成目标 ⇒ SC6 自证**假绿**。已加 `PACK_SYNC_ROOT` 环境变量。
- 🔴 **生成段不能只放「数组元素」**:`replace_region` 会把 `pub const … = &[` 连同 `];` 一起盖掉
⇒ 语法错。正确做法是生成器输出**完整声明块**。
- 🔴 **业务菜单不要传给 `.menus()`**:`.packs(reg)` 已经把 `PackRegistry.menus` 带进种子,
给两次会在种子 INSERT 撞主键。
- 🔴 **`resolve_project_dir` 找不到本仓**:平台默认锚点是 `src/backend/db/schema.sql`(本仓已删)
⇒ `main.rs` 自己按 `SSW_PROJECT_DIR` → `Cargo.toml` + `packs/` 向上找 → cwd。
- 🔴 **加了 `asset` 包 ⇒ 菜单树从 8 变 9**,`[MENU_TREE]` 不改 ⇒ 面 A 尺子当场红(它是对的)。
**第二批遗留(可选)**
- `MIGRATION.md` / `JNPF_COMPAT_SURFACE.md` / `JNPF_SOURCE_AUDIT.md` 是**历史技术报告**,
其中引用的 `src/backend/src/platform/*` 路径已不存在 —— 需要时按 `sspf` 包的模块对位,
不必逐条改(它们描述的是行为规格,不是本仓结构)。
- 前端 `src/frontend/dist/` 目前 gitignore;若要「开箱即用」,可把构建产物一起提交。
---
## 0. 当前状态
**v1 已完成 + v1.1 双面后端(面 B)已落地,验收全绿**(每一条 ✅ 都有实际执行输出,见 §9 与各任务报告)。
| 项 | 状态 |
|---|---|
| 目录 `~/Desktop/workspace/ssw-jnpf-lite-rust/` | ✅ 已建并已 commit(`main` 分支) |
| `CLAUDE.md` | ✅ 已写;**已逐条核对并与代码同步**(Task 12;2026-10-26 再同步面 B) |
| `HANDOFF.md`(本文件) | ✅ 已写并已同步(§0 状态表 / §9 交接话术,Task 12;2026-10-26 再同步面 B) |
| 代码 | ✅ 后端已实现(`src/backend/`,Rust 2021 + axum 0.8 + pglite-rs 0.2,**10 张表**、**32 条路由 = 面 A 27 + 面 B 5**) |
| 面 B(官方 JNPF 契约面) | ✅ 已落地(`src/backend/src/platform/jnpf.rs`,S1–S6 全完成):判别头 `Vue-Version: 3` 分流 · `PcUserVO` 5 字段 · `PageListVO` 分页 · 点权限(`f_en_code`)守卫 · 未登录 `602` |
| 前端 | ✅ 已逐字复制(`src/frontend/`;**唯一改动 = vite 代理端口改成 `30010`**,其余文件逐字节相同) |
| 脚本 | ✅ `scripts/perm-smoke.sh`(**32 条断言**)+ `scripts/check-module.sh`(9 接触点静态自检,**57 条 ✅**)+ `scripts/perm-smoke-jnpf.sh`(**面 B 尺子,18 条断言;已全绿 PASS=18 / SKIP=0**) |
| 工程脚本 | ✅ `run.sh`(`install`/`build`/`dev`/`backend`/`frontend`/`stop`/`logs`,退出码 0/1/2) |
| 文档 | ✅ `README.md` / `docs/runbook.md` / `.env.example` |
| 官方对齐文档 | ✅ `JNPF_SOURCE_AUDIT.md`(官方源码逐行核对)· `JNPF_COMPAT_SURFACE.md`(**面 B 规格 + 落地状态**)· `MIGRATION.md`(迁移指南) |
| 技能资产 | ✅ **仓根 = 技能根**(`SKILL.md` 与 `src/` `scripts/` `references/` 同仓,改一次仓 = 改一次技能);`~/.agents/skills/ssw-jnpf-lite-rust` → 仓根(绝对软链),`~/.claude/skills` / `~/.workbuddy/skills` / `~/.qwenworkcn/skills` 三处相对软链已验证可读 `SKILL.md` |
| 验收门 | ✅ 全绿(编译 **0 error 0 warning** · 单测 **197 passed / 0 failed** · 面 A 冒烟 **PASS=32 FAIL=0** · 面 B 冒烟 **PASS=18 FAIL=0 SKIP=0** · 前端**浏览器**手验全过) |
**读法**:`CLAUDE.md`(红线与坑位,日常改代码必读)→ §9(怎么起 / 怎么复现验收)。
§3(设计)与 §5(实施顺序 step 0–12)已**完结**,留作背景与决策记录,**不要再照着实施一遍**。
---
## 1. 决策记录(本轮问答全过程,含被推翻的方案)
> 保留被推翻的方案,是为了避免下个会话"重新考虑"已经讨论过的问题。
| # | 问题 | 决定 | 理由 |
|---|---|---|---|
| 1 | Rust 版做成什么形态? | **先做真实项目,验证后再抽技能** | 技能是模板;没跑通的模板没有价值 |
| 2 | v1 做多大? | **全量契约对齐**(auth + 5 组 `base_*` + 四源权限 + 两段种子 + 3 业务模块 + 冒烟) | 迁移价值全在权限与数据模型这两块,缺一块就不成立 |
| 3 | 落在哪个仓? | **独立仓** `ssw-jnpf-lite-rust` | ~~原方案:tdc-rs 开分支~~(已被 #4 推翻) |
| 4 | 运行时拓扑? | **先不碰 tdc-rs,独立仓做** | tdc-rs 已占它自己的后端端口,且已有自己的 `/api/oauth/Login`(JSON 账号库),两套同路径不同语义会打架 |
| 5 | 目录名? | **`ssw-jnpf-lite-rust`**(**正式名称**,2026-10-26 用户改定) | ~~原方案:`tds-lite-rs`~~(crate/binary 名已一并改名) |
| 6 | 数据库? | **pglite-rs 0.2**(进程内原生 PG) | 沿用 tdc-rs 已验证的形态;零服务零 Docker |
| 7 | 后端端口? | **`:30010`**(前端 vite `:5173`) | 避开 tdc-rs 已占用的后端端口 |
| 8 | 前端怎么办? | **逐字复制** react 技能的前端,**零改动** | 前端零改 = 契约真的对齐了(改了就说明后端在迁就前端) |
| 9 | 业务实体怎么实现? | **spec 驱动 CRUD 引擎**;5 组 `base_*` 走**显式 handler** | 业务模块语义简单可声明化;`base_*` 的语义(一维授权数组 / 用户↔角色 / 机构树防环)塞不进通用引擎 |
| 10 | 冒烟脚本的 node 依赖? | Rust 二进制加 `--enc <明文>` 模式,脚本**自证 cipher**,不依赖 node | 去掉 node 依赖 = 冒烟可在任何装了 Rust 的机器上跑 |
| 11 | 抽技能的时机? | **验收门全绿之后**再抽 | 目录结构现在就和 react 技能对齐(`src/backend` + `src/frontend` + `scripts/` + `run.sh`),届时 1:1 复制即可 |
**关键约束**:`tdc-rs` **只读**。本仓不 import 它的代码、不共享数据目录、不共享端口。
可以**读**它的 `src/cipher.rs` / `src/db.rs` / `src/envelope.rs` 作工程手法参考。
🔴 **实施期的逐条裁决(98 条)另见 [`docs/decisions.md`](docs/decisions.md)** ——
上面这张表是**立项期**的问答;实现过程里还有 98 条「什么 — 为什么 — 判错了的代价」级别的裁决
(契约歧义、pglite 的坑、评审发现的取舍、挂起的限制),那是**代码之外的「为什么」**。
---
## 2. 目标与非目标
**目标(v1 做完的样子)**:
1. 用 **Rust** 起一个**单二进制、零外部服务**的后端,行为与 `ssw-jnpf-lite-react`(NestJS)**逐条一致**。
2. 前端**一行不改**就能跑通(直接复用 react 技能的 `src/frontend`)。
3. `base_*` 表结构与官方 DDL **逐字一致** ⇒ 迁 JNPF 时**导数据即可**(`--data-only`)。
4. 权限闭环(登录 → 菜单树 → 建用户 → 授权 → 收窄 → 403)**有自动化冒烟钉住**。
5. 跑通之后,1:1 复制成技能(`ssw-jnpf-lite-rust`)。
**非目标(明确不做)**:低代码引擎 / 多租户 / 按钮·列·表单·数据范围级授权 /
Redis+Sa-Token / 分页 / `secretkey` 的官方双层 md5 算法。理由见 `CLAUDE.md`「明确不在 v1 范围」。
---
## 3. 设计(已定稿)
### 3.1 落点与边界
```
ssw-jnpf-lite-rust/ ← 独立 git 仓(已 init,未 commit)
├── Cargo.toml ← 【workspace 根】members=["src/backend"] + [profile.release]
├── src/backend/ ← 名字保留是为了将来抽技能时目录与 react 版对齐
│ ├── src/*.rs ← 16 个模块(见 §3.3)
│ ├── db/schema.sql ← 10 张表完整 DDL
│ └── data/ ← 运行期(gitignore)
├── src/frontend/ ← react 技能前端逐字复制(零改)
├── scripts/{perm-smoke.sh,check-module.sh}
├── run.sh ← install/build/dev/stop/logs
└── .env.example
```
**端口**:后端 `30010` · 前端 `5173`(vite)· vite proxy `/api` → `http://127.0.0.1:30010`。
🔴 **本仓端口是硬约定**:`run.sh` 的端口常量不许改 —— `PORT` 被设成 ≠ 30010 时
`run.sh dev` / `run.sh backend` **报错退出 2**(要换端口请**直接跑二进制**);
**后端二进制本身**确实吃 `PORT`(非法值回落 30010)。
🔴 后端**默认只监听 `127.0.0.1`**(`BIND_ADDR` 可覆盖);`BIND_ADDR=0.0.0.0` 才对外暴露。
**数据库**:`pglite-rs`,默认落盘 `src/backend/data/lite.pg`;`PGLITE_DIR=memory://` ⇒ **临时库**
(系统临时目录里的一次性数据目录,进程退出即销毁;pglite-rs 0.2.7 **没有**真内存模式)。
### 3.2 契约逐字对齐表(对着 react 技能源码抄)
| 契约点 | 精确口径 | react 源码位置 |
|---|---|---|
| 统一返回 | `{code,msg,data}`;成功 `code=200,msg='成功'`;失败 `data=null` | `src/backend/src/common/action-result.ts` |
| HTTP 状态 | 业务失败/鉴权失败 **HTTP 200**;**未知路由 HTTP 404**(body 仍是 ActionResult) | `common/action-result.filter.ts` |
| 错误码 | 未登录 `600` · 无菜单权限 `403` · 业务失败 `400`(msg 透传) | 同上 + 各 controller |
| 登录 | `POST /api/oauth/Login`,form-urlencoded `account`/`password`(密文 hex)/`grant_type=password` | `auth/auth.controller.ts:19` |
| 登录失败文案 | 缺参 → `400 '缺少 account / password'`;grant_type 不支持 → `400`;口令错 → `400 '账号或密码错误'` | `auth/auth.controller.ts` |
| 登录成功体 | `{token, expiresIn:7200, tokenTypeName:'bearer'}` | `auth/auth.service.ts` |
| CurrentUser | `GET /api/oauth/CurrentUser` → `{userInfo:{userId,userAccount,userName,isAdministrator}, menuList}` | `auth/auth.controller.ts:34` |
| cipher | `md5(明文)` → AES-256-ECB-PKCS7(key=`md5("EY8WePvjM5GGwQzn")` 的 32 ASCII 字节)→ hex | `common/cipher.ts` |
| 检验向量 | `encryptPassword('123456')` = `d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b` | `common/cipher.ts` 注释 |
| 口令比对 | 库内存 `md5(明文)` 小写 hex;登录解出 `md5(明文)` ⇒ **大小写不敏感**比较 | `auth/auth.service.ts` |
| 权限四源 | 直授 + 角色 + 组织 + 岗位;**管理员短路在 SQL 之前**;**菜单未映射 ⇒ 放行** | `sys/permission.service.ts` |
| 菜单树 | `parentId||'0'` 为根;按 `sortCode` 升序;节点 `{id,fullName,urlAddress,icon,parentId,children}` | `sys/permission.service.ts:toTree` |
| 授权写入 | `PUT /api/permission/Authority/Data/{objectId}`,body `{objectType:'role'(小写), module:[...]}`(**一维**) | `sys/authorize.controller.ts:39` |
| 授权读取 | `GET /api/permission/Authority/RoleModules?roleId=` → `string[]` | `sys/authorize.controller.ts:52` |
| 角色授权写 | 旧行**软删**(`delete_mark=1`)后插新行 | `sys/sys.service.ts:saveRoleModules` |
| 用户↔角色 | `setUserRoles` = 先 `delete` 旧 `base_role_relation` 行再插新行 | `sys/sys.service.ts` |
| 用户列表 | 去掉 `password`,追加 `roleIds` / `roleNames` | `sys/sys.service.ts:listUsers` |
| 账号唯一 | 应用层保证,**只比 `delete_mark=0`**(官方 DDL 无 UNIQUE) | `sys/sys.service.ts:saveUser` |
| 机构删除 | 有子机构 ⇒ `400 '该机构下还有子机构,先删除子机构'` | `sys/sys.service.ts:deleteOrganize` |
| 业务 List | 软删过滤 + `creatorTime DESC` | `shop/product.service.ts` |
| 业务 Save | 无 id ⇒ 新 36 位 UUID + `creatorUserId='admin'` + `creatorTime=now` + `deleteMark=0`;有 id ⇒ 覆盖更新 | `shop/product.service.ts` |
| 业务 Delete | **软删**(`f_delete_mark=1`) | `shop/product.service.ts` |
| numeric 列 | JSON **字符串**(`"9.90"`) | `shop/product.entity.ts` + TypeORM numeric→string |
| int 列 | JSON 数字 | `books/book.entity.ts` |
| 端点命名 | `/api/ssw/{appCode}/{Entity}/{List|Save|Delete}` | 各 controller |
**种子里必须逐字保留的常量**(`sys/seed.service.ts` 的字面量数组):
- 角色:`role_admin`/enCode `admin`/管理员/sort 1;`role_user`/enCode `user`/使用者/sort 2
- 菜单(`f_type`:1=目录 2=页面):
| id | fullName | urlAddress | parentId | type | icon | sortCode |
|---|---|---|---|---|---|---|
| `m_sys` | 系统管理 | `system` | `0` | 1 | setting | 1 |
| `m_user` | 用户管理 | `system/User` | `m_sys` | 2 | — | 2 |
| `m_role` | 角色管理 | `system/Role` | `m_sys` | 2 | — | 3 |
| `m_org` | 机构管理 | `system/Organize` | `m_sys` | 2 | — | 4 |
| `m_menu` | 菜单管理 | `system/Module` | `m_sys` | 2 | — | 5 |
| `m_demo` | Demo 示例 | `demo-item` | `0` | 2 | app | 6 |
| `m_product` | 产品管理 | `shop/Product` | `0` | 2 | app | 7 |
| `m_book` | 图书超市 | `books/Book` | `0` | 2 | app | 8 |
> ⚠️ `perm-smoke.sh` 在 react 版里是**从 `seed.service.ts` 的字面量动态算期望菜单树**的。
> Rust 版没有那个文件 ⇒ **两种做法二选一**:
> (a) 把上表搬进冒烟脚本作为字面量;或 (b) 后端暴露一个只读端点/二进制子命令打印期望树。
> **推荐 (a)**:脚本自包含、离线可跑。菜单增删时同步改脚本(这是**刻意的耦合**,不是缺陷)。
**两段式种子**(`sys/seed.service.ts`):
- `ensureBase`(**每次启动都跑**,幂等):按 `enCode` 补内置角色、按 `urlAddress` 补内置菜单、
补齐 admin 角色对内置菜单的授权(取库里**真实行 id**)。
**只补缺项**:不覆盖已改值;**同 urlAddress 已有行(含软删)不复活**。
- `firstSeed`(**仅 users==0 时跑一次**):`admin/123456`(`f_is_administrator=1`, `f_organize_id='0'`)
+ 一条 `base_role_relation`(`object_type='user'`, `object_id='admin'`, `role_id='role_admin'`)。
角色/菜单/授权行已由 `ensureBase` 建出,**不重复写**。
### 3.3 后端模块划分
| 模块 | 职责 | 备注 |
|---|---|---|
| `main.rs` | 启动装配:开库 → 起 schema → seed → 建路由 → 挂中间件 → 监听(+ 优雅停机) | `with_state` 必须是最后一步 |
| `config.rs` | `PORT` / `BIND_ADDR` / `PGLITE_DIR` / 静态目录 / 种子开关 | 环境变量 |
| `db.rs` | pglite 封装:`open()` / `open_temp()` / `ensure_schema()` / `query_json()` / `query_json_params()` / `exec()` / `exec_params()` / `scalar_text()` | 单 backend ⇒ 进程级 `db_lock` |
| `cipher.rs` | `md5_hex()` / `encrypt_password()` / `decrypt_to_md5()` | **逐字对齐 `cipher.ts`** + 上游向量单测 |
| `envelope.rs` | `ActionResult{code,msg,data}` + `ok()` / `fail()` | 业务失败恒 HTTP 200 |
| `ids.rs` | `new_uuid()` → 36 位 UUID v4 | **不是** tdc-rs 的雪花 |
| `session.rs` | 内存 token 表(`lite-` 前缀 + 32 hex) | 进程重启即失效 |
| `auth.rs` | 登录 / CurrentUser / `require_login()` / `require_module()` / `require_login_any()` | 守卫返回 `ActionResult`(600 / 403 / 602) |
| `jnpf.rs` | **【面 B】** 判别头 `Vue-Version: 3` · `PcUserVO` / `PageListVO` / `ListVO` 构造 · 点权限守卫(`f_en_code`)· 5 个官方 RESTful 端点 | 与面 A **共用** `base_*` 表 / cipher / seed,但**权限判据不同** |
| `permission.rs` | `resolve_user_module_ids()` 四源合并 / `has_module()` 管理员短路+未映射放行 / `build_menu_list()` | **四源 + 两条放行路径都要有测试** |
| `seed.rs` | `ensure_base()` + `first_seed()` | 幂等 + 只补缺项 |
| `sys.rs` | 5 组 `base_*` 的显式 handler 语义 | 用户/角色/机构/菜单/授权 |
| `crud.rs` | spec 驱动的通用 CRUD 引擎(List/Save/Delete)—— **不含任何业务表名 / app_code** | 业务实体用 |
| `entity.rs` | `EntitySpec` / `ColumnSpec` 的**类型**定义(不含任何业务 spec) | 引擎与业务层之间的契约 |
| `routes.rs` | 路由装配(404 / 405 / 413 改写 / catch-all 三层兜底)+ `merge(modules::router())` | |
| `state.rs` | `AppState{config, db, sessions}`(三个字段全是 `Arc`) | axum `State` 的载体 |
| `lib.rs` | 库入口:`pub mod platform / modules / routes` | 让单测 / 集成测试能直接引用各模块 |
> 🔴 **上表除 `routes.rs` / `lib.rs` 外全部在 `src/backend/src/platform/`(平台层)**。
> 业务层的 `src/backend/src/modules/{mod,demo,shop,books}.rs` = **每个业务模块自带
> spec + 3 个 handler + 自己的 `router()`** ⇒ **加业务模块只碰业务层**。
### 3.4 三个关键取舍
1. **业务实体走 spec 引擎,`base_*` 走显式 handler。**
理由:业务模块语义同构(列表/保存/软删/守卫),声明化后"加一个模块 = 加一条 spec";
而 `base_*` 的语义(一维授权数组、用户↔角色关系、机构树防环、账号唯一性)**塞不进通用引擎**,
硬塞会得到一个既不懂 JNPF 又难懂的框架。
2. **numeric 列在 SQL 投影里就 cast 成 text。**
理由:`row_to_json` 直接给数字 ⇒ serde_json 解析成 f64 ⇒ 回显 `9.9` ⇒ 契约破。
在投影层 `f_price::text AS price` 才是"一次解决、处处一致"。
3. **HTTP 状态语义**刻意**不同于** `tdc-rs`(那边是 401/403 裸 body,这边是 200 + code 600/403)。
理由:react 前端的拦截器只认 `body.code`;两边同时跑时更不能混形状,否则冒烟脚本得写两套。
### 3.5 前端
- **逐字复制** `ssw-jnpf-lite-react/src/frontend` → `src/frontend`(`package.json` / `vite.config.ts` / `src/**`)。
- **唯一允许的改动**:vite 的 proxy 目标端口改成 `30010`(以及 `baseURL` 仍是 `/api`,不变)。
- 前端 `utils/cipher.ts` **保持不变**(它是浏览器侧算法;后端 Rust 侧必须与它**逐字节等价**——由上游向量钉住)。
- 路由 path(`App.tsx`):`/login` `/demo-item` `/shop/Product` `/books/Book`
`/system/User` `/system/Role` `/system/Organize` `/system/Module`
⇒ **去掉前导斜杠**就是 `base_module.f_url_address` ⇒ 也是后端守卫的 module key。**三处一字不差。**
### 3.6 目录/文件对照(react 技能 → 本仓)
| react 技能 | 本仓 |
|---|---|
| `src/backend/src/common/cipher.ts` | `src/backend/src/platform/cipher.rs` |
| `src/backend/src/common/action-result.ts` + `.filter.ts` | `src/backend/src/platform/envelope.rs` |
| `src/backend/src/auth/*` | `src/backend/src/platform/auth.rs` |
| `src/backend/src/sys/permission.service.ts` | `src/backend/src/platform/permission.rs` |
| `src/backend/src/sys/seed.service.ts` | `src/backend/src/platform/seed.rs` |
| `src/backend/src/sys/sys.service.ts` | `src/backend/src/platform/sys.rs` |
| `src/backend/src/{demo,shop,books}/*` | `src/backend/src/modules/{demo,shop,books}.rs`(各自带 spec + handler + router) |
| `src/backend/db/schema.sql` | `src/backend/db/schema.sql`(**本仓要写全 10 张表**) |
| `src/frontend/**` | `src/frontend/**`(逐字复制) |
| `scripts/perm-smoke.sh` | `scripts/perm-smoke.sh`(移植,cipher 改用 `--enc`) |
| `scripts/check-module.sh` | `scripts/check-module.sh`(移植,grep 模式按 Rust 调整) |
| `run.sh` | `run.sh`(改成 cargo 版本) |
---
## 4. 四道验收门("做完"的唯一判据)
| 门 | 命令 | 通过标准 |
|---|---|---|
| ① 编译 | `cargo build --release` | 0 error 0 warning;release 配置:`opt-level=2` / `lto="thin"` / `strip="symbols"` / `codegen-units=16`。🔴 catch-all 依赖默认的 **unwind** 型 panic 策略(Ruling P19)⇒ **禁止**在 release profile 里启用 abort 型 panic(确切写法见根 `Cargo.toml` 里的注释)—— 那会让 catch-all 抓不到 panic ⇒ 契约 §6.5 的「uncaught panic ⇒ HTTP 200 + `{code:400}`」直接失效 |
| ② 单测 | `cargo test` | **实测 197 passed / 0 failed**(8 个测试目标:83+6+19+24+3+18+7+37)。覆盖清单见**契约 §12**(`docs/contract.md:940`):cipher 上游向量 · 信封形状(200/400/600/403)· 四源合并 · 管理员短路 · 未映射放行 · 种子幂等(跑两次结果一致 + 不复活软删行)· CRUD 往返(36 位 UUID / numeric→`"9.90"` / int→`100`)· 账号重复返 400 而非 500 · **面 B**(判别头 / `PcUserVO` 5 字段 / `PageListVO` / 点权限守卫 / `602`) |
| ③ 冒烟 | `bash scripts/perm-smoke.sh` | **32 条断言全绿**(实测 `PASS=32 FAIL=0`,退出码 0),与 react 版断言集**逐条对应**(见 §5 步骤 11 的清单) |
| ③' 冒烟(面 B) | `bash scripts/perm-smoke-jnpf.sh` | **18 条断言全绿**(实测 `PASS=18 FAIL=0 SKIP=0` ⇒ **面 B 覆盖 18/18**)。尺子必须带判别头 `Vue-Version: 3` |
| ④ 前端手验 | `cd src/frontend && npm run dev` | 浏览器 `http://127.0.0.1:5173` → `admin/123456` 登录 → 菜单树正确 → 5 个管理页可增删改 → DemoItem/Product/Book 三页可用 → 退出再登录 |
**外加**:`scripts/check-module.sh`(9 接触点静态自检)的 Rust 版移植,作为"加模块后立刻跑"的前置闸门。
---
## 5. 建议实施顺序(step 0–12)
> 每步都带**完成判据**。做完一步先跑该步的判据,再进下一步。
| step | 内容 | 完成判据 |
|---|---|---|
| **0** | 建 **cargo workspace**(根 `Cargo.toml`:`[workspace] members=["src/backend"]` + `[profile.release]`)+ 成员 crate(依赖照 tdc-rs:axum 0.8 / tokio / serde / serde_json / serde_urlencoded 0.7 / rand 0.8 / hex 0.4 / aes 0.8 / ecb 0.1 / md-5 0.10 / uuid v4 / pglite-rs 0.2 / chrono 0.4) | 根目录 `cargo build` 通过(哪怕是空 main) |
| **1** | `src/cipher.rs` + 单测 | 上游向量**逐字节**相等;`md5_hex` 与 `decrypt_to_md5` 往返一致 |
| **2** | `src/envelope.rs` + 单测 | 业务失败 HTTP 200 + `code=400`;`code=600/403` 同形 |
| **3** | `src/db.rs` + `src/config.rs` + `db/schema.sql`(10 张表) | 进程能开库并建表;`query_json()` 能取回 JSON |
| **4** | `src/ids.rs` + `src/session.rs` | UUID 36 位带连字符;token 登录后可查回 |
| **5** | `src/seed.rs`(`ensure_base` + `first_seed`) | 空库启动 ⇒ admin/123456 + 2 角色 + 8 菜单 + admin 授权;**再启动一次库内容不变** |
| **6** | `src/permission.rs` + 单测 | 四源合并各源单独可注入;管理员短路**不查 SQL**(可用「无授权记录的管理员仍放行」验证);未映射菜单放行 |
| **7** | `src/auth.rs` + `/api/oauth/*` | 登录返 `{token,expiresIn:7200,tokenTypeName:'bearer'}`;CurrentUser 返 `{userInfo,menuList}`;无 token ⇒ `code=600` |
| **8** | `src/sys.rs` + `/api/ssw/sys/*` + `/api/permission/Authority/*` | 5 组 CRUD 语义对齐;**重复账号返 `code=400` + msg `'账号已存在:xxx'`**(不是 500);授权写 `objectType='role'` 小写 + 一维数组 |
| **9** | `src/modules/{demo,shop,books}.rs` + `src/platform/crud.rs` + 3 个业务模块端点 | demo/shop/books 三个模块端点可用;numeric 往返 `"9.90"`;未授权非管理员访问 shop/books ⇒ `code=403` |
| **10** | `src/routes.rs` + `main.rs` 装配 + 404/405 兜底 | 未知路由 **HTTP 404** + `code=404`;405 返回 JSON;`with_state` 在链尾 |
| **11** | `scripts/perm-smoke.sh` 移植(**逐条对应 react 版**) | **32 条断言全绿**(`PASS=32 FAIL=0`) |
| **12** | 前端复制 + `run.sh` + `.env.example` + 文档 | ✅ **已完成**(Task 12):门④ 手验全过(浏览器实测);`run.sh install/build/dev/stop/logs` 可用 |
**step 11 的断言清单**(照 react 版 `scripts/perm-smoke.sh` 逐条移植):
1. 无 token 访问 `User/List` ⇒ `code=600`
2. 加密登录 ⇒ `code=200`;3. 拿到 token(非空)
4. `CurrentUser` ⇒ `code=200`
5. 菜单树与种子表**逐字相等**(推荐做法:把 §3.2 的菜单表搬进脚本作字面量)
6. 建用户 ⇒ `code=200`
7. **重复账号** ⇒ HTTP **200**(不是 500)且 `code=400` 且 msg `'账号已存在:smoke_user'`
8. 写授权(一维数组)⇒ `code=200`;9. 写授权(二维兼容)⇒ `code=200`
10. 非管理员登录 ⇒ `code=200`
11. 非管理员菜单**已收窄**(字符串比对)
12. 非管理员访问 `User/List` ⇒ `code=403`
13. 已授权业务(demo)⇒ `code=200`
14. 未知路由 ⇒ **HTTP 404**(不被吞掉)
15. admin 短路 ⇒ Product 列表 `code=200`
16. Product 新建 ⇒ `code=200`;17. 主键 **36 位**;18. numeric 往返 **`"9.90"`**
19. Product 无 token ⇒ `code=600`;20. 未授权非管理员 ⇒ `code=403`
(react 版断言条数更多,上表是主干;移植时以 react 脚本为准逐条对齐,**一条不落**。)
**另外**:`scripts/check-module.sh`(9 接触点静态自检)移植为 Rust 版——
把「grep TS 文件里的字符串」换成「grep Rust 源 + 检查 spec 注册」,保持同样的 ❌ 判定与退出码约定
(0 全过 / 1 有 ❌ / 2 用法错)。
**脚本退出码约定**(三个入口一致,照抄 react 技能):
| 入口 | 0 | 1 | 2 |
|---|---|---|---|
| `run.sh` | 执行成功 | 运行期失败 | 用法错 |
| `scripts/check-module.sh` | 接触点全过 | 有 ❌ 项 | 用法错 |
| `scripts/perm-smoke.sh` | 全绿(FAIL=0) | 有断言失败 | 前置错误(后端不可达) |
---
## 6. 必读参考文件(绝对路径)
### 契约真源(react 技能,**只读**)
```
~/Desktop/workspace/skills/ssw-jnpf-lite-react/
├── src/backend/src/common/cipher.ts ← cipher 算法 + 检验向量
├── src/backend/src/common/action-result.ts ← {code,msg,data}
├── src/backend/src/common/action-result.filter.ts ← HTTP 状态映射(200/404 的来源)
├── src/backend/src/auth/auth.controller.ts ← 登录 / CurrentUser 端点与文案
├── src/backend/src/auth/auth.service.ts ← 口令比对、token 生成
├── src/backend/src/sys/permission.service.ts ← 四源合并 + 管理员短路 + 未映射放行 + 菜单树
├── src/backend/src/sys/seed.service.ts ← roles/menus 字面量 + 两段式种子
├── src/backend/src/sys/sys.service.ts ← 5 组 base_* CRUD 语义
├── src/backend/src/sys/authorize.controller.ts ← 授权写/读 + 一维 module 归一化
├── src/backend/src/sys/base-*.entity.ts ← 7 张表的列 ↔ JSON 键映射
├── src/backend/src/{demo,shop,books}/* ← 业务模块参照实现
├── src/frontend/src/api/{request,auth,sys,product,book}.ts ← 前端实际调用的端点
├── src/frontend/src/App.tsx ← 前端路由 path(= urlAddress)
├── src/frontend/src/utils/cipher.ts ← 浏览器侧 cipher(后端必须等价)
├── scripts/perm-smoke.sh ← 断言集(逐条移植)
├── scripts/check-module.sh ← 9 接触点静态自检
└── run.sh ← 脚本骨架(改成 cargo 版)
```
### 官方 JNPF(数据模型真源,**只读**)
```
~/Desktop/workspace/jnpf/jnpf-database/PostgreSQL/JNPF-PostgreSQL.sql
base_authorize :812
base_module :2209
base_organize :3178
base_role :3686
base_role_relation :3729
base_user :4479
base_user_relation :4707
(另有 base_module_{authorize,button,column,data,form,link,scheme,use_num}、
base_organize_administrator、base_user_{device,extra,old_password} —— v1 不做)
同目录还有 jnpf_db_init.sql(base_user 的 INSERT 可二次确证列名)等 9 个 init 文件
```
### 本仓的官方对齐文档(面 B / 迁移期必读)
| 文件 | 何时读 | 内容 |
|---|---|---|
| `JNPF_SOURCE_AUDIT.md` | 迁移期 / 存疑时 | 官方源码(Java + Vue)逐行核对报告,全部结论标 `文件:行号`;含本仓与官方的**差异清单 D1–D8** |
| `JNPF_COMPAT_SURFACE.md` | 改面 B 时 | **面 B 规格**:官方形状的端点 / 响应形状 / 码表 / 判别头 / 落地顺序 S1–S6(**已全部落地**)+ §8 已知偏差 B1–B10 |
| `MIGRATION.md` | 稳定期迁 JNPF | 本仓 ↔ 官方的**逐项映射** + 数据 ETL + 口令 `secretkey` 换算(**不需要明文**) |
| `scripts/perm-smoke-jnpf.sh` | 改面 B 时 | **第二把尺子**:18 条官方形状断言(打 `Vue-Version: 3` 头);当前 **PASS=18 SKIP=0** |
| `src/backend/src/platform/jnpf.rs` | 改面 B 时 | 面 B 全部实现(判别头 / VO 构造 / 点权限守卫 / `602` 码) |
🔴 **面 A / 面 B 的判别头 = `Vue-Version: 3`**(官方前端**必发**、本仓前端**唯一不发**的一头)。
🔴 本仓前端**禁止**发 `Vue-Version`(发了 ⇒ 面 A 请求被误判成面 B)⇒ `scripts/check-module.sh` 的「全局红线」段静态钉住这一条。
### 工程手法参考(tdc-rs,**只读**、不共享代码)
```
~/Desktop/workspace/tdc-rs/src/cipher.rs ← cipher 的 Rust 版逐字实现 + 坑位注释
~/Desktop/workspace/tdc-rs/src/envelope.rs ← 信封形状
~/Desktop/workspace/tdc-rs/src/db.rs ← pglite 封装 / query_json / valid_table
~/Desktop/workspace/tdc-rs/src/main.rs ← resolve_project_dir / 404 兜底 / with_state 收口
~/Desktop/workspace/tdc-rs/src/routes/mw.rs ← 405 JSON 兜底中间件
~/Desktop/workspace/tdc-rs/Cargo.toml ← release 配置
```
---
## 7. 风险与坑(开工前先知道)
| 风险 | 表现 | 处置 |
|---|---|---|
| **pglite 单实例独占数据目录** | 第二个进程起不来(`postmaster.pid` 锁) | 换数据目录/端口;集成测试串行或各用独立目录 |
| **pglite 体积** | debug 二进制 ~35 MB(内嵌 PG 引擎) | 与 tdc-rs 同量级,可接受 |
| **cipher 的 ASCII-hex key 坑** | 一旦当 16 字节摘要用 ⇒ AES-128 ⇒ 登录全挂 | 单测钉死上游向量(步骤 1) |
| **numeric 变 9.9** | 前端金额显示错、冒烟第 18 条红 | 投影层 `::text`(步骤 9) |
| **`base_role_relation` 无 `f_user_id`** | 角色授权不生效 | 建表时逐字照官方 DDL(步骤 3) |
| **npm 装 esbuild 被拦** | vite 起不来 / 端口 000 且报错不指根因 | `npm install-scripts approve esbuild` 后在 `src/frontend` 重跑 `npm install` |
| **前端端口** | macOS 上 `localhost:5173` 失败 | 用 `127.0.0.1:5173`(vite 模板固定 bind IPv4) |
| **冒烟脚本依赖 node** | 换机器跑不了 | Rust 侧 `--enc` 自证(步骤 11) |
| **权限"看起来生效"其实没测到** | 返回了数据 ≠ 权限生效(管理员短路/菜单没映射/未清缓存/异常降级放行,**四条路径全是放行**) | 必须以「**菜单收窄 + 403 拦截**」为判据 |
---
## 8. 开放问题(开工时按需裁决,不阻塞)
1. **`git` 首个 commit 何时做** —— 目录已 `git init` 但**未 commit**。建议步骤 0 结束就 commit 一次骨架。
2. ~~**Cargo workspace 还是单 crate**~~ —— ✅ **已定:workspace**。
根 `Cargo.toml` = `[workspace] members = ["src/backend"] resolver = "2"` + `[workspace.dependencies]` +
`[profile.release]`(**release profile 只在 workspace 根生效**,别写到成员里);
`src/backend/Cargo.toml` = 成员 crate(crate 名 `ssw-jnpf-lite-rust`,`src/main.rs` 在 `src/backend/src/main.rs`)。
理由:保持目录与 react 版对齐 ⇒ 抽技能时 1:1 复制。
3. **`--enc` 子命令的参数形式** —— 建议 `./ssw-jnpf-lite-rust --enc 123456`(打印 hex 到 stdout,退出码 0);
未知参数按 `--help` 处理。
4. **是否需要 `/api/health`** —— react 版没有。**建议加**(`{ok, tables, version}`),便于冒烟探活,但**不是契约**。
5. **抽技能的目标目录名** —— 建议 `ssw-jnpf-lite-rust`,落在 `~/Desktop/workspace/skills/`,
与 `ssw-jnpf-lite-react` 并列。**验收全绿后再做。**
---
## 9. 交接话术(交付态:这个仓是什么、怎么跑、怎么复现验收)
> 读 `CLAUDE.md` + `HANDOFF.md`(本文件)。**设计已定稿且已实现完毕,不要重新设计、不要重写。**
### 一句话
`ssw-jnpf-lite-rust` = **JNPF 兼容契约的 Rust 实现**(单二进制、零外部服务:Rust 2021 + axum 0.8 +
pglite-rs 0.2 进程内原生 PostgreSQL;10 张表、**32 条路由 = 面 A 27 + 面 B 5**)。
**状态:v1 + v1.1(双面后端)已完成,验收门全绿**(见 §0)。
### 怎么起
```bash
cd ~/Desktop/workspace/ssw-jnpf-lite-rust
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)
```
- 前端:**http://127.0.0.1:5173**(vite dev server,`/api` 代理到后端)
- 后端:**http://127.0.0.1:30010**(**默认只监听本机**;`BIND_ADDR=0.0.0.0` 才对外暴露)
- 账号:**`admin` / `123456`**(首次启动自动种子)
- `bash run.sh dev` 的**后端与前端都就绪**才算成功(任一没就绪 ⇒ 退出码 1 并打印对应日志尾部)
- `bash run.sh logs` 看日志(`.logs/backend.log`、`.logs/frontend.log`);`bash run.sh stop` 停(幂等)
- 🔴 `run.sh` 的 `kill_ports` 是 `kill -9` ⇒ 只清 **30010 / 5173**,**绝不碰兄弟项目 `tdc-rs` 的端口**
- 🔴 打 localhost 用 curl **必须**加 `--noproxy '*'`(本机 curl 走系统代理)
### 怎么复现验收(四门,逐字命令 + 通过标准)
| 门 | 命令 | 通过标准 |
|---|---|---|
| ① 编译 | `cargo build --release` | **0 error 0 warning** |
| ② 单测 | `cargo test` | **197 passed / 0 failed**(8 个测试目标:83+6+19+24+3+18+7+37) |
| ③ 冒烟 | `bash scripts/perm-smoke.sh`(后端先起在 `:30010`) | **PASS=32 FAIL=0**,退出码 0 |
| ③' 冒烟(面 B) | `bash scripts/perm-smoke-jnpf.sh`(后端先起在 `:30010`) | **PASS=18 FAIL=0 SKIP=0** ⇒ 面 B 覆盖 18/18 |
| ④ 前端手验 | `bash run.sh dev` ⇒ 浏览器开 `http://127.0.0.1:5173` | `admin/123456` 登录 → 菜单树正确 → 5 个管理页可增删改 → 3 个业务页可用 → 退出再登录 |
外加前置闸门:`bash scripts/check-module.sh`(9 接触点静态自检,纯静态、零 node 依赖;
期望 `PASS=57 FAIL=0`;无参 ⇒ 查全部三个业务模块)。
> 门④ 的浏览器手验清单(逐条):
> 1. `admin/123456` 登录 ⇒ Dashboard 出现「功能菜单」;
> 2. 菜单树 = 系统管理(用户管理 / 角色管理 / 机构管理 / 菜单管理)+ Demo 示例 + 产品管理 + 图书超市;
> 3. 4 个管理页(用户/角色/机构/菜单)从菜单按钮进入,页面标题正确,且**可增删改**;
> 4. 3 个业务页(DemoItem / Product / Book)可达、可增删;
> 5. 退出 ⇒ 回登录页 ⇒ 再登录 ⇒ 仍正常。
>
> ⚠️ 已知:**react 版 Dashboard 只渲染「目录的子项」**(`node.children`)⇒
> Demo 示例 / 产品管理 / 图书超市是**顶层页面型菜单**(`parentId='0'`,无子项)⇒
> **Dashboard 里没有按钮**,只能按 URL 直达(`/demo-item`、`/shop/Product`、`/books/Book`)。
> 这是**参照物原样行为**(前端逐字复制 ⇒ 本仓未改),**不是本仓的 bug**。
### 已知限制(分支级)
摘自 [`docs/known-limitations.md`](docs/known-limitations.md) 的「分支级已知限制清单」(完整版;下面是摘要):
- **(k)** release 二进制**没有** catch-all 的自动化覆盖(触发 panic 的端点是 `#[cfg(test)]` 专属;
catch-all 中间件代码在测试构建与 release 构建里**逐字相同**,且 release profile **没有**启用 abort 型 panic ⇒ 行为等价)。
- **(l)** ~~`Path<String>` 遇**畸形百分号编码** ⇒ axum 默认返**非信封的 400 响应**~~ ⇒ 🔴 **已推翻**
(最终整体评审修复轮 R=3 实测):axum 0.8.9 **接受**该转义 ——
`PUT /api/permission/Authority/Data/%zz` 实测返回 **HTTP 200 + `{"code":600,"msg":"未登录","data":null}`**
(信封,正常)⇒ **不存在**「返非信封 400」这种破口,原裁决的前提不成立 ⇒ **不改代码**。
- **(n)** 冒烟脚本**每次跑**会往库里留一行 `shop_product` + 一行 `book_shop_book` + 一行 `smoke_user`
(react 同款行为;契约 §13 未要求清理 ⇒ 不改)。
🔴 **仅在复用外部后端时**:两把尺子**默认自起隔离实例**(临时 `PGLITE_DIR`)⇒ 跑完即删、不留脏数据、
互不污染、**CI 可跑**(显式给了 `B` 才打外部库)。
- **(o)** 冒烟脚本在「重复账号 curl 超时」场景下 stderr 会多一行 `cat: … No such file`(观感,判据不受影响)。
- **(p)** 冒烟脚本在「空 body 前置失败」时 jq / python 两条路径的**前置提示文案**不同
(`code=无` vs `code=ERR`),退出码都是 2。
- **(x)** **token 的真实寿命 = 后端进程寿命**(`session.rs` 是内存 token 表、**没有 TTL**):
登录响应里的 `expiresIn: 7200` 是**契约 §6.1 逐字定死**的字面量、**不会被强制执行**
(进程不重启就永不过期);契约未覆盖 TTL ⇒ **不改**。
**面 B(官方 JNPF 契约面)这一轮的已知限制**(详见 `docs/known-limitations.md` §H 与
`JNPF_COMPAT_SURFACE.md` §8 的 B1–B10):
- **面 B 已落地但仍有 10 条偏差**:`AuthorizeDataReturnVO.list` 返空数组 · `sysConfigInfo` 返 `{}` ·
`currentSystemId` 固定为 `ssw-jnpf-lite-rust` · **无按钮/列/表单/数据级权限**(B4/B5)·
三个业务菜单的 `f_en_code` 是**自拟占位**(B8,迁官方前须换真实编码)·
`permissionList` 粒度 = 每菜单一条、`modelId` = 菜单 id(B9)· `Organize/AsyncList` 未分页(B10)。
- **口令存储缺官方 `secretkey` 一步**:本仓存 `md5(明文)`,官方存 `md5(lower(md5(明文)) + lower(secretkey))`
⇒ 迁官方时**一次性换算**即可,**不需要明文**(`MIGRATION.md` §7)。
- **两套权限判据并存**(不是 bug):面 A 按菜单路径 `f_url_address`,面 B 按点权限 `f_en_code`
⇒ **同一用户可能面 A 通、面 B 拒**;种子菜单已补 8 条 `f_en_code`(存量库启动时**只补 NULL**,不覆盖已改值)。
Task 12 修复轮 R=1 另记两条 `run.sh` 的**行为口径**(不是缺陷,是刻意设计):
- `run.sh backend` 用 `exec` 跑后端 ⇒ **后端自己的退出码原样透传**(后端 panic 时是 **101**,不是子命令表里写的 1)。
- `run.sh stop` 的**实际停止路径 = PID 文件(SIGTERM → 1s → SIGKILL)+ `kill_ports`(按端口 `kill -9`)**;
`pkill` 只是最后一道兜底,且模式**收窄到后端本体的完整路径**
(macOS/BSD 的 `pkill -f` 匹配**完整命令行**,宽模式会连「命令行里提到本仓名字」的无关进程一起杀掉);
vite 由 `kill_ports 5173` 按**端口**收,不会误杀别的项目的 vite dev server。
本任务(Task 12)另记四条**已观察、未改**的观察(留给最终整体评审裁决):
- **react 版 Dashboard 只渲染「目录的子项」** ⇒ 3 个顶层业务页在菜单里**没有入口按钮**(只能按 URL 直达:
`/demo-item`、`/shop/Product`、`/books/Book`)。前端是**逐字复制** ⇒ 改它会破「除代理端口外一字不改」的
硬约束 ⇒ **不改**,只记档。(与契约 §8.4 的菜单表一致:`m_demo`/`m_product`/`m_book` 的 `parent_id='0'`。)
- `src/frontend/vite.config.ts` 的注释仍写着「转发到 **NestJS** 后端(30010)」——
本仓后端是 **Rust**。该注释行属于「代理目标行 + 紧邻注释行」两行允许改动范围,
但 brief 只授权把端口改成 `30010` ⇒ 框架名**逐字保留**,**不「顺手修好」**(最终评审按 Minor 记)。
- `src/api/request.ts:5` 的**陈旧端口注释**(写的仍是旧端口号)与 `:31` 的 axios **30 秒超时**
(`timeout` 毫秒数,**不是**端口)⇒ **逐字保留**(改了就破「除代理外一字不改」的 diff 门)。
- `/favicon.ico` 在 vite dev server 上返 **404**(`index.html` 没有 favicon 引用)⇒ 浏览器 console 会有两条 404。
无害,且 `index.html` 是逐字复制 ⇒ **不改**,只记档。
### 下一步(按 plan)
**已完成**:验收门全绿;**本仓本体就是技能 `ssw-jnpf-lite-rust`**(2026-10-26 第三段重排,见
`.workbuddy/memory/2026-10-26.md`)——**仓根 = 技能根**:`SKILL.md` 与 `src/` `scripts/` `run.sh`
`Cargo.toml` `references/` `template-boot-jnpf/` 同仓(不再有「仓外技能副本」⇒ 不漂移、进 git)。
`~/.agents/skills/ssw-jnpf-lite-rust` → **仓根**(绝对软链);
`~/.claude/skills/`、`~/.workbuddy/skills/`、`~/.qwenworkcn/skills/` 三处各放**相对**软链
`../../.agents/skills/ssw-jnpf-lite-rust`,已逐一验证能读到 `SKILL.md`。
技能比 react 版多三份资产:**面 B 规格**(`JNPF_COMPAT_SURFACE.md`)· **官方源码核对**(`JNPF_SOURCE_AUDIT.md`)·
**迁移指南**(`MIGRATION.md`),并自带**第二把尺子** `scripts/perm-smoke-jnpf.sh`。
**面 B 已落地(2026-10-26)** —— S1–S6 全部完成,对照表见 `JNPF_COMPAT_SURFACE.md` §7:
| 步 | 内容 | 落点 | 状态 |
|---|---|---|---|
| S1 | 判别头分流(`Vue-Version: 3` ⇒ 面 B)+ 第二套守卫(`f_en_code` 判据) | `jnpf.rs` / `permission.rs` / `routes.rs` | ✅ |
| S2 | 官方形状的 `CurrentUser`(`PcUserVO` 五字段) | `jnpf.rs` / `auth.rs` | ✅ |
| S3 | 分页信封(`{pagination:{currentPage,pageSize,total}, list:[…]}`) | `jnpf.rs` | ✅ |
| S4 | 码表补齐(`401` / `500` / `601` / **`602`**——官方前端只在 `601`/`602` 清 token) | `envelope.rs` | ✅ |
| S5 | 官方 RESTful 路径(`/api/permission/Users` / `Role` / `Organize` / `Authority` / `/api/system/Menu`) | `routes.rs` | ✅ |
| S6 | `f_en_code` 种子(8 条,存量库**只补 NULL**) | `seed.rs` | ✅ |
⇒ `bash scripts/perm-smoke-jnpf.sh` 已从 **`覆盖 5/18`** 走到 **18/18**;
面 A **零改动** ⇒ `perm-smoke.sh` 仍是 `PASS=32 FAIL=0`。
**下一步(候选,需人拍板才动代码)**:
1. **补齐面 B 的 B1–B10 偏差**(按价值排序):
B4/B5 按钮级 + 数据级权限(官方 `base_module_button` / `_data`)· B1 授权读 `list` 真返回 ·
B2 `sysConfigInfo` 真配置 · B6 导入导出 · B7 `secretkey` 换算链。
2. **把官方 JNPF 前端真接进来**(目前是「后端已就位,官方前端未实测」)——
验证 `Vue-Version: 3` 分流在真实官方 axios 拦截器下无歧义。
3. **反向验证路径**:拿 react 版后端/官方 JNPF 版的数据灌进本仓,跑两把**契约**尺子,
证明「迁移期数据可比对」(这是本仓作为**转换/验证框架**的核心价值,目前只验了正向)。