# 取数报表维护编排

本参考定义由 Skill + Agent 负责的业务方法。`tbcli` 只执行明确的目录发现、日期取数、覆盖查询和导入元命令，不自行决定维护范围。

## 维护清单

本表是插件唯一的维护清单，不在其他 Skill、JSON、定时任务提示词或 Agent 配置中复制另一份长期注册表；每次运行的计划快照不属于第二份注册表。
`日常启用=是` 表示已纳入默认日常检查；`否` 保留能力但不参加无人值守运行。
当前清单包含已确认的 19 张取数报表、1 张旺店通订单事实和 1 张旺店通退款事实，共 21 张且全部启用；用户点名只处理点名表，停用表需用户明确同意才临时执行。调度器提示词中曾记录的固定数量只是创建时基线，运行范围始终以本表实时“日常启用”行为准。
新增表先完成单表验证与用户确认，再加入清单；平台出现新维度不自动加入。
清单及本文件中的口径随 `tbcli update` 同步。运行不得自行修改清单。
日常维护完整流程见 [日常更新](daily-update.md)，历史重建仍使用本文件后半部分。

| 业务表 | 数据集 | 平台 / 粒度 / 维度 | 时间粒度 | 维护默认设置 | 日常启用 |
| --- | --- | --- | --- | --- | --- |
| 店铺-整体 | `shop-overall` | 生意参谋 / 店铺 / 整体 | `day` | `--fields all --device overall`；只保留所有终端汇总，不取无线端和 PC 端拆分 | 是 |
| 店铺-关键词 | `shop-keyword` | 生意参谋 / 店铺 / 关键词 | `day` | `--fields all`；“分词类型”选择目录返回的全部实时可用值，当前基线为 `se_keyword,lgt_keyword,core_keyword,prop_keyword,brd_keyword` | 是 |
| 商品-整体 | `item-overall` | 生意参谋 / 商品 / 整体 | `day` | 所有商品状态，`--fields all --device overall`；只保留所有终端汇总，不取无线端和 PC 端拆分 | 是 |
| 商品-SKU | `item-sku` | 生意参谋 / 商品 / SKU | `day` | 全部 SKU，`--fields all --device overall`；只保留所有终端汇总，不取无线端和 PC 端拆分 | 是 |
| 商品-经营投产比 | `item-roi` | 生意参谋 / 商品 / 经营投产比 | `day` | 所有商品状态，`--fields all`；此维度无终端分组，不传 `--device` | 是 |
| 商品-连带 | `item-bundle` | 生意参谋 / 商品 / 连带 | `week` | `--fields all`；此维度无终端分组，无额外筛选 | 是 |
| 商品-流量来源 | `item-traffic-source` | 生意参谋 / 商品 / 流量来源 | `day` | 精确使用旧版维度 `流量来源`，禁止选 `流量来源(新版)`；选择所有商品，`--fields all --filter '转化效果归属=nearest'`；支付金额筛选与访客数筛选均为全部（不设置上下限）；此维度无终端分组 | 是 |
| 商品-流量来源详情 | `item-traffic-source-detail` | 生意参谋 / 商品 / 流量来源详情 | `day` | 精确使用旧版维度 `流量来源详情`，禁止选 `流量来源详情(新版)`；选择所有商品，`--fields all`；“搜索来源”展开目录返回的全部实时值；`--filter '转化效果归属=nearest'`；此维度无终端分组 | 是 |
| 商品-整体退款分布 | `item-refund-overall` | 生意参谋 / 商品 / 整体退款分布 | `day` | 选择所有商品，`--fields all`；无额外筛选，不传 `--item-ids` 或 `--device` | 是 |
| 商品-退款原因分布 | `item-refund-reason` | 生意参谋 / 商品 / 退款原因分布 | `day` | 所有商品；全部时间类型 `pay,rfd`；退款场景 `ALL`；退款时间选择目录全部 6 项；`--fields all`；不传 `--item-ids` 或 `--device` | 是 |
| 商品-流失竞店分布 | `item-loss-competitor` | 生意参谋 / 商品 / 流失竞店分布 | `day` | 所有商品；全部时间类型 `pay,rfd`；退款场景 `ALL`；退款后状态选择目录全部实时值；`--fields all`；不传 `--item-ids` 或 `--device` | 是 |
| 商品-退款SKU分布 | `item-refund-sku` | 生意参谋 / 商品 / 退款SKU分布 | `day` | 所有商品，`--fields all`；无额外筛选，不传 `--item-ids` 或 `--device` | 是 |
| 无界-账户 | `wujie-account` | 无界 / 基础报表 / 账户 | `day` | `--fields all --filter '转化周期=15天转化'`；不传 `--device`；只维护 15 天转化口径，不与 1 天转化混合 | 是 |
| 无界-计划 | `wujie-plan` | 无界 / 基础报表 / 计划 | `day` | `--fields all --filter '转化周期=15天转化'`；不传 `--device` | 是 |
| 无界-人群 | `wujie-audience` | 无界 / 基础报表 / 人群 | `day` | `--fields all --filter '转化周期=15天转化'`；不传 `--device` | 是 |
| 无界-商品主体 | `wujie-subject` | 无界 / 基础报表 / 商品主体 | `day` | `--fields all --filter '转化周期=15天转化'`；不传 `--device` | 是 |
| 无界-创意 | `wujie-creative` | 无界 / 基础报表 / 创意 | `day` | `--fields all --filter '转化周期=15天转化'`；不传 `--device` | 是 |
| 无界-单元 | `wujie-unit` | 无界 / 基础报表 / 单元 | `day` | `--fields all --filter '转化周期=15天转化'`；不传 `--device` | 是 |
| 无界-关键词 | `wujie-keyword` | 无界 / 基础报表 / 关键词 | `day` | `--fields all --filter '转化周期=15天转化'`；不传 `--device`；全历史固定按最长 30 天连续分片 | 是 |
| 旺店通-订单及明细 | `wdt-orders` | 旺店通 / 订单头、订单明细、运单 | `day` | 按支付时间；精确单店；隐私白名单；`wdtcli web orders export` 完整分页并输出新 JSON，随后由 `tbcli profit orders validate/import/coverage` 校验和幂等入库 | 是 |
| 旺店通-退款及明细 | `wdt-refunds` | 旺店通 / 退款头、退款明细 | `day` | 按退款申请时间采集；保留结算时间和实际退款金额；精确单店；隐私白名单；`wdtcli web refunds export` 完整分页并输出新 JSON，随后由 `tbcli profit refunds validate/import/coverage` 校验和幂等刷新 | 是 |

