# 商品寄卖服务系统管理后台API接口PRD（完整版）

## 1. 项目概述

### 1.1 项目背景
商品寄卖服务系统是一个提供商品寄卖、交易、物流管理和财务管理的综合性平台。管理后台API接口文档旨在规范系统前后端交互，确保系统各功能模块的正常运行。

### 1.2 参考系统管理后台
- **系统地址**：https://miao1admin.suzhouyuqi.com/app/admin#
- **登录账号**：admin
- **登录密码**：A123456

### 1.3 文档目的
本文档详细描述管理后台的API接口规范、接口功能、请求参数、响应格式等信息，为前后端开发人员提供统一的接口参考标准。

### 1.4 术语定义
- **管理员**：系统后台操作人员，拥有不同权限
- **用户**：平台注册用户，可进行购买、寄售等操作
- **自营商品**：平台直接销售的商品
- **寄售商品**：用户委托平台销售的二手商品
- **转拍**：用户购买商品后再次上架销售的行为
- **提现**：用户将账户余额提取到银行卡或支付宝的操作
- **优惠券**：平台发放的虚拟货币
- **个人奖金**：用户自己交易获得的奖励
- **推广奖金**：用户邀请他人消费获得的返佣

---

## 2. API接口设计规范

### 2.1 接口URL规范
- **基础路径**：`https://miao1admin.suzhouyuqi.com/app/admin`
- **模块划分**：`/模块名/操作`，如`/user/select`
- **HTTP方法**：GET（查询）、POST（新增/修改）、DELETE（删除）

### 2.2 请求头规范
```
X-Requested-With: XMLHttpRequest
Content-Type: application/json (POST请求)
Accept: application/json, text/javascript, */*; q=0.01
```
- 认证信息：通过session/cookie机制实现身份验证

### 2.3 响应格式规范
- **统一JSON格式响应**
- **标准响应结构**：
```json
{
  "code": 0,          // 状态码：0成功，非0失败
  "msg": "ok",        // 响应消息
  "data": {},         // 数据主体（可以是对象或数组）
  "count": 100        // 分页数据总数（可选，仅列表接口返回）
}
```

### 2.4 错误码规范
| 错误码 | 说明 |
|--------|------|
| 0 | 成功 |
| 非0 | 失败，具体错误信息在msg字段中返回 |

### 2.5 分页参数规范
所有列表查询接口统一使用以下分页参数：
- `page`: 页码，从1开始
- `limit`: 每页记录数，默认10条

### 2.6 搜索条件规范
搜索条件支持数组格式，第一个元素为操作符，第二个元素为值：
- `字段名[0]`: 操作符（like、=、>、<、>=、<=、between等）
- `字段名[1]`: 搜索值
- 示例：`mobile[0]=like&mobile[1]=138` 表示手机号模糊查询

### 2.7 日期范围查询规范
日期范围查询使用数组格式：
- `字段名[0]`: 开始日期
- `字段名[1]`: 结束日期
- 示例：`created_at[0]=2025-01-01&created_at[1]=2025-12-31`

---

## 3. 核心API接口详细说明

### 3.1 用户管理模块 (user)

#### 3.1.1 用户列表查询
- **接口URL**：`/app/admin/user/select`
- **请求方法**：GET
- **功能描述**：查询用户列表，支持分页和多种筛选条件
- **请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | int | 否 | 页码，默认1 |
| limit | int | 否 | 每页记录数，默认10 |
| id | int | 否 | 用户ID（精确查询） |
| mobile | string | 否 | 手机号（模糊查询） |
| pid | int | 否 | 推荐人ID |
| username | string | 否 | 用户名 |
| status | int | 否 | 状态：0=禁用，1=启用 |
| is_vip | int | 否 | 是否VIP：0=否，1=是 |

- **请求示例**：
```
GET /app/admin/user/select?page=1&limit=10&id=&mobile=&pid=
```

- **响应数据**：
```json
{
  "code": 0,
  "msg": "ok",
  "count": 469,
  "data": [
    {
      "id": 92697,
      "pid": 92679,
      "username": "15324401200",
      "nickname": "153****1259",
      "mobile": "15324401200",
      "sex": "1",
      "avatar": "/app/admin/avatar.png",
      "invite": "el0yw1",
      "level": 1,
      "birthday": null,
      "money": "0.000",
      "coupon": "0.000",
      "self_bonus": "0.000",
      "share_bonus": "0.000",
      "score": 0,
      "last_time": "2025-11-13 14:17:00",
      "last_ip": "116.230.253.100",
      "join_time": "2025-11-13 14:15:44",
      "join_ip": "116.230.253.100",
      "status": 1,
      "viptime": null,
      "is_vip": 1,
      "contract": "https://contract.test.kywtwl.com/upload/contract/1753363479/xieyi.pdf",
      "max_order": 3,
      "is_resell": 1,
      "yesterday_sell_count": 0,
      "today_buy_count": 1,
      "today_buy_total": "29805.86",
      "today_sell_total": 0,
      "poor": -29805.86,
      "pname": "潘1陈1勇",
      "created_at": "2025-11-13 14:15:44",
      "updated_at": "2025-11-13 16:13:34"
    }
  ]
}
```

