wurenzhi/makemd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d32770608700549820eba4e399bdb24519ad9be0
makemd/docs/API_Documentation.md
wurenzhi d327706087 feat: 添加部门管理功能、主题切换和多语言支持 
refactor(dashboard): 重构用户管理页面和路由结构

feat(server): 实现部门管理API和RBAC增强功能

docs: 更新用户手册和管理员指南文档

style: 统一图标使用和组件命名规范

test: 添加部门服务和数据隔离测试用例

chore: 更新依赖和配置文件
2026-03-28 22:52:12 +08:00

18 KiB
Raw Blame History

API文档

1. 概述

本文档描述了 Crawlful Hub 系统的API接口，包括认证、用户、商品、订单、财务等模块的接口规范。所有API接口都遵循RESTful设计原则，使用JSON格式进行数据交换。

2. 基础信息

2.1 API版本

当前API版本：v1

2.2 基础URL

https://api.crawlful.com/v1

2.3 认证方式

系统使用JWT（JSON Web Token）进行认证，在请求头中添加Authorization字段：

Authorization: Bearer <token>

2.4 响应格式

所有API响应都遵循以下格式：

{
  "success": true,
  "data": {...},
  "error": null
}
  • success：布尔值，表示请求是否成功
  • data：请求成功时返回的数据
  • error：请求失败时返回的错误信息

2.5 错误码

错误码 描述 HTTP状态码
40001 参数错误 400
40101 未授权 401
40301 禁止访问 403
40401 资源不存在 404
50001 服务器内部错误 500

3. 认证接口

3.1 登录

请求：

  • 方法：POST
  • 路径：/auth/login
  • 内容类型：application/json
  • 请求体：
{
  "email": "user@example.com",
  "password": "password123"
}

响应：

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "1",
      "username": "user",
      "email": "user@example.com",
      "role": "OPERATOR"
    }
  },
  "error": null
}

3.2 注册

请求：

  • 方法：POST
  • 路径：/auth/register
  • 内容类型：application/json
  • 请求体：
{
  "username": "user",
  "email": "user@example.com",
  "password": "password123",
  "role": "OPERATOR"
}

响应：

{
  "success": true,
  "data": {
    "userId": "1"
  },
  "error": null
}

3.3 刷新令牌

请求：

  • 方法：POST
  • 路径：/auth/refresh
  • 内容类型：application/json
  • 请求体：
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

响应：

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "error": null
}

4. 用户接口

4.1 获取用户列表

请求：

  • 方法：GET
  • 路径：/users
  • 查询参数：
    • page：页码，默认1
    • pageSize：每页数量，默认10
    • role：角色筛选
    • search：搜索关键词

响应：

{
  "success": true,
  "data": {
    "users": [
      {
        "id": "1",
        "username": "user1",
        "email": "user1@example.com",
        "role": "OPERATOR",
        "createdAt": "2023-01-01T00:00:00Z"
      },
      ...
    ],
    "total": 100
  },
  "error": null
}

4.2 获取用户详情

请求：

  • 方法：GET
  • 路径：/users/{id}

响应：

{
  "success": true,
  "data": {
    "id": "1",
    "username": "user1",
    "email": "user1@example.com",
    "role": "OPERATOR",
    "createdAt": "2023-01-01T00:00:00Z",
    "updatedAt": "2023-01-01T00:00:00Z"
  },
  "error": null
}

4.3 创建用户

请求：

  • 方法：POST
  • 路径：/users
  • 内容类型：application/json
  • 请求体：
{
  "username": "user1",
  "email": "user1@example.com",
  "password": "password123",
  "role": "OPERATOR",
  "tenantId": "1"
}

响应：

{
  "success": true,
  "data": {
    "userId": "1"
  },
  "error": null
}

4.4 更新用户

