create-dp-koa 1.0.0

package/template/docs/API_DOCUMENTATION.md

@@ -0,0 +1,837 @@
+# API 文档
+
+DP-Koa Framework 提供完整的 RESTful API 接口，支持用户管理、商品管理、店铺管理等功能。
+
+## 📋 目录
+
+- [API 概览](#api-概览)
+- [认证授权](#认证授权)
+- [用户管理 API](#用户管理-api)
+- [商品管理 API](#商品管理-api)
+- [店铺管理 API](#店铺管理-api)
+- [系统管理 API](#系统管理-api)
+- [健康检查 API](#健康检查-api)
+- [错误处理](#错误处理)
+- [响应格式](#响应格式)
+- [示例代码](#示例代码)
+
+## 🌐 API 概览
+
+### 基础信息
+
+- **Base URL**: `http://localhost:3000`
+- **API 版本**: v1
+- **协议**: HTTP/HTTPS
+- **数据格式**: JSON
+- **字符编码**: UTF-8
+
+### 接口分类
+
+| 分类 | 路径前缀 | 描述 |
+|------|----------|------|
+| 用户管理 | `/home/user/yt_user` | 用户相关操作 |
+| 商品管理 | `/home/goods/common` | 商品相关操作 |
+| 店铺管理 | `/home/shop/common` | 店铺相关操作 |
+| 认证授权 | `/public/auth/yt_user` | 用户认证 |
+| 系统管理 | `/admin/*` | 管理员功能 |
+| 健康检查 | `/health` | 系统状态检查 |
+
+### Swagger 文档
+
+- **Swagger UI**: http://localhost:3000/swagger-ui
+- **Swagger JSON**: http://localhost:3000/swagger.json
+
+## 🔐 认证授权
+
+### JWT Token 认证
+
+大部分 API 需要 JWT Token 认证，请在请求头中包含：
+
+```http
+Authorization: Bearer <your-jwt-token>
+```
+
+### 获取 Token
+
+```http
+POST /public/auth/yt_user/login
+Content-Type: application/json
+
+{
+  "email": "user@example.com",
+  "password": "password123"
+}
+```
+
+**响应示例**:
+```json
+{
+  "code": 0,
+  "data": {
+    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+    "user": {
+      "id": 1,
+      "email": "user@example.com",
+      "nickName": "用户昵称"
+    }
+  },
+  "message": "登录成功"
+}
+```
+
+## 👤 用户管理 API
+
+### 获取用户信息
+
+获取当前登录用户的详细信息。
+
+```http
+GET /home/user/yt_user
+Authorization: Bearer <token>
+```
+
+**响应示例**:
+```json
+{
+  "code": 0,
+  "data": {
+    "id": 1,
+    "nickName": "用户昵称",
+    "status": "normal",
+    "email": "user@example.com",
+    "type": "CUSTOMER",
+    "avatar": "https://example.com/avatar.jpg",
+    "gender": 1,
+    "age": 25,
+    "constellation": "天秤座"
+  },
+  "message": ""
+}
+```
+
+**字段说明**:
+- `id`: 用户ID
+- `nickName`: 用户昵称
+- `status`: 用户状态 (`normal` | `forbidden`)
+- `email`: 邮箱地址
+- `type`: 用户类型 (`CUSTOMER` | `SHOP`)
+- `avatar`: 头像URL
+- `gender`: 性别 (0: 未知, 1: 男, 2: 女)
+- `age`: 年龄
+- `constellation`: 星座
+
+### 检查用户店铺
+
+检查当前用户是否拥有店铺。
+
+```http
+GET /home/user/yt_user/hasShop
+Authorization: Bearer <token>
+```
+
+**响应示例**:
+```json
+{
+  "code": 0,
+  "data": 1,
+  "message": ""
+}
+```
+
+**字段说明**:
+- `data`: 店铺ID，如果为 `null` 表示用户没有店铺
+
+## 🛍️ 商品管理 API
+
+### 获取商品信息
+
+根据商品ID获取商品详细信息。
+
+```http
+GET /home/goods/common?id=1
+Authorization: Bearer <token>
+```
+
+**请求参数**:
+- `id` (required): 商品ID
+
+**响应示例**:
+```json
+{
+  "code": 0,
+  "data": {
+    "id": 1,
+    "name": "商品名称",
+    "albums": ["https://example.com/image1.jpg", "https://example.com/image2.jpg"],
+    "tags": ["标签1", "标签2"],
+    "price": 99.99,
+    "description": "商品描述",
+    "content": "商品详细内容",
+    "imagesContent": "图片内容描述"
+  },
+  "message": ""
+}
+```
+
+**字段说明**:
+- `id`: 商品ID
+- `name`: 商品名称
+- `albums`: 商品图片数组
+- `tags`: 商品标签数组
+- `price`: 商品价格
+- `description`: 商品描述
+- `content`: 商品详细内容
+- `imagesContent`: 图片内容描述
+
+### 解锁商品图片
+
+使用密钥解锁商品图片。
+
+```http
+POST /home/goods/common/unlockGoodsImage
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "goodsId": 1,
+  "key": "unlock_key_123"
+}
+```
+
+**请求参数**:
+- `goodsId` (required): 商品ID
+- `key` (required): 解锁密钥
+
+**响应示例**:
+```json
+{
+  "code": 0,
+  "data": true,
+  "message": ""
+}
+```
+
+### 检查商品解锁状态
+
+检查用户是否已解锁指定商品。
+
+```http
+GET /home/goods/common/getGoodsUnlockInfo?goodsId=1
+Authorization: Bearer <token>
+```
+
+**请求参数**:
+- `goodsId` (required): 商品ID
+
+**响应示例**:
+```json
+{
+  "code": 0,
+  "data": true,
+  "message": ""
+}
+```
+
+**字段说明**:
+- `data`: `true` 表示已解锁，`false` 表示未解锁
+
+## 🏪 店铺管理 API
+
+### 店铺相关接口
+
+店铺管理相关接口请参考具体的店铺控制器实现。
+
+## ⚙️ 系统管理 API
+
+### 缓存管理
+
+#### 获取缓存统计信息
+
+```http
+GET /admin/cache/stats
+Authorization: Bearer <admin-token>
+```
+
+**响应示例**:
+```json
+{
+  "code": 0,
+  "data": {
+    "totalKeys": 150,
+    "hitRate": 0.85,
+    "memoryUsage": "2.5MB"
+  },
+  "message": ""
+}
+```
+
+#### 清理指定缓存
+
+```http
+DELETE /admin/cache/clear?pattern=user_*
+Authorization: Bearer <admin-token>
+```
+
+**请求参数**:
+- `pattern`: 缓存键模式，支持通配符
+
+#### 清理所有缓存
+
+```http
+DELETE /admin/cache/clearAll
+Authorization: Bearer <admin-token>
+```
+
+### 日志管理
+
+#### 获取日志列表
+
+```http
+GET /admin/logs?level=error&limit=50
+Authorization: Bearer <admin-token>
+```
+
+**请求参数**:
+- `level` (optional): 日志级别 (`error` | `warn` | `info` | `debug`)
+- `limit` (optional): 返回条数限制，默认100
+
+**响应示例**:
+```json
+{
+  "code": 0,
+  "data": [
+    {
+      "timestamp": "2024-01-01T12:00:00.000Z",
+      "level": "error",
+      "message": "数据库连接失败",
+      "context": {
+        "userId": 1,
+        "action": "login"
+      }
+    }
+  ],
+  "message": ""
+}
+```
+
+#### 下载日志文件
+
+```http
+GET /admin/logs/download?date=2024-01-01&type=error
+Authorization: Bearer <admin-token>
+```
+
+**请求参数**:
+- `date`: 日志日期 (YYYY-MM-DD)
+- `type`: 日志类型 (`error` | `access` | `performance`)
+
+## 🏥 健康检查 API
+
+### 基础健康检查
+
+检查应用整体健康状态。
+
+```http
+GET /health
+```
+
+**响应示例**:
+```json
+{
+  "code": 0,
+  "data": {
+    "status": "ok",
+    "timestamp": "2024-01-01T12:00:00.000Z",
+    "database": {
+      "connected": true,
+      "pool": {
+        "active": 5,
+        "idle": 10,
+        "total": 15
+      }
+    },
+    "cache": {
+      "stats": {
+        "keys": 150,
+        "hitRate": 0.85
+      },
+      "memory": {
+        "used": "2.5MB",
+        "total": "10MB"
+      }
+    },
+    "uptime": 3600,
+    "memory": {
+      "used": 128,
+      "total": 256,
+      "rss": 200
+    }
+  },
+  "message": ""
+}
+```
+
+### 数据库健康检查
+
+专门检查数据库连接状态。
+
+```http
+GET /health/db
+```
+
+**响应示例**:
+```json
+{
+  "code": 0,
+  "data": {
+    "connected": true,
+    "pool": {
+      "active": 5,
+      "idle": 10,
+      "total": 15
+    }
+  },
+  "message": ""
+}
+```
+
+### 缓存健康检查
+
+检查缓存系统状态。
+
+```http
+GET /health/cache
+```
+
+**响应示例**:
+```json
+{
+  "code": 0,
+  "data": {
+    "stats": {
+      "keys": 150,
+      "hitRate": 0.85
+    },
+    "memory": {
+      "used": "2.5MB",
+      "total": "10MB"
+    },
+    "status": "healthy"
+  },
+  "message": ""
+}
+```
+
+### 详细健康检查
+
+企业级详细健康检查，包含所有系统组件状态。
+
+```http
+GET /health/detailed
+```
+
+**响应示例**:
+```json
+{
+  "code": 0,
+  "data": {
+    "status": "healthy",
+    "timestamp": "2024-01-01T12:00:00.000Z",
+    "uptime": 3600,
+    "pid": 12345,
+    "version": "1.0.0",
+    "environment": "production",
+    "checks": {
+      "database": {
+        "status": "healthy",
+        "message": "Database connection OK",
+        "type": "mysql"
+      },
+      "memory": {
+        "status": "healthy",
+        "message": "Memory usage OK",
+        "details": {
+          "heapUsed": 128000000,
+          "heapTotal": 256000000,
+          "rss": 200000000,
+          "external": 5000000
+        }
+      },
+      "cache": {
+        "status": "healthy",
+        "message": "Cache status OK",
+        "details": {
+          "stats": {
+            "keys": 150,
+            "hitRate": 0.85
+          },
+          "memory": {
+            "used": "2.5MB",
+            "total": "10MB"
+          }
+        }
+      }
+    }
+  },
+  "message": ""
+}
+```
+
+### 就绪检查
+
+Kubernetes 就绪探针。
+
+```http
+GET /ready
+```
+
+**响应示例**:
+```json
+{
+  "code": 0,
+  "data": {
+    "status": "ready",
+    "timestamp": "2024-01-01T12:00:00.000Z",
+    "checks": {
+      "database": {
+        "status": "healthy"
+      }
+    }
+  },
+  "message": ""
+}
+```
+
+### 存活检查
+
+Kubernetes 存活探针。
+
+```http
+GET /live
+```
+
+**响应示例**:
+```json
+{
+  "code": 0,
+  "data": {
+    "status": "alive",
+    "timestamp": "2024-01-01T12:00:00.000Z",
+    "pid": 12345,
+    "uptime": 3600
+  },
+  "message": ""
+}
+```
+
+### 系统指标
+
+获取系统性能指标。
+
+```http
+GET /metrics
+```
+
+**响应示例**:
+```json
+{
+  "code": 0,
+  "data": {
+    "prometheus": "# HELP http_requests_total Total number of HTTP requests\n# TYPE http_requests_total counter\nhttp_requests_total{method=\"GET\",status=\"200\"} 1000",
+    "json": {
+      "requests": {
+        "total": 1000,
+        "success": 950,
+        "error": 50
+      },
+      "responseTime": {
+        "avg": 150,
+        "p95": 300,
+        "p99": 500
+      }
+    }
+  },
+  "message": ""
+}
+```
+
+## ❌ 错误处理
+
+### 错误响应格式
+
+所有 API 错误都遵循统一的响应格式：
+
+```json
+{
+  "code": 400,
+  "data": null,
+  "message": "错误描述信息"
+}
+```
+
+### 常见错误码
+
+| 错误码 | 描述 | 说明 |
+|--------|------|------|
+| 0 | 成功 | 请求处理成功 |
+| 400 | 请求错误 | 请求参数错误或格式不正确 |
+| 401 | 未授权 | 缺少认证信息或Token无效 |
+| 403 | 禁止访问 | 权限不足 |
+| 404 | 资源不存在 | 请求的资源不存在 |
+| 409 | 冲突 | 资源冲突（如邮箱已存在） |
+| 429 | 请求过多 | 触发速率限制 |
+| 500 | 服务器错误 | 服务器内部错误 |
+| -1 | 业务错误 | 业务逻辑错误 |
+
+### 错误示例
+
+#### 认证失败
+
+```json
+{
+  "code": 401,
+  "data": null,
+  "message": "Token无效或已过期"
+}
+```
+
+#### 参数错误
+
+```json
+{
+  "code": 400,
+  "data": null,
+  "message": "缺少必需参数: id"
+}
+```
+
+#### 资源不存在
+
+```json
+{
+  "code": 404,
+  "data": null,
+  "message": "用户不存在"
+}
+```
+
+#### 业务错误
+
+```json
+{
+  "code": -1,
+  "data": null,
+  "message": "解锁密钥错误"
+}
+```
+
+## 📊 响应格式
+
+### 成功响应
+
+所有成功的 API 响应都遵循以下格式：
+
+```json
+{
+  "code": 0,
+  "data": <响应数据>,
+  "message": "成功信息（可选）"
+}
+```
+
+### 分页响应
+
+对于列表接口，支持分页响应：
+
+```json
+{
+  "code": 0,
+  "data": {
+    "items": [...],
+    "pagination": {
+      "page": 1,
+      "size": 20,
+      "total": 100,
+      "totalPages": 5
+    }
+  },
+  "message": ""
+}
+```
+
+### 缓存响应头
+
+支持缓存控制的响应头：
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+Cache-Control: public, max-age=300
+ETag: "abc123"
+Last-Modified: Wed, 01 Jan 2024 12:00:00 GMT
+```
+
+## 💻 示例代码
+
+### JavaScript/TypeScript
+
+```typescript
+// 用户认证
+async function login(email: string, password: string) {
+  const response = await fetch('/public/auth/yt_user/login', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({ email, password })
+  });
+  
+  const result = await response.json();
+  if (result.code === 0) {
+    localStorage.setItem('token', result.data.token);
+    return result.data.user;
+  } else {
+    throw new Error(result.message);
+  }
+}
+
+// 获取用户信息
+async function getUserInfo() {
+  const token = localStorage.getItem('token');
+  const response = await fetch('/home/user/yt_user', {
+    headers: {
+      'Authorization': `Bearer ${token}`
+    }
+  });
+  
+  const result = await response.json();
+  if (result.code === 0) {
+    return result.data;
+  } else {
+    throw new Error(result.message);
+  }
+}
+
+// 获取商品信息
+async function getGoodsInfo(goodsId: number) {
+  const token = localStorage.getItem('token');
+  const response = await fetch(`/home/goods/common?id=${goodsId}`, {
+    headers: {
+      'Authorization': `Bearer ${token}`
+    }
+  });
+  
+  const result = await response.json();
+  if (result.code === 0) {
+    return result.data;
+  } else {
+    throw new Error(result.message);
+  }
+}
+```
+
+### Python
+
+```python
+import requests
+import json
+
+class DPKoaClient:
+    def __init__(self, base_url='http://localhost:3000'):
+        self.base_url = base_url
+        self.token = None
+    
+    def login(self, email, password):
+        url = f"{self.base_url}/public/auth/yt_user/login"
+        data = {"email": email, "password": password}
+        
+        response = requests.post(url, json=data)
+        result = response.json()
+        
+        if result['code'] == 0:
+            self.token = result['data']['token']
+            return result['data']['user']
+        else:
+            raise Exception(result['message'])
+    
+    def get_user_info(self):
+        if not self.token:
+            raise Exception("请先登录")
+        
+        url = f"{self.base_url}/home/user/yt_user"
+        headers = {"Authorization": f"Bearer {self.token}"}
+        
+        response = requests.get(url, headers=headers)
+        result = response.json()
+        
+        if result['code'] == 0:
+            return result['data']
+        else:
+            raise Exception(result['message'])
+    
+    def get_goods_info(self, goods_id):
+        if not self.token:
+            raise Exception("请先登录")
+        
+        url = f"{self.base_url}/home/goods/common"
+        headers = {"Authorization": f"Bearer {self.token}"}
+        params = {"id": goods_id}
+        
+        response = requests.get(url, headers=headers, params=params)
+        result = response.json()
+        
+        if result['code'] == 0:
+            return result['data']
+        else:
+            raise Exception(result['message'])
+
+# 使用示例
+client = DPKoaClient()
+user = client.login('user@example.com', 'password123')
+print(f"登录成功: {user['nickName']}")
+
+user_info = client.get_user_info()
+print(f"用户信息: {user_info}")
+
+goods_info = client.get_goods_info(1)
+print(f"商品信息: {goods_info}")
+```
+
+### cURL
+
+```bash
+# 用户登录
+curl -X POST http://localhost:3000/public/auth/yt_user/login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"user@example.com","password":"password123"}'
+
+# 获取用户信息
+curl -X GET http://localhost:3000/home/user/yt_user \
+  -H "Authorization: Bearer YOUR_JWT_TOKEN"
+
+# 获取商品信息
+curl -X GET "http://localhost:3000/home/goods/common?id=1" \
+  -H "Authorization: Bearer YOUR_JWT_TOKEN"
+
+# 健康检查
+curl -X GET http://localhost:3000/health
+
+# 详细健康检查
+curl -X GET http://localhost:3000/health/detailed
+```
+
+## 📚 相关文档
+
+- [快速开始指南](QUICK_START.md) - 5分钟快速上手
+- [开发指南](DEVELOPMENT_GUIDE.md) - 开发规范和最佳实践
+- [Swagger 集成指南](SWAGGER_INTEGRATION_GUIDE.md) - Swagger 文档配置
+- [故障排除指南](TROUBLESHOOTING.md) - 常见问题解决
+
+---
+
+**相关链接**:
+- [Swagger UI](http://localhost:3000/swagger-ui) - 在线 API 文档
+- [健康检查](http://localhost:3000/health) - 系统状态检查
+- [系统指标](http://localhost:3000/metrics) - 性能指标
+
+