# 业务 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` 注册。
- 单个业务模块包含多个独立资源或多张业务表时，`api/v1/<module>`、`service/<module>`、`router/<module>` 必须按资源拆分文件；禁止把多个资源的 CRUD 长期堆在同一个大文件。
- 单个业务模块包含多个独立资源或多张业务表时，`.ai-specs/doc-api/<端>/<resource>.md` 必须按资源拆分文档；禁止把多个资源的接口 contract 长期堆在同一个 doc-api 大文档。
- 每个资源文件只承载该资源的 `API`、`Service` 或 `Router` 方法；跨资源复用逻辑只能放在明确命名的 `common.go`、`helper.go` 等公共文件，且公共文件禁止承载具体资源 CRUD 主流程。
- `enter.go` 只负责聚合结构体、公共变量或分发注册，不承载具体业务逻辑和具体 CRUD handler。
- 同一模块如果同时有 `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` 这类顶层目录。