forecast_derive_period：手填 period_start 时 period_end 按「起点 + 3 个月」推导，可越出它自己标注的季度

[yinlianghui]

来源：#748（文档措辞单）实施过程中，为核实「手填 period_start 的真实行为」而实测出来的行为面问题。#748 只改文档措辞、不动契约（其 option 3 明确留给维护者拍板），故行为疑点单独记录，不在那条 PR 里顺手修。

现象（实测）

src/objects/forecast.hook.ts 在 period_start 由调用方给出时原样保留它（这是 #748 已确认、且现在文档已按实描述的部分），但接着用 endOfQuarter(start) = Date.UTC(y, m + 3, 0) 推 period_end —— 这是「起点往后数 3 个月」的滚动窗口，不是「该起点所属日历季度的最后一天」。于是同一个 period_label 下窗口长度对，位置却随手填值漂移：

手填 period_start	推出的 period_end	推出的 period_label
2026-07-15	2026-09-30	Q3 2026
2026-08-15	2026-10-31	Q3 2026
2026-09-20	2026-11-30	Q3 2026

后两行标着 Q3，窗口却伸进了 Q4。period = month 时同类：起点 2026-08-17 推出 period_end = 2026-08-31，窗口只剩半个月。

实测方式：把上表三个值送进 forecast_derive_period 的真实 handler（test/helpers/hook-harness.ts 的 makeCtx，beforeInsert），读回 input。

为什么标 finding 而不是缺陷

和 #748 一样，今天没有用户会踩到：src/ 里没有任何写入方送手填的 period_start（forecast-snapshot.flow.ts 的 create_forecast 只送 period；src/data/revenue.seed.ts 全部用 Date.UTC(y, m, 1) 算日历真值）。属于「已声明但未被行使」的路径。

不过有两点让它比 #748 的纯措辞面更值得看一眼：

1. 入口是敞开的。 period_start 是 required + notNull，并且出现在记录表单的 Snapshot 区块（src/views/forecast.view.ts:127）。source: 'manual'（经理手工录入）正是文档写明的三种来源之一，走的就是这个表单。
2. 二级后果（未实测，只是从元数据推出的）： 夜间 sweep 用 period_start <= today <= period_end 选「当前季度那一行」（src/flows/forecast-snapshot.flow.ts 的 CURRENT_PERIOD_FILTER）。一条手工建的、窗口恰好罩住今天的行会满足这个条件，于是 sweep 可能把它当成本季度行去 write_snapshot（覆盖四个金额、把 source 改成 scheduled），并因此认为本季度行已存在而不再开日历真值的那一行。

可选修法（供 triage 参考，不建议由文档单顺手带）

1. period_end 改为按 period_label 所属的日历周期算（即先 startOfPeriod(period, start) 再 endOfQuarter）—— 窗口回到日历真值，但 period_start 仍是手填值，行内自相矛盾只是换了个位置；
2. 手填的 period_start 一并吸附到日历边界（forecasting.mdx 的「boundary is always computed, never typed」措辞，对手填 period_start 的情形是过度承诺 #748 的 option 3）—— 改契约，会让「给某个特定季度拍快照」以外的用法失去表达能力；
3. 拒绝而不是接受：period_start 不是所属周期第一天时报校验错。对 AI 写元数据/写记录的场景，这是「声明即强制」方向上最不容易出错的一种，但同样是契约变更。

三者都动 crm_forecast 的写入契约，需维护者拍板。严重度请 PM 在 triage 轮判定。

Refs #748 #530 #590

[huangyiirene]

