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

# Hudu Integration — Phase 2: Assets & Documents

- Status: Draft (pending scope confirmation)
- Phase: 2 (still pull-only, Hudu → AlgaPSA)
- Predecessor: `ee/docs/plans/2026-06-08-hudu-integration` (Phase 1, complete)

## Overview

Phase 1 connected Hudu and surfaced a mapped company's assets, articles, and
passwords read-only on the client page. Phase 2 deepens two of those surfaces:

1. **Assets become first-class**: Hudu assets can be **mapped** to existing
   AlgaPSA assets, **imported** (created in Alga from Hudu), and kept current
   with a **manual pull sync** that updates synced fields on mapped assets.
2. **Articles meet Alga's Documents surfaces** (link-only, no content copy):
   a "Hudu Documentation" section on the client's Documents tab, and a "Hudu"
   tab on the main Documents page listing/searching articles across all
   mapped companies.

Phase 1 principles that still hold: EE-only behind the `hudu-integration`
flag; pull-only; deep-link to Hudu for content; never persist article bodies
or passwords; `system_settings` RBAC for integration administration.

## Problem / User Value

- Technicians track devices in both systems by hand. A Hudu asset and its
  Alga asset (used for tickets/billing) have no link, so device context is
  re-discovered on every ticket.
- MSPs onboarding to AlgaPSA already have their device inventory in Hudu;
  re-entering it manually is the single biggest adoption blocker for Alga's
  asset module.
- Runbooks/KB articles live in Hudu but technicians work documents from
  Alga's Documents surfaces; today they must remember which system holds what.

## Goals

- G1. Per-asset mapping between Hudu assets and Alga assets (per client).
- G2. One-click import of unmatched Hudu assets into Alga (single + bulk).
- G3. Manual "Sync from Hudu" per client that pull-updates synced fields on
  mapped assets and flags Hudu-side disappearances.
- G4. Link-only "Hudu Documentation" section in the client Documents tab.
- G5. "Hudu" tab on the main Documents page: cross-client article list with
  search, client resolution, and deep-links.

## Non-goals (Phase 2)

- **Push (Alga → Hudu)** in any form; the data model stays direction-agnostic.
- **Scheduled/background sync** (Temporal or otherwise). Sync is manual this
  phase; a low-frequency scheduled refresh remains a documented future step.
- **Importing article content** as Alga documents (link-only by decision).
- **Custom-field sync** beyond the core field set (name, serial number,
  asset type via layout map). Hudu layout custom fields are displayed in
  Phase 1's read-only view only.
- **Deleting or archiving Alga assets** in response to Hudu changes — sync
  never destroys Alga data; it only flags.
- Mapping Hudu passwords to assets (unchanged from Phase 1; company-scoped).

## Personas & Primary Flows

- **MSP Admin** — configures the asset-layout→asset-type map; runs bulk import.
- **MSP Technician** — maps/imports individual assets, runs Sync, browses
  Hudu documentation from Documents surfaces.

Flows:

1. **Configure layout map** (Admin): Settings → Integrations → Hudu →
   "Asset layouts" block → each Hudu asset layout gets an Alga asset type
   (heuristic prefill, `unknown` fallback) → Save.
2. **Map/import assets** (Technician): Client → Hudu tab → Assets section now
   shows per-asset state (Mapped / Suggested / Unmapped) with an Alga-asset
   picker per row, an Import action per unmatched row, and "Import all
   unmatched". Staged changes commit via an explicit **Save** bar (same
   confirmation pattern as Phase 1 company mappings).
3. **Sync** (Technician): Client → Hudu tab → "Sync from Hudu" → re-fetches
   the company's assets, updates synced fields on mapped Alga assets,
   reports created/updated/stale counts.
4. **Client documents** (Technician): Client → Documents tab → "Hudu
   Documentation" section lists the mapped company's articles (name,
   updated_at) → click → opens in Hudu.
5. **Global documents** (Technician): Documents page → "Hudu" tab → paged,
   searchable article list across companies; each row shows the resolved
   Alga client (or "unmapped") and deep-links to Hudu.

## UX / UI Notes