请求：

  • 方法：PUT
  • 路径：/users/{id}
  • 内容类型：application/json
  • 请求体：
{
  "username": "user1",
  "email": "user1@example.com",
  "role": "MANAGER"
}

响应：

{
  "success": true,
  "data": {
    "success": true
  },
  "error": null
}

4.5 删除用户

请求：

  • 方法：DELETE
  • 路径：/users/{id}

响应：

{
  "success": true,
  "data": null,
  "error": null
}

4.6 批量创建用户

请求：

  • 方法：POST
  • 路径：/users/batch
  • 内容类型：application/json
  • 请求体：
{
  "users": [
    {
      "username": "user1",
      "email": "user1@example.com",
      "password": "password123",
      "role": "OPERATOR",
      "tenantId": "1"
    },
    ...
  ]
}

响应：

{
  "success": true,
  "data": {
    "createdIds": ["1", "2", ...]
  },
  "error": null
}

5. 商品接口

5.1 获取商品列表

请求：

  • 方法：GET
  • 路径：/products
  • 查询参数：
    • page：页码，默认1
    • pageSize：每页数量，默认10
    • category：分类筛选
    • status：状态筛选
    • search：搜索关键词

响应：

{
  "success": true,
  "data": {
    "products": [
      {
        "id": "1",
        "name": "Product 1",
        "price": 99.99,
        "stock": 100,
        "category": "Electronics",
        "status": "ACTIVE"
      },
      ...
    ],
    "total": 100
  },
  "error": null
}

5.2 获取商品详情

请求：

  • 方法：GET
  • 路径：/products/{id}

响应：

{
  "success": true,
  "data": {
    "id": "1",
    "name": "Product 1",
    "price": 99.99,
    "stock": 100,
    "category": "Electronics",
    "status": "ACTIVE",
    "description": "Product description",
    "images": ["image1.jpg", "image2.jpg"]
  },
  "error": null
}

5.3 创建商品

请求：

  • 方法：POST
  • 路径：/products
  • 内容类型：application/json
  • 请求体：
{
  "name": "Product 1",
  "price": 99.99,
  "stock": 100,
  "category": "Electronics",
  "description": "Product description",
  "images": ["image1.jpg", "image2.jpg"]
}

响应：

{
  "success": true,
  "data": {
    "productId": "1"
  },
  "error": null
}

5.4 更新商品

请求：

  • 方法：PUT
  • 路径：/products/{id}
  • 内容类型：application/json
  • 请求体：
{
  "name": "Product 1 Updated",
  "price": 109.99,
  "stock": 150
}

响应：

{
  "success": true,
  "data": {
    "success": true
  },
  "error": null
}

5.5 删除商品

请求：

  • 方法：DELETE
  • 路径：/products/{id}

响应：

{
  "success": true,
  "data": null,
  "error": null
}

6. 订单接口

6.1 获取订单列表

请求：

  • 方法：GET
  • 路径：/orders
  • 查询参数：
    • page：页码，默认1
    • pageSize：每页数量，默认10
    • status：状态筛选
    • startDate：开始日期
    • endDate：结束日期

响应：

{
  "success": true,
  "data": {
    "orders": [
      {
        "id": "1",
        "orderNumber": "ORD-2023-0001",
        "totalAmount": 199.98,
        "status": "PENDING",
        "createdAt": "2023-01-01T00:00:00Z"
      },
      ...
    ],
    "total": 100
  },
  "error": null
}

6.2 获取订单详情

请求：

  • 方法：GET
  • 路径：/orders/{id}

响应：

{
  "success": true,
  "data": {
    "id": "1",
    "orderNumber": "ORD-2023-0001",
    "totalAmount": 199.98,
    "status": "PENDING",
    "createdAt": "2023-01-01T00:00:00Z",
    "items": [
      {
        "productId": "1",
        "name": "Product 1",
        "quantity": 2,
        "price": 99.99
      }
    ],
    "customer": {
      "name": "Customer 1",
      "email": "customer1@example.com",
      "address": "123 Main St"
    }
  },
  "error": null
}

