team/tyapi-server
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
39c46937ea1c5b3e0dcbe6c060e5a34fd2e1a68e
tyapi-server/docs/产品示例报告下载功能实现方案.md

1002 lines
33 KiB
Markdown
Raw Normal View History

Enhance ProductRoutes to include component report handling and related routes
2025-12-17 16:13:13 +08:00
# 产品示例报告下载功能实现方案
## 一、功能概述
在产品详情页面添加"下载示例报告"功能，允许用户下载与产品对应的前端组件报告。报告文件位于 `resources/Pure Component/src/ui` 目录下，通过产品编号（product_code）匹配对应的文件夹或文件。
## 二、核心需求
### 2.1 基本功能
1. **报告匹配**：根据子产品的 `product_code` 模糊匹配 `resources/Pure Component/src/ui` 下的文件夹或文件
- 支持前缀匹配（如产品编号为 `DWBG6A2C`，文件夹可能是 `DWBG6A2C` 或 `多cDWBG6A2C`）
- 匹配规则：文件夹名称包含产品编号，或产品编号包含文件夹名称的核心部分
2. **文件打包**：将匹配到的文件夹或文件压缩成 ZIP 格式供用户下载
- ZIP 文件结构：
```text
component-report.zip
├── src/
│ └── ui/
│ ├── DWBG6A2C/ # 子产品1的UI组件
│ │ ├── index.vue
│ │ ├── components/
│ │ └── ...
│ ├── CFLXG0V4B/ # 子产品2的UI组件
│ └── ...
└── public/
└── example.json # 响应示例数据文件
```
- 同时需要生成 `public/example.json` 文件，包含子产品的响应示例数据
- `example.json` 文件格式：
```json
[
{
"feature": {
"featureName": "产品名称",
"sort": 1
},
"data": {
"apiID": "产品编号",
"data": {
// 子产品的响应示例数据（JSON对象）
"code": 0,
"message": "success",
"data": { ... }
}
}
},
{
"feature": {
"featureName": "另一个产品名称",
"sort": 2
},
"data": {
"apiID": "另一个产品编号",
"data": { ... }
}
}
]
```
3. **支付流程**：
- 下载前检查用户已下载过的组件报告
- 根据子产品价格计算报告总价（已下载过的子产品价格需减免）
- 用户扫码支付（微信/支付宝）成功后允许下载
### 2.2 组合包产品特殊处理
1. **子产品筛选**：组合包产品只下载包含的子产品对应的报告
2. **价格减免**：如果用户已下载过某个子产品的报告，该子产品的价格不计入总价
3. **批量下载**：将多个子产品的报告打包成一个 ZIP 文件
### 2.3 性能优化
1. **缓存机制**：
- 缓存已生成的 ZIP 文件（基于产品ID和子产品列表的哈希值）
- 缓存文件匹配结果（产品编号到文件夹路径的映射）
- 缓存有效期：24小时
2. **二次下载**：
- 用户已支付过的报告支持免费重新下载（在有效期内）
- 记录下载历史，避免重复支付
## 三、数据库设计
### 3.1 报告下载记录表 (component_report_downloads)
```sql
CREATE TABLE component_report_downloads (
id VARCHAR(36) PRIMARY KEY,
user_id VARCHAR(36) NOT NULL,
product_id VARCHAR(36) NOT NULL,
product_code VARCHAR(50) NOT NULL,
sub_product_ids TEXT, -- JSON数组，存储子产品ID列表（组合包使用）
sub_product_codes TEXT, -- JSON数组，存储子产品编号列表
download_price DECIMAL(10,2) NOT NULL, -- 实际支付价格
original_price DECIMAL(10,2) NOT NULL, -- 原始总价
discount_amount DECIMAL(10,2) DEFAULT 0, -- 减免金额
payment_order_id VARCHAR(64), -- 支付订单号（关联充值记录）
payment_type VARCHAR(20), -- 支付类型：alipay, wechat
payment_status VARCHAR(20) DEFAULT 'pending', -- pending, success, failed
file_path VARCHAR(500), -- 生成的ZIP文件路径（用于二次下载）
file_hash VARCHAR(64), -- 文件哈希值（用于缓存验证）
download_count INT DEFAULT 0, -- 下载次数
last_download_at TIMESTAMP, -- 最后下载时间
expires_at TIMESTAMP, -- 下载有效期（支付成功后30天）
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
deleted_at TIMESTAMP NULL,
INDEX idx_user_id (user_id),
INDEX idx_product_id (product_id),
INDEX idx_product_code (product_code),
INDEX idx_payment_status (payment_status),
INDEX idx_expires_at (expires_at)
);
```
### 3.2 报告文件匹配缓存表 (component_report_cache)
```sql
CREATE TABLE component_report_cache (
id VARCHAR(36) PRIMARY KEY,
product_code VARCHAR(50) NOT NULL UNIQUE,
matched_path VARCHAR(500) NOT NULL, -- 匹配到的文件夹/文件路径
file_type VARCHAR(20) NOT NULL, -- folder, file
cache_key VARCHAR(64) NOT NULL UNIQUE, -- 缓存键（用于ZIP文件缓存）
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
INDEX idx_product_code (product_code),
INDEX idx_cache_key (cache_key)
);
```
## 四、后端实现方案
### 4.1 领域层 (Domain Layer)
#### 4.1.1 实体定义
**文件位置**: `internal/domains/product/entities/component_report_download.go`
```go
package entities
import (
"time"
"github.com/google/uuid"
"github.com/shopspring/decimal"
"gorm.io/gorm"
)
// ComponentReportDownload 组件报告下载记录
type ComponentReportDownload struct {
ID string `gorm:"primaryKey;type:varchar(36)"`
UserID string `gorm:"type:varchar(36);not null;index"`
ProductID string `gorm:"type:varchar(36);not null;index"`
ProductCode string `gorm:"type:varchar(50);not null;index"`
SubProductIDs string `gorm:"type:text"` // JSON数组
SubProductCodes string `gorm:"type:text"` // JSON数组
DownloadPrice decimal.Decimal `gorm:"type:decimal(10,2);not null"`
OriginalPrice decimal.Decimal `gorm:"type:decimal(10,2);not null"`
DiscountAmount decimal.Decimal `gorm:"type:decimal(10,2);default:0"`
PaymentOrderID *string `gorm:"type:varchar(64)"`
PaymentType *string `gorm:"type:varchar(20)"`
PaymentStatus string `gorm:"type:varchar(20);default:'pending';index"`
FilePath *string `gorm:"type:varchar(500)"`
FileHash *string `gorm:"type:varchar(64)"`
DownloadCount int `gorm:"default:0"`
LastDownloadAt *time.Time
ExpiresAt *time.Time `gorm:"index"`
CreatedAt time.Time `gorm:"autoCreateTime"`
UpdatedAt time.Time `gorm:"autoUpdateTime"`
DeletedAt gorm.DeletedAt `gorm:"index"`
}
// ComponentReportCache 报告文件匹配缓存
type ComponentReportCache struct {
ID string `gorm:"primaryKey;type:varchar(36)"`
ProductCode string `gorm:"type:varchar(50);not null;uniqueIndex"`
MatchedPath string `gorm:"type:varchar(500);not null"`
FileType string `gorm:"type:varchar(20);not null"`
CacheKey string `gorm:"type:varchar(64);not null;uniqueIndex"`
CreatedAt time.Time `gorm:"autoCreateTime"`
UpdatedAt time.Time `gorm:"autoUpdateTime"`
}
```
#### 4.1.2 仓储接口
**文件位置**: `internal/domains/product/repositories/component_report_repository_interface.go`
```go
package repositories
import (
"context"
"tyapi-server/internal/domains/product/entities"
)
// ComponentReportRepository 组件报告仓储接口
type ComponentReportRepository interface {
// 创建下载记录
CreateDownload(ctx context.Context, download *entities.ComponentReportDownload) (*entities.ComponentReportDownload, error)
// 更新下载记录
UpdateDownload(ctx context.Context, download *entities.ComponentReportDownload) error
// 根据ID获取下载记录
GetDownloadByID(ctx context.Context, id string) (*entities.ComponentReportDownload, error)
// 获取用户的下载记录列表
GetUserDownloads(ctx context.Context, userID string, productID *string) ([]*entities.ComponentReportDownload, error)
// 检查用户是否已下载过指定产品
HasUserDownloaded(ctx context.Context, userID string, productCode string) (bool, error)
// 获取用户已下载的产品编号列表
GetUserDownloadedProductCodes(ctx context.Context, userID string) ([]string, error)
// 根据支付订单号获取下载记录
GetDownloadByPaymentOrderID(ctx context.Context, orderID string) (*entities.ComponentReportDownload, error)
// 缓存相关
GetCacheByProductCode(ctx context.Context, productCode string) (*entities.ComponentReportCache, error)
CreateCache(ctx context.Context, cache *entities.ComponentReportCache) error
UpdateCache(ctx context.Context, cache *entities.ComponentReportCache) error
}
```
#### 4.1.3 领域服务
**文件位置**: `internal/domains/product/services/component_report_service.go`
```go
package services
import (
"context"
"path/filepath"
"strings"
"os"
"tyapi-server/internal/domains/product/repositories"
)
// ComponentReportService 组件报告服务
type ComponentReportService interface {
// 匹配产品编号到文件路径
MatchProductCodeToPath(ctx context.Context, productCode string) (string, string, error) // 返回路径和类型
// 计算报告价格（考虑已下载的产品）
CalculateReportPrice(ctx context.Context, userID string, productID string, subProductCodes []string) (decimal.Decimal, decimal.Decimal, []string, error) // 返回总价、减免金额、已下载的产品编号列表
// 生成 example.json 文件内容
GenerateExampleJSON(ctx context.Context, productID string, subProductCodes []string) ([]byte, error)
// 生成ZIP文件
GenerateZipFile(ctx context.Context, productID string, subProductCodes []string, cacheKey string) (string, string, error) // 返回文件路径和哈希值
// 验证下载权限
ValidateDownloadPermission(ctx context.Context, userID string, downloadID string) (bool, error)
}
```
### 4.2 应用层 (Application Layer)
**文件位置**: `internal/application/product/component_report_application_service.go`
```go
package application
import (
"context"
"tyapi-server/internal/domains/product/services"
"tyapi-server/internal/domains/finance/services"
)
// ComponentReportApplicationService 组件报告应用服务
type ComponentReportApplicationService interface {
// 1. 获取报告下载信息（价格、已下载列表等）
GetReportDownloadInfo(ctx context.Context, userID string, productID string) (*ReportDownloadInfoResponse, error)
// 2. 创建支付订单
CreateReportPaymentOrder(ctx context.Context, userID string, productID string) (*PaymentOrderResponse, error)
// 3. 处理支付成功回调
HandlePaymentSuccess(ctx context.Context, orderID string) error
// 4. 下载报告文件
DownloadReport(ctx context.Context, userID string, downloadID string) (*DownloadResponse, error)
// 5. 获取用户下载历史
GetUserDownloadHistory(ctx context.Context, userID string, params *PaginationParams) (*DownloadHistoryResponse, error)
}
```
### 4.3 接口层 (Interface Layer)
**文件位置**: `internal/infrastructure/http/handlers/component_report_handler.go`
#### API 接口设计
1. **GET `/api/v1/products/{productId}/component-report/info`**
- 获取报告下载信息（价格、已下载列表等）
- 响应示例：
```json
{
"code": 200,
"data": {
"product_id": "xxx",
"product_code": "DWBG6A2C",
"is_package": true,
"sub_products": [
{
"product_id": "xxx",
"product_code": "DWBG6A2C",
"product_name": "产品名称",
"price": 100.00,
"is_downloaded": false,
"matched": true,
"has_response_example": true
}
],
"original_total_price": 300.00,
"discount_amount": 100.00,
"final_price": 200.00,
"downloaded_product_codes": ["DWBG6A2C"],
"includes_example_json": true
}
}
```
2. **POST `/api/v1/products/{productId}/component-report/create-order`**
- 创建支付订单
- 请求体：
```json
{
"payment_type": "wechat" // 或 "alipay"
}
```
- 响应：返回支付二维码URL或支付链接
3. **POST `/api/v1/products/{productId}/component-report/payment-callback`**
- 支付成功回调（内部调用，由支付服务触发）
4. **GET `/api/v1/products/{productId}/component-report/download/{downloadId}`**
- 下载报告文件
- 响应：ZIP文件流
5. **GET `/api/v1/my/component-reports`**
- 获取用户下载历史
- 查询参数：page, page_size, product_id
## 五、前端实现方案
### 5.1 API 接口定义
**文件位置**: `tyapi-frontend/src/api/index.js`
```javascript
// 组件报告相关接口
export const componentReportApi = {
// 获取报告下载信息
getReportDownloadInfo: (productId) => request.get(`/products/${productId}/component-report/info`),
// 创建支付订单
createReportPaymentOrder: (productId, data) => request.post(`/products/${productId}/component-report/create-order`, data),
// 下载报告
downloadReport: (productId, downloadId) => request.get(`/products/${productId}/component-report/download/${downloadId}`, {
responseType: 'blob'
}),
// 获取用户下载历史
getUserDownloadHistory: (params) => request.get('/my/component-reports', { params })
}
```
### 5.2 页面组件修改
**文件位置**: `tyapi-frontend/src/pages/products/detail.vue`
#### 5.2.1 添加下载按钮
在页面头部操作区域添加"下载示例报告"按钮：
```vue
<el-button
v-if="isSubscribed"
:size="isMobile ? 'small' : 'default'"
type="success"
@click="handleDownloadReport"
:loading="reportDownloading"
>
<el-icon><Download /></el-icon>
下载示例报告
</el-button>
```
#### 5.2.2 下载流程实现
```javascript
// 响应式数据
const reportDownloading = ref(false)
const reportDownloadInfo = ref(null)
const showReportPaymentDialog = ref(false)
const reportPaymentType = ref('wechat') // 或 'alipay'
// 获取报告下载信息
const loadReportDownloadInfo = async () => {
if (!product.value) return
try {
const response = await componentReportApi.getReportDownloadInfo(product.value.id)
reportDownloadInfo.value = response.data
} catch (error) {
console.error('获取报告下载信息失败:', error)
}
}
// 处理下载报告
const handleDownloadReport = async () => {
if (!product.value) return
try {
// 1. 获取下载信息
await loadReportDownloadInfo()
// 2. 如果价格大于0，需要支付
if (reportDownloadInfo.value.final_price > 0) {
showReportPaymentDialog.value = true
return
}
// 3. 如果已支付过，直接下载
await downloadReportFile()
} catch (error) {
console.error('下载报告失败:', error)
ElMessage.error('下载报告失败')
}
}
// 创建支付订单并支付
const createReportPayment = async () => {
if (!product.value) return
try {
const response = await componentReportApi.createReportPaymentOrder(
product.value.id,
{ payment_type: reportPaymentType.value }
)
// 显示支付二维码（参考现有的支付流程）
if (reportPaymentType.value === 'wechat') {
await showWechatQrCode(response.data.code_url)
} else {
// 支付宝支付
window.location.href = response.data.pay_url
}
// 开始轮询支付状态
startPaymentPolling(response.data.order_id)
} catch (error) {
console.error('创建支付订单失败:', error)
ElMessage.error('创建支付订单失败')
}
}
// 下载报告文件
const downloadReportFile = async (downloadId) => {
if (!product.value) return
reportDownloading.value = true
try {
// 如果没有downloadId，从下载信息中获取
const id = downloadId || reportDownloadInfo.value?.download_id
if (!id) {
ElMessage.warning('请先完成支付')
return
}
const response = await componentReportApi.downloadReport(product.value.id, id)
// 创建下载链接
const blob = new Blob([response.data], { type: 'application/zip' })
const url = URL.createObjectURL(blob)
const link = document.createElement('a')
link.href = url
link.download = `${product.value.name || '产品'}_示例报告.zip`
document.body.appendChild(link)
link.click()
document.body.removeChild(link)
URL.revokeObjectURL(url)
ElMessage.success('报告下载成功')
// 关闭支付对话框
showReportPaymentDialog.value = false
} catch (error) {
console.error('下载报告文件失败:', error)
ElMessage.error('下载报告文件失败')
} finally {
reportDownloading.value = false
}
}
```
## 六、核心算法实现
### 6.1 响应示例数据提取
在生成 `example.json` 时，需要从产品文档中提取响应示例数据。数据来源优先级：
1. **产品文档的 `response_example` 字段**（JSON格式）
2. **产品文档的 `response_example` 字段**（Markdown代码块中的JSON）
3. **产品API配置的 `response_example` 字段**（如果产品文档中没有）
4. **默认空对象** `{}`（如果都没有）
### 6.2 产品编号匹配算法
```go
// MatchProductCodeToPath 匹配产品编号到文件路径
func (s *ComponentReportServiceImpl) MatchProductCodeToPath(ctx context.Context, productCode string) (string, string, error) {
// 1. 先查缓存
cache, err := s.repo.GetCacheByProductCode(ctx, productCode)
if err == nil && cache != nil {
return cache.MatchedPath, cache.FileType, nil
}
// 2. 扫描目录
basePath := "resources/Pure Component/src/ui"
entries, err := os.ReadDir(basePath)
if err != nil {
return "", "", err
}
// 3. 模糊匹配
for _, entry := range entries {
name := entry.Name()
// 精确匹配
if name == productCode {
path := filepath.Join(basePath, name)
fileType := "folder"
if !entry.IsDir() {
fileType = "file"
}
// 保存到缓存
cache := &entities.ComponentReportCache{
ID: uuid.New().String(),
ProductCode: productCode,
MatchedPath: path,
FileType: fileType,
CacheKey: generateCacheKey(productCode),
}
s.repo.CreateCache(ctx, cache)
return path, fileType, nil
}
// 模糊匹配：文件夹名称包含产品编号，或产品编号包含文件夹名称的核心部分
if strings.Contains(name, productCode) || strings.Contains(productCode, extractCoreCode(name)) {
path := filepath.Join(basePath, name)
fileType := "folder"
if !entry.IsDir() {
fileType = "file"
}
// 保存到缓存
cache := &entities.ComponentReportCache{
ID: uuid.New().String(),
ProductCode: productCode,
MatchedPath: path,
FileType: fileType,
CacheKey: generateCacheKey(productCode),
}
s.repo.CreateCache(ctx, cache)
return path, fileType, nil
}
}
return "", "", fmt.Errorf("未找到匹配的报告文件: %s", productCode)
}
// extractCoreCode 提取文件夹名称的核心代码（去除前缀）
func extractCoreCode(name string) string {
// 如果名称以字母开头，提取后面的代码部分
// 例如：多cDWBG6A2C -> DWBG6A2C
for i, r := range name {
if (r >= 'A' && r <= 'Z') || (r >= '0' && r <= '9') {
return name[i:]
}
}
return name
}
```
### 6.3 价格计算算法
```go
// CalculateReportPrice 计算报告价格
func (s *ComponentReportServiceImpl) CalculateReportPrice(ctx context.Context, userID string, productID string, subProductCodes []string) (decimal.Decimal, decimal.Decimal, []string, error) {
// 1. 获取用户已下载的产品编号列表
downloadedCodes, err := s.repo.GetUserDownloadedProductCodes(ctx, userID)
if err != nil {
return decimal.Zero, decimal.Zero, nil, err
}
// 2. 获取产品信息（包括子产品价格）
product, err := s.productRepo.GetByID(ctx, productID)
if err != nil {
return decimal.Zero, decimal.Zero, nil, err
}
// 3. 计算总价和减免金额
originalTotal := decimal.Zero
discountAmount := decimal.Zero
downloadedList := []string{}
if product.IsPackage {
// 组合包：遍历子产品
for _, item := range product.PackageItems {
if contains(subProductCodes, item.ProductCode) {
originalTotal = originalTotal.Add(item.Price)
// 检查是否已下载
if contains(downloadedCodes, item.ProductCode) {
discountAmount = discountAmount.Add(item.Price)
downloadedList = append(downloadedList, item.ProductCode)
}
}
}
} else {
// 单品
originalTotal = product.Price
if contains(downloadedCodes, product.Code) {
discountAmount = product.Price
downloadedList = append(downloadedList, product.Code)
}
}
finalPrice := originalTotal.Sub(discountAmount)
return finalPrice, discountAmount, downloadedList, nil
}
```
### 6.4 example.json 文件生成算法
```go
// GenerateExampleJSON 生成 example.json 文件内容
func (s *ComponentReportServiceImpl) GenerateExampleJSON(ctx context.Context, productID string, subProductCodes []string) ([]byte, error) {
// 1. 获取产品信息（包括子产品）
product, err := s.productRepo.GetByID(ctx, productID)
if err != nil {
return nil, err
}
// 2. 构建 example.json 数组
var examples []map[string]interface{}
if product.IsPackage {
// 组合包：遍历子产品
for sort, item := range product.PackageItems {
// 只处理在 subProductCodes 列表中的子产品
if !contains(subProductCodes, item.ProductCode) {
continue
}
// 获取子产品的文档信息（包含响应示例）
subProduct, err := s.productRepo.GetByID(ctx, item.ProductID)
if err != nil {
s.logger.Warn("获取子产品信息失败", zap.String("product_id", item.ProductID), zap.Error(err))
continue
}
// 获取响应示例数据（优先级：文档 > API配置 > 默认值）
var responseData interface{}
responseData = s.extractResponseExample(ctx, subProduct)
// 构建示例项
example := map[string]interface{}{
"feature": map[string]interface{}{
"featureName": item.ProductName,
"sort": sort + 1,
},
"data": map[string]interface{}{
"apiID": item.ProductCode,
"data": responseData,
},
}
examples = append(examples, example)
}
} else {
// 单品
responseData := s.extractResponseExample(ctx, product)
example := map[string]interface{}{
"feature": map[string]interface{}{
"featureName": product.Name,
"sort": 1,
},
"data": map[string]interface{}{
"apiID": product.Code,
"data": responseData,
},
}
examples = append(examples, example)
}
// 3. 序列化为JSON
jsonData, err := json.MarshalIndent(examples, "", " ")
if err != nil {
return nil, fmt.Errorf("序列化example.json失败: %w", err)
}
return jsonData, nil
}
// extractResponseExample 提取产品响应示例数据（优先级：文档 > API配置 > 默认值）
func (s *ComponentReportServiceImpl) extractResponseExample(ctx context.Context, product *entities.Product) interface{} {
var responseData interface{}
// 1. 优先从产品文档中获取
if product.Documentation != nil && product.Documentation.ResponseExample != "" {
// 尝试直接解析为JSON
err := json.Unmarshal([]byte(product.Documentation.ResponseExample), &responseData)
if err == nil {
return responseData
}
// 如果解析失败，尝试从Markdown代码块中提取JSON
responseData = extractJSONFromMarkdown(product.Documentation.ResponseExample)
if responseData != nil {
return responseData
}
}
// 2. 如果文档中没有，尝试从产品API配置中获取
apiConfig, err := s.productApiConfigRepo.GetByProductID(ctx, product.ID)
if err == nil && apiConfig != nil && apiConfig.ResponseExample != nil {
// API配置的响应示例通常是 map[string]interface{} 类型
return apiConfig.ResponseExample
}
// 3. 如果都没有，返回默认空对象
return map[string]interface{}{}
}
// extractJSONFromMarkdown 从Markdown代码块中提取JSON
func extractJSONFromMarkdown(markdown string) interface{} {
// 查找 ```json 代码块
re := regexp.MustCompile("(?s)```json\\s*(.*?)\\s*```")
matches := re.FindStringSubmatch(markdown)
if len(matches) > 1 {
var jsonData interface{}
err := json.Unmarshal([]byte(matches[1]), &jsonData)
if err == nil {
return jsonData
}
}
// 如果提取失败，返回 nil（由调用者决定默认值）
return nil
}
```
### 6.5 ZIP文件生成算法
```go
// GenerateZipFile 生成ZIP文件
func (s *ComponentReportServiceImpl) GenerateZipFile(ctx context.Context, productID string, subProductCodes []string, cacheKey string) (string, string, error) {
// 1. 检查缓存文件是否存在
cacheDir := "storage/component-reports"
zipPath := filepath.Join(cacheDir, cacheKey+".zip")
if _, err := os.Stat(zipPath); err == nil {
// 文件已存在，计算哈希值
hash, err := calculateFileHash(zipPath)
if err == nil {
return zipPath, hash, nil
}
}
// 2. 创建ZIP文件
zipFile, err := os.Create(zipPath)
if err != nil {
return "", "", err
}
defer zipFile.Close()
zipWriter := zip.NewWriter(zipFile)
defer zipWriter.Close()
// 3. 遍历子产品，添加UI组件文件到ZIP
basePath := "resources/Pure Component/src/ui"
for _, productCode := range subProductCodes {
path, fileType, err := s.MatchProductCodeToPath(ctx, productCode)
if err != nil {
continue // 跳过未找到的文件
}
if fileType == "folder" {
// 递归添加文件夹
err = addFolderToZip(zipWriter, path, basePath)
} else {
// 添加单个文件
err = addFileToZip(zipWriter, path, basePath)
}
if err != nil {
s.logger.Warn("添加文件到ZIP失败", zap.String("path", path), zap.Error(err))
}
}
// 4. 生成并添加 example.json 文件
exampleJSON, err := s.GenerateExampleJSON(ctx, productID, subProductCodes)
if err != nil {
s.logger.Warn("生成example.json失败", zap.Error(err))
// 不阻断流程，继续生成ZIP
} else {
// 添加 example.json 到 ZIP 的 public 目录
exampleWriter, err := zipWriter.Create("public/example.json")
if err != nil {
s.logger.Warn("创建example.json文件失败", zap.Error(err))
} else {
_, err = exampleWriter.Write(exampleJSON)
if err != nil {
s.logger.Warn("写入example.json失败", zap.Error(err))
}
}
}
// 5. 添加其他必要的文件（如果需要）
// 例如：复制 public 目录下的其他文件（如果有）
publicBasePath := "resources/Pure Component/public"
publicFiles, err := os.ReadDir(publicBasePath)
if err == nil {
for _, file := range publicFiles {
// 跳过 example.json（已经生成）
if file.Name() == "example.json" {
continue
}
filePath := filepath.Join(publicBasePath, file.Name())
if !file.IsDir() {
err = addFileToZip(zipWriter, filePath, publicBasePath)
if err != nil {
s.logger.Warn("添加public文件失败", zap.String("file", file.Name()), zap.Error(err))
}
}
}
}
// 6. 计算文件哈希值
hash, err := calculateFileHash(zipPath)
if err != nil {
return "", "", err
}
return zipPath, hash, nil
}
```
## 七、支付流程集成
### 7.1 支付订单创建
在创建报告支付订单时，需要：
1. 创建充值记录（RechargeRecord），类型为 `component_report`
2. 创建支付订单（微信/支付宝）
3. 创建下载记录（ComponentReportDownload），状态为 `pending`
### 7.2 支付成功回调
支付成功后：
1. 更新充值记录状态
2. 更新下载记录状态为 `success`
3. 生成ZIP文件（包括UI组件文件和 `public/example.json`）
4. 更新下载记录的 `file_path` 和 `file_hash`
5. 设置 `expires_at`（30天后）
### 7.3 二次下载
用户已支付过的报告：
1. 检查下载记录是否存在且未过期
2. 如果ZIP文件存在，直接返回
3. 如果ZIP文件不存在，重新生成（使用相同的cache_key）
## 八、性能优化策略
### 8.1 缓存策略
1. **文件匹配缓存**：产品编号到文件路径的映射缓存到数据库
2. **ZIP文件缓存**：生成的ZIP文件保存到 `storage/component-reports` 目录
3. **缓存键生成**：基于产品ID和子产品编号列表生成唯一缓存键
### 8.2 异步处理
对于大文件或包含多个子产品的组合包：
1. 支付成功后，异步生成ZIP文件
2. 生成完成后通知用户（可选：邮件/站内消息）
3. 用户下载时检查文件是否已生成完成
### 8.3 文件清理
定期清理过期的ZIP文件：
1. 下载记录过期后（expires_at + 7天）删除ZIP文件
2. 使用定时任务（cron）定期执行清理
## 九、错误处理
### 9.1 文件未找到
- 如果某个子产品的报告文件未找到，记录警告日志，但不影响其他文件的打包
- 在响应中返回未找到的文件列表
### 9.4 example.json 生成失败
- 如果某个子产品没有响应示例数据，使用空对象 `{}` 作为默认值
- 如果响应示例解析失败，尝试从Markdown代码块中提取JSON
- 如果所有子产品都没有响应示例，生成包含空数据的 `example.json` 文件
- 记录警告日志，但不阻断ZIP文件生成流程
### 9.2 支付失败
- 支付失败时，下载记录状态保持为 `pending`
- 用户可以重新发起支付
### 9.3 文件生成失败
- 记录错误日志
- 通知管理员
- 用户可以联系客服处理
## 十、测试要点
1. **匹配算法测试**：
- 精确匹配
- 模糊匹配（前缀、后缀）
- 未找到文件的情况
2. **价格计算测试**：
- 单品价格计算
- 组合包价格计算
- 已下载产品价格减免
3. **example.json 生成测试**：
- 单品 example.json 生成
- 组合包 example.json 生成（多个子产品）
- 响应示例数据提取（JSON格式、Markdown代码块格式）
- 缺少响应示例时的默认值处理
4. **支付流程测试**：
- 创建支付订单
- 支付成功回调
- 支付失败处理
5. **下载功能测试**：
- 首次下载
- 二次下载
- 文件过期处理
6. **性能测试**：
- 大文件生成时间
- 并发下载处理
- 缓存命中率
## 十一、部署注意事项
1. **目录权限**：确保 `storage/component-reports` 目录有写权限
2. **存储空间**：ZIP文件可能较大，需要足够的磁盘空间
3. **备份策略**：定期备份下载记录和缓存表
4. **监控告警**：监控文件生成失败、支付回调异常等情况
## 十二、后续优化方向
1. **CDN加速**：将ZIP文件上传到CDN，加速下载
2. **分片下载**：对于超大文件，支持分片下载
3. **预览功能**：在下载前提供报告预览
4. **版本管理**：支持报告版本更新，用户可选择下载历史版本
5. **批量下载**：支持用户选择多个产品批量下载
Reference in New Issue Copy Permalink