# API 接口文档模板

> 复制此文件，命名为 {module}-api.md，记录该模块对外暴露的 REST 接口。

---

## 模块信息
- **模块名**：{模块中文名} / {module}
- **Controller**：`{功能}RestController`
- **@eo.groupName**：`{一级模块}.{二级模块}`
- **@eo.path（base）**：`/{模块}/{资源}`
- **文件路径**：`other-adapter/src/.../adapter/app/{模块}/{功能}RestController.java`

---

## 接口列表

### 1. {接口名称}

```java
/**
 * {接口说明}.
 *
 * @eo.name {接口名称}
 * @eo.url {子路径，GET无子路径时留空}
 * @eo.method get
 * @eo.request-type formdata
 */
@GetMapping("/{sub-path}")
public {返回CO或DTO} {methodName}({QryCmd} cmd) {
    return {service}.{method}(cmd);
}
```

**请求参数（QryCmd 字段）**：
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| userId | Long | 否 | 目标用户ID（不传则取当前登录用户） |

**响应（CO 字段）**：
| 字段 | 类型 | 说明 |
|------|------|------|
| userId | Long | 用户ID |
| nickname | String | 昵称 |

---

### 2. {写操作接口名称}

```java
/**
 * {接口说明}.
 *
 * @eo.name {接口名称}
 * @eo.url /{sub-path}
 * @eo.method post
 * @eo.request-type json
 */
@PostMapping("/{sub-path}")
public {返回CO} {methodName}(@RequestBody @Validated {Cmd} cmd) {
    return {service}.{method}(cmd);
}
```

**请求体（Cmd 字段）**：
| 字段 | 类型 | 必填 | 校验 | 说明 |
|------|------|------|------|------|
| activityId | Long | 是 | @NotNull | 活动ID |
| drawCount | Integer | 否 | @Min(1) @Max(10) | 抽奖次数 |

**响应（CO 字段）**：
| 字段 | 类型 | 说明 |
|------|------|------|
| prizeId | Long | 奖品ID |
| prizeName | String | 奖品名称 |

---

## 枚举值说明

| 枚举类 | 值 | 说明 |
|-------|----|------|
| StatusEnum | 0 | 正常 |
| StatusEnum | 1 | 禁用 |

---

## 关联文件
- Service 接口：`other-client/src/.../app/service/{模块}/{功能}Service.java`
- Cmd：`other-client/src/.../app/dto/cmd/{模块}/`
- CO：`other-client/src/.../app/dto/clientobject/{模块}/`
- CmdExe：`other-application/src/.../app/command/{模块}/`