只有用户明确要求“维护全部取数报表”“日常更新”或“补全取数报表近期缺失数据”时才遍历日常启用的清单；无修饰的正式日常更新包括本表启用的全部来源。用户点名单表时只处理点名目标。新增表格时，先完成一次经用户确认的全量取数与入库，再把稳定口径加入本表。

### 旺店通订单事实口径

此行是同一维护清单中的异源分支，不把旺店通网页订单伪装成生意参谋 Excel，也不复制到第二份清单。

- 采集依赖：运行时发现 `wdtcli`，确认帮助中存在 `web orders export`，并以 `wdtcli auth status --json` 验证当前旺店通登录态。缺命令返回 `CONTRACT_UNSUPPORTED`；登录失效返回 `WDT_AUTH_REQUIRED`。无人值守不得打开交互登录或绕过验证码。
- 店铺身份：先运行 `tbcli profit orders identity --json`。只有结果恰好一个身份时才使用其中的 `shop_key`、`wdt_shop_id`、`shop_name`；零个身份返回 `INITIAL_IMPORT_REQUIRED`，多个身份返回 `SHOP_SCOPE_REQUIRED`，不得猜测。用户明确点名且与唯一身份一致时继续；相反证据立即停止。
- 日常范围：本数据集经用户确认的维护起点是 `2026-07-01`。检查下界取“维护起点”和“当前自然年 1 月 1 日”中较晚者，上界为昨天的完整支付日；2026 年因此从 `2026-07-01` 检查，2027 年及以后从当年 `01-01` 检查。用 `tbcli profit orders coverage --shop-key '<key>' --start-date '<检查下界>' --end-date '<昨天>' --json` 取得 `missingPeriods`；不能把维护起点以前的日期解释为缺失，不能靠订单表最大日期推断，也不补往年。
- 下载：每个连续缺口执行一条 `wdtcli web orders export --from '<开始> 00:00:00' --to '<结束> 23:59:59' --shop-id '<id>' --shop-name '<name>' --page-size 200 --out '<新JSON>' --json`。文件、checkpoint 和 SHA sidecar 均在本次 artifactDir；已有文件只允许按导出器的 checkpoint 契约显式 `--resume`，不能覆盖。
- 入库：先运行 `tbcli profit orders validate --input '<JSON>' --shop-key '<key>' --shop-name '<name>' --json`，要求店铺、日期、API 前后总数、订单/明细数、摘要、稳定键和隐私白名单全部通过；入库前重查 coverage，仍完整缺失才执行 `tbcli profit orders import ...`。导入按稳定订单、明细和运单键幂等更新，并保存来源批次；入库后对完整检查区间再次 coverage，只有 `complete:true` 才完成。
- 日常同时执行“缺口补齐”和“近期滚动刷新”。缺口仍从维护起点检查；滚动刷新窗口固定为昨天向前 45 个完整自然日（含昨天），早于维护起点则截断。该窗口内即使 coverage 已完整，也重新导出订单并用稳定键幂等更新状态、发货和运单；窗口外不回刷。滚动刷新文件仍须完整校验和保存新批次，不用 coverage 的“已完整”条件阻止经清单授权的刷新。

