服务端

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

@@ -0,0 +1,54 @@
+# 业务 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` 这类顶层目录。