# OPS 后端 API 使用手册

## 概述

- **基础URL**: `/api`
- **请求格式**: JSON Body（通过 `userCookieValue` 传cookie，`data` 传业务数据）
- **认证方式**: Cookie-based authentication
- **响应格式**: JSON

## 通用请求格式

```json
{
  "userCookieValue": "cookie字符串",
  "data": {
    // 业务参数
  }
}
```

## 通用响应格式

```json
{
  "err_code": 0,
  "err_msg": "apiOK",
  "return": {
    // 响应数据
  }
}
```

## 错误码

| err_code | err_msg | 说明 |
|----------|---------|------|
| 0 | apiOK | 成功 |
| -1 | apiErr | 服务器错误 |
| -2 | postErr | POST请求错误 |
| -3 | jsonErr | JSON解析错误 |
| -31 | jsonErr_1 | 数据格式错误 |
| -4 | userNameDup | 用户名已存在 |
| -41 | userNameNoFund | 用户不存在 |
| -42 | userPassIncorrect | 密码错误 |
| -43 | userEmailFormatError | 邮箱格式错误 |
| -44 | userCookieError | Cookie错误/未登录 |
| -51 | file_mime_err | 文件类型不允许 |
| -52 | file_size_err | 文件大小超限 |
| -53 | file_name_err | 文件名错误 |
| -54 | file_get_err | 文件获取错误 |
| -55 | file_hash_err | 文件哈希计算错误 |
| -56 | file_save_err | 文件保存失败 |
| -57 | file_not_found | 文件不存在 |
| -58 | file_part_err | 文件参数错误 |
| -61 | schedule_event_not_find | 日程不存在 |
| -62 | schedule_permission_denied | 无权限操作 |
| -1001 | order_not_found | 订单不存在 |
| -1002 | invalid_status | 无效的订单状态 |
| -1003 | status_no_change | 状态未变化 |
| -1004 | no_permission | 无权限 |
| -1005 | photo_hash_invalid | 图片哈希无效 |

---

## 用户模块 `/api/users`

### 用户登录

```
POST /api/users/login
```

**请求参数:**
```json
{
  "userCookieValue": "",
  "data": {
    "username": "用户名",
    "password": "密码",
    "remember": false
  }
}
```

**响应数据:**
```json
{
  "cookie": {
    "ID": 1,
    "Value": "32位随机字符串",
    "ExpiresAt": "过期时间"
  }
}
```

---

### 用户注册

```
POST /api/users/register
```

**请求参数:**
```json
{
  "userCookieValue": "",
  "data": {
    "username": "用户名",
    "useremail": "邮箱",
    "userpass": "密码"
  }
}
```

---

### 获取当前用户信息

```
POST /api/users/getinfo
```

**需要认证**

**响应数据:**
```json
{
  "user": {
    "ID": 1,
    "Name": "用户名",
    "Email": "邮箱"
  },
  "userInfo": {
    "UserID": 1,
    "Username": "显示名",
    "FirstName": "名",
    "Birthdate": "生日",
    "AvatarPath": "头像路径",
    "Gender": "M/F/U",
    "Region": "地区",
    "Language": "语言"
  }
}
```

---

### 获取指定用户信息

```
GET /api/users/getuserinfo/:id
```

**需要认证**

**响应数据:**
```json
{
  "userinfo": {
    "UserID": 1,
    "Username": "显示名"
  }
}
```

---

### 修改密码

```
POST /api/users/changePassword
```

**需要认证**

**请求参数:**
```json
{
  "userCookieValue": "cookie",
  "data": {
    "oldpass": "旧密码",
    "newpass": "新密码"
  }
}
```

---

### 修改邮箱

```
POST /api/users/changeEmail
```

**需要认证**

**请求参数:**
```json
{
  "userCookieValue": "cookie",
  "data": {
    "newemail": "新邮箱"
  }
}
```

---

### 更新用户信息

```
POST /api/users/updateInfo
```

**需要认证**

**请求参数:**
```json
{
  "userCookieValue": "cookie",
  "data": {
    "username": "用户名",
    "remark": "备注(作为FirstName)",
    "birthday": "2006-01-02"
  }
}
```

---

### 上传头像

```
POST /api/users/updateAvatar
```

**需要认证**

**请求格式:** `multipart/form-data`

| 字段 | 类型 | 说明 |
|------|------|------|
| cookie | string | 认证cookie |
| file | file | 图片文件(512字节-1MB) |

---

### 测试接口

```
GET /api/users/test
POST /api/users/test
```

---

## 订单模块 `/api/purchase`

### 获取订单列表