### 旺店通退款事实口径

- 与订单共用唯一店铺身份、维护起点 `2026-07-01`、维护锁和 artifactDir。按退款申请时间检查缺口，按结算时间参与每日利润。
- 缺口用 `tbcli profit refunds coverage --shop-key '<key>' --start-date '<下界>' --end-date '<昨天>' --json`。每个缺口执行 `wdtcli web refunds export --from '<开始> 00:00:00' --to '<结束> 23:59:59' --shop-id '<id>' --page-size 200 --out '<新JSON>' --json`。
- 每日另对昨天向前 45 个完整自然日执行一次滚动刷新，即使 coverage 已完整也执行；这是退款状态和结算金额会变化所必需的更新，不是全历史重建。
- 每个文件先 `tbcli profit refunds validate --input '<JSON>' --shop-key '<key>' --shop-name '<name>' --json`，再执行 `profit refunds import`。入库按退款稳定键替换同一退款的最新头和明细；源文件相同 SHA 时安全跳过。
- 日常完成后对完整检查区间再次运行 coverage；同时保存滚动刷新批次的范围、行数和 SHA。退款结算日可能晚于申请日，不能用申请日 coverage 代替结算金额的最新性证明。

维护默认设置优先于 `SKILL.md` 中普通临时取数的通用自然语言映射。特别是店铺-整体、商品-整体和商品-SKU：这里的“所有终端”固定指平台的汇总端 `--device overall`，不是技术参数 `--device all`。`--device all` 会同时加入汇总、无线端和 PC 端字段，会破坏现有仓库字段契约，维护流程禁止使用。

对有枚举筛选的表，目录中的“全部”必须展开为该次目录返回的所有实时值：商品-整体和商品-经营投产比的“商品状态”当前基线为 `Y,N`；商品-SKU的“SKU筛选”当前基线为 `Y,N`；店铺-关键词使用目录返回的全部分词类型。若实时值与基线不同，使用实时全集并在下载前披露变化；不要只取默认单值。

