---
phase: 14-pax8-ui-surface
plan: 02
subsystem: api
tags: [pax8, postgres, transaction, vitest, requireAuth, requirePermission]

# Dependency graph
requires:
  - phase: 14-pax8-ui-surface
    provides: migration 091/093 schema (pax8_companies, pax8_company_match_review), pax8-company-matcher.ts re-scoring guard
provides:
  - "GET /api/pax8/company-matches — requireAuth-gated unresolved review queue with bulk-fetched candidate names"
  - "resolvePax8CompanyMatch(tx, params) — unit-tested two-table transactional resolver service"
  - "POST /api/pax8/company-matches/[id]/resolve — requirePermission('admin','access')-gated resolve mutation"
affects: [14-pax8-ui-surface plan 06 (manual verification), any future pax8 admin UI plan consuming these routes]

# Tech tracking
tech-stack:
  added: []
  patterns:
    - "Extracted transactional write logic into lib/services/ as a plain-tx-parameter function for unit testability, mirroring device-link-conflicts' resolve route shape but diverging on the validation substitute (existence/active check instead of candidate-membership check)"

key-files:
  created:
    - app/api/pax8/company-matches/route.ts
    - lib/services/pax8-company-match-resolver.ts
    - lib/services/pax8-company-match-resolver.test.ts
    - app/api/pax8/company-matches/[id]/resolve/route.ts
  modified: []

key-decisions:
  - "D-07: GET /api/pax8/company-matches uses requireAuth() only (not requirePermission) — the review queue is manager-visible; only the mutation is admin-gated"
  - "D-08: POST .../resolve uses requirePermission('admin','access') — the deliberate asymmetry vs the GET route"
  - "D-05/D-09: resolver does not enforce candidate_company_ids membership — validates target company existence + active state instead, so the manual-search fallback and zero-candidate case can resolve to any valid Autotask company"

patterns-established:
  - "Resolver-as-tx-parameter pattern: lib/services/pax8-company-match-resolver.ts takes a `{ query }` tx handle as its first argument rather than importing postgresClient directly, making the transactional write path testable with a hand-rolled mock instead of vi.mock('@/lib/services/postgres-client')"

requirements-completed: [PAX8-12, PAX8-14]

# Metrics
duration: 12min
completed: 2026-07-11
---

# Phase 14 Plan 02: PAX8 Company Match Review + Resolve API Summary

**GET review-queue route (requireAuth) + admin-gated POST resolve route (requirePermission) backed by a unit-tested `resolvePax8CompanyMatch` service that writes both `pax8_companies.match_method='manual'` and the review row atomically in one transaction.**

## Performance

- **Duration:** ~12 min
- **Started:** 2026-07-11T18:18:00Z (approx, prior to first Read)
- **Completed:** 2026-07-11T18:29:47Z
- **Tasks:** 3 completed (Task 2 followed TDD RED→GREEN)
- **Files modified:** 4 created, 0 modified

## Accomplishments
- `GET /api/pax8/company-matches` returns the unresolved review queue (paginated, `limit`/`offset`) with each flagged PAX8 company's top-3 candidate Autotask companies resolved to names via a single bulk `= ANY($1::bigint[])` query — no N+1 lookups.
- `resolvePax8CompanyMatch()` extracted into `lib/services/` as the load-bearing, test-covered write path: it locks the review row (`FOR UPDATE`), guards `not_found`/`already_resolved`, validates the target company's existence + active state, then issues both required UPDATEs (`pax8_companies.match_method='manual'` and `pax8_company_match_review.resolved_*`) so the matcher's re-scoring eligibility guard never re-flags a resolved company on the next sync.
- `POST /api/pax8/company-matches/[id]/resolve` is admin-only (`requirePermission('admin','access')`), zod-validates the body (`companyId` positive int, `note` optional ≤500 chars), and delegates to the resolver inside `postgresClient.transaction(...)`, mapping result codes to HTTP status (`ok`→200, `not_found`→404, `already_resolved`→409, `company_not_found`→400).
- Five vitest behavior cases green, covering the full resolver contract including the D-05/D-09 non-candidate-id acceptance case.

## Task Commits

Each task was committed atomically:

1. **Task 1: GET /api/pax8/company-matches** - `a08664b` (feat)
2. **Task 2: resolvePax8CompanyMatch service + unit test (RED→GREEN)** - `afdcf14` (test, RED) → `0ce51a0` (feat, GREEN) → `4d7a58b` (docs, minor wording fix for grep acceptance check)
3. **Task 3: POST /api/pax8/company-matches/[id]/resolve** - `a81e358` (feat)

_TDD Gate Compliance: `test(...)` commit `afdcf14` precedes `feat(...)` commit `0ce51a0` — RED then GREEN confirmed by running vitest before and after implementation._

## Files Created/Modified
- `app/api/pax8/company-matches/route.ts` - GET unresolved review queue, requireAuth-gated, bulk candidate-name fetch
- `lib/services/pax8-company-match-resolver.ts` - `resolvePax8CompanyMatch(tx, params)` two-table transactional resolver
- `lib/services/pax8-company-match-resolver.test.ts` - vitest coverage: success (both writes), not_found, already_resolved, company_not_found, non-candidate companyId still resolves
- `app/api/pax8/company-matches/[id]/resolve/route.ts` - POST resolve, requirePermission('admin','access')-gated, zod body validation, wraps resolver in a transaction

## Decisions Made
- Followed interfaces block exactly for the `ResolveResult` discriminated union and `resolvePax8CompanyMatch` signature — no divergence from the plan's contract.
- Task 2's docstring originally referenced the literal string `candidate_company_ids` to explain what is deliberately *not* checked; reworded to satisfy the plan's grep-based acceptance criterion ("no reference to candidate_company_ids in the resolver source") without changing any logic — tracked as commit `4d7a58b`, not a deviation rule (documentation-only, no behavior change).

## Deviations from Plan

None - plan executed exactly as written. The one follow-up commit (`4d7a58b`) was a same-task documentation wording fix to satisfy a literal grep-based acceptance criterion, not a functional deviation.

## Issues Encountered

None.

## User Setup Required

None - no external service configuration required.

## Next Phase Readiness
- Read and write routes for PAX8 company match resolution are complete, type-checked, and unit-tested.
- Ready for Plan 06's manual verification step (resolve a real flagged company as admin, confirm both tables update, confirm re-sync leaves it untouched, confirm non-admin gets 403).
- No blockers for dependent UI plans consuming `GET /api/pax8/company-matches` / `POST .../resolve`.

---
*Phase: 14-pax8-ui-surface*
*Completed: 2026-07-11*

## Self-Check: PASSED

All created files verified present on disk; all task/summary commit hashes verified in git log.
