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

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

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

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

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

No files matched your search

+332
View File
@@ -0,0 +1,332 @@
package ssw.common.controller;
import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
import com.baomidou.mybatisplus.core.metadata.IPage;
import io.swagger.v3.oas.annotations.Operation;
import jakarta.servlet.http.HttpServletRequest;
import jnpf.base.ActionResult;
import jnpf.base.Pagination;
import jnpf.base.entity.SuperExtendEntity;
import jnpf.base.service.SuperService;
import jnpf.base.vo.PaginationVO;
import jnpf.util.JsonUtil;
import jnpf.util.RandomUtil;
import jnpf.util.UserProvider;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import java.util.Collections;
import java.util.Date;
import java.util.List;
import java.util.Map;
/**
* ssw 通用 CRUD 控制器骨架 — 业务 Controller 继承它即可省去 List/Page/Detail/Create/Update/Delete 样板。
*
* 子类只声明「关键字匹配哪些列」「支持哪些过滤参数」,
* 需要时覆写 {@link #beforeSave} 做业务校验。
*
* 三条硬约定:
* <ul>
* <li><b>软删除</b>:全局逻辑删除没开(yml 里 logic-delete-field 是注释掉的),
* 删除走手写的 f_delete_mark=1,列表查询一律带 {@code f_delete_mark IS NULL}。
* DDL 里的唯一索引也是按这个条件建的偏索引,两边必须对齐。</li>
* <li><b>基类不用 Lambda 条件构造器</b>:泛型擦除后拿不到具体实体的方法引用,
* 统一用字符串列名写 QueryWrapper。</li>
* <li><b>租户隔离</b>:一套实例可承载多个租户,
* 业务表统一带 f_tenant_id。子类通过 {@link #tenantColumn()} 声明租户列名,
* 基类自动接管 tenantId 过滤——子类不要自觉。</li>
* </ul>
*
* 审计留痕:{@link #audit} 钩子默认 noop。子类按需 override 连到自家审计服务
* (日志表 / MQ / 第三方审计平台)即可,方法签名见 {@code audit(action, bizId, target)}。
*
* @param <T> 实体类型(业务扩展位用 SuperExtendEntity<String>)
*/
public abstract class BaseCrudController<T extends SuperExtendEntity<String>> {
/**
* 菜单权限检查钩子。基类不依赖任何权限框架 — 子类按需覆盖({@code @PreAuthorize} /
* Sa-Token {@code @SaCheckPermission} / 调自家权限服务均可)。
* 默认空实现(不检查权限),适合 demo / 内部工具。
*/
protected void requireMenuPermission() {
}
/**
* 数据范围过滤钩子。基类不依赖具体的数据范围解析器 — 子类按需覆盖往 wrapper 里拼 SQL。
* 默认空实现(不过滤数据范围),适合单租户 / demo。
*/
protected void applyDataScope(QueryWrapper<T> wrapper, HttpServletRequest request) {
}
/** 逻辑未删除条件,所有查询都要带 */
protected static final String ALIVE = "(f_delete_mark IS NULL OR f_delete_mark = 0)";
// ------------------------------------------------------------------ 子类扩展点
protected abstract SuperService<T> service();
/** 新建实体实例(泛型擦除拿不到构造器,交给子类) */
protected abstract T newEntity();
/** 关键字模糊匹配的列,返回空数组表示不支持关键字搜索 */
protected String[] keywordColumns() {
return new String[]{"f_name"};
}
/** 精确过滤:请求参数名 -> 数据库列名 */
protected Map<String, String> filterColumns() {
return Collections.emptyMap();
}
/**
* 该表的「租户」列名,返回 null 表示本表不按租户隔离
* (如实例级全局配置)。返回非 null 时,请求参数 tenantId 自动生效。
*/
protected String tenantColumn() {
return "f_tenant_id";
}
/** 默认排序列,倒序 */
protected String defaultOrderColumn() {
return "f_creator_time";
}
/**
* 落库前的钩子,可做业务校验/补默认值。抛异常即中断并返回 fail。
*
* @param entity 待保存实体
* @param create true=新增,false=修改
*/
protected void beforeSave(T entity, boolean create) {
}
/** 删除前的钩子,可做引用检查 */
protected void beforeDelete(T entity) {
}
// ------------------------------------------------------------------ 审计留痕扩展点(可选实现)
/**
* 本控制器对应的业务类型。默认由实体类名推导;返回 {@code null} 表示不留痕。
*/
protected String auditBizType() {
String name = newEntity().getClass().getSimpleName().replaceAll("Entity$", "");
return name.replaceAll("([a-z0-9])([A-Z])", "$1_$2").toUpperCase();
}
/** 留痕时展示的对象描述 */
protected String auditTarget(T entity) {
if (entity == null) {
return null;
}
for (String getter : new String[]{"getCode", "getName", "getTaskNo", "getOrderCode",
"getDemandCode", "getResourceName", "getProductName", "getTitle", "getFullName"}) {
try {
Object v = entity.getClass().getMethod(getter).invoke(entity);
if (v != null && !v.toString().isBlank()) {
return v.toString();
}
} catch (Exception ignore) {
// 该实体没有这个字段,继续试下一个
}
}
return entity.getId();
}
/**
* 写一条业务留痕。子类要启用审计时,覆盖此方法连到自家审计服务;
* 不覆盖则 {@link #create} / {@link #update} / {@link #delete} 三处 audit 调用静默 noop。
*
* 替换为自家实现时可参考方法签名:bizId 实体主键 / action CREATE|UPDATE|DELETE / target 业务标识。
*/
protected void audit(String action, String bizId, String target) {
// 默认 noop;子类按需 override
}
/** 写一条带结果与明细的业务留痕;默认 noop */
protected void audit(String action, String bizId, String target,
String result, String failReason, String detail) {
// 默认 noop;子类按需 override
}
// ------------------------------------------------------------------ 通用接口
@GetMapping
@Operation(summary = "分页列表", description = "支持 keyword 模糊搜索、tenantId 过滤与子类声明的精确过滤参数")
public ActionResult<?> list(Pagination pagination, HttpServletRequest request) {
requireMenuPermission();
QueryWrapper<T> wrapper = buildWrapper(request);
long current = pagination.getCurrentPage() <= 0 ? 1 : pagination.getCurrentPage();
long size = pagination.getPageSize() <= 0 ? 20 : Math.min(pagination.getPageSize(), 500);
com.baomidou.mybatisplus.extension.plugins.pagination.Page<T> page =
new com.baomidou.mybatisplus.extension.plugins.pagination.Page<>(current, size);
IPage<T> result = service().page(page, wrapper);
List<T> records = pagination.setData(result.getRecords(), result.getTotal());
return ActionResult.page(records, JsonUtil.getJsonToBean(pagination, PaginationVO.class));
}
@GetMapping("/All")
@Operation(summary = "不分页全量列表", description = "用于下拉选择等场景,最多返回 1000 条")
public ActionResult<List<T>> all(HttpServletRequest request) {
requireMenuPermission();
QueryWrapper<T> wrapper = buildWrapper(request);
wrapper.last("limit 1000");
return ActionResult.success(service().list(wrapper));
}
@GetMapping("/{id}")
@Operation(summary = "详情")
public ActionResult<T> detail(@PathVariable("id") String id) {
requireMenuPermission();
T entity = getAlive(id);
if (entity == null) {
return ActionResult.fail("记录不存在或已删除");
}
return ActionResult.success(entity);
}
@PostMapping
@Operation(summary = "新增")
public ActionResult<String> create(@RequestBody T entity) {
requireMenuPermission();
entity.setId(RandomUtil.uuId());
entity.setDeleteMark(null);
beforeSave(entity, true);
service().save(entity);
audit("CREATE", entity.getId(), auditTarget(entity));
return ActionResult.success("新增成功", entity.getId());
}
@PutMapping("/{id}")
@Operation(summary = "修改", description = "只覆盖请求体里出现的字段,未传字段保持原值")
public ActionResult<String> update(@PathVariable("id") String id, @RequestBody T entity) {
requireMenuPermission();
T exists = getAlive(id);
if (exists == null) {
return ActionResult.fail("记录不存在或已删除");
}
entity.setId(id);
// 系统列不允许从请求体覆盖
entity.setCreatorTime(null);
entity.setCreatorUserId(null);
entity.setDeleteMark(null);
entity.setDeleteTime(null);
entity.setDeleteUserId(null);
beforeSave(entity, false);
service().updateById(entity);
// 用改前的实体取 target:改后的对象只带请求体里出现的字段,编号往往是 null
audit("UPDATE", id, auditTarget(exists));
return ActionResult.success("修改成功", id);
}
@DeleteMapping("/{id}")
@Operation(summary = "删除", description = "逻辑删除,置 f_delete_mark=1")
public ActionResult<String> delete(@PathVariable("id") String id) {
requireMenuPermission();
T exists = getAlive(id);
if (exists == null) {
return ActionResult.fail("记录不存在或已删除");
}
beforeDelete(exists);
T update = newEntity();
update.setId(id);
update.setDeleteMark(1);
update.setDeleteTime(new Date());
update.setDeleteUserId(safeUserId());
service().updateById(update);
audit("DELETE", id, auditTarget(exists));
return ActionResult.success("删除成功", id);
}
// ------------------------------------------------------------------ 内部工具
protected QueryWrapper<T> buildWrapper(HttpServletRequest request) {
QueryWrapper<T> wrapper = new QueryWrapper<>();
wrapper.apply(ALIVE);
String tenantColumn = tenantColumn();
if (tenantColumn != null) {
String tenantId = param(request, "tenantId");
if (tenantId != null) {
wrapper.eq(tenantColumn, tenantId);
}
}
filterColumns().forEach((param, column) -> {
String value = param(request, param);
if (value != null) {
wrapper.eq(column, value);
}
});
String keyword = param(request, "keyword");
String[] columns = keywordColumns();
if (keyword != null && columns.length > 0) {
wrapper.and(w -> {
for (int i = 0; i < columns.length; i++) {
if (i == 0) {
w.like(columns[i], keyword);
} else {
w.or().like(columns[i], keyword);
}
}
});
}
applyDataScope(wrapper, request);
wrapper.orderByDesc(defaultOrderColumn());
return wrapper;
}
/** 取请求参数,空串统一归一成 null */
protected String param(HttpServletRequest request, String name) {
if (request == null) {
return null;
}
String value = request.getParameter(name);
if (value == null) {
return null;
}
value = value.trim();
return value.isEmpty() ? null : value;
}
/** 按主键取未删除的记录 */
protected T getAlive(String id) {
QueryWrapper<T> wrapper = new QueryWrapper<>();
wrapper.eq("f_id", id).apply(ALIVE);
return service().getOne(wrapper, false);
}
/** 判断某列值是否已被占用(排除自身),用于编码唯一性校验 */
protected boolean existsBy(String column, String value, String excludeId) {
QueryWrapper<T> wrapper = new QueryWrapper<>();
wrapper.eq(column, value).apply(ALIVE);
if (excludeId != null && !excludeId.isEmpty()) {
wrapper.ne("f_id", excludeId);
}
return service().count(wrapper) > 0;
}
/** 必填校验小工具,减少 Controller 里成片的 if-blank */
protected void requireText(String value, String message) {
if (value == null || value.isBlank()) {
throw new IllegalArgumentException(message);
}
}
protected String safeUserId() {
try {
return UserProvider.getLoginUserId();
} catch (Exception e) {
return null;
}
}
}