无界-账户必须精确使用 `--data-platform '无界' --data-type '基础报表' --data-dimension '账户' --date-type day --fields all --filter '转化周期=15天转化'`，不传 `--device`。当前目录转化周期基线为 `1天转化,15天转化`，维护口径只选择 `15天转化`；若目录不再提供该值，停止并报告契约变化，不得改用 1 天转化。2026-08-26 的验证基线为目录完整区间 `2026-05-28~2026-08-25`、官方 Excel 68 列、378 行，所有行的转化周期均为 `15天转化`，核心维度是 `统计日期`、`店铺名称`、`转化周期`、`场景名字`、`原二级场景名字`，默认分析指标为 `展现量`、`点击量`、`花费`、`总成交金额`。全历史优先单文件；若恰好 100,000 行、实际日期未覆盖目录完整区间或出现截断迹象，按连续日期区间二分后重取。

无界-计划、人群、商品主体、创意、单元、关键词沿用相同的硬口径：精确使用 `无界 / 基础报表 / <维度>`、`day`、`--fields all --filter '转化周期=15天转化'`，不传 `--device`。目录若不再提供 `15天转化`，必须停止，不得改用其他周期。2026-08-26 的全量验证基线如下：

| 表 | 完整区间 | Excel 列数 | 数据行 | 核心业务身份 |
| --- | --- | ---: | ---: | --- |
| 无界-计划 | 2026-05-27~2026-08-24 | 70 | 8,153 | 计划ID、计划名字 |
| 无界-人群 | 2026-05-27~2026-08-24 | 74 | 56,830 | 计划、单元、人群名字、主体 |
| 无界-商品主体 | 2026-05-28~2026-08-25 | 73 | 50,005 | 计划、主体ID、主体类型、主体名称 |
| 无界-创意 | 2026-05-27~2026-08-24 | 73 | 60,507 | 计划、创意、主体 |
| 无界-单元 | 2026-05-27~2026-08-24 | 82 | 44,940 | 计划、单元、主体 |
| 无界-关键词 | 2026-05-27~2026-08-24 | 76 | 141,395 | 计划、单元、宝贝、词类型、词/词包ID与名称 |

前五张表全历史先尝试单文件，触及统一截断条件时再二分。无界-关键词已验证单文件恰好返回 100,000 行且实际只覆盖 `2026-07-10~2026-08-24`，因此全量固定按连续、无重叠、最长 30 天区间拆分；任何分片再次触及 100,000 行就二分。规范文件名统一为 `无界-<维度>-分日-15天转化-<开始>至<结束>.xlsx`。截断失败文件不得导入，也不得参与目录批量导入。

商品-流量来源有一个近似名称 `流量来源(新版)`。维护契约必须按目录中的精确名称选择旧版 `流量来源`，不得依赖模糊匹配。该表“所有商品”表示不传 `--item-ids`；“支付金额筛选=全部”和“访客数筛选=全部”表示不传这两个 custom 筛选项（不施加数值边界）；“最后一次访问来源”对应目录枚举代码 `nearest`，必须传 `--filter '转化效果归属=nearest'`。若目录不再返回这三个筛选项或 `nearest`，停止并报告契约变化，不猜测替代值。

商品-流量来源的官方 Excel 当前以 `一级流量来源`、`二级流量来源`、`三级流量来源` 表示目录中的来源身份字段；这是已验证的同一旧版维度表头契约。单次全历史导出在实测中会截断为 100,000 行，不能仅凭请求区间覆盖全历史就判定文件完整。全量取数固定按不重叠的 14 天连续区间拆分，最后一个区间可短于 14 天；逐片验证请求区间、实际数据范围、25 列表头、临时报表清理，并在全部分片完成后检查区间首尾相接、无重叠、无缺口。若平台限制或表头变化，停止并把新事实写回契约，不盲目加大分片。

