refactor(skill): 仓根即技能本体 —— 技能资产进版本控制 + 三处软链指向同一仓

影响:此前技能资产(SKILL.md / HOWTO_MODULE.md / PERMISSION.md / MIGRATION.md /
JNPF_SOURCE_AUDIT.md / JNPF_COMPAT_SURFACE.md / references/ / template-boot-jnpf/)
实体住在 ~/.agents/skills/ssw-jnpf-lite-rust/(仓外、不在 git)⇒ 改仓不生效、实体与仓漂移。
现在仓根 = 技能根(对齐 ssw-jnpf-lite-react 的形态),~/.agents · ~/.claude · ~/.workbuddy
(+ ~/.qwenworkcn)四处软链全部解析到同一个仓 ⇒ 改一次仓 = 改一次技能。

改动:
- 新增根级技能文档 6 份:SKILL.md(并补 frontmatter:name/description/type,原文件没有 frontmatter
  只靠目录名兜底)/ HOWTO_MODULE.md / PERMISSION.md / MIGRATION.md / JNPF_SOURCE_AUDIT.md /
  JNPF_COMPAT_SURFACE.md;references/ 与 template-boot-jnpf/ 一并入仓
- 根 README.md 改为技能版(选型/运行/验收门/已知限制),旧项目版 README 移入 docs/README-project.md
- docs/ 下 3 份与根级同源的文档删除(技能版取代),全仓链接改指根级(已修全部相对链接,无坏链)
- docs/ 保留契约真源 contract.md / runbook.md / decisions.md / known-limitations.md / ddl/
- Cargo.toml 取「技能版注释 + 仓版补充」合并;run.sh 用仓版(多旧名兜底 pkill)
- SKILL.md 补 frontmatter + 「技能目录 = 仓根」说明;CLAUDE.md 目录速览同步;HANDOFF.md 技能资产
  描述同步;工作日志补第三段

验证:cargo build --release 0 error · cargo test 195 passed/0 failed · check-module.sh PASS=57
FAIL=0 · 面 A 尺子 PASS=32 FAIL=0 · 面 B 尺子 PASS=18 FAIL=0 SKIP=0(覆盖 18/18)

Co-Authored-By: Claude <[email protected]>
This commit is contained in:
adminandClaude committed 2026-10-26 16:56:58 +08:00
1 parent 8b24bb1aea
commit 7c4ae39664
37 files changed
+2422 -131

No files matched your search