```
POST /api/purchase/getorders
```

**需要认证**

**请求参数:**
```json
{
  "userCookieValue": "cookie",
  "data": {
    "search": "搜索关键词(可选)",
    "status": "pending/ordered/arrived/received/lost/returned(可选)",
    "entries": 20,
    "page": 1
  }
}
```

**响应数据:**
```json
{
  "all_count": 100,
  "all_orders": [
    {
      "ID": 1,
      "UserID": 1,
      "Title": "订单标题",
      "Remark": "备注",
      "Link": "链接",
      "Styles": "样式",
      "OrderStatus": "pending",
      "CreatedAt": "创建时间",
      "UpdatedAt": "更新时间"
    }
  ]
}
```

---

### 获取单个订单详情

```
POST /api/purchase/getorder
```

**需要认证**

**请求参数:**
```json
{
  "userCookieValue": "cookie",
  "data": {
    "id": 1
  }
}
```

**响应数据:**
```json
{
  "order": {
    "ID": 1,
    "UserID": 1,
    "Title": "订单标题",
    "Remark": "备注",
    "Link": "链接",
    "Styles": "样式",
    "OrderStatus": "pending"
  },
  "canModify": true,
  "costs": [
    {
      "ID": 1,
      "OrderID": 1,
      "Price": 1000,
      "Quantity": 2,
      "CurrencyType": 1,
      "CostType": 1
    }
  ],
  "photos": [
    {
      "ID": 1,
      "Name": "图片名",
      "Sha256": "哈希值"
    }
  ],
  "commits": [
    {
      "ID": 1,
      "OrderID": 1,
      "UserID": 1,
      "Action": "create_status",
      "Status": "pending",
      "OldStatus": "",
      "Comment": "状态变更为: pending",
      "Photos": [],
      "CreatedAt": "时间"
    }
  ]
}
```

---

### 创建订单

```
POST /api/purchase/addorder
```

**需要认证**

**请求参数:**
```json
{
  "userCookieValue": "cookie",
  "data": {
    "title": "订单标题(必填)",
    "remark": "备注",
    "link": "链接",
    "styles": "样式",
    "costs": [
      {
        "cost": 1000,
        "costt": 2000,
        "currencytype": 1,
        "int": 2,
        "type": 1
      }
    ],
    "photos": ["图片sha256哈希"]
  }
}
```

**字段说明:**
- `cost`: 费用(分)
- `currencytype`: 货币类型 (1-CNY, 2-MOP, 3-HKD, 4-USD)
- `int`: 数量
- `type`: 费用类型 (1-单价, 2-运费)
- `photos`: 图片SHA256哈希数组

---

### 更新订单

```
POST /api/purchase/updateorder
```

**需要认证** (创建者或管理员)

**请求参数:**
```json
{
  "userCookieValue": "cookie",
  "data": {
    "id": 1,
    "title": "订单标题",
    "remark": "备注",
    "link": "链接",
    "styles": "样式",
    "costs": [
      {
        "cost": 1000,
        "currencytype": 1,
        "int": 2,
        "type": 1
      }
    ],
    "photos": ["哈希"]
  }
}
```

---

### 更新订单状态

```
POST /api/purchase/updatestatus
```

**需要认证** (创建者或管理员)

**请求参数:**
```json
{
  "userCookieValue": "cookie",
  "data": {
    "id": 1,
    "status": "ordered",
    "comment": "备注",
    "photos": ["变更图片哈希"]
  }
}
```

**状态值:**
| 值 | 说明 |
|----|------|
| pending | 待处理 |
| ordered | 已下单 |
| arrived | 已到达 |
| received | 已收件 |
| lost | 丢件 |
| returned | 退件 |

---

### 删除订单

```
POST /api/purchase/deleteorder
```

**需要认证** (创建者或管理员)

**请求参数:**
```json
{
  "userCookieValue": "cookie",
  "data": {
    "id": 1
  }
}
```

---

### 获取订单统计

```
POST /api/purchase/getordercount
```

**需要认证**

**响应数据:**
```json
{
  "pending": 10,
  "ordered": 5,
  "arrived": 3,
  "received": 20,
  "lost": 1,
  "returned": 2,
  "total": 41
}
```

---

## 日程模块 `/api/schedule`

### 获取日程列表

```
POST /api/schedule/getevents
```

**请求参数:**
```json
{
  "userCookieValue": "cookie",
  "data": {
    "start": "2026-01-01",
    "end": "2026-12-31"
  }
}
```

