zhouyonggao
/
MarketingSystemDataExportTool
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(spec): 编写营销系统数据导出工具需求文档 

- 详细描述项目背景、目标与技术栈
- 设计系统整体架构和数据库连接方式
- 定义导出模板管理模块属性、接口及业务规则
- 规划数据导出任务模块功能、流程及业务规则
- 列举支持的数据源、订单类型、可导出数据表
- 规范通用及特定数据源的过滤条件
- 说明字段处理、枚举转换及特殊字段处理方法
- 制定辅助查询接口及工具接口细节
- 描述前端功能包括模板管理与导出执行页面设计
- 明确任务状态展示与安全权限控制策略
- 提出性能优化方案涵盖SQL优化与导出优化
- 设定文件存储规范及部署配置要求
- 列出详细字段清单覆盖所有业务表字段
- 附录中提供接口响应格式、文件结构及日志格式示例
This commit is contained in:
zhouyonggao 2025-12-17 09:18:44 +08:00
parent ec3f890d7e
commit c0578b1d24
1 changed files with 728 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

728
docs/需求文档.md
View File

@ -0,0 +1,728 @@
# 营销系统数据导出工具需求文档
## 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"
}
```