影响:此前技能资产(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]>
332 lines
13 KiB
Java
332 lines
13 KiB
Java
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;
|
||
}
|
||
}
|
||
} |