# DESIGN: 开发规范文档设计

本文档定义了最终 `docs/开发规范.md` 的结构和核心内容，旨在为后续的文档撰写提供清晰的蓝图。

## 1. 整体结构

最终的开发规范文档将分为以下几个核心章节，每个章节都将包含详细的规则描述和代码示例。

```mermaid
graph TD
    A[开发规范] --\u003e B[1. 概述];
    A --\u003e C[2. 目录与文件结构];
    A --\u003e D[3. 命名规范];
    A --\u003e E[4. API Handler 规范];
    A --\u003e F[5. 数据传输对象 (DTO) 规范];
    A --\u003e G[6. 错误处理规范];
    A --\u003e H[7. 日志记录规范];
    A --\u003e I[8. 注释与文档(Swagger)];

    subgraph E [4. API Handler 规范]
        E1[4.1 Handler 定义]
        E2[4.2 路由与函数签名]
        E3[4.3 参数绑定与校验]
        E4[4.4 业务逻辑调用]
        E5[4.5 响应处理]
    end

    subgraph F [5. 数据传输对象 (DTO) 规范]
        F1[5.1 Request/Response 结构体]
        F2[5.2 JSON Tags]
        F3[5.3 Validation Tags]
    end
```

## 2. 核心章节设计

### 2.1 概述
*   **目的**：阐明制定此规范的背景和目标。
*   **范围**：明确规范的适用范围（API 层）。
*   **原则**：强调代码清晰、一致、可维护的核心原则。

### 2.2 目录与文件结构
*   **规则**：
    *   API 功能模块应在 `internal/api/{模块名}` 下创建独立目录。
    *   每个目录包含 `*.go` 文件，每个文件实现一个独立的 API 端点。
    *   `{模块名}.go` 文件用于定义 `handler` 结构体和 `New` 初始化函数。
*   **示例**：以 `admin` 模块为例，展示其目录结构。

### 2.3 命名规范
*   **规则**：
    *   Handler 文件名：使用小写蛇形命名法，如 `login.go`, `admin_create.go`。
    *   请求/响应结构体：使用驼峰式命名，并以 `Request`/`Response` 结尾，如 `loginRequest`, `loginResponse`。
    *   Handler 函数：使用驼峰式命名，如 `Login()`, `CreateAdmin()`。

### 2.4 API Handler 规范
*   **Handler 定义**：`handler` 结构体应包含 `logger` 和数据库连接（`readDB`, `writeDB`）。
*   **路由与函数签名**：Handler 函数必须返回 `core.HandlerFunc` 类型。
*   **参数绑定与校验**：必须使用 `ctx.ShouldBindJSON()` 进行参数绑定，并结合 `validation` 包进行错误信息格式化。
*   **业务逻辑调用**：通过 `h.readDB` 或 `h.writeDB` 与数据库交互，或调用 `service` 层方法。
*   **响应处理**：成功时使用 `ctx.Payload(res)` 返回数据。

### 2.5 数据传输对象 (DTO) 规范
*   **Request/Response 结构体**：每个 API 都应定义独立的请求和响应结构体。
*   **JSON Tags**：所有结构体字段必须包含 `json:"..."` tag。
*   **Validation Tags**：对需要校验的请求字段，必须添加 `binding:"..."` tag。

### 2.6 错误处理规范
*   **规则**：必须使用 `ctx.AbortWithError(core.Error(...))` 来中断请求并返回标准格式的错误。
*   **`core.Error` 参数**：需提供 HTTP 状态码、业务错误码 (`code.Code`) 和详细错误信息。

### 2.7 日志记录规范
*   **规则**：通过注入的 `h.logger` 实例进行日志记录（虽然在 `admin` 示例中不明显，但这是标准实践）。

### 2.8 注释与文档 (Swagger)
*   **规则**：
    *   每个 Handler 函数上方必须有完整的 Swagger 注解，包括 `@Summary`, `@Description`, `@Tags`, `@Param`, `@Success`, `@Failure`, `@Router` 等。
    *   所有 DTO 字段和函数都应有清晰的中文注释。

## 3. 数据流与接口契约

本文档本身不定义新的数据流或接口，而是规范如何定义它们。其核心思想是：**通过严格的结构体和规范化的错误处理，确保所有 API 的接口契约都是明确和一致的。**