#### 3.1.2 用户详情查询
- **接口URL**：`/app/admin/user/select`
- **请求方法**：GET
- **功能描述**：查询单个用户详细信息
- **请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | int | 是 | 用户ID |

- **请求示例**：
```
GET /app/admin/user/select?id=92697
```

- **响应数据**：返回单个用户对象（结构同上）

#### 3.1.3 用户信息更新
- **接口URL**：`/app/admin/user/update`
- **请求方法**：POST
- **功能描述**：更新用户信息
- **请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | int | 是 | 用户ID |
| nickname | string | 否 | 昵称 |
| mobile | string | 否 | 手机号 |
| status | int | 否 | 状态：0=禁用，1=启用 |
| is_vip | int | 否 | 是否VIP：0=否，1=是 |
| viptime | datetime | 否 | VIP截止时间 |
| max_order | int | 否 | 最高可抢单数 |
| is_resell | int | 否 | 是否可转拍：0=否，1=是 |
| money | decimal | 否 | 余额 |
| coupon | decimal | 否 | 优惠券余额 |
| self_bonus | decimal | 否 | 个人奖金 |
| share_bonus | decimal | 否 | 推广奖金 |
| password | string | 否 | 新密码（明文） |

- **请求示例**：
```
POST /app/admin/user/update
Content-Type: application/x-www-form-urlencoded

id=92697&status=1&is_vip=1&max_order=6
```

- **响应数据**：
```json
{
  "code": 0,
  "msg": "ok",
  "data": []
}
```

---

### 3.2 商品管理模块 (merchandise)

#### 3.2.1 寄售商品列表查询
- **接口URL**：`/app/admin/merchandise/select`
- **请求方法**：GET
- **功能描述**：查询寄售商品列表
- **请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | int | 否 | 页码，默认1 |
| limit | int | 否 | 每页记录数，默认10 |
| id | int | 否 | 商品ID |
| user_id | int | 否 | 卖家用户ID |
| title | string | 否 | 商品标题（模糊查询） |
| status | int | 否 | 状态：0=已售，1=未售 |
| is_show | int | 否 | 是否显示：0=隐藏，1=显示 |

- **请求示例**：
```
GET /app/admin/merchandise/select?page=1&limit=10
```

- **响应数据**：
```json
{
  "code": 0,
  "msg": "ok",
  "count": 50,
  "data": [
    {
      "id": 144753,
      "old_id": 0,
      "user_id": 92166,
      "title": "商品标题",
      "image": "[\"url1\",\"url2\"]",
      "price": "1000.00",
      "is_show": 1,
      "status": 1,
      "created_at": "2025-11-13 10:00:00",
      "updated_at": "2025-11-13 10:00:00",
      "username": "用户昵称"
    }
  ]
}
```

#### 3.2.2 寄售商品详情查询
- **接口URL**：`/app/admin/merchandise/select`
- **请求方法**：GET
- **功能描述**：查询单个寄售商品详情
- **请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | int | 是 | 商品ID |

- **请求示例**：
```
GET /app/admin/merchandise/select?id=144753
```

#### 3.2.3 寄售商品更新
- **接口URL**：`/app/admin/merchandise/update`
- **请求方法**：POST
- **功能描述**：更新寄售商品信息（主要用于审核和上下架）
- **请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | int | 是 | 商品ID |
| is_show | int | 否 | 是否显示：0=隐藏，1=显示 |
| status | int | 否 | 状态：0=已售，1=未售 |
| price | decimal | 否 | 寄售价格 |

- **请求示例**：
```
POST /app/admin/merchandise/update
Content-Type: application/x-www-form-urlencoded

id=144753&is_show=1
```

- **响应数据**：
```json
{
  "code": 0,
  "msg": "ok",
  "data": []
}
```

---

### 3.3 订单管理模块 (order)