6.3 创建订单

请求：

  • 方法：POST
  • 路径：/orders
  • 内容类型：application/json
  • 请求体：
{
  "customer": {
    "name": "Customer 1",
    "email": "customer1@example.com",
    "address": "123 Main St"
  },
  "items": [
    {
      "productId": "1",
      "quantity": 2
    }
  ]
}

响应：

{
  "success": true,
  "data": {
    "orderId": "1",
    "orderNumber": "ORD-2023-0001"
  },
  "error": null
}

6.4 更新订单状态

请求：

  • 方法：PUT
  • 路径：/orders/{id}/status
  • 内容类型：application/json
  • 请求体：
{
  "status": "SHIPPED"
}

响应：

{
  "success": true,
  "data": {
    "success": true
  },
  "error": null
}

6.5 取消订单

请求：

  • 方法：POST
  • 路径：/orders/{id}/cancel

响应：

{
  "success": true,
  "data": {
    "success": true
  },
  "error": null
}

7. 财务接口

7.1 获取财务报表

请求：

  • 方法：GET
  • 路径：/finance/reports
  • 查询参数：
    • startDate：开始日期
    • endDate：结束日期
    • type：报表类型（daily, monthly, yearly）

响应：

{
  "success": true,
  "data": {
    "report": {
      "totalSales": 10000.00,
      "totalExpenses": 5000.00,
      "netProfit": 5000.00,
      "transactions": [
        {
          "date": "2023-01-01",
          "amount": 1000.00,
          "type": "SALE"
        },
        ...
      ]
    }
  },
  "error": null
}

7.2 获取结算记录

请求：

  • 方法：GET
  • 路径：/finance/settlements
  • 查询参数：
    • page：页码，默认1
    • pageSize：每页数量，默认10
    • status：状态筛选

响应：

{
  "success": true,
  "data": {
    "settlements": [
      {
        "id": "1",
        "amount": 5000.00,
        "status": "COMPLETED",
        "createdAt": "2023-01-01T00:00:00Z",
        "completedAt": "2023-01-02T00:00:00Z"
      },
      ...
    ],
    "total": 10
  },
  "error": null
}

7.3 发起结算

请求：

  • 方法：POST
  • 路径：/finance/settlements
  • 内容类型：application/json
  • 请求体：
{
  "amount": 5000.00,
  "method": "BANK_TRANSFER"
}

响应：

{
  "success": true,
  "data": {
    "settlementId": "1"
  },
  "error": null
}

8. 店铺接口

8.1 获取店铺列表

请求：

  • 方法：GET
  • 路径：/shops
  • 查询参数：
    • page：页码，默认1
    • pageSize：每页数量，默认10
    • platform：平台筛选
    • status：状态筛选

响应：

{
  "success": true,
  "data": {
    "shops": [
      {
        "id": "1",
        "name": "Shop 1",
        "platform": "Amazon",
        "status": "ACTIVE",
        "createdAt": "2023-01-01T00:00:00Z"
      },
      ...
    ],
    "total": 10
  },
  "error": null
}

8.2 获取店铺详情

请求：

  • 方法：GET
  • 路径：/shops/{id}

响应：

{
  "success": true,
  "data": {
    "id": "1",
    "name": "Shop 1",
    "platform": "Amazon",
    "status": "ACTIVE",
    "createdAt": "2023-01-01T00:00:00Z",
    "updatedAt": "2023-01-01T00:00:00Z",
    "config": {
      "apiKey": "api_key",
      "apiSecret": "api_secret"
    }
  },
  "error": null
}

8.3 添加店铺

请求：

  • 方法：POST
  • 路径：/shops
  • 内容类型：application/json
  • 请求体：
{
  "name": "Shop 1",
  "platform": "Amazon",
  "config": {
    "apiKey": "api_key",
    "apiSecret": "api_secret"
  }
}

