# 营销系统数据导出工具需求文档

## 1. 项目概述

### 1.1 项目背景

营销系统数据导出工具（MarketingSystemDataExportTool）是一个面向营销系统和易码通系统的订单数据导出平台。该工具旨在为业务人员提供灵活、高效的数据导出能力，支持自定义导出模板、多种过滤条件和多种输出格式。

### 1.2 系统目标

- 提供统一的数据导出入口，支持营销系统和易码通两个数据源
- 支持用户自定义导出模板，灵活配置导出字段
- 提供丰富的过滤条件，满足多样化的数据查询需求
- 支持大数据量导出，具备分片处理和进度跟踪能力
- 提供友好的 Web 界面，降低使用门槛

### 1.3 技术栈

| 层级 | 技术选型 |
|------|----------|
| 后端 | Go 1.21 |
| 前端 | Vue 3 + Element Plus (CDN 引入) |
| 数据库 | MySQL |
| 导出格式 | CSV、Excel (XLSX) |

---

## 2. 系统架构

### 2.1 整体架构

```
┌─────────────────────────────────────────────────────────────┐
│                        Web 前端                              │
│                    (Vue 3 + Element Plus)                    │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                       Go HTTP 服务                           │
│                      (端口: 8077)                            │
└─────────────────────────────────────────────────────────────┘
                              │
          ┌───────────────────┼───────────────────┐
          ▼                   ▼                   ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│   元数据库      │ │  营销系统数据库  │ │  易码通数据库   │
│ (模板/任务存储) │ │   (Marketing)    │ │     (YMT)       │
└─────────────────┘ └─────────────────┘ └─────────────────┘
```

### 2.2 数据库连接

系统连接三个 MySQL 数据库：

1. **元数据库 (Meta DB)**：存储导出模板和导出任务信息
2. **营销系统数据库 (Marketing DB)**：营销系统业务数据
3. **易码通数据库 (YMT DB)**：易码通业务数据

---

## 3. 功能模块

### 3.1 导出模板管理

#### 3.1.1 功能描述

导出模板用于定义数据导出的配置，包括数据源选择、导出字段、过滤条件等。

#### 3.1.2 模板属性

| 字段 | 类型 | 说明 |
|------|------|------|
| id | uint64 | 模板唯一标识 |
| name | string | 模板名称 |
| datasource | string | 数据源：`marketing` / `ymt` |
| main_table | string | 主表：`order` / `order_info` |
| fields_json | JSON | 导出字段列表 |
| filters_json | JSON | 过滤条件 |
| file_format | string | 输出格式：`csv` / `xlsx` |
| visibility | string | 可见性：`private` / `public` |
| owner_id | uint64 | 所有者 ID |
| enabled | bool | 是否启用 |
| explain_json | JSON | SQL 执行计划 |
| explain_score | int | 执行计划评分 |

#### 3.1.3 接口列表

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/templates` | 创建模板 |
| GET | `/api/templates` | 获取模板列表 |
| GET | `/api/templates/{id}` | 获取模板详情 |
| PATCH | `/api/templates/{id}` | 更新模板 |
| DELETE | `/api/templates/{id}` | 删除模板 |
| POST | `/api/templates/{id}/validate` | 验证模板（执行 EXPLAIN） |

#### 3.1.4 业务规则

1. 模板名称必填
2. 必须选择至少一个导出字段
3. 删除模板时，若有关联的导出任务则执行软删除（标记 enabled=0）
4. 模板验证时执行 EXPLAIN 分析，评分低于 60 分禁止导出

---

### 3.2 数据导出任务

#### 3.2.1 功能描述

导出任务基于模板执行实际的数据导出操作，支持异步执行、进度跟踪和文件下载。

#### 3.2.2 任务属性

| 字段 | 类型 | 说明 |
|------|------|------|
| id | uint64 | 任务唯一标识 |
| template_id | uint64 | 关联模板 ID |
| status | string | 状态：`queued`/`running`/`completed`/`failed`/`canceled` |
| requested_by | uint64 | 请求者 ID |
| permission_scope_json | JSON | 权限范围 |
| options_json | JSON | 任务选项 |
| row_estimate | int64 | 预估行数 |
| total_rows | int64 | 实际行数 |
| file_format | string | 文件格式 |
| started_at | datetime | 开始时间 |
| finished_at | datetime | 完成时间 |

#### 3.2.3 接口列表

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/exports` | 创建导出任务 |
| GET | `/api/exports` | 获取任务列表（分页） |
| GET | `/api/exports/{id}` | 获取任务详情 |
| GET | `/api/exports/{id}/sql` | 获取任务 SQL |
| GET | `/api/exports/{id}/download` | 下载导出文件 |
| POST | `/api/exports/{id}/cancel` | 取消任务 |
| POST | `/api/exports/{id}/recompute` | 重新计算行数 |

