Track A · crm_opportunity: the qualification group, milestone dates, subcontracting, narrative, and approval on STATUS CHANGE — REQ-0006

[os-elon-musk]

Part of #1904 — Track A 实现批，REQ-0002 前 14 步的销售侧增强。⛔ 不依赖上游发版，与 #1907 的拆包线并行。

权威规格

docs/requirements/0006-opportunity-qualification-and-status-approval.md（已在 origin/main，PR #1912 合入 6ff28e7）。

⚠️ 该记录是本卡的唯一规格来源。⛔ 本卡不重抄它的内容、⛔ 不重新裁定它的 B/C 划分。动手前把它整篇读完，包括 Standard product analysis、Disposition & rationale、Product response 与 Acceptance 四节。

其中 C（客户定制层） 项一律 ⛔ 不做 —— 它们不属于标准产品，记录里逐条写明了理由。

串行约束 ⚠️

Track A 的四张实现卡文件面相交：都要动 src/sales/objects/ 与四个语言包 src/sales/translations/{en,zh-CN,es-ES,ja-JP}/。

⇒ 硬串行，一次只有一张在飞。 本卡落地后 PM 才派下一张。⛔ 不要并行开工、⛔ 不要顺手改别的对象。

文件面

⚠️ 本节由 PM 在派发前照 origin/main（661d2fa）重量过一遍，原稿的语言包路径是错的、漏了视图。以本节为准。

• src/sales/objects/opportunity.object.ts —— qualification 组、客户侧里程碑日期、分包、叙述组、业务线分类
• src/sales/flows/opportunity-approval.flow.ts —— 两道闸都是 flow 里的 approval 节点。⚠️ 验收第 4 条点名了这个文件 docstring 里记录过的一次实测失败（无 session 的写入者开闸），动手前读它。
• src/sales/views/opportunity.view.ts —— 验收第 2 条要求客户侧日期独立于 close_date 可报，「本季度预计招标的单子」要能在列表视图里拉出来。原稿漏了这一项。
• src/sales/translations/{en,zh-CN,es-ES,ja-JP}/objects.pipeline.ts —— ⚠️ 不是 translations/<locale>.ts。语言包按「翻译命名空间 → CRM 域族」两级拆分（The 70% advisory band's first real output: es-ES.ts (75.3%) and ja-JP.ts (73.4%) are the only two files it names, and a third sits 224 bytes below it #1311），crm_opportunity 属 pipeline 族（与 crm_lead 同文件）。四个语言同笔。

⚠️ 本卡排在 #1915 之后，同一个文件上已有它的改动

#1915 会在 opportunity.object.ts 上落一个 validations[] 条目（客户类别的能力闸，REQ-0003 第 128 行钉死的落点）。

⇒ 开工前 merge-forward，⛔ 不要回退或重写那个条目。它不是本卡的，本卡只往这个文件里加自己的字段与分组。

⛔ 验收第 5 条是一条否定要求

「Signing entity and revenue-recognition type have no field in core at all」—— 签约主体与收入确认类型 ⛔ 一个字段都不许加，业务线分类只发通用值。客户自己的业务线清单、主体清单和铁三角角色全部来自 overlay。⛔ 不要"顺手帮忙"补上它们。

⚠️ 记录明写两条：每个字段以 group: '<key>' 入组，表单布局保持派生，⛔ 不手写布局；业务线分类另立 select，⛔ 不替换也不重载现有的 type。
⚠️ 今天只有金额分级审批（src/sales/flows/opportunity-approval.flow.ts）；本卡要的是状态变更本身的审批。

⛔ 不碰其它销售对象、⛔ 不碰 src/service/、src/revenue/、src/marketing/、⛔ 不碰 content/docs/releases/。

验收

以 docs/requirements/0006-opportunity-qualification-and-status-approval.md 的 Acceptance 节为准，⛔ 本卡不另立标准。另加两条通用项：