#### 3.3.1 订单列表查询
- **接口URL**：`/app/admin/order/select`
- **请求方法**：GET
- **功能描述**：查询订单列表，支持多种筛选条件
- **请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | int | 否 | 页码，默认1 |
| limit | int | 否 | 每页记录数，默认10 |
| order_sn[0] | string | 否 | 订单号搜索方式（like） |
| order_sn[1] | string | 否 | 订单号 |
| seller_id | int | 否 | 卖家ID |
| buyer_id | int | 否 | 买家ID |
| status | int | 否 | 订单状态：0=待付款，1=已支付，2=已完成 |
| is_resell | int | 否 | 是否转拍：0=否，1=是 |
| is_cancel | int | 否 | 是否取消：0=否，1=是 |
| is_show | int | 否 | 是否显示：0=隐藏，1=显示 |
| buy_time[0] | datetime | 否 | 购买开始时间 |
| buy_time[1] | datetime | 否 | 购买结束时间 |
| confirm_time[0] | datetime | 否 | 确认开始时间 |
| confirm_time[1] | datetime | 否 | 确认结束时间 |

- **请求示例**：
```
GET /app/admin/order/select?page=1&limit=50&order_sn[0]=like&order_sn[1]=&seller_id=&buyer_id=&status=&is_resell=&is_cancel=&is_show=&buy_time[0]=&buy_time[1]=&confirm_time[0]=&confirm_time[1]=
```

- **响应数据**：
```json
{
  "code": 0,
  "msg": "ok",
  "count": 100,
  "data": [
    {
      "id": 12345,
      "old_id": 0,
      "seller_id": 0,
      "buyer_id": 92697,
      "order_sn": "79629117630147968611",
      "total_money": "1000.00",
      "pay_time": "2025-11-13 10:00:00",
      "pay_img": "",
      "status": 1,
      "is_resell": 0,
      "is_show": 1,
      "is_cancel": 0,
      "consignee": "张三",
      "phone": "13800138000",
      "province": "江苏省",
      "city": "苏州市",
      "area": "工业园区",
      "address": "详细地址",
      "merchandise_id": 0,
      "confirm_time": null,
      "buy_time": "2025-11-13 09:00:00",
      "buy_ip": "192.168.1.1",
      "cancel_ip": "",
      "created_at": "2025-11-13 09:00:00",
      "updated_at": "2025-11-13 10:00:00",
      "seller_name": "平台",
      "buyer_name": "张三"
    }
  ]
}
```

#### 3.3.2 订单详情查询
- **接口URL**：`/app/admin/order/select`
- **请求方法**：GET
- **功能描述**：查询单个订单详情
- **请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | int | 是 | 订单ID |

#### 3.3.3 订单更新
- **接口URL**：`/app/admin/order/update`
- **请求方法**：POST
- **功能描述**：更新订单状态
- **请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | int | 是 | 订单ID |
| status | int | 否 | 订单状态：0=待付款，1=已支付，2=已完成 |
| is_show | int | 否 | 是否显示：0=隐藏，1=显示 |
| is_cancel | int | 否 | 是否取消：0=否，1=是 |

- **请求示例**：
```
POST /app/admin/order/update
Content-Type: application/x-www-form-urlencoded

id=12345&status=2
```

- **响应数据**：
```json
{
  "code": 0,
  "msg": "ok",
  "data": []
}
```

---

### 3.4 提现管理模块 (withdraw)

#### 3.4.1 提现列表查询
- **接口URL**：`/app/admin/withdraw/select`
- **请求方法**：GET
- **功能描述**：查询提现申请列表
- **请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | int | 否 | 页码，默认1 |
| limit | int | 否 | 每页记录数，默认10 |
| transfer_no[0] | string | 否 | 提现编号搜索方式（like） |
| transfer_no[1] | string | 否 | 提现编号 |
| user_id | int | 否 | 用户ID |
| cate | int | 否 | 提现类型：2=优惠券，4=推广奖金 |
| account_type | int | 否 | 账号类型：1=银行卡，2=支付宝 |
| status | int | 否 | 状态：0=待审核，1=通过，2=驳回 |
| created_at[0] | datetime | 否 | 申请开始时间 |
| created_at[1] | datetime | 否 | 申请结束时间 |
| updated_at[0] | datetime | 否 | 处理开始时间 |
| updated_at[1] | datetime | 否 | 处理结束时间 |

- **请求示例**：
```
GET /app/admin/withdraw/select?page=1&limit=10&transfer_no[0]=like&transfer_no[1]=&cate=4&account_type=&status=&created_at[0]=&created_at[1]=&updated_at[0]=&updated_at[1]=
```

