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. 直接使用生成器

```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)
```