1. pnpm verify 绿（package.json 是权威，⛔ 不自行窄化）。退出码在任何管道之前写进文件再读。
   ⚠️ 记录的验收第 6 条点名 test/object-validation-predicates.test.ts —— 未加 has() 守卫的谓词直接判红。⛔ 不要动这道守卫。
   ⚠️ test/docs-declared-versions.test.ts 会因字段数变化转红。在源头修：重抄你自己分支的 validate 摘要进 docs/STATUS.md，⛔ 不要动那道守卫（feat(objects): a buying-centre map on crm_contact — buying function, attitude, relationship strength (REQ-0004) #1917 的先例）。
2. changeset：记录的验收第 6 条写的是「a changeset per PR, each naming REQ-0006」。本卡若一个 PR 交付就是一条；若你判断必须拆成多个 PR，每个 PR 各带一条，且都点名 REQ-0006。级别自判并在 PR 正文说明理由。

⛔ 顺手陷阱

你会在语言包 docblock 与对象文件注释里看到 src/translations/…、src/flows/… 这类已经不存在的路径（ADR-0130 搬迁的欠账）。⛔ 不要在本卡里顺手改 —— 文档半边是 #1918，源码半边是 #1919（正因与 Track A 直撞而挂 pm:blocked）。改了就是扩面。

---

Generated by Claude Code

[os-elon-musk]

PM 改挂 pm:blocked。解锁判据：#1928 的天花板裁决。

⛔ 不派本卡，理由是实测而非谨慎：

#1915 的施工席先量再写，量到本卡的同胞需要 ~1,458 个 business-semantics token，而余量只有 ~621 ⇒ 超出 ~837。其中审批流程单独就 ~886（同胞 lead-conversion-approval.flow.ts 实测 ~926）。

本卡的字段比 #1915 更多（qualification 组、客户侧里程碑日期、分包、叙述组、业务线分类）⇒ 撞的是同一堵墙，而且撞得更狠。

现在派下去的唯一结果，是再烧一席去拿一个我已经知道的答案。

⚠️ 解锁之后本卡还要先重量一遍 —— 届时的余量取决于 #1928 怎么裁、以及 #1915 最终以什么形态落地。⛔ 不要照抄本评论里的数字。

---

Generated by Claude Code

[os-elon-musk]

Claim: PM 认领本卡，派发施工 —— Track A 第 4 环（最后一环）。

• 基线：origin/main = 087b7c5（含 feat(account): registration identifier, a capability gate, business profile and approval (REQ-0003) #1948 / feat(flows): notify nodes speak the recipient's own language #1949）。
• 前序：Track A · crm_account: registration identifier, a category that GATES capability, business profile, approval — REQ-0003 #1915 已落地（PR feat(account): registration identifier, a capability gate, business profile and approval (REQ-0003) #1948），Re-land the four-locale notify-node conversion under ADR-0130 — templates split per owner module, the test fence opened #1945 已落地（PR feat(flows): notify nodes speak the recipient's own language #1949）。

⚠️ 一处卡面更正：#1915 的落点变了，本卡的「不要碰」对象也变了

卡面第「本卡排在 #1915 之后」节写着：

#1915 会在 opportunity.object.ts 上落一个 validations[] 条目（客户类别的能力闸，REQ-0003 第 128 行钉死的落点）

这条已失效。 维护者 2026-09-16 裁定闸门改走 hook（理由：validations[] 对每次写求值，会弄砖历史商机，与 REQ-0003 自己的验收第 2 条冲突）。PM 在 087b7c5 上实测：

	实况
opportunity.object.ts 里的 validations	2 处，都是既有的，⛔ 不是 #1915 留的
能力闸实际在	src/sales/objects/opportunity.hook.ts — opportunity_account_capability，events: ['beforeInsert']，priority: 150

⇒ 本卡要避开的是 opportunity.hook.ts 里那个 hook，⛔ 不是 object 文件里的某个 validations[]。⛔ 不要回退、重写或"顺手统一"它。

