API 文档:【模块名称】

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

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

一、通用约定

基础路径:/api/v1
鉴权方式:Authorization header(Bearer token) / Parse 会话

统一响应格式:

{ "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
权限:登录用户 / 指定角色
请求体:
```
{
"name": "名称",
"type": "typeA"
}
```

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

成功响应:

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

失败响应:

{ "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	首次创建