# API 文档:【模块名称】

> 文档元数据(每次修改必须更新)

| 字段 | 值 |
|---|---|
| 版本号 | v1.0 |
| 最后更新日期 | YYYY-MM-DD |
| 状态 | 草稿 / 评审 / 生效 / 废弃 |
| 本次变更原因 | 首次创建 / 接口变更(说明) |

## 一、通用约定

- 基础路径:`/api/v1`
- 鉴权方式:Authorization header(Bearer token) / Parse 会话
- 统一响应格式:

```json
{ "code": 0, "message": "success", "data": {} }
```

- 分页参数:统一 `page`(从 1 起)、`pageSize`(默认 10,最大 100);返回 `{ list, total, page, pageSize }`
- 时间格式:ISO 8601 字符串(UTC)

## 二、错误码表(分段登记,新增必须补充)

| 错误码 | HTTP 状态 | 含义 |
|---|---|---|
| 0 | 200 | 成功 |
| 10001 | 401 | 未登录/会话失效 |
| 10002 | 403 | 无权限 |
| 10003 | 400 | 参数校验失败 |
| 20001 | 400 | 业务错误:XXX |
| 20002 | 409 | 数据冲突:XXX |
| 30000 | 500 | 系统错误 |

> 错误码分段:10xxx 用户域 / 20xxx 业务域 / 30xxx 系统域。

## 三、接口列表

### 3.1 创建资源

- **方法**:`POST /api/v1/resources`
- **权限**:登录用户 / 指定角色
- **请求体**:

```json
{
  "name": "名称",
  "type": "typeA"
}
```

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| name | string | 是 | 长度 1-50 |
| type | string | 是 | 枚举:typeA/typeB |

- **成功响应**:

```json
{ "code": 0, "message": "success", "data": { "id": "xxx" } }
```

- **失败响应**:

```json
{ "code": 20001, "message": "名称已存在", "data": null }
```

- **验收关联**:AC-01(对应 PRD 编号)

### 3.2 查询列表

- **方法**:`GET /api/v1/resources?page=1&pageSize=10&status=active`
- **权限**:登录用户
- **查询参数**:

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| page | number | 否 | 默认 1 |
| pageSize | number | 否 | 默认 10,最大 100 |
| status | string | 否 | 过滤状态 |

- **成功响应**:见通用约定

## 四、变更历史

| 版本 | 日期 | 变更内容 | 变更原因 |
|---|---|---|---|
| v1.0 | YYYY-MM-DD | 首次创建 | |