⚠️ 二：本卡的闸门默认关，与 #1915 相反 —— ⛔ 不要照抄上一张

REQ-0006 验收第 3 条原文：

With the status-change gate switched on … ; with it off (the default), the existing amount-tiered behaviour of opportunity-approval.flow.ts is bit-for-bit what it is today.

而 #1915 的账户审批是默认开（REQ-0003 验收第 4 条明写 pending）。两张卡相邻、默认相反，各自的记录都写死了。 ⛔ 不要把上一张的 defaultValue: 'pending' 抄过来。

关法参考 lead-conversion-approval.flow.ts 的实测：开关是字段 defaultValue，⛔ 不是 flow 的 status（draft 照样触发；obsolete 会变成没人能再打开的闸）。

⚠️ 三：令牌余量很薄，两本账都要看

PM 在 087b7c5 上实测：

层	读数	余量
src/sales business semantics	54,179 / 55,000	821
src/sales authored total	99,340 / 100,000	660

⚠️ 本卡量级参照：#1914 吃 2,041，#1915 吃 1,906。本卡卡面自述字段数比 #1914 更多。

⇒ 几乎必然装不下。 这不是悲观，是把预期说在前面：

1. 骨架落下立刻量，⛔ 不要写完才量。
2. 装不下就立刻停，报 blocked 并给出 business semantics 与 authored total 各自的精确缺口 —— 这是一等交付物，⛔ 不是失败。PM 拿这两个数去开第二张天花板决策卡。
3. ⛔ 绝不抬天花板（[decision] Track A has ~621 tokens of business-semantics headroom left and two rings to go — raising the ceiling needs a maintainer ruling quoted in the raising PR #1928 已关，需要新的维护者裁决）、⛔ 绝不压无关散文、⛔ 绝不塞进不计量目录。

---

Generated by Claude Code

[os-elon-musk]

os-dev-report

