MarketingSystemDataExportTool/docs/requirements_and_tests.md

MarketingSystemDataTool 需求文档与测试点

背景与目标

• 为营销系统与易码通系统提供统一、可配置的数据导出能力（CSV/XLSX），以模板化方式生成安全、可控的查询与导出文件。
• 支持模板管理、EXPLAIN 评估、分批与时间分片执行、进度追踪与文件下载，满足运营与数据分析的批量导出场景。

范围

• 后端：Go 单服务，HTTP API，连接两套 MySQL（营销、易码通），不含消息队列与缓存。
• 前端：Vue 3 + Element Plus（CDN），单页工具页面，模板维护与导出发起、任务查看与下载。
• 存储：本地 storage/export/ 目录生成分片文件与最终 zip；导出记录与模板元数据存库。

系统架构

• 路由注册：server/internal/api/router.go:11、server/internal/api/router.go:13、server/internal/api/router.go:15、server/internal/api/router.go:16-27；静态文件：server/internal/api/router.go:40。
• 启动入口：server/cmd/server/main.go:15-46，加载配置、初始化日志、连接 MySQL、启动 HTTP Server。
• 配置加载：server/internal/config/config.go:31-69（YAML + 环境变量），DSN 组合：server/internal/config/config.go:94-99。
• 响应封装与中间件：server/internal/api/response.go:18-36、server/internal/api/middleware.go:18-31（TraceID/CORS/访问日志）。
• SQL 构建与评估：server/internal/exporter/sqlbuilder.go、server/internal/exporter/explain.go、server/internal/exporter/evaluate.go、server/internal/exporter/writer.go。
• Schema 映射与白名单：server/internal/schema/*.go；字段标签：server/internal/api/templates.go:315-317。
• 前端页面与逻辑：web/index.html、web/main.js。

功能需求

模板管理

• 新增模板：POST /api/templates，字段包含名称、数据源、场景主表、字段集合、默认筛选、输出格式、可见性、归属人。
• 列表与详情：GET /api/templates、GET /api/templates/{id}，支持 userId 过滤公共/个人模板；展示字段数、执行次数、最近校验。
• 编辑模板：PATCH /api/templates/{id}，支持名称、数据源、主表、字段、筛选、格式、可见性、启用状态变更。
• 删除模板：DELETE /api/templates/{id}，若存在任务引用禁止删除。
• 模板校验：POST /api/templates/{id}/validate，生成 SQL、执行 EXPLAIN、评分与索引建议写回模板。

导出执行

• 发起导出：POST /api/exports，加载模板→构建 SQL→EXPLAIN 评分（阈值 60）→估算行数→入库任务→异步执行。
• 进度与列表：GET /api/exports 分页返回任务，含评估摘要与行数；GET /api/exports/{id} 返回详细信息与文件列表。
• SQL 查看：GET /api/exports/{id}/sql 返回参数化 SQL 与最终展开 SQL。
• 取消与下载：POST /api/exports/{id}/cancel、GET /api/exports/{id}/download 下载最新 zip。

元数据与辅助

• 字段元数据：GET /api/metadata/fields?datasource&order_type，返回表与字段、推荐字段集合。
• 选择项：营销侧 GET /api/creators、GET /api/resellers?creator、GET /api/plans?reseller；易码通 GET /api/ymt/users、GET /api/ymt/merchants?user_id、GET /api/ymt/activities?merchant_id。
• Key 解析工具：GET /api/utils/decode_key?v=...。

权限与安全

• 强制权限条件：营销库必须提供 creator_in 与 create_time_between；易码通通过 creator_in（映射为 user_id）。
• 字段白名单：禁用 SELECT * 与非白名单字段；模板字段、过滤项统一白名单校验。
• 参数化查询：所有筛选采用预编译参数；禁止字符串拼接。
• 敏感字段处理：order.key 在易码通解密（SM4，YMT_KEY_DECRYPT_KEY_B64），营销系统做逆编码；下载统一 zip。

文件生成与存储

• 输出格式：csv 与 xlsx；首行写列名；统一 UTF-8。
• 分批与分片：每批查询 1000 行；单文件上限 300000 行自动切片；支持按时间范围（10 天步长）拆分执行。
• 记录文件：每个分片与最终 zip 写入 export_job_files，保留行数与大小。

前端交互

• 模板管理与执行：web/index.html、web/main.js；通过 userId 透传归属过滤；Cascader 选择场景字段；对话框尺寸可调整。
• 执行表单：必填时间范围；营销侧创建者/分销商/计划级联；易码通用户/客户/活动级联；订单类型附加筛选。
• 任务列表：每秒轮询；展示评估状态、行数、进度百分比、下载与 SQL 分析。

非功能需求

• 性能：EXPLAIN 评分达标（≥60）；避免 ALL、Using temporary/filesort；优先覆盖权限与时间索引。
• 稳定性：分批拉取与时间分片；进度每 50 行刷新；失败/取消状态管理；磁盘 I/O 控制。
• 安全：仅白名单字段；敏感信息通过环境变量注入；日志不打印明文密码与完整 DSN。
• 监控与日志：统一结构化访问日志、错误日志携带 TraceID 与 SQL；任务与模板操作记录。

接口规范（摘要）

• POST /api/templates
  • 请求：{ name, datasource, main_table, fields: string[], filters: object, file_format, visibility, owner_id }
  • 响应：201 ok
• GET /api/templates[?userId] → 列表；GET /api/templates/{id} → 详情
• PATCH /api/templates/{id} → 部分更新
• DELETE /api/templates/{id} → 模板未被引用时允许删除
• POST /api/templates/{id}/validate → { score, suggestions[] }
• POST /api/exports
  • 请求：{ template_id, requested_by, permission, options, file_format, filters, datasource }
  • 响应：{ id }（任务 ID）
• GET /api/exports[?template_id&page&page_size&userId] → { items, total, page, page_size }
• GET /api/exports/{id} → 任务详情与文件列表
• GET /api/exports/{id}/sql → { sql, final_sql }
• POST /api/exports/{id}/cancel、GET /api/exports/{id}/download
• GET /api/metadata/fields?datasource&order_type → { tables[], recommended[] }

配置与环境

• YAML：server/config.yaml（或根 config.yaml），示例端口 8077；两套 DB 连接参数与易码通密钥。
• 环境变量覆盖：MARKETING_DB_*、YMT_DB_*、YMT_KEY_DECRYPT_KEY_B64；支持 .env.local 注入。
• DSN 模板：<user>:<password>@tcp(<host>:<port>)/<dbname>?parseTime=True&loc=Local&charset=utf8mb4。

数据与字段（摘要）

• 主表：营销 order；易码通主表映射 order_info。
• 常用过滤：creator_in、create_time_between、type_eq、out_trade_no_eq、plan_id_eq、reseller_id_eq 等。
• 关联表：营销（order_detail、order_cash、order_voucher、plan、key_batch、code_batch、voucher、voucher_batch、merchant_key_send）；易码通（order_cash、order_voucher、order_digit、goods_voucher_batch、goods_voucher_subject_config、merchant、activity）。

关键流程（文字版）

1. 前端创建模板或选择已有模板，选择数据源、场景与字段，设置默认订单类型。
2. 发起导出：前端提交必填的时间范围与权限范围（创建者等），后端生成 SQL → EXPLAIN → 阈值校验。
3. 任务入库与异步执行：分批分页查询，每 1000 行拉取，单文件 300k 行分片，时间范围大时按 10 天拆分。
4. 行写入：写 CSV/XLSX；特定字段转换（order.key 解密/逆编码）；定期更新进度。
5. 完成：汇总分片为 zip，写文件记录，任务置为 completed，提供下载与 SQL 分析。

边界与限制

• 仅支持订单主表（营销 order，易码通 order_info），不支持自由主表选择。
• 必须包含权限与时间过滤；否则构建器报错或评估不通过。
• 单文件分片上限 300k 行；极大数据量建议按时间拆分或筛选范围收窄。

测试点

单元测试

• SQL 构建器（server/internal/exporter/sqlbuilder.go）
  • 字段白名单与非法字段拒绝。
  • 主表校验：仅 order / order_info。
  • 过滤解析：creator_in（多类型数组）、create_time_between（长度=2）、其他等值过滤。
  • 易码通字段映射与特殊枚举列（type/status/pay_status CASE 逻辑）。
  • JOIN 选择与避免笛卡尔积（不同过滤与字段组合）。
• EXPLAIN 评估（server/internal/exporter/explain.go、evaluate.go）
  • 出现 ALL/高 rows/Using temporary/filesort 的扣分逻辑与建议生成。
  • 评分阈值判定与错误分支（禁止执行）。
• 写入器（server/internal/exporter/writer.go）
  • CSV/XLSX 写列名与行；Close 返回路径与大小；异常路径处理。
• 行转换（server/internal/api/exports.go:868-887）
  • order.key 解密/逆编码：易码通 SM4（密钥为空与有效）、营销逆编码后长度与字符集校验。
• 时间分片（server/internal/api/exports.go:731-751）
  • 输入合法性与步长切分边界；起止相等、跨天与不足步长。

集成测试

• 模板生命周期：创建→校验→编辑→列表/详情→删除（被引用场景拒绝）。
• 导出端到端：发起（营销与易码通各 1 套）→下载→SQL 分析；大窗口下分片与 zip 生成验证。
• 列表分页与过滤：/api/exports page/page_size/template_id/userId 组合下返回一致性。
• 前端交互：字段级联选择、对话框动态尺寸、userId 透传与权限限制（编辑/删除按钮显隐）。

性能测试

• EXPLAIN 评分边界：构造不同索引覆盖与过滤条件，验证评分变化与建议内容。
• 大数据量导出：行数 10 万/30 万/100 万分批写入，评估速度、文件大小与 zip 打包时间；进度刷新频率与准确性。

安全测试

• 非白名单字段与非法主表拒绝；SQL 注入尝试（字符串拼接禁止）。
• 敏感信息：order.key 转换正确且日志不泄漏；配置与环境变量加载不写入日志明文密码。
• 下载鉴权：仅通过最新文件下载 API，404 场景与异常路径。

前端测试

• 表单校验：模板创建必填项、导出必填时间范围与权限范围。
• 选择项联动：创建者→分销商→计划（营销）；用户→客户→活动（易码通）。
• 任务轮询：进度计算、完成后下载按钮显隐；SQL 查看正确展示最终 SQL。

验收标准

• 模板创建、校验、编辑、删除流程完整可用；字段白名单生效。
• 导出任务在营销与易码通数据源下均可成功执行，EXPLAIN 评分≥60，能生成 zip 文件并下载。
• 在大窗口与分片场景下保持稳定，进度与行数统计准确；日志与响应携带 TraceID。
• 前端交互顺畅，必填项校验与权限控制符合预期；SQL 分析与下载功能可用。