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

1316 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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响应都遵循以下格式：
```json
{
"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
- 请求体：
```json
{
"email": "user@example.com",
"password": "password123"
}
```
**响应**：
```json
{
"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
- 请求体：
```json
{
"username": "user",
"email": "user@example.com",
"password": "password123",
"role": "OPERATOR"
}
```
**响应**：
```json
{
"success": true,
"data": {
"userId": "1"
},
"error": null
}
```
### 3.3 刷新令牌
**请求**：
- 方法：POST
- 路径：/auth/refresh
- 内容类型：application/json
- 请求体：
```json
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```
**响应**：
```json
{
"success": true,
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
},
"error": null
}
```
## 4. 用户接口
### 4.1 获取用户列表
**请求**：
- 方法：GET
- 路径：/users
- 查询参数：
- page：页码，默认1
- pageSize：每页数量，默认10
- role：角色筛选
- search：搜索关键词
**响应**：
```json
{
"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}
**响应**：
```json
{
"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
- 请求体：
```json
{
"username": "user1",
"email": "user1@example.com",
"password": "password123",
"role": "OPERATOR",
"tenantId": "1"
}
```
**响应**：
```json
{
"success": true,
"data": {
"userId": "1"
},
"error": null
}
```
### 4.4 更新用户
**请求**：
- 方法：PUT
- 路径：/users/{id}
- 内容类型：application/json
- 请求体：
```json
{
"username": "user1",
"email": "user1@example.com",
"role": "MANAGER"
}
```
**响应**：
```json
{
"success": true,
"data": {
"success": true
},
"error": null
}
```
### 4.5 删除用户
**请求**：
- 方法：DELETE
- 路径：/users/{id}
**响应**：
```json
{
"success": true,
"data": null,
"error": null
}
```
### 4.6 批量创建用户
**请求**：
- 方法：POST
- 路径：/users/batch
- 内容类型：application/json
- 请求体：
```json
{
"users": [
{
"username": "user1",
"email": "user1@example.com",
"password": "password123",
"role": "OPERATOR",
"tenantId": "1"
},
...
]
}
```
**响应**：
```json
{
"success": true,
"data": {
"createdIds": ["1", "2", ...]
},
"error": null
}
```
## 5. 商品接口
### 5.1 获取商品列表
**请求**：
- 方法：GET
- 路径：/products
- 查询参数：
- page：页码，默认1
- pageSize：每页数量，默认10
- category：分类筛选
- status：状态筛选
- search：搜索关键词
**响应**：
```json
{
"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}
**响应**：
```json
{
"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
- 请求体：
```json
{
"name": "Product 1",
"price": 99.99,
"stock": 100,
"category": "Electronics",
"description": "Product description",
"images": ["image1.jpg", "image2.jpg"]
}
```
**响应**：
```json
{
"success": true,
"data": {
"productId": "1"
},
"error": null
}
```
### 5.4 更新商品
**请求**：
- 方法：PUT
- 路径：/products/{id}
- 内容类型：application/json
- 请求体：
```json
{
"name": "Product 1 Updated",
"price": 109.99,
"stock": 150
}
```
**响应**：
```json
{
"success": true,
"data": {
"success": true
},
"error": null
}
```
### 5.5 删除商品
**请求**：
- 方法：DELETE
- 路径：/products/{id}
**响应**：
```json
{
"success": true,
"data": null,
"error": null
}
```
## 6. 订单接口
### 6.1 获取订单列表
**请求**：
- 方法：GET
- 路径：/orders
- 查询参数：
- page：页码，默认1
- pageSize：每页数量，默认10
- status：状态筛选
- startDate：开始日期
- endDate：结束日期
**响应**：
```json
{
"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}
**响应**：
```json
{
"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
- 请求体：
```json
{
"customer": {
"name": "Customer 1",
"email": "customer1@example.com",
"address": "123 Main St"
},
"items": [
{
"productId": "1",
"quantity": 2
}
]
}
```
**响应**：
```json
{
"success": true,
"data": {
"orderId": "1",
"orderNumber": "ORD-2023-0001"
},
"error": null
}
```
### 6.4 更新订单状态
**请求**：
- 方法：PUT
- 路径：/orders/{id}/status
- 内容类型：application/json
- 请求体：
```json
{
"status": "SHIPPED"
}
```
**响应**：
```json
{
"success": true,
"data": {
"success": true
},
"error": null
}
```
### 6.5 取消订单
**请求**：
- 方法：POST
- 路径：/orders/{id}/cancel
**响应**：
```json
{
"success": true,
"data": {
"success": true
},
"error": null
}
```
## 7. 财务接口
### 7.1 获取财务报表
**请求**：
- 方法：GET
- 路径：/finance/reports
- 查询参数：
- startDate：开始日期
- endDate：结束日期
- type：报表类型（daily, monthly, yearly）
**响应**：
```json
{
"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：状态筛选
**响应**：
```json
{
"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
- 请求体：
```json
{
"amount": 5000.00,
"method": "BANK_TRANSFER"
}
```
**响应**：
```json
{
"success": true,
"data": {
"settlementId": "1"
},
"error": null
}
```
## 8. 店铺接口
### 8.1 获取店铺列表
**请求**：
- 方法：GET
- 路径：/shops
- 查询参数：
- page：页码，默认1
- pageSize：每页数量，默认10
- platform：平台筛选
- status：状态筛选
**响应**：
```json
{
"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}
**响应**：
```json
{
"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
- 请求体：
```json
{
"name": "Shop 1",
"platform": "Amazon",
"config": {
"apiKey": "api_key",
"apiSecret": "api_secret"
}
}
```
**响应**：
```json
{
"success": true,
"data": {
"shopId": "1"
},
"error": null
}
```
### 8.4 更新店铺
**请求**：
- 方法：PUT
- 路径：/shops/{id}
- 内容类型：application/json
- 请求体：
```json
{
"name": "Shop 1 Updated",
"config": {
"apiKey": "new_api_key",
"apiSecret": "new_api_secret"
}
}
```
**响应**：
```json
{
"success": true,
"data": {
"success": true
},
"error": null
}
```
### 8.5 删除店铺
**请求**：
- 方法：DELETE
- 路径：/shops/{id}
**响应**：
```json
{
"success": true,
"data": null,
"error": null
}
```
## 9. 部门接口
### 9.1 获取部门列表
**请求**：
- 方法：GET
- 路径：/departments
**响应**：
```json
{
"success": true,
"data": {
"departments": [
{
"id": "1",
"name": "Department 1",
"parentId": null,
"userCount": 10
},
...
]
},
"error": null
}
```
### 9.2 获取部门详情
**请求**：
- 方法：GET
- 路径：/departments/{id}
**响应**：
```json
{
"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
- 请求体：
```json
{
"name": "Department 1",
"parentId": null,
"description": "Department description"
}
```
**响应**：
```json
{
"success": true,
"data": {
"departmentId": "1"
},
"error": null
}
```
### 9.4 更新部门
**请求**：
- 方法：PUT
- 路径：/departments/{id}
- 内容类型：application/json
- 请求体：
```json
{
"name": "Department 1 Updated",
"parentId": "2",
"description": "Updated department description"
}
```
**响应**：
```json
{
"success": true,
"data": {
"success": true
},
"error": null
}
```
### 9.5 删除部门
**请求**：
- 方法：DELETE
- 路径：/departments/{id}
**响应**：
```json
{
"success": true,
"data": null,
"error": null
}
```
### 9.6 设置部门负责人
**请求**：
- 方法：PUT
- 路径：/departments/{id}/manager
- 内容类型：application/json
- 请求体：
```json
{
"userId": "1"
}
```
**响应**：
```json
{
"success": true,
"data": {
"success": true
},
"error": null
}
```
## 10. 订阅接口
### 10.1 获取套餐列表
**请求**：
- 方法：GET
- 路径：/subscriptions/plans
**响应**：
```json
{
"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
**响应**：
```json
{
"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
- 请求体：
```json
{
"planId": "3"
}
```
**响应**：
```json
{
"success": true,
"data": {
"subscriptionId": "2"
},
"error": null
}
```
### 10.4 获取使用量统计
**请求**：
- 方法：GET
- 路径：/subscriptions/usage
- 查询参数：
- startDate：开始日期
- endDate：结束日期
**响应**：
```json
{
"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.）
**响应**：
```json
{
"success": true,
"data": {
"importedCount": 100,
"failedCount": 0
},
"error": null
}
```
## 12. 日志接口
### 12.1 获取操作日志
**请求**：
- 方法：GET
- 路径：/logs/operations
- 查询参数：
- page：页码，默认1
- pageSize：每页数量，默认10
- user：操作人
- action：操作类型
- startDate：开始日期
- endDate：结束日期
**响应**：
```json
{
"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：结束日期
**响应**：
```json
{
"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：结束日期
**响应**：
```json
{
"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
**响应**：
```json
{
"success": true,
"data": {
"system": {
"version": "1.0.0",
"status": "RUNNING",
"uptime": "7 days 12 hours 34 minutes"
}
},
"error": null
}
```
### 13.2 获取系统配置
**请求**：
- 方法：GET
- 路径：/system/config
**响应**：
```json
{
"success": true,
"data": {
"config": {
"systemName": "Crawlful Hub",
"timezone": "UTC",
"language": "en"
}
},
"error": null
}
```
### 13.3 更新系统配置
**请求**：
- 方法：PUT
- 路径：/system/config
- 内容类型：application/json
- 请求体：
```json
{
"systemName": "Crawlful Hub",
"timezone": "UTC",
"language": "en"
}
```
**响应**：
```json
{
"success": true,
"data": {
"success": true
},
"error": null
}
```
---
本文档会定期更新，以反映系统的最新API接口。
Reference in New Issue View Git Blame Copy Permalink