- 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)。
641 lines
49 KiB
Markdown
641 lines
49 KiB
Markdown
# 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 版的数据灌进本仓,跑两把**契约**尺子,
|
||
证明「迁移期数据可比对」(这是本仓作为**转换/验证框架**的核心价值,目前只验了正向)。
|