- **响应数据**：
```json
{
  "code": 0,
  "msg": "ok",
  "count": 50,
  "data": [
    {
      "id": 4457,
      "transfer_no": "W202511130001",
      "user_id": 92697,
      "cate": 4,
      "account_type": 2,
      "account_id": 123,
      "account_info": "{\"username\":\"张三\",\"account\":\"138****8000\"}",
      "money": "100.00",
      "handling_fee": "1.00",
      "actual_amount": "99.00",
      "status": 0,
      "remark": "",
      "created_at": "2025-11-13 10:00:00",
      "updated_at": "2025-11-13 10:00:00",
      "username": "张三",
      "mobile": "13800138000"
    }
  ]
}
```

#### 3.4.2 提现详情查询
- **接口URL**：`/app/admin/withdraw/select`
- **请求方法**：GET
- **功能描述**：查询单个提现申请详情
- **请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | int | 是 | 提现记录ID |

#### 3.4.3 提现审核
- **接口URL**：`/app/admin/withdraw/update`
- **请求方法**：POST
- **功能描述**：审核提现申请
- **请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | int | 是 | 提现记录ID |
| status | int | 是 | 状态：1=通过，2=驳回 |
| remark | string | 否 | 审核备注（驳回时必填原因） |

- **请求示例**：
```
POST /app/admin/withdraw/update
Content-Type: application/x-www-form-urlencoded

id=4457&status=1&remark=审核通过
```

- **响应数据**：
```json
{
  "code": 0,
  "msg": "ok",
  "data": []
}
```

---

### 3.5 财务日志管理模块

#### 3.5.1 优惠券日志查询
- **接口URL**：`/app/admin/coupon-log/select`
- **请求方法**：GET
- **功能描述**：查询优惠券发放和使用日志
- **请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | int | 否 | 页码，默认1 |
| limit | int | 否 | 每页记录数，默认10 |
| user_id | int | 否 | 用户ID |
| type | int | 否 | 类型：1=收入，2=支出，3=提现驳回 |
| memo[0] | string | 否 | 备注搜索方式（like） |
| memo[1] | string | 否 | 备注内容 |
| created_at[0] | datetime | 否 | 开始时间 |
| created_at[1] | datetime | 否 | 结束时间 |

- **请求示例**：
```
GET /app/admin/coupon-log/select?page=1&limit=10&user_id=&type=1&memo[0]=like&memo[1]=&created_at[0]=&created_at[1]=
```

- **响应数据**：
```json
{
  "code": 0,
  "msg": "ok",
  "count": 100,
  "data": [
    {
      "id": 1,
      "user_id": 92697,
      "type": 1,
      "money": "10.000",
      "before": "0.000",
      "after": "10.000",
      "memo": "系统发放",
      "created_at": "2025-11-13 10:00:00",
      "updated_at": "2025-11-13 10:00:00",
      "username": "张三",
      "mobile": "13800138000"
    }
  ]
}
```

#### 3.5.2 个人奖金日志查询
- **接口URL**：`/app/admin/selfbonus-log/select`
- **请求方法**：GET
- **功能描述**：查询个人奖金变动日志
- **请求参数**：（同优惠券日志）

#### 3.5.3 推广奖金日志查询
- **接口URL**：`/app/admin/sharebonus-log/select`
- **请求方法**：GET
- **功能描述**：查询推广奖金变动日志
- **请求参数**：（同优惠券日志，type支持：1=收入，2=支出，3=提现驳回）

---

### 3.6 系统管理模块

#### 3.6.1 获取系统配置
- **接口URL**：`/app/admin/setting/index`
- **请求方法**：GET
- **功能描述**：获取系统配置信息
- **请求参数**：无

- **响应数据**：
```json
{
  "code": 0,
  "msg": "ok",
  "data": ["*"]
}
```

#### 3.6.2 获取系统设置
- **接口URL**：`/app/admin/setting/get`
- **请求方法**：GET
- **功能描述**：获取系统设置详情
- **请求参数**：无

- **响应数据**：返回系统设置的键值对列表

#### 3.6.3 更新系统设置
- **接口URL**：`/app/admin/setting/update`
- **请求方法**：POST
- **功能描述**：更新系统设置
- **请求参数**：键值对形式，根据具体设置项而定

#### 3.6.4 获取菜单配置
- **接口URL**：`/app/admin/rule/get`
- **请求方法**：GET
- **功能描述**：获取系统菜单配置
- **请求参数**：无

