diff --git a/.workbuddy/memory/2026-10-26.md b/.workbuddy/memory/2026-10-26.md index e6dc347..04be4fb 100644 --- a/.workbuddy/memory/2026-10-26.md +++ b/.workbuddy/memory/2026-10-26.md @@ -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-`),未 `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`。 diff --git a/CLAUDE.md b/CLAUDE.md index d3996c8..bcd6f97 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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` 点权限) | 说明 | diff --git a/Cargo.toml b/Cargo.toml index 698abc0..0d7edda 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -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 diff --git a/HANDOFF.md b/HANDOFF.md index 5cce321..53539f0 100644 --- a/HANDOFF.md +++ b/HANDOFF.md @@ -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: | 步 | 内容 | 落点 | 状态 | |---|---|---|---| diff --git a/HOWTO_MODULE.md b/HOWTO_MODULE.md new file mode 100644 index 0000000..d5371f9 --- /dev/null +++ b/HOWTO_MODULE.md @@ -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/.ts 3 个函数(list/save/delete) + 7. frontend/src/views/.tsx 列表页 + 8. frontend/src/App.tsx + 9. scripts/check-module.sh 期望表加一行(appCode:Entity) + ⇒ bash scripts/check-module.sh 必须全 ✅ + 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/.ts` | 3 个函数 | 页面发请求 404 | +| 7 | `src/frontend/src/views/.tsx` | 列表页 | 页面空白 | +| 8 | `src/frontend/src/App.tsx` | `` | **页面 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, headers: HeaderMap) -> Json { + let spec = shoe_spec(); + handle_list(&state, &headers, spec).await +} + +/// `POST /api/ssw/shoes/Shoe/Save`。 +pub async fn shoe_save( + State(state): State, + headers: HeaderMap, + body: Bytes, +) -> Json { + 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, + headers: HeaderMap, + raw: RawQuery, +) -> Json { + let spec = shoe_spec(); + handle_delete(&state, &headers, spec, &raw).await +} + +fn shoe_spec() -> &'static EntitySpec { + &crate::entities::SHOE_SPEC +} +``` + +🔴 **签名不要改**:`Save` 收 `body: Bytes`(自己解析,不走 `Json`), +`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/.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/.tsx` —— 列表页 + +照抄 `views/Book.tsx`(含 numeric 往返、删除确认、错误提示)。 +🔴 **金额展示别用 `Number()` 转**——后端给的是字符串 `"9.90"`,转数字会丢尾零。 + +### 3.3 `src/App.tsx` —— 注册路由 + +```tsx +import Shoe from './views/Shoe'; +… +} /> +``` + +🔴 **Route path 必须 == 菜单 `url_address`**(去前导斜杠)—— 不一致 ⇒ 侧栏点了 404。 +🔴 JSX 常写成多行(``)⇒ `check-module.sh` 用 `tr '\n' ' '` 去换行再匹配。 + +## 四、菜单 + 授权 + +- **菜单**:`seed.rs` 加一条(见 2.5)。前端侧栏由**后端返回的菜单树**驱动 ⇒ 不用改前端导航。 +- **授权**:**默认不授权 ⇒ 非管理员看不到、访问 403**(这是对的)。 + 要让某个角色看到 ⇒ 写 `base_authorize` + (`f_object_type='role'` + `f_object_id=` + `f_item_type='module'` + `f_item_id=`)。 + 走 `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` 的行) | diff --git a/docs/JNPF_COMPAT_SURFACE.md b/JNPF_COMPAT_SURFACE.md similarity index 99% rename from docs/JNPF_COMPAT_SURFACE.md rename to JNPF_COMPAT_SURFACE.md index c686c77..b4e71a1 100644 --- a/docs/JNPF_COMPAT_SURFACE.md +++ b/JNPF_COMPAT_SURFACE.md @@ -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)(每条带 `文件:行号`)。 --- diff --git a/docs/JNPF_SOURCE_AUDIT.md b/JNPF_SOURCE_AUDIT.md similarity index 98% rename from docs/JNPF_SOURCE_AUDIT.md rename to JNPF_SOURCE_AUDIT.md index 40dcccd..7b60acb 100644 --- a/docs/JNPF_SOURCE_AUDIT.md +++ b/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/`)。 --- diff --git a/docs/MIGRATION.md b/MIGRATION.md similarity index 95% rename from docs/MIGRATION.md rename to MIGRATION.md index 36e394f..1d32dce 100644 --- a/docs/MIGRATION.md +++ b/MIGRATION.md @@ -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 张:官方**没有对应表** ⇒ 要先建实体 diff --git a/PERMISSION.md b/PERMISSION.md new file mode 100644 index 0000000..51f817d --- /dev/null +++ b/PERMISSION.md @@ -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` 的真实算法**——本仓留位待迁移补(迁时一次性换算)。 diff --git a/README.md b/README.md index 6f44fb9..1b0ee91 100644 --- a/README.md +++ b/README.md @@ -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` 遇畸形百分号编码** ⇒ **实测 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。 ## 技术栈 diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..b26dbaf --- /dev/null +++ b/SKILL.md @@ -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`。 diff --git a/docs/README-project.md b/docs/README-project.md new file mode 100644 index 0000000..be7a5a5 --- /dev/null +++ b/docs/README-project.md @@ -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` 遇畸形百分号编码** ⇒ **实测 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(逐字复用) diff --git a/docs/contract.md b/docs/contract.md index 5511b0a..857285b 100644 --- a/docs/contract.md +++ b/docs/contract.md @@ -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`)。 --- diff --git a/docs/known-limitations.md b/docs/known-limitations.md index a5b4913..7e124d4 100644 --- a/docs/known-limitations.md +++ b/docs/known-limitations.md @@ -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)。 | # | 限制 | 出处 | 为什么接受 / 代价 | |---|---|---|---| diff --git a/references/BaseCrudController.java b/references/BaseCrudController.java new file mode 100644 index 0000000..0690e50 --- /dev/null +++ b/references/BaseCrudController.java @@ -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} 做业务校验。 + * + * 三条硬约定: + *
    + *
  • 软删除:全局逻辑删除没开(yml 里 logic-delete-field 是注释掉的), + * 删除走手写的 f_delete_mark=1,列表查询一律带 {@code f_delete_mark IS NULL}。 + * DDL 里的唯一索引也是按这个条件建的偏索引,两边必须对齐。
  • + *
  • 基类不用 Lambda 条件构造器:泛型擦除后拿不到具体实体的方法引用, + * 统一用字符串列名写 QueryWrapper。
  • + *
  • 租户隔离:一套实例可承载多个租户, + * 业务表统一带 f_tenant_id。子类通过 {@link #tenantColumn()} 声明租户列名, + * 基类自动接管 tenantId 过滤——子类不要自觉。
  • + *
+ * + * 审计留痕:{@link #audit} 钩子默认 noop。子类按需 override 连到自家审计服务 + * (日志表 / MQ / 第三方审计平台)即可,方法签名见 {@code audit(action, bizId, target)}。 + * + * @param 实体类型(业务扩展位用 SuperExtendEntity) + */ +public abstract class BaseCrudController> { + + /** + * 菜单权限检查钩子。基类不依赖任何权限框架 — 子类按需覆盖({@code @PreAuthorize} / + * Sa-Token {@code @SaCheckPermission} / 调自家权限服务均可)。 + * 默认空实现(不检查权限),适合 demo / 内部工具。 + */ + protected void requireMenuPermission() { + } + + /** + * 数据范围过滤钩子。基类不依赖具体的数据范围解析器 — 子类按需覆盖往 wrapper 里拼 SQL。 + * 默认空实现(不过滤数据范围),适合单租户 / demo。 + */ + protected void applyDataScope(QueryWrapper wrapper, HttpServletRequest request) { + } + + /** 逻辑未删除条件,所有查询都要带 */ + protected static final String ALIVE = "(f_delete_mark IS NULL OR f_delete_mark = 0)"; + + // ------------------------------------------------------------------ 子类扩展点 + + protected abstract SuperService service(); + + /** 新建实体实例(泛型擦除拿不到构造器,交给子类) */ + protected abstract T newEntity(); + + /** 关键字模糊匹配的列,返回空数组表示不支持关键字搜索 */ + protected String[] keywordColumns() { + return new String[]{"f_name"}; + } + + /** 精确过滤:请求参数名 -> 数据库列名 */ + protected Map 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 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 page = + new com.baomidou.mybatisplus.extension.plugins.pagination.Page<>(current, size); + IPage result = service().page(page, wrapper); + + List records = pagination.setData(result.getRecords(), result.getTotal()); + return ActionResult.page(records, JsonUtil.getJsonToBean(pagination, PaginationVO.class)); + } + + @GetMapping("/All") + @Operation(summary = "不分页全量列表", description = "用于下拉选择等场景,最多返回 1000 条") + public ActionResult> all(HttpServletRequest request) { + requireMenuPermission(); + QueryWrapper wrapper = buildWrapper(request); + wrapper.last("limit 1000"); + return ActionResult.success(service().list(wrapper)); + } + + @GetMapping("/{id}") + @Operation(summary = "详情") + public ActionResult 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 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 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 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 buildWrapper(HttpServletRequest request) { + QueryWrapper 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 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 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; + } + } +} \ No newline at end of file diff --git a/references/README.md b/references/README.md new file mode 100644 index 0000000..0626273 --- /dev/null +++ b/references/README.md @@ -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` 即可省去样板。**不是 JNPF 官方类。** | + +## 使用方式 + +迁某个业务模块到 JNPF 时: + +1. 把 `BaseCrudController.java` 拷到目标工程的 `ssw.common.controller` 包(**推荐放共享层**,让多个 `-controller` 子模块复用) +2. 业务 Controller `extends BaseCrudController`,覆写方法: + - `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` 过去,本目录即「免去到处找」的 + 内置副本。 \ No newline at end of file diff --git a/scripts/check-module.sh b/scripts/check-module.sh index 18b35d6..cd51fc4 100755 --- a/scripts/check-module.sh +++ b/scripts/check-module.sh @@ -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` 是本仓前端唯一不发的** ⇒ 判别只能用它。 diff --git a/scripts/perm-smoke-jnpf.sh b/scripts/perm-smoke-jnpf.sh index ebcdad5..1c58a86 100644 --- a/scripts/perm-smoke-jnpf.sh +++ b/scripts/perm-smoke-jnpf.sh @@ -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`(同款), diff --git a/src/backend/src/auth.rs b/src/backend/src/auth.rs index bee1961..b4d2cc7 100644 --- a/src/backend/src/auth.rs +++ b/src/backend/src/auth.rs @@ -163,7 +163,7 @@ pub async fn login_handler(State(state): State, body: Bytes) -> Json Json { // 🔴 判别头 = `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( diff --git a/src/backend/src/jnpf.rs b/src/backend/src/jnpf.rs index 6b8abde..1175447 100644 --- a/src/backend/src/jnpf.rs +++ b/src/backend/src/jnpf.rs @@ -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 { /// `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)。 diff --git a/src/backend/src/permission.rs b/src/backend/src/permission.rs index 46e71bd..0e46d32 100644 --- a/src/backend/src/permission.rs +++ b/src/backend/src/permission.rs @@ -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'` 的菜单授权」。 /// diff --git a/src/backend/src/routes.rs b/src/backend/src/routes.rs index 44df67d..7fe5d36 100644 --- a/src/backend/src/routes.rs +++ b/src/backend/src/routes.rs @@ -117,7 +117,7 @@ pub fn build_router(state: AppState) -> axum::Router { .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)。 diff --git a/template-boot-jnpf/.env.example b/template-boot-jnpf/.env.example new file mode 100644 index 0000000..d2462d4 --- /dev/null +++ b/template-boot-jnpf/.env.example @@ -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 \ No newline at end of file diff --git a/template-boot-jnpf/README.md b/template-boot-jnpf/README.md new file mode 100644 index 0000000..4b0c4e5 --- /dev/null +++ b/template-boot-jnpf/README.md @@ -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。其它版本请自行调整 `` 的 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 +``` + +## 包命名约定 + +**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 包名**不强制同**:模板默认 `com.example` + `ssw-boot`(用户改 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` + `` 排除 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 的 + 。 +# 用 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-/ # 包名 = ssw.,目录用小写连字符 + ├── pom.xml # parent = ssw-boot + ├── ssw--entity/ + │ ├── pom.xml + │ └── src/main/java/ssw//entity/Entity.java + │ └─ extends SuperBaseEntity + └── ssw--controller/ + ├── pom.xml + └── src/main/java/ssw// + ├── controller/Controller.java + │ └─ @RestController + @RequestMapping("/api/ssw//") + └── mapper/Mapper.java + └─ extends SuperMapper<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` 的 `` 加: + +```xml + + com.myorg + ssw--controller + ${project.version} + +``` + +并在 `application-dev.yml` 加新业务库节点: + +```yaml +spring: + datasource: + dynamic: + datasource: + ssw-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 的 `` 用 `${project.version}` 占位,被 ssw-boot 继承后 `${project.version}` 展开成 `1.0.0-SNAPSHOT` | 父 POM 加 `7.0.0-RELEASE` 属性 + `` 显式锁 `jnpf-common-core/-database/-auth/-redis` 四个最常用的版本号 | +| 2 | **`SuperBaseEntity` 泛型基类 `getId()` 返 Object** | `DemoEntity extends SuperBaseEntity` 不带 `` → `getId()` 编译期解析为 `Object` → `.isBlank()` 报"找不到符号" | `DemoEntity` 显式 `extends SuperBaseEntity`(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` 加 `repackage` | + +最终产物验证(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 的 `` 一行 + 补 dependencyManagement 里没列到的 jnpf-* artifact(编译报错时会点名)。 + +> 配套自检脚本:`bash scripts/verify.sh` — 自动跑这 5 项 + jar 字节码级检查(`@DS` 注解值 / Manifest 的 Start-Class / dependencyManagement 锁版本)。改名 / 换包后忘了某项跑这个脚本能立即定位,不会等到运行时才发现。 \ No newline at end of file diff --git a/template-boot-jnpf/pom.xml b/template-boot-jnpf/pom.xml new file mode 100644 index 0000000..70eb536 --- /dev/null +++ b/template-boot-jnpf/pom.xml @@ -0,0 +1,96 @@ + + + + + com.jnpf + jnpf-common + 7.0.0-RELEASE + + + + 4.0.0 + + com.example + ssw-boot + 1.0.0-SNAPSHOT + pom + + + ssw-admin + ssw-demo + + + + 17 + 17 + 17 + UTF-8 + + + 7.0.0-RELEASE + + + + + + + com.jnpf + jnpf-common-core + ${jnpf.version} + + + com.jnpf + jnpf-common-database + ${jnpf.version} + + + com.jnpf + jnpf-common-auth + ${jnpf.version} + + + com.jnpf + jnpf-common-redis + ${jnpf.version} + + + + + + + + + org.apache.maven.plugins + maven-compiler-plugin + + ${java.version} + ${java.version} + UTF-8 + + + + + + \ No newline at end of file diff --git a/template-boot-jnpf/scripts/verify.sh b/template-boot-jnpf/scripts/verify.sh new file mode 100755 index 0000000..7ce2b0e --- /dev/null +++ b/template-boot-jnpf/scripts/verify.sh @@ -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 含 属性 + 锁版本 +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 含 属性 + 锁版本" +PARENT_POM="$ROOT/pom.xml" +if grep -q "" "$PARENT_POM"; then + VERSION=$(grep -oE "[^<]+" "$PARENT_POM" | sed 's///') + ok "jnpf.version = ${VERSION}" +else + no "父 POM 没有 属性(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>/' "$PARENT_POM" | grep -q "jnpf-common-core"; then + ok "dependencyManagement 里锁了 jnpf-common-core" + else + no "dependencyManagement 段里没有 jnpf-common-core(jnpf-* 解析会污染)" + fi +else + no "父 POM 完全没有 (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 \ No newline at end of file diff --git a/template-boot-jnpf/ssw-admin/pom.xml b/template-boot-jnpf/ssw-admin/pom.xml new file mode 100644 index 0000000..9e514bf --- /dev/null +++ b/template-boot-jnpf/ssw-admin/pom.xml @@ -0,0 +1,91 @@ + + + + + com.example + ssw-boot + 1.0.0-SNAPSHOT + + + 4.0.0 + ssw-admin + jar + + + + + com.jnpf + jnpf-common-core + ${jnpf.version} + + + com.jnpf + jnpf-activiti + + + com.jnpf + jnpf-tencent-oss + + + + + com.jnpf + jnpf-common-database + ${jnpf.version} + + + + + org.springframework.boot + spring-boot-starter-data-redis + + + + + com.example + ssw-demo-controller + ${project.version} + + + + + org.projectlombok + lombok + + + + + ${project.artifactId}-${project.version} + + + org.springframework.boot + spring-boot-maven-plugin + + ssw.SswAdminApplication + + + + + + repackage + + + + + + + \ No newline at end of file diff --git a/template-boot-jnpf/ssw-admin/src/main/java/ssw/SswAdminApplication.java b/template-boot-jnpf/ssw-admin/src/main/java/ssw/SswAdminApplication.java new file mode 100644 index 0000000..e5ac8c8 --- /dev/null +++ b/template-boot-jnpf/ssw-admin/src/main/java/ssw/SswAdminApplication.java @@ -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 启动完成"); + } +} \ No newline at end of file diff --git a/template-boot-jnpf/ssw-admin/src/main/java/ssw/common/config/SswMapperConfig.java b/template-boot-jnpf/ssw-admin/src/main/java/ssw/common/config/SswMapperConfig.java new file mode 100644 index 0000000..43a5b50 --- /dev/null +++ b/template-boot-jnpf/ssw-admin/src/main/java/ssw/common/config/SswMapperConfig.java @@ -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 { +} \ No newline at end of file diff --git a/template-boot-jnpf/ssw-admin/src/main/resources/application-dev.yml b/template-boot-jnpf/ssw-admin/src/main/resources/application-dev.yml new file mode 100644 index 0000000..2eaabb1 --- /dev/null +++ b/template-boot-jnpf/ssw-admin/src/main/resources/application-dev.yml @@ -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 \ No newline at end of file diff --git a/template-boot-jnpf/ssw-admin/src/main/resources/application.yml b/template-boot-jnpf/ssw-admin/src/main/resources/application.yml new file mode 100644 index 0000000..fd78c64 --- /dev/null +++ b/template-boot-jnpf/ssw-admin/src/main/resources/application.yml @@ -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 \ No newline at end of file diff --git a/template-boot-jnpf/ssw-demo/pom.xml b/template-boot-jnpf/ssw-demo/pom.xml new file mode 100644 index 0000000..a8dd48f --- /dev/null +++ b/template-boot-jnpf/ssw-demo/pom.xml @@ -0,0 +1,24 @@ + + + + + com.example + ssw-boot + 1.0.0-SNAPSHOT + + + 4.0.0 + ssw-demo + pom + + + ssw-demo-entity + ssw-demo-controller + + \ No newline at end of file diff --git a/template-boot-jnpf/ssw-demo/ssw-demo-controller/pom.xml b/template-boot-jnpf/ssw-demo/ssw-demo-controller/pom.xml new file mode 100644 index 0000000..48b3491 --- /dev/null +++ b/template-boot-jnpf/ssw-demo/ssw-demo-controller/pom.xml @@ -0,0 +1,36 @@ + + + + com.example + ssw-demo + 1.0.0-SNAPSHOT + + + 4.0.0 + ssw-demo-controller + jar + + + + com.example + ssw-demo-entity + ${project.version} + + + com.jnpf + jnpf-common-core + ${jnpf.version} + + + com.jnpf + jnpf-common-database + ${jnpf.version} + + + org.projectlombok + lombok + + + \ No newline at end of file diff --git a/template-boot-jnpf/ssw-demo/ssw-demo-controller/src/main/java/ssw/demo/controller/DemoController.java b/template-boot-jnpf/ssw-demo/ssw-demo-controller/src/main/java/ssw/demo/controller/DemoController.java new file mode 100644 index 0000000..f00b1b3 --- /dev/null +++ b/template-boot-jnpf/ssw-demo/ssw-demo-controller/src/main/java/ssw/demo/controller/DemoController.java @@ -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 即可(已剥 tdc 依赖); + * (b) 业务模块自建 BaseCrudController 抽象(见 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() { + QueryWrapper qw = new QueryWrapper<>(); + qw.eq("f_delete_mark", 0).orderByDesc("f_creator_time"); + return ActionResult.success(demoMapper.selectList(qw)); + } + + @PostMapping("/Save") + public ActionResult 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 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, "删除失败"); + } +} \ No newline at end of file diff --git a/template-boot-jnpf/ssw-demo/ssw-demo-controller/src/main/java/ssw/demo/mapper/DemoMapper.java b/template-boot-jnpf/ssw-demo/ssw-demo-controller/src/main/java/ssw/demo/mapper/DemoMapper.java new file mode 100644 index 0000000..5a395b9 --- /dev/null +++ b/template-boot-jnpf/ssw-demo/ssw-demo-controller/src/main/java/ssw/demo/mapper/DemoMapper.java @@ -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 { +} \ No newline at end of file diff --git a/template-boot-jnpf/ssw-demo/ssw-demo-entity/pom.xml b/template-boot-jnpf/ssw-demo/ssw-demo-entity/pom.xml new file mode 100644 index 0000000..1f4bad2 --- /dev/null +++ b/template-boot-jnpf/ssw-demo/ssw-demo-entity/pom.xml @@ -0,0 +1,26 @@ + + + + com.example + ssw-demo + 1.0.0-SNAPSHOT + + + 4.0.0 + ssw-demo-entity + jar + + + + com.jnpf + jnpf-common-database + ${jnpf.version} + + + org.projectlombok + lombok + + + \ No newline at end of file diff --git a/template-boot-jnpf/ssw-demo/ssw-demo-entity/src/main/java/ssw/demo/entity/DemoEntity.java b/template-boot-jnpf/ssw-demo/ssw-demo-entity/src/main/java/ssw/demo/entity/DemoEntity.java new file mode 100644 index 0000000..e4ac43d --- /dev/null +++ b/template-boot-jnpf/ssw-demo/ssw-demo-entity/src/main/java/ssw/demo/entity/DemoEntity.java @@ -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 { + + @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; +} \ No newline at end of file