From ec3f890d7e2c437d51c5cfb088a10d8f9f4dbb99 Mon Sep 17 00:00:00 2001 From: zhouyonggao <1971162852@qq.com> Date: Wed, 17 Dec 2025 09:14:47 +0800 Subject: [PATCH] =?UTF-8?q?chore(docs):=20=E7=A7=BB=E9=99=A4=E8=BF=87?= =?UTF-8?q?=E6=97=B6=E7=9A=84=E9=9C=80=E6=B1=82=E6=96=87=E6=A1=A3=E4=B8=8E?= =?UTF-8?q?=E6=B5=8B=E8=AF=95=E6=8A=A5=E5=91=8A?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 删除字段映射与导出校验规则文档 - 移除MarketingSystemDataTool需求与测试点详细文档 - 清理易码通直充卡密订单导出客户名称去重测试报告 - 减少项目冗余文档，便于维护和更新 --- docs/field_mapping_rules.md | 15 -- docs/requirements_and_tests.md | 144 ------------------- docs/test_report_ymt_direct_charge_dedupe.md | 21 --- docs/需求文档.md | 0 4 files changed, 180 deletions(-) delete mode 100644 docs/field_mapping_rules.md delete mode 100644 docs/requirements_and_tests.md delete mode 100644 docs/test_report_ymt_direct_charge_dedupe.md create mode 100644 docs/需求文档.md diff --git a/docs/field_mapping_rules.md b/docs/field_mapping_rules.md deleted file mode 100644 index 0ee7949..0000000 --- a/docs/field_mapping_rules.md +++ /dev/null @@ -1,15 +0,0 @@ -# 字段映射与导出校验规则 - -- 模板字段按保存顺序导出，严格保持数量与顺序一致。 -- YMT 物理表名 `order_info.*` 在模板保存时可使用，导出阶段统一标准化为逻辑 `order.*`。 -- 营销系统立减金批次别名：`order_voucher.channel_batch_no` 标准化为 `order_voucher.channel_activity_id`。 -- 白名单校验：所有字段必须在白名单中（见 `server/internal/schema/fields.go`），否则导出拒绝并提示具体字段列表。 -- 不做自动去重：如模板包含同名或同义字段，将按模板原样导出。 -- SQL 构建使用列别名 `AS \`table.field\``，表头通过 `FieldLabels()` 映射中文名。 - -## 失败返回 -- 若模板字段不在白名单，HTTP 400：`模板字段不在白名单: <列表>`。 -- 若字段数量不一致，将在日志记录 `field_count_mismatch` 事件供排查。 - -## 测试 -- 单元测试 `server/internal/exporter/sqlbuilder_test.go` 验证别名数量与模板字段数量一致。 diff --git a/docs/requirements_and_tests.md b/docs/requirements_and_tests.md deleted file mode 100644 index 3992ffd..0000000 --- a/docs/requirements_and_tests.md +++ /dev/null @@ -1,144 +0,0 @@ -# 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 模板：`:@tcp(:)/?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 分析与下载功能可用。 - diff --git a/docs/test_report_ymt_direct_charge_dedupe.md b/docs/test_report_ymt_direct_charge_dedupe.md deleted file mode 100644 index f714cd5..0000000 --- a/docs/test_report_ymt_direct_charge_dedupe.md +++ /dev/null @@ -1,21 +0,0 @@ -# 易码通直充卡密订单导出客户名称去重测试报告 - -## 场景与用例 -- 单客户订单导出：选择单一 `merchant_id`，包含多笔订单 -- 批量客户订单导出：选择多个 `merchant_id` -- 相同客户多笔订单：同一 `merchant_id` 在时间窗口内多笔订单 - -## 验证点 -- 导出文件格式：列头正确、编码 `UTF-8`、首行表头 -- 客户名称列：每行仅出现一次且来源为 `merchant.name` -- 其他订单信息：金额、时间、订单编号等字段完整无误 - -## 结果摘要 -- 前端：仅在立减金场景显示“立减金批次号”，直充卡密不显示 -- 后端：YMT 直充卡密过滤 `order_voucher/*` 与去重 `order.merchant_name` -- SQL 构建：包含 `LEFT JOIN merchant`，输出列使用 `merchant.name` - -## 兼容性与影响 -- YMT 立减金与营销立减金不受影响，仍支持“立减金批次号”筛选与列输出 -- 直充卡密模板示例更新为使用 `merchant.name` - diff --git a/docs/需求文档.md b/docs/需求文档.md new file mode 100644 index 0000000..e69de29