docs(11-01): complete company catalog subscription sync data-contract plan
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
parent
c3a0432869
commit
4b9643ac15
1 changed files with 120 additions and 0 deletions
|
|
@ -0,0 +1,120 @@
|
|||
---
|
||||
phase: 11-company-catalog-subscription-sync
|
||||
plan: 01
|
||||
subsystem: database, api-client
|
||||
tags: [postgres, migration, typescript, pax8, vitest, tdd]
|
||||
|
||||
# Dependency graph
|
||||
requires:
|
||||
- phase: 10-pax8-client-auth-foundation
|
||||
provides: Pax8Client OAuth2 client-credentials auth, pax8-factory, migrations/091_pax8_tables.sql schema, lib/types/pax8.ts base types
|
||||
provides:
|
||||
- migrations/092_pax8_subscription_costs.sql adding price/partner_cost/currency to pax8_subscriptions (applied to dev DB)
|
||||
- Extended lib/types/pax8.ts with cost fields on Pax8Subscription, vendorName/shortDescription on Pax8Product, and new Pax8EntitySyncResult/Pax8SyncResult shapes
|
||||
- Pax8Client.listAllCompanies()/listAllSubscriptions()/listAllProducts() read-only pagination helpers with mocked-fetch test coverage
|
||||
affects: [11-02-company-catalog-subscription-sync-service, 12-historical-sync-company-matching]
|
||||
|
||||
# Tech tracking
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns: ["paginateAll<T>() private helper looping page.number until page.totalPages - 1, reusing existing fetchJson() 429 backoff"]
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- migrations/092_pax8_subscription_costs.sql
|
||||
modified:
|
||||
- lib/types/pax8.ts
|
||||
- lib/services/pax8-client.ts
|
||||
- lib/services/pax8-client.test.ts
|
||||
|
||||
key-decisions:
|
||||
- "Cost columns are additive-only NUMERIC(12,2) price/partner_cost + CHAR(3) currency on pax8_subscriptions, matching migration 091's currency convention on pax8_orders/pax8_order_items — no monthly-normalization column (D-04 deferred to read-time)"
|
||||
- "Pagination ownership: the client (not the future sync service) owns the loop-until-exhausted logic via a shared private paginateAll<T>() helper, since all three entity types need identical page-walking logic"
|
||||
|
||||
patterns-established:
|
||||
- "Pattern: paginateAll<T>(fetchPage) — generic pagination loop reused by listAllCompanies/listAllSubscriptions/listAllProducts, stops at page.number >= page.totalPages - 1"
|
||||
|
||||
requirements-completed: [PAX8-04, PAX8-05, PAX8-08]
|
||||
|
||||
# Metrics
|
||||
duration: ~20min
|
||||
completed: 2026-07-10
|
||||
---
|
||||
|
||||
# Phase 11 Plan 01: Company Catalog & Subscription Sync — Data Contract Layer Summary
|
||||
|
||||
**Migration 092 adds price/partner_cost/currency to pax8_subscriptions, lib/types/pax8.ts gains cost fields plus Pax8SyncResult/Pax8EntitySyncResult, and Pax8Client gains read-only listAllCompanies/listAllSubscriptions/listAllProducts pagination helpers (TDD, 9 passing tests).**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** ~20 min
|
||||
- **Completed:** 2026-07-10
|
||||
- **Tasks:** 3 completed (Task 3 was a full TDD RED→GREEN cycle)
|
||||
- **Files modified:** 4 (1 created, 3 modified)
|
||||
|
||||
## Accomplishments
|
||||
- Added `migrations/092_pax8_subscription_costs.sql` (3 additive `ADD COLUMN IF NOT EXISTS` clauses) and applied it to the running dev Postgres container (`pulse-postgres` / `pulse_autotask` db, `pulse_user` role) — confirmed via `\d pax8_subscriptions` before and after
|
||||
- Extended `Pax8Subscription` (price, partnerCost, currencyCode, productName, endDate, updatedDate) and `Pax8Product` (vendorName, shortDescription) in `lib/types/pax8.ts`, plus new exported `Pax8EntitySyncResult`/`Pax8SyncResult` interfaces mirroring the AppGate sync-result shape
|
||||
- Added `listAllCompanies()`, `listAllSubscriptions()`, `listAllProducts()` to `Pax8Client` via a shared private `paginateAll<T>()` helper, requesting `size=200` and looping through `fetchJson()` (inheriting existing 429/Retry-After backoff); existing `listCompanies(page, size)` signature untouched
|
||||
- Full TDD cycle for Task 3: 5 new tests written and confirmed failing (RED) before implementation, then all 9 tests (4 existing + 5 new) passed after implementation (GREEN)
|
||||
|
||||
## Task Commits
|
||||
|
||||
Each task was committed atomically:
|
||||
|
||||
1. **Task 1: Add subscription cost columns (migration 092)** - `b0f6de0` (feat)
|
||||
2. **Task 2: Extend PAX8 types with cost fields and sync-result shapes** - `0d819ba` (feat)
|
||||
3. **Task 3: Add read-only pagination helpers to the PAX8 client** - `19fe788` (test, RED) then `c3a0432` (feat, GREEN)
|
||||
|
||||
_TDD task (Task 3) has two commits per the RED→GREEN cycle; no REFACTOR commit was needed._
|
||||
|
||||
## Files Created/Modified
|
||||
- `migrations/092_pax8_subscription_costs.sql` - Additive migration: `price NUMERIC(12,2)`, `partner_cost NUMERIC(12,2)`, `currency CHAR(3) NOT NULL DEFAULT 'USD'` on `pax8_subscriptions`; applied to dev DB via `docker exec -i pulse-postgres psql -U pulse_user -d pulse_autotask`
|
||||
- `lib/types/pax8.ts` - Cost/lifecycle fields on `Pax8Subscription`, `vendorName`/`shortDescription` on `Pax8Product`, new `Pax8EntitySyncResult`/`Pax8SyncResult` interfaces
|
||||
- `lib/services/pax8-client.ts` - New `paginateAll<T>()` private helper plus `listAllCompanies()`/`listAllSubscriptions()`/`listAllProducts()` public methods, all GET-only
|
||||
- `lib/services/pax8-client.test.ts` - New `makeMultiPageFetchMock()` helper and 5 new tests covering multi-page concatenation, `size=200` assertion, single-page no-infinite-loop, and GET-only/Bearer-header assertion across all three new methods
|
||||
|
||||
## Decisions Made
|
||||
- Followed the plan's explicit column/type/method specs verbatim — no open decisions required beyond what the plan already resolved (D-03/D-04 already settled at plan-authoring time)
|
||||
- Chose to implement pagination via one shared private `paginateAll<T>()` helper rather than duplicating the loop three times, since all three entity types share identical page-walking semantics (`page.number >= page.totalPages - 1`)
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
None - plan executed exactly as written. One pre-existing, out-of-scope issue was noted (see below) but not modified.
|
||||
|
||||
### Out-of-Scope Discovery (logged, not fixed)
|
||||
|
||||
`npx tsc --noEmit --pretty` surfaces 2 pre-existing errors in `lib/services/sync-scheduler.ts` (lines 446, 450) referencing `@/lib/services/appgate-factory` and `@/lib/services/appgate-sync-service`. These files exist as untracked (`??`) files in the main repo checkout but were never committed, so they are absent from this git worktree's history — a worktree/commit-state artifact unrelated to this plan's changes to `lib/types/pax8.ts`, `pax8-client.ts`, or the new migration. Confirmed identical before and after this plan's edits. Logged to `.planning/phases/11-company-catalog-subscription-sync/deferred-items.md` per the executor's scope-boundary rule; no action taken.
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
None - the RED phase confirmed all 5 new tests failed for the expected reason (`TypeError: client.listAllX is not a function`), and the GREEN phase confirmed all 9 tests (4 existing + 5 new) passed with no regressions.
|
||||
|
||||
## User Setup Required
|
||||
|
||||
None - no external service configuration required. The migration was applied directly to the existing `pulse-postgres` dev container as part of Task 1 (per CLAUDE.md's manual-apply-on-existing-volume caveat).
|
||||
|
||||
## Next Phase Readiness
|
||||
|
||||
Plan 02 (the sync service) can now consume:
|
||||
- `pax8_subscriptions.price` / `partner_cost` / `currency` columns (confirmed present in dev DB)
|
||||
- `Pax8Subscription.price`/`partnerCost`/`currencyCode`/`productName`/`endDate`/`updatedDate`, `Pax8Product.vendorName`/`shortDescription`, and `Pax8SyncResult`/`Pax8EntitySyncResult` from `lib/types/pax8.ts`
|
||||
- `Pax8Client.listAllCompanies()`/`listAllSubscriptions()`/`listAllProducts()` for full-catalog reads
|
||||
|
||||
No blockers. The unrelated `sync-scheduler.ts` tsc error (see Deviations) is a worktree artifact that should resolve itself once the AppGate work referenced there is committed to the shared base — it does not block Plan 02's PAX8 work.
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- FOUND: migrations/092_pax8_subscription_costs.sql
|
||||
- FOUND: lib/types/pax8.ts (partnerCost, Pax8SyncResult present)
|
||||
- FOUND: lib/services/pax8-client.ts (listAllCompanies/listAllSubscriptions/listAllProducts present)
|
||||
- FOUND: lib/services/pax8-client.test.ts (9 passing tests)
|
||||
- FOUND commit b0f6de0
|
||||
- FOUND commit 0d819ba
|
||||
- FOUND commit 19fe788
|
||||
- FOUND commit c3a0432
|
||||
|
||||
---
|
||||
*Phase: 11-company-catalog-subscription-sync*
|
||||
*Plan: 01*
|
||||
*Completed: 2026-07-10*
|
||||
Loading…
Add table
Add a link
Reference in a new issue