#### 3.2.4 导出流程

```
1. 创建导出任务
      │
      ▼
2. 解析模板配置
      │
      ▼
3. 合并过滤条件
      │
      ▼
4. 构建 SQL 查询
      │
      ▼
5. 执行 EXPLAIN 分析
      │
      ├── 评分 < 60 → 拒绝执行
      │
      ▼
6. 估算数据行数
      │
      ▼
7. 创建任务记录
      │
      ▼
8. 异步执行导出
      │
      ├── CSV 格式：分片写入，每文件最多 30 万行
      │
      ├── XLSX 格式：流式写入，每文件最多 30 万行
      │
      ▼
9. 生成 ZIP 压缩包（多文件时）
      │
      ▼
10. 更新任务状态为完成
```

#### 3.2.5 业务规则

1. **时间过滤必填**：营销系统订单导出必须提供 `create_time_between` 过滤条件
2. **EXPLAIN 评分阈值**：评分低于 60 分的查询禁止执行
3. **文件分片**：单文件最大行数为 30 万行，超过自动分片
4. **进度更新**：CSV 每 1000 行更新一次进度，XLSX 每 200 行更新一次
5. **分块导出**：大数据量导出按 10 天为周期分块查询

---

### 3.3 数据源与字段

#### 3.3.1 支持的数据源

| 数据源 | 标识 | 说明 |
|--------|------|------|
| 营销系统 | `marketing` | 营销系统订单数据 |
| 易码通 | `ymt` | 易码通订单数据 |

#### 3.3.2 订单类型

**营销系统订单类型：**

| 类型值 | 说明 |
|--------|------|
| 1 | 直充卡密 |
| 2 | 立减金 |
| 3 | 红包 |

**易码通订单类型：**

| 类型值 | 说明 |
|--------|------|
| 1 | 红包订单 |
| 2 | 直充卡密订单 |
| 3 | 立减金订单 |

#### 3.3.3 可导出表

**营销系统可导出表：**

| 表名 | 中文名 | 说明 |
|------|--------|------|
| order | 订单主表 | 核心订单数据 |
| order_detail | 订单详情 | 订单扩展信息 |
| order_cash | 红包订单 | 红包类型订单明细 |
| order_voucher | 立减金订单 | 立减金类型订单明细 |
| plan | 活动计划 | 营销活动计划 |
| key_batch | KEY 批次 | KEY 码批次信息 |
| code_batch | 兑换码批次 | 兑换码批次信息 |
| voucher | 立减金 | 立减金信息 |
| voucher_batch | 立减金批次 | 立减金批次信息 |
| merchant_key_send | 开放平台发放记录 | 开放平台 KEY 发放记录 |

**易码通可导出表：**

| 表名 | 中文名 | 说明 |
|------|--------|------|
| order_info | 订单主表 | 核心订单数据 |
| order_cash | 红包订单 | 红包类型订单明细 |
| order_voucher | 立减金订单 | 立减金类型订单明细 |
| order_digit | 直充卡密订单 | 直充卡密订单明细 |
| merchant | 客户 | 客户信息 |
| activity | 活动 | 活动信息 |
| goods_voucher_batch | 立减金批次表 | 立减金批次配置 |
| goods_voucher_subject_config | 立减金主体配置 | 立减金主体配置 |

---

### 3.4 过滤条件

#### 3.4.1 通用过滤条件

| 过滤键 | 说明 | 适用数据源 |
|--------|------|------------|
| creator_in | 创建者 ID 列表 | 全部 |
| create_time_between | 创建时间范围（必填） | 全部 |
| type_eq | 订单类型 | 全部 |
| out_trade_no_eq | 支付流水号 | 全部 |
| account_eq | 账号 | 全部 |
| plan_id_eq | 计划/活动 ID | 全部 |
| product_id_eq | 商品 ID | 全部 |
| reseller_id_eq | 分销商/客户 ID | 全部 |

#### 3.4.2 营销系统特有过滤

