652 lines
51 KiB
Markdown
652 lines
51 KiB
Markdown
# MarketingSystemDataTool 项目规则
|
||
|
||
## 1. 项目概述
|
||
|
||
- 技术栈：后端使用 `Go`，前端使用 `Vue 3 + Element Plus`（通过 CDN 引入，无打包）；前后端代码同仓管理。
|
||
- 目标：为“营销系统”和“易码通系统”提供统一的高性能数据导出能力，支持模板化 SQL 构建与权限控制，生成 `CSV` 与 `Excel` 文件。
|
||
- 数据源：至少包含两个独立库（`marketing_db`、`ymt_db`），通过环境变量配置连接与凭据。
|
||
|
||
## 2. 目录结构与命名约定
|
||
|
||
- `server/`：Go 服务端代码（API、模板校验、导出执行、权限校验、日志与监控）。
|
||
- `web/`：前端页面与静态资源（模板管理、导出发起、进度查看、历史下载），采用 `Vue 3 + Element Plus` 组件搭建。
|
||
- `config/`：非敏感配置（字段白名单、场景定义、关联关系元数据）。敏感信息使用环境变量注入。
|
||
- `scripts/`：开发与运维脚本（如生成索引建议、批量校验 EXPLAIN）。
|
||
- 命名规范：统一使用下划线或小驼峰，文件名见名知意；避免缩写导致歧义。
|
||
|
||
## 3. 权限与安全
|
||
|
||
- 权限字段：所有导出查询必须包含权限范围条件（如 `user_id`、`tenant_id`、`owner_id`），通过 `IN` 或等值过滤传入。
|
||
- 白名单策略：仅允许查询白名单字段与表；禁止 `SELECT *` 与任意动态 SQL 拼接。
|
||
- 参数化查询：所有条件、排序、分页使用预编译参数；禁止字符串拼接导致注入风险。
|
||
- 敏感信息：数据库凭据、密钥等仅通过环境变量加载；严禁写入仓库与日志。
|
||
- 审计日志：记录模板创建与变更、EXPLAIN 结果、导出执行参数、数据量、耗时、下载行为。
|
||
|
||
## 4. 导出场景定义
|
||
|
||
- 易码通系统：
|
||
- 订单导出：订单类型包含 `直充卡密订单`、`立减金订单`、`红包订单`。
|
||
- 支付记录导出：支付类型包含 `key码支付`、`商品支付`。
|
||
- 营销系统：
|
||
- 订单导出：订单类型包含 `直充卡密订单`、`立减金订单`、`红包订单`。
|
||
- 主表定义：每个场景明确主表与主键、权限字段、必要索引；关联表通过元数据预定义关联键与可选字段。
|
||
|
||
## 5. SQL 模板规范
|
||
|
||
- 模板组成：
|
||
- 选择数据源（库名）。
|
||
- 选择数据类型（主表）。
|
||
- 选择关联数据（关联表、连接类型、连接键）。
|
||
- 字段选择（仅白名单字段，支持别名）。
|
||
- 条件过滤（权限条件必填，业务条件可选）。
|
||
- 排序与分页（必须与索引一致性，避免大偏移）。
|
||
- 输出格式（`csv`/`xlsx`），列统计与多 sheet 选项。
|
||
- 生成规则：
|
||
- 自动生成 `JOIN` 与选择列，强制添加权限过滤。
|
||
- 禁止笛卡尔积；必须给出明确连接条件。
|
||
- 大表查询优先走索引覆盖；必要时使用 `CTE/子查询` 减少回表。
|
||
- 统一走 `EXPLAIN` 评估；达标才允许执行。
|
||
|
||
## 6. EXPLAIN 评估标准
|
||
|
||
- 基本要求：
|
||
- 禁止对大表 `type=ALL` 全表扫描；优先 `ref`/`range`/`const`。
|
||
- `rows` 估算在权限范围内合理可控；避免千万级一次性拉取。
|
||
- 正确使用连接顺序与驱动表；避免 `Using temporary`、`Using filesort` 发生在超大数据集。
|
||
- 必要索引存在（权限字段、连接键、排序键、过滤键）。
|
||
- 超标处理：
|
||
- 自动生成索引建议（基于过滤列与排序列）。
|
||
- 指导模板调整（减少字段、改用预聚合或分批）。
|
||
|
||
## 7. 导出执行与进度
|
||
|
||
- 执行模型：
|
||
- 单次查询尽量覆盖需求，避免多次往返；必要时拆分批次流式写入。
|
||
- 流式导出：服务端边拉取边写文件，控制内存与背压。
|
||
- 批大小动态：根据 `rows` 估算与 I/O 速率自适应。
|
||
- 进度追踪：
|
||
- 记录总行数（估算与实际）、已写行数、当前批次、速率、剩余时间估算。
|
||
- 状态：`queued`/`running`/`failed`/`completed`/`canceled`。
|
||
- 历史下载与导出记录：模板、发起人、是否公共、时间窗口、文件摘要（行数/大小/格式）。
|
||
|
||
## 8. 文件生成与格式
|
||
|
||
- `csv`：
|
||
- 统一 `UTF-8` 与 `\n`；首行写列名；转义逗号与引号。
|
||
- 超大数据优先选择 `csv`，可并发分块写入后合并。
|
||
- `xlsx`：
|
||
- 单 sheet 行数受限（建议 ≤ 100 万）；超限自动分 sheet。
|
||
- 多 sheet 划分：按指定条件（如订单类型、日期分区）生成；需稳定排序避免跨批次混入。
|
||
- 列统计：
|
||
- 支持 `count/sum/avg/min/max`；可生成统计 sheet 或尾部汇总。
|
||
- 统计尽量在同一 SQL 通过窗口/聚合生成，避免二次扫描。
|
||
|
||
## 9. 前后端交互协议
|
||
|
||
- 模板管理 API：
|
||
- `POST /api/templates` 创建模板并运行 `EXPLAIN` 校验。
|
||
- `GET /api/templates` 列表/搜索；`GET /api/templates/{id}` 详情。
|
||
- `POST /api/templates/{id}/validate` 重新校验与给出索引建议。
|
||
- `PATCH /api/templates/{id}` 更新元数据（公共/个人、描述、可见范围）。
|
||
- 导出执行 API：
|
||
- `POST /api/exports` 发起导出（模板 + 权限范围 + 条件 + 格式 + 统计 + 多 sheet）。
|
||
- `GET /api/exports/{id}` 进度与指标；`GET /api/exports/{id}/download` 下载文件。
|
||
- `POST /api/exports/{id}/cancel` 取消任务。
|
||
- 前端约定：
|
||
- 使用 `Vue 3 + Element Plus`，通过 CDN 加载：`vue@3` 与 `element-plus`；页面在 `web/index.html` 中挂载。
|
||
- 统一通过权限范围参数（如 `user_id IN (...)`）传递查询边界；由后端注入到 SQL。
|
||
- 所有下拉/选择项来自白名单与元数据；禁止自由输入列名与表名；表单与日期选择使用 Element Plus 组件。
|
||
|
||
## 10. 性能与稳定性
|
||
|
||
- 索引策略：优先覆盖权限字段、关联键、排序键；定期审计慢查询。
|
||
- 分批与限流：根据 `EXPLAIN` rows 估算选择批大小；对导出并发做全局限流。
|
||
- 超时与重试：数据库查询、文件写入设置超时；幂等与断点续传支持。
|
||
- 资源管理：严格控制连接池、内存占用、磁盘 I/O；避免阻塞主线程。
|
||
|
||
## 11. 测试与质量保障
|
||
|
||
- 单元测试：SQL 构建器、权限注入、EXPLAIN 评估、CSV/XLSX 写入器。
|
||
- 集成测试：常见场景模板端到端导出与校验；超大数据模拟与性能门槛验证。
|
||
- 基准测试：关键路径（查询与写文件）压测，建立性能基线与预算。
|
||
|
||
## 12. 日志、监控与告警
|
||
|
||
- 指标：导出次数、耗时、行数、失败率、平均速率、并发数。
|
||
- 监控：数据库慢查询、队列堆积、磁盘空间、错误分布。
|
||
- 告警：任务失败、耗时超阈值、EXPLAIN 超标、磁盘接近上限。
|
||
|
||
## 13. 版本控制与发布
|
||
|
||
- Git 工作流：特性分支 + 合并请求；语义化提交信息；模板变更需评审。
|
||
- 发布：后端可编译为单二进制；前端静态资源打包；提供启动脚本与环境样例。
|
||
- 变更管理：模板结构变更需迁移脚本与兼容策略；历史记录不丢失。
|
||
|
||
## 14. 角色与可见性
|
||
|
||
- 模板归属：支持公共与个人归属，公共模板需通过评审并标注责任人。
|
||
- 访问控制：按角色/租户限制模板使用与导出权限；下载链接带有效期与签名。
|
||
|
||
## 15. 错误处理与用户体验
|
||
|
||
- 明确错误：权限缺失、EXPLAIN 未达标、索引建议、数据过大提示与替代方案。
|
||
- 进度与估算：持续更新预计完成时间与当前速率；完成后通知。
|
||
- 可恢复：失败任务可重试或继续；中断后支持断点续导出。
|
||
|
||
---
|
||
|
||
以上规则用于指导实现与评审，确保导出功能在安全、性能与可维护性方面达标。后续如有新场景与数据源接入，应当补充白名单与关联元数据，并通过测试与指标验证后上线。
|
||
|
||
## 16. 环境与连接配置
|
||
|
||
- 原则：所有连接信息通过环境变量注入，禁止将密码和密钥写入仓库或日志。
|
||
- 营销系统关系型数据库（示例变量名）：
|
||
- `MARKETING_DB_HOST`
|
||
- `MARKETING_DB_PORT`
|
||
- `MARKETING_DB_USER`
|
||
- `MARKETING_DB_PASSWORD`
|
||
- `MARKETING_DB_NAME`
|
||
- `MARKETING_DB_MAX_OPEN_CONNS`、`MARKETING_DB_MAX_IDLE_CONNS`、`MARKETING_DB_CONN_MAX_LIFETIME`
|
||
- 易码通系统关系型数据库（示例变量名）：
|
||
- `YMT_DB_HOST`
|
||
- `YMT_DB_PORT`
|
||
- `YMT_DB_USER`
|
||
- `YMT_DB_PASSWORD`
|
||
- `YMT_DB_NAME`
|
||
- 易码通系统 MySQL 驱动与 DSN：
|
||
- 驱动：`mysql`（建议使用 `github.com/go-sql-driver/mysql`）。
|
||
- DSN 组合（推荐在运行时通过环境变量组装）：
|
||
- 模板：`<user>:<password>@tcp(<host>:<port>)/<dbname>?parseTime=True&loc=Local&charset=utf8mb4`
|
||
- 对应变量：`YMT_DB_USER`、`YMT_DB_PASSWORD`、`YMT_DB_HOST`、`YMT_DB_PORT`、`YMT_DB_NAME`。
|
||
- 连接选项：
|
||
- `parseTime=True` 解析时间类型为 `time.Time`。
|
||
- `loc=Local` 或设定为具体时区；如跨时区导出，优先统一到 `UTC` 并在前端展示时转换。
|
||
- `charset=utf8mb4` 以避免字符集问题。
|
||
- 生产建议：启用只读账号、限定白名单 IP、必要时开启 TLS，禁止在仓库或日志中存储明文密码与完整 DSN。
|
||
- 营销系统 Redis（缓存/队列等，示例变量名）：
|
||
- `MARKETING_REDIS_HOST`
|
||
- `MARKETING_REDIS_PORT`
|
||
- `MARKETING_REDIS_PASSWORD`
|
||
- 使用规范：
|
||
- 本地与生产环境分别通过系统环境或安全的配置服务注入上述变量。
|
||
- 连接池、超时与重试策略必须可配置：查询/执行超时、读写超时、最大重试次数与退避策略。
|
||
- 优先开启 TLS/SSL（如数据库与 Redis 支持），并使用白名单 IP 与最小权限账号。
|
||
- 在运行与监控面板中仅显示掩码信息（如 `***`），避免泄露。
|
||
|
||
## 17. 易码通数据库与表设计
|
||
|
||
- 存储位置：所有导出相关业务数据统一存储在易码通 MySQL（库：`merketing`），使用 `InnoDB` 与 `utf8mb4`，时间统一为 `UTC`（前端展示时转换）。
|
||
- 表清单与职责：
|
||
- `export_templates`（导出模板主表）：
|
||
- 字段：`id`、`name`、`datasource`（`ymt`/`marketing`）、`main_table`、`joins_json`、`fields_json`、`filters_json`、`file_format`（`csv`/`xlsx`）、`stats_enabled`、`sheet_split_by`、`visibility`（`public`/`private`）、`owner_id`、`enabled`、`explain_json`、`explain_score`、`last_validated_at`、`created_at`、`updated_at`。
|
||
- 索引：`owner_id`、`visibility`、`enabled`、`created_at`。
|
||
- `export_jobs`（导出任务表）：
|
||
- 字段：`id`、`template_id`、`status`（`queued`/`running`/`failed`/`completed`/`canceled`）、`requested_by`、`permission_scope_json`（如 `user_ids`、`tenant_id` 范围）、`options_json`、`row_estimate`、`total_rows`、`file_format`、`started_at`、`finished_at`、`created_at`、`updated_at`。
|
||
- 索引：`template_id`、`status`、`requested_by`、`created_at`。
|
||
- `export_job_files`（导出文件记录）：
|
||
- 字段：`id`、`job_id`、`storage_uri`、`sheet_name`、`row_count`、`size_bytes`、`checksum`、`created_at`。
|
||
- 索引：`job_id`。
|
||
- `export_audits`（审计与变更记录）：
|
||
- 字段：`id`、`actor_id`、`action`、`entity_type`、`entity_id`、`detail_json`、`created_at`。
|
||
- 索引：`entity_type+entity_id`、`actor_id`、`created_at`。
|
||
- 可选：`export_metrics_daily`（按日聚合指标）：`date`、`template_id`、`jobs_count`、`rows_count`、`avg_duration_ms` 等。
|
||
- 约束与规范：
|
||
- 外键：`export_jobs.template_id → export_templates.id`，`export_job_files.job_id → export_jobs.id`；模板被引用时 `ON DELETE RESTRICT`，避免误删。
|
||
- 主键：统一 `BIGINT UNSIGNED` 自增；布尔使用 `TINYINT(1)`；JSON 字段用于结构化模板与权限范围。
|
||
- 命名：`snake_case`；时间字段包含 `created_at`、`updated_at`，应用层维护更新时间。
|
||
- 权限与多租户：
|
||
- 表层面包含 `owner_id` 或 `tenant_id` 以便分区过滤；任务执行范围记录于 `permission_scope_json`（如 `user_ids`、`tenant_id`、`date_range`）。
|
||
- 所有查询必须依赖权限字段建索引并注入过滤条件。
|
||
- 索引策略：
|
||
- 组合索引：`status, created_at`、`owner_id, created_at`、`template_id, created_at`，满足列表与检索高频路径。
|
||
- 针对主表与关联键建立覆盖索引，降低回表与避免 `Using filesort/temporary`。
|
||
- 迁移与版本：
|
||
- 在 `server/migrations` 维护迁移脚本（`up/down`），每次结构变更必须提供兼容策略与数据迁移方案。
|
||
- 变更需通过测试与评审，记录在审计表中并与发布流程绑定。
|
||
- 数据保留与清理：
|
||
- 历史导出文件仅保留元数据与存储 URI，按策略定期清理物理文件；失败/取消任务保留审计但可清理文件记录。
|
||
- 性能与安全：
|
||
- 仅存储模板与任务元数据，不冗余导出结果数据；避免在表中存储敏感凭据；对大查询任务做限流与队列管理。
|
||
|
||
## 18. 营销系统订单主表定义
|
||
|
||
- 主表：`order`（保留字，SQL 中需使用反引号包裹：`` `order` ``）。
|
||
- 主键：`order_number`（`VARCHAR(20)`）。
|
||
- 权限字段：`creator`（`INT UNSIGNED`），用于用户权限过滤与范围查询，前端导出通过 `creator IN (...)` 传入范围参数。
|
||
- 字段要点：
|
||
- `` `key` ``（保留字，需使用反引号）：业务 KEY。
|
||
- `out_trade_no`：支付流水号。
|
||
- `type`：订单类型，建议映射：`1=直充卡密`、`2=立减金`、`3=红包`（如与现网不一致，以现网为准）。
|
||
- `status`：订单状态；`deliver_status`：向上游投递状态。
|
||
- `account`、`product_id`、`reseller_id`、`plan_id`、`key_batch_id`、`code_batch_id`。
|
||
- `contract_price`、`num`、`total`（生成列：`contract_price * num`）、`pay_amount`、`pay_type`、`pay_status`、`use_coupon`。
|
||
- `expire_time`、`recharge_time`、`create_time`、`update_time`。
|
||
- `card_code`：敏感信息字段，默认不允许导出；需更高权限并进行掩码或脱敏处理。
|
||
- 索引：
|
||
- `PRIMARY KEY (order_number)`。
|
||
- `idx_out_trade_no (out_trade_no)`、`idx_key (` `key` `)`、`idx_code_batch_id (code_batch_id)`、`idx_product_id (product_id)`、`idx_reseller_id (reseller_id)`、`idx_create_time_account (account, create_time)`。
|
||
- 复合索引：`idx_create_time_creator (create_time, creator)`、`idx_plan_id_create_time_creator (plan_id, create_time, creator)`。
|
||
- 导出查询规范：
|
||
- 所有营销系统订单导出必须包含 `creator` 范围过滤（例如：`creator IN (?)` 或等值），并优先结合 `create_time` 使用复合索引。
|
||
- 订单类型筛选通过 `type IN (1,2,3)`；支付相关通过 `pay_status`、`out_trade_no`；避免对未建索引列进行大范围过滤。
|
||
- 严禁 `SELECT *`；仅允许白名单列（默认排除 `card_code`）。
|
||
- 时间范围必填，建议按 `create_time` 进行分区或限窗，避免跨超大时间窗口的全量拉取。
|
||
- EXPLAIN 达标建议：
|
||
- 驱动表选择 `order`，过滤条件包含 `creator` 与 `create_time`；`type`、`plan_id`、`reseller_id` 作为附加过滤。
|
||
- 避免 `Using filesort/temporary` 在百万级数据上出现；如需排序，尽量使用已存在的复合索引顺序。
|
||
- 安全与合规：
|
||
- 对 `card_code` 输出采用掩码（如仅展示前 6 后 4）；权限不足禁止选取该列。
|
||
- 对支付流水号与账号字段进行最小必要输出；下载文件带签名与有效期。
|
||
- 命名注意：
|
||
- 表名 `order` 与列名 `` `key` ``为保留字，所有 SQL 需使用反引号包裹以避免语法冲突。
|
||
|
||
## 19. 营销系统订单详情表定义
|
||
|
||
- 表：`order_detail`（与主表 `order` 通过 `order_number` 一一关联）。
|
||
- 主键：`order_number`（`VARCHAR(20)`）。
|
||
- 关联关系：`order_detail.order_number = order.order_number`；查询时以 `order` 为驱动表进行 `INNER JOIN` 或 `LEFT JOIN`。
|
||
- 字段要点：
|
||
- `plan_title`、`reseller_name`、`product_name`：冗余展示字段，来自计划/分销商/商品。
|
||
- `show_url`：商品图片 URL（冗余）。
|
||
- `official_price`、`cost_price`：官方价与成本价；与 `order.contract_price` 有区分。
|
||
- `product`：冗余商品信息（`JSON`）。
|
||
- `refund_account`：退款打款账号（敏感，默认不导出或需掩码）。
|
||
- `create_time`、`update_time`：时间字段，跟随主表时区与展示规范。
|
||
- 索引：
|
||
- `PRIMARY KEY (order_number)`。
|
||
- 建议增加：`idx_update_time (update_time)` 或 `idx_create_time (create_time)` 视查询需要；如按时间窗口筛选详情。
|
||
- 导出查询规范：
|
||
- 所有详情导出需通过与主表 `order` 关联，并在主表上应用权限过滤：`creator IN (...)` 与时间范围。
|
||
- 字段白名单：默认允许 `plan_title/reseller_name/product_name/show_url/official_price/cost_price/create_time/update_time`；`refund_account` 与 `product`（JSON）需更高权限或进行脱敏/选择性字段输出。
|
||
- 避免单独对 `order_detail` 进行大范围扫描；以主表为驱动确保使用主表的复合索引。
|
||
- EXPLAIN 达标建议：
|
||
- 连接以主表为驱动（主表过滤 `creator + create_time`），详情表通过主键或索引快速匹配，避免 `Using temporary` 与大范围 `filesort`。
|
||
- 如需按详情时间排序，确保存在相应时间索引或采用分页与稳定排序键。
|
||
- 安全与合规：
|
||
- 对 `refund_account` 默认隐藏或掩码（如仅展示部分）；`product` JSON 仅输出必要键，避免泄露多余属性。
|
||
- 下载与展示遵循最小必要原则，确保敏感字段在模板白名单中默认关闭。
|
||
|
||
## 20. 营销系统红包订单副表定义
|
||
|
||
- 表：`order_cash`（与主表 `order` 通过 `order_number` 一一关联）。
|
||
- 主键：`order_number`（`VARCHAR(20)`）。
|
||
- 关联关系：`order_cash.order_number = order.order_number`；查询以主表为驱动表进行 `INNER JOIN` 或 `LEFT JOIN`。
|
||
- 字段要点：
|
||
- `channel`：渠道（`1=支付宝`、`2=微信`）。
|
||
- `cash_activity_id`：红包批次号；`cash_packet_id`：红包 ID；`cash_id`：红包模板/规则 ID。
|
||
- `receive_status`：领取状态；`receive_time`：拆红包时间。
|
||
- `channel_order_id`：支付宝转账订单号/微信批次单号；`pay_fund_order_id`：支付宝资金流水；`wechat_detail_id`：微信商家明细单号。
|
||
- `receive_user_id`：领取者唯一标识（微信 `open_id`/支付宝 `alipay_user_id`），属于敏感标识，默认不导出或需脱敏。
|
||
- `amount`：红包额度；`status`：状态（`1正常`、`2过期`）；`expire_time`：过期时间。
|
||
- `receive_name`：领取方真实姓名（PII，默认不导出或掩码）。
|
||
- `update_time`：更新时间（可用于按更新时间筛选）。
|
||
- 索引：
|
||
- `PRIMARY KEY (order_number)` 与 `UNIQUE o_uidx (order_number)`（二者功能重合，建议保留一个唯一约束以避免重复约束）。
|
||
- `r_time_idx (receive_time)`、`r_c_idx (receive_user_id, cash_id)`、`idx_expire_time_status (expire_time, status)`。
|
||
- 导出查询规范：
|
||
- 红包订单导出需与主表 `order` 关联，并在主表上应用权限过滤：`creator IN (...)` 和时间范围。
|
||
- 字段白名单：默认允许 `channel/cash_activity_id/receive_status/receive_time/cash_packet_id/cash_id/amount/status/expire_time/update_time`；`receive_user_id/receive_name/channel_order_id/pay_fund_order_id/wechat_detail_id` 需更高权限或掩码处理。
|
||
- 避免对未索引字段进行大范围过滤；按 `receive_time` 或 `expire_time,status` 进行筛选时使用相应索引。
|
||
- EXPLAIN 达标建议：
|
||
- 以主表为驱动（主表过滤 `creator + create_time`），副表通过主键或索引匹配；避免在大数据集上出现 `Using temporary` 与 `filesort`。
|
||
- 排序尽量使用已存在索引的前缀；对 `receive_time` 排序应结合筛选与分页。
|
||
- 安全与合规：
|
||
- `receive_user_id` 与 `receive_name` 属 PII，模板默认关闭并需权限校验与脱敏（如散列或局部显示）。
|
||
- 渠道订单/资金流水号仅在合规范围内输出，避免泄露与被用作外部关联键。
|
||
|
||
## 21. 营销系统立减金订单表定义
|
||
|
||
- 表：`order_voucher`（与主表 `order` 通过 `order_number` 关联；亦可通过唯一 `trade_no` 与外部交易做关联）。
|
||
- 主键：`id`（自增，`INT`）。唯一键：`trade_no`。
|
||
- 关联关系：`order_voucher.order_number = order.order_number`；查询以主表为驱动表进行 `INNER JOIN` 或 `LEFT JOIN`。
|
||
- 字段要点：
|
||
- 渠道与批次：`channel`（`1=支付宝`、`2=微信`）、`channel_activity_id`（渠道立减金批次）、`channel_voucher_id`（渠道立减金 ID）。
|
||
- 用户标识：`channel_user_id`（渠道用户 ID，PII，默认不导出或需脱敏）。
|
||
- 规则与状态：`rule`（立减金规则，`JSON`）、`status`（`1可用/2已实扣/3已过期/4已退款`）。
|
||
- 时间：`grant_time`（领取）、`usage_time`（核销）、`refund_time`（退款）、`status_modify_time`（状态更新时间）、`overdue_time`（过期）。
|
||
- 价格与账户：`official_price`、`refund_amount`、`receive_mode`（`1渠道授权用户id/2手机号或邮箱`）、`receive_error`、`app_id`、`out_biz_no`、`fail_time`、`notify_url`、`account_no`。
|
||
- 索引：
|
||
- `PRIMARY KEY (id)`、`UNIQUE idx_trade_no (trade_no)`。
|
||
- `idx_order_number (order_number)`、`idx_channel_uid (channel, channel_user_id)`、`idx_channel_user_id (channel_user_id, channel)`、`idx_channel_voucher_id (channel_voucher_id)`、`idx_activity_voucher (channel_activity_id, channel)`、`index_status (status)`、`idx_usage_time (usage_time)`、`idx_out_biz_no (out_biz_no)`。
|
||
- 导出查询规范：
|
||
- 立减金订单导出需与主表 `order` 关联，并在主表上应用权限过滤：`creator IN (...)` 与时间范围；避免对本表进行独立全表扫描。
|
||
- 字段白名单：默认允许 `channel/channel_activity_id/channel_voucher_id/status/grant_time/usage_time/refund_time/status_modify_time/overdue_time/refund_amount/official_price/out_biz_no/account_no`；`channel_user_id/app_id/notify_url/receive_error` 与 `rule`（JSON）需更高权限或脱敏后选择性输出。
|
||
- 规则字段 `rule` 建议由模板定义具体键路径进行选择性导出，避免整段 JSON 输出造成泄露与体积膨胀。
|
||
- EXPLAIN 达标建议：
|
||
- 以主表为驱动（主表过滤 `creator + create_time`），本表通过 `order_number` 或其他索引列匹配；对时间或状态筛选使用对应索引。
|
||
- 如需要按 `usage_time` 或 `status` 排序与筛选，确保选择性足够并配合分页，避免 `Using filesort/temporary` 在大数据集上出现。
|
||
- 安全与合规：
|
||
- `channel_user_id` 属 PII，模板默认关闭并需脱敏（如散列或局部显示）；`account_no` 亦需最小必要输出与掩码。
|
||
- `notify_url/out_biz_no/app_id` 等用于渠道交互的字段不用于外部分发，谨慎输出并记录审计。
|
||
|
||
## 22. 营销系统活动计划表定义
|
||
|
||
- 表：`plan`（营销计划与活动配置）。
|
||
- 主键与唯一：`id`（自增，`INT UNSIGNED`）；唯一键 `stock_id`（计划编号/批次号）。
|
||
- 关联关系：`order.plan_id = plan.id`；订单侧查询通过主表驱动与计划表关联。
|
||
- 权限字段：`creator`（数据所属用户）；可补充按 `reseller_id` 进行租户/渠道范围过滤。
|
||
- 字段要点：
|
||
- 创建者：`creator`、`creator_name`。
|
||
- 基本信息：`title`（计划标题）、`type`（计划类型）、`status`（活动状态，`0草稿` 等）。
|
||
- 分销商：`reseller_id`、`reseller_name`（冗余）。
|
||
- 时间：`begin_time`、`end_time`（活动窗口）、`create_time`、`update_time`、`delete_time`（软删除）。
|
||
- 计划与结算：`return_type`、`open`（1开启/2关闭）、`settlement_type`、`send_method`（1邮件/2API）。
|
||
- 压缩包与安全：`zip_file`、`zip_file_md5`、`zip_pwd`（敏感，默认不导出或需脱敏/掩码）。
|
||
- 其他：`approval_id`、`copy_count`、`stock_id`、`button_conf`（`JSON`）。
|
||
- 索引：
|
||
- `udx_stock_id (stock_id)` 唯一；`idx_reseller (begin_time, end_time, reseller_id)`；`idx_status_creator (status, creator)`；`idx_end_time (end_time)`。
|
||
- 建议：如存在常用 `begin_time` 范围筛选与按状态查询，可添加 `status, begin_time` 复合索引以提高选择性。
|
||
- 导出查询规范：
|
||
- 计划相关导出需结合主表订单或自身权限字段进行过滤：`creator IN (...)` 或 `reseller_id IN (...)` 与时间窗口 `begin_time ≤ t ≤ end_time`。
|
||
- 默认白名单不包含 `zip_pwd/zip_file_md5` 等敏感字段；如需导出，必须具备更高权限并进行掩码或仅输出校验摘要。
|
||
- 对软删除记录：导出与展示需排除 `delete_time IS NOT NULL` 条目（或由模板显式选择策略）。
|
||
- EXPLAIN 达标建议：
|
||
- 针对计划列表与关联查询，优先使用 `status, creator` 与 `begin_time, end_time, reseller_id` 组合索引；时间窗口筛选需与索引前缀一致以避免全表扫描。
|
||
- 计划与订单关联时，以订单为驱动（带 `creator + create_time` 的过滤），计划表通过主键或索引快速匹配，避免 `Using temporary/filesort`。
|
||
- 安全与合规：
|
||
- `zip_pwd` 等敏感信息严格限制输出并进行审计；`button_conf`（JSON）默认关闭或选择性键导出。
|
||
- 下载与展示遵循最小必要原则，模板白名单默认不包含敏感字段；所有导出操作记录审计。
|
||
|
||
## 23. 营销系统 KEY 批次表定义
|
||
|
||
- 表：`key_batch`（KEY 批次与库存配置）。
|
||
- 主键：`id`（自增，`INT UNSIGNED`）。
|
||
- 关联关系：`key_batch.plan_id = plan.id`；订单侧冗余引用为 `order.key_batch_id`。
|
||
- 权限字段与范围：
|
||
- `creator`（创建人用户 ID）用于权限过滤与范围查询；与计划表 `creator` 协同过滤。
|
||
- 结合 `plan_id` 与活动时间窗口进行边界限定（`begin_time ≤ t ≤ end_time`）。
|
||
- 字段要点：
|
||
- 基本信息：`style`（KEY 样式）、`batch_name`（批次名称）。
|
||
- 绑定与数量：`bind_object`（1兑换码/2优惠码/4立减金）、`quantity`（发放数量）、`stock`（剩余库存）、`restrict`（最大绑定数量）。
|
||
- 行为配置：`allow_repetition`（是否允许重复选商品）、`merge_stock`（是否合并库存）、`allow_loss`（是否允许亏损）。
|
||
- 时间与状态：`begin_time`、`end_time`、`status`、`create_time`、`update_time`、`delete_time`（软删除）、`discard_time`（作废时间）。
|
||
- 冗余与敏感：`code_batch`（关联兑换码批次 JSON）、`zip_file/zip_file_md5/zip_pwd`（敏感，默认不导出或需脱敏/掩码）。
|
||
- 成本与价格：`key_official_price`、`key_cost_price`；有效期与预警：`expiration_conf`、`warning_conf`（JSON）。
|
||
- 其他：`generate_id`（生成记录 ID）、`creator_name`、`approval_status`、`approval_id`、`mobile_excel`（白名单 Excel 路径）、`mobile_repeat`（白名单允许重复号码 JSON）、`copy_count`。
|
||
- 索引：
|
||
- 现有：`idx_end_time (end_time)`、`idx_plan_id (plan_id)`。
|
||
- 建议：如常按 `status + end_time` 或 `begin_time + end_time` 过滤，增加相应复合索引；对 `creator + create_time` 的审计或列表查询可新增复合索引以提高选择性。
|
||
- 导出查询规范：
|
||
- 所有与 KEY 批次相关的导出需结合权限：`creator IN (...)` 或通过计划与订单的权限边界进行过滤；必须包含时间窗口限定。
|
||
- 字段白名单：默认允许 `plan_id/style/batch_name/bind_object/quantity/stock/allow_repetition/merge_stock/allow_loss/begin_time/end_time/status/create_time/update_time/key_official_price/key_cost_price`；敏感字段 `zip_file/zip_file_md5/zip_pwd/mobile_excel/mobile_repeat/code_batch/expiration_conf/warning_conf` 默认关闭或仅选择性键导出。
|
||
- 禁止对未建索引字段进行大范围过滤；尽量以计划或订单为驱动进行关联查询，减少在批次表上的独立全表扫描。
|
||
- EXPLAIN 达标建议：
|
||
- 过滤条件包含 `plan_id` 与时间窗口；如按 `status` 或 `creator` 列表查询，需配合复合索引并分页，避免 `Using filesort/temporary`。
|
||
- 与订单或计划表关联时，以高选择性过滤的表作驱动（通常订单或计划），批次表通过主键/索引快速匹配。
|
||
- 安全与合规：
|
||
- 任何涉及白名单文件路径、压缩包与密码的字段默认不导出；需要更高权限且输出内容需进行掩码或摘要化（如仅输出 MD5 校验）。
|
||
- JSON 字段导出走模板键路径选择，避免整段输出造成泄露与体积膨胀；所有导出操作记录审计。
|
||
|
||
## 24. 营销系统兑换码批次表定义
|
||
|
||
- 表：`code_batch`（兑换码/优惠券批次信息）。
|
||
- 主键：`id`（自增，`INT UNSIGNED`）。
|
||
- 关联关系：
|
||
- `code_batch.key_batch_id = key_batch.id`（外键逻辑关联）。
|
||
- 订单侧冗余引用为 `order.code_batch_id`，查询时以订单或 KEY 批次为驱动进行关联。
|
||
- 权限字段：`creator`（创建者用户 ID），用于导出权限过滤与范围控制。
|
||
- 字段要点：
|
||
- 基本：`status`、`title`、`plan_title`（冗余）、`describe`（兑换说明）、`range`（使用范围描述）。
|
||
- 时间：`begin_time`、`end_time`、`create_time`、`update_time`、`delete_time`、`discard_time`。
|
||
- 数量与库存：`quantity`、`usage`、`invalid`、`stock`（生成列：`(quantity - usage) - invalid`）。
|
||
- 限额与类型：`restrict`（绑定限额次数）、`type`（`0兑换码/1优惠券`）、`recharge_type`（`1单个充值/2组合充值`）。
|
||
- 价格与组合：`full`（满额）、`reduce`（减额）、`group_info`（组合商品基础信息，`JSON`）。
|
||
- 审批与复制：`approval_status`、`approval_id`、`copy_count`。
|
||
- 产品冗余：`product`（`JSON`）。
|
||
- 周期配置：`period_type`（`1不设置/2自动/3手动`）、`period_num`、`period_day`、`period_fixed_receive_time`（`time`）。
|
||
- 索引：
|
||
- 现有：`key_batch_id (key_batch_id)`、`idx_end_time (end_time)`。
|
||
- 建议：常用筛选可增加 `creator, create_time` 或 `status, end_time` 复合索引以提升选择性；按标题/计划模糊查询建议走前端限定与分页，避免无索引扫描。
|
||
- 导出查询规范：
|
||
- 导出需在主表（订单或 KEY 批次）应用权限与时间过滤：`creator IN (...)`、`begin_time ≤ t ≤ end_time`，再关联到 `code_batch`。
|
||
- 字段白名单：默认允许 `title/status/begin_time/end_time/quantity/usage/invalid/stock/restrict/type/recharge_type/full/reduce/create_time/update_time`；`product/group_info/range`（大字段/JSON）默认关闭，需更高权限且建议选择性键导出。
|
||
- 大范围筛选避免对未索引列进行；按 `end_time` 或 `status` 过滤时利用对应索引并配合分页。
|
||
- EXPLAIN 达标建议：
|
||
- 以订单或 KEY 批次为驱动（带 `creator + 时间窗口` 过滤），`code_batch` 通过主键或索引列快速匹配；避免 `Using temporary/filesort` 在大数据集出现。
|
||
- 对组合/周期场景，必要时拆分查询或利用窗口函数在可支持的引擎上完成统计，减少回表与二次扫描。
|
||
- 安全与合规：
|
||
- `product`、`group_info`、`range` 等可能包含敏感或大体积信息，模板默认不导出；若需要输出，采用键路径与掩码策略并记录审计。
|
||
- 软删除记录（`delete_time IS NOT NULL`）默认不参与导出，除非模板明确要求。
|
||
|
||
## 25. 营销系统 key 码发放记录表定义
|
||
|
||
- 表：`merchant_key_send`（开放平台 key 码发放记录）。
|
||
- 主键与唯一：
|
||
- `PRIMARY KEY (id)`（`BIGINT UNSIGNED` 自增）。
|
||
- `UNIQUE udx_key (key)`（单码唯一）。
|
||
- `UNIQUE udx_merchant_id_out_biz_no (merchant_id, out_biz_no)`（商户侧业务号唯一）。
|
||
- 关联关系：
|
||
- `key_batch_id → key_batch.id`；`plan_id → plan.id`；`stock_id` 与 `plan.stock_id` 逻辑关联。
|
||
- 可与订单主表通过 `` `order`.`key` = merchant_key_send.key `` 进行关联以查询核销状态与订单信息。
|
||
- 权限与范围：
|
||
- 按 `reseller_id`（分销商）或 `merchant_id`（开放商户）进行范围过滤；前端导出通过传递 `reseller_id IN (...)` 或 `merchant_id IN (...)`。
|
||
- 必须包含时间窗口（如 `create_time` 或 `status_update_time`）与状态筛选以提高选择性。
|
||
- 字段要点：
|
||
- 基本：`reseller_id`、`merchant_id`、`out_biz_no`、`out_timestamp`、`key_batch_id`、`stock_id`、`plan_id`、`store_id`。
|
||
- 券码：`key`、`status`（`1待发放/2已核销/3已作废/4充值中`）、`num`（发放数量）。
|
||
- 客户端与账号：`attach`（客户端请求参数，`JSON`）、`account_type`、`account`、`send_msg`（短信是否发送）。
|
||
- 时间：`usage_time`（核销时间）、`discard_time`（作废时间）、`status_update_time`（状态变更时间）、`update_time`、`create_time`。
|
||
- 索引：
|
||
- 现有：`udx_key (key)`、`udx_merchant_id_out_biz_no (merchant_id, out_biz_no)`、`idx_merchant_id_stock_id (merchant_id, stock_id)`、`idx_stock_id (stock_id)`、`idx_out_biz_no (out_biz_no)`、`idx_create_time (create_time)`。
|
||
- 建议：如常按状态或时间查询，增加 `status, status_update_time` 复合索引；针对分销商或商户维度增加 `reseller_id, create_time` 或 `merchant_id, create_time` 复合索引。
|
||
- 导出查询规范：
|
||
- 作为主导出场景时，必须包含权限范围（`reseller_id/merchant_id`）与时间窗口（`create_time/status_update_time`）；必要条件如 `status IN (...)`。
|
||
- 与订单或批次关联导出时，以高选择性表为驱动（如订单带 `creator + create_time` 过滤 或 批次/计划带时间与状态过滤）。
|
||
- 字段白名单：默认允许 `reseller_id/merchant_id/out_biz_no/out_timestamp/key_batch_id/stock_id/plan_id/store_id/key/status/num/usage_time/discard_time/status_update_time/update_time/create_time`；`attach/account` 等敏感或 PII 默认关闭或掩码输出（如部分显示或哈希）。
|
||
- EXPLAIN 达标建议：
|
||
- 过滤优先使用 `merchant_id/reseller_id + create_time` 或 `status + status_update_time` 组合索引；对 `key` 的点查走唯一索引。
|
||
- 排序尽量与索引前缀一致并配合分页，避免在大数据集上 `Using filesort/temporary`。
|
||
- 安全与合规：
|
||
- `account` 属 PII，模板默认不导出；如需导出，必须具备更高权限与掩码策略。
|
||
- `attach` JSON 仅导出必要键；严禁导出包含凭据或签名的字段；所有导出操作记录审计。
|
||
|
||
## 26. 营销系统立减金表定义
|
||
|
||
- 表：`voucher`（立减金批次与预算配置）。
|
||
- 主键与唯一：`id`（自增，`INT UNSIGNED`）；唯一键 `channel_activity_id`（渠道立减金批次号）。
|
||
- 关联关系：
|
||
- 与立减金订单表 `order_voucher.channel_activity_id = voucher.channel_activity_id` 进行关联；
|
||
- 可与商品 `goods_id` 关联到商品表（如存在），与订单的 `product_id` 做间接关联。
|
||
- 字段要点：
|
||
- 渠道与批次：`channel`（`1支付宝/2微信`）、`channel_activity_id`、`batch_goods_name`。
|
||
- 金额与额度：`price`（合同单价）、`recharge_amount`（充值批次金额）、`frozen_amount`（冻结额度）、`balance`（剩余额度）、`used_amount`（生成列：`recharge_amount - balance`）、`denomination`（面额）、`reduce_amount`（立减额）。
|
||
- 预算：`all_budget`（总预算）、`day_budget`（单天预算）。
|
||
- 配置：`receive_conf`（领取配置，`JSON`）、`card_type`（卡种类型，`JSON`）、`time_limit`（时间限制配置，`JSON`）。
|
||
- 说明与通知：`instruction`（使用说明，`TEXT`）、`early_per`（预警百分比，`JSON`）、`early_notifier`（预警通知人，`JSON`）、`last_early_per`（上次预警百分比）。
|
||
- 模板与渠道：`temp_no`（券模板编号，仅支付宝）、`provider`（微信服务商标识，可选）。
|
||
- 发券方式与数量：`receive_mode`（`1渠道用户id/2手机号或邮箱`）、`send_num`（发放数量）、`is_webview`（是否 webview 方式）。
|
||
- 其他：`notice`（使用须知）、`index`（排序）、`goods_id`（商品）。
|
||
- 时间：`create_time`、`delete_time`（软删除）。
|
||
- 索引：
|
||
- 现有：唯一 `channel_activity_id`，`idx_goods_id (goods_id)`。
|
||
- 建议：如常按渠道与批次过滤，增加 `channel, channel_activity_id` 复合索引（若不会与唯一冲突的查询场景）；按创建时间列表查询可添加 `create_time` 索引；若按状态类筛选（来自配置），考虑在业务层限定，避免无选择性扫描。
|
||
- 导出查询规范：
|
||
- 立减金导出应通过与 `order_voucher` 或订单主表关联来继承权限边界（如 `creator IN (...)` 或租户范围），避免对 `voucher` 进行独立全表导出。
|
||
- 字段白名单：默认允许 `channel/channel_activity_id/batch_goods_name/price/recharge_amount/frozen_amount/balance/used_amount/denomination/reduce_amount/all_budget/day_budget/provider/receive_mode/send_num/is_webview/create_time`；大字段/JSON（`receive_conf/card_type/time_limit/early_per/early_notifier/instruction/notice`）默认关闭或选择性键导出。
|
||
- 如需按商品维度导出，需通过授权的 `goods_id IN (...)` 列表或与订单/商品白名单关联实现权限控制。
|
||
- EXPLAIN 达标建议：
|
||
- 关联查询以 `order_voucher` 或订单为驱动（带 `creator + 时间窗口` 过滤），`voucher` 通过唯一或索引列快速匹配；
|
||
- 列表查询按 `create_time` 或 `channel_activity_id` 做点查/前缀匹配并分页，避免 `Using filesort/temporary`。
|
||
- 安全与合规：
|
||
- JSON 与说明类大字段默认不导出；若需输出，采用键路径与最小必要原则，并记录审计。
|
||
- 避免导出可能包含渠道敏感配置或内部标识（如 `temp_no/provider`）到公共模板；需权限校验与用途限定。
|
||
|
||
## 27. 营销系统立减金批次表定义
|
||
|
||
- 表：`voucher_batch`（立减金批次与渠道映射）。
|
||
- 主键与唯一：`id`（自增，`INT UNSIGNED`）；唯一键 `udx_channel_activity_id (channel_activity_id)`。
|
||
- 关联关系：
|
||
- `voucher_batch.voucher_id = voucher.id`（立减金主表关联）。
|
||
- 与立减金订单 `order_voucher.channel_activity_id = voucher_batch.channel_activity_id` 间接关联。
|
||
- 字段要点：
|
||
- 渠道批次与模板：`channel_activity_id`（渠道立减金批次号）、`temp_no`（券模板编号，仅支付宝）。
|
||
- 服务商：`provider`（微信/支付宝可选）。
|
||
- 权重：`weight`（用于批次选择或优先级控制）。
|
||
- 时间：`create_time`、`update_time`。
|
||
- 索引：
|
||
- 现有：唯一 `channel_activity_id`。
|
||
- 建议：如按 `voucher_id` 维度频繁查询，增加 `voucher_id` 索引；列表按时间查询可增加 `create_time` 索引。
|
||
- 导出查询规范：
|
||
- 批次信息通常作为维表使用，导出应通过与 `voucher` 或 `order_voucher` 关联来继承权限边界（如订单的 `creator IN (...)`）。
|
||
- 字段白名单：默认允许 `voucher_id/channel_activity_id/provider/temp_no/weight/create_time/update_time`；避免导出仅内部使用的渠道敏感标识到公共模板。
|
||
- EXPLAIN 达标建议：
|
||
- 关联查询通过唯一或索引列（`channel_activity_id`/`voucher_id`）点查；列表查询按时间索引并分页，避免 `Using filesort/temporary`。
|
||
- 安全与合规：
|
||
- 渠道模板编号与服务商标识可能为内部标识；默认仅在具备相应权限的模板中使用，导出需审计。
|
||
|
||
## 28. 营销系统表关系与映射
|
||
|
||
- 驱动表与权限：
|
||
- 驱动表：`order`（主键 `order_number`，权限字段 `creator`）。
|
||
- 所有导出查询以 `order` 为驱动，强制注入权限过滤：`creator IN (...)`，并结合时间范围 `create_time`。
|
||
- 关系与连接（均采用 `LEFT JOIN`，仅当业务语义要求强关联时可用 `INNER JOIN`）：
|
||
- 详情：`order_detail.order_number = order.order_number`。
|
||
- 红包：`order_cash.order_number = order.order_number`。
|
||
- 立减金订单：`order_voucher.order_number = order.order_number`。
|
||
- 立减金：`voucher.channel_activity_id = order_voucher.channel_activity_id`。
|
||
- 立减金批次：`voucher_batch.voucher_id = voucher.id`。
|
||
- 计划：`plan.id = order.plan_id`。
|
||
- KEY 批次：`key_batch.plan_id = plan.id`。
|
||
- 兑换码批次：`code_batch.key_batch_id = key_batch.id`。
|
||
- 开放平台发放记录：`` `order`.`key` = merchant_key_send.key ``。
|
||
- 连接键索引与保留字：
|
||
- 为上述连接键建立或验证必要索引：`order.order_number`、`order.creator, order.create_time`、`order_detail.order_number`、`order_cash.order_number`、`order_voucher.order_number`、`voucher.channel_activity_id`、`voucher_batch.voucher_id`、`plan.id`、`key_batch.plan_id`、`code_batch.key_batch_id`、`merchant_key_send.key`。
|
||
- 表名 `order` 与列名 `` `key` ``为保留字，SQL 中需使用反引号包裹以避免语法冲突。
|
||
- 模板生成 SQL 的连接顺序建议：
|
||
- 优先应用驱动表过滤（`creator + create_time + type/...`），再按选择性从高到低依次连接：计划 → KEY 批次 → 兑换码批次；立减金订单 → 立减金 → 立减金批次；红包；详情；发放记录。
|
||
- 避免无条件连接造成笛卡尔积；每个连接必须具备明确的等值连接键。
|
||
- 性能与 EXPLAIN 要点：
|
||
- 连接计划应使高选择性条件尽早生效；排序字段尽量与索引前缀一致。
|
||
- 对超大数据场景采用分页与稳定排序键；避免在大范围上出现 `Using temporary` 与 `Using filesort`。
|
||
- 字段白名单与敏感字段：
|
||
- 默认排除敏感列（如 `card_code`、账号与渠道标识、JSON 大字段）；如需导出需更高权限并进行掩码或选择性键导出。
|
||
- 前端模板仅提供白名单字段选择，禁止自由输入列名与表名。
|
||
|
||
## 29. 操作面板与模板生成流程
|
||
|
||
- 面板步骤：
|
||
- 选择数据源：`营销系统` 或 `易码通`（当前默认支持“订单数据”场景）。
|
||
- 选择导出场景：`订单数据`（后续可扩展其他场景）。
|
||
- 选择附表信息：依据“表关系与映射”显示可选附表与连接键；用户勾选所需的详情、红包、立减金、计划、KEY 批次、兑换码批次、发放记录等。
|
||
- 设置权限范围与条件：必填 `creator IN (...)`（或租户范围）与时间窗口（如 `order.create_time`）；可选类型、状态、渠道、计划等条件；所有条件走参数化。
|
||
- 选择字段与输出格式：仅白名单字段；输出格式 `csv/xlsx`；是否列统计、是否按条件分多 sheet。
|
||
- 确认生成模板：生成模板并运行 `EXPLAIN` 评估，达标后方可保存与执行。
|
||
- SQL 生成：
|
||
- 以驱动表 `order` 构建 `SELECT`；按已选附表生成 `LEFT JOIN`，连接条件来自“表关系与映射”。
|
||
- 强制注入权限与时间条件；仅允许白名单列与等值/范围过滤；禁止自由拼接 SQL 与 `SELECT *`。
|
||
- 排序与分页：按索引前缀字段排序；大数据导出采用分页与稳定排序键；尽量一次查询覆盖需求并流式写文件。
|
||
- 多 sheet：可按指定列（如订单类型或日期）拆分；保持稳定排序避免跨批次混入。
|
||
- 列统计：在同一 SQL 使用聚合/窗口生成统计或追加统计 sheet，避免二次扫描。
|
||
- EXPLAIN 分析面板：
|
||
- 展示核心字段：`id`、`select_type`、`table`、`type`、`possible_keys`、`key`、`key_len`、`ref`、`rows`、`filtered`、`Extra`。
|
||
- 评估规则：禁止大表 `type=ALL`；优先 `ref/range/const`；`rows` 合理可控；避免超大数据集上的 `Using temporary/filesort`。
|
||
- 达标门槛：满足上述规则后允许执行；超标给出索引建议与模板调整指引（减少字段、改时间窗口、补充过滤或新增索引建议）。
|
||
- 模板保存与可见性：
|
||
- 保存为 `export_templates` 记录，包含数据源、主表、关联、字段、过滤、格式、统计、多 sheet、可见性（公共/个人）、所有者、`EXPLAIN` 结果与评分。
|
||
- 公共模板需通过评审并标注责任人；个人模板仅本人可见或按角色授权可见。
|
||
- 执行与进度：
|
||
- 发起导出后记录到 `export_jobs`；展示总行数估算/实际、当前批次、速率、预计完成时间与状态；支持取消与失败重试。
|
||
- 文件记录存入 `export_job_files`，下载链接带签名与有效期；支持 `csv/xlsx`。
|
||
- 安全与合规：
|
||
- 敏感字段默认不可选（如 `card_code`、账号、渠道标识与大 JSON）；需要更高权限并进行掩码或选择性键导出。
|
||
- 所有参数化与权限注入由后端统一实现；导出与下载行为记录审计。
|
||
|
||
## 30. 字段选择与列名约定
|
||
|
||
- 默认选择：
|
||
- 默认仅导出主表 `order` 的白名单字段；附表字段需用户显式勾选。
|
||
- 默认排除敏感字段（如 `card_code`、账号标识、渠道标识、大 JSON 等）。
|
||
- 列名来源：
|
||
- 优先使用数据库字段的 `COMMENT` 作为导出列名（中文优先）。
|
||
- 如 `COMMENT` 为空或过于技术化，则：
|
||
- 使用模板中的别名作为列名；
|
||
- 或将列名从 `snake_case`/`camelCase` 转为可读名（如 `order_number` → `订单编号`，无词典时保留原名）。
|
||
- 冲突与去重：
|
||
- 当不同表存在同名字段并被选择时，自动加前缀（如 `订单.订单编号`、`计划.计划编号`）或根据模板别名消除歧义。
|
||
- 同一语义字段重复选择时进行去重或保留一个主列，遵循模板优先级。
|
||
- 排序与输出：
|
||
- 列顺序遵循用户选择顺序；主表字段在前，附表字段在后；统计列或多 sheet 信息追加在末尾或独立 sheet。
|
||
- 文本统一 `UTF-8`；数值与时间按统一格式输出（时间默认 `YYYY-MM-DD HH:mm:ss`，时区统一为 `UTC` 或模板指定）。
|
||
- 安全与合规：
|
||
- 对被允许导出的敏感列进行掩码（如账号、姓名仅展示部分）；JSON 字段仅允许按键路径选择性导出。
|
||
- 列名中不包含敏感信息或内部标识；对渠道或凭据相关内容默认不展示于列名与文件中。
|
||
|
||
## 31. 新增导出模板整体流程
|
||
|
||
- 新增导出：在操作面板点击“新增导出”。
|
||
- 选择数据源：`营销系统` 或 `易码通`。
|
||
- 选择导出场景：当前支持 `订单数据`（后续可扩展）。
|
||
- 自定义导出字段：根据“表关系与映射”逐步选择主表与附表字段；默认仅主表字段，附表需显式勾选；仅白名单字段。
|
||
- 生成模板：点击“生成模板”，后端构建 SQL 并执行 `EXPLAIN` 分析。
|
||
- 返回分析结果：展示 `EXPLAIN` 关键项与评估结论；若达标则保存模板并可执行导出；未达标返回索引建议与模板调整提示。
|
||
- 执行导出：可立即基于模板发起导出，进入进度追踪与文件下载流程。
|
||
|
||
## 32. 模板列表与检索
|
||
|
||
- 列表范围：展示“内置公共模板”与“当前账号所有模板”（个人/共享）。管理员或具备相应角色可查看全部模板。
|
||
- 基本展示列：
|
||
- 模板名称、数据源（营销系统/易码通）、场景（订单数据）、主表、可见性（公共/个人）、所有者、创建/更新时间。
|
||
- EXPLAIN 评分与最近校验时间、字段数量、关联表数量、输出格式（csv/xlsx）、统计开启与多 sheet 条件。
|
||
- 过滤条件：
|
||
- 数据源、场景、可见性、所有者、创建时间范围、启用状态、EXPLAIN 评分区间、标签（如渠道/计划/类型）。
|
||
- 关键字搜索支持名称与主表/关联表名，采用前缀匹配与分页限制。
|
||
- 排序与分页：
|
||
- 支持按更新时间、创建时间、EXPLAIN 评分、预计行数等排序；统一服务端分页与总数统计。
|
||
- 快捷操作：
|
||
- 预览 SQL（敏感信息掩码）、重新校验 EXPLAIN、编辑元数据、启用/停用、发起导出、查看历史下载、复制（fork）模板、删除（仅未被引用或无权限边界影响时）。
|
||
- 权限与可见性：
|
||
- 公共模板所有符合角色/租户的用户可见与使用；个人模板仅所有者或授权角色可见；维护者可在可见范围内编辑公共模板。
|
||
- 删除受限：被导出记录引用的模板不可直接删除（或需先停用并解除引用）。
|
||
- 安全与审计：
|
||
- 列表与详情不展示完整 DSN 或任何敏感凭据；SQL 预览中掩码权限范围与敏感列。
|
||
- 模板的启停、删除、复制、校验与发起导出操作均记录审计日志。
|
||
|
||
## 33. 导出记录查看与操作
|
||
|
||
- 展示内容：
|
||
- 文件大小（`size_bytes` 聚合显示与各文件明细）。
|
||
- 文件地址（`storage_uri`，展示可下载的签名链接）。
|
||
- 数据量大小（总行数与各文件 `row_count`）。
|
||
- 导出开始时间（`started_at`）与完成时间（`finished_at`）。
|
||
- 执行人 ID（`requested_by`）。
|
||
- 任务状态（`queued/running/failed/completed/canceled`）与耗时。
|
||
- 列表来源：
|
||
- 来自 `export_jobs` 与 `export_job_files` 的聚合视图；多文件（多 sheet 或分块）展示合计与明细展开。
|
||
- 过滤与排序：
|
||
- 按执行人、时间范围、状态、模板、数据源过滤；按完成时间、耗时、文件大小、行数排序。
|
||
- 服务端分页与总数统计；支持关键字搜索模板名称与执行人。
|
||
- 行操作：
|
||
- 下载：提供带签名与有效期的下载链接；支持单文件与批量（ZIP 封装）。
|
||
- 删除：
|
||
- 仅拥有者或具备相应角色可删除；公共任务需具备维护权限。
|
||
- 默认删除逻辑：删除文件的物理存储并保留 `export_jobs` 元数据与审计；或将记录标记为已清理。
|
||
- 对正在运行的任务不可删除；对失败任务可清理文件记录与中间产物。
|
||
- 权限与合规：
|
||
- 下载链接签名与有效期控制，防止外泄；公开范围需受角色与租户限制。
|
||
- 列表中不展示敏感参数；文件名与路径不包含凭据或内部标识。
|
||
- 审计与保留：
|
||
- 下载与删除操作记录审计（操作者、时间、目标文件、结果）。
|
||
- 数据保留策略：按时间与空间配额定期清理历史文件，仅保留元数据；可配置每模板或每执行人的保留上限。
|
||
|
||
## 34. 模板行执行导出与进度展示
|
||
|
||
- 触发入口：
|
||
- 模板列表的每一行提供“执行导出”按钮；点击后创建一条新的导出任务记录并异步执行。
|
||
- 任务创建：
|
||
- 在 `export_jobs` 新增记录：`template_id`、`requested_by`、`permission_scope_json`、`options_json`、`file_format`、`status=queued`、`created_at`。
|
||
- 初始化 `row_estimate`（来自 `EXPLAIN` 或估算流程）、`started_at`（排队开始）、`total_rows`（执行中累计）。
|
||
- 异步执行：
|
||
- 任务状态流转：`queued → running → (completed | failed | canceled)`；支持取消与失败后重试。
|
||
- 并发与限流：对全局与每账号的并发进行限流与队列调度，避免资源争抢。
|
||
- 预计完成时间（ETA）：
|
||
- 依据 `row_estimate` 与实时写入速率（行/秒）计算 ETA，并随进度动态更新；若估算缺失，先以启动阶段速率预估后修正。
|
||
- 进度展示：
|
||
- 实时显示：已写行数、当前批次、平均速率、ETA、状态与错误摘要。
|
||
- 推送方式：SSE/WebSocket 或按 1-3 秒轮询；界面在模板行与导出记录页面均显示进度。
|
||
- 完成反馈：
|
||
- 导出完成后弹出通知，提供下载入口；同时在“导出记录”页可下载。
|
||
- 文件记录：在 `export_job_files` 新增记录并展示 `storage_uri`（签名链接）、`row_count`、`size_bytes`、`sheet_name`（如多 sheet）。
|
||
- 安全与合规：
|
||
- 下载链接签名与有效期；权限校验基于模板的可见范围与执行人身份。
|
||
- 进度与日志不展示敏感参数与凭据；错误信息进行安全脱敏。
|