影响:此前技能资产(SKILL.md / HOWTO_MODULE.md / PERMISSION.md / MIGRATION.md / JNPF_SOURCE_AUDIT.md / JNPF_COMPAT_SURFACE.md / references/ / template-boot-jnpf/) 实体住在 ~/.agents/skills/ssw-jnpf-lite-rust/(仓外、不在 git)⇒ 改仓不生效、实体与仓漂移。 现在仓根 = 技能根(对齐 ssw-jnpf-lite-react 的形态),~/.agents · ~/.claude · ~/.workbuddy (+ ~/.qwenworkcn)四处软链全部解析到同一个仓 ⇒ 改一次仓 = 改一次技能。 改动: - 新增根级技能文档 6 份:SKILL.md(并补 frontmatter:name/description/type,原文件没有 frontmatter 只靠目录名兜底)/ HOWTO_MODULE.md / PERMISSION.md / MIGRATION.md / JNPF_SOURCE_AUDIT.md / JNPF_COMPAT_SURFACE.md;references/ 与 template-boot-jnpf/ 一并入仓 - 根 README.md 改为技能版(选型/运行/验收门/已知限制),旧项目版 README 移入 docs/README-project.md - docs/ 下 3 份与根级同源的文档删除(技能版取代),全仓链接改指根级(已修全部相对链接,无坏链) - docs/ 保留契约真源 contract.md / runbook.md / decisions.md / known-limitations.md / ddl/ - Cargo.toml 取「技能版注释 + 仓版补充」合并;run.sh 用仓版(多旧名兜底 pkill) - SKILL.md 补 frontmatter + 「技能目录 = 仓根」说明;CLAUDE.md 目录速览同步;HANDOFF.md 技能资产 描述同步;工作日志补第三段 验证:cargo build --release 0 error · cargo test 195 passed/0 failed · check-module.sh PASS=57 FAIL=0 · 面 A 尺子 PASS=32 FAIL=0 · 面 B 尺子 PASS=18 FAIL=0 SKIP=0(覆盖 18/18) Co-Authored-By: Claude <[email protected]>
49 lines
2.9 KiB
Markdown
49 lines
2.9 KiB
Markdown
# references/
|
||
|
||
**用途**:迁 JNPF 时可复用的**通用基础设施源码** — 这些类不在 jnpf-common-all 里,
|
||
但 ssw-jnpf-lite-react 的实战用过并验证可工作。稳定期迁业务模块时按需拷贝。
|
||
|
||
> 自包含:**不**依赖任何本技能外的 `ssw-*` 类。BaseCrudController 不绑死任何权限框架 / 数据范围
|
||
> 解析器 / 审计服务 — 这些由子类按需 override 提供。
|
||
|
||
## 当前收录
|
||
|
||
| 类 | 用途 |
|
||
|---|---|
|
||
| `BaseCrudController.java` | 通用 CRUD 骨架(List / Page / Detail / Create / Update / Delete + 关键字 / 过滤 / 数据范围 / 租户 / 可选审计)。业务 Controller `extends BaseCrudController<T>` 即可省去样板。**不是 JNPF 官方类。** |
|
||
|
||
## 使用方式
|
||
|
||
迁某个业务模块到 JNPF 时:
|
||
|
||
1. 把 `BaseCrudController.java` 拷到目标工程的 `ssw.common.controller` 包(**推荐放共享层**,让多个 `-controller` 子模块复用)
|
||
2. 业务 Controller `extends BaseCrudController<T>`,覆写方法:
|
||
- `service()`、`newEntity()`(必选)
|
||
- `keywordColumns()`、`filterColumns()`(可选)
|
||
- `beforeSave(entity, create)`(可选,业务校验)
|
||
- `requireMenuPermission()`、`applyDataScope()`(可选;权限 / 数据范围由子类按需实现,本基类不绑死任何权限框架)
|
||
3. 配套 import:`import jnpf.base.{ActionResult, Pagination, vo.PaginationVO}`;
|
||
`import jnpf.util.{RandomUtil, UserProvider, JsonUtil}`。
|
||
|
||
> 包命名约定见 `../template-boot-jnpf/README.md`「包命名约定」节 — `BaseCrudController` 必须放 `ssw.common.controller`,
|
||
> 业务 Controller 放 `ssw.{yourAppCode}.controller`。
|
||
|
||
## 默认 noop 的扩展钩子
|
||
|
||
| 钩子 | 默认行为 | 何时 override |
|
||
|------|----------|---------------|
|
||
| `requireMenuPermission()` | 空实现(不检查) | 需要菜单级权限时(自注 `@PreAuthorize` / Sa-Token `@SaCheckPermission` / 调 jnpf 自带守卫均可) |
|
||
| `applyDataScope(wrapper, request)` | 空实现(不过滤) | 需要按用户数据范围过滤时(往 wrapper 拼 SQL) |
|
||
| `audit(action, bizId, target)` | 空实现(不记) | 需要审计日志时(写日志表 / 调 MQ / HTTP 第三方) |
|
||
|
||
> **重要**:本基类**不**自带任何权限 / 数据范围 / 审计服务 — 全部默认 noop,按需覆盖。
|
||
> 不要期望拷过来就有这些能力。
|
||
|
||
## 为什么不放在主目录 / 不集成进 jnpf-common-all
|
||
|
||
- 这些类属于**业务脚手架**,不是 JNPF 官方提供的公共组件;
|
||
- 形态与具体业务耦合(如 `auditBizType()` 默认从实体类名推导);
|
||
- JNPF 官方**只承诺**提供底层基元(SuperEntity/SuperMapper/SuperService/SuperServiceImpl/ActionResult),
|
||
不提供这种「一键 CRUD」基类。
|
||
- 因此稳定期迁每个业务模块都要带一份 `BaseCrudController.java` 过去,本目录即「免去到处找」的
|
||
内置副本。 |