# 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 分析与下载功能可用。