refactor(crm): dedupe opportunity logic, unify hook API type, fix hardcoded recipients

[xuyushun441-sys]

Summary

Code-quality optimizations across the CRM hooks and object definitions. No behavior change for end users; the goal is removing duplicate logic, tightening types, and adding regression coverage.

What changed & why

1. Eliminate Opportunity compute double-write — probability and expected_revenue were derived in two places: the lifecycle hook (opportunity.hook.ts) and two field_update workflows in opportunity.object.ts. Two value tables = drift risk. Removed the duplicate workflows; the hook is now the single source of truth. Kept set_forecast_category_by_stage (hook doesn't own it) and the large-deal email alert.

2. Remove dead code — STAGE_PROBABILITY and NARRATIVE_FIELDS were redefined inside the handler, shadowing identical module-level constants. Deleted the in-handler copies.

3. Unify the hook data-API type — 10 hooks each hand-rolled their own ctx.api shape, with inconsistent filter vs where spellings. Extracted a shared HookApi type into src/objects/_hook-api.ts and pointed every hook at it. (The SDK types HookContext.api as unknown, so a local structural type is the established/only option — this just consolidates it.)

4. Drop hardcoded notification mailboxes — replaced sales_management@example.com, support_manager@example.com, escalation_team@example.com with relationship merge fields ({owner}, {owner.manager}, {crm_account.owner}) so alerts scale with the role hierarchy.

5. Add regression test — new e2e/opportunity-lifecycle.spec.ts exercises the hook's stage→probability→expected_revenue math and the closed_won close_date stamp through the REST API.

Notes for reviewers

• Why e2e instead of unit tests for the hooks: L2 hooks are body-only sandboxed code and can't import value modules, so the logic can't be extracted into a pure, unit-testable function. The new spec follows the existing smoke.spec.ts pattern and self-skips when the data API returns 401/403 (the default launch mode gates writes, and the mock auth doesn't issue a usable bearer/cookie). It runs fully in an environment where writes are permitted.

Verification

• pnpm typecheck ✅
• pnpm build ✅ (Build complete, artifact unchanged in shape)
• npx playwright test --list discovers the new spec ✅

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hotcrm	Ignored		May 29, 2026 6:51am