# MarketingSystemDataTool 项目规则 ## 1. 项目概述 - 技术栈：后端使用 `Go`，前端使用 `HTML + CSS + JS`，前后端代码同仓管理。 - 目标：为“营销系统”和“易码通系统”提供统一的高性能数据导出能力，支持模板化 SQL 构建与权限控制，生成 `CSV` 与 `Excel` 文件。 - 数据源：至少包含两个独立库（`marketing_db`、`ymt_db`），通过环境变量配置连接与凭据。 ## 2. 目录结构与命名约定 - `server/`：Go 服务端代码（API、模板校验、导出执行、权限校验、日志与监控）。 - `web/`：前端页面与静态资源（模板管理、导出发起、进度查看、历史下载）。 - `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` 取消任务。 - 前端约定： - 统一通过权限范围参数（如 `user_id IN (...)`）传递查询边界；由后端注入到 SQL。 - 所有下拉/选择项来自白名单与元数据；禁止自由输入列名与表名。 ## 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 组合（推荐在运行时通过环境变量组装）： - 模板：`:@tcp(:)/?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）。 - 安全与合规： - 下载链接签名与有效期；权限校验基于模板的可见范围与执行人身份。 - 进度与日志不展示敏感参数与凭据；错误信息进行安全脱敏。