{
  "issue": 1916,
  "status": "blocked",
  "branch": "claude/issue-1916-opportunity-qualification-status-approval",
  "pr": "https://github.com/objectstack-ai/hotcrm/pull/1950",
  "premise_still_valid": true,
  "blocker": "src/sales token ratchet — the complete REQ-0006 implementation costs ~2,055 tokens and only ~660 of authored-total headroom exists. Raising a ceiling needs a maintainer ruling (#1928 is closed), so this seat stops here.",
  "ratchet_gap": {
    "measured_on": "85e5dbd (branch head), baseline origin/main 087b7c5, node scripts/check-source-token-ratchet.mjs, exit 1",
    "business_semantics": {
      "baseline": 54179,
      "branch": 55986,
      "ceiling": 55000,
      "cost": 1807,
      "over_by": 986
    },
    "interaction_layer": {
      "baseline": 29477,
      "branch": 29725,
      "ceiling": 31000,
      "cost": 248,
      "over_by": 0,
      "headroom_left": 1275
    },
    "authored_total": {
      "baseline": 99340,
      "branch": 101395,
      "ceiling": 100000,
      "cost": 2055,
      "over_by": 1395
    },
    "gap_is_final": "Yes. Every remaining deliverable (four locale packs, content/docs page, changeset, tests, docs/STATUS.md) is outside the ratcheted surface by ruling or by path, so finishing the card moves neither number. The changeset and the docs/STATUS.md re-transcription are already on the branch and cost 0.",
    "cost_breakdown": "object fields + 2 fieldGroups = ~830 authored-total tokens (measured alone, already red: business semantics 55,010 over by 10, authored total 100,170 over by 170); the new flow file = 717; the hook transition gate + allow-list, the flows barrel line and the requested_status field make up the rest; the tender_this_quarter view = 248 (interaction layer, green).",
    "siblings": "#1914 spent ~2,041 and #1915 ~1,906 — this card is the same size, hit from 821/660 of headroom."
  },
  "summary": "Authored the complete REQ-0006 B-scope on a measurement branch and measured it, rather than estimating: 18 new crm_opportunity fields (qualification group, the customer-side procurement calendar, deal narrative group, business_line beside type, requested_status and status_change_approval_status), two new fieldGroups entries, a tender_this_quarter list view for acceptance 2, and opportunity-status-change-approval.flow.ts with a transition gate in opportunity.hook.ts for acceptance 3/4. The gate ships OFF via the field defaultValue (not the flow status), so amount-tiered approval is bit-for-bit unchanged. pnpm validate, typecheck and hygiene are all exit 0 and 312 of 314 targeted tests pass. The card is blocked on the src/sales token ratchet alone: business semantics over by ~986, authored total over by ~1,395. Nothing was compressed, no ceiling was raised, nothing was hidden in translations/ or data/. PM's corrected premises both held on 087b7c5: the #1915 capability gate is a hook (opportunity_account_capability, beforeInsert, priority 150) and was left untouched, and the two validations[] entries on opportunity.object.ts are pre-existing.",
  "tests": "pnpm validate -> exit 0 (redirect-then-capture, run under os-verify-lock, VERDICT command-exit 0); pnpm typecheck (tsc --noEmit) -> exit 0, VERDICT command-exit 0; pnpm hygiene -> exit 0 'source hygiene clean'. Targeted vitest (9 files, 314 tests) -> 'Test Files 2 failed | 7 passed (9) / Tests 2 failed | 312 passed (314)'. The two failures: source-token-ratchet.test.ts (the blocker itself) and docs-declared-versions.test.ts ('Fields: page says 343, the stack registers 361 / Flows: page says 31, the stack registers 32'), fixed at the source per #1917 by re-transcribing this branch's own validate summary into docs/STATUS.md; the guard was not touched. Green in that run and relevant to this diff: object-validation-predicates, flow-condition-totality, flow-registration-completeness, freeze-guard-reference-cleanup, audit-stamp-readonly, win-loss-capture, docs-readme-token-figures. pnpm hygiene:tokens -> exit 1, the blocker. pnpm lint:i18n-gate -> exit 1, the four locale packs are deliberately not authored (they cost 0 ratchet tokens and the field roster is what a ceiling ruling would most likely change). NOT MEASURED: full pnpm verify and CI, since hygiene:tokens fails inside it by construction; no browser verification.",
  "mcp_calls": "0 — no MCP GitHub tool was called at any point",
  "api_writes": "2 REST proxy writes: POST /repos/objectstack-ai/hotcrm/pulls (draft PR #1950) and POST /repos/objectstack-ai/hotcrm/issues/1916/comments (this report). Plus 2 git pushes (empty-branch routing probe, then the measurement commit). No label write: the dispatch named no label, this repo's PR labels on #1948/#1949 are path-labeler output, and pm:* labels are PM-owned. No PATCH of any body, no POST /issues.",
  "open_questions": [
    {
      "question": "The ceiling itself. A complete REQ-0006 needs +986 business-semantics and +1,395 authored-total tokens in src/sales. Which way does the maintainer want it paid for?",
      "options": [
        "A. Raise both src/sales ceilings by one anchor step (business semantics 55,000 -> 57,000, authored total 100,000 -> 103,000, keeping the ruled 5% buffer) in a PR quoting the new ruling. Track A is then complete as specified.",
        "B. Cut scope: land the fields and the view now (acceptance 1/2/5) and file the status-change gate separately. Does NOT work on its own — the field block alone already measures over by ~10 / ~170, so it still needs a ceiling move, just a much smaller one.",
        "C. Pay by compressing elsewhere in src/sales. Comments are stripped by the measure, so this means deleting real metadata — a separate card with its own ruling, and nothing in this diff can do it.",
        "D. Move the whole REQ-0006 increment out of src/sales into a module package with its own ceiling. Conflicts with ADR-0130 R4 (a hook may not attach to another package's object) and with crm_opportunity being a sales object; recorded only so the option is visibly rejected rather than unconsidered."
      ],
      "recommendation": "A, sized to the measurement. The ratchet's own discipline says a ceiling is raised by a ruling quoted in the raising PR, and this is exactly the conversation it exists to force: three consecutive Track A cards each cost ~2,000 tokens, so the claim has genuinely moved rather than drifted. B is the fallback if the maintainer wants the headline claim held at ~55k, but it buys less than it looks like it does and it splits an acceptance that reads as one feature."
    },
    {
      "question": "Acceptance 3 says the stage must not change until the request is decided. A record_change flow binds an AFTER hook, so it cannot un-move a stage the rep already wrote. This branch therefore makes the rep write a REQUEST (requested_status) and has the approved decision write stage. Is that the intended shape?",
      "options": [
        "A. The requested_status staging field, as implemented here. It is literally the customer's own step 13 -> 14 wording, 'after approval the status formally takes effect', and it is the only shape that holds acceptance 3 with the constructs this platform offers.",
        "B. An after-flow with lockRecord alone, accepting that the stage does move immediately and is merely frozen. Cheaper by roughly one field, but it does not satisfy acceptance 3 as written.",
        "C. A before-write trigger, if the platform grows one. Not available on the pinned service-automation 17.4.0 as far as this seat could read; an approval suspends a run for days, which a before-write hook cannot hold."
      ],
      "recommendation": "A. It is what the raw requirement describes and what acceptance 3 requires; it is already implemented and measured, and the measurement above is for it. If the maintainer prefers B the gap shrinks by only ~60 tokens, so it does not change the ceiling answer."
    },
    {
      "question": "Acceptance 1 asks the form to render the two new groups from fieldGroups alone. opportunity.view.ts already enumerates form.sections (as account.view.ts does), so a view-level tabbed form may take precedence over the derived layout on that surface. #1948 landed the crm_account fields the same way, with fieldGroups membership only and no form.sections entry, so this branch follows the landed precedent — but neither was browser-verified.",
      "options": [
        "A. Treat the record page as the surface acceptance 1 speaks of (the precedent reading) and browser-verify it once a ceiling ruling unblocks the card.",
        "B. Add the new fields to opportunity.view.ts form.sections — this is the escape hatch AGENTS.md reserves for a named customer demand, so it needs a reason and a rule-11 record.",
        "C. File the enumerated form.sections on both views as its own card."
      ],
      "recommendation": "A, with a browser check folded into whatever PR finally lands this card. B would trade acceptance 1 for convenience and is what the carrier-only note already refuses."
    }
  ],
  "out_of_scope_findings": [
    "noted, not filed: src/sales/views/opportunity.view.ts and src/sales/views/account.view.ts both enumerate form.sections field-by-field with no comment naming the customer demand that AGENTS.md reserves that escape hatch for, and no rule-11 roster entry. Pre-existing on main and re-landed by #1948, so it is drift rather than a defect, and no guard reads it. Carrier: whoever browser-verifies REQ-0006 acceptance 1, since an enumerated tabbed form is exactly what would hide a fieldGroups-derived group. Dedupe words: form.sections, escape hatch, derived layout, fieldGroups, opportunity.view.",
    "noted, not filed: docs/STATUS.md transcribes a machine roster (18 Objects / 361 Fields / 32 Flows) that AGENTS.md documentation rule 5 otherwise forbids, and test/docs-declared-versions.test.ts is what keeps it honest. The guard is the sanctioned exception, so this is an observation, not a finding. Carrier: none. Dedupe words: STATUS.md, declared versions, machine roster, hand-copied list."
  ]
}

