tyapi-server/internal/shared/component_report/README.md

组件报告生成服务

这个服务用于生成产品示例报告的 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. 直接使用生成器

// 创建生成器
exampleJSONGenerator := component_report.NewExampleJSONGenerator(
    productRepo,
    docRepo,
    apiConfigRepo,
    logger,
)

// 生成 example.json
jsonData, err := exampleJSONGenerator.GenerateExampleJSON(
    ctx,
    productID,        // 产品ID（可以是组合包或单品）
    subProductCodes,  // 子产品编号列表（可选，如果为空则处理所有子产品）
)

2. 生成 ZIP 文件

// 创建ZIP生成器
zipGenerator := component_report.NewZipGenerator(logger)

// 生成ZIP文件
zipPath, err := zipGenerator.GenerateZipFile(
    ctx,
    productID,
    subProductCodes,
    exampleJSONGenerator,
    outputPath,  // 输出路径（可选，如果为空则使用默认路径）
)

3. 使用 HTTP 接口

生成 example.json

POST /api/v1/component-report/generate-example-json
Content-Type: application/json

{
  "product_id": "产品ID",
  "sub_product_codes": ["子产品编号1", "子产品编号2"]  // 可选
}

响应：

{
  "product_id": "产品ID",
  "json_content": "生成的JSON内容",
  "json_size": 1234
}

生成 ZIP 文件

POST /api/v1/component-report/generate-zip
Content-Type: application/json

{
  "product_id": "产品ID",
  "sub_product_codes": ["子产品编号1", "子产品编号2"],  // 可选
  "output_path": "自定义输出路径"  // 可选
}

响应：

{
  "code": 200,
  "message": "ZIP文件生成成功",
  "zip_path": "storage/component-reports/xxx_example.json.zip",
  "file_size": 12345,
  "file_name": "xxx_example.json.zip"
}

生成并下载 ZIP 文件

POST /api/v1/component-report/generate-and-download
Content-Type: application/json

{
  "product_id": "产品ID",
  "sub_product_codes": ["子产品编号1", "子产品编号2"]  // 可选
}

响应：直接返回 ZIP 文件流

下载已生成的 ZIP 文件

GET /api/v1/component-report/download-zip/:product_id

响应：直接返回 ZIP 文件流

example.json 格式

生成的 example.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 接口，需要在路由中注册：

// 创建处理器
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)