+34 -5
View File
@@ -2,9 +2,9 @@
## 本轮做了什么
- **官方 JNPF 对齐三件套**(新增):`docs/JNPF_SOURCE_AUDIT.md`(官方源码逐行核对,标 `文件:行号`)·
`docs/JNPF_COMPAT_SURFACE.md`(**面 B 规格**:官方形状的端点/响应/码表 + 落地顺序 S1–S6)·
`docs/MIGRATION.md`(本仓 ↔ 官方逐项映射 + 口令 `secretkey` 换算)。
- **官方 JNPF 对齐三件套**(新增):`JNPF_SOURCE_AUDIT.md`(官方源码逐行核对,标 `文件:行号`)·
`JNPF_COMPAT_SURFACE.md`(**面 B 规格**:官方形状的端点/响应/码表 + 落地顺序 S1–S6)·
`MIGRATION.md`(本仓 ↔ 官方逐项映射 + 口令 `secretkey` 换算)。
- **第二把尺子**(新增):`scripts/perm-smoke-jnpf.sh`(18 条官方形状断言,打判别头;未落地记 **SKIP**,**不计入 PASS**)。
当时实测 `PASS=5 FAIL=0 SKIP=13`(覆盖 5/18)⇒ 官方 JNPF 前端**还跑不进本仓**。
(🔴 **本段结论已被当天第二段作废** —— 面 B 已落地,尺子现为 `PASS=18 FAIL=0 SKIP=0`。)
@@ -36,7 +36,7 @@
## 下一步(需人拍板才动代码)—— ✅ **当天第二段已完成,见下**
**落地面 B**(`docs/JNPF_COMPAT_SURFACE.md` §7 的 S1–S6):判别头分流 + `f_en_code` 第二套守卫 → `PcUserVO` →
**落地面 B**(`JNPF_COMPAT_SURFACE.md` §7 的 S1–S6):判别头分流 + `f_en_code` 第二套守卫 → `PcUserVO` →
分页信封 → 码表补 `602`(官方前端只在 `601`/`602` 清 token)→ 官方 RESTful 路径 → `f_en_code` 种子 + `secretkey` 换算。
**面 A 必须零改动**(`perm-smoke.sh` 保持 `PASS=32`)。
@@ -97,9 +97,38 @@
`CLAUDE.md`(交付形态加 v1.1 双面 / 红线 10-11 / 端点全表拆两面 / 目录速览加 `jnpf.rs`)·
`README.md`(双面定位 / 验收门加 ③' / 已知限制改写)· `HANDOFF.md`(§0 状态 / §3.3 模块表 / §4 验收门 / §6 参考文件 / §9 已知限制 + 下一步)·
`docs/JNPF_COMPAT_SURFACE.md`(§7 落地对照 + §8 B8–B10 + §9 变更行)· `docs/known-limitations.md`(§H 改写)。
`JNPF_COMPAT_SURFACE.md`(§7 落地对照 + §8 B8–B10 + §9 变更行)· `docs/known-limitations.md`(§H 改写)。
## 下一步(候选,需人拍板)
补 B1–B10 偏差(优先 B4/B5 按钮级+数据级权限)· 接官方 JNPF 前端实测分流 ·
**反向验证**(官方/React 版数据灌进本仓跑两把尺子 —— 这是「转换/验证框架」的核心价值,目前只验了正向)。
## 第三段:仓根 = 技能根(按 `ssw-jnpf-lite-react` 的形态重排)
**动机**:原先技能资产(`SKILL.md` / `HOWTO_MODULE.md` / `PERMISSION.md` / `MIGRATION.md` /
`JNPF_SOURCE_AUDIT.md` / `JNPF_COMPAT_SURFACE.md` / `references/` / `template-boot-jnpf/`)
住在 `~/.agents/skills/ssw-jnpf-lite-rust/`(**仓外**)⇒ 不在 git 里、改一处漂两处;
`ssw-jnpf-lite-react` 则是**技能本体就在仓根**(`SKILL.md` 与 `src/` 同仓)⇒ 本仓照它对齐。
**结果**:
- 仓根变成技能根:`SKILL.md` + `README.md` + `HOWTO_MODULE.md` + `PERMISSION.md` + `MIGRATION.md`
+ `JNPF_SOURCE_AUDIT.md` + `JNPF_COMPAT_SURFACE.md` + `references/` + `template-boot-jnpf/`
与 `src/` `scripts/` `run.sh` `Cargo.toml` 同仓 ⇒ **改一次仓 = 改一次技能**。
- 三处软链统一指向**同一个仓**:
`~/.agents/skills/ssw-jnpf-lite-rust` → 仓根(绝对);
`~/.claude/skills/` 与 `~/.workbuddy/skills/` → `../../.agents/skills/ssw-jnpf-lite-rust`(相对,符合 triagent-sync 约定)。
旧的实体技能目录已**移入回收站**(`~/.Trash/ssw-jnpf-lite-rust-skillcopy-<ts>`),未 `rm`。
- 根级技能版 `MIGRATION.md` / `JNPF_COMPAT_SURFACE.md` / `JNPF_SOURCE_AUDIT.md` **取代**了 `docs/` 下的同名单文件
(内容同源,技能版按「技能根」措辞与链接改写)⇒ `docs/` 三份删除,全仓引用改指根级。
`docs/` 保留:`contract.md`(契约真源)· `runbook.md` · `decisions.md` · `known-limitations.md` · `ddl/` · `README-project.md`(旧项目版 README)。
- `SKILL.md` **补 frontmatter**(`name` / `description` / `type: skill`,对齐 react 技能)——
原文件**没有 frontmatter**,靠目录名兜底才能被识别为技能。
- `Cargo.toml` 取「agents 版注释 + 仓版两条补充」合并;`run.sh` 用仓版(agents 版是其子集,少旧名兜底 `pkill`)。
**验证**(重构后全跑过):`cargo build --release` 0 error · `cargo test` **195 passed / 0 failed** ·
`check-module.sh` PASS=57 FAIL=0 · 面 A 尺子 `PASS=32 FAIL=0` · 面 B 尺子 `PASS=18 FAIL=0 SKIP=0`(覆盖 18/18)。
**踩坑**:`~/.Trash` 在沙箱里 `ls` 不通(Operation not permitted),但 `mv` 进回收站**是成功的**——
判断是否进回收站要看源路径是否已消失,不要靠 `ls ~/.Trash`。
+12 -6
View File
@@ -59,20 +59,26 @@ Rust 版 ⇒ 可机械翻译回官方 JNPF;JNPF / React 版 ⇒ 可打到本
## 目录速览(当前形态)
```
ssw-jnpf-lite-rust/
ssw-jnpf-lite-rust/ # 【仓根 = 技能根】三处软链 ~/.agents · ~/.claude · ~/.workbuddy 都指向这里
├── SKILL.md # 【技能入口】是什么 / 何时用 / 契约红线 / 两把尺子
├── README.md # 选型 / 运行 / 验收门 / 已知限制
├── HOWTO_MODULE.md # 加一个业务模块的操作手册(9 个接触点)
├── PERMISSION.md # 权限模版:表结构 / 四源合并 / 码表
├── MIGRATION.md # 迁移指南(Rust ⇄ NestJS ⇄ 官方 JNPF Java)+ 数据 ETL + 口令换算
├── JNPF_SOURCE_AUDIT.md # 官方源码逐行核对报告(每条带 文件:行号)
├── JNPF_COMPAT_SURFACE.md # 面 B(官方 JNPF 契约面)规格书 + 落地顺序 S1–S6
├── Cargo.toml # 【workspace 根】members = ["src/backend"];release profile 写在这里
├── CLAUDE.md / HANDOFF.md # 本文件 / 交接文档
├── README.md # 项目定位 / 启动方式 / 验收门
├── run.sh # install / build / dev / backend / frontend / stop / logs
├── .env.example # PORT / PGLITE_DIR(后者只能写绝对路径或 memory://)
├── references/ # BaseCrudController.java(**非** JNPF 官方类)+ README
├── template-boot-jnpf/ # JNPF 标准栈最小可运行骨架(Java)
├── docs/
│ ├── contract.md # 【契约唯一真源】端点 / 返回形状 / 数据模型
│ ├── runbook.md # 怎么起 / 怎么冒烟 / 常见故障
│ ├── decisions.md # 实施期逐条裁决(88 条「什么—为什么—代价」)
│ ├── known-limitations.md # 分支级已知限制(被接受/挂起的东西)
│ ├── JNPF_SOURCE_AUDIT.md # 官方源码逐行核对报告(每条带 文件:行号)
│ ├── JNPF_COMPAT_SURFACE.md # 面 B(官方 JNPF 契约面)规格书 + 落地顺序 S1–S6
│ ├── MIGRATION.md # 迁移指南(Rust ⇄ NestJS ⇄ 官方 JNPF Java)+ 数据 ETL + 口令换算
│ ├── README-project.md # 项目定位 / 启动方式 / 验收门(历史版 README)
│ └── ddl/ # 官方 DDL 摘录
├── src/
│ ├── backend/ # Rust 后端(workspace 唯一成员,crate 名 ssw-jnpf-lite-rust)
@@ -245,7 +251,7 @@ ssw-jnpf-lite-rust/
### 面 B(5 条,官方 JNPF 形状)
🔴 全部在 `src/backend/src/jnpf.rs` 实现;规格见 `docs/JNPF_COMPAT_SURFACE.md`。
🔴 全部在 `src/backend/src/jnpf.rs` 实现;规格见 `JNPF_COMPAT_SURFACE.md`。
🔴 **未登录一律 `code=602`**(官方前端只对 `601`/`602` 清 token ⇒ 返 `600` 会卡住不跳登录)。
| 方法 | 路径 | 守卫(按 `f_en_code` 点权限) | 说明 |
+9 -1
View File
@@ -1,5 +1,13 @@
# ssw-jnpf-lite-rust —— cargo workspace 根
#
# 🔴 **本文件是脚手架的一部分,复制到项目根时必须一起带上**
#
# 为什么必须有它:`src/backend/Cargo.toml` 里的
# `version.workspace = true` / `edition.workspace = true` / `xxx = { workspace = true }`
# 都要求**上层有一个 workspace 根**。缺了它,cargo 直接报
# `error: could not find Cargo.toml in ... or any parent directory`,
# 脚手架**根本编译不起来**。
#
# 这里只放「跨成员共享」的配置:成员列表、依赖版本、release profile。
# 成员 crate(src/backend)不得再写 [profile.*],否则 cargo 直接报错。
@@ -40,7 +48,7 @@ chrono = "0.4"
opt-level = 2
lto = "thin"
strip = "symbols"
# 🔴 不要设 `panic = "abort"`:规格 §6.5 要求 panic ⇒ HTTP 200 + code=400,
# 🔴 不要设 `panic = "abort"`:契约 §6.5 要求 panic ⇒ HTTP 200 + code=400,
# 而 abort 下 `catch_unwind` 抓不到 panic(进程直接死 ⇒ 客户端连接重置)。
# catch-all 中间件依赖默认的 `panic = "unwind"`(Ruling P19)。
codegen-units = 16
+13 -11
View File
@@ -20,8 +20,8 @@
| 脚本 | ✅ `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` |
| 官方对齐文档 | ✅ `docs/JNPF_SOURCE_AUDIT.md`(官方源码逐行核对)· `docs/JNPF_COMPAT_SURFACE.md`(**面 B 规格 + 落地状态**)· `docs/MIGRATION.md`(迁移指南) |
| 技能资产 | ✅ `ssw-jnpf-lite-rust` 已落 `~/.agents/skills/ssw-jnpf-lite-rust/`(真相源;`~/.claude/skills` / `~/.workbuddy/skills` / `~/.qwenworkcn/skills` 三处相对软链已验证可读 `SKILL.md`) |
| 官方对齐文档 | ✅ `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** · 单测 **195 passed / 0 failed** · 面 A 冒烟 **PASS=32 FAIL=0** · 面 B 冒烟 **PASS=18 FAIL=0 SKIP=0** · 前端**浏览器**手验全过) |
**读法**:`CLAUDE.md`(红线与坑位,日常改代码必读)→ §9(怎么起 / 怎么复现验收)。
@@ -332,9 +332,9 @@ ssw-jnpf-lite-rust/ ← 独立 git 仓(已 init,未 com
| 文件 | 何时读 | 内容 |
|---|---|---|
| `docs/JNPF_SOURCE_AUDIT.md` | 迁移期 / 存疑时 | 官方源码(Java + Vue)逐行核对报告,全部结论标 `文件:行号`;含本仓与官方的**差异清单 D1–D8** |
| `docs/JNPF_COMPAT_SURFACE.md` | 改面 B 时 | **面 B 规格**:官方形状的端点 / 响应形状 / 码表 / 判别头 / 落地顺序 S1–S6(**已全部落地**)+ §8 已知偏差 B1–B10 |
| `docs/MIGRATION.md` | 稳定期迁 JNPF | 本仓 ↔ 官方的**逐项映射** + 数据 ETL + 口令 `secretkey` 换算(**不需要明文**) |
| `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/jnpf.rs` | 改面 B 时 | 面 B 全部实现(判别头 / VO 构造 / 点权限守卫 / `602` 码) |
@@ -458,14 +458,14 @@ bash run.sh dev # 日常:后台起后端(30010) + 前端(5173)
(进程不重启就永不过期);契约未覆盖 TTL ⇒ **不改**。
**面 B(官方 JNPF 契约面)这一轮的已知限制**(详见 `docs/known-limitations.md` §H 与
`docs/JNPF_COMPAT_SURFACE.md` §8 的 B1–B10):
`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))`
⇒ 迁官方时**一次性换算**即可,**不需要明文**(`docs/MIGRATION.md` §7)。
⇒ 迁官方时**一次性换算**即可,**不需要明文**(`MIGRATION.md` §7)。
- **两套权限判据并存**(不是 bug):面 A 按菜单路径 `f_url_address`,面 B 按点权限 `f_en_code`
⇒ **同一用户可能面 A 通、面 B 拒**;种子菜单已补 8 条 `f_en_code`(存量库启动时**只补 NULL**,不覆盖已改值)。
@@ -492,14 +492,16 @@ Task 12 修复轮 R=1 另记两条 `run.sh` 的**行为口径**(不是缺陷
### 下一步(按 plan)
**已完成**:验收门全绿;本仓 1:1 复制成技能 `ssw-jnpf-lite-rust` ⇒ 落在
**`~/.agents/skills/ssw-jnpf-lite-rust/`**(按全局硬约定,**技能唯一真相源 = `~/.agents/skills/`**;
**已完成**:验收门全绿;**本仓本体就是技能 `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`)。
`../../.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 全部完成,对照表见 `docs/JNPF_COMPAT_SURFACE.md` §7:
**面 B 已落地(2026-10-26)** —— S1–S6 全部完成,对照表见 `JNPF_COMPAT_SURFACE.md` §7:
| 步 | 内容 | 落点 | 状态 |
|---|---|---|---|
+298
View File
@@ -0,0 +1,298 @@
# 加一个业务模块(AI 开发主线)
本文件是 **Rust 版**的操作手册。参照实现 = 内置的三个模块
(`demo/DemoItem` · `shop/Product` · `books/Book`)——**照抄一个最接近的,别从零想**。
> 契约红线见 [`SKILL.md`](SKILL.md) §「契约红线」。**本文件只讲「改哪儿、怎么验证」。**
## 〇.5、一图看完全流程(先看一遍再动)
```
1. db/schema.sql 建表(f_ 前缀 + f_id VARCHAR(50) + 软删列)
2. src/entities.rs 加 spec(列清单 + json_key + numeric 标记 + module_key)
3. src/crud.rs 加 3 个 handler(List/Save/Delete)—— 复用 handle_list/handle_save/handle_delete
4. src/routes.rs 注册 3 条路径
5. src/seed.rs 加内置菜单(id + url_address = Route path)
6. frontend/src/api/<lc>.ts 3 个函数(list/save/delete)
7. frontend/src/views/<Ent>.tsx 列表页
8. frontend/src/App.tsx <Route path="/<route>">
9. scripts/check-module.sh 期望表加一行(appCode:Entity)
⇒ bash scripts/check-module.sh <appCode> <Entity> 必须全 ✅
10. scripts/perm-smoke.sh 追加该模块的断言(别新写脚本)
```
**9 个接触点 = 上面的 1–9**。第 9 步漏了 ⇒ `check-module.sh` 直接判「未知 app_code/Entity」退出 2。
## 〇、命名约定(先想清楚再动)
| 位置 | 约定 | 例(`books` / `Book`) |
|---|---|---|
| `app_code` | 小写业务名,**同时是 URL 段** | `books` |
| `entity` | 大驼峰,**同时是 URL 段** | `Book` |
| 表名 | 蛇形,**官方没有对应表** ⇒ 自己起(推荐 `{app}_{entity 小写}`) | `book_shop_book` |
| 前端 api 文件 | entity 小写 | `src/api/book.ts` |
| 前端 view 文件 | entity 大驼峰 | `src/views/Book.tsx` |
| Route path | **= 菜单 `url_address`**(去前导斜杠) | `books/Book` |
| 菜单种子 id | `m_` + entity 小写 | `m_book` |
| 列表函数名 | `list` + 复数(复数规则见 `check-module.sh` 的 `plural()`) | `listBooks` |
| 单条函数名 | `save` / `delete` + entity | `saveBook` / `deleteBook` |
🔴 **表名不与官方对齐是刻意的**(官方没有低代码业务表)——但**两版后端(react 版 / rust 版)之间要同名**,
才能开同一个库。`demo_item` / `shop_product` / `book_shop_book` 就是这么定的。
## 一、要碰的 9 个接触点
| # | 文件 | 改什么 | 漏了会怎样 |
|---|---|---|---|
| 1 | `src/backend/db/schema.sql` | `CREATE TABLE {table}` | 端点 500(表不存在) |
| 2 | `src/backend/src/entities.rs` | 加 `EntitySpec`(含列清单) | 端点 404(没注册) |
| 3 | `src/backend/src/crud.rs` | 加 3 个 handler | 端点 404 |
| 4 | `src/backend/src/routes.rs` | 注册 3 条路径 | 端点 404 |
| 5 | `src/backend/src/seed.rs` | 加内置菜单 | **菜单不显示**(前端侧栏空) |
| 6 | `src/frontend/src/api/<lc>.ts` | 3 个函数 | 页面发请求 404 |
| 7 | `src/frontend/src/views/<Ent>.tsx` | 列表页 | 页面空白 |
| 8 | `src/frontend/src/App.tsx` | `<Route path="/<route>">` | **页面 404** |
| 9 | `scripts/check-module.sh` | 期望表加一行 | 自检退出码 2(闸门形同虚设) |
**外加一条一致性(不是第 10 个文件)**:
`spec.module_key` == `seed.url_address` == `App.tsx` 的 Route path —— **三处一字不差**。
不一致的后果是**静默放行**(未映射到菜单就放行,不报错)。
## 二、后端五处改什么
### 2.1 `db/schema.sql` —— 建表
照抄 `book_shop_book` 的形状:
```sql
CREATE TABLE {table} (
f_id VARCHAR(50) NOT NULL,
f_title VARCHAR(200),
f_price NUMERIC(12,2),
f_stock INT,
f_creator_user_id VARCHAR(50),
f_creator_time TIMESTAMP,
f_delete_mark INT DEFAULT 0,
CONSTRAINT pk_{table} PRIMARY KEY (f_id)
);
```
红线:
- 列名**全部 `f_` 前缀**;主键 `f_id VARCHAR(50)`(**不是 32**——36 位 UUID 装不下)。
- 软删列 `f_delete_mark INT DEFAULT 0`(**不是**物理 DELETE)。
- 🔴 **numeric 列(金额)** ⇒ spec 里要标 `numeric: true`(投影 `::text` ⇒ JSON 字符串 `"9.90"`)。
- 🔴 **改了 schema.sql 不生效**:schema 只在**首次**建表时执行 ⇒ 改完要**清空 `data/` 重建**。
### 2.2 `src/entities.rs` —— 加 spec
```rust
const SHOE_COLUMNS: &[ColumnSpec] = &[
ColumnSpec { column: "f_id", json_key: "id", default: None, numeric: false },
ColumnSpec { column: "f_title", json_key: "title", default: None, numeric: false },
ColumnSpec { column: "f_price", json_key: "price", default: Some("0.00"), numeric: true },
ColumnSpec { column: "f_creator_user_id", json_key: "creatorUserId", default: None, numeric: false },
ColumnSpec { column: "f_creator_time", json_key: "creatorTime", default: None, numeric: false },
ColumnSpec { column: "f_delete_mark", json_key: "deleteMark", default: Some("0"), numeric: false },
];
pub const SHOE_SPEC: EntitySpec = EntitySpec {
app_code: "shoes",
entity: "Shoe",
table: "shoe_item",
module_key: Some("shoes/Shoe"), // 🔴 None ⇒ 仅登录(demo 就是 None)
columns: SHOE_COLUMNS,
numeric_columns: &["f_price"], // 🔴 必须与每列的 numeric 标记一致(有单测钉)
};
```
再把 `SHOE_SPEC` 加进 `ALL_SPECS`(否则 `find_spec` 找不到)。
🔴 **`json_key` 必须等于 `db::column_to_json_key(column)`**(`f_title` ⇒ `title`)—— 有单测钉死,不一致会红。
🔴 **列顺序 = 响应 JSON 的键序**(照抄参照模块,别自作主张排序)。
🔴 **`default` 只在「路径 1(无 id 的新建)」生效**——带 id 但库里没这行时,**一个默认值都不加**。
### 2.3 `src/crud.rs` —— 加 3 个 handler
**不要重写业务逻辑**——`handle_list` / `handle_save` / `handle_delete` 已经把
守卫、SQL 拼装、投影、软删、序列化全包了:
```rust
// ---------------------------------------------------------------- shoes(菜单 shoes/Shoe)
/// `GET /api/ssw/shoes/Shoe/List`。
pub async fn shoe_list(State(state): State<AppState>, headers: HeaderMap) -> Json<ActionResult> {
let spec = shoe_spec();
handle_list(&state, &headers, spec).await
}
/// `POST /api/ssw/shoes/Shoe/Save`。
pub async fn shoe_save(
State(state): State<AppState>,
headers: HeaderMap,
body: Bytes,
) -> Json<ActionResult> {
let spec = shoe_spec();
handle_save(&state, &headers, spec, &body).await
}
/// `DELETE /api/ssw/shoes/Shoe/Delete?id=`。
pub async fn shoe_delete(
State(state): State<AppState>,
headers: HeaderMap,
raw: RawQuery,
) -> Json<ActionResult> {
let spec = shoe_spec();
handle_delete(&state, &headers, spec, &raw).await
}
fn shoe_spec() -> &'static EntitySpec {
&crate::entities::SHOE_SPEC
}
```
🔴 **签名不要改**:`Save` 收 `body: Bytes`(自己解析,不走 `Json<T>`),
`Delete` 收 `raw: RawQuery`(`?id=`)—— `handle_save` / `handle_delete` 依赖这个形状。
### 2.4 `src/routes.rs` —— 注册路径
```rust
.route("/api/ssw/shoes/Shoe/List", get(crud::shoe_list))
.route("/api/ssw/shoes/Shoe/Save", post(crud::shoe_save))
.route("/api/ssw/shoes/Shoe/Delete", delete(crud::shoe_delete))
```
🔴 **axum 0.8 逐条注册**(matchit 不支持 `{a,b}`)⇒ 三个动作三条 `.route()`。
🔴 `with_state(state)` 必须是**链条最后一步**。
🔴 **路由表有钉子测试**(`routes.rs` 的 `route_table_is_pinned`,照抄**面 A 27 条**;
面 B 另有 `jnpf_route_table_is_pinned`,照抄**面 B 5 条**)⇒ **加完路径要同步改那张表**。
🔴 **面 B 已落地**(`src/backend/src/jnpf.rs`):新业务模块若要让**官方 JNPF 前端**也能用,
需另在面 B 补对应官方形状端点(分页信封 `PageListVO` + `f_en_code` 点权限)。
### 2.5 `src/seed.rs` —— 加内置菜单
在 `BUILTIN_MENUS` 常量里加一条:
```rust
BuiltinMenu {
id: "m_shoe",
full_name: "鞋",
url_address: "shoes/Shoe", // 🔴 必须 == Route path == spec.module_key
parent_id: "0",
menu_type: "2", // 1 = 目录,2 = 页面(官方 f_type 是 INTEGER)
icon: None,
sort_code: "…",
},
```
🔴 **种子是「幂等 ensure」**:启动时按 `f_url_address` **或** `f_id` 判存在 ⇒
**改了 `url_address` 必须重启回灌**;软删行**不复活**、不覆盖已改值。
🔴 **改了种子要重启进程**才会回灌存量库,**不必删库重建**。
🔴 **种子 INSERT 不写 `f_en_code`**(官方点权限靠它)⇒ 迁官方前要补(见 `MIGRATION.md` §2.4)。
## 三、前端三文件改什么
### 3.1 `src/api/<lc>.ts` —— 3 个函数
```ts
import request from './request';
export const listShoes = () => request.get('/ssw/shoes/Shoe/List');
export const saveShoe = (dto: any) => request.post('/ssw/shoes/Shoe/Save', dto);
export const deleteShoe = (id: string) => request.delete(`/ssw/shoes/Shoe/Delete?id=${id}`);
```
🔴 `request.ts` 的 `baseURL` 是 `/api` ⇒ 这里**不要**再写 `/api` 前缀。
🔴 **函数名规则**:`list` + 复数(`plural()`:`s/x/ch/sh` → `+es`;辅音 + `y` → `ies`;否则 `+s`),
`save`/`delete` + entity。`check-module.sh` 按这个规则查。
### 3.2 `src/views/<Ent>.tsx` —— 列表页
照抄 `views/Book.tsx`(含 numeric 往返、删除确认、错误提示)。
🔴 **金额展示别用 `Number()` 转**——后端给的是字符串 `"9.90"`,转数字会丢尾零。
### 3.3 `src/App.tsx` —— 注册路由
```tsx
import Shoe from './views/Shoe';
…
<Route path="/shoes/Shoe" element={<RequireAuth><Shoe /></RequireAuth>} />
```
🔴 **Route path 必须 == 菜单 `url_address`**(去前导斜杠)—— 不一致 ⇒ 侧栏点了 404。
🔴 JSX 常写成多行(`<Route\n path=…>`)⇒ `check-module.sh` 用 `tr '\n' ' '` 去换行再匹配。
## 四、菜单 + 授权
- **菜单**:`seed.rs` 加一条(见 2.5)。前端侧栏由**后端返回的菜单树**驱动 ⇒ 不用改前端导航。
- **授权**:**默认不授权 ⇒ 非管理员看不到、访问 403**(这是对的)。
要让某个角色看到 ⇒ 写 `base_authorize`
(`f_object_type='role'` + `f_object_id=<roleId>` + `f_item_type='module'` + `f_item_id=<menuId>`)。
走 `PUT /api/permission/Authority/Data/{objectId}`(`objectType` **小写** `'role'`,
`module` 传**一维数组**)。
- **admin 角色**:`seed.rs` 的 `ensure_admin_authorizations` 会**自动**补内置菜单的授权 ⇒
管理员开箱即用,普通角色要手动授权。
## 五、验证(追加断言,别新写脚本)
### 5.1 静态自检(改完立刻跑,**先于** perm-smoke)
```bash
bash scripts/check-module.sh shoes Shoe # 单模块
bash scripts/check-module.sh # 全部三个 + 全局红线
```
🔴 **先改 `scripts/check-module.sh` 的期望表**(§一 第 9 步)——
`case "${A}:${E}"` 分支里补 `shoes:Shoe` 的表名 / ROUTE / 种子 id / module_key / 有无 api 文件。
### 5.2 端到端(`scripts/perm-smoke.sh` 追加断言)
**必选 4 条**(每个业务模块都有):
1. `GET /api/ssw/{app}/{Ent}/List` 无 token ⇒ `code=600`
2. 无 token ⇒ `code=600`(同上一条,测的是**端点在、守卫在**)
3. 非管理员未授权 ⇒ `code=403`
4. 管理员新建一条 ⇒ `code=200` + 回读列表里能看到(长度 +1)
**每个业务字段加一条往返断言**(防 numeric/text/int 转换 bug):
```bash
# numeric ⇒ JSON 字符串(带尾零);int ⇒ JSON 数字
# 例:Shoe 的 f_price 回显必须等于 "9.90"(字符串),f_stock 必须等于 100(数字)
```
🔴 **判据要比原始 JSON 文本**——字符串 `"9.90"` 与数字 `9.9` 在 jq 里都能取到,
只有比**原始文本**才分得出来。
🔴 **别用 `--data-urlencode` 配 `-G`**(curl 里两个互斥)——body 用 `-d`,query 用 `-G`。
🔴 本机 curl 走系统代理 ⇒ **测 localhost 必须 `--noproxy '*'`**。
### 5.3 三件套全绿才算完
```bash
cargo test # 195 条
bash scripts/check-module.sh # 静态自检
bash scripts/perm-smoke.sh # 面 A 32 条
bash scripts/perm-smoke-jnpf.sh # 面 B 18 条(面 A 不受影响时也应保持 18/18)
```
## 六、写之前的自查(5 条)
1. **列名全 `f_` 前缀?** `f_id` 是 `VARCHAR(50)` 不是 `VARCHAR(32)`?
2. **`json_key` = 列名去 `f_` 后 camelCase?**(`f_creator_user_id` ⇒ `creatorUserId`)
3. **numeric 列标了 `numeric: true`?** `numeric_columns` 数组同步更新?
4. **`module_key` == `seed.url_address` == `App.tsx` 的 Route path?**(三处一字不差)
5. **改了 `schema.sql` 之后清空 `data/` 重建了吗?**(schema 只在首次建表时执行)
## 七、常见坑速查
| 症状 | 根因 | 处理 |
|---|---|---|
| 端点 404 | 忘了 `routes.rs` 注册 | 补 3 条 `.route()` + 同步改 `route_table_is_pinned` 钉子表 |
| 端点 500 | 表不存在 / spec 没进 `ALL_SPECS` | 补 `schema.sql` + 补 `ALL_SPECS` |
| 页面 404 | `App.tsx` 的 Route path ≠ 菜单 `url_address` | 三处对齐 |
| 侧栏没有这个菜单 | `seed.rs` 没加 / 没重启回灌 | 加种子 + **重启进程**(不必删库) |
| 非管理员也能看 | `module_key` 是 `None` | 改成 `Some("app/Entity")` |
| 非管理员看不到也访问不了(预期) | 没授权 | 写 `base_authorize` 或调授权接口 |
| 金额变成 `9.9` | numeric 列没标 `numeric: true` | spec 标上 + `numeric_columns` 同步 |
| 改了 schema 不生效 | schema 只在首次建表执行 | 清空 `data/` 重建 |
| `check-module.sh` 退出码 2 | 期望表没加这个 appCode/Entity | 改 `scripts/check-module.sh` 的 `case` |
| 建了重复账号 | 官方 `f_account` **无 UNIQUE** | 唯一性**应用层**保证(只比 `delete_mark=0` 的行) |
@@ -1,6 +1,6 @@
# 面 B:官方 JNPF 契约面(规格书)
> **这份文档是「尺子的规格」** —— [`scripts/perm-smoke-jnpf.sh`](../scripts/perm-smoke-jnpf.sh) 逐条断言的就是本文的每一条。
> **这份文档是「尺子的规格」** —— [`scripts/perm-smoke-jnpf.sh`](scripts/perm-smoke-jnpf.sh) 逐条断言的就是本文的每一条。
> 官方源码依据见 [`JNPF_SOURCE_AUDIT.md`](JNPF_SOURCE_AUDIT.md)(每条带 `文件:行号`)。
---
@@ -1,16 +1,19 @@
# 官方 JNPF 源码审计(本仓的「官方面」地基)
# 官方 JNPF 源码审计(本技能的「官方面」地基)
> 这份文档回答**一个**问题:**本仓(Rust)的契约与官方 JNPF(Java)到底差在哪、哪些已经对齐了。**
> 这份文档回答**一个**问题:**本技能(Rust 模板)的契约与官方 JNPF(Java)到底差在哪、哪些已经对齐了。**
>
> 全部结论来自对官方源码的**逐行核对**,每条带 `文件:行号`。
> 官方源码坐标:`~/Desktop/workspace/jnpf/`(下文所有路径均相对它)。
> 核对日期:**2026-10-26**。官方版本:`jnpf-web-apps-main`(Vue3 前端)+ `jnpf-java-boot`(Java 后端)。
**配套阅读**:
- 契约(权威)→ [`contract.md`](contract.md)
- 契约红线(权威)→ [`SKILL.md`](SKILL.md) §契约红线 + [`PERMISSION.md`](PERMISSION.md)
- 迁移操作(怎么做)→ [`MIGRATION.md`](MIGRATION.md)
- 面 B 规格(要做到什么程度)→ [`JNPF_COMPAT_SURFACE.md`](JNPF_COMPAT_SURFACE.md)
- 实施期裁决 → [`decisions.md`](decisions.md)
- 实施期裁决 → 参照实现仓的 `docs/decisions.md`(`~/Desktop/workspace/ssw-jnpf-lite-rust/docs/decisions.md`)
> 📌 下文的「本仓」= 本技能的 Rust 模板(`src/backend` + `src/frontend`)。
> 模板与参照实现仓 `~/Desktop/workspace/ssw-jnpf-lite-rust/` 的 `src/` **逐字节一致**(只差 `data/` 与 `dist/`)。
---
+9 -4
View File
@@ -1,11 +1,16 @@
# 迁移指南(Rust ⇄ NestJS ⇄ 官方 JNPF Java)
> 本仓的价值不是「一个 JNPF 后台」,而是**一个可双向搬运的框架**:
> 官方 JNPF Java ↔ 本仓 Rust ⇄ react 版 NestJS,三者**数据模型逐字同形**(同一套 `base_*` 表、同一套 cipher、同一套信封)。
> 本技能的价值不是「一个 JNPF 后台」,而是**一个可双向搬运的框架**:
> 官方 JNPF Java ↔ 本技能 Rust 模板 ⇄ react 版 NestJS,三者**数据模型逐字同形**(同一套 `base_*` 表、同一套 cipher、同一套信封)。
>
> **先读**:[`JNPF_SOURCE_AUDIT.md`](JNPF_SOURCE_AUDIT.md)(官方源码逐行核对,带 `文件:行号`)、
> [`JNPF_COMPAT_SURFACE.md`](JNPF_COMPAT_SURFACE.md)(面 B 规格)、
> [`contract.md`](contract.md)(本仓契约唯一真源)。
> [`PERMISSION.md`](PERMISSION.md)(权限与 `base_*` 表的红线)、
> [`SKILL.md`](SKILL.md) §契约红线。
> 📌 **本文的「本仓」= 本技能的 Rust 模板**(`src/backend` + `src/frontend`)。
> 模板与参照实现仓 `~/Desktop/workspace/ssw-jnpf-lite-rust/` 的 `src/` **逐字节一致**(只差 `data/` 与 `dist/`),
> 所以文中提到的文件/行号在两处都成立。
---
@@ -201,7 +206,7 @@ COPY (SELECT * FROM base_module) TO STDOUT WITH CSV HEADER;
**(b) 直接在官方库侧手写 `INSERT`**
本仓种子数据量极小(内置 2 角色 + 8 菜单 + 1 管理员 + 若干授权)⇒
用 `docs/contract.md` 的字段清单手写 `INSERT` 往往比导数据更快。
用 `PERMISSION.md` §一的字段清单手写 `INSERT` 往往比导数据更快。
**业务数据**(`demo_item` / `shop_product` / `book_shop_book`)同理。
### 6.2 业务表 3 张:官方**没有对应表** ⇒ 要先建实体
+178
View File
@@ -0,0 +1,178 @@
# 权限模版(MVP 期就按 JNPF 形态钉死)
> 权限是迁移最硬的一块。本仓从第一天起就把 `base_*` 的**表名/列名/语义**照官方 DDL 抄死,
> 使稳定期换 Java 后端时**不用动表**(只导数据)。端点路径与列表形状**故意没锁**(那是面 A/面 B 的事)。
## 一、数据模型(7 张表,字段名与官方逐字一致)
| 表 | 用途 | 关键列 |
|---|---|---|
| `base_user` | 用户 | `f_id` / `f_account` / `f_password` / `f_real_name` / `f_is_administrator` / `f_delete_mark` / `f_secretkey` |
| `base_role` | 角色 | `f_id` / `f_en_code`(应用层唯一) / `f_full_name` / `f_delete_mark` |
| `base_module` | 菜单 | `f_id` / `f_full_name` / `f_url_address`(= 前端 Route path 去前导斜杠) / `f_parent_id` / `f_type`(**INTEGER**:1 目录 2 页面) / `f_en_code`(官方点权限用,本仓种子为空) |
| `base_authorize` | 授权 | `f_object_type` / `f_object_id` / `f_item_type` / `f_item_id` |
| `base_role_relation` | 用户↔角色 | `f_role_id` / **`f_object_id`(用户 id!)** / `f_object_type='user'` |
| `base_user_relation` | 用户↔组织/岗位 | **`f_user_id`** / `f_object_id` / `f_object_type`(`'organize'` / `'position'`) |
| `base_organize` | 机构 | `f_parent_id` 树 |
所有表复合主键 `(f_id, f_tenant_id)`,单租户固定 `f_tenant_id='0'`。
### ⚠️ 两个高频字段名陷阱(官方原样保留,别"优化")
| 陷阱 | 事实 | 写错的后果 |
|---|---|---|
| `base_role_relation` | 用户 id 存在 **`f_object_id`**(配 `f_object_type='user'`),**没有 `f_user_id`** | 角色授权**永远不生效**(且**不报错**) |
| `base_user_relation` | 组织/岗位关系在**另一张表**,那里**才有 `f_user_id`** | 组织/岗位授权**永远不生效**(且**不报错**) |
🔴 这两个坑**都是静默失败** ⇒ 必须有测试钉住(本仓 `permission_it.rs` 钉了)。
### 权威来源(不要凭记忆写列名)
- 官方 DDL:`~/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)
(同目录另有 9 个 init 文件,**只读**)
- 本仓落地:`src/backend/db/schema.sql`
- 逐行核对报告:[`JNPF_SOURCE_AUDIT.md`](JNPF_SOURCE_AUDIT.md) §2.6
## 二、四源合并(已实现,`src/backend/src/permission.rs`)
**权限 = 用户直授 + 角色 + 组织 + 岗位**,四条路都查:
| 源 | 路径 |
|---|---|
| 1. **直授** | `base_authorize`(`f_object_type='user'`)⇒ 菜单 id |
| 2. **角色** | `base_role_relation`(`f_object_type='user'`)⇒ `f_role_id` ⇒ `base_authorize`(`f_object_type='role'`) |
| 3. **组织** | `base_user_relation`(`f_object_type='organize'`)⇒ `f_object_id` ⇒ `base_authorize`(`f_object_type='organize'`) |
| 4. **岗位** | `base_user_relation`(`f_object_type='position'`)⇒ `f_object_id` ⇒ `base_authorize`(`f_object_type='position'`) |
🔴 **只查角色会漏授权**——组织/岗位授权最容易被忽略。
🔴 **管理员短路在查 SQL 之前**(`f_is_administrator=1` ⇒ 直接放行,不查任何授权表)。
🔴 **只有 `base_authorize` 过滤 `f_delete_mark = 0`**;`base_role_relation` / `base_user_relation`
**不过滤**(对齐官方 SQL 的过滤习惯)。
### 判权:菜单**路径**,不是点权限
本仓的守卫 = **`spec.module_key` == 菜单 `f_url_address`**:
```
spec.module_key == seed.url_address == 前端 App.tsx 的 Route path(去前导斜杠)
```
🔴 **官方是点权限**(`@SaCheckPermission("permission.user")`,取自 `base_module.f_en_code`)——
这是本仓与官方最大的鉴权模型差异(审计报告 D6)。
⇒ 迁官方前**必须给菜单补 `f_en_code`**(`MIGRATION.md` §2.4)。
⇒ 面 B 落地时要**两套判据并存**(路径判权给面 A,`f_en_code` 判权给面 B)。
### 未映射 ⇒ **放行**(不是拒绝)
菜单**未映射**到 `base_module` ⇒ **放行**(对齐官方 `SswPermissionGuard` 的 warn 路径)。
🔴 **这条最容易写反,而且静默**(不报错)⇒ 有测试钉住。
## 三、端点契约
| 方法 | 路径 | 守卫 | 返回 |
|---|---|---|---|
| POST | `/api/oauth/Login` | 无 | `{token, expiresIn:7200, tokenTypeName:'bearer'}` |
| GET | `/api/oauth/CurrentUser` | 登录 | `{userInfo:{userId,userAccount,userName,isAdministrator}, menuList}` |
| 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}` | 登录 | body `{objectType:'role', module:['m1','m2']}` |
| GET | `/api/permission/Authority/RoleModules?roleId=` | 登录 | `string[]` |
| GET/POST/DELETE | `/api/ssw/{app}/{Entity}/{List,Save,Delete?id=}` | 登录(+ 菜单,按 `module_key`) | |
### 授权写接口的三个坑
1. **`objectType` 必须小写 `'role'`** —— 官方对大小写错误是**静默忽略**(返 200 但一行不写)。
2. **`module` 传一维数组** `['m1','m2',…]`(半选节点合进同一数组,对齐官方 `MenuAuth.vue`)。
3. 官方 body 是本仓的**超集**(多 `button`/`column`/`resource`/`form`/`systemIds`)⇒ 本仓**照单全收**,
只消费 `objectType` + `module` ⇒ 官方前端直接调本仓即可(**零改动**)。
## 四、`ActionResult` 码表
本仓已用官方 `ActionResultCode` 的前 4 个:
| code | 含义 | 何时 |
|---|---|---|
| `200` | 成功 | |
| `400` | 业务失败 | 账号重复、参数错、有子机构拒删…… |
| `403` | 无菜单权限 | 已登录但菜单未授权 |
| `600` | 未登录(会话过期) | 无 token / token 无效 |
🔴 **业务失败恒 HTTP 200**——成败只看 body 的 `code`。**禁止** 401/403 裸 body。
🔴 **未知路由保留 HTTP 404**(body 仍是信封形状)——不要用全局 404 兜底把它变成 200。
**官方还有、本仓缺的**(面 B 要补,见 `JNPF_COMPAT_SURFACE.md` §4):
| code | 官方常量 | 说明 |
|---|---|---|
| `401` | `VALIDATEERROR` | 官方 `MsgCode.PS012` 之类的校验失败 |
| `500` | `EXCEPTION` | 未捕获异常 |
| `601` | `SESSIONOFFLINE` | 被踢下线 |
| `602` | `SESSIONERROR` | 会话异常 |
🔴 **官方前端 `request.ts:78-80` 只在 `601`/`602` 时清 token** ⇒ 只返 `600` 会让页面**卡住不跳登录**。
⇒ 面 B **无 token 必须返 `602`**(不是 600)。
## 五、口令
- **加密链**(前端 → 后端):`md5(明文)` → `AES-256-ECB-PKCS7`(key = `md5("EY8WePvjM5GGwQzn")` 的 **32 个 ASCII 字节**)→ hex。
- **检验向量**:`encryptPassword('123456')` ==
`d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b`。
一行自证:`./target/release/ssw-jnpf-lite-rust --enc 123456`。
- **库内存** `md5(明文)` 的小写 hex;登录时 `decrypt(密文)` 得到 `md5(明文)` ⇒ **大小写不敏感**比较。
- 🔴 **密文只在请求体里出现,永不回显**;用户列表**手工挑字段**去掉 `password`。
- 🔴 官方多一步 `secretkey`(`md5(lower(md5(明文)) + lower(secretkey))`)⇒ 迁官方要**换算**,
但**不需要明文**(`MIGRATION.md` §7)。
## 六、迁移映射(稳定期)
| 本仓 | 官方 |
|---|---|
| `permission.rs` 的四源合并 | `@SaCheckPermission` + `SswPermissionGuard.requireMenu`(判据从**路径**换成 **`f_en_code`**) |
| `auth.rs` 的内存 token | jnpf-oauth / Sa-Token(内存模式同代) |
| `cipher.rs` | `DesUtil` + `SecurityProperties.setSecurityKey`(**逐字节一致**) |
| `envelope.rs` | `ActionResult` + `ResultExceptionHand` |
| `sys.rs` 的 5 组显式 handler | 5 个官方 Controller(`/api/permission/Users` / `Role` / `Organize` / `Authority` / `/api/system/Menu`) |
| `db/schema.sql` 的 7 张 `base_*` | 官方 DDL(**逐字同形**)⇒ **只导数据,不导结构** |
| `seed.rs` 的两段式种子 | 官方建表后灌数据(补 `f_en_code` + `f_secretkey`) |
**数据 ETL**:
```bash
# 🔴 pglite 是**进程内单用户 PG、无 TCP 监听** ⇒ psql / pg_dump **连不上**
# ⇒ 走应用内导出(新增一个 --dump 子命令跑 COPY ... TO STDOUT),或手写 INSERT
```
详见 [`MIGRATION.md`](MIGRATION.md) §6。
## 七、验证(可重复执行)
```bash
bash scripts/perm-smoke.sh # 面 A 32 条(含权限闭环)
bash scripts/perm-smoke-jnpf.sh # 面 B 18 条(官方形状)
cargo test # 195 条单测(含两个陷阱的回归)
```
**面 A 尺子覆盖的权限闭环**:
未登录 600 · 加密登录 · 菜单树 · 建用户 · **重复账号返 400 而非 500** ·
写授权(一维/二维兼容)· 非管理员菜单收窄 · 非管理员访问系统管理返 403 ·
已授权业务返 200 · 未知路由 404 · 三个业务模块全链路。
🔴 **判读原则**:**返回了数据不能证明权限生效**
(管理员短路 / 菜单没映射 / 缓存没清 / 异常降级放行,四条路径全是"放行")。
**「菜单收窄 + 403 拦截」才是有说服力的信号。**
## 八、MVP 未做的部分(迁移时补,不是遗漏)
- **按钮 / 列 / 表单 / 数据范围级授权**(`base_module_button` / `_column` / `_form` / `_data`)——
官方 DDL 里都有,v1 只做 `item_type='module'`(菜单)一类。
- **多租户**(`jnpf-tenant*`)——单租户固定 `f_tenant_id='0'`。
- **Redis / Sa-Token**——内存 token 表即可。
- **分页**——契约里的 `List` 就是全量;要分页是 JNPF 稳定期的 `SuperServiceImpl.page`。
- **低代码引擎**(表单 / 流程 / 代码生成)——官方能力,不碰。
- **点权限(`f_en_code`)**——本仓按菜单路径判权;面 B 才引入 `f_en_code` 判据。
- **`base_user.secretkey` 的真实算法**——本仓留位待迁移补(迁时一次性换算)。
+134 -86
View File
@@ -1,28 +1,100 @@
# ssw-jnpf-lite-rust
# ssw-jnpf-lite-rust · Rust 全栈 MVP
**JNPF 兼容契约的 Rust 实现** —— 单二进制、零外部服务(进程内原生 PostgreSQL)。
**自包含技能**:模板、契约实现、权限模版、冒烟脚本全部在技能目录内,**不依赖任何其它技能或外部服务**,
除 Node 外无需安装任何东西(数据库是**进程内原生 PostgreSQL**)。
它的存在意义只有一条:**让「用 Rust 写业务」和「迁回官方 JNPF(Java)」之间是机械翻译,而不是重写。**
为此本仓的**数据模型(`base_*` 表名/列名/语义)与 HTTP 契约**从第一天起就锁死成官方 JNPF 的形状。
来自 `ssw-jnpf-lite-react`(NestJS + React)的 **Rust 全栈 counterpart**——两者是**并列可选**的独立技能,
不是依赖关系:要 MVP 期就用 Node 栈选 `ssw-jnpf-lite-react`,要 MVP 期用 Rust 栈选本技能。
本仓是**双面后端**:**同一进程**同时提供
**面 A**(ssw/react 契约,27 条路由,冻结)与 **面 B**(官方 JNPF 契约,5 条路由 + 2 条共用路由按 `Vue-Version: 3` 分流),
共用同一套 `base_*` 表 / cipher / seed,但**权限判据不同**(面 A 按菜单路径 / 面 B 按 `f_en_code` 点权限)。
⇒ 既是「Rust ⇒ 官方 JNPF」的**可移植性验证床**,也是「官方 JNPF / React 版 ⇒ 打到本框架跑」的**对照靶场**。
> 📌 **本仓 = 技能本体**(不是「技能的项目副本」):仓根就是技能目录(`SKILL.md` 在仓根),
> 三处软链 `~/.agents/skills/` · `~/.claude/skills/` · `~/.workbuddy/skills/` 均指向本仓,
> 所以**改一次仓 = 改一次技能**。
- 📘 **契约唯一真源**:[`docs/contract.md`](docs/contract.md) —— 与本文件冲突时以契约为准。
- 🧭 **agent 指引**:[`CLAUDE.md`](CLAUDE.md)(红线 / 踩坑 / 端点全表)· [`HANDOFF.md`](HANDOFF.md)(交接)。
- 🛠 **怎么起 / 怎么冒烟 / 常见故障**:[`docs/runbook.md`](docs/runbook.md)。
- 🧾 **实施期裁决(88 条「什么—为什么—代价」)**:[`docs/decisions.md`](docs/decisions.md)
· **分支级已知限制**:[`docs/known-limitations.md`](docs/known-limitations.md)。
## 设计原则:MVP = JNPF 的 Rust 版垫片
---
**MVP 后端不是随便写的 Rust 服务,而是 JNPF 契约的 Rust 版垫片**——契约从第一天锁死,
使稳定期换 Java 后端是「机械翻译」而非重写。
**锁死的五件事**(详见 [`MIGRATION.md`](MIGRATION.md) §1):
| # | 锁死的东西 | 为什么 |
|---|---|---|
| 1 | `base_*` 表名 / 列名(逐字对齐官方 DDL,含两个官方陷阱) | 迁移期靠 `--data-only` 导数据,列名差一个字符就导不进去 |
| 2 | 口令密文算法(`md5 → AES-256-ECB-PKCS7 → hex`) | 前端 `cipher.ts` / 后端 `cipher.rs` / 官方 `DesUtil` 逐字节一致 |
| 3 | 统一信封 `ActionResult{code,msg,data}` + 业务失败恒 HTTP 200 | 换栈后前端零改 |
| 4 | 主键 = 36 位 UUID v4(`f_id VARCHAR(50)`) | 与官方 `IdUtil.fastUUID()` 同形 |
| 5 | JSON 键名 = 列名去 `f_` 前缀后 camelCase | 官方 Jackson 自动剥离 `f` |
**故意没锁的两件事**(就是「面 A / 面 B」要解决的):
- **端点路径**——面 A 走 ssw 约定 `/api/ssw/{app}/{Entity}/{List|Save|Delete}`,面 B 走官方 RESTful 形状。
- **列表响应形状**——面 A 是裸数组,面 B 是官方 `PageListVO{pagination,list}`。
⇒ **一个后端进程同时服务两套契约**,靠请求头 `Vue-Version: 3` 判面
(官方前端必发,本仓前端**唯一不发**的一头 ⇒ 零歧义)。详见 [`JNPF_COMPAT_SURFACE.md`](JNPF_COMPAT_SURFACE.md)。
## 选型决策:Rust 版 vs react 版 vs ssw-jnpf-lite(Java)
| | **ssw-jnpf-lite-rust**(本技能) | **ssw-jnpf-lite-react** | **ssw-jnpf-lite**(Java) |
|---|---|---|---|
| MVP 期后端栈 | Rust / axum | Node / NestJS | Java / Spring Boot |
| 部署 | **单二进制**(库链进可执行文件) | Node 进程 + 前端静态产物 | JVM + 前端静态产物 |
| MVP 期迭代速度 | **快**(编译期类型安全,重构有保障) | 快(AI 也熟) | 慢(编译 + 脚手架重) |
| 迁官方 JNPF 的成本 | 低(`MIGRATION.md` 有逐件翻译表) | 低(同上,NestJS 版) | **零**(本来就在 Java 上) |
| 官方前端能跑在上面吗 | ✅ **能**(面 B) | ✅ 能(面 B) | ✅ 原生 |
| 数据模型 | 与官方逐字一致(`base_*`) | 与官方逐字一致 | 与官方逐字一致 |
| 适合谁 | 想要 Rust 性能/单二进制,且要保迁移性 | 团队/AI 更熟 Node | 已经是 Java 团队,不打算换栈 |
**一句话**:**MVP 期用哪种栈都行,代价是「稳定期迁 JNPF」这件事**。
本技能把「快」放在 MVP 期(Rust),把「换栈」推迟并**锁死到有界范围**(5 件事 + 两把尺子)。
若你**本来就要用 Java**,直接用 `ssw-jnpf-lite`(零迁移摩擦)比绕一圈更划算。
## 目录
```
ssw-jnpf-lite-rust/ ← 仓根 = 技能根(三处软链指向这里)
├── SKILL.md # 入口:是什么 / 何时用 / 契约红线 / 两把尺子
├── README.md # 本文件:选型 / 运行 / 验收门 / 已知限制
├── HOWTO_MODULE.md # 加一个业务模块的操作手册(9 个接触点)
├── PERMISSION.md # 权限模版:表结构 / 四源合并 / 码表
├── MIGRATION.md # 迁移指南(Rust ⇄ NestJS ⇄ 官方 JNPF Java)
├── JNPF_SOURCE_AUDIT.md # 官方源码逐行核对报告(标 文件:行号)
├── JNPF_COMPAT_SURFACE.md # 面 B 规格书:官方形状端点 + 落地顺序 S1–S6
├── CLAUDE.md / HANDOFF.md # 项目级 agent 指引 / 交接文档
├── run.sh # install / build / dev / backend / frontend / stop / logs
├── Cargo.toml # 🔴 cargo workspace 根(**复制脚手架时必须一起带走**)
├── .env.example # PORT / BIND_ADDR / PGLITE_DIR
├── scripts/
│ ├── perm-smoke.sh # 面 A 尺子(32 条)
│ ├── perm-smoke-jnpf.sh # 面 B 尺子(18 条)★ 本技能独有
│ └── check-module.sh # 业务模块 9 接触点静态自检
├── src/
│ ├── backend/ # Rust 后端(6372 行 src + 4758 行 tests)
│ │ ├── src/{main,config,db,cipher,envelope,ids,session,state}.rs
│ │ ├── src/{auth,permission,seed,sys,crud,entities,routes,lib}.rs
│ │ ├── db/schema.sql # 10 张表(base_* 7 + 业务 3)
│ │ └── tests/ # 6 个集成测试文件
│ └── frontend/ # React + Vite(1374 行)
│ ├── utils/cipher · api/{request,auth,sys,product,book}
│ └── views/{Login,Dashboard,DemoItem★,Product★,Book★,UserManage,RoleManage,OrganizeManage,MenuManage}
├── references/ # BaseCrudController.java(**非** JNPF 官方类)+ README
├── template-boot-jnpf/ # JNPF 标准栈最小可运行骨架(Java)
└── docs/ # 项目级文档(契约真源 / 运维 / 裁决 / DDL)
├── contract.md # 【契约唯一真源】端点 / 返回形状 / 数据模型
├── runbook.md # 怎么起 / 怎么冒烟 / 常见故障
├── decisions.md # 实施期逐条裁决(88 条「什么—为什么—代价」)
├── known-limitations.md # 分支级已知限制(被接受/挂起的东西)
└── ddl/ # 官方 DDL 摘录
```
★ = 业务模块模板(`HOWTO_MODULE.md` 参照实现)。
## 快速开始
```bash
# 一次性:装依赖(cargo fetch + npm install)+ 构建(cargo build --release + vite build)
# 一次性:装依赖(cargo fetch + npm install)
bash run.sh install
# 构建(cargo build --release + vite build)
bash run.sh build
# 日常:后台起后端(30010) + 前端(5173),日志在 .logs/,PID 在 .run/
@@ -40,46 +112,23 @@ bash run.sh logs # 看日志尾部
| `30010` | 后端(Rust) | **硬约定**:`run.sh` 的端口不许改 —— `PORT` ≠ 30010 时 `run.sh dev` / `run.sh backend` 报错退出 2(要换端口请**直接跑二进制**)。**后端二进制本身**吃 `PORT`(非法值回落 30010)。默认**只监听 `127.0.0.1`**;`BIND_ADDR=0.0.0.0` 才对外暴露 |
| `5173` | 前端(vite dev) | `strictPort: true` ⇒ 端口被占直接报错,不自动换端口 |
---
> ⚠️ 本机 curl 走系统代理 ⇒ 打 localhost **必须**加 `--noproxy '*'`。
## 目录
## 把脚手架复制到新项目
```
ssw-jnpf-lite-rust/
├── Cargo.toml # cargo workspace 根(成员 = src/backend)+ release profile
├── run.sh # install / build / dev / backend / frontend / stop / logs
├── .env.example # PORT / BIND_ADDR / PGLITE_DIR(PGLITE_DIR 只能写绝对路径或 memory://)
├── src/backend/ # Rust 后端(axum 0.8 + pglite-rs 0.2,10 张表,32 条路由 = 面 A 27 + 面 B 5)
├── src/frontend/ # react 技能前端**逐字复制**(只改 vite 代理端口 30000 → 30010)
├── scripts/perm-smoke.sh # 权限闭环冒烟(32 条断言,零 node 依赖)—— 面 A 尺子
├── scripts/perm-smoke-jnpf.sh # 官方 JNPF 形状冒烟(18 条断言)—— 面 B 尺子(**已全绿 18/18**)
├── scripts/check-module.sh # 业务模块 9 接触点静态自检(纯静态,不起后端)
└── docs/ # contract.md(契约)· runbook.md(运维)· decisions.md(裁决)· known-limitations.md(已知限制)
# JNPF_SOURCE_AUDIT.md(官方源码逐行核对)· JNPF_COMPAT_SURFACE.md(面 B 规格)· MIGRATION.md(迁移指南)· ddl/
```bash
SKILL=~/.agents/skills/ssw-jnpf-lite-rust # 软链 ⇒ 实际指向本仓
PROJ=~/Desktop/my-app
mkdir -p "$PROJ/src" # 脚手架固定进 src/:没有则创建,已有则并入
rsync -a --exclude node_modules --exclude dist --exclude target --exclude data --exclude .DS_Store \
"$SKILL"/src "$SKILL"/scripts "$SKILL"/run.sh "$SKILL"/Cargo.toml "$SKILL"/.env.example "$SKILL"/.gitignore "$PROJ"/
cd "$PROJ" && cp .env.example .env && ./run.sh install && ./run.sh dev
```
---
## 它做了什么(v1 = 全量契约对齐)
- **登录 / `CurrentUser`**:`POST /api/oauth/Login`(form-urlencoded,密文 hex)⇒ `{token, expiresIn:7200, tokenTypeName:'bearer'}`;
`GET /api/oauth/CurrentUser` ⇒ `{userInfo, menuList}`。
- **5 组 `base_*` 管理 CRUD**:用户 / 角色 / 机构 / 菜单 / 授权。
- **统一授权**:`PUT /api/permission/Authority/Data/{objectId}`(body `{objectType:'role', module:[...]}`,**小写 + 一维数组**)。
- **四源权限合并**:用户直授 + 角色 + 组织 + 岗位;**管理员在任何 SQL 之前短路放行**;**菜单未映射 ⇒ 放行**。
- **两段式种子**:`ensure_base`(每次启动补内置角色/菜单/授权)+ `first_seed`(仅首次建 `admin/123456`)。
- **3 个业务模块**(spec 驱动 CRUD 引擎):`demo/DemoItem` · `shop/Product` · `books/Book`。
### 契约红线(摘要,完整版见 `CLAUDE.md`)
1. **业务失败一律 HTTP 200 + `{code,msg,data}`**;成败只看 body 的 `code`。
唯一例外:**未知路由 = HTTP 404**(body 仍是信封)。鉴权失败也是 200(`600` 未登录 / `403` 无菜单权限)。
2. **`base_*` 表名/列名逐字对齐官方 JNPF DDL**(含两个「故意不修正」的陷阱,见 `CLAUDE.md`)。
3. **numeric 列必须是 JSON 字符串**(`"9.90"`,不是 `9.9`);int 列保持数字。
4. **口令不得外泄**:库里存 `md5(明文)`,对外响应手工挑字段(用户列表去掉 `password`)。
5. **schema DDL 绝不可从 HTTP 下载**。
---
> ⚠️ **只复制脚手架本体**——`*.md` / `references/` / `template-boot-jnpf/` 是技能资产,留在技能目录只读引用。
> 全量 `cp -R` 会让项目目录混满技能噪音,日后技能升级也灌不进项目。
> 🔴 **`Cargo.toml`(workspace 根)别漏**:缺了它 `src/backend` 的 `workspace = true` 继承无处可依 ⇒ cargo 直接报
> `could not find Cargo.toml in ... or any parent directory`,**脚手架编译不起来**。
## 验收门
@@ -87,26 +136,37 @@ ssw-jnpf-lite-rust/
|---|---|---|
| ① 编译 | `cargo build --release` | 0 error **0 warning** |
| ② 单测 | `cargo test` | 全绿(当前 **195 passed / 0 failed**) |
| ③ 冒烟 | `bash scripts/perm-smoke.sh` | **PASS=32 FAIL=0**(需后端已起在 `:30010`) |
| ③ 冒烟(面 A) | `bash scripts/perm-smoke.sh` | **PASS=32 FAIL=0**(需后端已起在 `:30010`) |
| ③' 冒烟(面 B) | `bash scripts/perm-smoke-jnpf.sh` | **PASS=18 FAIL=0 SKIP=0**(**已达标**) |
| ④ 前端手验 | `bash run.sh dev` | `http://127.0.0.1:5173` → `admin/123456` 登录 → 菜单树正确 → 5 个管理页可增删改 → DemoItem/Product/Book 三页可用 → 退出再登录 |
外加:`bash scripts/check-module.sh`(9 接触点静态自检)—— 加业务模块后立刻跑的前置闸门。
### 第二把尺子(面 B:官方 JNPF 形状)
## 数据库:进程内原生 PostgreSQL
```bash
bash scripts/perm-smoke-jnpf.sh # 18 条断言,打印「面 B 覆盖 N/18」
```
**pglite-rs 0.2** —— 把 `postgres-pglite` 编译成**原生静态库**链进二进制 ⇒ 进程内单 backend,
**真实 PostgreSQL 语义**(类型 / MVCC / 事务 / 扩展 / 线协议)。
**面 B = 官方 JNPF 契约面**(官方形状的端点 / 响应 / 码表),规格见 `docs/JNPF_COMPAT_SURFACE.md`。
✅ **已落地**(`src/backend/src/jnpf.rs`,S1–S6 全完成)⇒ 当前报 **`PASS=18 FAIL=0 SKIP=0`(面 B 覆盖 18/18)**。
面 B 的判别头是 **`Vue-Version: 3`**(官方前端必发,本仓前端**唯一不发**的一头 ⇒ 零歧义)。
面 A 27 条路由**冻结**、面 B 5 条新增 ⇒ **同一进程**同时提供两套契约。
- 🔴 **不是**浏览器 WASM 版 PGlite(`@electric-sql/pglite`)——那个禁止引入。
- 数据落盘 `src/backend/data/lite.pg`。
- 🔴 **一个数据目录只能被一个进程打开** ⇒ 集成测试要么串行、要么各自独立数据目录。
- 🔴 `PGLITE_DIR=memory://` = 系统临时目录里的一次性数据目录(进程退出即销毁),**不是**真内存模式。
- 🔴 **无 TCP 监听** ⇒ `psql` / `pg_dump` **连不上** ⇒ 数据导出要走应用内的 `COPY ... TO STDOUT`(见 `MIGRATION.md` §6)。
> 本机 curl 走系统代理 ⇒ 打 localhost **必须**加 `--noproxy '*'`。
## 已知限制(被接受 / 挂起)
---
| 限制 | 说明 |
|---|---|
| **面 B 仍有 10 条偏差** | 面 B 已落地(`src/backend/src/jnpf.rs`,尺子 **18/18 全绿**),但 `AuthorizeDataReturnVO.list` 返空数组 · `sysConfigInfo` 返 `{}` · 无按钮/列/表单/数据级权限 · 业务菜单 `f_en_code` 是自拟占位 · `permissionList` 粒度 = 每菜单一条 · `Organize/AsyncList` 未分页 —— 逐条见 `JNPF_COMPAT_SURFACE.md` §8(B1–B10) |
| 不分页(**面 A**) | 面 A 契约里的 `List` 就是全量(前端不分页);要分页是 JNPF 稳定期的 `SuperServiceImpl.page`(**面 B 已是分页信封**) |
| 不做按钮/列/表单/数据范围级授权 | 官方 DDL 里有 `base_module_button` / `_column` / `_form` / `_data`,v1 只做 `item_type='module'` |
| 不做多租户 | 单租户固定 `f_tenant_id='0'` |
| 无 Redis / Sa-Token | 内存 token 表即可(进程重启即失效,与 JNPF 的 Sa-Token 内存模式同代) |
| 口令存储**缺 `secretkey` 一步** | 本仓存 `md5(明文)`,官方存 `md5(md5(明文)+secretkey)`;迁官方时**一次性换算**,**不需要明文**(`MIGRATION.md` §7) |
| `f_account` 无 UNIQUE | 官方 DDL 就是没有 ⇒ 唯一性**应用层**保证(只比 `delete_mark=0` 的行) |
| **两套权限判据并存** | 面 A 按**菜单路径**(`f_url_address`)、面 B 按**点权限**(`f_en_code`)⇒ 同一用户可能**面 A 通、面 B 拒**(设计,不是 bug) |
| 低代码引擎不碰 | 表单 / 流程 / 代码生成是官方能力 |
| token 寿命 = 进程寿命 | `session.rs` 是内存 token 表、无 TTL;`expiresIn:7200` 是契约字面量、**不强制执行** |
## 三个参照物(各司其职,别混)
@@ -116,32 +176,20 @@ bash scripts/perm-smoke-jnpf.sh # 18 条断言,打印「面 B 覆盖 N/18」
| `ssw-jnpf-lite-react` 技能(`~/Desktop/workspace/skills/ssw-jnpf-lite-react/`) | **行为真源**(NestJS 版把契约跑起来了);本仓前端是它的**逐字复制** |
| `tdc-rs` 兄弟项目(`~/Desktop/workspace/tdc-rs/`) | **只抄工程手法**;不共享代码 / 端口 / 数据目录 |
---
## 与 react 版的关系
## 已知限制(分支级)
| | react 版 | rust 版 |
|---|---|---|
| 后端栈 | NestJS | axum |
| 端口 | **30000** | **30010** |
| 契约 | 同一套(面 A) | 同一套(面 A) |
| 前端 | 同一份 React 产物 | 同一份 React 产物 |
| 业务表名 | `demo_item` / `shop_product` / `book_shop_book` | **同名** ⇒ 两版后端能开同一个库 |
| 尺子 | `perm-smoke.sh`(22 条基线) | `perm-smoke.sh`(32 条)+ `perm-smoke-jnpf.sh`(18 条) |
- **面 B 的 10 条已知偏差**(B1–B10,逐条见 `docs/JNPF_COMPAT_SURFACE.md` §8 与 `docs/known-limitations.md` §H):
授权读 `list` 返空数组 · `sysConfigInfo` 返 `{}` · `currentSystemId` 固定 ·
**无按钮/列/表单/数据级权限** · 三个业务菜单的 `f_en_code` 是自拟占位 ·
`permissionList` 粒度 = 每菜单一条(`modelId` = 菜单 id)· `Organize/AsyncList` 未分页。
- **口令存储缺官方 `secretkey` 一步**:本仓存 `md5(明文)`,官方存 `md5(md5(明文)+secretkey)`。
迁官方时**一次性换算**即可,**不需要明文**(见 `docs/MIGRATION.md` §7)。
- **两套权限判据并存**:面 A 按菜单路径(`f_url_address`)、面 B 按点权限编码(`f_en_code`)。
⇒ 同一用户可能**面 A 通、面 B 拒**(这是设计,不是 bug);种子菜单已补 `f_en_code`(8 条),
业务菜单的 `f_en_code` 仍是自拟值,迁官方前须换成官方真实编码。
- **release 二进制没有 catch-all 的自动化覆盖**:触发 panic 的端点是 `#[cfg(test)]` 专属;
catch-all 中间件代码在测试构建与 release 构建里逐字相同,且 release profile **无** `panic = "abort"` ⇒ 行为等价。
- **`Path<String>` 遇畸形百分号编码** ⇒ **实测 axum 0.8.9 接受该转义**:`PUT /api/permission/Authority/Data/%zz`
返回 **HTTP 200 + `{"code":600,"msg":"未登录","data":null}`**(信封,正常)⇒ **不存在**「返非信封 400」这种破口。
- **token 的真实寿命 = 后端进程寿命**(`session.rs` 是内存 token 表、**没有 TTL**):
登录响应里的 `expiresIn: 7200` 是**契约 §6.1 逐字定死**的字面量、**不会被强制执行**
(进程不重启就永不过期);契约未覆盖 TTL ⇒ 不改。
- **冒烟脚本每次跑会往库里留一行** `shop_product` + 一行 `book_shop_book` + 一行 `smoke_user`(react 同款行为,契约未要求清理)。
- 冒烟脚本在「重复账号 curl 超时」场景下 stderr 会多一行 `cat: … No such file`(观感,判据不受影响)。
- 冒烟脚本在「空 body 前置失败」时 jq / python 两条路径的前置提示文案不同(退出码都是 2)。
---
🔴 **两版之间不共享代码、不共享端口、不共享数据目录**。
迁移走「换栈」路径:契约不变 ⇒ **前端零改**,只换后端进程。
详见 [`MIGRATION.md`](MIGRATION.md) §5。
## 技术栈
+171
View File
@@ -0,0 +1,171 @@
---
name: ssw-jnpf-lite-rust
description: Rust 全栈 MVP 脚手架,契约与数据模型从第一天起对齐 JNPF 标准版(cipher / ActionResult / f_ 列 / varchar(50) UUID / base_* 权限表 / 进程内原生 PostgreSQL),前后端同一进程同时提供「面 A(ssw 契约 27 条)」与「面 B(官方 JNPF 形状 5 条 + 2 条共用按 Vue-Version 头分流)」两套契约。适用于「AI 开发 MVP 阶段要 Rust 全栈快速迭代、稳定后迁 JNPF 标准栈」的场景,含用户/角色/机构/菜单/授权五套管理页与四源合并菜单守卫。加业务模块见同目录 HOWTO_MODULE.md。
type: skill
---
# ssw-jnpf-lite-rust
**自包含技能**:Rust 后端(axum 0.8 + 进程内原生 PostgreSQL)+ React 前端 + 两把冒烟尺子,
全部在技能目录内,**不依赖任何其它技能或外部服务**(无 Docker、无 Redis、无外部 PG、**除 Node 外无需装任何东西**)。
来自 `ssw-jnpf-lite-react`(NestJS + React)的 **Rust 全栈 counterpart**——两者是**并列可选**的独立技能,
不是依赖关系:要 MVP 期就用 Node 栈选 `ssw-jnpf-lite-react`,要 MVP 期用 Rust 栈选本技能。
## 本技能的真身:**不是「一个 JNPF 后台」,而是一个可双向搬运的框架**
```rust ⇄ TypeScript ⇄ Java
(axum) (NestJS) (官方 JNPF 7.0)
```
**三方共用同一套数据模型(`base_*` 表名/列名逐字对齐官方 DDL)与同一套密文算法**,
所以「迁到 JNPF」「从 JNPF 迁回来」「从 react 版换到 Rust 版」都是**近机械翻译**,不是重写。
- **Rust → 官方 JNPF** ⇒ 见 [`MIGRATION.md`](MIGRATION.md)(逐件翻译表 + import 速查 + 数据 ETL + 口令换算)
- **官方 JNPF → Rust** ⇒ 走**「面 B」**:本仓按官方形状提供第二套端点,**官方前端能直接跑在本仓上**
(判别依据 = 官方必发、而本仓前端**唯一不发**的 `Vue-Version: 3` 请求头;见 [`JNPF_COMPAT_SURFACE.md`](JNPF_COMPAT_SURFACE.md))
- **react 版 NestJS → Rust** ⇒ **同一套契约 ⇒ 前端零改**;两边能开同一个库(业务表名故意对齐)
## 开发主线:加一个业务模块
**只读这两份就够开发**:本文件(契约红线)+ [`HOWTO_MODULE.md`](HOWTO_MODULE.md)(9 个接触点、逐文件改法、验证命令)。
> ⚠️ **技能是模板不是项目**:起项目时**只复制脚手架本体**
> (`src/`(backend+frontend)+ `scripts/` + `run.sh` + `Cargo.toml` + `.env.example` + `.gitignore`)
> 到目标项目——代码固定落在**项目根的 `src/` 下**(`src/backend` + `src/frontend`,项目没有 `src/` 就先创建),在副本里开发。
> **不要 `cp -R` 整个技能目录**——`*.md` 文档和 `references/`、`template-boot-jnpf/` 是技能资产,
> 留在技能目录只读引用即可;全量复制会让项目目录混满技能噪音、日后技能升级也灌不进项目。
>
> 🔴 **`Cargo.toml`(workspace 根)必须一起复制**:`src/backend/Cargo.toml` 用的是
> `version.workspace = true` / `xxx = { workspace = true }` ⇒ 缺了上层 workspace 根,
> cargo 直接报 `could not find Cargo.toml in ... or any parent directory`,**脚手架根本编译不起来**。
```bash
SKILL=~/.agents/skills/ssw-jnpf-lite-rust # 本技能目录
PROJ=~/Desktop/my-app # 目标项目目录(任意路径)
mkdir -p "$PROJ/src" # 脚手架固定进 src/:没有则创建,已有则并入
rsync -a --exclude node_modules --exclude dist --exclude target --exclude data --exclude .DS_Store \
"$SKILL"/src "$SKILL"/scripts "$SKILL"/run.sh "$SKILL"/Cargo.toml "$SKILL"/.env.example "$SKILL"/.gitignore "$PROJ"/
cd "$PROJ" && cp .env.example .env && ./run.sh install && ./run.sh dev
# 后端 :30010 + 前端 :5173 → 打开 http://127.0.0.1:5173 → admin / 123456
```
> **除 Node 外无外部依赖**——数据库是 **pglite-rs 0.2**(把 postgres-pglite 编译成**原生静态库**链进二进制,
> 进程内单 backend,**真实 PostgreSQL 语义**;不是浏览器 WASM 版 PGlite)。数据落盘 `src/backend/data/lite.pg`。
> 🔴 **一个数据目录只能被一个进程打开** ⇒ 别把两个项目的 `PGLITE_DIR` 指到同一处。
> 🔴 `PGLITE_DIR=memory://` = 系统临时目录里的一次性数据目录(进程退出即销毁),
> **不是**真内存模式(pglite-rs 0.2.7 没有)。
## 何时用
- MVP 阶段想用 **Rust 全栈**(性能好、部署单二进制、迭代快),同时要保证「稳定后能快速迁 JNPF 标准版」。
- 需要**权限/用户/角色/菜单**这套基础管理能力——这是迁移最硬的一块,本技能已把 `base_*` 表结构与契约钉死。
- 要让**官方 JNPF 前端**跑在 Rust 后端上(面 B)⇒ 见 [`JNPF_COMPAT_SURFACE.md`](JNPF_COMPAT_SURFACE.md)。
- 与 `ssw-jnpf-lite-react` 的取舍:后者 MVP 期就在 Node 栈里写(迁移零摩擦、MVP 慢);本技能把「快」放在 MVP 期
(Rust 单二进制、编译期类型安全),把「换栈」推迟并**锁死到有界范围**。详见 `README.md` 的「选型决策」。
## 模板位置
本技能即脚手架本体——模板随技能目录一起分发,**无需额外拉取**。
🔴 **技能目录 = 仓根**(`SKILL.md` 在仓根,源码 `src/`、`scripts/`、`references/`、`template-boot-jnpf/` 同在仓根),
三处软链 `~/.agents/skills/ssw-jnpf-lite-rust` · `~/.claude/skills/ssw-jnpf-lite-rust` · `~/.workbuddy/skills/ssw-jnpf-lite-rust`
**全部指向同一个仓** ⇒ **改一次仓 = 改一次技能**,不存在「技能副本漂移」。
```
src/backend/ Rust(axum 0.8 :30010, pglite-rs 0.2 进程内 PG)
src/{main,config,db,cipher,envelope,ids,session,auth,permission}.rs
src/{seed,sys,crud,entities,routes,state}.rs ← 5 组 base_* 显式 handler + spec 驱动 CRUD
db/schema.sql 10 张表(base_* 7 + 业务 3)
tests/ 6 个集成测试文件
src/frontend/ React+Vite(:5173, proxy /api→30010)
utils/cipher · api/{request,auth,sys,product,book} · views/{Login,Dashboard,DemoItem★,Product★,Book★,UserManage,RoleManage,OrganizeManage,MenuManage}
scripts/ perm-smoke.sh 面 A 尺子(32 条)—— 测 ssw 契约
perm-smoke-jnpf.sh 面 B 尺子(18 条)—— 测官方 JNPF 形状 ★ 本技能独有
check-module.sh 业务模块 9 接触点静态自检(纯静态,不起后端)
references/ BaseCrudController.java(**非** JNPF 官方类)+ README
template-boot-jnpf/ JNPF 标准栈最小可运行骨架(Java)—— 迁官方时直接拷
```
★ = 业务模块模板(`HOWTO_MODULE.md` 参照实现)。
## 契约红线(改业务必须守住,否则迁移退化成重写)
1. **登录口令加密**:`md5(plain)` → `AES-256-ECB-PKCS7`(key = `md5("EY8WePvjM5GGwQzn")` 的 **32 个 ASCII 字节**)→ hex。
检验向量:`encryptPassword('123456')` ==
`d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b`。
前后端 `cipher.ts` / `cipher.rs` 同一算法,与官方 `DesUtil` 逐字节一致。
🔴 **key 必须是 32 个 ASCII 字节(不是 16 字节原始摘要)** ⇒ AES-256,不是 AES-128。
2. **统一返回** `ActionResult{code,msg,data}`,成功 `200`;**业务失败也是 HTTP 200**(看 body 的 `code`)。
未知路由保留 **HTTP 404**(body 仍是信封形状)。
🔴 **鉴权失败也是 HTTP 200**:`600` 未登录 / `403` 无菜单权限。
3. **端点命名** `/api/ssw/{appCode}/{Entity}/{List|Save|Delete}`(ssw 约定,非官方 visualdev 路径)。
官方前端要跑 ⇒ 走**面 B** 的官方形状路径,**不要**改面 A 的路径。
4. **实体列 `f_` 前缀**;主键 `f_id VARCHAR(50)`(36 位 UUID v4 装得下)。
`f_tenant_id / f_last_modify_* / f_delete_time / f_delete_user_id` 属 `SuperEntity` **可选增强层,非强制**——MVP 不必补。
5. **前端模型用去前缀名**(`title` 非 `fTitle`);JSON 键名 = 列名去 `f_ 前缀后 camelCase。
6. **numeric 列必须序列化成 JSON 字符串**(`"9.90"`,不是 `9.9`)⇒ 在 SQL 投影里就 `f_price::text AS price`。
`int` 列(`f_delete_mark` / `f_stock` / `f_is_administrator`)**保持数字**。
7. **权限表照官方 `base_*` 抄,别自创**;字段名有两个官方陷阱**故意不修正**:
- `base_role_relation` 里用户 id 存在 **`f_object_id`**(配 `f_object_type='user'`),不是 `f_user_id`;
- 组织/岗位关系在**另一张表** `base_user_relation`,那里才有 `f_user_id`。
8. **授权写接口 `objectType` 必须小写 `'role'`**,`module` 传**一维数组** `['m1','m2',…]`
(半选节点合进同一数组,对齐官方 `MenuAuth.vue`)。官方对大小写错误是**静默忽略**(返 200 但一行不写)。
官方 body 是本仓的**超集**(多 `button`/`column`/`resource`/`form`/`systemIds`)⇒ 本仓**照单全收**。
9. **权限是四源合并**:用户直授 + 角色 + 组织 + 岗位;只查 `role` 会漏授权。**管理员短路在查 SQL 之前**。
10. **菜单 `url_address` == 前端 `Route path`(去前导斜杠)== spec 的 `module_key`**,三处一字不差。
不一致的后果是**静默放行**(未映射到菜单就放行)。
11. 🔴 **同一文件的多个 Edit 必须串行**(并行 Edit = last-writer-wins 静默覆盖);改完**必须 grep 复核**。
## 两把尺子(**都要跑**)
| | `scripts/perm-smoke.sh` | `scripts/perm-smoke-jnpf.sh` |
|---|---|---|
| 测的面 | **面 A**(ssw 契约) | **面 B**(官方 JNPF 形状) |
| 判别 | 无特殊头 | 请求头带 `Vue-Version: 3` |
| 断言数 | **32** | **18** |
| 退出码 | 0 全绿 / 1 有失败 / 2 前置错误 | 0 全绿 / 1 有失败或未全覆盖 / 2 前置错误 |
```bash
bash scripts/perm-smoke.sh # 面 A:32 条 —— 「没把原契约改坏」
bash scripts/perm-smoke-jnpf.sh # 面 B:18 条 —— 打印「面 B 覆盖 N/18」(**当前 N=18,已全绿**)
bash scripts/check-module.sh # 业务模块 9 接触点静态自检(纯静态,不起后端)
```
- **面 B 尺子不假装全过**:未落地的能力记 **SKIP**(不算 PASS),结尾打印 **「面 B 覆盖 N/18」** ⇒ 它是一把**诚实量进度**的尺子。
✅ **2026-10-26 当前状态:面 B 已落地 ⇒ `PASS=18 FAIL=0 SKIP=0`(覆盖 18/18)**;
`SKIP` 机制**保留**(后续新增端点未落地时仍如实记 SKIP)。
- **判读原则**:**返回了数据不能证明权限生效**(管理员短路 / 菜单没映射 / 缓存没清 / 异常降级放行,四条路径全是"放行")。
「菜单收窄 + 403 拦截」才是有说服力的信号。
- **不依赖 node**:cipher 用后端 `--enc` 自证(`./target/release/ssw-jnpf-lite-rust --enc 123456`);JSON 取值 jq 优先、python3 兜底。
## 文档导航
| 文档 | 何时读 |
|---|---|
| `HOWTO_MODULE.md` | **开发时**:加业务模块的操作手册(9 个接触点 + 逐文件改法 + 验证) |
| `README.md` | **开发时**:选型理由、运行、目录、已知限制 |
| `PERMISSION.md` | 涉及**权限/角色/授权**时:表结构、四源合并、码表、两个官方陷阱 |
| `MIGRATION.md` | **迁移期**:Rust ⇄ NestJS ⇄ 官方 Java 三方映射、import 速查、数据 ETL、口令换算 |
| `JNPF_SOURCE_AUDIT.md` | **迁移期/存疑时**:官方源码逐行核对报告(标 `文件:行号`),**开发 MVP 不必读** |
| `JNPF_COMPAT_SURFACE.md` | **做面 B 时**:官方形状的端点/响应/码表规格 + 落地顺序 S1–S6 |
| `references/BaseCrudController.java` | **迁移期**:通用 CRUD 骨架(业务 Controller 继承它可省 5 样板);**非 JNPF 官方类** |
| `template-boot-jnpf/` | **迁移期**:JNPF 标准栈最小可运行骨架(Java);包命名 `ssw.{appCode}.xx.xx`、master + ssw-{appCode}Ds 双数据源、`@DS` 切库;用法见该目录 README |
| `docs/contract.md` | **开发时**:契约唯一真源(端点 / 返回形状 / 数据模型),与本文冲突以契约为准 |
| `docs/runbook.md` | **运维时**:怎么起 / 怎么冒烟 / 常见故障 |
| `docs/decisions.md` | **存疑时**:实施期 88 条裁决(什么—为什么—代价) |
| `docs/known-limitations.md` | **验收前**:分支级已知限制(被接受 / 挂起) |
| `CLAUDE.md` / `HANDOFF.md` | **agent 协作**:项目级红线 / 踩坑 / 端点全表 · 交接文档 |
## 校验
- **cipher**:`src/backend/src/cipher.rs` 顶部注释含检验向量;`./target/release/ssw-jnpf-lite-rust --enc 123456` 一行复现。
- **加新模块的「9 接触点」静态自检**:`bash scripts/check-module.sh`(无参查全部三个模块)
或 `bash scripts/check-module.sh books Book`(单模块)。改完模块立刻跑,能在 perm-smoke 之前发现漏改。
- **端到端权限闭环**:`bash scripts/perm-smoke.sh`(32 条)。
覆盖:未登录 600 · 加密登录 · 菜单树 · 建用户 · **重复账号返 400 而非 500** · 写授权(一维/二维兼容)·
非管理员菜单收窄 · 非管理员访问系统管理返 403 · 已授权业务返 200 · 未知路由 404 ·
**三个业务模块全链路**(新建 / 36 位 UUID / numeric 金额往返 / 无 token 600 / 未授权 403)。
- **官方形状达标**:`bash scripts/perm-smoke-jnpf.sh`(18 条)⇒ 「面 B 覆盖 N/18」(**当前 18/18**)。
- **单测**:`cargo test`(195 条)。
- **三入口退出码约定一致**:`run.sh` / `check-module.sh` / `perm-smoke*.sh` 都是 `0` 成功 / `1` 运行期失败 / `2` 用法错。
各脚本支持 `-h`/`--help`。
+149
View File
@@ -0,0 +1,149 @@
# ssw-jnpf-lite-rust
**JNPF 兼容契约的 Rust 实现** —— 单二进制、零外部服务(进程内原生 PostgreSQL)。
它的存在意义只有一条:**让「用 Rust 写业务」和「迁回官方 JNPF(Java)」之间是机械翻译,而不是重写。**
为此本仓的**数据模型(`base_*` 表名/列名/语义)与 HTTP 契约**从第一天起就锁死成官方 JNPF 的形状。
本仓是**双面后端**:**同一进程**同时提供
**面 A**(ssw/react 契约,27 条路由,冻结)与 **面 B**(官方 JNPF 契约,5 条路由 + 2 条共用路由按 `Vue-Version: 3` 分流),
共用同一套 `base_*` 表 / cipher / seed,但**权限判据不同**(面 A 按菜单路径 / 面 B 按 `f_en_code` 点权限)。
⇒ 既是「Rust ⇒ 官方 JNPF」的**可移植性验证床**,也是「官方 JNPF / React 版 ⇒ 打到本框架跑」的**对照靶场**。
- 📘 **契约唯一真源**:[`docs/contract.md`](contract.md) —— 与本文件冲突时以契约为准。
- 🧭 **agent 指引**:[`CLAUDE.md`](../CLAUDE.md)(红线 / 踩坑 / 端点全表)· [`HANDOFF.md`](../HANDOFF.md)(交接)。
- 🛠 **怎么起 / 怎么冒烟 / 常见故障**:[`docs/runbook.md`](runbook.md)。
- 🧾 **实施期裁决(88 条「什么—为什么—代价」)**:[`docs/decisions.md`](decisions.md)
· **分支级已知限制**:[`docs/known-limitations.md`](known-limitations.md)。
---
## 快速开始
```bash
# 一次性:装依赖(cargo fetch + npm install)+ 构建(cargo build --release + vite build)
bash run.sh install
bash run.sh build
# 日常:后台起后端(30010) + 前端(5173),日志在 .logs/,PID 在 .run/
bash run.sh dev
# 前端 http://127.0.0.1:5173 后端 http://127.0.0.1:30010
# 账号 admin / 123456
# (**后端与前端都就绪**才算成功;任一没就绪 ⇒ 退出码 1 并打印对应日志尾部)
bash run.sh stop # 停(幂等)
bash run.sh logs # 看日志尾部
```
| 端口 | 谁 | 说明 |
|---|---|---|
| `30010` | 后端(Rust) | **硬约定**:`run.sh` 的端口不许改 —— `PORT` ≠ 30010 时 `run.sh dev` / `run.sh backend` 报错退出 2(要换端口请**直接跑二进制**)。**后端二进制本身**吃 `PORT`(非法值回落 30010)。默认**只监听 `127.0.0.1`**;`BIND_ADDR=0.0.0.0` 才对外暴露 |
| `5173` | 前端(vite dev) | `strictPort: true` ⇒ 端口被占直接报错,不自动换端口 |
---
## 目录
```
ssw-jnpf-lite-rust/
├── Cargo.toml # cargo workspace 根(成员 = src/backend)+ release profile
├── run.sh # install / build / dev / backend / frontend / stop / logs
├── .env.example # PORT / BIND_ADDR / PGLITE_DIR(PGLITE_DIR 只能写绝对路径或 memory://)
├── src/backend/ # Rust 后端(axum 0.8 + pglite-rs 0.2,10 张表,32 条路由 = 面 A 27 + 面 B 5)
├── src/frontend/ # react 技能前端**逐字复制**(只改 vite 代理端口 30000 → 30010)
├── scripts/perm-smoke.sh # 权限闭环冒烟(32 条断言,零 node 依赖)—— 面 A 尺子
├── scripts/perm-smoke-jnpf.sh # 官方 JNPF 形状冒烟(18 条断言)—— 面 B 尺子(**已全绿 18/18**)
├── scripts/check-module.sh # 业务模块 9 接触点静态自检(纯静态,不起后端)
└── docs/ # contract.md(契约)· runbook.md(运维)· decisions.md(裁决)· known-limitations.md(已知限制)
# JNPF_SOURCE_AUDIT.md(官方源码逐行核对)· JNPF_COMPAT_SURFACE.md(面 B 规格)· MIGRATION.md(迁移指南)· ddl/
```
---
## 它做了什么(v1 = 全量契约对齐)
- **登录 / `CurrentUser`**:`POST /api/oauth/Login`(form-urlencoded,密文 hex)⇒ `{token, expiresIn:7200, tokenTypeName:'bearer'}`;
`GET /api/oauth/CurrentUser` ⇒ `{userInfo, menuList}`。
- **5 组 `base_*` 管理 CRUD**:用户 / 角色 / 机构 / 菜单 / 授权。
- **统一授权**:`PUT /api/permission/Authority/Data/{objectId}`(body `{objectType:'role', module:[...]}`,**小写 + 一维数组**)。
- **四源权限合并**:用户直授 + 角色 + 组织 + 岗位;**管理员在任何 SQL 之前短路放行**;**菜单未映射 ⇒ 放行**。
- **两段式种子**:`ensure_base`(每次启动补内置角色/菜单/授权)+ `first_seed`(仅首次建 `admin/123456`)。
- **3 个业务模块**(spec 驱动 CRUD 引擎):`demo/DemoItem` · `shop/Product` · `books/Book`。
### 契约红线(摘要,完整版见 `CLAUDE.md`)
1. **业务失败一律 HTTP 200 + `{code,msg,data}`**;成败只看 body 的 `code`。
唯一例外:**未知路由 = HTTP 404**(body 仍是信封)。鉴权失败也是 200(`600` 未登录 / `403` 无菜单权限)。
2. **`base_*` 表名/列名逐字对齐官方 JNPF DDL**(含两个「故意不修正」的陷阱,见 `CLAUDE.md`)。
3. **numeric 列必须是 JSON 字符串**(`"9.90"`,不是 `9.9`);int 列保持数字。
4. **口令不得外泄**:库里存 `md5(明文)`,对外响应手工挑字段(用户列表去掉 `password`)。
5. **schema DDL 绝不可从 HTTP 下载**。
---
## 验收门
| 门 | 命令 | 通过标准 |
|---|---|---|
| ① 编译 | `cargo build --release` | 0 error **0 warning** |
| ② 单测 | `cargo test` | 全绿(当前 **195 passed / 0 failed**) |
| ③ 冒烟 | `bash scripts/perm-smoke.sh` | **PASS=32 FAIL=0**(需后端已起在 `:30010`) |
| ③' 冒烟(面 B) | `bash scripts/perm-smoke-jnpf.sh` | **PASS=18 FAIL=0 SKIP=0**(**已达标**) |
| ④ 前端手验 | `bash run.sh dev` | `http://127.0.0.1:5173` → `admin/123456` 登录 → 菜单树正确 → 5 个管理页可增删改 → DemoItem/Product/Book 三页可用 → 退出再登录 |
外加:`bash scripts/check-module.sh`(9 接触点静态自检)—— 加业务模块后立刻跑的前置闸门。
### 第二把尺子(面 B:官方 JNPF 形状)
```bash
bash scripts/perm-smoke-jnpf.sh # 18 条断言,打印「面 B 覆盖 N/18」
```
**面 B = 官方 JNPF 契约面**(官方形状的端点 / 响应 / 码表),规格见 `../JNPF_COMPAT_SURFACE.md`。
✅ **已落地**(`src/backend/src/jnpf.rs`,S1–S6 全完成)⇒ 当前报 **`PASS=18 FAIL=0 SKIP=0`(面 B 覆盖 18/18)**。
面 B 的判别头是 **`Vue-Version: 3`**(官方前端必发,本仓前端**唯一不发**的一头 ⇒ 零歧义)。
面 A 27 条路由**冻结**、面 B 5 条新增 ⇒ **同一进程**同时提供两套契约。
> 本机 curl 走系统代理 ⇒ 打 localhost **必须**加 `--noproxy '*'`。
---
## 三个参照物(各司其职,别混)
| 参照物 | 地位 |
|---|---|
| 官方 JNPF 源码 + DDL(`~/Desktop/workspace/jnpf/`) | **数据模型真源**(`base_*` 表名/列名) |
| `ssw-jnpf-lite-react` 技能(`~/Desktop/workspace/skills/ssw-jnpf-lite-react/`) | **行为真源**(NestJS 版把契约跑起来了);本仓前端是它的**逐字复制** |
| `tdc-rs` 兄弟项目(`~/Desktop/workspace/tdc-rs/`) | **只抄工程手法**;不共享代码 / 端口 / 数据目录 |
---
## 已知限制(分支级)
- **面 B 的 10 条已知偏差**(B1–B10,逐条见 `../JNPF_COMPAT_SURFACE.md` §8 与 `docs/known-limitations.md` §H):
授权读 `list` 返空数组 · `sysConfigInfo` 返 `{}` · `currentSystemId` 固定 ·
**无按钮/列/表单/数据级权限** · 三个业务菜单的 `f_en_code` 是自拟占位 ·
`permissionList` 粒度 = 每菜单一条(`modelId` = 菜单 id)· `Organize/AsyncList` 未分页。
- **口令存储缺官方 `secretkey` 一步**:本仓存 `md5(明文)`,官方存 `md5(md5(明文)+secretkey)`。
迁官方时**一次性换算**即可,**不需要明文**(见 `../MIGRATION.md` §7)。
- **两套权限判据并存**:面 A 按菜单路径(`f_url_address`)、面 B 按点权限编码(`f_en_code`)。
⇒ 同一用户可能**面 A 通、面 B 拒**(这是设计,不是 bug);种子菜单已补 `f_en_code`(8 条),
业务菜单的 `f_en_code` 仍是自拟值,迁官方前须换成官方真实编码。
- **release 二进制没有 catch-all 的自动化覆盖**:触发 panic 的端点是 `#[cfg(test)]` 专属;
catch-all 中间件代码在测试构建与 release 构建里逐字相同,且 release profile **无** `panic = "abort"` ⇒ 行为等价。
- **`Path<String>` 遇畸形百分号编码** ⇒ **实测 axum 0.8.9 接受该转义**:`PUT /api/permission/Authority/Data/%zz`
返回 **HTTP 200 + `{"code":600,"msg":"未登录","data":null}`**(信封,正常)⇒ **不存在**「返非信封 400」这种破口。
- **token 的真实寿命 = 后端进程寿命**(`session.rs` 是内存 token 表、**没有 TTL**):
登录响应里的 `expiresIn: 7200` 是**契约 §6.1 逐字定死**的字面量、**不会被强制执行**
(进程不重启就永不过期);契约未覆盖 TTL ⇒ 不改。
- **冒烟脚本每次跑会往库里留一行** `shop_product` + 一行 `book_shop_book` + 一行 `smoke_user`(react 同款行为,契约未要求清理)。
- 冒烟脚本在「重复账号 curl 超时」场景下 stderr 会多一行 `cat: … No such file`(观感,判据不受影响)。
- 冒烟脚本在「空 body 前置失败」时 jq / python 两条路径的前置提示文案不同(退出码都是 2)。
---
## 技术栈
Rust 2021 · axum 0.8 · tokio · pglite-rs 0.2(进程内原生 PostgreSQL,零服务/零 Docker/零 WASM)·
aes 0.8 + ecb 0.1 + md-5 0.10 · React 18 + Vite 5(逐字复用)
+1 -1
View File
@@ -4,7 +4,7 @@
> 与 `HANDOFF.md` 冲突时,以本文件为准;与本文件冲突的**计划文字**由控制者裁决并记入 ledger。
>
> 🔴 **本文件 = 面 A(ssw/react 契约)的规格,冻结不动。**
> 面 B(官方 JNPF 契约面)的规格在 **[`JNPF_COMPAT_SURFACE.md`](JNPF_COMPAT_SURFACE.md)**(已落地 18/18),
> 面 B(官方 JNPF 契约面)的规格在 **[`JNPF_COMPAT_SURFACE.md`](../JNPF_COMPAT_SURFACE.md)**(已落地 18/18),
> 两面共用同一套 `base_*` 表 / cipher / seed,但**权限判据不同**(面 A 按菜单路径、面 B 按 `f_en_code`)。
---
+2 -2
View File
@@ -76,8 +76,8 @@
## H. 官方 JNPF 对齐(面 B)—— 2026-10-26
> 本节是**「把官方 JNPF 前端跑进本仓」**这条线的已知限制。三份配套文档:
> 官方源码核对 [`JNPF_SOURCE_AUDIT.md`](JNPF_SOURCE_AUDIT.md) · 面 B 规格
> [`JNPF_COMPAT_SURFACE.md`](JNPF_COMPAT_SURFACE.md) · 迁移指南 [`MIGRATION.md`](MIGRATION.md)。
> 官方源码核对 [`JNPF_SOURCE_AUDIT.md`](../JNPF_SOURCE_AUDIT.md) · 面 B 规格
> [`JNPF_COMPAT_SURFACE.md`](../JNPF_COMPAT_SURFACE.md) · 迁移指南 [`MIGRATION.md`](../MIGRATION.md)。
| # | 限制 | 出处 | 为什么接受 / 代价 |
|---|---|---|---|
+332
View File
@@ -0,0 +1,332 @@
package ssw.common.controller;
import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
import com.baomidou.mybatisplus.core.metadata.IPage;
import io.swagger.v3.oas.annotations.Operation;
import jakarta.servlet.http.HttpServletRequest;
import jnpf.base.ActionResult;
import jnpf.base.Pagination;
import jnpf.base.entity.SuperExtendEntity;
import jnpf.base.service.SuperService;
import jnpf.base.vo.PaginationVO;
import jnpf.util.JsonUtil;
import jnpf.util.RandomUtil;
import jnpf.util.UserProvider;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import java.util.Collections;
import java.util.Date;
import java.util.List;
import java.util.Map;
/**
* ssw 通用 CRUD 控制器骨架 — 业务 Controller 继承它即可省去 List/Page/Detail/Create/Update/Delete 样板。
*
* 子类只声明「关键字匹配哪些列」「支持哪些过滤参数」,
* 需要时覆写 {@link #beforeSave} 做业务校验。
*
* 三条硬约定:
* <ul>
* <li><b>软删除</b>:全局逻辑删除没开(yml 里 logic-delete-field 是注释掉的),
* 删除走手写的 f_delete_mark=1,列表查询一律带 {@code f_delete_mark IS NULL}。
* DDL 里的唯一索引也是按这个条件建的偏索引,两边必须对齐。</li>
* <li><b>基类不用 Lambda 条件构造器</b>:泛型擦除后拿不到具体实体的方法引用,
* 统一用字符串列名写 QueryWrapper。</li>
* <li><b>租户隔离</b>:一套实例可承载多个租户,
* 业务表统一带 f_tenant_id。子类通过 {@link #tenantColumn()} 声明租户列名,
* 基类自动接管 tenantId 过滤——子类不要自觉。</li>
* </ul>
*
* 审计留痕:{@link #audit} 钩子默认 noop。子类按需 override 连到自家审计服务
* (日志表 / MQ / 第三方审计平台)即可,方法签名见 {@code audit(action, bizId, target)}。
*
* @param <T> 实体类型(业务扩展位用 SuperExtendEntity<String>)
*/
public abstract class BaseCrudController<T extends SuperExtendEntity<String>> {
/**
* 菜单权限检查钩子。基类不依赖任何权限框架 — 子类按需覆盖({@code @PreAuthorize} /
* Sa-Token {@code @SaCheckPermission} / 调自家权限服务均可)。
* 默认空实现(不检查权限),适合 demo / 内部工具。
*/
protected void requireMenuPermission() {
}
/**
* 数据范围过滤钩子。基类不依赖具体的数据范围解析器 — 子类按需覆盖往 wrapper 里拼 SQL。
* 默认空实现(不过滤数据范围),适合单租户 / demo。
*/
protected void applyDataScope(QueryWrapper<T> wrapper, HttpServletRequest request) {
}
/** 逻辑未删除条件,所有查询都要带 */
protected static final String ALIVE = "(f_delete_mark IS NULL OR f_delete_mark = 0)";
// ------------------------------------------------------------------ 子类扩展点
protected abstract SuperService<T> service();
/** 新建实体实例(泛型擦除拿不到构造器,交给子类) */
protected abstract T newEntity();
/** 关键字模糊匹配的列,返回空数组表示不支持关键字搜索 */
protected String[] keywordColumns() {
return new String[]{"f_name"};
}
/** 精确过滤:请求参数名 -> 数据库列名 */
protected Map<String, String> filterColumns() {
return Collections.emptyMap();
}
/**
* 该表的「租户」列名,返回 null 表示本表不按租户隔离
* (如实例级全局配置)。返回非 null 时,请求参数 tenantId 自动生效。
*/
protected String tenantColumn() {
return "f_tenant_id";
}
/** 默认排序列,倒序 */
protected String defaultOrderColumn() {
return "f_creator_time";
}
/**
* 落库前的钩子,可做业务校验/补默认值。抛异常即中断并返回 fail。
*
* @param entity 待保存实体
* @param create true=新增,false=修改
*/
protected void beforeSave(T entity, boolean create) {
}
/** 删除前的钩子,可做引用检查 */
protected void beforeDelete(T entity) {
}
// ------------------------------------------------------------------ 审计留痕扩展点(可选实现)
/**
* 本控制器对应的业务类型。默认由实体类名推导;返回 {@code null} 表示不留痕。
*/
protected String auditBizType() {
String name = newEntity().getClass().getSimpleName().replaceAll("Entity$", "");
return name.replaceAll("([a-z0-9])([A-Z])", "$1_$2").toUpperCase();
}
/** 留痕时展示的对象描述 */
protected String auditTarget(T entity) {
if (entity == null) {
return null;
}
for (String getter : new String[]{"getCode", "getName", "getTaskNo", "getOrderCode",
"getDemandCode", "getResourceName", "getProductName", "getTitle", "getFullName"}) {
try {
Object v = entity.getClass().getMethod(getter).invoke(entity);
if (v != null && !v.toString().isBlank()) {
return v.toString();
}
} catch (Exception ignore) {
// 该实体没有这个字段,继续试下一个
}
}
return entity.getId();
}
/**
* 写一条业务留痕。子类要启用审计时,覆盖此方法连到自家审计服务;
* 不覆盖则 {@link #create} / {@link #update} / {@link #delete} 三处 audit 调用静默 noop。
*
* 替换为自家实现时可参考方法签名:bizId 实体主键 / action CREATE|UPDATE|DELETE / target 业务标识。
*/
protected void audit(String action, String bizId, String target) {
// 默认 noop;子类按需 override
}
/** 写一条带结果与明细的业务留痕;默认 noop */
protected void audit(String action, String bizId, String target,
String result, String failReason, String detail) {
// 默认 noop;子类按需 override
}
// ------------------------------------------------------------------ 通用接口
@GetMapping
@Operation(summary = "分页列表", description = "支持 keyword 模糊搜索、tenantId 过滤与子类声明的精确过滤参数")
public ActionResult<?> list(Pagination pagination, HttpServletRequest request) {
requireMenuPermission();
QueryWrapper<T> wrapper = buildWrapper(request);
long current = pagination.getCurrentPage() <= 0 ? 1 : pagination.getCurrentPage();
long size = pagination.getPageSize() <= 0 ? 20 : Math.min(pagination.getPageSize(), 500);
com.baomidou.mybatisplus.extension.plugins.pagination.Page<T> page =
new com.baomidou.mybatisplus.extension.plugins.pagination.Page<>(current, size);
IPage<T> result = service().page(page, wrapper);
List<T> records = pagination.setData(result.getRecords(), result.getTotal());
return ActionResult.page(records, JsonUtil.getJsonToBean(pagination, PaginationVO.class));
}
@GetMapping("/All")
@Operation(summary = "不分页全量列表", description = "用于下拉选择等场景,最多返回 1000 条")
public ActionResult<List<T>> all(HttpServletRequest request) {
requireMenuPermission();
QueryWrapper<T> wrapper = buildWrapper(request);
wrapper.last("limit 1000");
return ActionResult.success(service().list(wrapper));
}
@GetMapping("/{id}")
@Operation(summary = "详情")
public ActionResult<T> detail(@PathVariable("id") String id) {
requireMenuPermission();
T entity = getAlive(id);
if (entity == null) {
return ActionResult.fail("记录不存在或已删除");
}
return ActionResult.success(entity);
}
@PostMapping
@Operation(summary = "新增")
public ActionResult<String> create(@RequestBody T entity) {
requireMenuPermission();
entity.setId(RandomUtil.uuId());
entity.setDeleteMark(null);
beforeSave(entity, true);
service().save(entity);
audit("CREATE", entity.getId(), auditTarget(entity));
return ActionResult.success("新增成功", entity.getId());
}
@PutMapping("/{id}")
@Operation(summary = "修改", description = "只覆盖请求体里出现的字段,未传字段保持原值")
public ActionResult<String> update(@PathVariable("id") String id, @RequestBody T entity) {
requireMenuPermission();
T exists = getAlive(id);
if (exists == null) {
return ActionResult.fail("记录不存在或已删除");
}
entity.setId(id);
// 系统列不允许从请求体覆盖
entity.setCreatorTime(null);
entity.setCreatorUserId(null);
entity.setDeleteMark(null);
entity.setDeleteTime(null);
entity.setDeleteUserId(null);
beforeSave(entity, false);
service().updateById(entity);
// 用改前的实体取 target:改后的对象只带请求体里出现的字段,编号往往是 null
audit("UPDATE", id, auditTarget(exists));
return ActionResult.success("修改成功", id);
}
@DeleteMapping("/{id}")
@Operation(summary = "删除", description = "逻辑删除,置 f_delete_mark=1")
public ActionResult<String> delete(@PathVariable("id") String id) {
requireMenuPermission();
T exists = getAlive(id);
if (exists == null) {
return ActionResult.fail("记录不存在或已删除");
}
beforeDelete(exists);
T update = newEntity();
update.setId(id);
update.setDeleteMark(1);
update.setDeleteTime(new Date());
update.setDeleteUserId(safeUserId());
service().updateById(update);
audit("DELETE", id, auditTarget(exists));
return ActionResult.success("删除成功", id);
}
// ------------------------------------------------------------------ 内部工具
protected QueryWrapper<T> buildWrapper(HttpServletRequest request) {
QueryWrapper<T> wrapper = new QueryWrapper<>();
wrapper.apply(ALIVE);
String tenantColumn = tenantColumn();
if (tenantColumn != null) {
String tenantId = param(request, "tenantId");
if (tenantId != null) {
wrapper.eq(tenantColumn, tenantId);
}
}
filterColumns().forEach((param, column) -> {
String value = param(request, param);
if (value != null) {
wrapper.eq(column, value);
}
});
String keyword = param(request, "keyword");
String[] columns = keywordColumns();
if (keyword != null && columns.length > 0) {
wrapper.and(w -> {
for (int i = 0; i < columns.length; i++) {
if (i == 0) {
w.like(columns[i], keyword);
} else {
w.or().like(columns[i], keyword);
}
}
});
}
applyDataScope(wrapper, request);
wrapper.orderByDesc(defaultOrderColumn());
return wrapper;
}
/** 取请求参数,空串统一归一成 null */
protected String param(HttpServletRequest request, String name) {
if (request == null) {
return null;
}
String value = request.getParameter(name);
if (value == null) {
return null;
}
value = value.trim();
return value.isEmpty() ? null : value;
}
/** 按主键取未删除的记录 */
protected T getAlive(String id) {
QueryWrapper<T> wrapper = new QueryWrapper<>();
wrapper.eq("f_id", id).apply(ALIVE);
return service().getOne(wrapper, false);
}
/** 判断某列值是否已被占用(排除自身),用于编码唯一性校验 */
protected boolean existsBy(String column, String value, String excludeId) {
QueryWrapper<T> wrapper = new QueryWrapper<>();
wrapper.eq(column, value).apply(ALIVE);
if (excludeId != null && !excludeId.isEmpty()) {
wrapper.ne("f_id", excludeId);
}
return service().count(wrapper) > 0;
}
/** 必填校验小工具,减少 Controller 里成片的 if-blank */
protected void requireText(String value, String message) {
if (value == null || value.isBlank()) {
throw new IllegalArgumentException(message);
}
}
protected String safeUserId() {
try {
return UserProvider.getLoginUserId();
} catch (Exception e) {
return null;
}
}
}
+49
View File
@@ -0,0 +1,49 @@
# references/
**用途**:迁 JNPF 时可复用的**通用基础设施源码** — 这些类不在 jnpf-common-all 里,
但 ssw-jnpf-lite-react 的实战用过并验证可工作。稳定期迁业务模块时按需拷贝。
> 自包含:**不**依赖任何本技能外的 `ssw-*` 类。BaseCrudController 不绑死任何权限框架 / 数据范围
> 解析器 / 审计服务 — 这些由子类按需 override 提供。
## 当前收录
| 类 | 用途 |
|---|---|
| `BaseCrudController.java` | 通用 CRUD 骨架(List / Page / Detail / Create / Update / Delete + 关键字 / 过滤 / 数据范围 / 租户 / 可选审计)。业务 Controller `extends BaseCrudController<T>` 即可省去样板。**不是 JNPF 官方类。** |
## 使用方式
迁某个业务模块到 JNPF 时:
1. 把 `BaseCrudController.java` 拷到目标工程的 `ssw.common.controller` 包(**推荐放共享层**,让多个 `-controller` 子模块复用)
2. 业务 Controller `extends BaseCrudController<T>`,覆写方法:
- `service()`、`newEntity()`(必选)
- `keywordColumns()`、`filterColumns()`(可选)
- `beforeSave(entity, create)`(可选,业务校验)
- `requireMenuPermission()`、`applyDataScope()`(可选;权限 / 数据范围由子类按需实现,本基类不绑死任何权限框架)
3. 配套 import:`import jnpf.base.{ActionResult, Pagination, vo.PaginationVO}`;
`import jnpf.util.{RandomUtil, UserProvider, JsonUtil}`。
> 包命名约定见 `../template-boot-jnpf/README.md`「包命名约定」节 — `BaseCrudController` 必须放 `ssw.common.controller`,
> 业务 Controller 放 `ssw.{yourAppCode}.controller`。
## 默认 noop 的扩展钩子
| 钩子 | 默认行为 | 何时 override |
|------|----------|---------------|
| `requireMenuPermission()` | 空实现(不检查) | 需要菜单级权限时(自注 `@PreAuthorize` / Sa-Token `@SaCheckPermission` / 调 jnpf 自带守卫均可) |
| `applyDataScope(wrapper, request)` | 空实现(不过滤) | 需要按用户数据范围过滤时(往 wrapper 拼 SQL) |
| `audit(action, bizId, target)` | 空实现(不记) | 需要审计日志时(写日志表 / 调 MQ / HTTP 第三方) |
> **重要**:本基类**不**自带任何权限 / 数据范围 / 审计服务 — 全部默认 noop,按需覆盖。
> 不要期望拷过来就有这些能力。
## 为什么不放在主目录 / 不集成进 jnpf-common-all
- 这些类属于**业务脚手架**,不是 JNPF 官方提供的公共组件;
- 形态与具体业务耦合(如 `auditBizType()` 默认从实体类名推导);
- JNPF 官方**只承诺**提供底层基元(SuperEntity/SuperMapper/SuperService/SuperServiceImpl/ActionResult),
不提供这种「一键 CRUD」基类。
- 因此稳定期迁每个业务模块都要带一份 `BaseCrudController.java` 过去,本目录即「免去到处找」的
内置副本。
+1 -1
View File
@@ -343,7 +343,7 @@ done
# -------- 全局红线(与具体模块无关,但一样会让闸门失真)--------
#
# 🔴 **面 A / 面 B 的判别头是 `Vue-Version: 3`**(见 docs/JNPF_COMPAT_SURFACE.md §2.2):
# 🔴 **面 A / 面 B 的判别头是 `Vue-Version: 3`**(见 JNPF_COMPAT_SURFACE.md §2.2):
# 官方 JNPF 前端**必带** `Jnpf-Origin: pc` / `App-Code` / `Vue-Version: 3` 三个头,
# 而本仓前端**只带前两个**(`App-Code: sswflow` + `Jnpf-Origin: pc`,与官方同款)
# ⇒ 三个头里**只有 `Vue-Version` 是本仓前端唯一不发的** ⇒ 判别只能用它。
+1 -1
View File
@@ -13,7 +13,7 @@
# 前置:后端已启动,且处于**初始种子状态**(admin / 123456)。
# 退出码:0 = 全绿(面 B 覆盖 18/18) / 1 = 有 FAIL 或有 SKIP(未全覆盖) / 2 = 前置错误
#
# 🔴 **面 B 的判别规则**(见 docs/JNPF_COMPAT_SURFACE.md §2.2):
# 🔴 **面 B 的判别规则**(见 JNPF_COMPAT_SURFACE.md §2.2):
# 请求头带 `Vue-Version: 3` ⇒ 走官方形状;否则走面 A。
# 官方前端**必然**带这三个头(jnpf-web-apps-main/src/api/request.ts:109-112),
# 但本仓 React 前端**也发** `App-Code` 与 `Jnpf-Origin: pc`(同款),
+2 -2
View File
@@ -163,7 +163,7 @@ pub async fn login_handler(State(state): State<AppState>, body: Bytes) -> Json<A
/// 🔴 `userName` = **账号**(不是 `realName`);`isAdministrator` 是 **JSON 布尔**。
///
/// 🔴 **面 B 分流**:请求头带 `Vue-Version: 3` ⇒ 走**官方 `PcUserVO` 形状**
/// (`docs/JNPF_COMPAT_SURFACE.md` §3.1)⇒ **面 A 的形状一个字都不动**。
/// (`JNPF_COMPAT_SURFACE.md` §3.1)⇒ **面 A 的形状一个字都不动**。
pub async fn current_user(state: &AppState, headers: HeaderMap) -> Json<ActionResult> {
// 🔴 判别头 = `Vue-Version: 3`(本仓前端唯一不发的官方头 ⇒ 零歧义)。
if crate::jnpf::is_jnpf(&headers) {
@@ -204,7 +204,7 @@ pub async fn require_login(
///
/// 🔴 **面 B 必须返 `602` 而不是 `600`** —— 官方前端 `request.ts:78-80` 只对
/// `601`/`602`(`TOKEN_ERROR` / `TOKEN_LOGGED` / `TOKEN_TIMEOUT`)清 token
/// ⇒ 只返 `600` 会让页面**卡住不跳登录**(`docs/JNPF_COMPAT_SURFACE.md` §4)。
/// ⇒ 只返 `600` 会让页面**卡住不跳登录**(`JNPF_COMPAT_SURFACE.md` §4)。
///
/// 🔴 失败也**恒 HTTP 200**(信封里的 `code`),不是 HTTP 401。
pub async fn require_login_jnpf(
+4 -4
View File
@@ -1,6 +1,6 @@
//! jnpf —— **面 B**(官方 JNPF 契约面)的端点与响应形状。
//!
//! 规格:`docs/JNPF_COMPAT_SURFACE.md`(§2.2 判别头 / §3 端点 / §4 码表 / §8 已知错位)。
//! 规格:`JNPF_COMPAT_SURFACE.md`(§2.2 判别头 / §3 端点 / §4 码表 / §8 已知错位)。
//! 官方真源:`~/Desktop/workspace/jnpf/`(Java 后端 + `jnpf-web-apps-main` 官方前端)。
//!
//! 🔴 **面 A 一个字都不动** —— 本模块只**新增**官方形状的端点;
@@ -63,7 +63,7 @@ const MAX_TREE_DEPTH: usize = 32;
/// 🔴 **这个请求是不是「面 B」** —— 判别头 `Vue-Version: 3`。
///
/// **唯一的全局判别规则**(`docs/JNPF_COMPAT_SURFACE.md` §2.2):
/// **唯一的全局判别规则**(`JNPF_COMPAT_SURFACE.md` §2.2):
/// ```text
/// 请求头含 "Vue-Version: 3" ⇒ 走【面 B】官方形状
/// 否则 ⇒ 走【面 A】ssw 形状
@@ -482,7 +482,7 @@ async fn organize_name_of(db: &Db, id: &str) -> Option<String> {
/// `GET /api/permission/Users` —— 官方 `UserController.java:295` 的形状。
///
/// 🔴 **硬性要求**(`docs/JNPF_COMPAT_SURFACE.md` §3.2):
/// 🔴 **硬性要求**(`JNPF_COMPAT_SURFACE.md` §3.2):
/// 1. `data` 是**对象**(`pagination` + `list`),**不是**裸数组;
/// 2. 列表项**不含** `password` / `secretkey`(投影里根本不选那两列);
/// 3. `pagination.total` = **总条数**;
@@ -694,7 +694,7 @@ pub async fn module_by_system(
///
/// **响应**(官方 `AuthorizeDataReturnVO.java:16-27`)= `{list, ids, all}`。
///
/// 🔴 **面 B v1 降级**(`docs/JNPF_COMPAT_SURFACE.md` §3.6):
/// 🔴 **面 B v1 降级**(`JNPF_COMPAT_SURFACE.md` §3.6):
/// - `list` 恒 `[]` —— 本仓**不实现**官方那套权限树模型;
/// - `all` 返本仓**全部菜单 id**(官方的 `all` **不含**菜单 id)⇒ **已知错位 B1**;
/// - `ids` 语义**正确**(已勾选的菜单 id)。
+1 -1
View File
@@ -192,7 +192,7 @@ pub async fn has_module(db: &Db, user_id: &str, is_admin: i32, module_key: &str)
/// **面 B 的点权限守卫** —— 当前用户能否访问 `f_en_code = en_code` 的菜单。
///
/// 🔴 这是**第二套判据**(面 A 用菜单路径 `f_url_address`;官方用 `f_en_code`),
/// 两者**并存**、互不影响(`docs/JNPF_COMPAT_SURFACE.md` §3.2 / §7 S5)。
/// 两者**并存**、互不影响(`JNPF_COMPAT_SURFACE.md` §3.2 / §7 S5)。
/// 官方形态:`@SaCheckPermission("permission.user")` ⇒ 判「该用户是否持有
/// `f_en_code='permission.user'` 的菜单授权」。
///
+1 -1
View File
@@ -117,7 +117,7 @@ pub fn build_router(state: AppState) -> axum::Router<AppState> {
.route("/api/ssw/books/Book/List", get(crud::book_list))
.route("/api/ssw/books/Book/Save", post(crud::book_save))
.route("/api/ssw/books/Book/Delete", delete(crud::book_delete))
// ---- 面 B:官方 JNPF 契约面(`docs/JNPF_COMPAT_SURFACE.md` §3)----
// ---- 面 B:官方 JNPF 契约面(`JNPF_COMPAT_SURFACE.md` §3)----
// 🔴 **面 A 的 27 条路由一个都没动** —— 面 B 全部是**新增**的官方形状路径。
// 唯一共用的是 `CurrentUser` / `Authority/Data`,它们按**判别头**分流
// (`Vue-Version: 3` ⇒ 面 B)。
+45
View File
@@ -0,0 +1,45 @@
# template-boot-jnpf 启动环境变量样板。
# 用法: cp .env.example .env,按需改值;启动前 source .env 或用 docker --env-file。
#
# 必设项:DB_HOST / DB_NAME / DB_USER / DB_PASSWORD / REDIS_HOST / DEMO_DB_NAME
# 其它有默认值(见 application-dev.yml)。
#
# ⚠️ 两个 PostgreSQL 数据库:
# - master(jnpf 主库):装 base_* 权限表,由 DB_* 控制
# - ssw-demoDs(业务库):装业务表,由 DEMO_DB_* 控制
# 两个可以共用一个 PostgreSQL 实例 + 不同 DB name,也可以不同实例。
# === Spring profile(默认 dev) ===
SPRING_PROFILES_ACTIVE=dev
# === Tomcat(默认 30000) ===
SERVER_PORT=30000
# === master 主库(jnpf 自带,含 base_* 权限表) ===
# DB_NAME=j7 是 jnpf 7.0 installer 默认建的主库名
DB_HOST=127.0.0.1
DB_PORT=5432
DB_NAME=j7
DB_USER=postgres
DB_PASSWORD=postgres
# === Redis ===
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0
# === ssw-demoDs 业务库(appCode=demo 的业务表) ===
# 不设时回落到 master 的 DB_HOST/DB_USER/DB_PASSWORD;DB_NAME 默认 demo_db
DEMO_DB_HOST=
DEMO_DB_PORT=
DEMO_DB_NAME=demo_db
DEMO_DB_USER=
DEMO_DB_PASSWORD=
# === 其它 ssw-{appCode}Ds 业务库(按需加) ===
# DEMO_DB_HOST=127.0.0.1
# DEMO_DB_PORT=5432
# DEMO_DB_NAME=other_db
# DEMO_DB_USER=postgres
# DEMO_DB_PASSWORD=postgres
+245
View File
@@ -0,0 +1,245 @@
# template-boot-jnpf — JNPF 标准栈最小骨架
`ssw-jnpf-lite-react`(NestJS MVP)稳定后迁到 JNPF 标准 Java 栈时的**最小可运行模板**——
自包含、5 个踩坑点已写在防御注释中,开发者 `cp -R` 到新目录、把 Maven `groupId` 由
`com.example` 替换为自己组织、`appCode=demo` 替换为业务名,**第一次 `mvn package` 就过**。
> ⚠️ **这不是开箱即用的成品**:模板只搭出"启动即可见到 Spring Boot 默认页 + 一个 CRUD 端点"的
> 骨架,**不**包含:
> • DDL 数据初始化(jnpf 7.0 自动建表,但 seed 数据要按官方 installer 走)
> • 完整 4 库菜单 / 权限 / 角色初始化(按需自家业务自己写)
> • 鉴权拦截器完整版(BaseCrudController 的权限 / 数据范围钩子默认 noop,
> 由业务子类按需 override — 不绑死任何权限框架)
模板对应 JNPF 7.0.0-RELEASE + JDK 17。其它版本请自行调整 `<parent>` 的 jnpf-common version。
## 目录结构
```
template-boot-jnpf/
├── pom.xml # 父 POM(继承 jnpf-common 7.0.0-RELEASE,artifactId=ssw-boot)
├── .env.example # DB_HOST / REDIS_HOST 等环境变量样板
├── README.md # 本文件
├── ssw-admin/ # 唯一可执行的 Spring Boot 入口
│ ├── pom.xml
│ └── src/main/
│ ├── java/ssw/
│ │ ├── SswAdminApplication.java # @SpringBootApplication(scanBasePackages = {"jnpf","ssw"})
│ │ └── common/config/
│ │ └── SswMapperConfig.java # 统一扫 ssw.**.mapper
│ └── resources/
│ ├── application.yml # profile 切换 + 鉴权
│ └── application-dev.yml # dev 单业务库 + Redis IP
└── ssw-demo/ # 一个最小业务模块(appCode=demo)
├── pom.xml # ssw-demo 的父(聚合 -entity / -controller)
├── ssw-demo-entity/
│ ├── pom.xml
│ └── src/main/java/ssw/demo/entity/DemoEntity.java
└── ssw-demo-controller/
├── pom.xml
└── src/main/java/ssw/demo/
├── controller/DemoController.java # @RestController 三端点
└── mapper/DemoMapper.java # extends SuperMapper<DemoEntity>
```
## 包命名约定
**Java 包命名 = `ssw.{appCode}.xx.xx`**:
| 类 | 包 |
|----|----|
| `SswAdminApplication` | `ssw`(顶层,无子包) |
| `SswMapperConfig` | `ssw.common.config`(共享层) |
| `DemoController` | `ssw.demo.controller`(业务模块) |
| `DemoMapper` | `ssw.demo.mapper`(业务模块) |
| `DemoEntity` | `ssw.demo.entity`(业务模块) |
Maven `groupId / artifactId` 与 Java 包名**不强制同**:模板默认 `<groupId>com.example</groupId>` + `<artifactId>ssw-boot</artifactId>`(用户改 groupId 时同步改所有子模块 parent 段)。Java 包名按上表硬约定。
## 数据源约定(多库架构)
**两个数据源分离**:MVP 时代 `base_*` 权限表与业务表同库;迁 JNPF 后必须分离:
| 数据源 key | 物理 DB | 装什么表 | 切换方式 |
|------------|---------|---------|---------|
| `master`(默认) | jnpf 主库(DB_NAME) | `base_user` / `base_role` / `base_module` / `base_*` 等权限与系统表 | JNPF MybatisPlusConfig 自动建 |
| `ssw-demoDs` | 业务库(DEMO_DB_NAME) | `demo_demo` 等业务表 | Mapper 上 `@DS("ssw-demoDs")` |
业务库命名约定 `ssw-{appCode}Ds`:
- `ssw-` 前缀避免与 jnpf 内部 key(如 `master` / `work`) 混淆
- `Ds` 后缀与 `dynamic-datasource-spring-boot-starter` 习惯一致
- 每加一个业务模块 = 一个新 `ssw-{appCode}Ds` 数据源 + 一个 `@DS` 注解
⚠️ **业务表必须在业务库**,不要让 `demo_demo` 这种表进 master 库(迁后再拆数据迁移非常痛)。
⚠️ **`base_*` 表不要自己建**——让 jnpf installer 在 master 库装,自己手工建表会和官方 schema 漂移。
## 5 个已写在防御注释里的踩坑(迁业务模块时也避这 5 个)
这些是从"严格按 JNPF 资深工程复制 → 删除不需要的子系统 → 加自己的业务模块"路线里**首次启动
就可能踩到的 5 个连环坑**。模板 pom / 配置里都已用 `⚠️` 注释防御。
| # | 坑 | 模板里的位置 |
|---|----|--------------|
| 1 | **jnpf-common-all 伞包传递依赖失败**——每个 jnpf-* 子包自身 pom 用 `${revision}` 占位 `1.0.0-RELEASE`,在 BOM 继承路径下解析失败 | `ssw-admin/pom.xml` 改直引 `jnpf-common-core` + `jnpf-common-database` + `<exclusion>` 排除 SaaS 集成包 |
| 2 | **IdGeneratorConfig 需要 RedisTemplate**——jnpf-common-database 的 `@Configuration` 自动启动,缺 Redis bean 会因 NoSuchBean 启动失败 | `ssw-admin/pom.xml` 含 `spring-boot-starter-data-redis`;`application-dev.yml` 含 `spring.data.redis.*` |
| 3 | **容器主机名解析失败**——主机 DNS 解析不到 docker 容器名(如 `jnpf-redis`) | `application-dev.yml` 显式用 `${DB_HOST:127.0.0.1}` / `${REDIS_HOST:127.0.0.1}` 占位符,从 `.env` 读 IP |
| 4 | **profile 切换错连多库**——多 profile(如 `full`)会挂载 4 个数据源,缺连接直接启动失败 | `application.yml` 用 `${SPRING_PROFILES_ACTIVE:dev}` 占位;不要在 `SswAdminApplication` 里硬写 `default Profile` |
| 5 | **业务库与 base_* 表未分离**——MVP 时代 base_* 与业务表同库;迁 JNPF 后 base_* 应在 jnpf **主库 master**,业务表应在 ssw-{appCode}Ds **业务库**,Mapper 上打 `@DS("ssw-{appCode}Ds")` 切库 | `application-dev.yml` 用 JNPF 扁平主配置 (`host/port/db-name`) + `spring.datasource.dynamic.datasource.ssw-demoDs` 子节点;`DemoMapper.java` 加 `@DS("ssw-demoDs")` |
## 跑通流程
```bash
# 1. 复制模板
cp -R /path/to/template-boot-jnpf ./my-boot
cd my-boot
# 2. 重命名:groupId com.example → com.myorg;包名 ssw.{appCode} 默认即可(appCode=demo 是模板演示,可全替换)
# 涉及文件:所有 pom.xml 的 <parent><groupId> + <dependency><groupId>。
# 用 sed 批量替换 com.example → com.myorg,但要保留 jnpf.* / org.springframework.* 等前缀不动。
# Java 包名已是 ssw.* 形态,不需要改目录结构。
sed -i '' 's/com.example/com.myorg/g' \
pom.xml ssw-admin/pom.xml ssw-demo/pom.xml ssw-demo/*/pom.xml
# 3. 配 .env
cp .env.example .env
$EDITOR .env # 必改:DB_HOST / DB_NAME (j7) / DEMO_DB_NAME (demo_db) / DB_USER / DB_PASSWORD / REDIS_HOST
# 跑通前置条件:本机装好 PostgreSQL + 建好两个库 (j7, demo_db) + Redis 在跑
# j7 库由 jnpf installer 装 base_* 表;demo_db 自己 psql -c 'CREATE DATABASE demo_db;' 即可
# 4. mvn install(先装父 POM,再装各子模块)
mvn -N install -DskipTests
mvn install -DskipTests
# 5. 启 ssw-admin
cd ssw-admin
nohup java -jar target/ssw-admin-1.0.0-SNAPSHOT.jar > ../boot.log 2>&1 &
tail -f ../boot.log
# → Tomcat on port 30000 + jnpf 启动成功后访问 http://127.0.0.1:30000/api/oauth/Login 应返 {"code":600,...}
# 6. 端到端验证
curl -s -X POST http://127.0.0.1:30000/api/oauth/Login \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode "account=admin" --data-urlencode "password=$PWD_ENC" --data-urlencode "grant_type=password"
# password 必须按官方公式:md5( md5(明文) + secretkey.toLowerCase() ),AES cipher 是密文传输
# 端点返 {"code":200,"data":{token:...}} 即视为端到端通
```
## 加一个新业务模块(按本模板结构复制)
参照 `ssw-demo/` 形态(包命名 `ssw.{appCode}.xx.xx`):
```
my-boot/
└── ssw-<your-appcode>/ # 包名 = ssw.<your-appcode>,目录用小写连字符
├── pom.xml # parent = ssw-boot
├── ssw-<your-appcode>-entity/
│ ├── pom.xml
│ └── src/main/java/ssw/<your-appcode>/entity/<Entity>Entity.java
│ └─ extends SuperBaseEntity
└── ssw-<your-appcode>-controller/
├── pom.xml
└── src/main/java/ssw/<your-appcode>/
├── controller/<Entity>Controller.java
│ └─ @RestController + @RequestMapping("/api/ssw/<your-appcode>/<Entity>")
└── mapper/<Entity>Mapper.java
└─ extends SuperMapper<<Entity>Entity>
```
**业务 Controller 三端点**(参考 `ssw-demo/ssw-demo-controller/.../DemoController.java`):
```java
@GetMapping("/List") // GET /api/ssw/{appCode}/{Entity}/List
@PostMapping("/Save") // POST /api/ssw/{appCode}/{Entity}/Save body = JSON
@DeleteMapping("/Delete") // DELETE /api/ssw/{appCode}/{Entity}/Delete?id=
```
并在 `ssw-admin/pom.xml` 的 `<dependencies>` 加:
```xml
<dependency>
<groupId>com.myorg</groupId>
<artifactId>ssw-<your-appcode>-controller</artifactId>
<version>${project.version}</version>
</dependency>
```
并在 `application-dev.yml` 加新业务库节点:
```yaml
spring:
datasource:
dynamic:
datasource:
ssw-<your-appcode>Ds: # ⚠️ key 必须与 Mapper 上 @DS("...") 一致
url: jdbc:postgresql://${DEMO_DB_HOST:127.0.0.1}:${DEMO_DB_PORT:5432}/${DEMO_DB_NAME:other_db}?currentSchema=public&stringtype=unspecified
username: ${DEMO_DB_USER:postgres}
password: ${DEMO_DB_PASSWORD:postgres}
driver-class-name: org.postgresql.Driver
lazy: false
```
最后 `mvn install` + 重启 `ssw-admin`。
> ⚠️ **Mapper 必须打 `@DS("ssw-{yourAppcode}Ds")`**——不加则默认走 master 库,业务表会建到 jnpf 主库里去,
> 后续想拆业务库时数据迁移非常痛。详见 `ssw-demo/ssw-demo-controller/.../DemoMapper.java`。
> ⚠️ 想要"继承基类省 5 个样板"?模板**不**预设这种抽象 — 各 JNPF 工程命名风格不一,
> 本仓库 `../references/BaseCrudController.java` 是中性版本(包 `ssw.common.controller`),
> 拷到目标 `ssw.common.controller` 包即用。审计钩子默认 noop,按需 override `audit()` 连到自家审计服务
> (详见 `../references/README.md`)。
## 与 `ssw-jnpf-lite-react` 的契约对接
迁业务模块时 `f_` 列 / `varchar(50)` UUID / `ActionResult{code,msg,data}` / `code:200` /
`code:600/601/602` 会话过期 / `BizException → code:400` / 端点 `/api/ssw/{appCode}/{Entity}/{List|Save|Delete}`
全部**一对一**保留——前端契约不变,零改接入。
详细对照表见 `../MIGRATION.md`。
## 验证记录与已知踩坑(2026-09-18 实测)
2026-09-18 把模板复制到 `/Users/xs/Desktop/jxcj/boot/` 跑 `mvn package` 验证,记录 5 个修复:
| # | 坑 | 现象 | 修复(已写进模板) |
|---|----|------|--------------------|
| 1 | **jnpf-common-* 找不到(`${project.version}` 占位被继承后污染)** | Maven 报 `com.jnpf:jnpf-common-database:jar:1.0.0-SNAPSHOT (absent)` — jnpf-common 父 POM 的 `<dependencyManagement>` 用 `${project.version}` 占位,被 ssw-boot 继承后 `${project.version}` 展开成 `1.0.0-SNAPSHOT` | 父 POM 加 `<jnpf.version>7.0.0-RELEASE</jnpf.version>` 属性 + `<dependencyManagement>` 显式锁 `jnpf-common-core/-database/-auth/-redis` 四个最常用的版本号 |
| 2 | **`SuperBaseEntity<T>` 泛型基类 `getId()` 返 Object** | `DemoEntity extends SuperBaseEntity` 不带 `<String>` → `getId()` 编译期解析为 `Object` → `.isBlank()` 报"找不到符号" | `DemoEntity` 显式 `extends SuperBaseEntity<String>`(SuperBaseEntity 的 T 就是 id 的类型) |
| 3 | **JNPF API 名是 `RandomUtil.uuId()` 不是 `uuid()`** | `dto.setId(RandomUtil.uuid())` 报"找不到方法 uuid()" | 改为 `RandomUtil.uuId()`(jnpf.util.RandomUtil 的实际方法签名是 `uuId()`,驼峰式) |
| 4 | **`@EnableFileStorage`(dromara x-file-storage)+ `SpringContext`(jnpf 内)不在依赖里** | SswAdminApplication import 这俩就编译失败 | SswAdminApplication 删掉这俩 import + 注解;用到时再加对应 starter |
| 5 | **spring-boot-maven-plugin 没绑 `repackage` → 瘦 jar** | 第一次打出来是 6.9K 瘦 jar,启动 `java -jar` 找不到依赖。Spring Boot 默认只在 pluginManagement 里 register,要显式 executions 绑到 package 阶段 | `ssw-admin/pom.xml` 加 `<executions><execution><goals><goal>repackage</goal></goals></execution></executions>` |
最终产物验证(jar 内部字节码层):
```text
$ mvn -pl ssw-admin -am package -DskipTests
[INFO] BUILD SUCCESS # 5 模块全绿
$ unzip -l ssw-admin/target/ssw-admin-1.0.0-SNAPSHOT.jar
169M / 332 files / 196 jars in BOOT-INF/lib/
✓ Main-Class: org.springframework.boot.loader.launch.JarLauncher
✓ Start-Class: ssw.SswAdminApplication
✓ BOOT-INF/classes/ssw/SswAdminApplication.class
✓ BOOT-INF/classes/ssw/common/config/SswMapperConfig.class
✓ BOOT-INF/lib/ssw-demo-controller-1.0.0-SNAPSHOT.jar (嵌套 jar)
✓ BOOT-INF/lib/jnpf-common-database-7.0.0-RELEASE.jar
✓ BOOT-INF/lib/dynamic-datasource-spring-boot3-starter-4.5.0.jar
✓ BOOT-INF/classes/application-dev.yml
$ javap -v BOOT-INF/lib/ssw-demo-controller-*.jar (内 DemoMapper.class)
RuntimeVisibleAnnotations:
com.baomidou.dynamic.datasource.annotation.DS(value="ssw-demoDs")
```
模板已用 `@DS` 把业务表切到 `ssw-demoDs` 数据源;与 `application-dev.yml` 里 `dynamic.datasource.datasource.ssw-demoDs` key 一一对应。
运行时启动未实测:模板运行需连 jnpf 主库(master)+ 业务库(ssw-{appCode}Ds)+ Redis,本机需先:
```bash
# 假设本机 jnpf 已用官方 installer 装过 master 库;新业务库直接 psql 建空 DB 即可
psql -h ${DB_HOST} -U ${DB_USER} -c "CREATE DATABASE demo_db;"
nohup java -jar ssw-admin/target/ssw-admin-1.0.0-SNAPSHOT.jar > boot.log 2>&1 &
tail -f boot.log
```
升级 jnpf 7.x → 8.x 时只需改父 POM 的 `<jnpf.version>` 一行 + 补 dependencyManagement 里没列到的 jnpf-* artifact(编译报错时会点名)。
> 配套自检脚本:`bash scripts/verify.sh` — 自动跑这 5 项 + jar 字节码级检查(`@DS` 注解值 / Manifest 的 Start-Class / dependencyManagement 锁版本)。改名 / 换包后忘了某项跑这个脚本能立即定位,不会等到运行时才发现。
+96
View File
@@ -0,0 +1,96 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
template-boot-jnpf 父 POM — 把 ssw-jnpf-lite-react 的 NestJS 后端迁到 JNPF 标准栈(jnpf-common-*)的最小骨架。
继承自官方 jnpf-common 7.0.0-RELEASE,统一管理三段子模块。
⚠️ 不要改 parent 路径:jnpf-common 内嵌 BOM <dependencyManagement>,子模块用 ${jnpf.version}
即可拿到所有 jnpf-* 依赖的精确版本。
-->
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<parent>
<groupId>com.jnpf</groupId>
<artifactId>jnpf-common</artifactId>
<version>7.0.0-RELEASE</version>
<relativePath></relativePath>
</parent>
<modelVersion>4.0.0</modelVersion>
<!--
groupId 是 Maven 坐标;Java 包名是 `ssw.*`,二者不必同。
改 groupId 时同步把所有子模块 pom 的 <parent><groupId> 也改一遍。
-->
<groupId>com.example</groupId>
<artifactId>ssw-boot</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>pom</packaging>
<modules>
<module>ssw-admin</module>
<module>ssw-demo</module>
</modules>
<properties>
<java.version>17</java.version>
<maven.compiler.source>17</maven.compiler.source>
<maven.compiler.target>17</maven.compiler.target>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<!--
⚠️ jnpf-* 依赖统一引用此版本号。
原因:jnpf-common 父 POM 的 dependencyManagement 用 ${project.version} 占位,
被我们的 ssw-boot 继承后 ${project.version} 展开成 ssw-boot 自己的版本(1.0.0-SNAPSHOT),
导致 jnpf-common-core / jnpf-common-database 解析成不存在的 1.0.0-SNAPSHOT → "absent" 错误。
用 jnpf.version 显式固定,可绕过此坑。
-->
<jnpf.version>7.0.0-RELEASE</jnpf.version>
</properties>
<!--
⚠️ 把 jnpf-common 父 BOM 里"用 ${project.version} 占位的 jnpf-*"重新声明一次,
显式锁到 ${jnpf.version}。这是覆盖式 dependencyManagement,会**完全替换**父 POM 的同名 entry。
漏一个就会出现 "1.0.0-SNAPSHOT absent" 报错 — 报错会指出具体哪个 artifact,照着补全即可。
启动阶段先列这 4 个最常用的;实际编译报错再补全。
-->
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.jnpf</groupId>
<artifactId>jnpf-common-core</artifactId>
<version>${jnpf.version}</version>
</dependency>
<dependency>
<groupId>com.jnpf</groupId>
<artifactId>jnpf-common-database</artifactId>
<version>${jnpf.version}</version>
</dependency>
<dependency>
<groupId>com.jnpf</groupId>
<artifactId>jnpf-common-auth</artifactId>
<version>${jnpf.version}</version>
</dependency>
<dependency>
<groupId>com.jnpf</groupId>
<artifactId>jnpf-common-redis</artifactId>
<version>${jnpf.version}</version>
</dependency>
</dependencies>
</dependencyManagement>
<build>
<pluginManagement>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<source>${java.version}</source>
<target>${java.version}</target>
<encoding>UTF-8</encoding>
</configuration>
</plugin>
</plugins>
</pluginManagement>
</build>
</project>
+125
View File
@@ -0,0 +1,125 @@
#!/usr/bin/env bash
# template-boot-jnpf/ 一键自检脚本
#
# 用途:验证从本模板复制走的副本(jxcj-boot 等)是否"5 项关键修复都还在"。
# 当用户把模板改名/换包后忘了某项时,跑这个脚本能立即定位。
#
# 用法:
# cd /path/to/your-boot # 例如 /Users/xs/Desktop/jxcj/boot
# bash ../scripts/verify.sh # 或 bash scripts/verify.sh
#
# 检测 5 项(每项 PASS/FAIL + 修复指引):
# 1. mvn package 全绿(验证依赖解析 + 编译)
# 2. ssw-admin/target/*-SNAPSHOT.jar 是 fat jar(大小 > 100M)
# 3. jar Manifest 含 Start-Class=ssw.SswAdminApplication
# 4. DemoMapper.class 含 @DS(value="ssw-demoDs")(动态多数据源切换)
# 5. 父 POM 含 <jnpf.version> 属性 + <dependencyManagement> 锁版本
set -u
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
PASS=0; FAIL=0
ok() { echo " ✅ $1"; PASS=$((PASS+1)); }
no() { echo " ❌ $1"; FAIL=$((FAIL+1)); }
hdr() { echo; echo "── $1 ──"; }
cd "$ROOT" || { echo "❌ 无法 cd 到 $ROOT"; exit 1; }
# ---- 1. mvn package ----
hdr "1. mvn -pl ssw-admin -am package -DskipTests(验证依赖 + 编译)"
if mvn -pl ssw-admin -am package -DskipTests -o 2>&1 | tail -5 | grep -q "BUILD SUCCESS"; then
ok "BUILD SUCCESS"
else
no "mvn package 失败(最常见:jnpf-* 1.0.0-SNAPSHOT absent → 父 POM 没锁版本;看 README '验证记录' #1)"
fi
# ---- 2. fat jar 检查 ----
hdr "2. ssw-admin fat jar 大小(应 > 100M)"
JAR="$ROOT/ssw-admin/target/ssw-admin-*-SNAPSHOT.jar"
JAR_FILE="$(ls $JAR 2>/dev/null | grep -v "\.original$" | head -1 || true)"
if [ -z "${JAR_FILE:-}" ]; then
no "找不到 ssw-admin/target/*-SNAPSHOT.jar(运行 step 1 重打)"
elif [ ! -f "${JAR_FILE:-}" ]; then
no "${JAR_FILE} 不存在"
else
SIZE=$(stat -f %z "${JAR_FILE}" 2>/dev/null || stat -c %s "${JAR_FILE}" 2>/dev/null)
SIZE_M=$((SIZE / 1024 / 1024))
if [ "$SIZE_M" -gt 100 ]; then
ok "fat jar ${SIZE_M}M(${JAR_FILE})"
else
no "${JAR_FILE} 只有 ${SIZE_M}M(瘦 jar;spring-boot-maven-plugin 没绑 repackage → README '验证记录' #5)"
fi
fi
# ---- 3. Manifest ----
hdr "3. jar Manifest 含 Start-Class=ssw.SswAdminApplication"
if [ -n "${JAR_FILE:-}" ] && [ -f "${JAR_FILE:-}" ]; then
MANIFEST="$(unzip -p "${JAR_FILE}" META-INF/MANIFEST.MF 2>/dev/null || true)"
if echo "$MANIFEST" | grep -q "Main-Class: org.springframework.boot.loader.launch.JarLauncher"; then
ok "Main-Class 是 JarLauncher(Spring Boot fat jar 入口)"
else
no "Main-Class 不是 JarLauncher(瘦 jar 形态,不是 Spring Boot fat jar)"
fi
if echo "$MANIFEST" | grep -q "Start-Class: ssw.SswAdminApplication"; then
ok "Start-Class = ssw.SswAdminApplication"
else
no "Start-Class 不是 ssw.SswAdminApplication(ssw-admin/pom.xml 的 mainClass 配错?)"
fi
else
no "跳过(jar 不存在)"
fi
# ---- 4. DemoMapper 含 @DS ----
hdr "4. DemoMapper 含 @DS(value=\"ssw-demoDs\")"
if [ -n "${JAR_FILE:-}" ] && [ -f "${JAR_FILE:-}" ]; then
DEMO_MAPPER_JAR="$(unzip -l "$JAR_FILE" 2>/dev/null | grep -oE 'BOOT-INF/lib/ssw-demo-controller-[^ ]+\.jar' | head -1)"
if [ -z "$DEMO_MAPPER_JAR" ]; then
no "BOOT-INF/lib/ 里找不到 ssw-demo-controller-*.jar(业务模块没打包进 fat jar)"
else
TMP="$(mktemp -d)"
unzip -p "${JAR_FILE}" "$DEMO_MAPPER_JAR" > "$TMP/demo-controller.jar" 2>/dev/null || true
unzip -p "$TMP/demo-controller.jar" "ssw/demo/mapper/DemoMapper.class" > "$TMP/DemoMapper.class" 2>/dev/null || true
if javap -v "$TMP/DemoMapper.class" 2>/dev/null | grep -q "Lcom/baomidou/dynamic/datasource/annotation/DS;"; then
if javap -v "$TMP/DemoMapper.class" 2>/dev/null | grep -A2 "DS;" | grep -q 'ssw-demoDs'; then
ok "@DS(value=\"ssw-demoDs\") 在 DemoMapper.class 字节码里"
else
no "@DS 注解存在但 value 不是 ssw-demoDs(业务库 key 与 application-dev.yml 对不上?)"
fi
else
no "DemoMapper.class 完全没有 @DS 注解(业务表会落进 master 库;改 DemoMapper.java 加 @DS)"
fi
rm -rf "$TMP"
fi
else
no "跳过(jar 不存在)"
fi
# ---- 5. 父 POM 含 jnpf.version + dependencyManagement ----
hdr "5. 父 POM 含 <jnpf.version> 属性 + <dependencyManagement> 锁版本"
PARENT_POM="$ROOT/pom.xml"
if grep -q "<jnpf.version>" "$PARENT_POM"; then
VERSION=$(grep -oE "<jnpf.version>[^<]+" "$PARENT_POM" | sed 's/<jnpf.version>//')
ok "jnpf.version = ${VERSION}"
else
no "父 POM 没有 <jnpf.version> 属性(jnpf-* 依赖会解析成 1.0.0-SNAPSHOT → README '验证记录' #1)"
fi
if grep -q "jnpf-common-core" "$PARENT_POM" | grep -q "dependencyManagement" "$PARENT_POM"; then
if awk '/<dependencyManagement>/,/<\/dependencyManagement>/' "$PARENT_POM" | grep -q "jnpf-common-core"; then
ok "dependencyManagement 里锁了 jnpf-common-core"
else
no "dependencyManagement 段里没有 jnpf-common-core(jnpf-* 解析会污染)"
fi
else
no "父 POM 完全没有 <dependencyManagement>(jnpf-* 解析污染 1.0.0-SNAPSHOT)"
fi
# ---- 总结 ----
echo
echo "── 总结 ──"
echo "PASS=$PASS FAIL=$FAIL"
if [ "$FAIL" -eq 0 ]; then
echo "全 ✅ 模板产物与 README 验证记录一致"
exit 0
else
echo "有 ❌ — 看上面 FAIL 行的指引 + template-boot-jnpf/README.md '验证记录' 章节"
exit 1
fi
+91
View File
@@ -0,0 +1,91 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
ssw-admin — Spring Boot 启动入口(唯一可执行 artifact)。
⚠️ 不要用 jnpf-common-all 伞包:每个 jnpf-* 子包自身 pom 用 ${revision} 占位 1.0.0-RELEASE,
在 BOM 继承路径下解析失败。改直引 jnpf-common-core + jnpf-common-database,
并 <exclusion> 排除不需要的 SaaS 集成包(activiti/tencent-oss 等)。
⚠️ jnpf-common-database 的 IdGeneratorConfig 自动启动,
需要 spring-boot-starter-data-redis + RedisTemplate bean(application-dev.yml 已含配置)。
-->
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<parent>
<groupId>com.example</groupId>
<artifactId>ssw-boot</artifactId>
<version>1.0.0-SNAPSHOT</version>
</parent>
<modelVersion>4.0.0</modelVersion>
<artifactId>ssw-admin</artifactId>
<packaging>jar</packaging>
<dependencies>
<!-- jnpf 核心 — 不要换成 jnpf-common-all,参见顶部 ⚠️ -->
<dependency>
<groupId>com.jnpf</groupId>
<artifactId>jnpf-common-core</artifactId>
<version>${jnpf.version}</version>
<exclusions>
<exclusion>
<groupId>com.jnpf</groupId>
<artifactId>jnpf-activiti</artifactId>
</exclusion>
<exclusion>
<groupId>com.jnpf</groupId>
<artifactId>jnpf-tencent-oss</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>com.jnpf</groupId>
<artifactId>jnpf-common-database</artifactId>
<version>${jnpf.version}</version>
</dependency>
<!-- Redis:IdGeneratorConfig 必需(雪花算法 workerId 持久化) -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-redis</artifactId>
</dependency>
<!-- 业务模块入口(每个业务模块 -controller 子模块都要列) -->
<dependency>
<groupId>com.example</groupId>
<artifactId>ssw-demo-controller</artifactId>
<version>${project.version}</version>
</dependency>
<!-- Lombok + Spring Boot 打包插件 -->
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
</dependency>
</dependencies>
<build>
<finalName>${project.artifactId}-${project.version}</finalName>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<configuration>
<mainClass>ssw.SswAdminApplication</mainClass>
</configuration>
<!--
⚠️ 必须显式绑 repackage 目标到 package 阶段,否则 maven-jar-plugin 先打一个瘦 jar 覆盖输出,
启动 java -jar 会找不到依赖。
-->
<executions>
<execution>
<goals>
<goal>repackage</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
@@ -0,0 +1,30 @@
package ssw;
import lombok.extern.slf4j.Slf4j;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration;
import org.springframework.boot.web.servlet.support.SpringBootServletInitializer;
/**
* ssw 标准 Spring Boot 启动入口(包名 ssw,类名 SswAdminApplication)。
*
* ⚠️ scanBasePackages 必须含 "ssw" — 否则 ssw.common.config.SswMapperConfig 等共享 bean 不会被 Spring 扫描到。
* ⚠️ exclude = DataSourceAutoConfiguration.class — jnpf-common-database 自带数据源配置,
* 不要让 Spring Boot 自动配置覆盖它。
*
* 业务模块 mapper 扫描由 {@link ssw.common.config.SswMapperConfig} 统一接管
* (basePackages = "ssw.**.mapper"),不必在本类加 @MapperScan。
*
* 注:本模板**不**带 `@EnableFileStorage`(dromara x-file-storage,文件存储用)
* 与 `jnpf.util.context.SpringContext`(Spring 容器提前初始化)这两个 starter — 用到时再加对应依赖。
*/
@Slf4j
@SpringBootApplication(scanBasePackages = {"jnpf", "ssw"}, exclude = {DataSourceAutoConfiguration.class})
public class SswAdminApplication extends SpringBootServletInitializer {
public static void main(String[] args) {
SpringApplication.run(SswAdminApplication.class, args);
log.info("SswAdmin 启动完成");
}
}
@@ -0,0 +1,22 @@
package ssw.common.config;
import org.mybatis.spring.annotation.MapperScan;
import org.springframework.context.annotation.Configuration;
/**
* ssw 共享 MapperConfig — 所有 ssw.{appCode}.**.*.mapper 由这一个配置统一注册。
*
* ⚠️ 根因:JNPF 自带 MybatisPlusConfig @MapperScan 只扫 "jnpf.**.mapper" / "jnpf.mapper",
* 不扫 ssw.**.mapper,导致所有 ssw-{app_code} 业务模块的 Mapper 接口无法被 Spring 注册为 bean,
* 启动后报 java.lang.NoSuchBeanDefinitionException: No qualifying bean of type 'ssw.{app_code}.mapper.XxxMapper'。
*
* ✅ 单一解决方案:本文件统一处理 ssw.**.mapper — 任何新加 ssw-{app_code} 包都无需再单独写 MapperConfig。
*
* 跨子系统 Mapper 重名(多 ssw-{app_code} 都叫 ContractMapper)时,启用 nameGenerator
* {@link SswMapperBeanNameGenerator} 给 bean 名加子系统前缀,从机制上避免冲突。
* 本模板默认不启用 nameGenerator;按需在本 pom 加 ssw-common-biz 依赖或复制 SswMapperBeanNameGenerator。
*/
@Configuration
@MapperScan(basePackages = "ssw.**.mapper")
public class SswMapperConfig {
}
@@ -0,0 +1,111 @@
# application-dev.yml — dev 单 profile。
#
# ⚠️ 多数据源架构(与 MVP 时代"一个库装下 base_* + 业务表"不同):
# ┌──────────────┐ ┌──────────────────────┐
# │ master (主) │ │ ssw-demoDs (业务库) │
# │ jnpf 7.0 主库│ │ 自己的 PostgreSQL │
# │ base_* 表 │ │ 业务表 (demo_demo…) │
# └──────────────┘ └──────────────────────┘
# ↑ ↑
# MybatisPlusConfig @DS("ssw-demoDs") 切库
# 自动建 master 数据源 (在 Entity / Mapper / ServiceImpl 上加注解)
#
# ⚠️ MVP 时代的 base_* 表**不再**放在业务库 — 由 jnpf 主库接替:
# 1. 让 jnpf 7.0 官方 installer 装好 master 库(含全部 base_* 表 + seed 数据)
# 2. 自己建一个空白 PostgreSQL DB(这里 demo_db),授权给 DB_USER
# 3. 业务表 DDL 由 jnpf 启动时扫描 @TableName 自动建(或在 db/schema.sql 手建)
server:
port: ${SERVER_PORT:30000}
tomcat:
uri-encoding: UTF-8
spring:
# ============= 主库(jnpf 自带 master,含 base_* 权限表)=============
# JNPF MybatisPlusConfig 会用 host/port/db-name/db-schema 自动拼出 master 的 JDBC URL,
# 不必显式写 spring.datasource.url/username/password。
application:
name: ssw-admin
profiles:
active: ${SPRING_PROFILES_ACTIVE:dev}
jackson:
date-format: yyyy-MM-dd HH:mm:ss
time-zone: GMT+8
datasource:
db-type: PostgreSQL
host: ${DB_HOST:127.0.0.1}
port: ${DB_PORT:5432}
username: ${DB_USER:postgres}
password: ${DB_PASSWORD:postgres}
db-name: ${DB_NAME:j7} # master 库名(JNPF 平台主库)
db-schema: public
# ============= 动态多数据源 =============
# primary: 默认数据源 key(master 由 JNPF MybatisPlusConfig 隐式构建)
# strict: true=未匹配到 @DS 直接抛;false=降级到 master(开发用 true 防静默放行)
dynamic:
primary: master
strict: true
druid:
test-while-idle: true
time-between-eviction-runs-millis: 60000
max-wait: 3000
initial-size: 4
max-active: 20
min-idle: 4
keep-alive: true
connect-timeout: 10000
socket-timeout: 10000
query-timeout: 90000
transaction-query-timeout: 90000
slf4j:
statementLogEnabled: true
resultSetLogEnabled: false
connectionLogEnabled: false
statementExecutableSqlLogEnable: true
# ============= 业务库节点 =============
# key 必须与 @DS("...") 注解值一致。
# ⚠️ 命名约定:`ssw-{appCode}Ds` — 显式带 ssw- 前缀避免与 jnpf 内部 key(如 "master")冲突;
# "Ds" 后缀与 dynamic-datasource-spring-boot-starter 习惯一致。
# ⚠️ 业务库 url 直接写死 JDBC URL(不像 master 用扁平字段),
# dynamic-datasource-spring-boot-starter 在 url 字段填了的情况下优先用 url。
datasource:
# appCode=demo 的业务库(不含 base_*,只放业务表 demo_demo)
ssw-demoDs:
url: jdbc:postgresql://${DEMO_DB_HOST:${DB_HOST:127.0.0.1}}:${DEMO_DB_PORT:${DB_PORT:5432}}/${DEMO_DB_NAME:demo_db}?currentSchema=public&stringtype=unspecified
username: ${DEMO_DB_USER:${DB_USER:postgres}}
password: ${DEMO_DB_PASSWORD:${DB_PASSWORD:postgres}}
driver-class-name: org.postgresql.Driver
lazy: false
# 多业务库时继续往下加:ssw-{otherAppCode}Ds: { url: ..., username: ..., password: ... }
data:
redis:
host: ${REDIS_HOST:127.0.0.1}
port: ${REDIS_PORT:6379}
password: ${REDIS_PASSWORD:}
database: ${REDIS_DB:0}
timeout: 5000
# ============= MyBatis-Plus =============
mybatis-plus:
mapper-locations: classpath*:mapper/**/*.xml
type-aliases-package: jnpf.**.entity,ssw.**.entity # ssw-{appCode} 实体扫到才能 @TableName 解析
global-config:
db-config:
id-type: assign_id
logic-delete-field: f_delete_mark
logic-delete-value: 1
logic-not-delete-value: 0
configuration:
call-setters-on-nulls: true
jdbc-type-for-null: "NULL"
log-impl: org.apache.ibatis.logging.slf4j.Slf4jImpl
logging:
level:
root: INFO
ssw: DEBUG
jnpf: WARN
@@ -0,0 +1,41 @@
# application.yml — 基础 profile 切换 + 占位。
#
# ⚠️ 多 profile 加载顺序:real / full / prod profile 可能挂载多库(业务库 / 审计库 / 报告库),
# 若 .env 仅配了单库 DB_HOST,启用这些 profile 会因缺连接而启动失败。
# 迁 JNPF 标准栈时,**默认只走 dev profile**(单业务库),其它 profile 切前必须先迁移对应 DDL。
spring:
profiles:
active: ${SPRING_PROFILES_ACTIVE:dev}
application:
name: example-boot
jackson:
date-format: yyyy-MM-dd HH:mm:ss
time-zone: GMT+8
server:
port: ${SERVER_PORT:30000}
servlet:
context-path: /
# 业务库 DSN — dev profile 在 application-dev.yml 里设值;多 profile 各自维护一组 config.* + 数据源
# (jnpf 7.0 默认有 master / work / report 三个数据源配置位置,按官方 application-{profile}.yml 模板补)。
jnpf:
config:
tenant: false # 单租户;如需多租户见 JNPF_TENANT_ANALYSIS.md 并部署 jnpf-tenant
version: false
multiDatabase: false
nacos: false
# 鉴权 — Sa-Token;切换到 redis 必走
sa-token:
token-name: Authorization
timeout: 2592000
active-timeout: -1
is-concurrent: true
is-share: true
token-style: uuid
is-log: false
is-read-cookie: false
is-read-header: true
# Sa-Token 走 Redis 存 token + 雪花 id worker
type: redis
+24
View File
@@ -0,0 +1,24 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
ssw-demo — 一个最小业务模块(appCode=demo,演示三端点基本形态)。
父 POM:ssw-boot;子模块:ssw-demo-controller、ssw-demo-entity。
业务量上来了再加 ssw-demo-biz(Service 层独立)。
-->
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<parent>
<groupId>com.example</groupId>
<artifactId>ssw-boot</artifactId>
<version>1.0.0-SNAPSHOT</version>
</parent>
<modelVersion>4.0.0</modelVersion>
<artifactId>ssw-demo</artifactId>
<packaging>pom</packaging>
<modules>
<module>ssw-demo-entity</module>
<module>ssw-demo-controller</module>
</modules>
</project>
@@ -0,0 +1,36 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<parent>
<groupId>com.example</groupId>
<artifactId>ssw-demo</artifactId>
<version>1.0.0-SNAPSHOT</version>
</parent>
<modelVersion>4.0.0</modelVersion>
<artifactId>ssw-demo-controller</artifactId>
<packaging>jar</packaging>
<dependencies>
<dependency>
<groupId>com.example</groupId>
<artifactId>ssw-demo-entity</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>com.jnpf</groupId>
<artifactId>jnpf-common-core</artifactId>
<version>${jnpf.version}</version>
</dependency>
<dependency>
<groupId>com.jnpf</groupId>
<artifactId>jnpf-common-database</artifactId>
<version>${jnpf.version}</version>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
</dependency>
</dependencies>
</project>
@@ -0,0 +1,65 @@
package ssw.demo.controller;
import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
import jnpf.base.ActionResult;
import jnpf.util.RandomUtil;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import ssw.demo.entity.DemoEntity;
import ssw.demo.mapper.DemoMapper;
import java.util.List;
/**
* Demo 业务 Controller — 最简三端点形态(List / Save / Delete),不依赖任何抽象基类。
*
* ⚠️ 包命名遵循 ssw.{appCode}.controller 约定;appCode = demo。
* 与 MVP 端 {@code /api/ssw/{appCode}/{Entity}/{List|Save|Delete}} 路径一一对应,
* 便于前端契约零改迁入。
*
* 本模板**不**继承任何 CRUD 抽象基类,避免锁定到特定业务子系统的类名。
* 如需"继承基类省 5 个样板"的写法,可选:
* (a) 拷贝技能仓库 references/BaseCrudController.java 到自己的 ssw.common.controller 包,
* 业务 Controller extends BaseCrudController<YourEntity> 即可(已剥 tdc 依赖);
* (b) 业务模块自建 BaseCrudController<T> 抽象(见 ssw-jnpf-lite-react/MIGRATION.md 的「b. 手写 @RestController」分支 + 抽象复用段落)。
*/
@RestController
@RequestMapping("/api/ssw/demo/Demo")
public class DemoController {
@Autowired
private DemoMapper demoMapper;
@GetMapping("/List")
public ActionResult<List<DemoEntity>> list() {
QueryWrapper<DemoEntity> qw = new QueryWrapper<>();
qw.eq("f_delete_mark", 0).orderByDesc("f_creator_time");
return ActionResult.success(demoMapper.selectList(qw));
}
@PostMapping("/Save")
public ActionResult<DemoEntity> save(@RequestBody DemoEntity dto) {
if (dto.getTitle() == null || dto.getTitle().isBlank()) {
return ActionResult.fail(400, "标题不能为空");
}
if (dto.getId() == null || dto.getId().isBlank()) {
dto.setId(RandomUtil.uuId()); // 36 位 UUID;varchar(50) 装得下 — JNPF API 是 uuId 不是 uuid
}
return ActionResult.success(demoMapper.insert(dto) > 0 ? dto : null);
}
@DeleteMapping("/Delete")
public ActionResult<Void> delete(@RequestParam String id) {
// 软删:update f_delete_mark=1,非 mapper.deleteById
DemoEntity upd = new DemoEntity();
upd.setId(id);
upd.setDeleteMark((short) 1);
return demoMapper.updateById(upd) > 0 ? ActionResult.success() : ActionResult.fail(500, "删除失败");
}
}
@@ -0,0 +1,19 @@
package ssw.demo.mapper;
import com.baomidou.dynamic.datasource.annotation.DS;
import jnpf.base.mapper.SuperMapper;
import ssw.demo.entity.DemoEntity;
/**
* Demo Mapper — 直接继承 jnpf SuperMapper 拿到 CRUD 基本方法(list / save / updateById / deleteById 等)。
* 包命名遵循 ssw.{appCode}.mapper 约定;appCode = demo。
*
* 被 {@link ssw.common.config.SswMapperConfig} 的 @MapperScan(basePackages = "ssw.**.mapper") 自动注册。
*
* ⚠️ @DS("ssw-demoDs") 切到业务库(对应 application-dev.yml 中
* spring.datasource.dynamic.datasource.ssw-demoDs.url 配置的 PostgreSQL DB),
* 业务表 demo_demo 即建在该库。base_* 等权限表**不在**这里 — 由 jnpf 主库(master)托管。
*/
@DS("ssw-demoDs")
public interface DemoMapper extends SuperMapper<DemoEntity> {
}
@@ -0,0 +1,26 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<parent>
<groupId>com.example</groupId>
<artifactId>ssw-demo</artifactId>
<version>1.0.0-SNAPSHOT</version>
</parent>
<modelVersion>4.0.0</modelVersion>
<artifactId>ssw-demo-entity</artifactId>
<packaging>jar</packaging>
<dependencies>
<dependency>
<groupId>com.jnpf</groupId>
<artifactId>jnpf-common-database</artifactId>
<version>${jnpf.version}</version>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
</dependency>
</dependencies>
</project>
@@ -0,0 +1,37 @@
package ssw.demo.entity;
import com.baomidou.mybatisplus.annotation.TableField;
import com.baomidou.mybatisplus.annotation.TableName;
import jnpf.base.entity.SuperBaseEntity;
import lombok.Data;
import java.math.BigDecimal;
/**
* Demo 实体 — 演示 JNPF 形态:extends SuperBaseEntity 仅引入 f_id varchar(50) 主键。
* 包命名遵循 ssw.{appCode}.entity 约定;appCode = demo。
*
* 字段命名严格遵守「f_ 前缀 + snake_case」,与 MVP 端 ssw-jnpf-lite-react 的契约 1:1。
*
* 表名 demo_demo — 命名约定 `{appCode}_{Entity_snake}`,与 MVP 的 HOWTO_MODULE.md §0 一致。
* DDL 由 jnpf 启动时扫 @TableName 自动建(或在 db/schema.sql 手建)。
*
* ⚠️ 本 Entity 放在哪个数据源由 {@link ssw.demo.mapper.DemoMapper} 上的 @DS("ssw-demoDs") 决定
* (Entity 上不打 @DS,靠 Mapper 注解传递)。jnpf 7.0 启动后会自动建表到 ssw-demoDs 业务库。
*/
@Data
@TableName("demo_demo")
public class DemoEntity extends SuperBaseEntity<String> {
@TableField("f_title")
private String title;
@TableField("f_amount")
private BigDecimal amount;
@TableField("f_enabled_mark")
private short enabledMark;
@TableField("f_delete_mark")
private short deleteMark;
}