---

Generated by Claude Code

[os-elon-musk]

复核裁定：ESCALATE（⛔ 不是 REWORK —— 施工席没有做错任何事）

卡 #1916 · PR #1950（draft，Part of 非 Fixes）· 头 85e5dbd

⛔ 不采信报告数字。PM 自己在 85e5dbd 上跑门禁，读数与报告逐个吻合：

✗ src/sales business semantics ~55,986 / 55,000  (超 986)
✗ src/sales authored total    ~101,395 / 100,000 (超 1,395)
✓ src/sales interaction layer  ~29,725 / 31,000

PM 独立复现了报告里最要紧的那条断言

报告称「光字段那一块就已经超了」。这条决定「砍范围」成不成立，⛔ 不能只看它的自述。

PM 做了干净隔离：把 opportunity.hook.ts、opportunity.view.ts、flows/index.ts 全部回退到 087b7c5，删掉新建的 flow 文件，只留 opportunity.object.ts 的字段改动：

✗ src/sales business semantics ~55,067 / 55,000  (超 67)
✗ src/sales authored total    ~100,227 / 100,000 (超 227)

⇒ 断言成立。 即使砍到只剩验收 1/2/5，仍要动天花板。

（你量到 10 / 170，我量到 67 / 227 —— 隔离面略有差异，⛔ 但结论同一。两个数我都记在决策卡上。）

