---
sync_policy: engine_only
---
# {{ModuleName}} API 契约文档

> 自动生成于 {{date}} | 风险等级: {{riskLevel}} | 复杂度: {{complexityLevel}}

## 基础信息

- 模块名: {{ModuleName}}
- 基路径: `{{basePath}}`
- 版本: {{apiVersion}}

## 接口列表

### 1. 查询 {{ModuleName}} 列表

```
GET {{basePath}}
```

**请求参数:**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码，默认 1 |
| size | int | 否 | 每页条数，默认 20，最大 100 |

**响应示例:**

```json
{
  "records": [],
  "total": 0,
  "page": 1,
  "size": 20,
  "totalPages": 0
}
```

### 2. 查询 {{ModuleName}} 详情

```
GET {{basePath}}/{id}
```

**路径参数:**

| 参数 | 类型 | 说明 |
|------|------|------|
| id | Long | 记录 ID |

**响应示例:**

```json
{
  "id": 1,
  "createdAt": "2026-01-01T00:00:00",
  "updatedAt": "2026-01-01T00:00:00"
}
```

### 3. 创建 {{ModuleName}}

```
POST {{basePath}}
```

**请求体:**

```json
{
}
```

**响应:** 创建成功的对象（含 id）

### 4. 更新 {{ModuleName}}

```
PUT {{basePath}}/{id}
```

**请求体:** 同创建请求体

**响应:** 更新后的对象

### 5. 删除 {{ModuleName}}

```
DELETE {{basePath}}/{id}
```

**响应:** 204 No Content

## 错误码

| 错误码 | 说明 |
|--------|------|
| {{MODULE_NAME}}_001 | {{ModuleName}} 不存在 |
| {{MODULE_NAME}}_002 | {{ModuleName}} 已存在 |
| {{MODULE_NAME}}_003 | 参数校验失败 |
| {{MODULE_NAME}}_004 | 操作失败 |

## 通用错误响应格式

```json
{
  "code": "ERROR_CODE",
  "message": "错误描述",
  "timestamp": "2026-01-01T00:00:00"
}
```