zhouyonggao
/
MarketingSystemDataExportTool
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
MarketingSystemDataExportTool/docs/需求文档.md

20 KiB
Raw Blame History

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

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

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 接口响应格式

成功响应：

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

失败响应：

{
  "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/ 目录：

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