商品-流量来源详情有近似名称 `流量来源详情(新版)`。维护时必须精确选择旧版 `流量来源详情`。该表“所有商品”表示不传 `--item-ids`；“搜索来源=全部”必须展开为该次目录返回的所有实时枚举值，当前验证基线为 `关键词推广(原直通车),手淘搜索,关键词推广`；“最后一次访问来源”对应 `nearest`。命令必须包含 `--filter '搜索来源=<实时全集>' --filter '转化效果归属=nearest'`，不传 `--device`。若实时枚举或筛选结构变化，停止并报告，不猜测。

商品-流量来源详情官方 Excel 的当前表头契约为 23 列，核心身份字段是 `商品ID`、`商品名称`、`搜索词类型`、`搜索词`、`归属原则`。全量取数固定先按不重叠的 14 天连续区间拆分；逐片验证请求区间、实际数据范围、23 列表头和清理结果。任何分片若返回恰好 100,000 行或出现截断迹象，不得入库；把该区间二分后重新取数，直到每片通过完整性验证。最后检查全部声明区间首尾相接、无重叠、无缺口。

商品-整体退款分布没有筛选项和终端拆分。“所有商品”表示不传 `--item-ids`；使用 `--data-dimension '整体退款分布' --date-type day --fields all`，不传 `--filter` 或 `--device`。官方 Excel 当前为 21 列，核心身份字段是 `商品ID`、`商品名称`、`时间类型`，默认分析指标为 `成功退款金额`、`成功退款子订单数`、`成功退款人数`。全量取数按连续、无重叠的 90 天区间拆分，最后一片可短于 90 天；任何分片若返回恰好 100,000 行或出现截断迹象，不得入库，二分该区间后重取。

商品-退款原因分布必须使用 `--filter '时间类型=pay,rfd' --filter '退款场景=ALL' --filter '退款时间=全部,支付30分钟内,30分钟-24小时,24小时-7天,7天-15天,15天以上'`。其中“全部时间类型”是目录实时返回的 `pay,rfd` 全集，“退款场景=全部”是代码 `ALL`，退款时间则按用户要求同时选择全部汇总项和 5 个时长分桶。所有商品表示不传 `--item-ids`，该维度无终端拆分。官方 Excel 当前为 16 列，核心维度包括 `商品ID`、`商品名称`、`时间类型`、`退款场景`、`退款识别类型`、`退款时间`、`退款原因类型`、`退款原因`。默认分析指标为 `成功退款金额`、`成功退款子订单数`、`成功退款人数`。汇总项与明细分桶可能重叠，后续分析不得跨 `时间类型` 或把 `退款时间=全部` 与 5 个分桶直接相加。全量取数固定按连续、无重叠的 90 天区间拆分。

商品-流失竞店分布必须使用 `--filter '时间类型=pay,rfd' --filter '退款场景=ALL' --filter '退款后状态=<目录实时全集>'`。当前退款后状态基线为 `samepay,otherpay,loss,notbuy-strong,notbuy-weak,notbuy`；若目录变化，使用实时全集并披露。所有商品表示不传 `--item-ids`，该维度无终端拆分。官方 Excel 当前为 11 列，核心维度包括 `商品ID`、`商品标题`、`时间类型`、`退款场景`、`退款时间`、`退款后状态`、`流失商家ID`、`流失商品ID`，默认指标为 `竞品流失金额`。后续分析必须保留时间类型和退款后状态口径，避免跨互斥或重叠口径误加。全量取数固定按连续、无重叠的 90 天区间拆分。

商品-退款SKU分布没有筛选项和终端拆分。所有商品表示不传 `--item-ids`；使用 `--data-dimension '退款SKU分布' --date-type day --fields all`。官方 Excel 当前为 12 列，核心维度包括 `商品ID`、`商品名称`、`SKU ID`、`SKU名称`、`时间类型`，默认指标为 `成功退款金额`、`成功退款子订单数`、`成功退款人数`。全量取数固定按连续、无重叠的 90 天区间拆分。