- **响应数据**：
```json
{
  "logo": {
    "title": "采贪平台",
    "image": "/app/admin/admin/images/logo.png"
  },
  "menu": {
    "data": "/app/admin/rule/get",
    "method": "GET",
    "accordion": true,
    "collapse": false,
    "control": false,
    "controlWidth": 500,
    "select": "0",
    "async": true
  },
  "tab": {
    "enable": true,
    "keepState": true,
    "preload": false,
    "session": false,
    "max": "30",
    "index": {
      "id": "8",
      "href": "/app/admin/user/index",
      "title": "用户管理"
    }
  },
  "theme": {
    "defaultColor": "2",
    "defaultMenu": "light-theme",
    "defaultHeader": "light-theme",
    "allowCustom": true,
    "banner": false
  },
  "colors": [
    {"id": "1", "color": "#36b368", "second": "#f0f9eb"},
    {"id": "2", "color": "#2d8cf0", "second": "#ecf5ff"},
    {"id": "3", "color": "#f6ad55", "second": "#fdf6ec"},
    {"id": "4", "color": "#f56c6c", "second": "#fef0f0"},
    {"id": "5", "color": "#3963bc", "second": "#ecf5ff"}
  ],
  "other": {
    "keepLoad": "500",
    "autoHead": false,
    "footer": false
  },
  "header": {
    "message": false
  }
}
```

#### 3.6.5 获取系统配置（通用）
- **接口URL**：`/app/admin/config/get`
- **请求方法**：GET
- **功能描述**：获取系统通用配置
- **请求参数**：无

#### 3.6.6 获取账户信息
- **接口URL**：`/app/admin/account/info`
- **请求方法**：GET
- **功能描述**：获取当前登录管理员账户信息
- **请求参数**：无

- **响应数据**：
```json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": 1,
    "username": "admin",
    "nickname": "管理员",
    "avatar": "/app/admin/avatar.png",
    "email": "admin@example.com",
    "mobile": "13800138000",
    "login_at": "2025-11-13 08:00:00"
  }
}
```

---

## 4. 数据库表结构参考

### 4.1 用户表（wa_users）

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | int | 用户ID |
| pid | int | 推荐人ID |
| username | varchar | 用户名 |
| nickname | varchar | 昵称 |
| mobile | varchar | 手机号 |
| password | varchar | 密码（加密） |
| salt | varchar | 密码盐 |
| sex | enum | 性别：0=女，1=男 |
| avatar | varchar | 头像URL |
| invite | varchar | 邀请码 |
| level | tinyint | 用户等级 |
| birthday | date | 生日 |
| money | decimal | 余额 |
| coupon | decimal | 优惠券余额 |
| self_bonus | decimal | 个人奖金 |
| share_bonus | decimal | 推广奖金 |
| score | int | 积分 |
| last_time | datetime | 最后登录时间 |
| last_ip | varchar | 最后登录IP |
| join_time | datetime | 注册时间 |
| join_ip | varchar | 注册IP |
| token | varchar | 登录Token |
| status | tinyint | 状态：0=禁用，1=启用 |
| is_vip | tinyint | 是否VIP：0=否，1=是 |
| viptime | datetime | VIP截止时间 |
| contract | varchar | 合同文件 |
| max_order | int | 最高可抢单数 |
| is_resell | tinyint | 是否可转拍：0=否，1=是 |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |

### 4.2 寄售商品表（wa_merchandise）

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | int | 主键ID |
| old_id | int | 从订单转拍过来的原订单ID |
| user_id | int | 卖家用户ID |
| title | varchar | 商品标题 |
| image | varchar | 商品图片（JSON数组） |
| price | decimal | 寄售价格 |
| is_show | tinyint | 是否显示：0=隐藏，1=显示 |
| status | tinyint | 状态：0=已售，1=未售 |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |

### 4.3 订单表（wa_order）

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | int | 订单ID |
| old_id | int | 从订单转拍过来的原订单ID |
| seller_id | int | 卖家ID（0=平台） |
| buyer_id | int | 买家ID |
| order_sn | varchar | 订单号 |
| total_money | decimal | 订单金额 |
| pay_time | datetime | 支付时间 |
| pay_img | varchar | 支付凭证图片 |
| status | tinyint | 状态：0=待付款，1=已支付，2=已完成 |
| is_resell | tinyint | 是否转拍：0=否，1=是 |
| is_show | tinyint | 是否显示：0=隐藏，1=显示 |
| is_cancel | tinyint | 是否取消：0=否，1=是 |
| consignee | varchar | 收货人 |
| phone | varchar | 收货电话 |
| province | varchar | 省份 |
| city | varchar | 城市 |
| area | varchar | 区县 |
| address | varchar | 详细地址 |
| merchandise_id | int | 寄售商品ID |
| confirm_time | datetime | 确认收货时间 |
| buy_time | datetime | 下单抢购时间 |
| buy_ip | varchar | 下单IP |
| cancel_ip | varchar | 取消订单IP |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |

