[CRM] 矩阵报表日期粒度缺失：v9 迁移遗漏属实，但补齐阻塞于 16.1 两处平台缺口（17.0 已修，二次改判）

[yinlianghui]

现象

矩阵报表的日期列不按预期粒度分桶：

• lead_inflow_by_month_source（预期按月）与 pipeline_coverage_by_quarter（预期按季）：每个原始日期一列
• cases_opened_by_day_priority：粒度正确但列序乱（07-01, 07-05, …, 07-02, …），且出现一个「—」列

根因（已用 17.0.0-rc.0 平台源码核实，改判为主要是 CRM 侧问题）

1. 粒度丢失 = CRM 侧迁移遗漏（本 issue 的主修项）
平台的粒度门禁在 16.1 与 17.0 逐字相同（service-analytics/dataset-executor.ts 的 granularityFor：数据集维度未声明 dateGranularity 且 selection 未传粒度 ⇒ 按原始时间戳分组）。HotCRM 在 v9 单形态迁移（commit a67f1e77）删除了 groupingsAcross[].dateGranularity: 'month' 与 sortOrder: 'asc'，之后一直没有迁到新位置。修法：

// src/datasets/lead.dataset.ts 等 6 处日期维度
{ name: 'last_contacted_date', ..., type: 'date', dateGranularity: 'month' }

注意维度是共享的：若同一维度别处需要原始日期，应另加专用维度（同 field、不同 name + dateGranularity）。src/reports/opportunity.report.ts:34 的注释（"the dataset's dateGranularity buckets it into quarters"）与代码已脱节，一并修正。

2. 「—」列 = 平台 17.0 有意 breaking change（#3839：空分组桶键从 '(null)' 改为真 null）。数据侧处理 last_contacted_date 为空的记录（或 runtimeFilter 排除）。

3. 日期列乱序 = 平台真实缺口（服务端无隐式排序、聚合 SQL 无 ORDER BY、pivot 按到达序建列头、report schema 未给作者提供排序声明）——已另行反馈平台，见后续评论中的交叉链接。补上 dateGranularity 只让键可排序，不会自动排序。

原「[17.0-rc][疑似平台]」标题保留在历史里；本 issue 现改为跟踪 CRM 侧的 dateGranularity 迁移补齐。

[yinlianghui]

补充平台侧交叉引用：列乱序缺口已上报 objectstack-ai/objectstack#3916（服务端无隐式排序 + report schema 无排序声明字段）；「—」空列是 17.0 有意 breaking（objectstack#3839，空桶键 '(null)' → 真 null）。本 issue 保留跟踪 CRM 侧 dateGranularity 补齐（6 个日期维度）。

[yinlianghui]

📎 分支 upgrade/objectstack-17 已推送至上游（仅分支，无 PR，勿合并——阻塞于 17.0 正式版与 objectstack#3912/#3913/#3914）。正文引用的文档现在可直接访问：测试报告 ｜ 测试计划

[yinlianghui]

🎯 施工说明（2026-07-30）：在 main 上修，不要用升级分支

上面那条"分支 upgrade/objectstack-17 已推送"的评论只是提供测试报告链接，不是让本 issue 在该分支上修。本 issue 已改判为 CRM 侧问题，且正文已核实粒度门禁在 16.1 与 17.0 逐字相同，所以：

• 基于 main 切分支，走正常 PR 审核合并；
• 升级分支之后 merge main 会自动吸收本修复，不需要在那边重复改。

当前 main 上的状态（已核实）

src/datasets/ 下 9 个数据集文件中，只有 account.dataset.ts 和 opportunity.dataset.ts 各有 1 处 dateGranularity，其余日期维度均未声明，符合正文描述的"v9 迁移遗漏"。

提醒