上述三张新增退款表的每个分片都必须验证请求筛选回执、实际表头、日期范围和临时报表清理。若分片恰好返回 100,000 行或有截断迹象，不得入库；二分区间后重取。若平台对某个已请求枚举没有返回明细行，只能说明该区间当前没有对应行，不能擅自删除该枚举或把请求口径改成单选。

## 意图路由

- “补全取数报表近期缺失数据” → 清单内全部表，执行近期增量流程。
- “补全商品-整体表格” → 只对商品-整体执行近期增量流程。
- “重新拉取商品-整体的全量数据” → 只对商品-整体执行全量重建流程。
- 明确日期、字段或筛选条件的普通下载 → 执行普通 SYCM Report Flow；除非用户同时要求入库，否则不要自动导入。
- “下载/处理某张维护表的所有历史并上传数据库” → 对点名表执行全量重建流程；若一次导出恰好 100,000 行或实际日期未覆盖目录完整区间，立即判为截断并返回分片主线，禁止入库。

## 近期增量流程

以下是单表业务算法；执行前必须先进入 [日常更新](daily-update.md) 完成预检、互斥与运行记录。
只检查模式不执行写检查、下载、入库、run-start 或登录等待。定时与手动实际更新共用同一运行目录。
完成旧日期回刷、跨年补漏或历史重建均不是本流程的默认权限。

“近期”是业务策略，不是 CLI 默认值。当前规则为：只维护当前自然年，不追补往年历史缺口。开始边界取本地日期所在年份的 1 月 1 日；结束边界由每张表实时 `sycm catalog` 的完整可取上界决定。分日表不使用尚未完整的当天；分周表只使用目录允许的完整周。若平台可取下界晚于年度开始边界，使用两者交集并披露。

对每张目标表依次执行：

1. 运行精确维度的 `tbcli sycm catalog ... --date-type <day|week> --json`，验证维度、时间粒度、字段、筛选项和实时可取区间。
2. 用明确的年度开始与实时结束运行：

   ```bash
   tbcli db coverage --dataset '<业务表>' \
     --start-date '<YYYY-01-01>' --end-date '<实时完整上界>' --json
   ```

3. `complete: true` 时跳过该表。否则只取 `missingPeriods`，不得把往年差异带入本轮。
4. 为每个连续缺失区间在日常模块 run-start 返回的 artifactDir 内选择新路径，包含业务表、开始、结束和尝试编号。先检查路径不存在；需要项目数据子目录时，按运行记录协议统一设置 state-dir，不同时使用两套路径规则。
5. 运行一条明确的 `tbcli sycm fetch`：固定平台、粒度、维度、时间粒度、全部字段、该表维护默认设置、缺失区间和新输出路径。不要使用 `--all-history`。商品-整体必须使用 `--device overall --filter '商品状态=Y,N'`（若实时全集变化则替换为实时全集）；商品-SKU同理使用 `--device overall` 和全部实时 SKU筛选值；商品-流量来源必须精确使用 `--data-dimension '流量来源' --filter '转化效果归属=nearest'`，不传 `--item-ids`、`--device`、支付金额筛选和访客数筛选；商品-流量来源详情必须精确使用 `--data-dimension '流量来源详情' --filter '搜索来源=<实时全集>' --filter '转化效果归属=nearest'`，不传 `--item-ids` 或 `--device`；商品-整体退款分布和商品-退款SKU分布使用各自精确维度与 `--fields all`，不传 `--item-ids`、`--filter` 或 `--device`；商品-退款原因分布和商品-流失竞店分布使用上文各自的全部枚举筛选，不传 `--item-ids` 或 `--device`；所有已登记无界基础报表固定使用 `--filter '转化周期=15天转化' --fields all`，不传 `--device`。
6. 验证 Excel、目标身份、请求区间、实际数据区间和临时报表清理结果。
7. 入库前再次查询同一缺失分片的覆盖；若已完整则跳过写入；若部分被其他写入覆盖，停止该分片并重新规划剩余缺口。只有仍完全缺失才用同一个声明区间原子替换入库：

   ```bash
   tbcli db import --input '<新Excel>' --dataset '<业务表>' \
     --mode replace-range --start-date '<开始>' --end-date '<结束>' --json
   ```

   `replace-range` 是调用者明确选择的技术写入方式：它允许安全重跑同一区间，也能记录即使边界日没有明细行仍已完成取数。不要用 `append` 写入可能与现有日期重叠的文件。
