PSA/ee/docs/plans/2026-06-11-hudu-integration-phase2/SCRATCHPAD.md

# Scratchpad — Hudu Phase 2 (Assets & Documents)

## Decisions

- 2026-06-11 — Scope settled with Natallia via three options questions:
  assets = **import + pull sync** (not mapping-only, not one-time import);
  articles = **link-only** section in client Documents tab; global view =
  **Documents page "Hudu" tab** (not global-search-only).
- Sync is **manual-only** this phase (button per client); scheduled refresh
  stays a future enhancement (was already a Phase 1 non-goal).
- Sync conflict policy: **Hudu wins on synced fields only** (`name`,
  `serial_number`); everything else in Alga untouched; `asset_type` never
  retro-changed after import/mapping.
- Hudu disappearance → mapping metadata `stale: true` + badge. Never delete.
- Layout→type map lives in `hudu_integrations.settings.asset_layout_type_map`
  (no new table); UI block inside HuduIntegrationSettings.
- Asset mapping UI reuses the **staged Save/Discard confirmation pattern**
  built for company mappings on 2026-06-11 (picker stages; Save commits;
  dismissible suggestions; row revert/unmap actions).

## Discoveries (verified in code)

- `tenant_external_entity_mappings` unique indexes
  (`server/migrations/20250502173321_…`) are scoped by
  `(tenant…, integration_type, alga_entity_type, …)` → asset mappings
  (`alga_entity_type='asset'`) coexist with Phase 1 client mappings. The
  original migration named the column `tenant_id` but Phase 1's
  companyMapping.ts queries `tenant` and its real-DB tests pass — a later
  rename superseded it. **Mirror companyMapping.ts, not the old migration.**
- `CreateAssetRequest` (`packages/types/src/interfaces/asset.interfaces.ts:378`):
  fixed enum `asset_type: 'workstation'|'network_device'|'server'|
  'mobile_device'|'printer'|'unknown'`; **required** `asset_tag`, `name`,
  `status`, `client_id`; optional `serial_number`; per-type extension blobs.
- `createAsset` = `packages/assets/src/actions/assetActions.ts:755`
  (withAuth wrapper → asset RBAC).
- Client Documents tab: `packages/clients/src/components/clients/
  ClientDetails.tsx` tab id `documents` (~line 1715). Phase 1 EE-injection
  precedent: `useHuduClientTab(client.client_id)` at line 283 + spread tabs
  at ~1844.
- Main documents page: `server/src/app/msp/documents/page.tsx` →
  `packages/documents/src/components/DocumentsPage.tsx`.
- Hudu API (plan dir `hudu-api-reference.md`): assets by company
  `GET /api/v1/assets?company_id=&page=&archived=false`; articles
  `GET /api/v1/articles?company_id=&page=`; global articles = omit
  company_id. Asset layouts: `GET /api/v1/asset_layouts` (verify response
  shape on local instance). 25/page, 300 req/min.
- Hudu asset payload carries `primary_serial`, `asset_layout_id`, `fields[]`
  (layout custom fields), `archived`.

## Environment / testing

- Local Hudu: `http://hudu.localtest.me` (stack in `~/hudu2`), API key
  unscoped, password access on. Companies: ExampleCo (1), Emerald City Ltd
  (2). Alga dev: bigmac worktree, `localhost:3001`, tenant
  `c7c99e9f-19dd-46b0-80be-0a2a59f5ab7a` (has `enterprise` add-on row).
  Flags forced via `server/.env.local` (`NEXT_PUBLIC_FORCE_FEATURE_FLAGS`
  + `DISABLE_FEATURE_FLAGS=true`).
- Unit tests: `cd ee/server && npx vitest run src/__tests__/unit/hudu` —
  273 passing pre-Phase-2 (incl. staged-save mapping manager rewrite).

## Implementation findings

