kevin/ops2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
ops2/DOC/API手册.md
T
kevin bb6c9fbecb up 
Signed-off-by: 吴文峰 <kevin@lmve.net>
2026-04-14 21:42:39 +08:00

12 KiB
Raw Permalink Blame History

OPS 后端 API 使用手册

概述

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

通用请求格式

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

通用响应格式

{
  "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

请求参数:

{
  "userCookieValue": "",
  "data": {
    "username": "用户名",
    "password": "密码",
    "remember": false
  }
}

响应数据:

{
  "cookie": {
    "ID": 1,
    "Value": "32位随机字符串",
    "ExpiresAt": "过期时间"
  }
}

用户注册

POST /api/users/register

请求参数:

{
  "userCookieValue": "",
  "data": {
    "username": "用户名",
    "useremail": "邮箱",
    "userpass": "密码"
  }
}

获取当前用户信息

POST /api/users/getinfo

需要认证

响应数据:

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

获取指定用户信息

GET /api/users/getuserinfo/:id

需要认证

响应数据:

{
  "userinfo": {
    "UserID": 1,
    "Username": "显示名"
  }
}

修改密码

POST /api/users/changePassword

需要认证

请求参数:

{
  "userCookieValue": "cookie",
  "data": {
    "oldpass": "旧密码",
    "newpass": "新密码"
  }
}

修改邮箱

POST /api/users/changeEmail

需要认证

请求参数:

{
  "userCookieValue": "cookie",
  "data": {
    "newemail": "新邮箱"
  }
}

更新用户信息

POST /api/users/updateInfo

需要认证

请求参数:

{
  "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

需要认证

请求参数:

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

响应数据:

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

获取单个订单详情

POST /api/purchase/getorder

需要认证

请求参数:

{
  "userCookieValue": "cookie",
  "data": {
    "id": 1
  }
}

响应数据:

{
  "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

需要认证

请求参数:

{
  "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

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

请求参数:

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

更新订单状态

POST /api/purchase/updatestatus

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

请求参数:

{
  "userCookieValue": "cookie",
  "data": {
    "id": 1,
    "status": "ordered",
    "comment": "备注",
    "photos": ["变更图片哈希"]
  }
}

状态值:

值 说明
pending 待处理
ordered 已下单
arrived 已到达
received 已收件
lost 丢件
returned 退件

删除订单

POST /api/purchase/deleteorder

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

请求参数:

{
  "userCookieValue": "cookie",
  "data": {
    "id": 1
  }
}

获取订单统计

POST /api/purchase/getordercount

需要认证

响应数据:

{
  "pending": 10,
  "ordered": 5,
  "arrived": 3,
  "received": 20,
  "lost": 1,
  "returned": 2,
  "total": 41
}

日程模块 /api/schedule

获取日程列表

POST /api/schedule/getevents

请求参数:

{
  "userCookieValue": "cookie",
  "data": {
    "start": "2026-01-01",
    "end": "2026-12-31"
  }
}

响应数据:

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

创建日程

POST /api/schedule/addevent

需要认证

请求参数:

{
  "userCookieValue": "cookie",
  "data": {
    "id": 0,
    "title": "日程标题",
    "start": "2026-01-01",
    "end": "2026-01-01",
    "color": "#3788d9"
  }
}

编辑日程

POST /api/schedule/editevent

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

请求参数:

{
  "userCookieValue": "cookie",
  "data": {
    "id": 1,
    "title": "日程标题",
    "start": "2026-01-01",
    "end": "2026-01-01",
    "color": "#3788d9"
  }
}

删除日程

POST /api/schedule/deleevent

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

请求参数:

{
  "userCookieValue": "cookie",
  "data": {
    "id": 1
  }
}

文件模块 /api/files

上传图片

POST /api/files/upload/image

需要认证

请求格式: multipart/form-data

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

响应数据:

{
  "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 用户组成员：可修改/删除所有日程
Reference in New Issue View Git Blame Copy Permalink