• 正文已指出：维度是共享的，若同一维度别处需要原始日期，应新增专用维度而不是改动现有维度的粒度。
• 请补一条守卫测试，防止再次遗漏；放在独立的新文件（例如 test/dataset-granularity.test.ts），不要追加到 test/metadata-references.test.ts —— 那是当前多个并行改动的冲突热点。
• 本仓库 CI 要求每个 PR 新增一个 changeset（.changeset/*.md），否则 Check Changeset 会红。

完成后

本 issue 可以关闭。

[yinlianghui]

施工反馈：改判需要再修正一次 —— 16.1 上「加 dateGranularity」不是分桶，而是清空报表

PR #558（draft，基于 main）。先说结论，再给证据。

正文里的一处误读

src/datasets/ 下 9 个数据集文件中，只有 account.dataset.ts 和 opportunity.dataset.ts 各有 1 处 dateGranularity

这两处不是声明，是注释——#500（d0aa956，2026-07-29）留下的「不要声明」说明。所以 main 上实际是 0 处声明，「v9 迁移遗漏」的判断成立；但 #500 当时不敢声明是有原因的，而那个原因与正文核实的 granularityFor 门禁是两条不同的代码路径。

两个 16.1 缺口（都已实测，都只在 17.0.0-rc.0 修好）

① 读作用域被丢掉 → 私有对象直接 deny-all。
维度一旦带粒度，NativeSQLStrategy.canHandle 就拒收（query.timeDimensions?.some(td => !!td.granularity) → false），查询落到 ObjectQLStrategy → auto-bridged executeAggregate，而 16.1 的桥调用 engine.aggregate() 不传 context。plugin-sharing 的中间件（op === 'aggregate' 同样走 buildReadFilter）拿到空 principal，对每个 sharingModel: 'private' 对象组合出 { id: '__deny_all__' } —— 我们的对象全是 private。

实测（启动真实 kernel：sqlite-wasm + ObjectQL + sharing + analytics，queryDataset 传真实 context）：

raw date dim            | rows=21 | keys=["2026-04-06","2026-05-18","2026-02-06", …]
dateGranularity: month  | rows=0  | keys=[]

引擎层单独验证（同一 kernel，直接 engine.aggregate('crm_lead', {groupBy:[{field:'last_contacted_date',dateGranularity:'month'}], …})）：

context = { isSystem: true }   → rows=1
context = { userId: 'u1' }     → rows=0
context = undefined（桥的实际行为）→ rows=0

17.0.0-rc.0 已修（两道保险）：桥多了 context，注释直接写明 #3602 / #3597 — 「an authenticated aggregate reached the engine with no principal and plugin-security fell open」；ObjectQLStrategy 自己也补了 withReadScope。CLI 侧确认无解：serve.js 的 CAPABILITY_PROVIDERS 只用 new AnalyticsServicePlugin({ cubes }) 构造，没有可注入的 executeAggregate，而且 strategy 本身也不把 context 传给 executeAggregate，所以 app 侧无法绕过。

② Field.datetime() 在 SQLite 上分桶必为 NULL。
16.1 的 driver-sql 用裸 strftime('%Y-%m', col)，而 Field.datetime() 落库是 INTEGER epoch 毫秒：

-- crm_case.created_date
typeof=integer  v=1785283200000  strftime('%Y-%m-%d', v) → null
-- crm_lead.last_contacted_date
typeof=integer  v=1785196800000  strftime('%Y-%m', v)    → null
-- crm_opportunity.close_date（Field.date → TEXT）
typeof=text     v='2026-01-12'   strftime('%Y-%m', v)    → '2026-01'  ✅

带 isSystem 绕过缺口 ① 后逐个维度实测：

维度	字段类型	分桶结果
opportunity_metrics.close_date	Field.date	✅ 2026-Q1 … 2027-Q1（5 桶）
forecast_metrics.period_start	Field.date	✅ 2026-Q2 / 2026-Q3
task_metrics.due_date	Field.date	✅ 逐日
lead_metrics.last_contacted_date	Field.datetime	❌ 单个 null 桶
case_metrics.created_date	Field.datetime	❌ 单个 null 桶

17.0 的 driver-sql 加了 sqliteTemporalArg()（epoch → julian day 再 strftime），并明确写了为什么不能直接 /1000.0。

所以：在 16.1 上按正文字面补齐，三张矩阵报表会从「分桶错」变成「无数据」；close_date 是共享维度，还会顺带清空 Sales / CRM / Executive 三块营收趋势图。

本 PR 落地的内容（按「长远稳定 + 最终必须修好」取舍）

1. 守卫测试 test/dataset-granularity.test.ts（独立新文件，未碰 metadata-references.test.ts）——迁移意图以表格形式落在代码里：每个日期维度、每张矩阵报表轴该用哪个桶，含 pipeline_coverage_by_quarter 需要的专用 quarter 维度（close_date 与趋势图共享且要 month，正文的「共享维度」规则在这里生效）。它在 16.x 上禁止任何声明（防 Executive dashboard carries inert widget config and hardcoded trend percentages #500 回归），并在依赖 major 跨到 17 的瞬间翻面为强制声明——升级分支不补完迁移，CI 就是红的。两个方向都已把依赖临时改成 17.0.0-rc.0 验证过。
2. — 空列：这一条 16.1 上就能修，已修。lead_inflow_by_month_source / cases_opened_by_day_priority 过滤掉无日期记录（Lead 报表 21 组 → 20 组，null 桶消失）。
3. 注释纠偏：opportunity.report.ts:32 的 "the dataset's dateGranularity buckets it into quarters" 描述的是不存在的声明；lead.report.ts / case.report.ts 的 "Exercises the dateGranularity path" 同样失真。数据集里的说明也从一行猜测换成了核实过的机制。

仍然开着的两条（确认非 CRM 侧）

• 列乱序 → objectstack#3916。另外确认：16.1 的 ReportSchema 里根本没有 order / sort 字段（AnalyticsQuerySchema 有 order，但作者层的 report 拿不到），所以补 dateGranularity 只让键可排序，作者仍无法表达排序。
• 非空值造成的 — → objectstack#3839。

建议

本 issue 先别关：main 上这版把迁移钉住了，但真正生效在 17.0 升级那一刻（届时按守卫的报错做三件事：填 INTENDED_BUCKET、加 close_quarter、把 pipeline_coverage_by_quarter 指过去）。如果你更希望现在就按字面把 dateGranularity 声明进去、接受这三张报表（和三块趋势图）在 17.0 落地前为空，我可以直接改成那样 —— 一句话的事。

---

Generated by Claude Code