fix(views): window "Closing This Quarter" to deals that close this quarter (#743)

[yinlianghui]

Fixes #743

前提复核：成立，且区间可表达

派单要求先证伪再实现。两半都复核了，都成立：

缺陷本身在 origin/main 上确实存在（src/views/opportunity.view.ts:236）：closing_this_quarter 的 filter 只有 forecast_category in [commit, best_case] 和 stage not_in [closed_won, closed_lost]，对 close_date 没有任何条件。四个语言包（metadata "Closing This Quarter" / zh-CN 本季度待成交商机 / es-ES Cierres de Este Trimestre / ja-JP 今四半期にクローズ予定）都在承诺这个时间范围。test/forecast-current-quarter-view.test.ts:109 的 KNOWN_DEBT 例外和它的自过期断言也都在原处。

区间在 17.0.0-rc.2 上可以表达 —— 这是不能靠推断的那一半，所以是跑出来的。宏词表在 @objectstack/spec/src/data/date-macros.zod.ts 的 DATE_MACRO_PERIOD_TOKENS 里，current_quarter_end 和 current_quarter_start 并列存在；解析实现在 @objectstack/core 的 resolvePeriodToken，*_end 走 next period start 减一天。在 pinned 17.0.0-rc.2 上实测：

quarter window: 2026-07-01 .. 2026-09-30
all rows:                    5  ["2026-07-01","2026-09-30","2026-10-01","2027-03-15","2025-05-20"]
$gte {current_quarter_start} + $lte {current_quarter_end}
                          -> 2  ["first-day-of-quarter=2026-07-01","last-day-of-quarter=2026-09-30"]
$gte {current_quarter_start} + $lt  {next_quarter_start}
                          -> 2  （同一结果集）
$gte {current_quarter_start} 单边
                          -> 4  （2026-10-01 / 2027-03-15 都漏进来）
{this_quarter_start}      -> throws: Unresolvable filter placeholder

所以不需要 needs_decision，也没有把算出来的日期冻进 metadata。

改了什么

src/views/opportunity.view.ts

• filter 增加两条 close_date 边界。算子用规范拼写 greater_than_or_equal / less_than_or_equal——不是 issue 正文里建议的 greater_or_equal / less_or_equal。后者在 VIEW_FILTER_OPERATOR_ALIASES 里，parse 时会被折叠成规范形式，所以运行起来一样，但源码就偏离了 VIEW_FILTER_OPERATORS 这唯一的 authoring 词表。测试里对拼写做了结构钉。
• 上界取闭区间 <= {current_quarter_end}，而不是半开的 < {next_quarter_start}。这是刻意选的，理由写进了注释：*_end 是周期的最后一个日历日，spec 明确警告在 datetime 列上它会停在午夜——但 close_date 是 Field.date()，两侧都是 YYYY-MM-DD TEXT，闭区间是精确的。这正是 metadata-references.test.ts 里「dashboard 只能 window date 字段」那条规则（Service dashboard renders empty by default — dateRange defaults to last_30_days but seed cases are older #460）依据的同一个字段类型性质。两种写法实测同一结果集，闭区间读起来就是它的字面意思。
• 新增 emptyState。这是本 PR 唯一的用户可见副作用，判断依据说清楚：和 fix(views): scope the "This Quarter" forecast view to the current quarter (#730) #745 那个不一样。forecast 视图是全新安装必然为空（窗口归扫描任务）；这里种子会产出行——查了 src/data/sales.seed.ts，六条商机在 forecast_category + stage 上合格，close_date 分别是 daysFromNow 的 11/14/24/30/38/45。但这些偏移都是相对安装日的，所以当季度剩余不足 11 天时六条全部落到下个季度，刚种子化的演示打开这个 tab 就是空的；真实组织在本季度承诺滑出时同样会遇到。空是合法状态，不解释就像坏了。

四个语言包 —— label 一个字没改（它们本来就是对的，说谎的是 filter），只加 emptyState 的 title/message。en.ts 里 closing_this_quarter 原本就没有条目（和 stale_opportunities 一样，英文名走 metadata label），所以只补 emptyState、不补 label，并把这个取舍写在注释里。

测试

test/forecast-current-quarter-view.test.ts

• KNOWN_DEBT 例外行删除。map 本身保留（留空）并改写 docblock —— 下一个同类缺陷需要一个不会腐烂的记录位置。
• 新增第二个运行时块，按 fix(views): scope the "This Quarter" forecast view to the current quarter (#730) #745 的三选一钉法钉区间这一形态：0 行 = 宏没解析、全部行 = 没限定、只有本季度 = 契约。区间比等值多一种腐烂方式，所以额外加了逐边界减法（只去掉上界 → 明年的单子漏进来；只去掉下界 → 去年的漏进来），以及季度首日和末日两条边界行，防止闭区间哪天悄悄变成开区间。
• fixture 里放了两条「在窗口内但被另外两个条件排除」的行（pipeline 类别、closed_won），这样日期区间不会被记在整个结果集的功劳上。
• whereFromViewFilter translator 原本对非 equals 直接抛异常（刻意如此：静默丢条件会把红测试变绿）。现在实现了比较算子，并且同字段两条规则合并成一个比较对象；标量等值和区间撞在同一字段上仍然抛异常，因为那必然要丢掉一条。

反向验证（方向事先预判，两个都跑了，都命中）

预判红 —— 删掉两条 range 条件（即恢复 main 的 filter）→ 5 条转红，且各自点名真实原因：

× every current-period label is backed by a filter that pins that period
    crm_opportunity.closing_this_quarter is labelled metadata:"Closing This Quarter",
    zh-CN:"本季度待成交商机", ja-JP:"今四半期にクローズ予定",
    es-ES:"Cierres de Este Trimestre" but its filter carries no
    {current_quarter_start} … (filter tokens: none)
× the shipped filter carries both bounds, in the canonical operator spelling
× selects this quarter only — expected [ 'closes-the-quarter', …(5) ] to deeply equal …(2)
× both quarter boundary days are INSIDE the window — expected […] to not include '2026-10-01'
× dropping EITHER bound alone widens the window — expected […] to not include '2025-05-20'
      Tests  5 failed | 12 passed (17)

预判绿 —— 同一次运行里 every KNOWN_DEBT exemption is still needed 保持绿，因为 map 已清空，没有例外可以过期。这条不是疏漏，是这个断言的语义。

第二个反向验证（自过期断言本身）：在修好的 filter 之上把 KNOWN_DEBT 条目加回去 → 正好这一条转红，措辞就是 issue 承诺的那句：

× every KNOWN_DEBT exemption is still needed
AssertionError: these views no longer breach the rule — delete their KNOWN_DEBT
entries so the guard covers them again:
  crm_opportunity.closing_this_quarter (#743)
      Tests  1 failed | 16 passed (17)

docblock 里「它在修好那天转红、直到删掉这行」这句话因此是实测的，不是转述的。

验证

pnpm validate   ✓ Validation passed (1008ms)
pnpm typecheck  ✓ (tsc --noEmit，无输出)
pnpm hygiene    ✓ source hygiene clean
pnpm build      ✓ Build complete (1075ms)
pnpm lint       13 warning(s), 14 suggestion(s)  —— 与 main 同量，无新增项
pnpm test       Test Files 62 passed (62)
                Tests 1473 passed | 1 skipped (1474)

平台依赖未动，仍锁在 @objectstack/* 17.0.0-rc.2；没有任何绕行实现或冻结日期，用的就是平台自己的宏词表。

越界的部分：没改

• src/views/opportunity.view.ts:219-221（stale_opportunities 的注释）仍然写着「the list data path resolves no date macros」 —— 这是 Two source comments still assert the list-view path resolves no date macro — one of them tells the next author not to generalise #744 那一类过期注释的第三处，而且和本 PR 在同一个文件里、在我改的 filter 上方十几行，读起来是直接自相矛盾的。没有在这里顺手改，也没有另开 issue（那会和 Two source comments still assert the list-view path resolves no date macro — one of them tells the next author not to generalise #744 撞成孪生），而是把这处补充到了 Two source comments still assert the list-view path resolves no date macro — one of them tells the next author not to generalise #744 的评论里，让三处在同一次修正中保持一致口径。它不影响 stale_opportunities 的形态：那条注释还给了第二个独立且仍然成立的理由（days_in_stage 是公式字段，引擎查询后才算）。
• content/docs/sales/opportunities.mdx:117 用第三个名字（"Pipeline This Quarter"）称呼这个视图、并列出仓库里并不存在的视图名 —— issue 正文已记录，属于 forecasting.zh-Hans/zh-Hant 相对英文页存在早于 #627 的整页漂移 —— 桶语义、承诺定义、缺失的汇总提示框需要整页重译 #736/content/docs/sales/activities.mdx 与事件模型对账：把「活动 = Task 记录」讲窄了，并承诺了 crm_opportunity 上并不存在的 last activity date 字段 #739 同轮在飞的文档面，本 PR 一行未动。

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hotcrm	Ignored		Aug 5, 2026 5:19pm