docs: NPI/healthcare products implementation plan

docs/plans/npi-healthcare-products-plan.md

@@ -0,0 +1,113 @@
+# Plan — NPI / Healthcare Compliance Products + Site Pages
+
+## Goal
+Build the full NPI/Healthcare compliance product line: ERPNext-backed ordering
+(mirroring the FCC + trucking patterns), public service + order pages, and a free
+NPI compliance-check lookup tool. **Exclude HIPAA** (separate specialty). All
+ordering flows through the existing `compliance_orders` → ERPNext pipeline.
+
+## Scope / affected areas
+The codebase defines a compliance service in ~5 coordinated places. We replicate
+that for the new healthcare slugs:
+
+1. **API catalog** — `api/src/routes/compliance-orders.ts`
+   `COMPLIANCE_SERVICES` map (slug → name, price_cents, gov_fee, erpnext_item),
+   plus per-slug intake-required-fields and any slug-specific intake derivation.
+2. **Intake manifest** — `site/src/lib/intake_manifest.ts`
+   `INTAKE_MANIFEST` (steps) + `SERVICE_META` (name/price) for each slug.
+3. **ERPNext items** — `performancewest_erpnext/.../fixtures/item.json`
+   one Item per service (item_code must match the slug for worker dispatch via
+   `base_worker._resolve_service_slug`).
+4. **Site pages (Astro)** —
+   - `site/src/pages/services/healthcare/*.astro` (marketing/service pages)
+   - `site/src/pages/order/*.astro` (order/intake wizard pages, copy cpni pattern)
+   - nav menu entry (add a "Healthcare" column to the Services dropdown).
+5. **Worker handlers** — `scripts/workers/services/*.py` + registration in
+   `services/__init__.py` `SERVICE_HANDLERS` (keyed by slug). Start as
+   review-staged handlers (like FCC auto-filing-off default) since PECOS/NPPES
+   submission is manual initially.
+6. **Free tool** — backend `api/src/routes/npi-lookup.ts` (mirror `dot-lookup.ts`)
+   + frontend `site/public/tools/npi-compliance-check/` (mirror dot tool) + an
+   `npi_*` data table (migration) loaded from the companion DBs we already pulled.
+7. **Portal** — `performancewest_erpnext/.../www/orders.py` already renders a
+   generic compliance section; add the new slugs to `COMPLIANCE_SERVICE_LABELS`
+   and (optionally) a healthcare filing-field map for Filed/Overdue badges.
+
+## Product set (slugs, names, prices — from doc sec 6, HIPAA excluded)
+| slug | name | price |
+|---|---|---|
+| `npi-revalidation` | Medicare PECOS Revalidation Filing | $399 |
+| `npi-reactivation` | NPI Reactivation | $249 |
+| `nppes-update` | NPPES Data Update / Attestation | $149 |
+| `medicare-enrollment` | Medicare Enrollment (PECOS) | $499 |
+| `medicare-reenrollment` / opt-out renewal | Opt-Out Renewal / Re-enrollment | $249 |
+| `oig-sam-screening` | OIG/SAM Exclusion Screening (annual) | $99/yr |
+| `caqh-attestation` | CAQH Profile Attestation/Maintenance | $249/yr |
+| `provider-credentialing` | Payer Credentialing (per payer) | $199 |
+| `provider-compliance-bundle` | Provider Compliance Bundle (annual) | $599–$899/yr |
+
+(Flagship = `npi-revalidation`; bundle = recurring revenue anchor.)
+
+## Approach (concrete ordered steps)
+1. **Data layer for the free tool.** Add migration `npi_providers` (+ companion
+   tables: revalidation, exclusions, opt-out) loaded from the already-downloaded
+   free CMS/OIG files. Loader script under `scripts/workers/` mirroring the FMCSA
+   census downloader. Join key = NPI.
+2. **Free lookup backend.** `api/src/routes/npi-lookup.ts`:
+   `GET /api/v1/npi/lookup?npi=` and `?name=`, returning checks
+   (revalidation overdue, NPI deactivated, exclusion flag, opt-out expiring,
+   stale NPPES) in the same `ComplianceCheck[]` shape as dot-lookup.
+3. **Free lookup frontend.** `tools/npi-compliance-check/` cloned from the dot
+   tool (green/teal healthcare theme), pre-fillable `?npi=` for campaign links.
+4. **Service catalog wiring.** Add all slugs to `COMPLIANCE_SERVICES`
+   (compliance-orders.ts) with prices + `erpnext_item` codes + intake-required
+   fields. Add matching `SERVICE_META` + `INTAKE_MANIFEST` entries.
+5. **ERPNext items.** Add one Item per slug to `item.json` (item_code == slug).
+6. **Order + service pages.** Generate `order/*.astro` (Wizard, copy cpni) and
+   `services/healthcare/*.astro` for each product; add Healthcare nav column.
+7. **Worker handlers.** Add `scripts/workers/services/npi_*.py` handlers
+   (review-staged: generate packet + admin ToDo + email, like FCC auto-file-off),
+   register in `SERVICE_HANDLERS`.
+8. **Portal labels.** Extend `COMPLIANCE_SERVICE_LABELS` (orders.py) so healthcare
+   orders render in the customer portal.
+9. **Intake steps.** Reuse the generic `entity/review/payment` steps; add a small
+   NPI intake step component if NPI-specific fields are needed (NPI #, enrollment
+   ID). Most products can run on entity + review + payment.
+
+## Validation
+- **Data/tool:** load companion data, hit `/api/v1/npi/lookup?npi=<known overdue
+  NPI from our 217,968 list>` and confirm it returns the overdue-revalidation
+  flag; confirm a deactivated NPI returns the reactivation check. Load the tool
+  page locally and run a lookup end-to-end.
+- **Catalog:** unit-check that every new slug in `COMPLIANCE_SERVICES` has a
+  matching `SERVICE_META`, `INTAKE_MANIFEST`, ERPNext Item (item_code), and worker
+  handler in `SERVICE_HANDLERS` — write a small consistency check script that
+  fails if any slug is missing in any of the 5 places.
+- **Order flow:** `POST /api/v1/compliance-orders` with a healthcare slug returns
+  an order_number; confirm row lands in `compliance_orders` with correct price.
+- **Build:** `npm run build` in `site/` succeeds with the new Astro pages; nav
+  renders the Healthcare column; order pages load the Wizard.
+- **Worker:** simulate a paid order and confirm the handler stages a review packet
+  + admin ToDo (no live PECOS submission).
+- **Portal:** a seeded healthcare order shows in `/orders` with the right label.
+
+## Open questions / decisions
+1. **Free tool data source.** NPPES is ~10M rows / ~1GB+. Load full NPI table, or
+   only the ~225k with revalidation due dates + ~491k with endpoints (smaller,
+   targeted)? Recommend: load the targeted subset first, expand later.
+2. **NPI intake field.** Do we collect the provider's NPI at order time and
+   auto-pull their revalidation/exclusion status into the order? (Improves
+   fulfillment, small extra intake step.)
+3. **Fulfillment reality.** PECOS revalidation/enrollment is done in CMS PECOS
+   (login). Confirm handlers stay review-staged (human files) initially — same
+   safety default as FCC auto-filing-off. Agreed?
+4. **Bundle composition.** What exactly is in the $599–$899 Provider Compliance
+   Bundle (revalidation watch + OIG/SAM screening + NPPES upkeep)? Need final SKU.
+5. **Recurring billing.** OIG/SAM screening + CAQH + bundle are annual
+   subscriptions — does the current order system handle recurring, or do we model
+   as annual one-time renewals (like CRTC maintenance)? Recommend annual one-time
+   to match existing patterns.
+6. **Theme/brand.** Pick the healthcare accent color (telecom=blue, trucking=
+   orange, privacy=purple). Propose teal/green.
+7. **Scope of first cut.** Ship flagship 3 (`npi-revalidation`, `npi-reactivation`,
+   `nppes-update`) + free tool first, then add the rest? Recommend yes.