**响应数据:**
```json
{
  "list": [
    {
      "ID": 1,
      "UserID": 1,
      "Title": "日程标题",
      "StartDate": "2026-01-01",
      "EndDate": "2026-01-01",
      "BgColor": "#3788d9",
      "Remark": "备注",
      "edit": true
    }
  ]
}
```

---

### 创建日程

```
POST /api/schedule/addevent
```

**需要认证**

**请求参数:**
```json
{
  "userCookieValue": "cookie",
  "data": {
    "id": 0,
    "title": "日程标题",
    "start": "2026-01-01",
    "end": "2026-01-01",
    "color": "#3788d9"
  }
}
```

---

### 编辑日程

```
POST /api/schedule/editevent
```

**需要认证** (创建者或管理员)

**请求参数:**
```json
{
  "userCookieValue": "cookie",
  "data": {
    "id": 1,
    "title": "日程标题",
    "start": "2026-01-01",
    "end": "2026-01-01",
    "color": "#3788d9"
  }
}
```

---

### 删除日程

```
POST /api/schedule/deleevent
```

**需要认证** (创建者或管理员)

**请求参数:**
```json
{
  "userCookieValue": "cookie",
  "data": {
    "id": 1
  }
}
```

---

## 文件模块 `/api/files`

### 上传图片

```
POST /api/files/upload/image
```

**需要认证**

**请求格式:** `multipart/form-data`

| 字段 | 类型 | 说明 |
|------|------|------|
| cookie | string | 认证cookie |
| file | file | 图片文件 |

**响应数据:**
```json
{
  "download": "/api/files/download/文件哈希",
  "get": "/api/files/get/文件哈希",
  "hash": "sha256哈希值"
}
```

---

### 获取/下载文件

```
GET /api/files/:mode/:hash

mode: get - 获取(预览)
mode: download - 下载
```

**参数说明:**
- `get`: 返回文件预览
- `download`: 返回文件下载

---

## 静态资源 `/api/static`

### 获取头像

```
GET /api/static/avatar/:filename
```

---

## 数据模型

### TabUser_ (用户表)

| 字段 | 类型 | 说明 |
|------|------|------|
| ID | uint | 主键 |
| Name | string | 用户名(唯一) |
| Email | string | 邮箱 |
| Pass | string | 密码(哈希) |
| Salt | string | 盐值 |
| Type | string | 用户类型 |
| Date | datetime | 创建时间 |

### TabUserInfo_ (用户信息表)

| 字段 | 类型 | 说明 |
|------|------|------|
| ID | uint | 主键 |
| UserID | uint | 用户ID(唯一) |
| Username | string | 显示名 |
| FirstName | string | 名 |
| Birthdate | datetime | 生日 |
| Gender | char | 性别 M/F/U |
| AvatarPath | string | 头像路径 |
| Region | string | 地区 |
| Language | string | 语言 |

### TabPurchaseOrder (订单表)

| 字段 | 类型 | 说明 |
|------|------|------|
| ID | uint | 主键 |
| UserID | uint | 创建者ID |
| Title | string | 标题 |
| Remark | text | 备注 |
| Link | string | 链接 |
| Styles | text | 样式 |
| OrderStatus | string | 状态 |
| CreatedAt | datetime | 创建时间 |
| UpdatedAt | datetime | 更新时间 |

### TabPurchaseCosts (订单费用表)

| 字段 | 类型 | 说明 |
|------|------|------|
| ID | uint | 主键 |
| OrderID | uint | 订单ID |
| UserID | uint | 用户ID |
| Price | int | 单价(分) |
| Quantity | int | 数量 |
| CurrencyType | int | 货币类型 |
| CostType | int | 费用类型 |

### TabSchedule (日程表)

| 字段 | 类型 | 说明 |
|------|------|------|
| ID | uint | 主键 |
| UserID | uint | 创建者ID |
| Title | string | 标题 |
| StartDate | string | 开始日期 |
| EndDate | string | 结束日期 |
| BgColor | string | 背景颜色 |
| Remark | text | 备注 |

### TabFileInfo_ (文件表)

| 字段 | 类型 | 说明 |
|------|------|------|
| ID | uint | 主键 |
| Name | string | 文件名 |
| Size | int64 | 文件大小 |
| Path | string | 存储路径 |
| Sha256 | string | 文件哈希 |
| Mime | string | MIME类型 |
| Type | string | 文件类型 |
| UserID | uint | 上传用户ID |
| Date | datetime | 上传时间 |

---

## 权限说明

### 订单权限
- 创建者：可修改/删除自己的订单
- purchase_admin 用户组成员：可修改/删除所有订单

### 日程权限
- 创建者：可修改/删除自己的日程
- schedule_admin 用户组成员：可修改/删除所有日程