- **Settings — Asset layouts block** (inside `HuduIntegrationSettings`, below
  Company Mappings): table of Hudu asset layouts (fetched live) × Alga asset
  type select (`workstation | network_device | server | mobile_device |
  printer | unknown`). Heuristic prefill by layout-name keywords
  (server→server; workstation/desktop/laptop→workstation; printer→printer;
  phone/mobile/tablet→mobile_device; network/switch/router/firewall/access
  point→network_device; else unknown). Explicit Save; persisted per tenant.
- **Client Hudu tab — Assets section** becomes an asset mapping manager,
  visually consistent with the company mapping manager: counters
  (mapped/suggested/unmapped), per-row Alga asset picker + status badge,
  row actions (revert / unmap / dismiss suggestion), Import per row,
  "Import all unmatched" button, staged-changes Save/Discard bar, and a
  "Sync from Hudu" button with last-synced timestamp and result summary.
  Mapped rows whose Hudu asset disappeared/archived show a **Stale** badge.
- **Client Documents tab — Hudu section**: collapsed-by-default section
  "Hudu Documentation (N)" listing articles name + updated_at + external-link
  icon. Only rendered when the Phase 1 client-tab gate passes (EE + flag +
  connected + mapped). No upload/edit affordances.
- **Documents page — Hudu tab**: tab visible when EE + flag + connected.
  Search box (server-side, passed to Hudu), paged table (25/page mirroring
  Hudu pages): article name, company name → resolved client name (or
  "Unmapped" badge), updated_at, open-in-Hudu. No bulk fetch of all pages.
- All new strings via i18n (en + de/es/fr/it/nl/pl/pt), following Phase 1
  key families (`integrations.hudu.assets.*`, `integrations.hudu.documents.*`,
  `documents.huduTab.*`, `clientDetails.huduDocs.*` as applicable).

## Functional Requirements

Assets — mapping:
- FR1. Asset mapping rows reuse `tenant_external_entity_mappings` with
  `integration_type='hudu'`, `alga_entity_type='asset'`,
  `external_entity_id=<hudu asset id>`; metadata carries
  `hudu_asset_name`, `hudu_company_id`, `asset_layout_id`,
  `asset_layout_name`, `primary_serial`, `url`. One-to-one both directions
  per tenant (existing unique indexes are scoped by `alga_entity_type`).
- FR2. Auto-suggest matches per Hudu asset against the client's Alga assets:
  serial exact (confidence 1.0) → name exact (0.9) → name fuzzy ≥0.8
  (reusing the Phase 1 normalized-Levenshtein matcher incl. suffix rules);
  one-to-one greedy claiming, mapped rows/assets excluded.
- FR3. Mapping UI follows the staged-changes pattern: picker stages, Save
  commits (clear+set for replace), Discard reverts, suggestions are
  confirmed by Save and dismissible per row.

Assets — import:
- FR4. Import creates an Alga asset via the existing `createAsset` action:
  `client_id` = the mapped client, `name` = Hudu asset name,
  `serial_number` = `primary_serial` (when present), `asset_type` = layout
  map lookup (fallback `unknown`), `asset_tag` = `primary_serial` if unique
  else `hudu-<hudu asset id>`, `status` = the tenant's default/first asset
  status (same default the manual create form uses). A mapping row is
  created atomically with the asset.
- FR5. "Import all unmatched" imports every unmapped, unsuggested Hudu asset
  for the client sequentially, reporting created/failed counts; individual
  failures don't abort the batch.
- FR6. Import requires the `asset` RBAC create permission (in addition to the
  Phase 1 client-tab gate); the UI hides Import affordances without it.

Assets — sync:
- FR7. "Sync from Hudu" re-fetches the company's Hudu assets and, for each
  mapped pair, updates the Alga asset's synced fields — `name`,
  `serial_number` — when they differ (Hudu wins on synced fields only;
  other Alga fields untouched). `asset_type` is not retro-changed.
- FR8. Sync flags mappings whose Hudu asset is archived/absent as stale
  (metadata `stale: true` + UI badge); it never deletes Alga assets or
  mappings. Unflagging happens automatically if the asset reappears.
- FR9. Sync records `last_synced_at` on affected mapping rows and surfaces a
  result summary (updated / unchanged / stale counts) in the UI.
- FR10. Sync requires the `asset` RBAC update permission.

Layout→type map:
- FR11. `hudu_integrations.settings.asset_layout_type_map` (jsonb:
  `{ "<layout_id>": "<alga asset_type>" }`) with server action get/set
  (system_settings update RBAC) and live layout listing via
  `GET /api/v1/asset_layouts`.
