ops2/DOC/API快速参考.md

OPS API 快速参考

基础信息

Base URL: http://localhost:8080/api/v1/
认证方式: Bearer Token, Cookie, 或POST body userCookieValue
响应格式: JSON

认证端点

方法	端点	描述	需要认证
POST	/users/register	用户注册	❌
POST	/users/login	用户登录	❌
POST	/users/forgot-password	忘记密码	❌
POST	/users/reset-password	重置密码	❌
GET	/users/profile	获取用户资料	✅
PUT	/users/profile	更新用户资料	✅
POST	/users/logout	用户登出	✅

文件管理端点

方法	端点	描述	需要认证
POST	/files/upload	上传文件	✅
GET	/files/list	获取文件列表	✅
GET	/files/{id}	获取文件信息	✅
DELETE	/files/{id}	删除文件	✅
GET	/files/download/{hash}	下载文件	❌
GET	/files/get/{hash}	预览文件	❌

采购订单端点

兼容前端API

方法	端点	描述	需要认证
POST	/purchase/getorders	获取订单列表	✅
POST	/purchase/addorder	创建订单	✅

RESTful API

方法	端点	描述	需要认证
GET	/purchase/orders	获取订单列表	✅
POST	/purchase/orders	创建订单	✅
GET	/purchase/orders/{id}	获取订单详情	✅

系统管理端点

方法	端点	描述	需要认证	需要管理员
GET	/system/status	系统状态	❌	❌
GET	/system/config	获取配置	✅	✅
PUT	/system/config	更新配置	✅	✅

请求头示例

Bearer Token

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Cookie

Cookie: ops_session=abc123def456

Content-Type

Content-Type: application/json

响应格式

{
  "code": "0",           // 错误码
  "message": "Success",  // 消息
  "data": {}            // 数据
}

核心错误码

错误码	含义	说明
0	成功	请求成功完成
-1	内部错误	服务器内部错误
-2	参数错误	请求参数不正确
-3	未登录	用户未登录或令牌无效
-4	用户已存在	注册时用户名已存在
-5	用户不存在	用户记录不存在
-42	凭证错误	用户名或密码错误

分页参数

所有列表接口支持分页：

• page: 页码 (默认: 1)
• entries: 每页数量 (默认: 20)

GET /api/v1/purchase/orders?page=2&entries=50

文件上传

支持的文件类型：

• 图片: PNG, JPEG, GIF, WebP
• 最大文件大小: 5MB

POST /api/v1/files/upload
Content-Type: multipart/form-data

采购订单数据结构

创建订单请求体

{
  "title": "订单标题",
  "order_status": "pending",
  "part_name": "物品名称",
  "remark": "备注信息",
  "link": "https://example.com",
  "photos": ["hash1", "hash2"],
  "tracking_number": "TN123456789",
  "update_time": "2026-03-31T18:00:00",
  "costs": [
    {
      "cost": 1000,
      "costt": 1000,
      "currencytype": "CNY",
      "int": 2,
      "type": "类型"
    }
  ]
}

订单状态值

• pending: 待处理
• processing: 处理中
• shipped: 已发货
• completed: 已完成
• cancelled: 已取消

快速示例

1. 用户登录

curl -X POST http://localhost:8080/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{"name": "admin", "password": "password123"}'

2. 获取订单列表

curl -X GET "http://localhost:8080/api/v1/purchase/orders?page=1" \
  -H "Authorization: Bearer YOUR_TOKEN"

3. 上传文件

curl -X POST http://localhost:8080/api/v1/files/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@image.png"

状态码映射

OPS错误码	HTTP状态码	含义
0	200 OK	成功
-2	400 Bad Request	参数错误
-3, -42	401 Unauthorized	认证失败
-4	409 Conflict	资源冲突
-5, -100	404 Not Found	资源不存在
-102	413 Payload Too Large	文件太大
-101	415 Unsupported Media Type	文件类型不支持
-1	500 Internal Server Error	服务器错误

开发环境配置

数据库配置

# backend/data/config.yaml
database:
  driver: "sqlite"      # sqlite, mysql, postgres
  path: "./data/db.db"  # SQLite文件路径
  # 或MySQL配置:
  # host: "localhost"
  # port: 3306
  # name: "ops"
  # user: "root"
  # password: "password"

启动命令

# 开发模式
go run cmd/ops-server/main.go

# 生产模式
go build -o ops-server cmd/ops-server/main.go
./ops-server

前端集成示例

存储令牌

// 登录后存储令牌
localStorage.setItem('ops_token', response.data.cookie_value);

// 后续请求自动附加令牌
const token = localStorage.getItem('ops_token');
fetch('/api/v1/users/profile', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

处理响应

async function apiRequest(endpoint, options = {}) {
  const token = localStorage.getItem('ops_token');
  
  const response = await fetch(`/api/v1${endpoint}`, {
    ...options,
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`,
      ...options.headers
    }
  });
  
  const result = await response.json();
  
  if (result.code === '0') {
    return result.data;
  } else {
    throw new Error(result.message);
  }
}

故障排除

常见问题

1. 401 Unauthorized

   • 检查令牌是否过期
   • 确保请求头格式正确
   • 尝试重新登录获取新令牌

2. 400 Bad Request

   • 检查请求体JSON格式
   • 验证必填字段是否提供
   • 检查字段类型和值范围

3. 500 Internal Server Error

   • 查看服务器日志
   • 检查数据库连接
   • 验证文件权限

日志位置

• 后端日志: 控制台输出或日志文件
• 访问日志: backend/logs/access.log
• 错误日志: backend/logs/error.log

---

文档版本: v1.0.0
最后更新: 2026-03-31
保持联系: support@example.com