PSA/ee/docs/plans/2026-06-12-hudu-integration-phase2-1/PRD.md

# Hudu Integration — Phase 2.1: Attributes, Layout Exclusion, Multi-Source Guard

- Status: Approved (scope picked by Natallia 2026-06-12)
- Phase: 2.1 (pull-only, Hudu → AlgaPSA)
- Predecessors: Phase 1 (`2026-06-08-hudu-integration`), Phase 2 (`2026-06-11-hudu-integration-phase2`)

## Overview

Three gaps surfaced while reviewing Phase 2:

1. **Hudu field data (incl. Notes) isn't imported** — Hudu assets carry their
   real documentation in per-layout custom `fields[]`; Phase 2 imported only
   name/serial/type.
2. **Every Hudu layout is importable** — but most layouts (API Secrets,
   Contracts & SLAs, Cloud Accounts…) aren't devices and shouldn't become
   AlgaPSA assets at all.
3. **Multi-source sync is unguarded** — NinjaOne's sync engine already
   creates/updates Alga assets; Hudu sync writing name/serial to the same
   asset means last-writer-wins ping-pong, and import can create duplicates
   when serials are absent or unmatched.

## Verified foundations

- Live `assets` columns include `attributes jsonb` (NinjaOne precedent for
  integration extras), `rmm_provider/rmm_device_id/agent_status/last_seen_at`
  (direct RMM-ownership signal), and `notes_document_id` (document-backed
  notes — NOT used here; creating documents from Hudu content would break the
  link-only philosophy and invite drift).
- Hudu `fields[]` shape (live): `{ id, label, value, position }`, ordered by
  position; values are strings/dates/numbers/null.

## Goals

- G1. Import and sync copy a Hudu asset's `fields[]` into the Alga asset's
  `attributes` under a Hudu namespace; the asset detail page renders them.
- G2. The layout map supports **Don't import** per layout; import paths skip
  excluded layouts.
- G3. Hudu sync never fights an RMM for device facts; import never silently
  creates a serial-duplicate of an existing asset.

## Non-goals

- Per-field mapping UI (Hudu field → specific Alga column) — the namespace
  copy is wholesale and read-only.
- Writing Hudu data into `notes_document_id` / creating Alga documents.
- Per-tenant configurable field-precedence matrix (the fixed RMM-wins rule is
  this phase; config comes if a real need appears).
- Touching NinjaOne's sync engine.

## Functional Requirements

Hudu attributes (group `hudu-attributes`):
- FR1. `HuduAsset` contract gains `asset_layout_id` and `fields[]` (lifting
  the Phase 2 local typing into contracts.ts).
- FR2. Import writes `attributes.hudu_fields = [{label, value}]` (position
  order preserved) and `attributes.hudu_synced_at`; other attributes keys
  untouched.
- FR3. Sync refreshes `attributes.hudu_fields` on every mapped, live Hudu
  asset (the Hudu namespace is always Hudu-won, independent of the RMM rule);
  a row counts as `updated` if name/serial OR hudu_fields changed.
- FR4. Asset detail page renders a read-only "Hudu Documentation" card
  listing label/value pairs whenever `attributes.hudu_fields` is non-empty.
  Pure data-presence gate — no EE import, no flag check (the data only exists
  if the EE integration wrote it), so the card lives in packages/assets (CE)
  next to its siblings.
- FR5. New UI strings i18n'd in all 8 locales in whatever namespace the
  asset detail components already use.

Layout exclusion (group `layout-exclude`):
- FR6. The layout-type map accepts `'excluded'` alongside the six asset
  types; normalization/validation updated; `resolveAssetTypeForLayout`
  exposes exclusion distinctly (not as 'unknown').
- FR7. Settings UI type select gains a "Don't import" option.
- FR8. Single import of an excluded-layout asset returns a typed
  `layout_excluded` failure; bulk import skips excluded-layout assets and
  reports a `skipped` count in the summary.
- FR9. The client-tab mapping manager hides the Import affordance (and
  excludes the row from "Import all unmatched" counts) for excluded-layout
  rows; mapping an excluded-layout Hudu asset to an EXISTING Alga asset
  remains allowed (context-linking is harmless).

Multi-source guard (group `multi-source-guard`):
- FR10. Sync skips `name`/`serial_number` writes for assets with
  `rmm_provider` set (RMM owns device facts); it still refreshes
  `attributes.hudu_fields` and stale flags for them. Summary gains an
  `rmmSkipped` count surfaced in the UI alongside updated/unchanged/stale.
- FR11. Import pre-checks tenant-wide for an existing asset with the same
  non-blank serial_number; hit → typed `serial_conflict` failure naming the
  existing asset (id + name); bulk records these per-row under `failed` with
  the code.
- FR12. Mapping manager renders bulk-import summaries distinguishing
  created / skipped (excluded) / failed (incl. serial conflicts).

Cross-cutting:
- FR13. Permissions sweep and i18n static scan stay green (no new action
  modules; new strings added to scans where components are Hudu-owned).

## Acceptance Criteria

- AC1. Importing EC-WS-001 lands its Hudu fields on the Alga asset and they
  render on the asset page; re-sync after editing a field in Hudu updates it.
- AC2. "API Secrets" marked Don't import → invisible to Import-all, single
  import fails typed, row not importable in UI but still mappable.
- AC3. An asset with rmm_provider='ninjaone' mapped to a Hudu asset keeps its
  RMM name/serial through a Hudu sync, while its hudu_fields refresh; the
  summary shows it under rmmSkipped.
- AC4. Importing a Hudu asset whose serial matches any existing tenant asset
  fails with serial_conflict naming the existing asset.
- AC5. Full hudu suites green; locale files updated in 8 languages.