Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/packages/search/src/indexed-entities.ts
T

177 lines
7.2 KiB
TypeScript

import { ALL_SEARCH_INDEXES } from "./schemas/index.js";
/**
* Central entity-registration convention for the permission-aware global search
* (M057 / M058), referenced by AGENTS.md DoD #16 and INTEGRATION-CONTRACTS §8.
*
* This sits ABOVE the low-level Meilisearch index schemas (`./schemas`): a
* registered entity declares which domain table it maps to, which Meilisearch
* `index` it is searched through, which document fields are queried, and the
* permission a user needs for the entity to appear in their global-search
* results. The global search reads this registry to know what to query and to
* permission-gate per result type.
*
* Each fachmodul registers its searchable entity here when it is built. HiveGrid
* fachentities (contact/company/lead/deal/project/…) are greenfield, so the
* registry starts empty and grows module by module — e.g. when M042 lands:
*
* contact: {
* table: "Kontakt",
* index: "crm_contacts",
* searchable: ["displayName", "email", "phone"],
* permission: "crm.read",
* }
*/
export type IndexedEntityConfig = {
/** Prisma model / domain table the entity maps to (e.g. "Kontakt"). */
table: string;
/** Meilisearch index this entity is searched through (must exist in ALL_SEARCH_INDEXES). */
index: string;
/** Document fields surfaced/queried for this entity in global search. */
searchable: string[];
/** Permission required for this entity to appear in a user's global-search results (M057). */
permission: string;
};
/** A registered entity together with its registry key. */
export type IndexedEntity = IndexedEntityConfig & { key: string };
/**
* The registry. Keys are stable global-search entity keys (used in result
* grouping + deep-link routing). Empty until fachmodule register their entities.
*/
export const indexedEntities = {
// Team chat (AK-P15b). Normal member search is executed against PostgreSQL
// with active-channel membership in the same RLS transaction. The central
// index is intentionally gated to tenant-wide chat auditors so a coarse
// global permission can never expose messages from an unreadable channel.
chatMessage: {
table: "TeamChatMessage",
index: "chat-messages",
searchable: ["body"],
permission: "chat.read_all_channels",
},
// Files (AK-P4a). Tenant-scoped; only files the user may read_all surface in
// global search (owner/link-scoped read_own visibility is enforced at the
// route layer, not here).
file: {
table: "File",
index: "files",
searchable: ["displayName", "notes", "tags"],
permission: "files.read_all",
},
// Tasks (AK-P4b). Tenant-scoped; only tasks the user may read_all surface in
// global search (owner/assignee/group read_own visibility is enforced at the
// route layer, not here).
task: {
table: "Task",
index: "tasks",
searchable: ["title", "description"],
permission: "tasks.read_all",
},
// CRM contacts (R-P6). Tenant-scoped; only contacts the user may read_all
// surface in global search (the owner/zustaendiger read_own visibility is
// enforced at the route layer, not here — mirroring file/task). One entry is
// sufficient: a Kontakt is the Oberbegriff for BOTH private persons
// (kontaktTyp = privatperson → vorname/nachname) and organisations
// (kontaktTyp = organisation → orgName), so there is no separate Firma/Company
// model or index — companies search through this same `contact` entry.
//
// `searchable` lists the `crm-contacts` Meilisearch *document* fields (English,
// = crmContactsIndex.searchableAttributes), NOT the German Kontakt columns:
// the typed Kontakt fields are projected onto these document keys when indexed
// (vorname → firstName, nachname → lastName, orgName → company, primaerEmail →
// email), exactly like the existing entity-builder contact feeder
// (apps/web/.../rowSearchOutbox.server.ts → rowToContactDocument).
contact: {
table: "Kontakt",
index: "crm-contacts",
searchable: ["firstName", "lastName", "email", "company", "jobTitle", "tags"],
permission: "crm.read_all",
},
company: {
table: "Kontakt",
index: "crm-contacts",
searchable: ["company", "email", "tags"],
permission: "crm.read_all",
},
lead: {
table: "InboxLead",
index: "crm-contacts",
searchable: ["firstName", "lastName", "email", "company", "tags"],
permission: "leads.read_all",
},
project: {
table: "Projekt",
index: "projects",
searchable: ["projectNumber", "name", "description", "type", "source"],
permission: "projects.read_all",
},
// Personnel directory (R-UX3). Only non-sensitive profile fields are
// searchable. `hr.read_own` is applied as a stricter self/direct-report
// fallback by the global-search service; tenant-wide results require the
// registry permission below.
employee: {
table: "HrEmployeeProfile",
index: "hr-directory",
searchable: ["name", "email", "position", "team"],
permission: "hr.read_all",
},
user: {
table: "TenantUser",
index: "users",
searchable: ["firstName", "lastName", "email"],
permission: "app.settings.members.view",
},
} satisfies Record<string, IndexedEntityConfig>;
export type IndexedEntityKey = keyof typeof indexedEntities;
export type IndexedEntityRegistry = Record<string, IndexedEntityConfig>;
/** All registered entities (with their keys), in declaration order. */
export function listIndexedEntities(registry: IndexedEntityRegistry = indexedEntities): IndexedEntity[] {
return Object.entries(registry).map(([key, config]) => ({ key, ...config }));
}
/** Look up a single registered entity by key. */
export function getIndexedEntity(key: string, registry: IndexedEntityRegistry = indexedEntities): IndexedEntity | undefined {
const config = registry[key];
return config ? { key, ...config } : undefined;
}
/**
* Entities the given permission set may see in global search (M057). Pass the
* caller's resolved permissions; only entities whose `permission` is granted
* are returned.
*/
export function getIndexedEntitiesForPermissions(
permissions: ReadonlySet<string> | readonly string[],
registry: IndexedEntityRegistry = indexedEntities
): IndexedEntity[] {
const granted = permissions instanceof Set ? permissions : new Set(permissions);
return listIndexedEntities(registry).filter((entity) => granted.has(entity.permission));
}
/**
* Integrity check: every registered entity must reference a known Meilisearch
* index. Returns a list of human-readable problems (empty = valid). Intended
* for a startup assertion / CI guard as the registry grows.
*/
export function validateIndexedEntities(registry: IndexedEntityRegistry = indexedEntities): string[] {
const knownIndexes = new Set(ALL_SEARCH_INDEXES.map((schema) => schema.name));
const problems: string[] = [];
for (const entity of listIndexedEntities(registry)) {
if (!knownIndexes.has(entity.index)) {
problems.push(`indexedEntities["${entity.key}"] references unknown search index "${entity.index}"`);
}
if (entity.searchable.length === 0) {
problems.push(`indexedEntities["${entity.key}"] has no searchable fields`);
}
if (entity.permission.length === 0) {
problems.push(`indexedEntities["${entity.key}"] has no permission`);
}
}
return problems;
}