响应：

{
  "success": true,
  "data": {
    "shopId": "1"
  },
  "error": null
}

8.4 更新店铺

请求：

  • 方法：PUT
  • 路径：/shops/{id}
  • 内容类型：application/json
  • 请求体：
{
  "name": "Shop 1 Updated",
  "config": {
    "apiKey": "new_api_key",
    "apiSecret": "new_api_secret"
  }
}

响应：

{
  "success": true,
  "data": {
    "success": true
  },
  "error": null
}

8.5 删除店铺

请求：

  • 方法：DELETE
  • 路径：/shops/{id}

响应：

{
  "success": true,
  "data": null,
  "error": null
}

9. 部门接口

9.1 获取部门列表

请求：

  • 方法：GET
  • 路径：/departments

响应：

{
  "success": true,
  "data": {
    "departments": [
      {
        "id": "1",
        "name": "Department 1",
        "parentId": null,
        "userCount": 10
      },
      ...
    ]
  },
  "error": null
}

9.2 获取部门详情

请求：

  • 方法：GET
  • 路径：/departments/{id}

响应：

{
  "success": true,
  "data": {
    "id": "1",
    "name": "Department 1",
    "parentId": null,
    "userCount": 10,
    "createdAt": "2023-01-01T00:00:00Z",
    "updatedAt": "2023-01-01T00:00:00Z"
  },
  "error": null
}

9.3 创建部门

请求：

  • 方法：POST
  • 路径：/departments
  • 内容类型：application/json
  • 请求体：
{
  "name": "Department 1",
  "parentId": null,
  "description": "Department description"
}

响应：

{
  "success": true,
  "data": {
    "departmentId": "1"
  },
  "error": null
}

9.4 更新部门

请求：

  • 方法：PUT
  • 路径：/departments/{id}
  • 内容类型：application/json
  • 请求体：
{
  "name": "Department 1 Updated",
  "parentId": "2",
  "description": "Updated department description"
}

响应：

{
  "success": true,
  "data": {
    "success": true
  },
  "error": null
}

9.5 删除部门

请求：

  • 方法：DELETE
  • 路径：/departments/{id}

响应：

{
  "success": true,
  "data": null,
  "error": null
}

9.6 设置部门负责人

请求：

  • 方法：PUT
  • 路径：/departments/{id}/manager
  • 内容类型：application/json
  • 请求体：
{
  "userId": "1"
}

响应：

{
  "success": true,
  "data": {
    "success": true
  },
  "error": null
}

10. 订阅接口

10.1 获取套餐列表

请求：

  • 方法：GET
  • 路径：/subscriptions/plans

响应：

{
  "success": true,
  "data": {
    "plans": [
      {
        "id": "1",
        "name": "Free",
        "price": 0,
        "features": ["5 shops", "100 products"]
      },
      {
        "id": "2",
        "name": "Basic",
        "price": 99,
        "features": ["20 shops", "1000 products"]
      },
      ...
    ]
  },
  "error": null
}

10.2 获取当前订阅

请求：

  • 方法：GET
  • 路径：/subscriptions/current

响应：

{
  "success": true,
  "data": {
    "subscription": {
      "id": "1",
      "planId": "2",
      "planName": "Basic",
      "startDate": "2023-01-01T00:00:00Z",
      "endDate": "2023-02-01T00:00:00Z",
      "status": "ACTIVE"
    }
  },
  "error": null
}

10.3 切换套餐

请求：

  • 方法：POST
  • 路径：/subscriptions/switch
  • 内容类型：application/json
  • 请求体：
{
  "planId": "3"
}

响应：

{
  "success": true,
  "data": {
    "subscriptionId": "2"
  },
  "error": null
}

10.4 获取使用量统计

请求：

  • 方法：GET
  • 路径：/subscriptions/usage
  • 查询参数：
    • startDate：开始日期
    • endDate：结束日期