### 4.4 提现表（wa_withdraw）

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | int | 提现记录ID |
| transfer_no | varchar | 提现编号 |
| user_id | int | 用户ID |
| cate | tinyint | 提现类型：2=优惠券，4=推广奖金 |
| account_type | tinyint | 账号类型：1=银行卡，2=支付宝 |
| account_id | int | 收款账号ID |
| account_info | text | 收款账号信息（JSON） |
| money | decimal | 提现金额 |
| handling_fee | decimal | 手续费 |
| actual_amount | decimal | 实际到账金额 |
| status | tinyint | 状态：0=待审核，1=通过，2=驳回 |
| remark | varchar | 备注 |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |

### 4.5 财务日志表（通用结构）

财务日志表包括：
- wa_money_log（余额变动日志）
- wa_coupon_log（优惠券变动日志）
- wa_selfbonus_log（个人奖金变动日志）
- wa_sharebonus_log（推广奖金变动日志）

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | int | 主键ID |
| user_id | int | 用户ID |
| type | tinyint | 类型：1=收入，2=支出，3=提现驳回 |
| money | decimal | 变更金额 |
| before | decimal | 变更前余额 |
| after | decimal | 变更后余额 |
| memo | varchar | 备注说明 |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |

---

## 5. API调用示例

### 5.1 用户列表查询示例

**jQuery AJAX**:
```javascript
$.ajax({
  url: '/app/admin/user/select',
  type: 'GET',
  data: {
    page: 1,
    limit: 10,
    mobile: '138'
  },
  success: function(res) {
    if (res.code === 0) {
      console.log('总记录数：', res.count);
      console.log('用户列表：', res.data);
    } else {
      layer.msg(res.msg);
    }
  }
});
```

**Fetch API**:
```javascript
fetch('/app/admin/user/select?page=1&limit=10', {
  method: 'GET',
  headers: {
    'X-Requested-With': 'XMLHttpRequest'
  }
})
.then(response => response.json())
.then(data => {
  if (data.code === 0) {
    console.log(data.data);
  }
});
```

### 5.2 用户信息更新示例

```javascript
$.ajax({
  url: '/app/admin/user/update',
  type: 'POST',
  data: {
    id: 92697,
    status: 1,
    is_vip: 1,
    max_order: 6
  },
  success: function(res) {
    if (res.code === 0) {
      layer.msg('更新成功');
    } else {
      layer.msg(res.msg);
    }
  }
});
```

### 5.3 订单列表查询示例（带复杂筛选条件）

```javascript
$.ajax({
  url: '/app/admin/order/select',
  type: 'GET',
  data: {
    page: 1,
    limit: 50,
    'order_sn[0]': 'like',
    'order_sn[1]': '796291',
    seller_id: '',
    buyer_id: '',
    status: '',
    is_resell: 1,
    is_cancel: '',
    is_show: '',
    'buy_time[0]': '2025-11-01',
    'buy_time[1]': '2025-11-30',
    'confirm_time[0]': '',
    'confirm_time[1]': ''
  },
  success: function(res) {
    if (res.code === 0) {
      console.log('订单列表：', res.data);
    }
  }
});
```

### 5.4 提现审核示例

```javascript
$.ajax({
  url: '/app/admin/withdraw/update',
  type: 'POST',
  data: {
    id: 4457,
    status: 1,  // 1=通过，2=驳回
    remark: '审核通过'
  },
  success: function(res) {
    if (res.code === 0) {
      layer.msg('审核成功');
      // 刷新列表
      table.reload('withdrawTable');
    } else {
      layer.msg(res.msg);
    }
  }
});
```

### 5.5 寄售商品上下架示例

```javascript
$.ajax({
  url: '/app/admin/merchandise/update',
  type: 'POST',
  data: {
    id: 144753,
    is_show: 1  // 1=显示，0=隐藏
  },
  success: function(res) {
    if (res.code === 0) {
      layer.msg('操作成功');
    } else {
      layer.msg(res.msg);
    }
  }
});
```

---

## 6. 业务流程说明

### 6.1 用户注册流程
1. 用户通过邀请码注册（邀请码关联推荐人）
2. 创建用户记录，生成专属邀请码
3. 初始化财务账户（余额、优惠券、奖金均为0）
4. 记录注册IP和时间