| 过滤键 | 说明 |
|--------|------|
| key_batch_id_eq | KEY 批次 ID |
| code_batch_id_eq | 兑换码批次 ID |
| order_cash_cash_activity_id_eq | 红包批次 ID |
| order_voucher_channel_activity_id_eq | 立减金渠道批次 ID |
| voucher_batch_channel_activity_id_eq | 立减金批次渠道批次 ID |
| merchant_out_biz_no_eq | 商户业务号 |

#### 3.4.3 易码通特有过滤

| 过滤键 | 说明 |
|--------|------|
| merchant_id_in | 客户 ID 列表 |
| order_voucher_channel_activity_id_eq | 立减金渠道批次号 |

---

### 3.5 字段处理与转换

#### 3.5.1 枚举值转换

系统自动将数据库中的枚举值转换为中文标签：

**订单状态（营销系统）：**

| 值 | 标签 |
|----|------|
| 0 | 待充值 |
| 1 | 充值中 |
| 2 | 已完成 |
| 3 | 充值失败 |
| 4 | 已取消 |
| 5 | 已过期 |
| 6 | 待支付 |

**订单状态（易码通）：**

| 值 | 标签 |
|----|------|
| 1 | 待充值 |
| 2 | 充值中 |
| 3 | 充值成功 |
| 4 | 充值失败 |
| 5 | 已过期 |
| 6 | 已作废 |
| 7 | 已核销 |
| 8 | 核销失败 |
| 9 | 订单重置 |
| 10 | 卡单 |

**支付状态（营销系统）：**

| 值 | 标签 |
|----|------|
| 1 | 待支付 |
| 2 | 已支付 |
| 3 | 已退款 |

**支付状态（易码通）：**

| 值 | 标签 |
|----|------|
| 1 | 待支付 |
| 2 | 支付中 |
| 3 | 已支付 |
| 4 | 取消支付 |
| 5 | 退款中 |
| 6 | 退款成功 |

#### 3.5.2 特殊字段处理

1. **KEY 解密**
   - 易码通：使用 SM4 算法解密
   - 营销系统：使用 Base58 解码

2. **卡密脱敏**
   - 营销系统卡密字段自动脱敏：前 6 位 + `****` + 后 4 位

3. **支付渠道解析**
   - 活动渠道字段（JSON 数组）自动解析为渠道名称列表

---

### 3.6 辅助查询接口

#### 3.6.1 营销系统辅助接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/creators` | 获取创建者列表 |
| GET | `/api/resellers` | 获取分销商列表 |
| GET | `/api/plans` | 获取活动计划列表 |
| GET | `/api/fields` | 获取可用字段列表 |
| GET | `/api/metadata/fields` | 获取字段元数据（含中文标签） |

#### 3.6.2 易码通辅助接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/ymt/users` | 获取用户列表 |
| GET | `/api/ymt/merchants` | 获取客户列表 |
| GET | `/api/ymt/activities` | 获取活动列表 |

#### 3.6.3 工具接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/utils/decode_key` | 解密 KEY 码 |

---

## 4. 前端功能

### 4.1 模板管理页面

#### 4.1.1 功能列表

- 模板列表展示（支持分页）
- 创建新模板
- 编辑已有模板
- 删除模板
- 查看模板执行历史

#### 4.1.2 模板创建/编辑

**表单字段：**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| 模板名称 | 文本 | 是 | 模板显示名称 |
| 数据源 | 下拉 | 是 | 营销系统/易码通 |
| 订单类型 | 下拉 | 是 | 直充卡密/立减金/红包 |
| 导出字段 | 树形选择 | 是 | 支持多级表关联选择 |
| 输出格式 | 下拉 | 是 | XLSX/CSV |
| 可见性 | 下拉 | 是 | 个人/公共 |

### 4.2 导出执行页面

#### 4.2.1 功能列表

- 选择模板执行导出
- 配置过滤条件
- 查看导出任务列表
- 实时进度跟踪
- 下载导出文件
- 查看执行 SQL

#### 4.2.2 过滤条件表单

**通用过滤：**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| 时间范围 | 日期范围 | 是 | 创建时间过滤 |

**营销系统过滤：**

| 字段 | 类型 | 说明 |
|------|------|------|
| 创建者 | 多选 | 可选多个创建者 |
| 分销商 | 下拉 | 依赖创建者选择 |
| 活动计划 | 下拉 | 依赖分销商选择 |
| 立减金批次 | 文本 | 立减金订单可用 |

**易码通过滤：**