- **FR1 correction**: `idx_unique_external_mapping` is `(tenant,
  integration_type, external_entity_id, COALESCE(external_realm_id,''))` —
  NOT scoped by alga_entity_type (only the alga-direction index is). Hudu
  company and asset ids overlap numerically → asset mapping rows carry
  `external_realm_id = String(hudu company id)` (client rows use null).
  T215 proves coexistence with identical external ids.
- `getHuduAssetMappings` reuses the Phase 1 `getHuduCompanyAssets` action
  for fetch+cache → effectively requires system_settings read in addition
  to asset read (technicians already have it for the client tab). Acceptable.
- regression-phase2 DONE (2026-06-11): huduPermissions.test.ts now enumerates
  all 8 action modules (Phase 1 three + layoutMap/assetMapping/assetImport/
  assetSync/globalDocs) — 97 tests. Layout-map actions joined the
  system_settings manage/view lists; the Technician flows got a
  resource+permission matrix (asset read/update/create, client read) plus an
  unauthenticated sweep over every entry (withAuth mock now drops the session
  user). T093 exhaustiveness still fails on any future unlisted export.
  T250 = information_schema column-list check in
  hudu-regression.integration.test.ts (real-DB harness): exactly the 12
  Phase 1 columns, no pull-only additions (NFR4). T110 expected-file list
  extended with the 5 new action modules.
- Found while running tsc for regression-phase2: 6 hudu type errors from
  earlier groups, all fixed — HuduAssetMappingManager.tsx relied on
  `!result.success` narrowing, which the non-strict EE tsconfig doesn't do
  (added isImportFailure/isBulkImportFailure guards, the file's existing
  isMappingFailure idiom); two TS2347s (type args on untyped vi helpers) in
  huduSettingsPageCategory.test.tsx / huduDocumentsTabGate.test.tsx became
  post-call casts. Remaining tsc errors are the known pre-existing chat
  registry / mcp agent-tooling / msp-composition ones (14).
- `HuduAsset` in contracts.ts lacks `asset_layout_id` (runtime has it);
  typed locally in actions as HuduAssetListItem — consider lifting to
  contracts in a later group.

## OQ resolutions (2026-06-11, verified on local instance)

- **OQ1 RESOLVED**: `GET /api/v1/articles?search=` does case-insensitive
  partial matching ("vpn" → "VPN Setup Guide"); `?name=` is exact-only.
  Use `?search=`. Global list = omit `company_id`; response carries
  `company_id` per article.
- **OQ2 RESOLVED**: `assets.asset_tag` is notNullable but has NO unique
  constraint (migration `20241112031330_create_asset_management_tables.cjs`).
  `primary_serial` as tag is safe; `hudu-<id>` fallback only for missing
  serials. NOTE: assets table column is `company_id` (legacy name for
  client) + `type_id` uuid — the `asset_type` enum in CreateAssetRequest is
  the action-level API; verify createAsset's mapping when implementing.
- Hudu asset payload verified: `{id, name, company_id, asset_layout_id,
  primary_serial, archived, fields[]}`. Default layouts on fresh instance
  incl. "Computer Assets" (7), "Databases" (9), "Applications" (3).
- Seeded local data: articles (2× ExampleCo + 3 pre-existing, 1× Emerald),
  assets EC-WS-001 (SN-EC-1001), EC-SRV-01 (SN-EC-2001) in Computer Assets.
- Git: commits require Natallia's explicit request (auto-mode enforces) —
  implement all groups, flip flags, let her commit per group at the end.

## Gotchas

- `asset_tag` uniqueness semantics unverified (R2) — check before using
  `primary_serial` as tag; fallback `hudu-<id>`.
- Hudu article search param name unverified (OQ1): try `?search=`, fall back
  to `?name=`.
- i18n: every new string needs en + de/es/fr/it/nl/pl/pt keys, and the
  Phase 1 static i18n test (`huduI18n.test.ts`) must be extended to scan the
  new components (it whitelists scanned sources explicitly).
- DocumentsPage is a CE package — EE tab must inject via gate hook, never a
  hard import of EE components (R4).