{项目名称} - API接口文档

{客户端名称}端与管理端接口定义。固定顺序：接口架构 -> 架构总览 -> 接口详情（功能点、输入参数、输出参数）-> 统计。

1. 接口架构与规范

接口详情必须包含：功能点介绍、输入参数（Header/Path/Query/Body）、输出参数、请求/响应示例。

基本信息

Base URL	以实际部署为准（如 `https://api.xxx.com`）
协议	HTTPS
数据格式	JSON
字符编码	UTF-8
认证方式	Bearer Token（JWT）

通用响应格式

{
  "code": 1000,
  "message": "success",
  "data": {}
}

错误码说明

错误码	说明
1000	成功
1001	请求参数错误
1002	未授权（Token无效或过期）
1003	权限不足
1004	资源不存在
1005	服务器内部错误

2. 接口架构总览

模块	功能点	端口范围	方法	路径	鉴权	状态
{模块A名称}	{功能点A1}	{客户端名称}端	GET	`/app/{模块前缀}/{资源}/list`	是	已实现
{模块A名称}	{功能点A2}	管理后台	POST	`/admin/{模块前缀}/{资源}/page`	是	已实现
{模块B名称}	{功能点B1}	{客户端名称}端	POST	`/app/{模块前缀}/{资源}/add`	是	待开发

3. 接口详情（功能点 + 输入参数 + 输出参数）

GET /app/{模块前缀}/{资源}/list 已实现

{资源}列表

功能点{功能点A1}

功能点介绍{例如：支持关键词筛选并分页返回资源列表}

业务端{客户端名称}端

文件路径modules/{模块}/controller/app/{资源}.ts

输入参数（固定列顺序）

参数名	位置	类型	必填	默认值	示例	说明
Authorization	Header	string	是	-	Bearer xxx	用户令牌
shopId	Query	number	否	0	1001	门店ID
keyword	Query	string	否	空字符串	牛奶	搜索关键词
page	Query	number	否	1	1	页码
size	Query	number	否	20	20	每页条数

输出参数（固定列顺序）

字段	类型	必返	示例	说明
code	number	是	1000	业务状态码
message	string	是	success	提示信息
data.list	array	是	[]	列表数据
data.list[].id	number	是	1	ID
data.pagination.total	number	是	120	总条数

示例请求

GET /app/{模块前缀}/{资源}/list?shopId=1001&page=1&size=20
Authorization: Bearer <token>

示例响应

{
  "code": 1000,
  "message": "success",
  "data": {
    "list": [{ "id": 1, "name": "示例名称" }],
    "pagination": { "page": 1, "size": 20, "total": 120 }
  }
}

POST /app/{模块前缀}/{资源}/add 待开发

新增{资源}

功能点{功能点A2}

功能点介绍{例如：创建新记录并返回主键}

业务端{客户端名称}端

预计文件modules/{模块}/controller/app/{资源}.ts

输入参数（固定列顺序）

参数名	位置	类型	必填	默认值	示例	说明
Authorization	Header	string	是	-	Bearer xxx	用户令牌
name	Body	string	是	-	会员活动A	名称
remark	Body	string	否	空字符串	活动描述	备注

输出参数（固定列顺序）

字段	类型	必返	示例	说明
code	number	是	1000	业务状态码
message	string	是	success	提示信息
data.id	number	是	10086	新增记录主键

4. 待开发类与方法

Entity 实体类

modules/{模块}/entity/{资源}.ts (待创建)
- {EntityPrefix}{资源名}Entity
  - id: number - 主键
  - shopId: number - 门店ID
  - userId: number - 用户ID
  - name: string - 名称
  - status: number - 状态
  - createTime: Date - 创建时间
  - updateTime: Date - 更新时间

Service 服务类

modules/{模块}/service/{资源}.ts (待创建)
- {EntityPrefix}{资源名}Service extends BaseService
  - add(dto) - 新增
  - page(query) - 分页查询
  - info(id) - 获取详情
  - update(dto) - 修改
  - delete(ids) - 删除

Controller 控制器

modules/{模块}/controller/app/{资源}.ts (待创建)
- {EntityPrefix}App{资源名}Controller
  - @Post('/add') add()
  - @Post('/page') page()
  - @Get('/info') info()

modules/{模块}/controller/admin/{资源}.ts (待创建)
- {EntityPrefix}Admin{资源名}Controller
  - @Post('/page') page()
  - @Get('/info') info()
  - @Post('/update') update()
  - @Post('/delete') delete()

5. 接口统计

{已实现数}

已实现

{待开发数}

待开发

{待扩展数}

待扩展

端口范围	已实现	待开发	待扩展	合计
{客户端名称}端	{已实现数}	{待开发数}	{待扩展数}	{总数}
管理后台	{已实现数}	{待开发数}	{待扩展数}	{总数}

文档版本：v1.1 · {更新日期}

← 返回文档总览

6. JSON契约驱动接口清单

统一数据源：doc/data/api-contract.json；测试核心代码按 Postman/Apifox 规范，默认折叠。