# CONSENSUS: 开发规范

## 1. 需求描述和验收标准

**需求描述**：
基于对 `/internal/api/admin` 模块代码的分析，制定一套清晰、统一的 Go API 开发规范。该规范将作为项目后续所有 API 开发的强制标准，以确保代码质量、一致性和可维护性。

**验收标准**：
1.  生成一份完整的 `docs/开发规范.md` 文档。
2.  文档内容必须准确反映从 `admin` 模块总结出的最佳实践。
3.  规范应覆盖从 API 定义、实现到错误处理的全过程。
4.  规范应明确代码风格、目录结构、命名约定等关键要素。
5.  所有示例代码必须符合规范本身，并能作为开发者参考的模板。

## 2. 技术实现方案

将遵循以下步骤来产出最终的规范文档：

1.  **结构设计**：将规范文档分为不同章节，如“目录结构”、“命名规范”、“API Handler 规范”、“数据传输对象 (DTO)”、“错误处理”等。
2.  **内容撰写**：在每个章节中，详细描述具体的规则，并提供从 `admin` 模块中提取的**正例代码**作为示范。
3.  **规则提炼**：将观察到的模式提炼为必须遵守的规则，例如：
    *   每个 API Handler 必须返回 `core.HandlerFunc`。
    *   使用 `ctx.ShouldBindJSON()` 进行参数绑定和基础校验。
    *   通过 `ctx.AbortWithError()` 统一处理错误。
    *   使用 `ctx.Payload()` 返回成功响应。
    *   请求和响应结构体必须包含 `json` tag，并提供清晰的字段注释。
    *   必须为每个 API 编写完整的 Swagger 注解。
4.  **文档生成**：将所有内容整合到 `docs/开发规范.md` 文件中。

## 3. 任务边界限制

*   **仅限于文档**：此任务不涉及任何代码的创建、修改或删除。
*   **聚焦于 API 层**：规范主要针对 `internal/api` 层的开发，对于 `service` 层和 `repository` 层的规范，虽然可以借鉴其思想，但不是本次任务的重点。
*   **基于现有实践**：所有规范都必须源于对现有 `admin` 代码的分析，不允许凭空创造规则。

## 4. 确认所有不确定性已解决

通过 `ALIGNMENT` 阶段的分析，所有关于任务目标、范围和方法的不确定性均已解决。现在可以进入 `Architect`（架构）阶段，设计最终规范文档的详细结构。