Initial commit from Create Next App

2025-09-22 15:40:57 +08:00
commit 75900a7dcf
18 changed files with 2495 additions and 0 deletions
--- a/docs/API文档.md
+++ b/docs/API文档.md
@@ -0,0 +1,867 @@
+# 账户管理系统 API 文档
+
+## 概述
+
+本文档描述了账户管理系统的API接口，用于Web前端对接。系统提供了账户的获取、上传、更新、删除和统计等功能。
+
+### 基础信息
+
+- **基础URL**: `{API_BASE_URL}`
+- **数据格式**: JSON
+- **字符编码**: UTF-8
+- **认证方式**: 需要在请求头中包含认证信息
+
+### 通用响应格式
+
+所有API接口都使用统一的响应格式：
+
+```typescript
+interface ApiResponse<T> {
+  code: BusinessCode;  // 业务状态码
+  message: string;     // 响应消息
+  data: T | null;      // 响应数据
+}
+```
+
+#### 业务状态码 (BusinessCode)
+
+| 状态码 | 名称 | 说明 |
+|--------|------|------|
+| 0 | Success | 请求成功 |
+| 1001 | NoResource | 资源不存在 |
+| 2001 | InvalidParams | 参数无效 |
+| 3001 | ResourceConflict | 资源冲突 |
+| 4001 | PermissionDenied | 权限不足 |
+| 5001 | BusinessError | 业务错误 |
+
+## 数据模型
+
+### 账户 (Account)
+
+账户是系统的核心数据模型，包含以下字段：
+
+```typescript
+interface Account {
+  id: number;        // 账户ID，自增主键
+  ownerId: string;  // 所有者ID
+  platform: string; // 平台名称
+  customId: string; // 自定义ID
+  data: string;     // 账户数据，JSON格式字符串
+  status: string;   // 账户状态
+  notes?: string;   // 备注，可选
+  lockedAt?: Date;  // 锁定时间，可选
+  createdAt: Date;  // 创建时间
+  updatedAt: Date;  // 更新时间
+}
+```
+
+#### 账户状态
+
+- `available`: 可用
+- `locked`: 已锁定
+- 其他自定义状态
+
+### 分页结果 (PaginationResult)
+
+```typescript
+interface PaginationResult {
+  page: number;      // 当前页码
+  pageSize: number;  // 每页条数
+  total: number;     // 总记录数
+  totalPages: number; // 总页数
+}
+```
+
+### 统计概览 (StatsOverview)
+
+```typescript
+interface StatsOverview {
+  totalAccounts: number; // 总账户数
+  platformSummary: Record<string, number>; // 平台统计
+  ownerSummary: Record<string, number>;    // 所有者统计
+  statusSummary: Record<string, number>;    // 状态统计
+  detailedBreakdown: {  // 详细统计
+    platform: string;
+    ownerId: string;
+    status: string;
+    count: number;
+  }[];
+}
+```
+
+## API 接口
+
+### 1. 账户获取接口
+
+用于脚本端获取可用账户。
+
+#### 请求
+
+```http
+GET /s/v1/{ownerId}/acquire?platform={platform}&count={count}
+```
+
+#### 参数
+
+| 参数名 | 位置 | 类型 | 必填 | 说明 |
+|--------|------|------|------|------|
+| ownerId | 路径 | string | 是 | 所有者ID |
+| platform | 查询 | string | 是 | 平台名称 |
+| count | 查询 | number | 否 | 获取数量，默认1，最大100 |
+
+#### 响应
+
+成功响应：
+
+```json
+{
+  "code": 0,
+  "message": "Successfully acquired 1 account.",
+  "data": [
+    {
+      "id": 1,
+      "customId": "custom123",
+      "data": "{\"username\":\"test\",\"password\":\"123456\"}"
+    }
+  ]
+}
+```
+
+无可用账户响应：
+
+```json
+{
+  "code": 1001,
+  "message": "No available accounts found for platform 'example'.",
+  "data": null
+}
+```
+
+#### 示例
+
+```javascript
+// 使用fetch获取账户
+async function acquireAccounts(ownerId, platform, count = 1) {
+  const response = await fetch(`/s/v1/${ownerId}/acquire?platform=${platform}&count=${count}`, {
+    method: 'GET',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': 'Bearer YOUR_TOKEN'
+    }
+  });
+  
+  const result = await response.json();
+  return result;
+}
+
+// 调用示例
+const result = await acquireAccounts('owner123', 'example', 2);
+if (result.code === 0) {
+  console.log('获取成功:', result.data);
+} else {
+  console.error('获取失败:', result.message);
+}
+```
+
+### 2. 账户状态更新接口
+
+用于脚本端更新账户状态。
+
+#### 请求
+
+```http
+GET /s/v1/{ownerId}/update/{accountId}/{newStatus}?notes={notes}
+```
+
+#### 参数
+
+| 参数名 | 位置 | 类型 | 必填 | 说明 |
+|--------|------|------|------|------|
+| ownerId | 路径 | string | 是 | 所有者ID |
+| accountId | 路径 | number | 是 | 账户ID |
+| newStatus | 路径 | string | 是 | 新状态 |
+| notes | 查询 | string | 否 | 备注 |
+
+#### 响应
+
+成功响应：
+
+```json
+{
+  "code": 0,
+  "message": "Account status updated to 'used'.",
+  "data": {
+    "updatedId": 1
+  }
+}
+```
+
+权限不足响应：
+
+```json
+{
+  "code": 4001,
+  "message": "Account not found or permission denied.",
+  "data": null
+}
+```
+
+#### 示例
+
+```javascript
+// 使用fetch更新账户状态
+async function updateAccountStatus(ownerId, accountId, newStatus, notes) {
+  const url = `/s/v1/${ownerId}/update/${accountId}/${newStatus}`;
+  if (notes) {
+    url += `?notes=${encodeURIComponent(notes)}`;
+  }
+  
+  const response = await fetch(url, {
+    method: 'GET',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': 'Bearer YOUR_TOKEN'
+    }
+  });
+  
+  const result = await response.json();
+  return result;
+}
+
+// 调用示例
+const result = await updateAccountStatus('owner123', 1, 'used', '测试使用');
+if (result.code === 0) {
+  console.log('更新成功:', result.data);
+} else {
+  console.error('更新失败:', result.message);
+}
+```
+
+### 3. 账户上传接口
+
+用于脚本端批量上传账户。
+
+#### 请求
+
+```http
+POST /s/v1/{ownerId}/upload
+```
+
+#### 请求体
+
+```json
+[
+  {
+    "platform": "string",
+    "customId": "string",
+    "data": "string",
+    "status": "string"
+  }
+]
+```
+
+#### 参数
+
+| 参数名 | 位置 | 类型 | 必填 | 说明 |
+|--------|------|------|------|------|
+| ownerId | 路径 | string | 是 | 所有者ID |
+| body | 请求体 | ScriptUploadItem[] | 是 | 账户数据数组 |
+
+#### ScriptUploadItem 类型
+
+```typescript
+interface ScriptUploadItem {
+  platform: string;  // 平台名称
+  customId: string;  // 自定义ID
+  data: string;      // 账户数据，JSON格式字符串
+  status?: string;   // 账户状态，可选，默认为"available"
+}
+```
+
+#### 响应
+
+成功响应：
+
+```json
+{
+  "code": 0,
+  "message": "Successfully processed 2 accounts (1 created, 1 updated).",
+  "data": {
+    "processedCount": 2,
+    "createdCount": 1,
+    "updatedCount": 1
+  }
+}
+```
+
+#### 示例
+
+```javascript
+// 使用fetch上传账户
+async function uploadAccounts(ownerId, accounts) {
+  const response = await fetch(`/s/v1/${ownerId}/upload`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': 'Bearer YOUR_TOKEN'
+    },
+    body: JSON.stringify(accounts)
+  });
+  
+  const result = await response.json();
+  return result;
+}
+
+// 调用示例
+const accounts = [
+  {
+    platform: 'example',
+    customId: 'user123',
+    data: JSON.stringify({ username: 'user123', password: 'pass123' }),
+    status: 'available'
+  },
+  {
+    platform: 'example',
+    customId: 'user456',
+    data: JSON.stringify({ username: 'user456', password: 'pass456' })
+  }
+];
+
+const result = await uploadAccounts('owner123', accounts);
+if (result.code === 0) {
+  console.log('上传成功:', result.data);
+} else {
+  console.error('上传失败:', result.message);
+}
+```
+
+### 4. 账户列表接口
+
+用于Web端获取账户列表，支持筛选、分页和排序。
+
+#### 请求
+
+```http
+POST /web/v1/accounts/list
+```
+
+#### 请求体
+
+```json
+{
+  "filters": {
+    "platform": "string",
+    "status": ["string"],
+    "ownerId": "string",
+    "search": "string"
+  },
+  "pagination": {
+    "page": 1,
+    "pageSize": 10
+  },
+  "sort": {
+    "field": "id",
+    "order": "desc"
+  }
+}
+```
+
+#### 参数
+
+| 参数名 | 位置 | 类型 | 必填 | 说明 |
+|--------|------|------|------|------|
+| filters | 请求体 | ListAccountsFilters | 否 | 筛选条件 |
+| pagination | 请求体 | object | 是 | 分页参数 |
+| sort | 请求体 | object | 是 | 排序参数 |
+
+#### ListAccountsFilters 类型
+
+```typescript
+interface ListAccountsFilters {
+  platform?: string;   // 平台名称筛选
+  status?: string[];   // 状态筛选，多选
+  ownerId?: string;    // 所有者ID筛选
+  search?: string;     // 搜索关键词，搜索customId和notes
+}
+```
+
+#### 排序字段
+
+支持以下字段排序：
+- `id`: 账户ID
+- `ownerId`: 所有者ID
+- `platform`: 平台名称
+- `customId`: 自定义ID
+- `data`: 账户数据
+- `status`: 账户状态
+- `notes`: 备注
+- `lockedAt`: 锁定时间
+- `createdAt`: 创建时间
+- `updatedAt`: 更新时间
+
+#### 响应
+
+成功响应：
+
+```json
+{
+  "code": 0,
+  "message": "Success",
+  "data": {
+    "list": [
+      {
+        "id": 1,
+        "ownerId": "owner123",
+        "platform": "example",
+        "customId": "user123",
+        "data": "{\"username\":\"user123\",\"password\":\"pass123\"}",
+        "status": "available",
+        "notes": "测试账户",
+        "lockedAt": null,
+        "createdAt": "2023-01-01T00:00:00.000Z",
+        "updatedAt": "2023-01-01T00:00:00.000Z"
+      }
+    ],
+    "pagination": {
+      "page": 1,
+      "pageSize": 10,
+      "total": 1,
+      "totalPages": 1
+    }
+  }
+}
+```
+
+#### 示例
+
+```javascript
+// 使用fetch获取账户列表
+async function getAccountsList(filters, pagination, sort) {
+  const response = await fetch('/web/v1/accounts/list', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': 'Bearer YOUR_TOKEN'
+    },
+    body: JSON.stringify({
+      filters,
+      pagination,
+      sort
+    })
+  });
+  
+  const result = await response.json();
+  return result;
+}
+
+// 调用示例
+const filters = {
+  platform: 'example',
+  status: ['available'],
+  search: 'test'
+};
+
+const pagination = {
+  page: 1,
+  pageSize: 10
+};
+
+const sort = {
+  field: 'createdAt',
+  order: 'desc'
+};
+
+const result = await getAccountsList(filters, pagination, sort);
+if (result.code === 0) {
+  console.log('账户列表:', result.data.list);
+  console.log('分页信息:', result.data.pagination);
+} else {
+  console.error('获取失败:', result.message);
+}
+```
+
+### 5. 批量删除账户接口
+
+用于Web端批量删除账户。
+
+#### 请求
+
+```http
+POST /web/v1/accounts/delete-batch
+```
+
+#### 请求体
+
+```json
+{
+  "ids": [1, 2, 3]
+}
+```
+
+#### 参数
+
+| 参数名 | 位置 | 类型 | 必填 | 说明 |
+|--------|------|------|------|------|
+| ids | 请求体 | number[] | 是 | 要删除的账户ID数组 |
+
+#### 响应
+
+成功响应：
+
+```json
+{
+  "code": 0,
+  "message": "Successfully deleted 3 accounts.",
+  "data": {
+    "deletedCount": 3
+  }
+}
+```
+
+#### 示例
+
+```javascript
+// 使用fetch批量删除账户
+async function batchDeleteAccounts(ids) {
+  const response = await fetch('/web/v1/accounts/delete-batch', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': 'Bearer YOUR_TOKEN'
+    },
+    body: JSON.stringify({ ids })
+  });
+  
+  const result = await response.json();
+  return result;
+}
+
+// 调用示例
+const result = await batchDeleteAccounts([1, 2, 3]);
+if (result.code === 0) {
+  console.log('删除成功:', result.data);
+} else {
+  console.error('删除失败:', result.message);
+}
+```
+
+### 6. 批量更新账户接口
+
+用于Web端批量更新账户。
+
+#### 请求
+
+```http
+POST /web/v1/accounts/update-batch
+```
+
+#### 请求体
+
+```json
+{
+  "ids": [1, 2, 3],
+  "payload": {
+    "status": "available",
+    "ownerId": "newOwner",
+    "notes": "批量更新备注"
+  }
+}
+```
+
+#### 参数
+
+| 参数名 | 位置 | 类型 | 必填 | 说明 |
+|--------|------|------|------|------|
+| ids | 请求体 | number[] | 是 | 要更新的账户ID数组 |
+| payload | 请求体 | object | 是 | 更新数据 |
+
+#### payload 类型
+
+```typescript
+interface UpdatePayload {
+  status?: string;   // 新状态
+  ownerId?: string;  // 新所有者ID
+  notes?: string;    // 新备注
+}
+```
+
+#### 响应
+
+成功响应：
+
+```json
+{
+  "code": 0,
+  "message": "Successfully updated 3 accounts.",
+  "data": {
+    "updatedCount": 3
+  }
+}
+```
+
+#### 示例
+
+```javascript
+// 使用fetch批量更新账户
+async function batchUpdateAccounts(ids, payload) {
+  const response = await fetch('/web/v1/accounts/update-batch', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': 'Bearer YOUR_TOKEN'
+    },
+    body: JSON.stringify({ ids, payload })
+  });
+  
+  const result = await response.json();
+  return result;
+}
+
+// 调用示例
+const ids = [1, 2, 3];
+const payload = {
+  status: 'available',
+  notes: '批量更新为可用状态'
+};
+
+const result = await batchUpdateAccounts(ids, payload);
+if (result.code === 0) {
+  console.log('更新成功:', result.data);
+} else {
+  console.error('更新失败:', result.message);
+}
+```
+
+### 7. 统计概览接口
+
+用于Web端获取账户统计信息。
+
+#### 请求
+
+```http
+GET /web/v1/stats/overview
+```
+
+#### 响应
+
+成功响应：
+
+```json
+{
+  "code": 0,
+  "message": "Success",
+  "data": {
+    "totalAccounts": 100,
+    "platformSummary": {
+      "example": 50,
+      "test": 30,
+      "demo": 20
+    },
+    "ownerSummary": {
+      "owner1": 40,
+      "owner2": 35,
+      "owner3": 25
+    },
+    "statusSummary": {
+      "available": 70,
+      "locked": 20,
+      "used": 10
+    },
+    "detailedBreakdown": [
+      {
+        "platform": "example",
+        "ownerId": "owner1",
+        "status": "available",
+        "count": 20
+      },
+      {
+        "platform": "example",
+        "ownerId": "owner1",
+        "status": "locked",
+        "count": 10
+      }
+    ]
+  }
+}
+```
+
+#### 示例
+
+```javascript
+// 使用fetch获取统计概览
+async function getStatsOverview() {
+  const response = await fetch('/web/v1/stats/overview', {
+    method: 'GET',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': 'Bearer YOUR_TOKEN'
+    }
+  });
+  
+  const result = await response.json();
+  return result;
+}
+
+// 调用示例
+const result = await getStatsOverview();
+if (result.code === 0) {
+  console.log('总账户数:', result.data.totalAccounts);
+  console.log('平台统计:', result.data.platformSummary);
+  console.log('所有者统计:', result.data.ownerSummary);
+  console.log('状态统计:', result.data.statusSummary);
+  console.log('详细统计:', result.data.detailedBreakdown);
+} else {
+  console.error('获取失败:', result.message);
+}
+```
+
+## 错误处理
+
+所有API接口在发生错误时都会返回统一的错误响应格式：
+
+```json
+{
+  "code": "错误码",
+  "message": "错误信息",
+  "data": null
+}
+```
+
+### 常见错误码
+
+| 错误码 | 说明 | 处理建议 |
+|--------|------|----------|
+| 1001 | 资源不存在 | 检查请求的资源是否存在 |
+| 2001 | 参数无效 | 检查请求参数是否符合要求 |
+| 3001 | 资源冲突 | 检查是否有重复数据 |
+| 4001 | 权限不足 | 检查认证信息是否正确 |
+| 5001 | 业务错误 | 检查业务逻辑是否正确 |
+
+## 最佳实践
+
+1. **认证**：所有API请求都需要在请求头中包含认证信息，例如：
+   ```http
+   Authorization: Bearer YOUR_TOKEN
+   ```
+
+2. **错误处理**：前端应该根据返回的`code`值进行相应的错误处理，而不是依赖`message`字段。
+
+3. **分页**：在获取列表数据时，合理设置分页大小，建议不超过100条。
+
+4. **批量操作**：批量操作时，建议限制单次操作的数量，避免服务器压力过大。
+
+5. **数据格式**：账户数据字段`data`存储的是JSON格式字符串，前端需要进行相应的序列化和反序列化操作。
+
+## 类型定义
+
+以下是完整的TypeScript类型定义，可以直接在前端项目中使用：
+
+```typescript
+// 业务状态码
+enum BusinessCode {
+  Success = 0,
+  NoResource = 1001,
+  InvalidParams = 2001,
+  ResourceConflict = 3001,
+  PermissionDenied = 4001,
+  BusinessError = 5001,
+}
+
+// 通用响应格式
+interface ApiResponse<T> {
+  code: BusinessCode;
+  message: string;
+  data: T | null;
+}
+
+// 账户类型
+interface Account {
+  id: number;
+  ownerId: string;
+  platform: string;
+  customId: string;
+  data: string;
+  status: string;
+  notes?: string;
+  lockedAt?: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+// 分页结果
+interface PaginationResult {
+  page: number;
+  pageSize: number;
+  total: number;
+  totalPages: number;
+}
+
+// 脚本获取响应
+type ScriptAcquireResponse = Pick<Account, 'id' | 'customId' | 'data'>[];
+
+// 脚本上传项
+interface ScriptUploadItem {
+  platform: string;
+  customId: string;
+  data: string;
+  status?: string;
+}
+
+// 账户列表筛选条件
+interface ListAccountsFilters {
+  platform?: string;
+  status?: string[];
+  ownerId?: string;
+  search?: string;
+}
+
+// 账户列表请求体
+interface ListAccountsBody {
+  filters: ListAccountsFilters;
+  pagination: {
+    page: number;
+    pageSize: number;
+  };
+  sort: {
+    field: keyof Account;
+    order: 'asc' | 'desc';
+  };
+}
+
+// 账户列表响应
+interface ListAccountsResponse {
+  list: Account[];
+  pagination: PaginationResult;
+}
+
+// 批量删除请求体
+interface BatchDeleteBody {
+  ids: number[];
+}
+
+// 批量更新请求体
+interface BatchUpdateBody {
+  ids: number[];
+  payload: Partial<Pick<Account, 'status' | 'ownerId' | 'notes'>>;
+}
+
+// 统计概览
+interface StatsOverview {
+  totalAccounts: number;
+  platformSummary: Record<string, number>;
+  ownerSummary: Record<string, number>;
+  statusSummary: Record<string, number>;
+  detailedBreakdown: {
+    platform: string;
+    ownerId: string;
+    status: string;
+    count: number;
+  }[];
+}
+```
+
+## 版本历史
+
+| 版本 | 日期 | 说明 |
+|------|------|------|
+| 1.0.0 | 2023-01-01 | 初始版本 |