feat: 完成第四批任务 (Task 6.2, 10.1-10.3)
Task 6.2 - 报告导出功能: - ReportExportService: 报告导出服务 - ExportToMarkdown: Markdown 格式导出 - ExportToHtml: HTML 格式导出（可打印为 PDF） - ExportToPdf: PDF 导出（HTML 包装） Task 10.1-10.3 - 文档和打包: - README.md: 项目主文档 - docs/USAGE.md: 使用指南（CLI 命令、API、Web 界面） - docs/DEVELOPMENT.md: 开发指南（项目结构、构建、测试、部署） - docs/API.md: API 参考文档（端点、认证、错误码） - Dockerfile: Web API Docker 镜像 - docker-compose.yml: Docker Compose 配置 - .dockerignore: Docker 忽略文件 - NuGet 打包配置 (CodePlay.Core.csproj) 测试：42 个 (41 通过，1 跳过) ✅ 新增文件: - CodePlay.Core/Services/ReportExportService.cs - README.md - docs/USAGE.md - docs/DEVELOPMENT.md - docs/API.md - Dockerfile - docker-compose.yml - .dockerignore Co-authored-by: monkeycode-ai <monkeycode-ai@chaitin.com>
This commit is contained in:
monkeycode-ai
+129
@@ -0,0 +1,129 @@
|
||||
# CodePlay API 参考文档
|
||||
|
||||
## 基础 URL
|
||||
```
|
||||
开发环境：http://localhost:5000/api
|
||||
生产环境：https://your-domain.com/api
|
||||
```
|
||||
|
||||
## 认证
|
||||
|
||||
所有 API 端点（除 /api/auth/login 外）都需要 JWT Token 认证。
|
||||
|
||||
### 获取 Token
|
||||
```http
|
||||
POST /api/auth/login
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"username": "user",
|
||||
"password": "password"
|
||||
}
|
||||
```
|
||||
|
||||
响应：
|
||||
```json
|
||||
{
|
||||
"token": "eyJhbGc...",
|
||||
"username": "user",
|
||||
"expiresIn": 3600
|
||||
}
|
||||
```
|
||||
|
||||
### 使用 Token
|
||||
```http
|
||||
Authorization: Bearer eyJhbGc...
|
||||
```
|
||||
|
||||
## API 端点
|
||||
|
||||
### 转换 (Conversion)
|
||||
|
||||
#### POST /conversion/convert
|
||||
转换代码
|
||||
|
||||
**请求体**:
|
||||
```json
|
||||
{
|
||||
"sourceCode": "string",
|
||||
"sourceLanguage": "CSharp",
|
||||
"targetLanguage": "Java",
|
||||
"validationRounds": 2,
|
||||
"options": {
|
||||
"keepComments": true,
|
||||
"keepDocStrings": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"transformedCode": "string",
|
||||
"report": {
|
||||
"linesConverted": 100,
|
||||
"classesConverted": 5
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 报告 (Report)
|
||||
|
||||
#### GET /report
|
||||
获取所有报告
|
||||
|
||||
#### GET /report/{id}
|
||||
获取指定报告
|
||||
|
||||
#### DELETE /report/{id}
|
||||
删除报告
|
||||
|
||||
#### GET /report/stats
|
||||
获取统计信息
|
||||
|
||||
### 项目 (Project)
|
||||
|
||||
#### GET /project
|
||||
获取项目列表
|
||||
|
||||
#### POST /project
|
||||
创建项目
|
||||
|
||||
#### GET /project/{id}
|
||||
获取项目详情
|
||||
|
||||
#### PUT /project/{id}
|
||||
更新项目
|
||||
|
||||
#### DELETE /project/{id}
|
||||
删除项目
|
||||
|
||||
### 认证 (Auth)
|
||||
|
||||
#### POST /auth/login
|
||||
用户登录
|
||||
|
||||
#### POST /auth/refresh
|
||||
刷新 Token
|
||||
|
||||
#### GET /auth/me
|
||||
获取当前用户信息
|
||||
|
||||
## 错误码
|
||||
|
||||
| 状态码 | 说明 |
|
||||
|--------|------|
|
||||
| 200 | 成功 |
|
||||
| 400 | 请求参数错误 |
|
||||
| 401 | 未授权 |
|
||||
| 403 | 禁止访问 |
|
||||
| 404 | 资源不存在 |
|
||||
| 429 | 请求过于频繁 |
|
||||
| 500 | 服务器内部错误 |
|
||||
|
||||
## 限流
|
||||
|
||||
- 限制：60 请求/分钟/IP
|
||||
- 超出返回 429 状态码
|
||||
- 响应头包含 Retry-After
|
||||
@@ -0,0 +1,128 @@
|
||||
# CodePlay 开发指南
|
||||
|
||||
## 项目结构
|
||||
|
||||
```
|
||||
CodePlay/
|
||||
├── CodePlay.Core/ # 核心转换引擎
|
||||
├── CodePlay.Persistence/ # 数据持久化层
|
||||
├── CodePlay.WebAPI/ # ASP.NET Core Web API
|
||||
├── CodePlay.CLI/ # 命令行工具
|
||||
├── CodePlay.Web/ # Vue3 前端
|
||||
├── CodePlay.WebUI/ # Blazor 管理端
|
||||
└── CodePlay.Tests/ # 单元测试
|
||||
```
|
||||
|
||||
## 开发环境配置
|
||||
|
||||
### 1. 安装 .NET 8.0 SDK
|
||||
https://dotnet.microsoft.com/download
|
||||
|
||||
### 2. 安装 Node.js 18+
|
||||
https://nodejs.org/
|
||||
|
||||
### 3. 克隆并还原依赖
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd CodePlay
|
||||
dotnet restore
|
||||
```
|
||||
|
||||
### 4. 安装前端依赖
|
||||
```bash
|
||||
cd CodePlay.Web
|
||||
npm install
|
||||
```
|
||||
|
||||
## 构建和测试
|
||||
|
||||
### 编译所有项目
|
||||
```bash
|
||||
dotnet build
|
||||
```
|
||||
|
||||
### 运行单元测试
|
||||
```bash
|
||||
dotnet test --logger "console;verbosity=normal"
|
||||
```
|
||||
|
||||
### 查看测试覆盖率
|
||||
```bash
|
||||
dotnet test /p:CollectCoverage=true
|
||||
```
|
||||
|
||||
### 代码格式化
|
||||
```bash
|
||||
dotnet format
|
||||
```
|
||||
|
||||
## 添加新功能
|
||||
|
||||
### 1. 添加新的转换器
|
||||
1. 在 `CodePlay.Core/Converters/` 创建新类
|
||||
2. 实现 `IConverter` 接口
|
||||
3. 在 `ConversionService` 中注册
|
||||
|
||||
### 2. 添加新的 API 端点
|
||||
1. 在 `CodePlay.WebAPI/Controllers/` 创建控制器
|
||||
2. 添加 `[Authorize]` 特性 (如需认证)
|
||||
3. 实现 CRUD 方法
|
||||
|
||||
### 3. 添加前端组件
|
||||
1. 在 `CodePlay.Web/src/components/` 创建组件
|
||||
2. 在 `views/` 创建页面
|
||||
3. 更新路由配置
|
||||
|
||||
## 调试技巧
|
||||
|
||||
### 日志查看
|
||||
```bash
|
||||
# 查看实时日志
|
||||
tail -f logs/codeplay-*.log
|
||||
```
|
||||
|
||||
### API 测试
|
||||
使用 Swagger UI: http://localhost:5000/swagger
|
||||
|
||||
### 前端调试
|
||||
使用浏览器开发者工具的 Vue Devtools
|
||||
|
||||
## 提交代码
|
||||
|
||||
```bash
|
||||
# 1. 确保测试通过
|
||||
dotnet test
|
||||
|
||||
# 2. 格式化代码
|
||||
dotnet format
|
||||
|
||||
# 3. 提交
|
||||
git add .
|
||||
git commit -m "feat: description"
|
||||
git push
|
||||
```
|
||||
|
||||
## 发布 NuGet 包
|
||||
|
||||
```bash
|
||||
# 1. 更新版本号
|
||||
# 编辑 CodePlay.Core.csproj 中的 <Version>
|
||||
|
||||
# 2. 打包
|
||||
dotnet pack CodePlay.Core/CodePlay.Core.csproj -c Release
|
||||
|
||||
# 3. 发布
|
||||
dotnet nuget push CodePlay.Core.1.0.0.nupkg \
|
||||
--source "https://api.nuget.org/v3/index.json" \
|
||||
--api-key YOUR_API_KEY
|
||||
```
|
||||
|
||||
## Docker 部署
|
||||
|
||||
```bash
|
||||
# 构建镜像
|
||||
docker build -t codeplay:latest .
|
||||
|
||||
# 运行
|
||||
docker run -d -p 5000:80 codeplay:latest
|
||||
```
|
||||
Reference in New Issue
Block a user