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

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

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

Co-Authored-By: Claude <[email protected]>
2026-10-26 16:56:58 +08:00

49 lines
2.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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` 过去,本目录即「免去到处找」的
内置副本。