响应：

{
  "success": true,
  "data": {
    "usage": {
      "aiCalls": 100,
      "shops": 5,
      "storage": 1024,
      "apiCalls": 1000
    }
  },
  "error": null
}

11. 数据接口

11.1 导出数据

请求：

  • 方法：GET
  • 路径：/data/export
  • 查询参数：
    • type：数据类型（users, products, orders, etc.）
    • format：导出格式（csv, excel）
    • startDate：开始日期
    • endDate：结束日期

响应：

  • 类型：文件下载

11.2 导入数据

请求：

  • 方法：POST
  • 路径：/data/import
  • 内容类型：multipart/form-data
  • 请求体：
    • file：数据文件
    • type：数据类型（users, products, orders, etc.）

响应：

{
  "success": true,
  "data": {
    "importedCount": 100,
    "failedCount": 0
  },
  "error": null
}

12. 日志接口

12.1 获取操作日志

请求：

  • 方法：GET
  • 路径：/logs/operations
  • 查询参数：
    • page：页码，默认1
    • pageSize：每页数量，默认10
    • user：操作人
    • action：操作类型
    • startDate：开始日期
    • endDate：结束日期

响应：

{
  "success": true,
  "data": {
    "logs": [
      {
        "id": "1",
        "userId": "1",
        "username": "user1",
        "action": "CREATE_USER",
        "details": "Created user user2",
        "createdAt": "2023-01-01T00:00:00Z"
      },
      ...
    ],
    "total": 100
  },
  "error": null
}

12.2 获取登录日志

请求：

  • 方法：GET
  • 路径：/logs/logins
  • 查询参数：
    • page：页码，默认1
    • pageSize：每页数量，默认10
    • user：用户
    • ip：IP地址
    • startDate：开始日期
    • endDate：结束日期

响应：

{
  "success": true,
  "data": {
    "logs": [
      {
        "id": "1",
        "userId": "1",
        "username": "user1",
        "ip": "192.168.1.1",
        "status": "SUCCESS",
        "createdAt": "2023-01-01T00:00:00Z"
      },
      ...
    ],
    "total": 100
  },
  "error": null
}

12.3 获取异常日志

请求：

  • 方法：GET
  • 路径：/logs/exceptions
  • 查询参数：
    • page：页码，默认1
    • pageSize：每页数量，默认10
    • type：异常类型
    • startDate：开始日期
    • endDate：结束日期

响应：

{
  "success": true,
  "data": {
    "logs": [
      {
        "id": "1",
        "type": "API_ERROR",
        "message": "Invalid API key",
        "stack": "Error: Invalid API key\n    at ...",
        "createdAt": "2023-01-01T00:00:00Z"
      },
      ...
    ],
    "total": 100
  },
  "error": null
}

13. 系统接口

13.1 获取系统信息

请求：

  • 方法：GET
  • 路径：/system/info

响应：

{
  "success": true,
  "data": {
    "system": {
      "version": "1.0.0",
      "status": "RUNNING",
      "uptime": "7 days 12 hours 34 minutes"
    }
  },
  "error": null
}

13.2 获取系统配置

请求：

  • 方法：GET
  • 路径：/system/config

响应：

{
  "success": true,
  "data": {
    "config": {
      "systemName": "Crawlful Hub",
      "timezone": "UTC",
      "language": "en"
    }
  },
  "error": null
}

13.3 更新系统配置

请求：

  • 方法：PUT
  • 路径：/system/config
  • 内容类型：application/json
  • 请求体：
{
  "systemName": "Crawlful Hub",
  "timezone": "UTC",
  "language": "en"
}

响应：

{
  "success": true,
  "data": {
    "success": true
  },
  "error": null
}

本文档会定期更新，以反映系统的最新API接口。

Reference in New Issue View Git Blame Copy Permalink