205 lines
4.6 KiB
Markdown
205 lines
4.6 KiB
Markdown
# 组件报告生成服务
|
||
|
||
这个服务用于生成产品示例报告的 `example.json` 文件，并打包成 ZIP 文件供下载。
|
||
|
||
## 功能概述
|
||
|
||
1. **生成 example.json 文件**：根据组合包子产品的响应示例数据生成符合格式要求的 JSON 文件
|
||
2. **打包 ZIP 文件**：将生成的 `example.json` 文件打包成 ZIP 格式
|
||
3. **HTTP 接口**：提供 HTTP 接口用于生成和下载文件
|
||
|
||
## 文件结构
|
||
|
||
```
|
||
component_report/
|
||
├── example_json_generator.go # 示例JSON生成器
|
||
├── zip_generator.go # ZIP文件生成器
|
||
├── handler.go # HTTP处理器
|
||
└── README.md # 说明文档
|
||
```
|
||
|
||
## 使用方法
|
||
|
||
### 1. 直接使用生成器
|
||
|
||
```go
|
||
// 创建生成器
|
||
exampleJSONGenerator := component_report.NewExampleJSONGenerator(
|
||
productRepo,
|
||
docRepo,
|
||
apiConfigRepo,
|
||
logger,
|
||
)
|
||
|
||
// 生成 example.json
|
||
jsonData, err := exampleJSONGenerator.GenerateExampleJSON(
|
||
ctx,
|
||
productID, // 产品ID（可以是组合包或单品）
|
||
subProductCodes, // 子产品编号列表（可选，如果为空则处理所有子产品）
|
||
)
|
||
```
|
||
|
||
### 2. 生成 ZIP 文件
|
||
|
||
```go
|
||
// 创建ZIP生成器
|
||
zipGenerator := component_report.NewZipGenerator(logger)
|
||
|
||
// 生成ZIP文件
|
||
zipPath, err := zipGenerator.GenerateZipFile(
|
||
ctx,
|
||
productID,
|
||
subProductCodes,
|
||
exampleJSONGenerator,
|
||
outputPath, // 输出路径（可选，如果为空则使用默认路径）
|
||
)
|
||
```
|
||
|
||
### 3. 使用 HTTP 接口
|
||
|
||
#### 生成 example.json
|
||
|
||
```http
|
||
POST /api/v1/component-report/generate-example-json
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"product_id": "产品ID",
|
||
"sub_product_codes": ["子产品编号1", "子产品编号2"] // 可选
|
||
}
|
||
```
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"product_id": "产品ID",
|
||
"json_content": "生成的JSON内容",
|
||
"json_size": 1234
|
||
}
|
||
```
|
||
|
||
#### 生成 ZIP 文件
|
||
|
||
```http
|
||
POST /api/v1/component-report/generate-zip
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"product_id": "产品ID",
|
||
"sub_product_codes": ["子产品编号1", "子产品编号2"], // 可选
|
||
"output_path": "自定义输出路径" // 可选
|
||
}
|
||
```
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "ZIP文件生成成功",
|
||
"zip_path": "storage/component-reports/xxx_example.json.zip",
|
||
"file_size": 12345,
|
||
"file_name": "xxx_example.json.zip"
|
||
}
|
||
```
|
||
|
||
#### 生成并下载 ZIP 文件
|
||
|
||
```http
|
||
POST /api/v1/component-report/generate-and-download
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"product_id": "产品ID",
|
||
"sub_product_codes": ["子产品编号1", "子产品编号2"] // 可选
|
||
}
|
||
```
|
||
|
||
响应：直接返回 ZIP 文件流
|
||
|
||
#### 下载已生成的 ZIP 文件
|
||
|
||
```http
|
||
GET /api/v1/component-report/download-zip/:product_id
|
||
```
|
||
|
||
响应：直接返回 ZIP 文件流
|
||
|
||
## example.json 格式
|
||
|
||
生成的 `example.json` 文件格式如下：
|
||
|
||
```json
|
||
[
|
||
{
|
||
"feature": {
|
||
"featureName": "产品名称",
|
||
"sort": 1
|
||
},
|
||
"data": {
|
||
"apiID": "产品编号",
|
||
"data": {
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": { ... }
|
||
}
|
||
}
|
||
},
|
||
{
|
||
"feature": {
|
||
"featureName": "另一个产品名称",
|
||
"sort": 2
|
||
},
|
||
"data": {
|
||
"apiID": "另一个产品编号",
|
||
"data": { ... }
|
||
}
|
||
}
|
||
]
|
||
```
|
||
|
||
## 响应示例数据提取优先级
|
||
|
||
1. **产品文档的 `response_example` 字段**（JSON格式）
|
||
2. **产品文档的 `response_example` 字段**（Markdown代码块中的JSON）
|
||
3. **产品API配置的 `response_example` 字段**
|
||
4. **默认空对象** `{}`（如果都没有）
|
||
|
||
## ZIP 文件结构
|
||
|
||
生成的 ZIP 文件结构：
|
||
|
||
```
|
||
component-report.zip
|
||
└── public/
|
||
└── example.json
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. 确保 `storage/component-reports` 目录存在且有写权限
|
||
2. 如果产品是组合包，会遍历所有子产品（或指定的子产品）生成响应示例
|
||
3. 如果某个子产品没有响应示例数据，会使用空对象 `{}` 作为默认值
|
||
4. ZIP 文件会保存在 `storage/component-reports` 目录下，文件名为 `{productID}_example.json.zip`
|
||
|
||
## 集成到路由
|
||
|
||
如果需要使用 HTTP 接口，需要在路由中注册：
|
||
|
||
```go
|
||
// 创建处理器
|
||
componentReportHandler := component_report.NewComponentReportHandler(
|
||
productRepo,
|
||
docRepo,
|
||
apiConfigRepo,
|
||
logger,
|
||
)
|
||
|
||
// 注册路由
|
||
router.POST("/api/v1/component-report/generate-example-json", componentReportHandler.GenerateExampleJSON)
|
||
router.POST("/api/v1/component-report/generate-zip", componentReportHandler.GenerateZip)
|
||
router.POST("/api/v1/component-report/generate-and-download", componentReportHandler.GenerateAndDownloadZip)
|
||
router.GET("/api/v1/component-report/download-zip/:product_id", componentReportHandler.DownloadZip)
|
||
```
|