8. 对同一区间再次运行 `db coverage`。只有 `complete: true` 且入库结果、行数、字段和范围一致时才完成该表。
9. 返回清单主线处理下一表。单表失败时保留已完成表和已下载的新文件，报告失败表与阶段，不重新下载已经验证成功的表。

## 全量重建流程

1. 只处理用户点名的数据表；遍历全清单需要用户明确要求。
2. 用 `sycm catalog` 确认实时全历史区间和当前字段/筛选契约。
3. 通常用 `sycm fetch ... --all-history` 下载到新文件，不覆盖旧文件。商品-流量来源和商品-流量来源详情固定按 14 天分片；商品-整体退款分布、商品-退款原因分布、商品-流失竞店分布和商品-退款SKU分布固定按 90 天分片；无界-关键词固定按最长 30 天分片。四张退款相关表的规范文件名分别使用 `商品-整体退款分布-分日-全部商品-<开始>-<结束>.xlsx`、`商品-退款原因分布-分日-全部商品-全部时间类型-全部退款场景-全部退款时间-<开始>-<结束>.xlsx`、`商品-流失竞店分布-分日-全部商品-全部时间类型-全部退款场景-全部退款后状态-<开始>-<结束>.xlsx`、`商品-退款SKU分布-分日-全部商品-<开始>-<结束>.xlsx`。所有无界基础报表规范文件名为 `无界-<维度>-分日-15天转化-<开始>至<结束>.xlsx`；除关键词外先按目录完整区间单文件取数，通过完整性验证即可入库，触及截断条件时再二分。每段执行一条显式日期 `sycm fetch`；任何触及 100,000 行上限或有截断迹象的区间继续二分。
4. 验证完整 Excel 后，使用目录返回的实际完整区间执行：

   ```bash
   tbcli db import --input '<新Excel>' --dataset '<业务表>' \
     --mode replace-all --start-date '<完整开始>' --end-date '<完整结束>' --json
   ```

   上述分片表首次入库或分片重建时，对每个已验证分片使用相同声明区间的 `--mode replace-range`，按日期升序执行；不得导入单次全历史或任何触及 100,000 行上限的文件。每片是独立事务且可安全重跑，最后必须对目录完整区间运行一次 `db coverage`。
5. 单文件表的 `replace-all` 在一个事务内重建该数据集；失败必须回滚并保留旧数据。分片表要披露其事务边界是“每个分片”，中途失败时从失败分片继续，不重复下载或重写已验证分片。完成后运行 `db datasets`、`db fields` 和全区间 `db coverage` 复核。

## 元命令边界与失败处理

- Agent/Skill 决定目标表、近期边界、缺失区间、执行顺序、重试范围和是否全量重建。
- 每张表的维护默认设置是其仓库字段契约。普通取数的用户参数不得悄悄覆盖维护默认；用户明确要求改变维护字段或终端结构时，停止增量并把它作为一次新的全量重建决策。
- CLI 只负责参数校验、登录与风控停止、官方取数、文件验证、事务、覆盖计算、模式执行和结构化回执。
- `append` 仅用于调用者已证明与现有日期完全不重叠的新数据；CLI 遇到日期重叠必须拒绝。
- `replace-range` 必须同时给出开始和结束日期，一次只接收一个明确文件；Excel 数据不得越出声明区间。
- `replace-all` 一次只接收一个明确文件。平台字段结构变化时，先报告差异，只有用户明确要求全量重建后才能使用。
- 不通过原始 SQL、`psql` 或临时脚本绕过这些契约。