### 6.2 订单交易流程
```
1. 用户下单（创建订单，status=0）
   ↓
2. 用户支付（更新status=1，记录pay_time）
   ↓
3. 卖家发货
   ↓
4. 买家确认收货（更新status=2，记录confirm_time）
   ↓
5. 交易完成（资金结算，奖励计算）
```

### 6.3 商品转拍流程
```
1. 买家购买商品并确认收货
   ↓
2. 买家申请转拍（创建寄售商品记录）
   - 记录old_id（原订单ID）
   - 设置寄售价格
   - 等待管理员审核（is_show=0）
   ↓
3. 管理员审核通过（is_show=1）
   ↓
4. 商品上架展示
   ↓
5. 其他用户购买（生成新订单）
   ↓
6. 卖家收款（扣除平台手续费）
```

### 6.4 提现审核流程
```
1. 用户提交提现申请
   - 选择提现类型（优惠券/推广奖金）
   - 选择收款方式（银行卡/支付宝）
   - 填写提现金额
   - 系统自动扣除相应账户余额
   ↓
2. 管理员审核
   - 查看用户信息和收款账号
   - 审核通过：标记status=1
   - 审核驳回：标记status=2，填写驳回原因
   ↓
3. 驳回时系统自动返还金额
   - 记录类型为3（提现驳回）的财务日志
   - 恢复用户相应账户余额
```

### 6.5 财务账户说明

用户有4个独立的财务账户：

1. **余额（money）**
   - 来源：充值、退款、活动奖励
   - 用途：购买商品、提现
   - 变动记录：wa_money_log

2. **优惠券（coupon）**
   - 来源：系统发放、活动赠送
   - 用途：购买商品抵扣、提现（可选）
   - 变动记录：wa_coupon_log

3. **个人奖金（self_bonus）**
   - 来源：自己交易获得的奖励
   - 用途：提现、转入余额
   - 变动记录：wa_selfbonus_log

4. **推广奖金（share_bonus）**
   - 来源：邀请用户消费返佣
   - 用途：提现
   - 变动记录：wa_sharebonus_log

---

## 7. 安全注意事项

### 7.1 接口安全
- 所有接口调用均需进行身份验证（基于Session/Cookie）
- 敏感操作需要二次确认（如：大额提现审核）
- 防止SQL注入：使用参数化查询
- 防止XSS攻击：输出数据进行HTML转义
- 防止CSRF攻击：验证Referer和Token

### 7.2 数据安全
- 用户密码使用加密算法存储（MD5+盐值）
- 敏感信息脱敏显示（手机号、银行卡号）
- 定期数据备份（每日全量+每小时增量）
- 重要操作记录日志（提现、审核等）

### 7.3 权限控制
- 基于角色的权限管理（RBAC）
- 细粒度的操作权限控制
- 操作日志记录（谁、何时、做了什么）
- 敏感功能需要管理员权限

### 7.4 业务风控
- 提现限额控制（单笔、单日）
- 异常交易监控（频繁操作、大额交易）
- 黑名单机制（异常用户、IP）
- 防刷单策略

---

## 8. 错误码说明

### 8.1 通用错误码

| 错误码 | 说明 | 处理建议 |
|--------|------|----------|
| 0 | 成功 | - |
| -1 | 系统错误 | 联系管理员 |
| 1000 | 参数错误 | 检查请求参数 |
| 1001 | 缺少必填参数 | 补充必填参数 |
| 1002 | 参数格式错误 | 检查参数格式 |
| 2000 | 未登录 | 跳转登录页 |
| 2001 | 无权限 | 提示无权限 |
| 2002 | 账号被禁用 | 联系管理员 |
| 3000 | 数据不存在 | 刷新页面重试 |
| 3001 | 数据已存在 | 提示重复 |
| 4000 | 业务逻辑错误 | 查看msg详细信息 |

### 8.2 业务错误码

| 错误码 | 说明 |
|--------|------|
| 5001 | 余额不足 |
| 5002 | 库存不足 |
| 5003 | 订单状态不正确 |
| 5004 | 提现金额超限 |
| 5005 | 账户已冻结 |
| 5006 | 审核已处理 |
| 5007 | 不支持该操作 |

---

## 9. 接口版本管理

### 9.1 当前版本
- **版本号**：V1.0
- **更新日期**：2025-11-13
- **基础路径**：`/app/admin`

### 9.2 版本变更说明

#### V1.0（2025-11-13）
- 初始版本发布
- 包含用户、订单、商品、提现、财务日志、系统设置等核心模块
- 支持分页查询、复杂筛选、CRUD操作

---

## 10. 技术栈说明

