addui

internal/shared/component_report/README.md

@@ -0,0 +1,204 @@
+# 组件报告生成服务
+
+这个服务用于生成产品示例报告的 `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)
+```