Refresh HiveGrid Cloud reference snapshot

This commit is contained in:
david committed 2026-08-03 15:31:14 +02:00
1 parent 5e99e14772
commit 7f88026f79
5955 files changed
+1177325 -188362

No files matched your search

@@ -29,21 +29,37 @@ in phase 04 (#48). It is the user-facing complement to
- **Source of truth** is Postgres. Meilisearch is a projected read-side
populated asynchronously through the outbox pattern (#42).
- **Tenant isolation** is enforced inside `@hivegrid/search`. Every read
and write goes through `searchInIndex / bulkIndex / deleteFromIndex`
with an explicit `tenantId`. The wrapper injects
and write goes through the tenant-scoped package helpers with an explicit
`tenantId`. The wrapper injects
`tenantId = "<id>"` into the Meilisearch filter expression and
escapes the value to defeat filter injection. Raw Meilisearch SDK
access is not re-exported.
- **Estate namespace:** schemas, outbox payloads and worker pagers use logical
names such as `projects`. The `SearchClient` adapter is the only boundary
that maps them to physical Meilisearch UIDs (`hivegrid-projects`). Callers
never add the prefix themselves, and the adapter rejects already-prefixed
input so no unprefixed or double-prefixed namespace can be touched.
- **Graceful degradation:** every hot-path is wrapped in
`searchWithFallback`, which routes to the legacy SQL `LIKE`
implementation when Meilisearch raises a connectivity error. The
search stays degraded-but-up instead of returning 500s.
## User-Facing Contract
Since the 2026-07-12 scope cut, global search is exposed only as a Spotlight
overlay. On desktop it opens through Cmd+K/Ctrl+K or the header search trigger;
on mobile the header trigger opens a viewport-filling overlay. There is no
user-facing `/search` page, shareable search URL, or full-page filter/pagination
surface in v1. `/search/api` remains the protected, tenant-scoped internal
resource used by the overlay. `R-P11b` continues to consume the same index and
search contracts.
## Index Schema Reference
The current schemas live in `packages/search/src/schemas/`. Each is a
whitelist — only fields listed in `allowedDocumentFields` reach
Meilisearch.
Meilisearch. Names in this table are logical contract names; the physical UID
always has the estate prefix `hivegrid-`.
| Index | Searchable | Filterable | Sortable |
| -------------- | --------------------------------------------------- | ------------------------------------------------------ | --------------------------------------- |
@@ -73,13 +89,13 @@ one otherwise).
## Hot-Path Migrations
| Path | Migrated | Notes |
| ------------------------------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| KB public search (`KnowledgeBaseService.search`) | yes (#48) | wraps `findKnowledgeBaseArticles` via `searchKnowledgeBaseArticles` helper with `searchWithFallback`. Tenant id resolved from KB record. |
| CRM contact helper | shipped | `apps/web/app/modules/crm/services/crmContactSearch.server.ts` wraps `crm-contacts` with `searchWithFallback` and a tenant-scoped SQL fallback. |
| Rows helper | shipped | `apps/web/app/modules/rows/services/rowSearch.server.ts` wraps the `rows` index with an `entityId` filter and tenant-scoped SQL fallback. |
| CRM/Rows producer and callsite integration | yes | `RowsApi.getAll` calls `searchCrmContacts` for tenant-scoped CRM contact-list free-text filters and `searchRows` for other tenant-scoped row filters. `RowsApi.create / createSimple / update / del` emit `search.index.*` events through `rowSearchOutbox.server.ts`. Contact rows fan out to both `crm-contacts` and `rows`. |
| HiveGrid global-search producers | yes | `apps/web/app/services/search/searchIndexProjection.server.ts` publishes `search.index.*` events and mirrors `SearchIndexEntry` for Kontakt/Firma/Lead/Projekt/File/Task/User lifecycle mutations. Cmd+K and `/search` read through tenant- and permission-aware SQL+Meili search. |
| Path | Migrated | Notes |
| ------------------------------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| KB public search (`KnowledgeBaseService.search`) | yes (#48) | wraps `findKnowledgeBaseArticles` via `searchKnowledgeBaseArticles` helper with `searchWithFallback`. Tenant id resolved from KB record. |
| CRM contact helper | shipped | `apps/web/app/modules/crm/services/crmContactSearch.server.ts` wraps `crm-contacts` with `searchWithFallback` and a tenant-scoped SQL fallback. |
| Rows helper | shipped | `apps/web/app/modules/rows/services/rowSearch.server.ts` wraps the `rows` index with an `entityId` filter and tenant-scoped SQL fallback. |
| CRM/Rows producer and callsite integration | yes | `RowsApi.getAll` calls `searchCrmContacts` for tenant-scoped CRM contact-list free-text filters and `searchRows` for other tenant-scoped row filters. `RowsApi.create / createSimple / update / del` emit `search.index.*` events through `rowSearchOutbox.server.ts`. Contact rows fan out to both `crm-contacts` and `rows`. |
| HiveGrid global-search producers | yes | `apps/web/app/services/search/searchIndexProjection.server.ts` publishes `search.index.*` events and mirrors `SearchIndexEntry` for Kontakt/Firma/Lead/Projekt/File/Task/User lifecycle mutations. The Spotlight overlay reads through `/search/api` using tenant- and permission-aware SQL+Meili search. |
| Bulk reindex pagers | partial | `apps/worker/src/index.ts` registers `createSearchIndexerBulkPagers({ prisma })`; `BULK_REINDEX_SUPPORTED_INDEX_NAMES` exposes `kb-articles`, `crm-contacts`, `users`, and `projects`. File/task live producers are wired, but their disaster-recovery bulk pagers still need explicit coverage before `--index=all` can rebuild every projected index. |
Open hot-path gaps still serve from the legacy SQL path. Until a specific
@@ -98,10 +114,10 @@ post-write rather than inside the row mutation transaction.
```bash
# Reindex every supported bulk-reindex index for every tenant via outbox events.
# Today this means KB articles, CRM contacts, users, and projects; unsupported names are rejected.
pnpm cli search reindex --tenant=all --index=all
pnpm exec tsx packages/cli/bin/hivegrid-cli.mjs search reindex --tenant=all --index=all
# Reindex one tenant's KB articles.
pnpm cli search reindex --tenant=tnt_abc123 --index=kb-articles
pnpm exec tsx packages/cli/bin/hivegrid-cli.mjs search reindex --tenant=tnt_abc123 --index=kb-articles
```
The CLI never writes to Meilisearch directly. It produces
@@ -142,7 +158,7 @@ The Meilisearch volume is treated as cache. To rebuild from scratch:
1. `docker volume rm meilisearch-data` (after stopping the container).
2. Restart the container.
3. `pnpm cli search reindex --tenant=all --index=all`.
3. `pnpm exec tsx packages/cli/bin/hivegrid-cli.mjs search reindex --tenant=all --index=all`.
This rebuild currently covers the supported bulk-reindex set only:
`kb-articles`, `crm-contacts`, `users`, and `projects`. Entities require a