### 10.1 前端技术
- **框架**：Layui（轻量级前端UI框架）
- **AJAX库**：jQuery
- **图表库**：ECharts（如有数据统计需求）

### 10.2 后端技术
- **语言**：PHP
- **框架**：Webman（高性能PHP框架）
- **数据库**：MySQL 5.7
- **Web服务器**：Nginx
- **字符集**：UTF-8

### 10.3 开发规范
- RESTful风格API设计
- MVC架构模式
- 统一的响应格式
- 统一的错误处理机制

---

## 11. 测试建议

### 11.1 功能测试
- 测试所有接口的正常流程
- 测试异常参数的处理
- 测试权限控制
- 测试数据边界值

### 11.2 性能测试
- 接口响应时间（建议<500ms）
- 并发请求处理能力
- 数据库查询优化
- 接口限流策略

### 11.3 安全测试
- SQL注入测试
- XSS攻击测试
- CSRF攻击测试
- 权限越权测试

---

## 12. 附录

### 12.1 完整接口列表

| 模块 | 接口路径 | 方法 | 说明 |
|------|----------|------|------|
| 用户管理 | /user/index | GET | 用户管理页面 |
| 用户管理 | /user/select | GET | 用户列表/详情查询 |
| 用户管理 | /user/update | POST | 用户信息更新 |
| 寄售商品 | /merchandise/index | GET | 寄售商品管理页面 |
| 寄售商品 | /merchandise/select | GET | 寄售商品列表/详情查询 |
| 寄售商品 | /merchandise/update | POST | 寄售商品更新 |
| 订单管理 | /order/index | GET | 订单管理页面 |
| 订单管理 | /order/select | GET | 订单列表/详情查询 |
| 订单管理 | /order/update | POST | 订单信息更新 |
| 提现管理 | /withdraw/index | GET | 提现管理页面 |
| 提现管理 | /withdraw/select | GET | 提现列表/详情查询 |
| 提现管理 | /withdraw/update | POST | 提现审核 |
| 优惠券日志 | /coupon-log/index | GET | 优惠券日志页面 |
| 优惠券日志 | /coupon-log/select | GET | 优惠券日志查询 |
| 个人奖金日志 | /selfbonus-log/index | GET | 个人奖金日志页面 |
| 个人奖金日志 | /selfbonus-log/select | GET | 个人奖金日志查询 |
| 推广奖金日志 | /sharebonus-log/index | GET | 推广奖金日志页面 |
| 推广奖金日志 | /sharebonus-log/select | GET | 推广奖金日志查询 |
| 系统设置 | /setting/index | GET | 系统设置页面 |
| 系统设置 | /setting/get | GET | 获取系统设置 |
| 系统设置 | /setting/update | POST | 更新系统设置 |
| 系统配置 | /config/get | GET | 获取系统配置 |
| 权限规则 | /rule/get | GET | 获取菜单配置 |
| 账户信息 | /account/info | GET | 获取管理员信息 |

### 12.2 数据状态枚举汇总

#### 用户状态（status）
- 0：禁用
- 1：启用

#### 性别（sex）
- 0：女
- 1：男

#### 是否VIP（is_vip）
- 0：否
- 1：是

#### 订单状态（status）
- 0：待付款
- 1：已支付
- 2：已完成

#### 寄售商品状态（status）
- 0：已售
- 1：未售

#### 显示状态（is_show）
- 0：隐藏
- 1：显示

#### 财务变动类型（type）
- 1：收入
- 2：支出
- 3：提现驳回

#### 提现类型（cate）
- 2：优惠券
- 4：推广奖金

#### 提现账号类型（account_type）
- 1：银行卡
- 2：支付宝

#### 提现状态（status）
- 0：待审核
- 1：通过
- 2：驳回

### 12.3 常用查询参数说明

**分页参数**：
- page：页码
- limit：每页数量

**搜索条件**：
- 字段名[0]：操作符（like、=、>、<等）
- 字段名[1]：搜索值

**日期范围**：
- 字段名[0]：开始日期
- 字段名[1]：结束日期

---

## 13. 联系方式

### 13.1 技术支持
- **文档维护**：产品团队
- **技术对接**：开发团队
- **问题反馈**：提交Issue或联系项目负责人

### 13.2 更新记录
| 版本 | 日期 | 更新内容 | 更新人 |
|------|------|----------|--------|
| V1.0 | 2025-11-13 | 初始完整版文档 | 系统分析 |

---

**文档结束**

> 本文档基于参考系统（https://miao1admin.suzhouyuqi.com）的HAR文件分析生成，包含了系统所有核心API接口的详细说明。如有疑问或需要补充，请联系文档维护团队。