| 字段 | 类型 | 说明 |
|------|------|------|
| 创建者 | 下拉 | 单选 |
| 客户 | 下拉 | 依赖创建者选择 |
| 活动 | 下拉 | 依赖客户选择 |

### 4.3 任务状态展示

| 状态 | 显示 | 说明 |
|------|------|------|
| queued | 排队中 | 任务等待执行 |
| running | 进行中（显示百分比） | 正在导出数据 |
| completed | 已完成 | 可下载文件 |
| failed | 失败 | 导出失败 |
| canceled | 已取消 | 用户取消 |

---

## 5. 安全与权限

### 5.1 数据权限

1. **用户隔离**：通过 URL 参数 `userId` 标识当前用户
2. **模板权限**：
   - 私有模板：仅创建者可见
   - 公共模板：所有用户可见
3. **数据过滤**：导出时自动注入 `creator_in` 过滤条件

### 5.2 接口安全

1. **访问控制中间件**：支持配置 IP 白名单和请求头验证
2. **请求追踪**：每个请求生成唯一 `trace_id` 便于问题排查

### 5.3 数据脱敏

1. 卡密字段自动脱敏处理
2. KEY 码加密存储，导出时解密

---

## 6. 性能优化

### 6.1 SQL 优化

1. **EXPLAIN 预检**：执行前分析 SQL 执行计划
2. **评分机制**：基于执行计划评估查询效率
3. **索引建议**：提供优化建议

### 6.2 导出优化

1. **分块查询**：大时间范围按 10 天分块
2. **流式写入**：避免内存溢出
3. **游标分页**：基于主键游标分批读取
4. **自适应批次**：根据数据量动态调整批次大小

| 估算行数 | 批次大小 (CSV) |
|----------|----------------|
| < 50,000 | 10,000 |
| < 200,000 | 20,000 |
| < 500,000 | 50,000 |
| ≥ 2,000,000 | 100,000 |

### 6.3 文件存储

1. **本地存储**：文件保存在 `storage/` 目录
2. **自动压缩**：多文件自动打包为 ZIP
3. **文件命名**：`export_job_{id}_{timestamp}.{ext}`

---

## 7. 部署配置

### 7.1 配置文件

配置文件路径：`server/config.yaml`

```yaml
app:
  port: "8077"
  marketing_db:
    host: "localhost"
    port: "3306"
    user: "root"
    password: ""
    name: "marketing"
  ymt_db:
    host: "localhost"
    port: "3306"
    user: "root"
    password: ""
    name: "ymt"
  ymt_test_db:
    host: "localhost"
    port: "3306"
    user: "root"
    password: ""
    name: "meta"
```

### 7.2 环境变量

支持通过环境变量覆盖配置：

| 变量名 | 说明 |
|--------|------|
| MARKETING_DB_HOST | 营销系统数据库主机 |
| MARKETING_DB_PORT | 营销系统数据库端口 |
| MARKETING_DB_USER | 营销系统数据库用户 |
| MARKETING_DB_PASSWORD | 营销系统数据库密码 |
| MARKETING_DB_NAME | 营销系统数据库名 |
| YMT_DB_HOST | 易码通数据库主机 |
| YMT_DB_PORT | 易码通数据库端口 |
| YMT_DB_USER | 易码通数据库用户 |
| YMT_DB_PASSWORD | 易码通数据库密码 |
| YMT_DB_NAME | 易码通数据库名 |
| YMT_TEST_DB_HOST | 元数据库主机 |
| YMT_TEST_DB_PORT | 元数据库端口 |
| YMT_TEST_DB_USER | 元数据库用户 |
| YMT_TEST_DB_PASSWORD | 元数据库密码 |
| YMT_TEST_DB_NAME | 元数据库名 |
| YMT_KEY_DECRYPT_KEY_B64 | SM4 解密密钥（Base64） |

### 7.3 数据库连接池

支持通过环境变量配置连接池：

| 变量名前缀 | 说明 |
|------------|------|
| YMT_DB_ | 易码通数据库连接池 |
| MARKETING_DB_ | 营销系统数据库连接池 |
| YMT_TEST_DB_ | 元数据库连接池 |

---

## 8. 字段清单

### 8.1 订单主表字段