- FR12. Heuristic prefill computes suggested types for unconfigured layouts
  (UI-side); unconfigured layouts import as `unknown`.

Documents — client section:
- FR13. Client Documents tab renders a link-only "Hudu Documentation"
  section (name, updated_at, deep-link) using the Phase 1 per-company
  articles fetch/cache; same gate as the client Hudu tab; collapsed by
  default; independent error/empty states that never break the native
  documents UI.

Documents — global tab:
- FR14. A server action lists Hudu articles across companies (no
  `company_id` filter), one Hudu page per request (25 items), passing the
  user's search term to Hudu, and resolves each article's `company_id` to
  the mapped Alga client via the companies cache + mapping rows.
- FR15. Documents page "Hudu" tab renders the paged list with search,
  resolved client names ("Unmapped" badge otherwise), and deep-links.
  Visible only when EE + flag + connected; CE/flag-off tenants see no trace.
- FR16. All new server surfaces enforce the Phase 1 guard chain (EE add-on +
  tier + flag + RBAC) server-side, not just in the UI.

## Non-functional Requirements

- NFR1. Pull-only; no Hudu writes anywhere.
- NFR2. Respect Hudu limits: never fan out unbounded page fetches; bulk
  import/sync fetch the company's assets with bounded pagination and stop on
  rate-limit (429) with a typed, user-visible error.
- NFR3. Article content is never persisted; only ids/names/timestamps already
  cached for lists.
- NFR4. Mapping rows remain direction-agnostic (no pull-only columns).
- NFR5. New UI strings fully translated (8 locales) and pass the Phase 1
  i18n static checks (extended to new components).

## Data / Integration Notes

- No new tables. Asset mappings reuse `tenant_external_entity_mappings`
  (indexes verified: uniqueness is per `alga_entity_type`, so client and
  asset mappings coexist). Layout map lives in `hudu_integrations.settings`.
- New `HuduClient` surfaces: `GET /api/v1/asset_layouts`, global
  `GET /api/v1/articles?page=&search=` (verify Hudu's article search param
  name during implementation; fall back to `?name=` filter if needed).
- Alga asset creation: `createAsset` in `packages/assets/src/actions/
  assetActions.ts` (`CreateAssetRequest`: fixed `asset_type` enum, required
  `asset_tag`/`status`).
- Client Documents tab host: `ClientDetails.tsx` tab id `documents`;
  EE injection follows the Phase 1 `useHuduClientTab` precedent.
- Documents page: `packages/documents/src/components/DocumentsPage.tsx`.

## Risks

- R1. Hudu asset layouts are arbitrary per instance; the heuristic prefill
  will misclassify exotic layouts → mitigated by explicit admin map +
  `unknown` fallback.
- R2. `asset_tag` uniqueness semantics in Alga need verification before
  using `primary_serial` as tag (fallback `hudu-<id>` is always unique).
- R3. Cross-client article listing's client resolution depends on the
  companies cache freshness; stale cache shows "Unmapped" — acceptable,
  refreshable.
- R4. DocumentsPage is a CE package surface; the EE tab must be injected
  without breaking CE builds (follow the ClientDetails gate-hook pattern).

## Open Questions

- OQ1. Hudu global article search: exact query param (`search` vs `name`)
  and whether it spans body or title only — verify against the local
  instance during implementation.
- OQ2. Asset status default on import: confirm the tenant's default status
  source used by the manual create form and reuse it.

## Acceptance Criteria

- AC1. A technician can map, import (single + bulk), and sync a client's
  Hudu assets entirely from the client Hudu tab, with explicit Save
  confirmation and no destructive surprises (stale ≠ deleted).
- AC2. An imported asset appears in Alga's asset module with correct client,
  name, serial, and type per the layout map, and is immediately mapped.
- AC3. Sync updates renamed/re-serialed Hudu assets' mapped Alga twins and
  flags disappeared ones, reporting counts.
- AC4. The client Documents tab shows the mapped company's Hudu articles and
  deep-links correctly; unmapped/disconnected clients show nothing extra.
- AC5. The Documents page Hudu tab lists and searches articles across
  companies with correct client resolution and pagination; invisible on CE
  or with the flag off.
- AC6. All new strings translated in 8 locales; i18n static checks extended
  and green; full Hudu unit suite green.