基础项目

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

@@ -1,4 +1,4 @@
-# 业务 admin 端默认 CRUD 接口规范
+# 业务 admin 端默认 CRUD 接口规范
 
 ## 适用范围
 
@@ -35,6 +35,10 @@
 - 新增业务 `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 挂载一致。