xuanzhi-service/server/.ai-specs/coding-specs/module-admin-crud-default.md

业务 admin 端默认 CRUD 接口规范

适用范围

• 新增业务模块的 admin 端管理接口时，使用本文。
• 判断某个业务模块默认应该提供哪些后台 CRUD 接口时，使用本文。
• 业务模块没有明确说明“只读”“无详情”“禁止批量删除”等例外时，默认按本文落地。

默认接口基线

• 默认 CRUD = 创建、单删、批量删除、更新、详情、分页列表 6 个接口。
• 完整路径 = <router-prefix>/<abbreviation>/...；如果 router-prefix 为空，则完整路径不带额外前缀。禁止把 /api 写死为项目事实。
• admin 接口默认挂 PrivateGroup，统一走后台 JWT + Casbin。
• 写操作默认挂 middleware.OperationRecord()；读操作默认不挂操作审计。

动作	Method	默认路径	API 方法名	Service 方法名
创建	POST	/<abbreviation>/create<StructName>	Create<StructName>	Create<StructName>
单删	DELETE	/<abbreviation>/delete<StructName>	Delete<StructName>	Delete<StructName>
批量删除	DELETE	/<abbreviation>/delete<StructName>ByIds	Delete<StructName>ByIds	Delete<StructName>ByIds
更新	PUT	/<abbreviation>/update<StructName>	Update<StructName>	Update<StructName>
详情	GET	/<abbreviation>/find<StructName>	Find<StructName>	Get<StructName>
分页列表	GET	/<abbreviation>/get<StructName>List	Get<StructName>List	Get<StructName>InfoList

参数约定

• Create、Update 默认使用 body 传实体或业务 request。
• Delete 默认用主键 query 参数删除；主键名必须和实体主键字段保持一致。
• DeleteByIds 默认用主键数组 query 参数删除，格式统一为 <primaryField>s[]。
• Find 默认用主键 query 参数查询详情。
• GetList 默认接收 model/<module>/request 下的搜索结构；普通列表返回分页结果，树形列表可不接分页参数，但接口名仍保持 get<StructName>List。

强制规则

• 新增业务 admin 模块时，如无明确例外，先提供这 6 个接口，再叠加业务特有接口。
• 路由统一放在 router/<module>，接口统一放在 api/v1/<module>，业务统一放在 service/<module>，模型统一放在 model/<module>。
• 新增业务路由后，必须同步在 initialize/router_biz.go 注册。
• 同一模块如果同时有 admin/app 两套接口，目录仍按业务模块落点，admin 与 app 必须分文件或分承载结构体，不能长期混写。
• Swagger 注解里的 @Router、@Security ApiKeyAuth、Method 必须和真实 router 挂载一致。

允许例外

• 业务天然只读时，可以不做 Create、Update、Delete、DeleteByIds，但必须在对应业务文档或接口文档中明确说明。
• 业务明确禁止批量删除时，可以去掉 DeleteByIds，但 router、api、service、前端调用、权限点必须同步移除，不能只删单层。
• 树形实体的列表接口可以返回整棵树，不强制分页；但接口名仍保持 get<StructName>List，不要随意改成 tree、all、queryList。
• 配置型场景如果本质不是独立业务实体，优先复用已有能力，例如 sys_params；不要为了凑 CRUD 强行建完整业务模块。

禁止事项

• 禁止把默认 admin CRUD 直接挂到 PublicGroup。
• 禁止同一批后台 CRUD 同时出现 createXxx、addXxx、saveXxx 多套命名。
• 禁止把列表接口随意命名成 page、list、query，导致不同模块接口风格漂移。
• 禁止只新增 API 或只新增 Router，不补齐 Service、Model、注册入口。
• 禁止因为有 app 端，就把 admin 端默认 CRUD 改落到 router/app、api/v1/app 这类顶层目录。