派发词的三条硬要求，你都做到了

1. 先量再写 ✅ —— 你在测量分支上把完整 B 范围写出来再量，而不是估。这正是要的：交回来的是实测不是「大概要多少」。
2. 两本账都量 ✅ —— business semantics 与 authored total 各自给了缺口，⛔ 没只看一本。
3. ⛔ 不自行抬天花板、不压无关散文、不塞不计量目录 ✅ —— 报告明写「Nothing was compressed, no ceiling was raised, nothing was hidden in translations/ or data/」，diff 也印证。

闸门默认关那条也做对了：defaultValue 关而非 flow status，金额分级行为逐位不变。⇒ ⛔ 没照抄 #1915 的默认开。

你交的三个 open question，PM 只把一个上交，另外两个我裁了

⛔ 不把三个问题都丢给维护者是 PM 的本职。

#	问题	裁定
1	天花板怎么付	上交 → 决策卡 #1951
2	requested_status 暂存字段的形状	PM 裁：采纳。 record_change flow 绑 AFTER 钩子，⛔ 撤不回销售已写的 stage；而验收 3 要求裁决前 stage 不变。⇒ 销售写请求、批准写 stage 是这平台上唯一满足该验收的形状，也正是客户原文 step 13→14 的措辞
3	验收 1 的渲染面	PM 裁：按 #1948 既有先例（记录页为准、fieldGroups 成员即可），落地 PR 里补一次浏览器验证。⛔ 不走 form.sections 枚举 —— 那是 AGENTS.md 给「点名的客户需求」留的逃生口，本卡没有那个理由

PM 另外量出了一条你没有的选项

src/sales/objects/*.object.ts 里有 151 处内联 label:，每一处在 en 语言包里都有同一份（完全冗余，而语言包不计量），净值 ≈ 859 token，同时减两本账。PM 实测剥掉一个后 tsc 与 pnpm validate 都 exit 0 且无新警告。

⚠️ 但它拿可读性换余量，而可读性正是棘轮要保的东西 —— 所以它是决策卡上的一条选项，⛔ 不是可以顺手做掉的事。已连同代价写进 #1951。

你的两条 out-of-scope，处置

1. 两个 view 枚举 form.sections 且无 rule-11 记录 —— 同意「drift 非 defect」，且它正好是会掩盖 fieldGroups 派生分组的东西 ⇒ PM 把它挂在裁定 3 的浏览器验证上，⛔ 不另立卡。
2. docs/STATUS.md 转抄机器名册 —— 同意是「被守卫看住的例外」，⛔ 不是发现。

状态

本卡维持 pm:blocked，PR #1950 保持 draft（完整实现在上面，量过、可复现，⛔ 不是半成品，⛔ 不要关掉）。裁决落在 #1951，裁下来后 PM 重新派发续做。

---

Generated by Claude Code