| 字段标识 | 中文名 |
|----------|--------|
| order.order_number | 订单编号 |
| order.key | KEY |
| order.creator | 创建者ID |
| order.out_trade_no | 支付流水号 |
| order.type | 订单类型 |
| order.status | 订单状态 |
| order.account | 账号 |
| order.product_id | 商品ID |
| order.reseller_id | 分销商ID |
| order.plan_id | 计划ID |
| order.pay_type | 支付方式 |
| order.pay_status | 支付状态 |
| order.contract_price | 合同单价 |
| order.num | 数量 |
| order.total | 总金额 |
| order.pay_amount | 支付金额 |
| order.create_time | 创建时间 |
| order.update_time | 更新时间 |
| order.official_price | 官方价 |
| order.merchant_name | 客户名称 |
| order.activity_name | 活动名称 |
| order.goods_name | 商品名称 |
| order.pay_time | 支付时间 |
| order.card_code | 卡密(脱敏) |
| order.supplier_name | 供应商名称 |
| order.cost_price | 成本价 |
| order.is_inner | 供应商类型 |
| order.recharge_suc_time | 充值成功时间 |

### 8.2 红包订单字段

| 字段标识 | 中文名 |
|----------|--------|
| order_cash.order_no | 订单号 |
| order_cash.trade_no | 交易号 |
| order_cash.channel | 渠道 |
| order_cash.denomination | 红包面额 |
| order_cash.account | 领取账号 |
| order_cash.receive_name | 真实姓名 |
| order_cash.cash_activity_id | 红包批次号 |
| order_cash.receive_status | 领取状态 |
| order_cash.receive_time | 拆红包时间 |
| order_cash.success_time | 成功时间 |
| order_cash.amount | 红包额度 |

### 8.3 立减金订单字段

| 字段标识 | 中文名 |
|----------|--------|
| order_voucher.channel | 渠道 |
| order_voucher.channel_activity_id | 渠道立减金批次 |
| order_voucher.channel_voucher_id | 渠道立减金ID |
| order_voucher.status | 状态 |
| order_voucher.receive_mode | 领取方式 |
| order_voucher.grant_time | 领取时间 |
| order_voucher.usage_time | 核销时间 |
| order_voucher.refund_time | 退款时间 |
| order_voucher.overdue_time | 过期时间 |
| order_voucher.refund_amount | 退款金额 |
| order_voucher.official_price | 官方价 |
| order_voucher.account_no | 账户号 |

### 8.4 直充卡密订单字段（易码通）

| 字段标识 | 中文名 |
|----------|--------|
| order_digit.order_no | 订单号 |
| order_digit.card_no | 卡号 |
| order_digit.account | 充值账号 |
| order_digit.success_time | 到账时间 |
| order_digit.order_type | 商品类型 |
| order_digit.end_time | 卡密有效期 |
| order_digit.code | 验证码 |
| order_digit.sms_channel | 短信渠道 |

### 8.5 客户/分销商字段

| 字段标识 | 中文名 |
|----------|--------|
| merchant.id | 客户ID |
| merchant.name | 客户名称 |
| merchant.merchant_no | 商户编码 |
| merchant.subject | 客户主体 |
| merchant.third_party | 供应商类型 |
| merchant.balance | 客户余额 |
| merchant.contact_name | 联系人名称 |
| merchant.contact_phone | 联系人电话 |

### 8.6 活动字段

| 字段标识 | 中文名 |
|----------|--------|
| activity.id | 活动ID |
| activity.name | 活动名称 |
| activity.activity_no | 活动编号 |
| activity.status | 状态 |
| activity.settlement_type | 结算方式 |
| activity.begin_time | 开始时间 |
| activity.end_time | 结束时间 |
| activity.channels | 支付渠道 |
| activity.amount | 支付金额 |

---

## 9. 附录

### 9.1 接口响应格式

**成功响应：**

```json
{
  "code": 0,
  "message": "ok",
  "data": { ... }
}
```

**失败响应：**

```json
{
  "code": 1,
  "message": "错误信息",
  "category": "错误分类"
}
```

### 9.2 文件存储结构

```
storage/
├── export_job_1_20241217100000.xlsx
├── export_job_2_20241217110000.csv
├── export_job_3_20241217120000.zip
│   ├── export_job_3_part1.xlsx
│   └── export_job_3_part2.xlsx
└── ...
```

### 9.3 日志格式

系统采用 JSON 格式日志，存储在 `log/` 目录：

```json
{
  "level": "INFO",
  "event": "export_sql",
  "datasource": "marketing",
  "main_table": "order",
  "file_format": "xlsx",
  "sql": "SELECT ...",
  "args": [...],
  "timestamp": "2024-12-17T10:00:00Z"
}
```