CRUD 指南

增删改查模块的 落地模板。写任何 sys_xxx 的 CRUD 之前先读完本指南，照抄模板 + 查对照表即可， 不需要再去翻 client/config 模块的源码。
分层依赖、命名、雪花 ID、注释克制等全局约束见架构与编码约定，本指南不重复，只讲 CRUD 的具体写法。
参考实现（本指南所有片段都取自它们，需要看完整上下文时再读）：sys_config（无逻辑删除 + 缓存 + 内置保护）、sys_client （有逻辑删除 + 状态开关）。

动手前先确认三件事

要确认的	怎么查	影响什么
表有没有 `del_flag`	原项目 `script/sql/ry_vue.sql` 的 `create table`	决定 entity 是否嵌 `repository.LogicDelete`，删除是物理还是逻辑
原实现的过滤语义	`XxxServiceImpl.buildQueryWrapper`	`likeIfText` → LIKE，`eqIfText` → `=`，`betweenParams` → 闭区间
前端实际调用形态	`ruoyi-plus-vben5-main/apps/web-antd/src/api/system/<模块>/index.ts` 与同级 `views/.../index.vue`	导出是 POST form、日期区间摊平成 `params[beginTime]`、哪些字段真会回传

别跳过第三条 Controller 的方法签名不等于前端的调用形态，updateByKey 就是典型：原实现复用 SysConfigBo

，但前端只回传 2 个字段。

六个文件，固定顺序

按 model → repository → service → handler → router → test 的顺序写，每步 go build ./... 一次。

internal/system/model/entity 或 model/sys_xxx.go   实体（多数已存在，先 ls 确认）
internal/system/model/bo/sys_xxx_query_bo.go       查询条件（新建，勿复用写入 BO）
internal/system/model/vo/sys_xxx_vo.go             出参 + excel tag（多数已存在，补 tag）
internal/system/repository/xxx_repository.go       数据访问
internal/system/service/xxx_service.go             业务逻辑
internal/system/handler/xxx_handler.go             HTTP 层
internal/system/router.go                          注册路由（改现有文件）

model/bo/conv.go、model/vo/conv.go 里的 goverter 接口 多数已声明好，先 grep "ConvertToSysXxx" internal/system/model/*/conv_gen.go 确认。缺了才补声明并 go generate ./internal/system/model/...。

后续章节

BO 与 VO —— 查询 BO 单开、excel tag
Repository —— 六条硬规则
Service —— 主键发号 / 唯一性 / 存在性判定 / 更新列取舍 / 删除 / 缓存
Handler —— 骨架 + 三条铁律 + 错误码
Router —— 注册顺序 + 中间件顺序 + 注解速查

CRUD 指南 ​

动手前先确认三件事 ​

六个文件，固定顺序 ​

后续章节 ​

CRUD 指南

动手前先确认三件事

六个文件，固定顺序

后续章节