Ruling (maintainer, 2026-08-11, PM chat, verbatim: 「接受你的全部建议」): Option 3 — a hand-filled period_start that is not a calendar-period boundary is a validation error. Of the three options this is the only one that makes the invalid state structurally unwritable (declared = enforced); measurement shows no writer sends a hand-filled period_start today, so tightening has zero stock cost. The secondary risk noted in the body (nightly sweep's CURRENT_PERIOD_FILTER overwriting manual rows) should be verified in passing and filed separately if real.

Queued (S–M).

---

Generated by Claude Code

[huangyiirene]

Claim: PM loop round 5

Session: session_01NM6o28jmBgsyTRQHutn7LC
Branch: claude/issue-1008-forecast-period-boundary
Worktree: hotcrm-issue-1008
File surface: src/objects/forecast.* (hook + object), test/ — plus src/flows/forecast-snapshot.flow.ts for the read-only secondary probe (stop on breach; explain in the report)
Container & model: S–M, but the judgment face is in the refusal contract rather than in the gates, so it does not take the sonnet floor: mode:subagent, model: opus
Serial constraints cleared: no in-flight claim touches src/objects/forecast.*; #1060 (this round) is package.json-scoped, #858 (this round) is src/translations/ja-JP.ts-scoped — all three disjoint.

Ruling already recorded above (Option 3 — a hand-filled period_start off a calendar-period boundary is a validation error); this dispatch implements it, it does not reopen it.

---

Generated by Claude Code

[huangyiirene]

{
  "issue": 1008,
  "status": "done",
  "branch": "claude/issue-1008-forecast-period-boundary",
  "pr": "https://github.com/objectstack-ai/hotcrm/pull/1081",
  "premise_still_valid": true,
  "summary": "Premise re-measured on origin/main (e6e43be4) and still true: the real forecast_derive_period handler turns period:'quarter' + period_start:2026-08-15 into period_end 2026-10-31 under period_label 'Q3 2026', and month + 2026-08-17 into a half-month window. Implemented the ruling's option 3 as TWO DECLARATIVE VALIDATION RULES on crm_forecast (period_start_first_of_period, quarter_starts_on_quarter_boundary) rather than a throw in the hook — the PM's mechanism assumption was tested and falsified in the app's favour: the declarative position exists, can express 'first day of its calendar period', and yields a better envelope; the hook's derivation is deliberately untouched, since with the start pinned to a boundary 'start + one period' already IS the calendar period. Zero stock cost re-verified (no writer in src/ sends a hand-filled period_start; the flow sends only `period`, every seed row is Date.UTC(y,m,1)) and now pinned by tests. Refusal envelope measured, not assumed: ValidationError / code VALIDATION_FAILED / status UNDEFINED — the tests assert name+code+message and pin status as undefined, and deliberately assert no status VALUE, since this repo produces none (#1075 owns unifying that). One thing I did NOT do and want on the record: the constraint is not stated in period_start's field description, because test/i18n-references.test.ts demands a `help` entry in every locale for any field with a description — including ja-JP.ts, which this card fenced off (#858). Worth a follow-up after #858 lands.",
  "tests": "npx vitest run (full suite, --maxWorkers=2): 'Test Files 87 passed (87) / Tests 2115 passed | 1 skipped (2116)'. New test/forecast-period-boundary.test.ts alone: 29 passed. pnpm validate: exit 0, '✓ Validation passed (1147ms)' (the ⚠ page/view lines are pre-existing and untouched). pnpm typecheck: clean, exit 0. pnpm lint: exit 0 ('153 warning(s), 10 suggestion(s)', all pre-existing). pnpm hygiene: '✓ no raw control bytes in first-party files / ✓ source hygiene clean'. Self-scan grep -naP '[\\x00-\\x08\\x0b\\x0c\\x0e-\\x1f\\x7f]' over all four changed files: no hits. REVERSE VERIFICATION, direction predicted in advance and confirmed: with the two rules removed (git checkout origin/main -- forecast.object.ts, never git stash) the new suite went 13 failed / 16 passed, and every refusal case failed with 'the write was ADMITTED — no refusal to inspect' while ALL positive/admission cases stayed green — an over-firing rule would have reddened the positives instead. Note the restore step: `git checkout <branch> -- file` restored from the branch TIP, which was still origin/main at that point, so it discarded the edit; caught it immediately via grep and re-applied, then re-ran everything green. Local scope was the affected suites plus the full app suite (single-package repo); gate names were read out of package.json scripts at the time, not from memory. CI not waited on, per the report-at-draft-PR-time contract.",
  "open_questions": [],
  "out_of_scope_findings": [
    "filed as #1082: forecast_snapshot's CURRENT_PERIOD_FILTER claims the current-quarter row by window containment (period_start <= today <= period_end), never by `source`, so a manager's manual current-quarter row is treated as the sweep's own — its four amounts are overwritten, snapshot_date restamped and source flipped manual→scheduled, while quota survives (making the loss partial and easy to miss). Verified READ-ONLY per the card's boundary; NOT driven end-to-end through a flow run, and said so in the issue. This SURVIVES #1008: the fix removes the drifting-window variant, but a boundary-correct manual row lands on exactly the window the sweep looks for, so the two become indistinguishable by construction. Filed unassigned with the `finding` label, no pm:queue, standalone (not a sub-issue), backlinked to #1008/#1081/#702/#590; dedupe search over open+closed issues first turned up only #702/#613/#590/#614/#530, none of which is this."
  ]
}

---

Generated by Claude Code