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:
1 parent
8b24bb1aea
commit
7c4ae39664
37 files changed
+2422
-131
No files matched your search
@@ -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`。
|
||||
@@ -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
@@ -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
@@ -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
@@ -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/`)。
|
||||
|
||||
---
|
||||
|
||||
@@ -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
@@ -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` 的真实算法**——本仓留位待迁移补(迁时一次性换算)。
|
||||
@@ -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。
|
||||
|
||||
## 技术栈
|
||||
|
||||
|
||||
@@ -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`。
|
||||
@@ -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
@@ -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`)。
|
||||
|
||||
---
|
||||
|
||||
@@ -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)。
|
||||
|
||||
| # | 限制 | 出处 | 为什么接受 / 代价 |
|
||||
|---|---|---|---|
|
||||
|
||||
@@ -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;
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -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` 过去,本目录即「免去到处找」的
|
||||
内置副本。
|
||||
@@ -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` 是本仓前端唯一不发的** ⇒ 判别只能用它。
|
||||
|
||||
@@ -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`(同款),
|
||||
|
||||
@@ -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(
|
||||
|
||||
@@ -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)。
|
||||
|
||||
@@ -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'` 的菜单授权」。
|
||||
///
|
||||
|
||||
@@ -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)。
|
||||
|
||||
@@ -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
|
||||
@@ -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 锁版本)。改名 / 换包后忘了某项跑这个脚本能立即定位,不会等到运行时才发现。
|
||||
@@ -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>
|
||||
Executable
+125
@@ -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
|
||||
@@ -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
|
||||
@@ -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>
|
||||
+65
@@ -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, "删除失败");
|
||||
}
|
||||
}
|
||||
+19
@@ -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>
|
||||
+37
@@ -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;
|
||||
}
|
||||
Reference in new issue
Block a user