From c60f8aae24a78f2a9d09b55037f632cbb78d3ade Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 29 Oct 2026 09:49:29 +0000 Subject: [PATCH] docs(i18n): delete the stale ja/de/es/fr/ko pages and sync their sidebars Phase 0 of the other-locale plan. Every ja, de, es, fr and ko page was stale (10 per locale), and a stale translation renders claims the English source no longer makes. Deleting them lets those readers fall back to the current English page with the locale's chrome. The five configure/permissions sidebars also lacked hierarchy-visibility; their pages arrays now equal the English meta.json. Translated titles stay. Fixes #384 Co-Authored-By: Claude Claude-Session: https://claude.ai/code/session_01QsR2jQwFe3sMgr7BPeEk4B --- content/docs/build/ai-skills.de.mdx | 117 -------- content/docs/build/ai-skills.es.mdx | 119 -------- content/docs/build/ai-skills.fr.mdx | 122 -------- content/docs/build/ai-skills.ja.mdx | 116 -------- content/docs/build/ai-skills.ko.mdx | 117 -------- content/docs/build/interface/views.de.mdx | 263 ------------------ content/docs/build/interface/views.es.mdx | 256 ----------------- content/docs/build/interface/views.fr.mdx | 256 ----------------- content/docs/build/interface/views.ja.mdx | 255 ----------------- content/docs/build/interface/views.ko.mdx | 255 ----------------- content/docs/build/marketplace.de.mdx | 130 --------- content/docs/build/marketplace.es.mdx | 131 --------- content/docs/build/marketplace.fr.mdx | 136 --------- content/docs/build/marketplace.ja.mdx | 128 --------- content/docs/build/marketplace.ko.mdx | 123 -------- content/docs/configure/api-access.de.mdx | 140 ---------- content/docs/configure/api-access.es.mdx | 140 ---------- content/docs/configure/api-access.fr.mdx | 143 ---------- content/docs/configure/api-access.ja.mdx | 135 --------- content/docs/configure/api-access.ko.mdx | 131 --------- content/docs/configure/authentication.de.mdx | 127 --------- content/docs/configure/authentication.es.mdx | 124 --------- content/docs/configure/authentication.fr.mdx | 124 --------- content/docs/configure/authentication.ja.mdx | 102 ------- content/docs/configure/authentication.ko.mdx | 126 --------- .../docs/configure/permissions/meta.de.json | 2 +- .../docs/configure/permissions/meta.es.json | 2 +- .../docs/configure/permissions/meta.fr.json | 2 +- .../docs/configure/permissions/meta.ja.json | 2 +- .../docs/configure/permissions/meta.ko.json | 2 +- .../permissions/permission-sets.de.mdx | 114 -------- .../permissions/permission-sets.es.mdx | 114 -------- .../permissions/permission-sets.fr.mdx | 114 -------- .../permissions/permission-sets.ja.mdx | 99 ------- .../permissions/permission-sets.ko.mdx | 112 -------- .../permissions/record-access.de.mdx | 64 ----- .../permissions/record-access.es.mdx | 63 ----- .../permissions/record-access.fr.mdx | 63 ----- .../permissions/record-access.ja.mdx | 59 ---- .../permissions/record-access.ko.mdx | 62 ----- content/docs/configure/storage.de.mdx | 193 ------------- content/docs/configure/storage.es.mdx | 194 ------------- content/docs/configure/storage.fr.mdx | 200 ------------- content/docs/configure/storage.ja.mdx | 194 ------------- content/docs/configure/storage.ko.mdx | 191 ------------- content/docs/configure/system-settings.de.mdx | 91 ------ content/docs/configure/system-settings.es.mdx | 89 ------ content/docs/configure/system-settings.fr.mdx | 89 ------ content/docs/configure/system-settings.ja.mdx | 89 ------ content/docs/configure/system-settings.ko.mdx | 89 ------ content/docs/configure/webhooks.de.mdx | 115 -------- content/docs/configure/webhooks.es.mdx | 110 -------- content/docs/configure/webhooks.fr.mdx | 116 -------- content/docs/configure/webhooks.ja.mdx | 110 -------- content/docs/configure/webhooks.ko.mdx | 101 ------- 55 files changed, 5 insertions(+), 6656 deletions(-) delete mode 100644 content/docs/build/ai-skills.de.mdx delete mode 100644 content/docs/build/ai-skills.es.mdx delete mode 100644 content/docs/build/ai-skills.fr.mdx delete mode 100644 content/docs/build/ai-skills.ja.mdx delete mode 100644 content/docs/build/ai-skills.ko.mdx delete mode 100644 content/docs/build/interface/views.de.mdx delete mode 100644 content/docs/build/interface/views.es.mdx delete mode 100644 content/docs/build/interface/views.fr.mdx delete mode 100644 content/docs/build/interface/views.ja.mdx delete mode 100644 content/docs/build/interface/views.ko.mdx delete mode 100644 content/docs/build/marketplace.de.mdx delete mode 100644 content/docs/build/marketplace.es.mdx delete mode 100644 content/docs/build/marketplace.fr.mdx delete mode 100644 content/docs/build/marketplace.ja.mdx delete mode 100644 content/docs/build/marketplace.ko.mdx delete mode 100644 content/docs/configure/api-access.de.mdx delete mode 100644 content/docs/configure/api-access.es.mdx delete mode 100644 content/docs/configure/api-access.fr.mdx delete mode 100644 content/docs/configure/api-access.ja.mdx delete mode 100644 content/docs/configure/api-access.ko.mdx delete mode 100644 content/docs/configure/authentication.de.mdx delete mode 100644 content/docs/configure/authentication.es.mdx delete mode 100644 content/docs/configure/authentication.fr.mdx delete mode 100644 content/docs/configure/authentication.ja.mdx delete mode 100644 content/docs/configure/authentication.ko.mdx delete mode 100644 content/docs/configure/permissions/permission-sets.de.mdx delete mode 100644 content/docs/configure/permissions/permission-sets.es.mdx delete mode 100644 content/docs/configure/permissions/permission-sets.fr.mdx delete mode 100644 content/docs/configure/permissions/permission-sets.ja.mdx delete mode 100644 content/docs/configure/permissions/permission-sets.ko.mdx delete mode 100644 content/docs/configure/permissions/record-access.de.mdx delete mode 100644 content/docs/configure/permissions/record-access.es.mdx delete mode 100644 content/docs/configure/permissions/record-access.fr.mdx delete mode 100644 content/docs/configure/permissions/record-access.ja.mdx delete mode 100644 content/docs/configure/permissions/record-access.ko.mdx delete mode 100644 content/docs/configure/storage.de.mdx delete mode 100644 content/docs/configure/storage.es.mdx delete mode 100644 content/docs/configure/storage.fr.mdx delete mode 100644 content/docs/configure/storage.ja.mdx delete mode 100644 content/docs/configure/storage.ko.mdx delete mode 100644 content/docs/configure/system-settings.de.mdx delete mode 100644 content/docs/configure/system-settings.es.mdx delete mode 100644 content/docs/configure/system-settings.fr.mdx delete mode 100644 content/docs/configure/system-settings.ja.mdx delete mode 100644 content/docs/configure/system-settings.ko.mdx delete mode 100644 content/docs/configure/webhooks.de.mdx delete mode 100644 content/docs/configure/webhooks.es.mdx delete mode 100644 content/docs/configure/webhooks.fr.mdx delete mode 100644 content/docs/configure/webhooks.ja.mdx delete mode 100644 content/docs/configure/webhooks.ko.mdx diff --git a/content/docs/build/ai-skills.de.mdx b/content/docs/build/ai-skills.de.mdx deleted file mode 100644 index d0715e78..00000000 --- a/content/docs/build/ai-skills.de.mdx +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: IDE-Skills (Claude Code / Cursor / Copilot) -description: Installieren Sie ObjectOS-Skills in Ihren Coding-Agent, damit Claude Code, Cursor, Copilot, Codex und Co. wissen, wie man ObjectOS-Metadaten korrekt erstellt. -translation: - source_sha: 13dc900bd554134c9584ba12f7505b6c43049269fbf5d0fa94e125e5584021dc - guide_rev: 1 - mode: auto ---- - -Der [AI Builder](./ai-builder) lebt innerhalb der Console und kommuniziert mit der -Datenbank Ihres Mandanten. Aber manchmal möchten Sie dasselbe Domänenwissen -direkt in Ihrer IDE — wenn Sie `*.object.ts` von Hand bearbeiten, einen -Flow entwerfen oder Cursor bitten, ein CEL-Prädikat zu schreiben. - -ObjectOS liefert **9 First-Party-Agent-Skills** mit, die Coding-Assistenten -beibringen, wie man jede Art von ObjectOS-Metadaten erstellt. Sie werden -über das offene [`skills`](https://www.npmjs.com/package/skills)-Ökosystem -(Vercel Labs) verteilt und funktionieren mit **Claude Code, Cursor, Copilot, -Codex, Gemini CLI, Windsurf, Cline, Continue, Roo, Goose, Kiro, -opencode** und etwa 50 weiteren Agents. - -## Installation - -In jedem Projekt, das `@objectstack/*`-Pakete verwendet: - -```bash -npx skills add objectstack-ai/objectstack/skills -``` - -Die CLI erkennt, welche Agents Sie konfiguriert haben (`.claude/`, -`.cursor/`, `.github/copilot/`, `AGENTS.md` usw.) und schreibt die -Skills an die richtige Stelle. Führen Sie den Befehl jederzeit erneut aus, -um die neuesten Versionen zu beziehen. - -> Keine Änderung an `package.json`, keine globale Installation. Skills sind -> reine Markdown-Dateien, die in Ihr Repository committet werden, sodass das -> gesamte Team — und CI-Agents — dieselben Anweisungen teilen. - -## Was Sie erhalten - -| Skill | Laden, wenn Sie an … arbeiten | -|:------|:-----------------------------| -| `objectstack-platform` | `defineStack`, Drivern, Adaptern, Plugins, Services, der `os`-CLI, Deployment | -| `objectstack-data` | `*.object.ts`, `*.seed.ts`, Feldern, Beziehungen, Validierungen, Indizes, Lifecycle-Hooks, RLS | -| `objectstack-query` | ObjectQL — Filter, Sortierung, Pagination, Aggregation, Joins, Window-Funktionen, Volltextsuche | -| `objectstack-ui` | Views, Apps, Pages, Dashboards, Reports, Charts, Actions | -| `objectstack-automation` | Flows, Workflows, Triggers, Approvals, Zeitplänen, Webhooks | -| `objectstack-ai` | Agents, Tools, Skills, Conversations, Model Registry, MCP | -| `objectstack-api` | REST/GraphQL-Endpunkten, Auth, Realtime, Error-Envelopes | -| `objectstack-i18n` | Übersetzungs-Bundles, Locale-Fallback, Abdeckung | -| `objectstack-formula` | CEL-Ausdrücken — Formelfeldern, Validierungs-/Sharing-/Sichtbarkeits-Prädikaten, Bedingungen | - -Jeder Skill ist **scope-aware** — er teilt dem Agent mit, wann er sich -selbst laden und wann er an einen verwandten Skill verweisen soll, sodass -Claude nicht versucht, ein Objekt mit dem Platform-Skill zu modellieren oder -einen CEL-Ausdruck mit dem Data-Skill zu schreiben. - -## Wie es funktioniert - -Jeder Skill ist ein Ordner unter `skills/` im -[Framework-Repo](https://github.com/objectstack-ai/objectstack/tree/main/skills): - -``` -skills/objectstack-data/ -├── SKILL.md # YAML frontmatter + prose guide -├── references/ -│ └── _index.md # pointers into @objectstack/spec Zod sources -└── rules/ # optional deep-dive rules -``` - -Das Frontmatter in `SKILL.md` ist das, was `skills add` liest, um den -Skill an die richtige Agent-Oberfläche zu leiten: - -```yaml ---- -name: objectstack-data -description: Design ObjectStack data schemas — objects, fields, ... -license: Apache-2.0 -compatibility: Requires @objectstack/spec Zod schemas (v4+) -metadata: - domain: data - tags: object, field, validation, relationship, hook, permission, rls ---- -``` - -Eine zentrale Regel über alle Skills hinweg: **Die Zod-Schemas in -`@objectstack/spec` sind die Wahrheit**. Skills vermitteln die Absicht; -Agents lesen die Schemas in `node_modules/@objectstack/spec/src/**/*.zod.ts` -für die exakten Feldformen. Deshalb verschwinden halluzinierte Felder -praktisch, sobald die Skills installiert sind. - -## Skills vs. AI Builder - -| | [AI Builder](./ai-builder) | IDE-Skills | -|:--|:--|:--| -| Wo es läuft | Console (Browser) | Ihre IDE / Ihr Coding-Agent | -| Was es ändert | Live-Metadaten in Ihrem Mandanten | Dateien in Ihrem Repository | -| Handelt im Namen von | Ihren Endnutzern / Admins | Ihren Entwicklern | -| Genehmigungsmodell | HITL-Warteschlange (`ai:approve`) | Pull-Request-Review | -| Am besten für | Tägliche Erweiterungen, No-Code-Nutzer | Templates, Pakete, komplexe Flows, Bibliothekscode | - -Die beiden ergänzen sich. Die meisten Teams nutzen den AI Builder für die -Mandantenanpassung und IDE-Skills bei der Arbeit an **Paketen, die sie -veröffentlichen wollen** (siehe [Templates](./templates) und [Marketplace](./marketplace)). - -## Aktualisieren - -Die Skills folgen den `@objectstack/spec`-Versionen. Führen Sie -`npx skills add objectstack-ai/objectstack/skills` nach dem Upgrade des Spec-Pakets -erneut aus, um Ihren Agent mit den neuesten Zod-Schemas, CEL-Helfern und -dem Metadaten-Vokabular synchron zu halten. - -## Verwandt - -- [AI Builder](./ai-builder) — das Gegenstück innerhalb der Console -- [Agents](./agents) — deklarieren Sie serverseitige Agents, die *innerhalb* von ObjectOS laufen -- [Templates](./templates) — jedes offizielle Template wird mit diesen geladenen Skills erstellt diff --git a/content/docs/build/ai-skills.es.mdx b/content/docs/build/ai-skills.es.mdx deleted file mode 100644 index 014157a6..00000000 --- a/content/docs/build/ai-skills.es.mdx +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: AI Skills para IDE (Claude Code / Cursor / Copilot) -description: Instala las skills de ObjectOS en tu agente de programación para que Claude Code, Cursor, Copilot, Codex y similares sepan cómo crear correctamente metadatos de ObjectOS. -translation: - source_sha: 13dc900bd554134c9584ba12f7505b6c43049269fbf5d0fa94e125e5584021dc - guide_rev: 1 - mode: auto ---- - -El [AI Builder](./ai-builder) vive dentro de Console y se comunica con la -base de datos de tu tenant. Pero a veces quieres ese mismo conocimiento -de dominio dentro de tu IDE — cuando editas a mano `*.object.ts`, diseñas -un flow o le pides a Cursor que escriba un predicado CEL. - -ObjectOS incluye **9 AI Skills de agente de primera categoría** que enseñan -a los asistentes de programación cómo crear todo tipo de metadatos de -ObjectOS. Se distribuyen a través del ecosistema abierto -[`skills`](https://www.npmjs.com/package/skills) (Vercel Labs) y funcionan -con **Claude Code, Cursor, Copilot, Codex, Gemini CLI, Windsurf, Cline, -Continue, Roo, Goose, Kiro, opencode** y ~50 agentes más. - -## Instalación - -En cualquier proyecto que use paquetes `@objectstack/*`: - -```bash -npx skills add objectstack-ai/objectstack/skills -``` - -El CLI detecta qué agentes tienes configurados (`.claude/`, -`.cursor/`, `.github/copilot/`, `AGENTS.md`, etc.) y escribe las -skills en el lugar correcto. Vuelve a ejecutarlo en cualquier momento -para obtener las últimas versiones. - -> No hay cambios en `package.json` ni instalación global. Las skills son -> simples archivos markdown incluidos en tu repositorio, de modo que todo -> el equipo — y los agentes de CI — comparten las mismas instrucciones. - -## Qué obtienes - -| Skill | Cárgala cuando trabajes en… | -|:------|:-----------------------------| -| `objectstack-platform` | `defineStack`, drivers, adaptadores, plugins, servicios, el CLI `os`, despliegue | -| `objectstack-data` | `*.object.ts`, `*.seed.ts`, campos, relaciones, validaciones, índices, hooks de ciclo de vida, RLS | -| `objectstack-query` | ObjectQL — filtros, ordenación, paginación, agregación, joins, funciones de ventana, búsqueda de texto completo | -| `objectstack-ui` | Views, Apps, Pages, Dashboards, Reports, Charts, Actions | -| `objectstack-automation` | Flows, Workflows, Triggers, Approvals, programaciones, webhooks | -| `objectstack-ai` | Agents, Tools, Skills, Conversations, Model Registry, MCP | -| `objectstack-api` | Endpoints REST/GraphQL, autenticación, tiempo real, envelopes de error | -| `objectstack-i18n` | Paquetes de traducción, fallback de locales, cobertura | -| `objectstack-formula` | Expresiones CEL — campos de fórmula, predicados de validación/compartición/visibilidad, condiciones | - -Cada skill **conoce su alcance** — le indica al agente cuándo cargarse y -cuándo delegar en una skill hermana, de modo que Claude no intente modelar -un objeto con la skill de plataforma ni escribir una expresión CEL con la -skill de datos. - -## Cómo funciona - -Cada skill es una carpeta dentro de `skills/` en el -[repositorio del framework](https://github.com/objectstack-ai/objectstack/tree/main/skills): - -``` -skills/objectstack-data/ -├── SKILL.md # YAML frontmatter + prose guide -├── references/ -│ └── _index.md # pointers into @objectstack/spec Zod sources -└── rules/ # optional deep-dive rules -``` - -El frontmatter de `SKILL.md` es lo que lee `skills add` para enrutar la -skill a la superficie de agente correcta: - -```yaml ---- -name: objectstack-data -description: Design ObjectStack data schemas — objects, fields, ... -license: Apache-2.0 -compatibility: Requires @objectstack/spec Zod schemas (v4+) -metadata: - domain: data - tags: object, field, validation, relationship, hook, permission, rls ---- -``` - -Una regla fundamental en todas las skills: **los esquemas Zod en -`@objectstack/spec` son la fuente de verdad**. Las skills aportan la -intención; los agentes leen los esquemas en -`node_modules/@objectstack/spec/src/**/*.zod.ts` para conocer las formas -exactas de los campos. Por eso los campos alucinados desaparecen -efectivamente una vez instaladas las skills. - -## Skills frente a AI Builder - -| | [AI Builder](./ai-builder) | AI Skills para IDE | -|:--|:--|:--| -| Dónde se ejecuta | Console (navegador) | Tu IDE / agente de programación | -| Qué modifica | Metadatos en vivo en tu tenant | Archivos en tu repositorio | -| Actúa en nombre de | Tus usuarios finales / administradores | Tus desarrolladores | -| Modelo de aprobación | Cola HITL (`ai:approve`) | Revisión de pull request | -| Ideal para | Extensiones del día a día, usuarios no-code | Plantillas, paquetes, flows complejos, código de librería | - -Ambos son complementarios. La mayoría de los equipos usan el AI Builder -para la personalización del tenant y las AI Skills para IDE al trabajar en -**paquetes que pretenden publicar** (consulta [Templates](./templates) y -[Marketplace](./marketplace)). - -## Actualización - -Las skills siguen las versiones de `@objectstack/spec`. Vuelve a ejecutar -`npx skills add objectstack-ai/objectstack/skills` tras actualizar el paquete spec -para mantener tu agente sincronizado con los últimos esquemas Zod, -helpers de CEL y vocabulario de metadatos. - -## Relacionado - -- [AI Builder](./ai-builder) — la contraparte dentro de Console -- [Agents](./agents) — declara agentes del lado del servidor que se ejecutan *dentro* de ObjectOS -- [Templates](./templates) — cada plantilla oficial se construye con estas skills cargadas diff --git a/content/docs/build/ai-skills.fr.mdx b/content/docs/build/ai-skills.fr.mdx deleted file mode 100644 index b8249378..00000000 --- a/content/docs/build/ai-skills.fr.mdx +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: Skills IDE (Claude Code / Cursor / Copilot) -description: Installez les skills ObjectOS dans votre agent de codage afin que Claude Code, Cursor, Copilot, Codex et compagnie sachent rédiger correctement les métadonnées ObjectOS. -translation: - source_sha: 13dc900bd554134c9584ba12f7505b6c43049269fbf5d0fa94e125e5584021dc - guide_rev: 1 - mode: auto ---- - -L'[AI Builder](./ai-builder) vit dans Console et communique avec la -base de données de votre tenant. Mais il arrive que vous vouliez les -mêmes connaissances métier directement dans votre IDE — lorsque vous -éditez à la main des `*.object.ts`, concevez un flow ou demandez à -Cursor d'écrire un prédicat CEL. - -ObjectOS fournit **9 agent skills first-party** qui apprennent aux -assistants de codage à rédiger tous les types de métadonnées ObjectOS. -Ils sont distribués via l'écosystème ouvert -[`skills`](https://www.npmjs.com/package/skills) (Vercel Labs) et -fonctionnent avec **Claude Code, Cursor, Copilot, Codex, Gemini CLI, -Windsurf, Cline, Continue, Roo, Goose, Kiro, opencode** et une -cinquantaine d'autres agents. - -## Installation - -Dans n'importe quel projet utilisant les packages `@objectstack/*` : - -```bash -npx skills add objectstack-ai/objectstack/skills -``` - -La CLI détecte les agents que vous avez configurés (`.claude/`, -`.cursor/`, `.github/copilot/`, `AGENTS.md`, etc.) et écrit les skills -au bon endroit. Relancez-la à tout moment pour récupérer les dernières -versions. - -> Aucune modification de `package.json`, aucune installation globale. -> Les skills sont de simples fichiers markdown commités dans votre dépôt -> afin que toute l'équipe — ainsi que les agents de CI — partagent les -> mêmes instructions. - -## Ce que vous obtenez - -| Skill | À charger quand vous travaillez sur… | -|:------|:-----------------------------| -| `objectstack-platform` | `defineStack`, drivers, adaptateurs, plugins, services, la CLI `os`, le déploiement | -| `objectstack-data` | `*.object.ts`, `*.seed.ts`, champs, relations, validations, index, hooks de cycle de vie, RLS | -| `objectstack-query` | ObjectQL — filtres, tri, pagination, agrégation, jointures, fonctions de fenêtrage, recherche plein texte | -| `objectstack-ui` | Views, Apps, Pages, Dashboards, Reports, Charts, Actions | -| `objectstack-automation` | Flows, Workflows, Triggers, Approvals, planifications, webhooks | -| `objectstack-ai` | Agents, Tools, Skills, Conversations, Model Registry, MCP | -| `objectstack-api` | endpoints REST/GraphQL, authentification, temps réel, enveloppes d'erreur | -| `objectstack-i18n` | bundles de traduction, repli de locale, couverture | -| `objectstack-formula` | expressions CEL — champs de formule, prédicats de validation/partage/visibilité, conditions | - -Chaque skill est **conscient de son périmètre** — il indique à l'agent -quand se charger lui-même et quand déléguer à un skill voisin, afin que -Claude n'essaie pas de modéliser un objet avec le skill platform ni -d'écrire une expression CEL avec le skill data. - -## Comment ça fonctionne - -Chaque skill est un dossier sous `skills/` dans le -[dépôt framework](https://github.com/objectstack-ai/objectstack/tree/main/skills) : - -``` -skills/objectstack-data/ -├── SKILL.md # YAML frontmatter + prose guide -├── references/ -│ └── _index.md # pointers into @objectstack/spec Zod sources -└── rules/ # optional deep-dive rules -``` - -Le frontmatter du `SKILL.md` est ce que `skills add` lit pour router -le skill vers la bonne surface d'agent : - -```yaml ---- -name: objectstack-data -description: Design ObjectStack data schemas — objects, fields, ... -license: Apache-2.0 -compatibility: Requires @objectstack/spec Zod schemas (v4+) -metadata: - domain: data - tags: object, field, validation, relationship, hook, permission, rls ---- -``` - -Une règle fondamentale dans tous les skills : **les schémas Zod de -`@objectstack/spec` font foi**. Les skills donnent l'intention ; les -agents lisent les schémas dans -`node_modules/@objectstack/spec/src/**/*.zod.ts` pour connaître la -forme exacte des champs. C'est pourquoi les champs hallucinés -disparaissent de fait une fois les skills installés. - -## Skills vs. AI Builder - -| | [AI Builder](./ai-builder) | Skills IDE | -|:--|:--|:--| -| Où ça s'exécute | Console (navigateur) | Votre IDE / agent de codage | -| Ce que ça modifie | Métadonnées en direct dans votre tenant | Fichiers de votre dépôt | -| Agit pour le compte de | Vos utilisateurs finaux / admins | Vos développeurs | -| Modèle d'approbation | File HITL (`ai:approve`) | Revue de pull request | -| Idéal pour | Extensions du quotidien, utilisateurs no-code | Templates, packages, flows complexes, code de bibliothèque | - -Les deux sont complémentaires. La plupart des équipes utilisent l'AI -Builder pour la personnalisation du tenant et les skills IDE lorsqu'elles -travaillent sur des **packages qu'elles comptent publier** (voir -[Templates](./templates) et [Marketplace](./marketplace)). - -## Mise à jour - -Les skills suivent les versions de `@objectstack/spec`. Relancez -`npx skills add objectstack-ai/objectstack/skills` après avoir mis à niveau le -package spec pour garder votre agent synchronisé avec les derniers -schémas Zod, helpers CEL et vocabulaire de métadonnées. - -## Voir aussi - -- [AI Builder](./ai-builder) — l'équivalent intégré à Console -- [Agents](./agents) — déclarez des agents côté serveur qui s'exécutent *à l'intérieur* d'ObjectOS -- [Templates](./templates) — chaque template officiel est conçu avec ces skills chargés diff --git a/content/docs/build/ai-skills.ja.mdx b/content/docs/build/ai-skills.ja.mdx deleted file mode 100644 index 4ae09af0..00000000 --- a/content/docs/build/ai-skills.ja.mdx +++ /dev/null @@ -1,116 +0,0 @@ ---- -title: IDE スキル (Claude Code / Cursor / Copilot) -description: ObjectOS スキルをコーディングエージェントにインストールして、Claude Code、Cursor、Copilot、Codex などが ObjectOS メタデータを正しく作成できるようにします。 -translation: - source_sha: 13dc900bd554134c9584ba12f7505b6c43049269fbf5d0fa94e125e5584021dc - guide_rev: 1 - mode: auto ---- - -[AI Builder](./ai-builder) は Console の内部に存在し、テナントの -データベースとやり取りします。しかし、IDE の中で同じドメイン知識が -欲しい場面もあります。たとえば `*.object.ts` を手作業で編集したり、 -フローを設計したり、Cursor に CEL 述語を書かせたりするときです。 - -ObjectOS は **9 個のファーストパーティ製エージェントスキル** を提供しており、 -あらゆる種類の ObjectOS メタデータの作成方法をコーディングアシスタントに教えます。 -これらはオープンな [`skills`](https://www.npmjs.com/package/skills) -エコシステム (Vercel Labs) を通じて配布され、**Claude Code、Cursor、Copilot、 -Codex、Gemini CLI、Windsurf、Cline、Continue、Roo、Goose、Kiro、 -opencode** およびその他約 50 種類のエージェントで動作します。 - -## インストール - -`@objectstack/*` パッケージを使用しているプロジェクトであればどこでも: - -```bash -npx skills add objectstack-ai/objectstack/skills -``` - -CLI は構成済みのエージェント (`.claude/`、`.cursor/`、`.github/copilot/`、 -`AGENTS.md` など) を検出し、スキルを適切な場所に書き込みます。 -最新バージョンを取得するには、いつでも再実行してください。 - -> `package.json` の変更も、グローバルインストールも不要です。スキルは -> リポジトリにコミットされるプレーンな Markdown ファイルなので、チーム全体 — -> そして CI エージェント — が同じ指示を共有できます。 - -## 得られるもの - -| スキル | 読み込むタイミング(作業対象) | -|:------|:-----------------------------| -| `objectstack-platform` | `defineStack`、ドライバー、アダプター、プラグイン、サービス、`os` CLI、デプロイ | -| `objectstack-data` | `*.object.ts`、`*.seed.ts`、フィールド、リレーションシップ、バリデーション、インデックス、ライフサイクルフック、RLS | -| `objectstack-query` | ObjectQL — フィルター、ソート、ページネーション、集計、結合、ウィンドウ関数、全文検索 | -| `objectstack-ui` | Views、Apps、Pages、Dashboards、Reports、Charts、Actions | -| `objectstack-automation` | Flows、Workflows、Triggers、Approvals、スケジュール、Webhook | -| `objectstack-ai` | Agents、Tools、Skills、Conversations、Model Registry、MCP | -| `objectstack-api` | REST/GraphQL エンドポイント、認証、リアルタイム、エラーエンベロープ | -| `objectstack-i18n` | 翻訳バンドル、ロケールフォールバック、カバレッジ | -| `objectstack-formula` | CEL 式 — 数式フィールド、バリデーション/共有/可視性の述語、条件 | - -各スキルは **スコープを認識** しており、いつ自身を読み込み、いつ兄弟スキルに -委譲すべきかをエージェントに伝えます。そのため Claude が platform スキルで -オブジェクトをモデリングしようとしたり、data スキルで CEL 式を書こうとしたりすることはありません。 - -## 仕組み - -すべてのスキルは -[framework リポジトリ](https://github.com/objectstack-ai/objectstack/tree/main/skills) -の `skills/` 配下にあるフォルダーです: - -``` -skills/objectstack-data/ -├── SKILL.md # YAML frontmatter + prose guide -├── references/ -│ └── _index.md # pointers into @objectstack/spec Zod sources -└── rules/ # optional deep-dive rules -``` - -`SKILL.md` の frontmatter は、`skills add` がスキルを適切なエージェント -サーフェスへルーティングするために読み取るものです: - -```yaml ---- -name: objectstack-data -description: Design ObjectStack data schemas — objects, fields, ... -license: Apache-2.0 -compatibility: Requires @objectstack/spec Zod schemas (v4+) -metadata: - domain: data - tags: object, field, validation, relationship, hook, permission, rls ---- -``` - -すべてのスキルに共通する中核的なルール: **`@objectstack/spec` 内の Zod -スキーマが真実です**。スキルは意図を与え、エージェントは正確なフィールドの -形状を得るために `node_modules/@objectstack/spec/src/**/*.zod.ts` の -スキーマを読み取ります。これが、スキルをインストールすると幻覚的な -フィールドが事実上消える理由です。 - -## スキル vs. AI Builder - -| | [AI Builder](./ai-builder) | IDE スキル | -|:--|:--|:--| -| 実行される場所 | Console (ブラウザー) | あなたの IDE / コーディングエージェント | -| 変更対象 | テナント内のライブメタデータ | リポジトリ内のファイル | -| 代理する対象 | エンドユーザー / 管理者 | 開発者 | -| 承認モデル | HITL キュー (`ai:approve`) | プルリクエストレビュー | -| 最適な用途 | 日常的な拡張、ノーコードユーザー | テンプレート、パッケージ、複雑なフロー、ライブラリコード | - -両者は補完的な関係です。多くのチームは、テナントのカスタマイズには -AI Builder を使い、**公開を意図したパッケージ** を扱う際には IDE スキルを -使います ([Templates](./templates) と [Marketplace](./marketplace) を参照)。 - -## 更新 - -スキルは `@objectstack/spec` のバージョンに追従します。spec パッケージを -アップグレードした後に `npx skills add objectstack-ai/objectstack/skills` を再実行して、 -エージェントを最新の Zod スキーマ、CEL ヘルパー、メタデータ語彙と -同期させてください。 - -## 関連項目 - -- [AI Builder](./ai-builder) — Console 内のカウンターパート -- [Agents](./agents) — ObjectOS の *内部* で実行されるサーバーサイドエージェントを宣言する -- [Templates](./templates) — すべての公式テンプレートはこれらのスキルを読み込んで構築されている diff --git a/content/docs/build/ai-skills.ko.mdx b/content/docs/build/ai-skills.ko.mdx deleted file mode 100644 index 870b30fe..00000000 --- a/content/docs/build/ai-skills.ko.mdx +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: IDE Skills (Claude Code / Cursor / Copilot) -description: 코딩 에이전트에 ObjectOS skills를 설치하여 Claude Code, Cursor, Copilot, Codex 등이 ObjectOS 메타데이터를 올바르게 작성하는 방법을 알도록 하세요. -translation: - source_sha: 13dc900bd554134c9584ba12f7505b6c43049269fbf5d0fa94e125e5584021dc - guide_rev: 1 - mode: auto ---- - -[AI Builder](./ai-builder)는 Console 안에서 동작하며 테넌트의 -데이터베이스와 통신합니다. 하지만 때로는 동일한 도메인 지식을 IDE -안에서 사용하고 싶을 때가 있습니다 — `*.object.ts`를 직접 편집하거나, -플로우를 설계하거나, Cursor에게 CEL 술어를 작성하라고 요청할 때처럼요. - -ObjectOS는 코딩 어시스턴트에게 모든 종류의 ObjectOS 메타데이터를 -작성하는 방법을 가르치는 **9개의 퍼스트파티 에이전트 skills**를 -제공합니다. 이 skills는 오픈 [`skills`](https://www.npmjs.com/package/skills) -생태계(Vercel Labs)를 통해 배포되며 **Claude Code, Cursor, Copilot, -Codex, Gemini CLI, Windsurf, Cline, Continue, Roo, Goose, Kiro, -opencode** 및 그 외 약 50개의 에이전트와 함께 작동합니다. - -## 설치 - -`@objectstack/*` 패키지를 사용하는 모든 프로젝트에서: - -```bash -npx skills add objectstack-ai/objectstack/skills -``` - -CLI는 어떤 에이전트가 구성되어 있는지(`.claude/`, -`.cursor/`, `.github/copilot/`, `AGENTS.md` 등) 감지하고 skills를 -적절한 위치에 작성합니다. 최신 버전을 가져오려면 언제든지 다시 -실행하세요. - -> `package.json` 변경도, 전역 설치도 없습니다. Skills는 리포지토리에 -> 커밋되는 일반 마크다운 파일이므로 팀 전체와 CI 에이전트가 동일한 -> 지침을 공유합니다. - -## 무엇을 얻나요 - -| Skill | 작업 대상이… 일 때 로드 | -|:------|:-----------------------------| -| `objectstack-platform` | `defineStack`, 드라이버, 어댑터, 플러그인, 서비스, `os` CLI, 배포 | -| `objectstack-data` | `*.object.ts`, `*.seed.ts`, 필드, 관계, 검증, 인덱스, 라이프사이클 훅, RLS | -| `objectstack-query` | ObjectQL — 필터, 정렬, 페이지네이션, 집계, 조인, 윈도우 함수, 전문 검색 | -| `objectstack-ui` | Views, Apps, Pages, Dashboards, Reports, Charts, Actions | -| `objectstack-automation` | Flows, Workflows, Triggers, Approvals, 스케줄, 웹훅 | -| `objectstack-ai` | Agents, Tools, Skills, Conversations, Model Registry, MCP | -| `objectstack-api` | REST/GraphQL 엔드포인트, 인증, 실시간, 에러 엔벨로프 | -| `objectstack-i18n` | 번역 번들, 로케일 폴백, 커버리지 | -| `objectstack-formula` | CEL 표현식 — 수식 필드, 검증/공유/가시성 술어, 조건 | - -각 skill은 **스코프를 인식**합니다 — 언제 자신을 로드하고 언제 형제 -skill에게 위임할지 에이전트에게 알려주므로, Claude가 platform skill로 -객체를 모델링하거나 data skill로 CEL 표현식을 작성하려고 시도하지 -않습니다. - -## 작동 방식 - -모든 skill은 -[framework repo](https://github.com/objectstack-ai/objectstack/tree/main/skills)의 -`skills/` 아래에 있는 폴더입니다: - -``` -skills/objectstack-data/ -├── SKILL.md # YAML frontmatter + prose guide -├── references/ -│ └── _index.md # pointers into @objectstack/spec Zod sources -└── rules/ # optional deep-dive rules -``` - -`SKILL.md` frontmatter는 `skills add`가 읽어서 skill을 적절한 -에이전트 표면으로 라우팅하는 내용입니다: - -```yaml ---- -name: objectstack-data -description: Design ObjectStack data schemas — objects, fields, ... -license: Apache-2.0 -compatibility: Requires @objectstack/spec Zod schemas (v4+) -metadata: - domain: data - tags: object, field, validation, relationship, hook, permission, rls ---- -``` - -모든 skill에 걸친 핵심 규칙: **`@objectstack/spec`의 Zod 스키마가 -진실입니다**. Skills는 의도를 제공하고, 에이전트는 정확한 필드 형태를 -위해 `node_modules/@objectstack/spec/src/**/*.zod.ts`의 스키마를 -읽습니다. 이것이 바로 skills를 설치하면 환각으로 만들어진 필드가 -사실상 사라지는 이유입니다. - -## Skills vs. AI Builder - -| | [AI Builder](./ai-builder) | IDE Skills | -|:--|:--|:--| -| 실행 위치 | Console (브라우저) | 당신의 IDE / 코딩 에이전트 | -| 변경 대상 | 테넌트의 라이브 메타데이터 | 리포지토리의 파일 | -| 대행 대상 | 최종 사용자 / 관리자 | 개발자 | -| 승인 모델 | HITL 큐 (`ai:approve`) | 풀 리퀘스트 리뷰 | -| 적합한 용도 | 일상적인 확장, 노코드 사용자 | 템플릿, 패키지, 복잡한 플로우, 라이브러리 코드 | - -이 둘은 상호 보완적입니다. 대부분의 팀은 테넌트 커스터마이징에는 AI -Builder를, 그리고 **게시할 의도가 있는 패키지** 작업에는 IDE skills를 -사용합니다(자세한 내용은 [Templates](./templates) 및 [Marketplace](./marketplace) 참조). - -## 업데이트 - -Skills는 `@objectstack/spec` 버전을 따릅니다. spec 패키지를 업그레이드한 -후 `npx skills add objectstack-ai/objectstack/skills`를 다시 실행하여 에이전트를 -최신 Zod 스키마, CEL 헬퍼, 메타데이터 어휘와 동기화 상태로 유지하세요. - -## 관련 항목 - -- [AI Builder](./ai-builder) — Console 내의 대응 기능 -- [Agents](./agents) — ObjectOS *내부*에서 실행되는 서버 측 에이전트 선언 -- [Templates](./templates) — 모든 공식 템플릿은 이 skills를 로드한 상태로 구축됩니다 diff --git a/content/docs/build/interface/views.de.mdx b/content/docs/build/interface/views.de.mdx deleted file mode 100644 index 8e19a4be..00000000 --- a/content/docs/build/interface/views.de.mdx +++ /dev/null @@ -1,263 +0,0 @@ ---- -title: Views -description: List, Form, Kanban, Calendar, Gantt und mehr — wie jede Objektoberfläche in der Console deklariert wird. -translation: - source_sha: 7fe2a7f72a3951df0b657558e4d93a551d264827b33a6041988fefaefd2ec24c - guide_rev: 1 - mode: auto ---- - -Eine **View** ist die Art und Weise, wie ein Benutzer Datensätze in der -Console sieht und bearbeitet. Views sind deklarative Metadaten — mit -demselben Lebenszyklus wie Objekte: einmal deklarieren, mit Ihrem Paket -ausliefern, überall rendern. - -Zwei Arten: - -- **List Views** — viele Datensätze visualisieren (Grid, Kanban, Calendar, …) -- **Form Views** — einen einzelnen Datensatz ansehen / bearbeiten (simple, tabbed, - wizard, …) - -Schema-Quelle: -[`packages/spec/src/ui/view.zod.ts`](https://github.com/objectstack-ai/objectstack/blob/main/packages/spec/src/ui/view.zod.ts). - -## Die kürzestmögliche Deklaration - -Jedes Objekt erhält automatisch eine Standard-Grid-Liste + ein einfaches -Formular, selbst wenn Sie keine Views deklarieren. Fügen Sie `view` hinzu, -um zu überschreiben oder zu erweitern: - -```ts -import { defineObject, F, P } from '@objectstack/spec' - -export default defineObject({ - name: 'support_ticket', - fields: [ /* ... */ ], - - view: { - list: { type: 'grid', columns: ['subject', 'status', 'priority', 'assignee'] }, - form: { sections: [ { label: 'Details', fields: ['subject','description','priority','status','assignee'] } ] } - } -}) -``` - -Für Objekte mit mehreren Views (z. B. ein Kanban *und* ein Calendar über -denselben Daten) verwenden Sie die benannten Varianten: - -```ts -view: { - listViews: { - by_status: { type: 'kanban', kanban: { groupByField: 'status' }, columns: ['subject','priority'] }, - schedule: { type: 'calendar', calendar: { startDateField: 'due_at', titleField: 'subject' } }, - by_owner: { type: 'grid', columns: ['subject','status','priority'], filterableFields: ['assignee'] } - }, - formViews: { - quick: { type: 'modal', sections: [ /* ... */ ] }, - full: { type: 'tabbed', sections: [ /* ... */ ] } - } -} -``` - -## List-View-Typen - -| `type` | Rendert | Erforderliche Konfiguration | -|:--|:--|:--| -| `grid` | Datentabelle (Standard) | `columns` | -| `kanban` | Board mit Spalten | `kanban: { groupByField }` | -| `gallery` | Kartenstapel | `gallery: { coverField, titleField }` | -| `calendar` | Monat / Woche / Tag | `calendar: { startDateField, titleField }` | -| `timeline` | Chronologischer Feed | `timeline: { startDateField, titleField }` | -| `gantt` | Projektzeitachse + Abhängigkeiten | `gantt: { startDateField, endDateField, titleField }` | -| `map` | Geografische Pins | `map: { locationField }` | -| `tree` | Selbstreferenzierende Hierarchie | `tree: { parentField, labelField }` | -| `chart` | Eingebettetes Diagramm | `chart: { chartType, dataset }` | - -### Allgemeine List-Optionen - -```ts -{ - type: 'grid', - columns: ['subject','status','priority','assignee','created_at'], - - filter: [ { field: 'archived', operator: 'equals', value: false } ], - sort: [ { field: 'created_at', order: 'desc' } ], - pagination: { pageSize: 25 }, - searchableFields: ['subject','description'], - filterableFields: ['status','priority','assignee'], - - navigation: { mode: 'drawer' }, // 'page' | 'drawer' | 'modal' | 'split' | 'popover' | 'new_window' | 'none' - selection: { type: 'multiple' }, // 'none' | 'single' | 'multiple' - - rowActions: ['close_ticket','assign_to_me'], - bulkActions: ['bulk_close','bulk_export'], - - conditionalFormatting: [ - { condition: P`record.priority == 'urgent'`, style: { background: '#fef2f2', fontWeight: 600 } } - ], - - exportOptions: ['csv','xlsx'], - emptyState: { title: 'No tickets yet', message: 'Create one to get started', icon: 'inbox' } -} -``` - -`filter` und `sort` werden zu [ObjectQL](/docs/reference/objectql) -kompiliert; `rowActions` und `bulkActions` verweisen per Name auf -[Actions](./actions). - -### Kanban - -```ts -{ - type: 'kanban', - kanban: { - groupByField: 'status', // discrete field — usually a select - summarizeField: 'amount', // optional total per column - columns: ['subject', 'priority', 'assignee'] // fields shown on each card - } -} -``` - -Die Spalten des Boards stammen aus den Werten des `groupByField`; ihre -Reihenfolge und Farbe werden den `select`-Optionsdefinitionen dieses -Feldes entnommen. - -Drag & Drop zwischen Spalten löst ein Update aus, das das gruppierte Feld -setzt — mit denselben Berechtigungsregeln wie bei einer manuellen -Bearbeitung. - -### Calendar - -```ts -{ - type: 'calendar', - calendar: { - startDateField: 'start_at', - endDateField: 'end_at', // optional — single-point if omitted - titleField: 'subject', - colorField: 'priority' // optional — colours events by value - } -} -``` - -### Gantt - -```ts -{ - type: 'gantt', - gantt: { - startDateField: 'start_at', - endDateField: 'due_at', - titleField: 'name', - progressField: 'percent_complete', // optional, drives the progress bar - dependenciesField: 'depends_on' // optional — multiselect lookup to same object - } -} -``` - -### Tree - -```ts -{ - type: 'tree', - tree: { - parentField: 'parent_id', // self-lookup that builds the hierarchy - labelField: 'name', // shown indented in the first column - defaultExpandedDepth: 1 // optional — 0 = roots only, omit = expand all - } -} -``` - -Für ein selbstreferenzierendes Objekt (Kategorien, Stücklisten, Organisationseinheiten, verschachtelte Kommentare) verschachtelt das Tree-Grid die Zeilen anhand ihres `parentField`-Zeigers. - -### Chart (inline) - -Eine `chart`-Listenansicht bindet ein benanntes **Dataset** — die semantische Analyseschicht (ADR-0021) — und wählt dessen Dimensionen und Kennzahlen **per Name**. Definieren Sie eine Kennzahl einmal, und jedes Diagramm, Dashboard und jeder Report, der dasselbe Dataset bindet, bleibt konsistent: - -```ts -{ - type: 'chart', - chart: { - chartType: 'bar', // 'bar' | 'line' | 'pie' | 'area' | 'scatter' - dataset: 'tickets_by_status', // a dataset declared with defineDataset(...) - dimensions: ['status'], // dataset dimension name(s) — X / group / split - values: ['ticket_count'] // dataset measure name(s) — the value axis - } -} -``` - -Die Inline-Form `xAxisField` / `yAxisFields` / `aggregation` / `groupByField` wurde in 9.0 entfernt — jedes Diagramm, Dashboard-Widget und jeder Report bindet jetzt ein Dataset. Für umfangreichere, objektübergreifende Analysen verwenden Sie die dedizierte Reports-Oberfläche. - -## Form-View-Typen - -| `type` | Layout | -|:--|:--| -| `simple` | Einzelne Spalte oder Abschnitte (Standard) | -| `tabbed` | Abschnitte mit Tabs | -| `wizard` | Schritt-für-Schritt-Ablauf | -| `split` | Master-Detail mit zwei Bereichen | -| `drawer` | Formular im Seitenbereich | -| `modal` | Formular im Dialog | - -```ts -{ - type: 'tabbed', - sections: [ - { label: 'Overview', fields: ['subject','status','priority','assignee'] }, - { label: 'Customer', fields: ['customer','contact','email','phone'] }, - { label: 'Resolution', fields: ['resolution_notes','resolved_at'] } - ], - submitBehavior: { kind: 'next-record' } // 'thank-you' | 'redirect' | 'continue' | 'next-record' -} -``` - -### Öffentliche Formulare - -Formulare können anonym zugänglich gemacht werden: - -```ts -{ - type: 'simple', - sections: [ { fields: ['name','email','message'] } ], - sharing: { - enabled: true, - publicLink: 'contact-us', // slug under /forms/ - allowAnonymous: true - }, - submitBehavior: { kind: 'thank-you' } -} -``` - -Dadurch werden automatisch `GET /api/v1/forms/contact-us` und -`POST /api/v1/forms/contact-us/submit` bereitgestellt — öffentliche -Formularrouten, die keine Authentifizierung erfordern. Siehe -[REST API → Public forms](/docs/reference/rest-api#public-forms). - -## Sichtbarkeit, ARIA, Theming - -- `visibleOn: P\`...\`` — auf Formular-**Abschnitten** und **Feldern**, - blendet sie basierend auf Benutzer / Datensatz / Umgebung aus (CEL-Prädikat) -- `aria: { label, description, ... }` — ARIA-Attribute für Screenreader - (List- und Form-Views) -- `appearance: { showDescription, allowedVisualizations: [...] }` — auf - List-Views, schränkt ein, zu welchen List-Typen Endbenutzer wechseln können - -## Per Chat erstellen - -Normalerweise schreiben Sie View-Metadaten nicht von Hand. Weisen Sie den -AI Builder an: - -> *"Add a kanban view of the support_ticket object grouped by status, -> with cards showing subject and priority. Colour the columns red / -> amber / green by status."* - -Er ruft die Metadaten-Tools auf, stellt den Diff in die Warteschlange, -und sobald Sie ihn genehmigen, erscheint die View in der Console. Siehe -[AI Builder](/docs/build/ai-builder). - -## Siehe auch - -- [Data model](/docs/build/data) — die Objekte, aus denen Views lesen -- [Actions](./actions) — worauf `rowActions` / `bulkActions` verweisen -- [ObjectQL](/docs/reference/objectql) — wozu `filter` / `sort` kompiliert werden -- [CEL](/docs/reference/cel) — `conditionalFormatting`, `visibleOn` -- [`@objectstack/spec/ui/view.zod.ts`](https://github.com/objectstack-ai/objectstack/blob/main/packages/spec/src/ui/view.zod.ts) — Schema diff --git a/content/docs/build/interface/views.es.mdx b/content/docs/build/interface/views.es.mdx deleted file mode 100644 index d68e73dc..00000000 --- a/content/docs/build/interface/views.es.mdx +++ /dev/null @@ -1,256 +0,0 @@ ---- -title: Vistas -description: List, Form, Kanban, Calendar, Gantt y más — cómo se declara cada superficie de objeto en Console. -translation: - source_sha: 7fe2a7f72a3951df0b657558e4d93a551d264827b33a6041988fefaefd2ec24c - guide_rev: 1 - mode: auto ---- - -Una **vista** es la forma en que un usuario ve y edita registros en Console. Las -vistas son metadatos declarativos — con el mismo ciclo de vida que los objetos: -decláralas una vez, distribúyelas con tu paquete y renderízalas en cualquier lugar. - -Dos tipos: - -- **Vistas de lista** — visualizan muchos registros (grid, kanban, calendar, …) -- **Vistas de formulario** — ver / editar un único registro (simple, con pestañas, - asistente, …) - -Fuente del esquema: -[`packages/spec/src/ui/view.zod.ts`](https://github.com/objectstack-ai/objectstack/blob/main/packages/spec/src/ui/view.zod.ts). - -## La declaración más corta posible - -Cada objeto obtiene automáticamente una lista en grid + un formulario simple por -defecto, incluso si no declaras ninguna vista. Añade `view` para sobrescribir o -ampliar: - -```ts -import { defineObject, F, P } from '@objectstack/spec' - -export default defineObject({ - name: 'support_ticket', - fields: [ /* ... */ ], - - view: { - list: { type: 'grid', columns: ['subject', 'status', 'priority', 'assignee'] }, - form: { sections: [ { label: 'Details', fields: ['subject','description','priority','status','assignee'] } ] } - } -}) -``` - -Para objetos con varias vistas (p. ej. un Kanban *y* un calendario sobre los -mismos datos) usa las variantes con nombre: - -```ts -view: { - listViews: { - by_status: { type: 'kanban', kanban: { groupByField: 'status' }, columns: ['subject','priority'] }, - schedule: { type: 'calendar', calendar: { startDateField: 'due_at', titleField: 'subject' } }, - by_owner: { type: 'grid', columns: ['subject','status','priority'], filterableFields: ['assignee'] } - }, - formViews: { - quick: { type: 'modal', sections: [ /* ... */ ] }, - full: { type: 'tabbed', sections: [ /* ... */ ] } - } -} -``` - -## Tipos de vista de lista - -| `type` | Renderiza | Configuración requerida | -|:--|:--|:--| -| `grid` | Tabla de datos (por defecto) | `columns` | -| `kanban` | Tablero con columnas | `kanban: { groupByField }` | -| `gallery` | Baraja de tarjetas | `gallery: { coverField, titleField }` | -| `calendar` | Mes / semana / día | `calendar: { startDateField, titleField }` | -| `timeline` | Feed cronológico | `timeline: { startDateField, titleField }` | -| `gantt` | Cronograma de proyecto + dependencias | `gantt: { startDateField, endDateField, titleField }` | -| `map` | Pines geoespaciales | `map: { locationField }` | -| `tree` | Jerarquía autorreferenciada | `tree: { parentField, labelField }` | -| `chart` | Gráfico incrustado | `chart: { chartType, dataset }` | - -### Opciones comunes de lista - -```ts -{ - type: 'grid', - columns: ['subject','status','priority','assignee','created_at'], - - filter: [ { field: 'archived', operator: 'equals', value: false } ], - sort: [ { field: 'created_at', order: 'desc' } ], - pagination: { pageSize: 25 }, - searchableFields: ['subject','description'], - filterableFields: ['status','priority','assignee'], - - navigation: { mode: 'drawer' }, // 'page' | 'drawer' | 'modal' | 'split' | 'popover' | 'new_window' | 'none' - selection: { type: 'multiple' }, // 'none' | 'single' | 'multiple' - - rowActions: ['close_ticket','assign_to_me'], - bulkActions: ['bulk_close','bulk_export'], - - conditionalFormatting: [ - { condition: P`record.priority == 'urgent'`, style: { background: '#fef2f2', fontWeight: 600 } } - ], - - exportOptions: ['csv','xlsx'], - emptyState: { title: 'No tickets yet', message: 'Create one to get started', icon: 'inbox' } -} -``` - -`filter` y `sort` se compilan a [ObjectQL](/docs/reference/objectql); -`rowActions` y `bulkActions` referencian [actions](./actions) por nombre. - -### Kanban - -```ts -{ - type: 'kanban', - kanban: { - groupByField: 'status', // discrete field — usually a select - summarizeField: 'amount', // optional total per column - columns: ['subject', 'priority', 'assignee'] // fields shown on each card - } -} -``` - -Las columnas del tablero provienen de los valores del `groupByField`; su orden -y color se toman de las definiciones de opciones `select` de ese campo. - -Arrastrar y soltar entre columnas emite una actualización que establece el campo -agrupado — con las mismas reglas de permisos que una edición manual. - -### Calendar - -```ts -{ - type: 'calendar', - calendar: { - startDateField: 'start_at', - endDateField: 'end_at', // optional — single-point if omitted - titleField: 'subject', - colorField: 'priority' // optional — colours events by value - } -} -``` - -### Gantt - -```ts -{ - type: 'gantt', - gantt: { - startDateField: 'start_at', - endDateField: 'due_at', - titleField: 'name', - progressField: 'percent_complete', // optional, drives the progress bar - dependenciesField: 'depends_on' // optional — multiselect lookup to same object - } -} -``` - -### Tree - -```ts -{ - type: 'tree', - tree: { - parentField: 'parent_id', // self-lookup that builds the hierarchy - labelField: 'name', // shown indented in the first column - defaultExpandedDepth: 1 // optional — 0 = roots only, omit = expand all - } -} -``` - -Para un objeto autorreferenciado (categorías, listas de materiales, unidades organizativas, comentarios anidados) el tree-grid anida las filas según su puntero `parentField`. - -### Chart (en línea) - -Una vista de lista `chart` vincula un **dataset** con nombre —la capa analítica semántica (ADR-0021)— y selecciona sus dimensiones y medidas **por nombre**. Define una métrica una vez y cada gráfico, panel e informe vinculado al mismo dataset se mantiene consistente: - -```ts -{ - type: 'chart', - chart: { - chartType: 'bar', // 'bar' | 'line' | 'pie' | 'area' | 'scatter' - dataset: 'tickets_by_status', // a dataset declared with defineDataset(...) - dimensions: ['status'], // dataset dimension name(s) — X / group / split - values: ['ticket_count'] // dataset measure name(s) — the value axis - } -} -``` - -La forma en línea `xAxisField` / `yAxisFields` / `aggregation` / `groupByField` se eliminó en 9.0 — cada gráfico, widget de panel e informe ahora vincula un dataset. Para analíticas más ricas y entre objetos, usa la superficie dedicada de informes. - -## Tipos de vista de formulario - -| `type` | Diseño | -|:--|:--| -| `simple` | Columna única o secciones (por defecto) | -| `tabbed` | Secciones con pestañas | -| `wizard` | Flujo paso a paso | -| `split` | Maestro-detalle de dos paneles | -| `drawer` | Formulario en panel lateral | -| `modal` | Formulario en diálogo | - -```ts -{ - type: 'tabbed', - sections: [ - { label: 'Overview', fields: ['subject','status','priority','assignee'] }, - { label: 'Customer', fields: ['customer','contact','email','phone'] }, - { label: 'Resolution', fields: ['resolution_notes','resolved_at'] } - ], - submitBehavior: { kind: 'next-record' } // 'thank-you' | 'redirect' | 'continue' | 'next-record' -} -``` - -### Formularios públicos - -Los formularios pueden hacerse accesibles de forma anónima: - -```ts -{ - type: 'simple', - sections: [ { fields: ['name','email','message'] } ], - sharing: { - enabled: true, - publicLink: 'contact-us', // slug under /forms/ - allowAnonymous: true - }, - submitBehavior: { kind: 'thank-you' } -} -``` - -Esto expone automáticamente `GET /api/v1/forms/contact-us` y -`POST /api/v1/forms/contact-us/submit` — rutas de formulario público que -no requieren autenticación. Consulta [REST API → Public forms](/docs/reference/rest-api#public-forms). - -## Visibilidad, ARIA, temas - -- `visibleOn: P\`...\`` — en **secciones** y **campos** de formulario, ocúltalos - según el usuario / registro / entorno (predicado CEL) -- `aria: { label, description, ... }` — atributos ARIA para lectores de pantalla - (vistas de lista y de formulario) -- `appearance: { showDescription, allowedVisualizations: [...] }` — en vistas de - lista, restringe a qué tipos de lista pueden cambiar los usuarios finales - -## Construye por chat - -Normalmente no escribes los metadatos de vista a mano. Dile al AI Builder: - -> *"Añade una vista kanban del objeto support_ticket agrupada por status, -> con tarjetas que muestren subject y priority. Colorea las columnas en rojo / -> ámbar / verde según el status."* - -Este llama a las herramientas de metadatos, pone en cola el diff y, una vez que -lo apruebas, la vista aparece en Console. Consulta [AI Builder](/docs/build/ai-builder). - -## Consulta también - -- [Data model](/docs/build/data) — los objetos de los que leen las vistas -- [Actions](./actions) — a qué referencian `rowActions` / `bulkActions` -- [ObjectQL](/docs/reference/objectql) — a qué se compilan `filter` / `sort` -- [CEL](/docs/reference/cel) — `conditionalFormatting`, `visibleOn` -- [`@objectstack/spec/ui/view.zod.ts`](https://github.com/objectstack-ai/objectstack/blob/main/packages/spec/src/ui/view.zod.ts) — esquema diff --git a/content/docs/build/interface/views.fr.mdx b/content/docs/build/interface/views.fr.mdx deleted file mode 100644 index d70bc5c0..00000000 --- a/content/docs/build/interface/views.fr.mdx +++ /dev/null @@ -1,256 +0,0 @@ ---- -title: Vues -description: Liste, Formulaire, Kanban, Calendrier, Gantt et plus encore — comment chaque surface d'objet dans Console est déclarée. -translation: - source_sha: 7fe2a7f72a3951df0b657558e4d93a551d264827b33a6041988fefaefd2ec24c - guide_rev: 1 - mode: auto ---- - -Une **vue** correspond à la manière dont un utilisateur consulte et modifie -des enregistrements dans Console. Les vues sont des métadonnées -déclaratives — même cycle de vie que les objets : déclarez-les une fois, -livrez-les avec votre package, affichez-les n'importe où. - -Deux types : - -- **Vues de liste** — visualiser de nombreux enregistrements (grille, kanban, calendrier, …) -- **Vues de formulaire** — consulter / modifier un seul enregistrement (simple, à onglets, - assistant, …) - -Source du schéma : -[`packages/spec/src/ui/view.zod.ts`](https://github.com/objectstack-ai/objectstack/blob/main/packages/spec/src/ui/view.zod.ts). - -## La déclaration la plus courte possible - -Chaque objet obtient automatiquement une grille de liste par défaut et un formulaire -simple, même si vous ne déclarez aucune vue. Ajoutez `view` pour remplacer ou étendre : - -```ts -import { defineObject, F, P } from '@objectstack/spec' - -export default defineObject({ - name: 'support_ticket', - fields: [ /* ... */ ], - - view: { - list: { type: 'grid', columns: ['subject', 'status', 'priority', 'assignee'] }, - form: { sections: [ { label: 'Details', fields: ['subject','description','priority','status','assignee'] } ] } - } -}) -``` - -Pour les objets à vues multiples (par exemple un Kanban *et* un calendrier sur les -mêmes données), utilisez les variantes nommées : - -```ts -view: { - listViews: { - by_status: { type: 'kanban', kanban: { groupByField: 'status' }, columns: ['subject','priority'] }, - schedule: { type: 'calendar', calendar: { startDateField: 'due_at', titleField: 'subject' } }, - by_owner: { type: 'grid', columns: ['subject','status','priority'], filterableFields: ['assignee'] } - }, - formViews: { - quick: { type: 'modal', sections: [ /* ... */ ] }, - full: { type: 'tabbed', sections: [ /* ... */ ] } - } -} -``` - -## Types de vues de liste - -| `type` | Affiche | Configuration requise | -|:--|:--|:--| -| `grid` | Tableau de données (par défaut) | `columns` | -| `kanban` | Tableau avec colonnes | `kanban: { groupByField }` | -| `gallery` | Jeu de cartes | `gallery: { coverField, titleField }` | -| `calendar` | Mois / semaine / jour | `calendar: { startDateField, titleField }` | -| `timeline` | Flux chronologique | `timeline: { startDateField, titleField }` | -| `gantt` | Échéancier de projet + dépendances | `gantt: { startDateField, endDateField, titleField }` | -| `map` | Repères géospatiaux | `map: { locationField }` | -| `tree` | Hiérarchie auto-référencée | `tree: { parentField, labelField }` | -| `chart` | Graphique intégré | `chart: { chartType, dataset }` | - -### Options de liste courantes - -```ts -{ - type: 'grid', - columns: ['subject','status','priority','assignee','created_at'], - - filter: [ { field: 'archived', operator: 'equals', value: false } ], - sort: [ { field: 'created_at', order: 'desc' } ], - pagination: { pageSize: 25 }, - searchableFields: ['subject','description'], - filterableFields: ['status','priority','assignee'], - - navigation: { mode: 'drawer' }, // 'page' | 'drawer' | 'modal' | 'split' | 'popover' | 'new_window' | 'none' - selection: { type: 'multiple' }, // 'none' | 'single' | 'multiple' - - rowActions: ['close_ticket','assign_to_me'], - bulkActions: ['bulk_close','bulk_export'], - - conditionalFormatting: [ - { condition: P`record.priority == 'urgent'`, style: { background: '#fef2f2', fontWeight: 600 } } - ], - - exportOptions: ['csv','xlsx'], - emptyState: { title: 'No tickets yet', message: 'Create one to get started', icon: 'inbox' } -} -``` - -`filter` et `sort` se compilent en [ObjectQL](/docs/reference/objectql) ; -`rowActions` et `bulkActions` référencent des [actions](./actions) par leur nom. - -### Kanban - -```ts -{ - type: 'kanban', - kanban: { - groupByField: 'status', // discrete field — usually a select - summarizeField: 'amount', // optional total per column - columns: ['subject', 'priority', 'assignee'] // fields shown on each card - } -} -``` - -Les colonnes du tableau proviennent des valeurs du `groupByField` ; leur ordre -et leur couleur sont repris des définitions d'options `select` de ce champ. - -Le glisser-déposer entre colonnes déclenche une mise à jour qui définit le -champ de regroupement — mêmes règles d'autorisation qu'une modification manuelle. - -### Calendrier - -```ts -{ - type: 'calendar', - calendar: { - startDateField: 'start_at', - endDateField: 'end_at', // optional — single-point if omitted - titleField: 'subject', - colorField: 'priority' // optional — colours events by value - } -} -``` - -### Gantt - -```ts -{ - type: 'gantt', - gantt: { - startDateField: 'start_at', - endDateField: 'due_at', - titleField: 'name', - progressField: 'percent_complete', // optional, drives the progress bar - dependenciesField: 'depends_on' // optional — multiselect lookup to same object - } -} -``` - -### Arbre - -```ts -{ - type: 'tree', - tree: { - parentField: 'parent_id', // self-lookup that builds the hierarchy - labelField: 'name', // shown indented in the first column - defaultExpandedDepth: 1 // optional — 0 = roots only, omit = expand all - } -} -``` - -Pour un objet auto-référencé (catégories, nomenclatures, unités organisationnelles, commentaires imbriqués), la grille arborescente imbrique les lignes selon leur pointeur `parentField`. - -### Graphique (intégré) - -Une vue liste `chart` lie un **dataset** nommé — la couche analytique sémantique (ADR-0021) — et sélectionne ses dimensions et mesures **par leur nom**. Définissez une métrique une fois, et chaque graphique, tableau de bord et rapport lié au même dataset reste cohérent : - -```ts -{ - type: 'chart', - chart: { - chartType: 'bar', // 'bar' | 'line' | 'pie' | 'area' | 'scatter' - dataset: 'tickets_by_status', // a dataset declared with defineDataset(...) - dimensions: ['status'], // dataset dimension name(s) — X / group / split - values: ['ticket_count'] // dataset measure name(s) — the value axis - } -} -``` - -La forme en ligne `xAxisField` / `yAxisFields` / `aggregation` / `groupByField` a été supprimée en 9.0 — chaque graphique, widget de tableau de bord et rapport lie désormais un dataset. Pour des analyses plus riches et inter-objets, utilisez la surface de rapports dédiée. - -## Types de vues de formulaire - -| `type` | Mise en page | -|:--|:--| -| `simple` | Colonne unique ou sections (par défaut) | -| `tabbed` | Sections à onglets | -| `wizard` | Flux étape par étape | -| `split` | Maître-détail à deux volets | -| `drawer` | Formulaire en panneau latéral | -| `modal` | Formulaire en boîte de dialogue | - -```ts -{ - type: 'tabbed', - sections: [ - { label: 'Overview', fields: ['subject','status','priority','assignee'] }, - { label: 'Customer', fields: ['customer','contact','email','phone'] }, - { label: 'Resolution', fields: ['resolution_notes','resolved_at'] } - ], - submitBehavior: { kind: 'next-record' } // 'thank-you' | 'redirect' | 'continue' | 'next-record' -} -``` - -### Formulaires publics - -Les formulaires peuvent être rendus accessibles de manière anonyme : - -```ts -{ - type: 'simple', - sections: [ { fields: ['name','email','message'] } ], - sharing: { - enabled: true, - publicLink: 'contact-us', // slug under /forms/ - allowAnonymous: true - }, - submitBehavior: { kind: 'thank-you' } -} -``` - -Cela expose automatiquement `GET /api/v1/forms/contact-us` et -`POST /api/v1/forms/contact-us/submit` — des routes de formulaire publiques qui -ne nécessitent pas d'authentification. Voir [REST API → Public forms](/docs/reference/rest-api#public-forms). - -## Visibilité, ARIA, thématisation - -- `visibleOn: P\`...\`` — sur les **sections** et **champs** de formulaire, les masquer - selon l'utilisateur / l'enregistrement / l'environnement (prédicat CEL) -- `aria: { label, description, ... }` — attributs ARIA pour les lecteurs d'écran - (vues de liste et de formulaire) -- `appearance: { showDescription, allowedVisualizations: [...] }` — sur les vues de - liste, restreint les types de liste vers lesquels les utilisateurs finaux peuvent basculer - -## Construire par conversation - -En général, vous n'écrivez pas les métadonnées de vue à la main. Dites-le à l'AI Builder : - -> *"Ajoute une vue kanban de l'objet support_ticket regroupée par statut, -> avec des cartes affichant le sujet et la priorité. Colore les colonnes en rouge / -> ambre / vert selon le statut."* - -Il appelle les outils de métadonnées, met en file d'attente le diff, et une fois que -vous l'approuvez, la vue apparaît dans Console. Voir [AI Builder](/docs/build/ai-builder). - -## Voir aussi - -- [Modèle de données](/docs/build/data) — les objets que les vues lisent -- [Actions](./actions) — ce que référencent `rowActions` / `bulkActions` -- [ObjectQL](/docs/reference/objectql) — ce en quoi se compilent `filter` / `sort` -- [CEL](/docs/reference/cel) — `conditionalFormatting`, `visibleOn` -- [`@objectstack/spec/ui/view.zod.ts`](https://github.com/objectstack-ai/objectstack/blob/main/packages/spec/src/ui/view.zod.ts) — schéma diff --git a/content/docs/build/interface/views.ja.mdx b/content/docs/build/interface/views.ja.mdx deleted file mode 100644 index ecd3102d..00000000 --- a/content/docs/build/interface/views.ja.mdx +++ /dev/null @@ -1,255 +0,0 @@ ---- -title: ビュー -description: リスト、フォーム、カンバン、カレンダー、ガントなど — Console におけるすべてのオブジェクト画面の宣言方法。 -translation: - source_sha: 7fe2a7f72a3951df0b657558e4d93a551d264827b33a6041988fefaefd2ec24c - guide_rev: 1 - mode: auto ---- - -**ビュー** とは、ユーザーが Console でレコードを閲覧・編集する方法です。ビューは -宣言的メタデータであり、オブジェクトと同じライフサイクルを持ちます。一度宣言すれば、 -パッケージとともに配布し、どこでもレンダリングできます。 - -2 種類あります。 - -- **リストビュー** — 多数のレコードを可視化（グリッド、カンバン、カレンダーなど） -- **フォームビュー** — 単一レコードの閲覧・編集（シンプル、タブ、 - ウィザードなど） - -スキーマソース: -[`packages/spec/src/ui/view.zod.ts`](https://github.com/objectstack-ai/objectstack/blob/main/packages/spec/src/ui/view.zod.ts)。 - -## 最小限の宣言 - -すべてのオブジェクトは、ビューを宣言しなくても自動的にデフォルトのグリッドリスト -とシンプルフォームを取得します。`view` を追加してオーバーライドまたは拡張できます。 - -```ts -import { defineObject, F, P } from '@objectstack/spec' - -export default defineObject({ - name: 'support_ticket', - fields: [ /* ... */ ], - - view: { - list: { type: 'grid', columns: ['subject', 'status', 'priority', 'assignee'] }, - form: { sections: [ { label: 'Details', fields: ['subject','description','priority','status','assignee'] } ] } - } -}) -``` - -マルチビューオブジェクト（例えば同じデータに対するカンバン *と* カレンダー）の場合は、 -名前付きバリアントを使用します。 - -```ts -view: { - listViews: { - by_status: { type: 'kanban', kanban: { groupByField: 'status' }, columns: ['subject','priority'] }, - schedule: { type: 'calendar', calendar: { startDateField: 'due_at', titleField: 'subject' } }, - by_owner: { type: 'grid', columns: ['subject','status','priority'], filterableFields: ['assignee'] } - }, - formViews: { - quick: { type: 'modal', sections: [ /* ... */ ] }, - full: { type: 'tabbed', sections: [ /* ... */ ] } - } -} -``` - -## リストビューの種類 - -| `type` | レンダリング | 必須の設定 | -|:--|:--|:--| -| `grid` | データテーブル（デフォルト） | `columns` | -| `kanban` | 列を持つボード | `kanban: { groupByField }` | -| `gallery` | カードデッキ | `gallery: { coverField, titleField }` | -| `calendar` | 月 / 週 / 日 | `calendar: { startDateField, titleField }` | -| `timeline` | 時系列フィード | `timeline: { startDateField, titleField }` | -| `gantt` | プロジェクトタイムライン + 依存関係 | `gantt: { startDateField, endDateField, titleField }` | -| `map` | 地理空間ピン | `map: { locationField }` | -| `tree` | 自己参照型の階層 | `tree: { parentField, labelField }` | -| `chart` | 埋め込みチャート | `chart: { chartType, dataset }` | - -### 共通のリストオプション - -```ts -{ - type: 'grid', - columns: ['subject','status','priority','assignee','created_at'], - - filter: [ { field: 'archived', operator: 'equals', value: false } ], - sort: [ { field: 'created_at', order: 'desc' } ], - pagination: { pageSize: 25 }, - searchableFields: ['subject','description'], - filterableFields: ['status','priority','assignee'], - - navigation: { mode: 'drawer' }, // 'page' | 'drawer' | 'modal' | 'split' | 'popover' | 'new_window' | 'none' - selection: { type: 'multiple' }, // 'none' | 'single' | 'multiple' - - rowActions: ['close_ticket','assign_to_me'], - bulkActions: ['bulk_close','bulk_export'], - - conditionalFormatting: [ - { condition: P`record.priority == 'urgent'`, style: { background: '#fef2f2', fontWeight: 600 } } - ], - - exportOptions: ['csv','xlsx'], - emptyState: { title: 'No tickets yet', message: 'Create one to get started', icon: 'inbox' } -} -``` - -`filter` と `sort` は [ObjectQL](/docs/reference/objectql) にコンパイルされます。 -`rowActions` と `bulkActions` は [actions](./actions) を名前で参照します。 - -### カンバン - -```ts -{ - type: 'kanban', - kanban: { - groupByField: 'status', // discrete field — usually a select - summarizeField: 'amount', // optional total per column - columns: ['subject', 'priority', 'assignee'] // fields shown on each card - } -} -``` - -ボードの列は `groupByField` の値から生成され、その順序と色は当該フィールドの -`select` オプション定義から取得されます。 - -列間でのドラッグ&ドロップは、グループ化されたフィールドを設定する更新を発行します。 -手動編集と同じ権限ルールが適用されます。 - -### カレンダー - -```ts -{ - type: 'calendar', - calendar: { - startDateField: 'start_at', - endDateField: 'end_at', // optional — single-point if omitted - titleField: 'subject', - colorField: 'priority' // optional — colours events by value - } -} -``` - -### ガント - -```ts -{ - type: 'gantt', - gantt: { - startDateField: 'start_at', - endDateField: 'due_at', - titleField: 'name', - progressField: 'percent_complete', // optional, drives the progress bar - dependenciesField: 'depends_on' // optional — multiselect lookup to same object - } -} -``` - -### ツリー - -```ts -{ - type: 'tree', - tree: { - parentField: 'parent_id', // self-lookup that builds the hierarchy - labelField: 'name', // shown indented in the first column - defaultExpandedDepth: 1 // optional — 0 = roots only, omit = expand all - } -} -``` - -自己参照型のオブジェクト（カテゴリ、部品表、組織単位、入れ子のコメント）では、ツリーグリッドが `parentField` ポインタに従って行を入れ子にします。 - -### チャート（インライン） - -`chart` リストビューは、名前付きの **dataset**（セマンティック分析レイヤー、ADR-0021）をバインドし、そのディメンションとメジャーを**名前で**選択します。メトリックを一度定義すれば、同じ dataset をバインドするすべてのチャート、ダッシュボード、レポートが一貫します。 - -```ts -{ - type: 'chart', - chart: { - chartType: 'bar', // 'bar' | 'line' | 'pie' | 'area' | 'scatter' - dataset: 'tickets_by_status', // a dataset declared with defineDataset(...) - dimensions: ['status'], // dataset dimension name(s) — X / group / split - values: ['ticket_count'] // dataset measure name(s) — the value axis - } -} -``` - -インラインの `xAxisField` / `yAxisFields` / `aggregation` / `groupByField` の形式は 9.0 で削除されました。すべてのチャート、ダッシュボードウィジェット、レポートは現在 dataset をバインドします。より高度なオブジェクト横断分析には、専用のレポート画面を使用してください。 - -## フォームビューの種類 - -| `type` | レイアウト | -|:--|:--| -| `simple` | 単一カラムまたはセクション（デフォルト） | -| `tabbed` | タブ付きセクション | -| `wizard` | ステップバイステップのフロー | -| `split` | マスター・ディテールの 2 ペイン | -| `drawer` | サイドパネルフォーム | -| `modal` | ダイアログフォーム | - -```ts -{ - type: 'tabbed', - sections: [ - { label: 'Overview', fields: ['subject','status','priority','assignee'] }, - { label: 'Customer', fields: ['customer','contact','email','phone'] }, - { label: 'Resolution', fields: ['resolution_notes','resolved_at'] } - ], - submitBehavior: { kind: 'next-record' } // 'thank-you' | 'redirect' | 'continue' | 'next-record' -} -``` - -### 公開フォーム - -フォームは匿名アクセス可能にできます。 - -```ts -{ - type: 'simple', - sections: [ { fields: ['name','email','message'] } ], - sharing: { - enabled: true, - publicLink: 'contact-us', // slug under /forms/ - allowAnonymous: true - }, - submitBehavior: { kind: 'thank-you' } -} -``` - -これにより、`GET /api/v1/forms/contact-us` と -`POST /api/v1/forms/contact-us/submit` が自動的に公開されます。これらは -認証を必要としない公開フォームルートです。[REST API → Public forms](/docs/reference/rest-api#public-forms) を参照してください。 - -## 可視性、ARIA、テーマ - -- `visibleOn: P\`...\`` — フォームの **セクション** と **フィールド** に対して、 - ユーザー / レコード / 環境に基づいて非表示にします（CEL 述語） -- `aria: { label, description, ... }` — スクリーンリーダー向けの ARIA 属性 - （リストビューとフォームビュー） -- `appearance: { showDescription, allowedVisualizations: [...] }` — リスト - ビューにおいて、エンドユーザーが切り替えられるリストタイプを制限します - -## チャットで構築する - -通常、ビューのメタデータを手作業で書くことはありません。AI Builder に伝えましょう。 - -> *「support_ticket オブジェクトのカンバンビューを status でグループ化して追加し、 -> カードに subject と priority を表示してください。列を status に応じて -> 赤 / 黄 / 緑で色分けしてください。」* - -AI Builder はメタデータツールを呼び出し、差分をキューに入れます。承認すると、 -ビューが Console に表示されます。[AI Builder](/docs/build/ai-builder) を参照してください。 - -## 関連項目 - -- [Data model](/docs/build/data) — ビューが読み取るオブジェクト -- [Actions](./actions) — `rowActions` / `bulkActions` が参照するもの -- [ObjectQL](/docs/reference/objectql) — `filter` / `sort` のコンパイル先 -- [CEL](/docs/reference/cel) — `conditionalFormatting`、`visibleOn` -- [`@objectstack/spec/ui/view.zod.ts`](https://github.com/objectstack-ai/objectstack/blob/main/packages/spec/src/ui/view.zod.ts) — スキーマ diff --git a/content/docs/build/interface/views.ko.mdx b/content/docs/build/interface/views.ko.mdx deleted file mode 100644 index 67001616..00000000 --- a/content/docs/build/interface/views.ko.mdx +++ /dev/null @@ -1,255 +0,0 @@ ---- -title: 뷰 -description: List, Form, Kanban, Calendar, Gantt 등 — Console의 모든 오브젝트 표면을 선언하는 방법. -translation: - source_sha: 7fe2a7f72a3951df0b657558e4d93a551d264827b33a6041988fefaefd2ec24c - guide_rev: 1 - mode: auto ---- - -**뷰**는 사용자가 Console에서 레코드를 보고 편집하는 방식입니다. 뷰는 -선언적 메타데이터이며 — 오브젝트와 동일한 라이프사이클을 가집니다. 한 번 -선언하고, 패키지와 함께 배포하며, 어디서나 렌더링합니다. - -두 가지 종류: - -- **List 뷰** — 여러 레코드를 시각화합니다 (grid, kanban, calendar 등) -- **Form 뷰** — 단일 레코드를 보거나 편집합니다 (simple, tabbed, - wizard 등) - -스키마 소스: -[`packages/spec/src/ui/view.zod.ts`](https://github.com/objectstack-ai/objectstack/blob/main/packages/spec/src/ui/view.zod.ts). - -## 가능한 가장 짧은 선언 - -모든 오브젝트는 뷰를 선언하지 않아도 기본 grid list와 simple form을 -자동으로 가집니다. 재정의하거나 확장하려면 `view`를 추가하세요: - -```ts -import { defineObject, F, P } from '@objectstack/spec' - -export default defineObject({ - name: 'support_ticket', - fields: [ /* ... */ ], - - view: { - list: { type: 'grid', columns: ['subject', 'status', 'priority', 'assignee'] }, - form: { sections: [ { label: 'Details', fields: ['subject','description','priority','status','assignee'] } ] } - } -}) -``` - -여러 뷰를 가진 오브젝트(예: 동일한 데이터에 대해 Kanban *과* calendar)의 -경우 명명된 변형을 사용하세요: - -```ts -view: { - listViews: { - by_status: { type: 'kanban', kanban: { groupByField: 'status' }, columns: ['subject','priority'] }, - schedule: { type: 'calendar', calendar: { startDateField: 'due_at', titleField: 'subject' } }, - by_owner: { type: 'grid', columns: ['subject','status','priority'], filterableFields: ['assignee'] } - }, - formViews: { - quick: { type: 'modal', sections: [ /* ... */ ] }, - full: { type: 'tabbed', sections: [ /* ... */ ] } - } -} -``` - -## List 뷰 타입 - -| `type` | 렌더링 | 필수 설정 | -|:--|:--|:--| -| `grid` | 데이터 테이블 (기본값) | `columns` | -| `kanban` | 컬럼이 있는 보드 | `kanban: { groupByField }` | -| `gallery` | 카드 덱 | `gallery: { coverField, titleField }` | -| `calendar` | 월 / 주 / 일 | `calendar: { startDateField, titleField }` | -| `timeline` | 시간순 피드 | `timeline: { startDateField, titleField }` | -| `gantt` | 프로젝트 타임라인 + 의존성 | `gantt: { startDateField, endDateField, titleField }` | -| `map` | 지리공간 핀 | `map: { locationField }` | -| `tree` | 자기 참조 계층 | `tree: { parentField, labelField }` | -| `chart` | 임베드 차트 | `chart: { chartType, dataset }` | - -### 공통 list 옵션 - -```ts -{ - type: 'grid', - columns: ['subject','status','priority','assignee','created_at'], - - filter: [ { field: 'archived', operator: 'equals', value: false } ], - sort: [ { field: 'created_at', order: 'desc' } ], - pagination: { pageSize: 25 }, - searchableFields: ['subject','description'], - filterableFields: ['status','priority','assignee'], - - navigation: { mode: 'drawer' }, // 'page' | 'drawer' | 'modal' | 'split' | 'popover' | 'new_window' | 'none' - selection: { type: 'multiple' }, // 'none' | 'single' | 'multiple' - - rowActions: ['close_ticket','assign_to_me'], - bulkActions: ['bulk_close','bulk_export'], - - conditionalFormatting: [ - { condition: P`record.priority == 'urgent'`, style: { background: '#fef2f2', fontWeight: 600 } } - ], - - exportOptions: ['csv','xlsx'], - emptyState: { title: 'No tickets yet', message: 'Create one to get started', icon: 'inbox' } -} -``` - -`filter`와 `sort`는 [ObjectQL](/docs/reference/objectql)로 컴파일됩니다. -`rowActions`와 `bulkActions`는 [actions](./actions)를 이름으로 참조합니다. - -### Kanban - -```ts -{ - type: 'kanban', - kanban: { - groupByField: 'status', // discrete field — usually a select - summarizeField: 'amount', // optional total per column - columns: ['subject', 'priority', 'assignee'] // fields shown on each card - } -} -``` - -보드의 컬럼은 `groupByField`의 값에서 가져오며, 그 순서와 색상은 해당 -필드의 `select` 옵션 정의에서 가져옵니다. - -컬럼 간 드래그 앤 드롭은 그룹화된 필드를 설정하는 업데이트를 발생시키며 — -수동 편집과 동일한 권한 규칙이 적용됩니다. - -### Calendar - -```ts -{ - type: 'calendar', - calendar: { - startDateField: 'start_at', - endDateField: 'end_at', // optional — single-point if omitted - titleField: 'subject', - colorField: 'priority' // optional — colours events by value - } -} -``` - -### Gantt - -```ts -{ - type: 'gantt', - gantt: { - startDateField: 'start_at', - endDateField: 'due_at', - titleField: 'name', - progressField: 'percent_complete', // optional, drives the progress bar - dependenciesField: 'depends_on' // optional — multiselect lookup to same object - } -} -``` - -### Tree - -```ts -{ - type: 'tree', - tree: { - parentField: 'parent_id', // self-lookup that builds the hierarchy - labelField: 'name', // shown indented in the first column - defaultExpandedDepth: 1 // optional — 0 = roots only, omit = expand all - } -} -``` - -자기 참조 오브젝트(카테고리, BOM, 조직 단위, 중첩 댓글)의 경우 tree-grid는 `parentField` 포인터에 따라 행을 중첩합니다. - -### Chart (인라인) - -`chart` 리스트 뷰는 이름이 지정된 **dataset**(시맨틱 분석 레이어, ADR-0021)을 바인딩하고 그 디멘션과 측정값을 **이름으로** 선택합니다. 메트릭을 한 번 정의하면 동일한 dataset을 바인딩하는 모든 차트, 대시보드, 리포트가 일관되게 유지됩니다: - -```ts -{ - type: 'chart', - chart: { - chartType: 'bar', // 'bar' | 'line' | 'pie' | 'area' | 'scatter' - dataset: 'tickets_by_status', // a dataset declared with defineDataset(...) - dimensions: ['status'], // dataset dimension name(s) — X / group / split - values: ['ticket_count'] // dataset measure name(s) — the value axis - } -} -``` - -인라인 `xAxisField` / `yAxisFields` / `aggregation` / `groupByField` 형식은 9.0에서 제거되었습니다 — 모든 차트, 대시보드 위젯, 리포트는 이제 dataset을 바인딩합니다. 더 풍부한 오브젝트 간 분석을 위해서는 전용 reports 표면을 사용하세요. - -## Form 뷰 타입 - -| `type` | 레이아웃 | -|:--|:--| -| `simple` | 단일 컬럼 또는 섹션 (기본값) | -| `tabbed` | 탭 섹션 | -| `wizard` | 단계별 플로우 | -| `split` | 마스터-디테일 두 개 창 | -| `drawer` | 측면 패널 폼 | -| `modal` | 다이얼로그 폼 | - -```ts -{ - type: 'tabbed', - sections: [ - { label: 'Overview', fields: ['subject','status','priority','assignee'] }, - { label: 'Customer', fields: ['customer','contact','email','phone'] }, - { label: 'Resolution', fields: ['resolution_notes','resolved_at'] } - ], - submitBehavior: { kind: 'next-record' } // 'thank-you' | 'redirect' | 'continue' | 'next-record' -} -``` - -### 공개 폼 - -폼은 익명 접근이 가능하도록 만들 수 있습니다: - -```ts -{ - type: 'simple', - sections: [ { fields: ['name','email','message'] } ], - sharing: { - enabled: true, - publicLink: 'contact-us', // slug under /forms/ - allowAnonymous: true - }, - submitBehavior: { kind: 'thank-you' } -} -``` - -이는 `GET /api/v1/forms/contact-us`와 -`POST /api/v1/forms/contact-us/submit`를 자동으로 노출합니다 — 인증이 -필요하지 않은 공개 폼 라우트입니다. [REST API → Public forms](/docs/reference/rest-api#public-forms)를 참고하세요. - -## 가시성, ARIA, 테마 - -- `visibleOn: P\`...\`` — form **섹션** 및 **필드**에서, 사용자 / 레코드 / - 환경에 따라 숨깁니다 (CEL 술어) -- `aria: { label, description, ... }` — 스크린 리더를 위한 ARIA 속성 - (list 및 form 뷰) -- `appearance: { showDescription, allowedVisualizations: [...] }` — list - 뷰에서, 최종 사용자가 전환할 수 있는 list 타입을 제한합니다 - -## 채팅으로 빌드하기 - -일반적으로 뷰 메타데이터를 직접 작성하지 않습니다. AI Builder에게 알려주세요: - -> *"subject와 priority를 보여주는 카드와 함께 status별로 그룹화된 -> support_ticket 오브젝트의 kanban 뷰를 추가해줘. status에 따라 컬럼을 -> 빨강 / 호박색 / 초록으로 색칠해줘."* - -AI Builder가 메타데이터 도구를 호출하고, diff를 큐에 넣으며, 승인하면 해당 -뷰가 Console에 나타납니다. [AI Builder](/docs/build/ai-builder)를 참고하세요. - -## 참고 - -- [Data model](/docs/build/data) — 뷰가 읽는 오브젝트 -- [Actions](./actions) — `rowActions` / `bulkActions`가 참조하는 것 -- [ObjectQL](/docs/reference/objectql) — `filter` / `sort`가 컴파일되는 대상 -- [CEL](/docs/reference/cel) — `conditionalFormatting`, `visibleOn` -- [`@objectstack/spec/ui/view.zod.ts`](https://github.com/objectstack-ai/objectstack/blob/main/packages/spec/src/ui/view.zod.ts) — 스키마 diff --git a/content/docs/build/marketplace.de.mdx b/content/docs/build/marketplace.de.mdx deleted file mode 100644 index d7d21cfd..00000000 --- a/content/docs/build/marketplace.de.mdx +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: Marketplace -description: Installieren Sie fertige Apps in eine laufende ObjectOS, ohne Code zu schreiben. -translation: - source_sha: 6594741158e878583fe7c8ade604d28171cc95179827cdbd114fadbd105a34b5 - guide_rev: 1 - mode: auto ---- - -Der ObjectOS marketplace ermöglicht es Ihnen, vorgefertigte Apps in eine -laufende Runtime zu installieren — kein Build-Schritt, kein Neustart, -kein Source-Checkout. Es ist der schnellste Weg, um Benutzern bereits am -ersten Tag echte Software zur Verfügung zu stellen. - -## Funktionsweise - -Jede ObjectOS-Runtime wird standardmäßig mit aktivierten Plugins -`MarketplaceProxy` und `MarketplaceInstallLocal` ausgeliefert. Wenn Sie -die Console (`/_console/`) öffnen, fragt der Marketplace-Tab den -konfigurierten App-Katalog ab und zeigt installierbare Apps an. - -```text -You ─→ Console ─→ Marketplace tab ─→ pick app ─→ Install - ↓ - Artifact merged into kernel - ↓ - Console re-renders with new - objects / views / permissions - ↓ - Done — no restart -``` - -## Kataloge - -| Katalog | Quelle | Wann zu verwenden | -|---|---|---| -| **Default** | Vorgebündelt mit dem Runtime-Image | Erste Evaluierung, Demos, offline | -| **ObjectStack public catalog** | Öffentliche App-Registry | Neueste Community- + Erstanbieter-Apps | -| **Private catalog** | Ihre eigenen veröffentlichten Artefakte | Interne Apps, die nicht öffentlich sein sollen | -| **Local** | In die Runtime eingebundene Dateien | Air-Gapped, benutzerdefinierte Builds | - -Die Katalogquelle wird über das Marketplace-Plugin oder Umgebungsvariablen -konfiguriert; siehe [Runtime Configuration](/docs/configure/runtime). - -## Was im Standardkatalog enthalten ist - -Diese Apps lassen sich mit einem Klick in der Console installieren: - -| App | Was Sie damit erhalten | -|---|---| -| **Todo** | Universeller Aufgaben- und Projekt-Tracker | -| **Contracts** | Vertragslebenszyklus (CLM) mit KI-basierter Klauselextraktion | -| **Procurement** | Lieferanten, Bestellungen, 3-Wege-Abgleich | -| **Compliance** | SOC 2 / ISO 27001 Kontrollen + Nachweissammlung | -| **Helpdesk** | KI-first Kundensupport-Ticketing | -| **Content** | Redaktionskalender + Kanal-ROI | -| **HR** | Verzeichnis, Organigramm, Abwesenheiten | -| **Project** | Projekt-/Aufgaben-/Meilenstein-Tracking | - -Der Quellcode befindet sich unter -[github.com/objectstack-ai/templates](https://github.com/objectstack-ai/templates) — -klonen Sie eine davon als Ausgangspunkt für eine benutzerdefinierte App. - -## Installationsablauf - -1. **Console öffnen** — http://localhost:3000/_console/ -2. **Anmelden** — falls noch kein Konto existiert, registrieren Sie eines unter `/_account/register` -3. **Zum Marketplace-Tab navigieren** -4. **Eine App auswählen und auf Install klicken** -5. **Console neu laden** — die Objekte, Ansichten und Flows der neuen App erscheinen - -Im Hintergrund holt der Marketplace das kompilierte Artefakt der App, -führt es in den laufenden Kernel zusammen und registriert dessen Objekte -bei ObjectQL. Seed-Daten (falls die App welche definiert) werden bei der -ersten Installation eingefügt. - -## Deinstallation - -Über Console → Marketplace → installierte App → Uninstall. Die Objekte der -App werden aus dem Kernel entfernt und ihre Tabellen werden zur Bereinigung -markiert (Daten werden standardmäßig beibehalten; Sie entscheiden, ob -Tabellen gelöscht werden). - -## Eigene App veröffentlichen - -Alles, was Sie mit `os init` erstellen, kann zu einer Marketplace-App werden. - -```bash -os init my-app -t app --install -cd my-app -# ... write objects, views, etc. ... -os compile # → dist/objectstack.json -os package publish # publish to a catalog -``` - -Um im öffentlichen Katalog zu veröffentlichen, benötigen Sie ein -Registry-Konto (`os login`). Um in einem privaten Katalog zu -veröffentlichen, richten Sie `OS_PACKAGE_REGISTRY` auf Ihren eigenen aus. - -## Versionierung - -Jede veröffentlichte App ist unveränderlich. Updates erzeugen eine neue -Version. Die Runtime verfolgt die installierte Version + verfügbare Updates -pro App. Benutzer sehen ein Badge "Update available" in der Console, wenn -eine neue Version in einem Katalog veröffentlicht wird, den sie verfolgen. - -## Berechtigungen - -Die Installation von Apps erfordert die Systemberechtigung -`manage_marketplace` — standardmäßig besitzen nur Mitglieder des -Berechtigungssatzes **Setup Administrator** diese. Normale Benutzer sehen -den Marketplace schreibgeschützt. - -## Air-Gapped-Marketplaces - -Für Bereitstellungen ohne Internet-Zugang betreiben Sie einen lokalen -Katalogserver innerhalb Ihres Netzwerks und richten ObjectOS darauf aus. -Siehe [Air-gapped](/docs/deploy/air-gapped) für die Topologie. - -## Was der Marketplace nicht ist - -- **Kein Code-Distributionskanal.** Veröffentlichte Apps sind kompilierte - Artefakte — sie beschreiben Daten + UI + Flows deklarativ. Sie liefern - keinen beliebigen JavaScript-Code aus. -- **Keine Sandbox.** Eine installierte App hat denselben Zugriff auf Ihre - Datenbank wie alles andere im Kernel — prüfen Sie das Artefakt, bevor Sie - Apps aus nicht vertrauenswürdigen Quellen installieren. -- **Keine Zahlungsplattform** (noch nicht). Apps im öffentlichen Katalog sind - kostenlos unter Apache-2.0. Kommerzielle / kostenpflichtige Distribution - steht auf der Roadmap. diff --git a/content/docs/build/marketplace.es.mdx b/content/docs/build/marketplace.es.mdx deleted file mode 100644 index 3902c01b..00000000 --- a/content/docs/build/marketplace.es.mdx +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: Marketplace -description: Instala aplicaciones listas para usar en un ObjectOS en ejecución sin escribir código. -translation: - source_sha: 6594741158e878583fe7c8ade604d28171cc95179827cdbd114fadbd105a34b5 - guide_rev: 1 - mode: auto ---- - -El marketplace de ObjectOS te permite instalar aplicaciones preconstruidas en un -runtime en ejecución: sin paso de compilación, sin reinicios, sin descargar el -código fuente. Es la forma más rápida de poner software real frente a los -usuarios desde el primer día. - -## Cómo funciona - -Cada runtime de ObjectOS incluye los plugins `MarketplaceProxy` y -`MarketplaceInstallLocal` habilitados de forma predeterminada. Cuando abres -Console (`/_console/`), la pestaña del marketplace consulta el catálogo de -aplicaciones configurado y muestra las aplicaciones instalables. - -```text -You ─→ Console ─→ Marketplace tab ─→ pick app ─→ Install - ↓ - Artifact merged into kernel - ↓ - Console re-renders with new - objects / views / permissions - ↓ - Done — no restart -``` - -## Catálogos - -| Catálogo | Origen | Cuándo usarlo | -|---|---|---| -| **Default** | Preempaquetado con la imagen del runtime | Primera evaluación, demos, sin conexión | -| **ObjectStack public catalog** | Registro público de aplicaciones | Las aplicaciones más recientes de la comunidad y oficiales | -| **Private catalog** | Tus propios artefactos publicados | Aplicaciones internas que no quieres hacer públicas | -| **Local** | Archivos montados en el runtime | Entornos aislados, compilaciones personalizadas | - -El origen del catálogo se configura a través del plugin del marketplace o de -variables de entorno; consulta [Runtime Configuration](/docs/configure/runtime). - -## Qué incluye el catálogo predeterminado - -Estas aplicaciones están listas para instalarse con un clic en Console: - -| Aplicación | Lo que te ofrece | -|---|---| -| **Todo** | Seguimiento universal de tareas y proyectos | -| **Contracts** | Ciclo de vida de contratos (CLM) con extracción de cláusulas mediante IA | -| **Procurement** | Proveedores, órdenes de compra, conciliación de 3 vías | -| **Compliance** | Controles SOC 2 / ISO 27001 + recopilación de evidencias | -| **Helpdesk** | Gestión de tickets de soporte al cliente con IA como prioridad | -| **Content** | Calendario editorial + ROI por canal | -| **HR** | Directorio, organigrama, ausencias | -| **Project** | Seguimiento de proyectos / tareas / hitos | - -El código fuente está en -[github.com/objectstack-ai/templates](https://github.com/objectstack-ai/templates): -clona cualquiera de ellos como punto de partida para una aplicación personalizada. - -## Flujo de instalación - -1. **Abre Console** — http://localhost:3000/_console/ -2. **Inicia sesión** — si aún no existe ninguna cuenta, regístrate en `/_account/register` -3. **Navega a la pestaña del marketplace** -4. **Elige una aplicación y haz clic en Install** -5. **Recarga Console** — aparecen los objetos, las vistas y los flujos de la nueva aplicación - -Entre bastidores, el marketplace obtiene el artefacto compilado de la aplicación, -lo fusiona en el kernel en ejecución y registra sus objetos con ObjectQL. Los -datos de inicialización (si la aplicación los define) se insertan en la primera -instalación. - -## Desinstalación - -Desde Console → Marketplace → aplicación instalada → Uninstall. Los objetos de -la aplicación se eliminan del kernel y sus tablas se marcan para limpieza (los -datos se conservan de forma predeterminada; tú decides si eliminar las tablas). - -## Publicar tu propia aplicación - -Cualquier cosa que construyas con `os init` puede convertirse en una aplicación -del marketplace. - -```bash -os init my-app -t app --install -cd my-app -# ... write objects, views, etc. ... -os compile # → dist/objectstack.json -os package publish # publish to a catalog -``` - -Para publicar en el catálogo público necesitarás una cuenta de registro -(`os login`). Para publicar en un catálogo privado, apunta `OS_PACKAGE_REGISTRY` -al tuyo propio. - -## Versionado - -Cada aplicación publicada es inmutable. Las actualizaciones generan una nueva -versión. El runtime hace seguimiento de la versión instalada y de las -actualizaciones disponibles por aplicación. Los usuarios ven una insignia -"Update available" en Console cuando se publica una nueva versión en un catálogo -que están siguiendo. - -## Permisos - -La instalación de aplicaciones requiere el permiso de sistema -`manage_marketplace`: de forma predeterminada, solo los miembros del conjunto de -permisos **Setup Administrator** lo tienen. Los usuarios normales ven el -marketplace en modo de solo lectura. - -## Marketplaces en entornos aislados - -Para despliegues sin salida a internet, ejecuta un servidor de catálogo local -dentro de tu red y apunta ObjectOS hacia él. Consulta -[Air-gapped](/docs/deploy/air-gapped) para conocer la topología. - -## Qué no es el marketplace - -- **No es un canal de distribución de código.** Las aplicaciones publicadas son - artefactos compilados: describen datos + interfaz de usuario + flujos de forma - declarativa. No distribuyen JavaScript arbitrario. -- **No es un sandbox.** Una aplicación instalada tiene el mismo acceso a tu base - de datos que cualquier otro elemento del kernel: revisa el artefacto antes de - instalar aplicaciones de fuentes no confiables. -- **No es una plataforma de pagos** (todavía). Las aplicaciones del catálogo - público son gratuitas con licencia Apache-2.0. La distribución comercial / de - pago está en la hoja de ruta. diff --git a/content/docs/build/marketplace.fr.mdx b/content/docs/build/marketplace.fr.mdx deleted file mode 100644 index 2a6bddea..00000000 --- a/content/docs/build/marketplace.fr.mdx +++ /dev/null @@ -1,136 +0,0 @@ ---- -title: Marketplace -description: Installez des applications prêtes à l'emploi dans un ObjectOS en cours d'exécution, sans écrire de code. -translation: - source_sha: 6594741158e878583fe7c8ade604d28171cc95179827cdbd114fadbd105a34b5 - guide_rev: 1 - mode: auto ---- - -Le marketplace ObjectOS vous permet d'installer des applications -préconstruites dans un runtime en cours d'exécution — sans étape de -build, sans redémarrage, sans récupération du code source. C'est le -moyen le plus rapide de mettre un vrai logiciel entre les mains des -utilisateurs dès le premier jour. - -## Comment ça fonctionne - -Chaque runtime ObjectOS est livré avec les plugins `MarketplaceProxy` et -`MarketplaceInstallLocal` activés par défaut. Lorsque vous ouvrez la -Console (`/_console/`), l'onglet marketplace interroge le catalogue -d'applications configuré et affiche les applications installables. - -```text -You ─→ Console ─→ Marketplace tab ─→ pick app ─→ Install - ↓ - Artifact merged into kernel - ↓ - Console re-renders with new - objects / views / permissions - ↓ - Done — no restart -``` - -## Catalogues - -| Catalogue | Source | Quand l'utiliser | -|---|---|---| -| **Default** | Préfourni avec l'image du runtime | Première évaluation, démos, hors ligne | -| **Catalogue public ObjectStack** | Registre public d'applications | Dernières applications de la communauté et propriétaires | -| **Catalogue privé** | Vos propres artefacts publiés | Applications internes que vous ne souhaitez pas rendre publiques | -| **Local** | Fichiers montés dans le runtime | Environnements isolés, builds personnalisés | - -La source du catalogue est configurée via le plugin marketplace ou des -variables d'environnement ; voir [Runtime Configuration](/docs/configure/runtime). - -## Ce que contient le catalogue par défaut - -Ces applications sont prêtes à être installées en un clic dans la Console : - -| Application | Ce qu'elle vous apporte | -|---|---| -| **Todo** | Suivi universel des tâches et des projets | -| **Contracts** | Cycle de vie des contrats (CLM) avec extraction de clauses par IA | -| **Procurement** | Fournisseurs, bons de commande, rapprochement à trois voies | -| **Compliance** | Contrôles SOC 2 / ISO 27001 + collecte de preuves | -| **Helpdesk** | Gestion de tickets de support client orientée IA | -| **Content** | Calendrier éditorial + ROI par canal | -| **HR** | Annuaire, organigramme, congés | -| **Project** | Suivi des projets / tâches / jalons | - -Le code source se trouve sur -[github.com/objectstack-ai/templates](https://github.com/objectstack-ai/templates) — -clonez l'un d'entre eux comme point de départ pour une application personnalisée. - -## Flux d'installation - -1. **Ouvrez la Console** — http://localhost:3000/_console/ -2. **Connectez-vous** — si aucun compte n'existe encore, créez-en un sur `/_account/register` -3. **Accédez à l'onglet marketplace** -4. **Choisissez une application, cliquez sur Install** -5. **Rechargez la Console** — les objets, vues et flux de la nouvelle application apparaissent - -En coulisses, le marketplace récupère l'artefact compilé de -l'application, le fusionne dans le kernel en cours d'exécution et -enregistre ses objets auprès d'ObjectQL. Les données initiales (si -l'application en définit) sont insérées lors de la première -installation. - -## Désinstallation - -Depuis Console → Marketplace → application installée → Uninstall. Les -objets de l'application sont supprimés du kernel et ses tables sont -marquées pour nettoyage (les données sont conservées par défaut ; vous -choisissez de supprimer ou non les tables). - -## Publier votre propre application - -Tout ce que vous construisez avec `os init` peut devenir une application -de marketplace. - -```bash -os init my-app -t app --install -cd my-app -# ... write objects, views, etc. ... -os compile # → dist/objectstack.json -os package publish # publish to a catalog -``` - -Pour publier sur le catalogue public, vous aurez besoin d'un compte de -registre (`os login`). Pour publier sur un catalogue privé, pointez -`OS_PACKAGE_REGISTRY` vers le vôtre. - -## Gestion des versions - -Chaque application publiée est immuable. Les mises à jour produisent une -nouvelle version. Le runtime suit la version installée et les mises à -jour disponibles pour chaque application. Les utilisateurs voient un -badge « Update available » dans la Console lorsqu'une nouvelle version -est publiée dans un catalogue qu'ils suivent. - -## Permissions - -L'installation d'applications nécessite la permission système -`manage_marketplace` — par défaut, seuls les membres de l'ensemble de -permissions **Setup Administrator** la possèdent. Les utilisateurs -ordinaires voient le marketplace en lecture seule. - -## Marketplaces en environnement isolé - -Pour les déploiements sans accès Internet sortant, exécutez un serveur -de catalogue local au sein de votre réseau et pointez ObjectOS vers -celui-ci. Voir [Air-gapped](/docs/deploy/air-gapped) pour la topologie. - -## Ce que le marketplace n'est pas - -- **Ce n'est pas un canal de distribution de code.** Les applications - publiées sont des artefacts compilés — elles décrivent données + UI + - flux de manière déclarative. Elles ne livrent pas de JavaScript - arbitraire. -- **Ce n'est pas un bac à sable.** Une application installée dispose du - même accès à votre base de données que tout le reste dans le kernel — - examinez l'artefact avant d'installer des applications provenant de - sources non fiables. -- **Ce n'est pas (encore) une plateforme de paiement.** Les applications - du catalogue public sont gratuites et sous licence Apache-2.0. La - distribution commerciale / payante figure sur la feuille de route. diff --git a/content/docs/build/marketplace.ja.mdx b/content/docs/build/marketplace.ja.mdx deleted file mode 100644 index b4173284..00000000 --- a/content/docs/build/marketplace.ja.mdx +++ /dev/null @@ -1,128 +0,0 @@ ---- -title: marketplace -description: コードを書かずに、稼働中の ObjectOS に既製のアプリをインストールします。 -translation: - source_sha: 6594741158e878583fe7c8ade604d28171cc95179827cdbd114fadbd105a34b5 - guide_rev: 1 - mode: auto ---- - -ObjectOS の marketplace を使うと、ビルド手順もリスタートもソースのチェックアウトも不要で、 -稼働中のランタイムに構築済みのアプリをインストールできます。初日からユーザーに -実用的なソフトウェアを届ける最速の方法です。 - -## 仕組み - -すべての ObjectOS ランタイムには、デフォルトで `MarketplaceProxy` と -`MarketplaceInstallLocal` プラグインが有効化された状態で同梱されています。Console -（`/_console/`）を開くと、marketplace タブが設定済みのアプリ -カタログに問い合わせ、インストール可能なアプリを表示します。 - -```text -You ─→ Console ─→ Marketplace tab ─→ pick app ─→ Install - ↓ - Artifact merged into kernel - ↓ - Console re-renders with new - objects / views / permissions - ↓ - Done — no restart -``` - -## カタログ - -| カタログ | ソース | 使いどころ | -|---|---|---| -| **デフォルト** | ランタイムイメージにあらかじめ同梱 | 初回評価、デモ、オフライン | -| **ObjectStack 公開カタログ** | 公開アプリレジストリ | 最新のコミュニティ製 + ファーストパーティ製アプリ | -| **プライベートカタログ** | 自分で公開したアーティファクト | 公開したくない社内向けアプリ | -| **ローカル** | ランタイムにマウントしたファイル | エアギャップ環境、カスタムビルド | - -カタログのソースは marketplace プラグインまたは環境変数で設定します。 -詳しくは [Runtime Configuration](/docs/configure/runtime) を参照してください。 - -## デフォルトカタログに含まれるもの - -これらのアプリは Console でワンクリックですぐにインストールできます。 - -| アプリ | 提供される機能 | -|---|---| -| **Todo** | 汎用のタスク・プロジェクト管理ツール | -| **Contracts** | AI 条項抽出を備えた契約ライフサイクル管理（CLM） | -| **Procurement** | ベンダー、発注書、3-way マッチング | -| **Compliance** | SOC 2 / ISO 27001 統制 + エビデンス収集 | -| **Helpdesk** | AI ファーストのカスタマーサポートチケット管理 | -| **Content** | 編集カレンダー + チャネル ROI | -| **HR** | ディレクトリ、組織図、休暇管理 | -| **Project** | プロジェクト / タスク / マイルストーン管理 | - -ソースは -[github.com/objectstack-ai/templates](https://github.com/objectstack-ai/templates) -にあります。いずれかをクローンして、カスタムアプリの出発点として利用できます。 - -## インストールの流れ - -1. **Console を開く** — http://localhost:3000/_console/ -2. **サインインする** — まだアカウントがない場合は `/_account/register` で登録します -3. **marketplace タブに移動する** -4. **アプリを選び、Install をクリックする** -5. **Console をリロードする** — 新しいアプリのオブジェクト、ビュー、フローが表示されます - -裏側では、marketplace がアプリのコンパイル済みアーティファクトを取得し、 -稼働中の kernel にマージし、そのオブジェクトを ObjectQL に登録します。 -シードデータは（アプリが定義していれば）初回インストール時に挿入されます。 - -## アンインストール - -Console → Marketplace → インストール済みアプリ → Uninstall から行います。アプリの -オブジェクトは kernel から削除され、そのテーブルはクリーンアップ対象として -マークされます（データはデフォルトで保持され、テーブルを削除するかどうかは -ユーザーが選択します）。 - -## 自分のアプリを公開する - -`os init` で構築したものはすべて marketplace アプリにできます。 - -```bash -os init my-app -t app --install -cd my-app -# ... write objects, views, etc. ... -os compile # → dist/objectstack.json -os package publish # publish to a catalog -``` - -公開カタログに公開するにはレジストリアカウント（`os login`）が必要です。 -プライベートカタログに公開するには、`OS_PACKAGE_REGISTRY` を自分の -レジストリに向けてください。 - -## バージョニング - -公開されたアプリはすべてイミュータブルです。更新すると新しいバージョンが -生成されます。ランタイムはアプリごとにインストール済みバージョンと利用可能な -更新を追跡します。追跡対象のカタログに新しいバージョンが公開されると、 -ユーザーには Console に「Update available」バッジが表示されます。 - -## 権限 - -アプリのインストールには `manage_marketplace` システム権限が必要です。 -デフォルトでは **Setup Administrator** 権限セットのメンバーのみがこの権限を -持ちます。一般ユーザーには marketplace が読み取り専用で表示されます。 - -## エアギャップ環境の marketplace - -インターネット egress のないデプロイメントでは、ネットワーク内でローカルの -カタログサーバーを実行し、そこへ ObjectOS を向けます。トポロジーについては -[Air-gapped](/docs/deploy/air-gapped) を参照してください。 - -## marketplace ではないもの - -- **コード配布チャネルではありません。** 公開されるアプリはコンパイル済みの - アーティファクトであり、データ + UI + フローを宣言的に記述したものです。 - 任意の JavaScript を配布するものではありません。 -- **サンドボックスではありません。** インストールされたアプリは、kernel 内の - 他のあらゆるものと同じように、あなたのデータベースにアクセスできます。 - 信頼できないソースのアプリをインストールする前に、アーティファクトを確認して - ください。 -- **（まだ）決済プラットフォームではありません。** 公開カタログのアプリは - Apache-2.0 で無償提供されます。商用 / 有償の配布はロードマップに含まれて - います。 diff --git a/content/docs/build/marketplace.ko.mdx b/content/docs/build/marketplace.ko.mdx deleted file mode 100644 index 914ec78d..00000000 --- a/content/docs/build/marketplace.ko.mdx +++ /dev/null @@ -1,123 +0,0 @@ ---- -title: marketplace -description: 코드를 작성하지 않고 실행 중인 ObjectOS에 완성된 앱을 설치합니다. -translation: - source_sha: 6594741158e878583fe7c8ade604d28171cc95179827cdbd114fadbd105a34b5 - guide_rev: 1 - mode: auto ---- - -ObjectOS marketplace를 사용하면 실행 중인 런타임에 사전 빌드된 앱을 설치할 수 -있습니다. 빌드 단계도, 재시작도, 소스 체크아웃도 필요하지 않습니다. 첫날부터 -실제 소프트웨어를 사용자에게 선보이는 가장 빠른 방법입니다. - -## 작동 방식 - -모든 ObjectOS 런타임에는 `MarketplaceProxy`와 `MarketplaceInstallLocal` -플러그인이 기본적으로 활성화되어 제공됩니다. Console(`/_console/`)을 열면 -marketplace 탭이 구성된 앱 카탈로그를 조회하고 설치 가능한 앱을 표시합니다. - -```text -You ─→ Console ─→ Marketplace tab ─→ pick app ─→ Install - ↓ - Artifact merged into kernel - ↓ - Console re-renders with new - objects / views / permissions - ↓ - Done — no restart -``` - -## 카탈로그 - -| 카탈로그 | 소스 | 사용 시점 | -|---|---|---| -| **Default** | 런타임 이미지에 사전 번들됨 | 첫 평가, 데모, 오프라인 | -| **ObjectStack public catalog** | 공개 앱 레지스트리 | 최신 커뮤니티 + 퍼스트파티 앱 | -| **Private catalog** | 직접 게시한 아티팩트 | 공개하고 싶지 않은 내부 앱 | -| **Local** | 런타임에 마운트된 파일 | 에어갭 환경, 커스텀 빌드 | - -카탈로그 소스는 marketplace 플러그인 또는 환경 변수를 통해 구성됩니다. -[Runtime Configuration](/docs/configure/runtime)을 참조하세요. - -## 기본 카탈로그에 포함된 내용 - -이 앱들은 Console에서 클릭 한 번으로 설치할 수 있습니다. - -| 앱 | 제공 기능 | -|---|---| -| **Todo** | 범용 작업 및 프로젝트 추적기 | -| **Contracts** | AI 조항 추출 기능이 포함된 계약 수명 주기(CLM) | -| **Procurement** | 공급업체, 발주서, 3자 대사(3-way match) | -| **Compliance** | SOC 2 / ISO 27001 통제 항목 + 증적 수집 | -| **Helpdesk** | AI 우선 고객 지원 티켓팅 | -| **Content** | 편집 캘린더 + 채널 ROI | -| **HR** | 디렉터리, 조직도, 휴가 관리 | -| **Project** | 프로젝트 / 작업 / 마일스톤 추적 | - -소스는 -[github.com/objectstack-ai/templates](https://github.com/objectstack-ai/templates)에 -있습니다. 이들 중 아무거나 복제하여 커스텀 앱의 출발점으로 삼으세요. - -## 설치 흐름 - -1. **Console 열기** — http://localhost:3000/_console/ -2. **로그인** — 아직 계정이 없다면 `/_account/register`에서 등록합니다 -3. **marketplace 탭으로 이동** -4. **앱을 선택하고 Install 클릭** -5. **Console 새로고침** — 새 앱의 오브젝트, 뷰, 플로우가 나타납니다 - -내부적으로 marketplace는 앱의 컴파일된 아티팩트를 가져와 실행 중인 커널에 -병합하고, 해당 오브젝트를 ObjectQL에 등록합니다. 시드 데이터는(앱이 정의한 -경우) 최초 설치 시 삽입됩니다. - -## 제거 - -Console → Marketplace → 설치된 앱 → Uninstall에서 제거합니다. 앱의 -오브젝트는 커널에서 제거되고 해당 테이블은 정리 대상으로 표시됩니다(데이터는 -기본적으로 유지되며, 테이블 삭제 여부는 사용자가 선택합니다). - -## 직접 만든 앱 게시하기 - -`os init`으로 빌드한 모든 것은 marketplace 앱이 될 수 있습니다. - -```bash -os init my-app -t app --install -cd my-app -# ... write objects, views, etc. ... -os compile # → dist/objectstack.json -os package publish # publish to a catalog -``` - -공개 카탈로그에 게시하려면 레지스트리 계정(`os login`)이 필요합니다. 프라이빗 -카탈로그에 게시하려면 `OS_PACKAGE_REGISTRY`를 직접 운영하는 레지스트리로 -지정하세요. - -## 버전 관리 - -게시된 모든 앱은 불변(immutable)입니다. 업데이트는 새 버전을 생성합니다. -런타임은 앱별로 설치된 버전과 사용 가능한 업데이트를 추적합니다. 추적 중인 -카탈로그에 새 버전이 게시되면 사용자는 Console에서 "Update available" 배지를 -보게 됩니다. - -## 권한 - -앱 설치에는 `manage_marketplace` 시스템 권한이 필요합니다. 기본적으로 -**Setup Administrator** 권한 집합의 구성원만 이 권한을 가집니다. 일반 -사용자에게는 marketplace가 읽기 전용으로 표시됩니다. - -## 에어갭 marketplace - -인터넷 송신이 없는 배포 환경에서는 네트워크 내부에 로컬 카탈로그 서버를 -실행하고 ObjectOS가 이를 가리키도록 합니다. 토폴로지는 -[Air-gapped](/docs/deploy/air-gapped)를 참조하세요. - -## marketplace가 아닌 것 - -- **코드 배포 채널이 아닙니다.** 게시된 앱은 컴파일된 아티팩트로, 데이터 + UI + - 플로우를 선언적으로 기술합니다. 임의의 JavaScript를 제공하지 않습니다. -- **샌드박스가 아닙니다.** 설치된 앱은 커널 내의 다른 무엇과 마찬가지로 - 데이터베이스에 동일하게 접근합니다. 신뢰할 수 없는 출처의 앱을 설치하기 - 전에는 아티팩트를 검토하세요. -- **(아직은) 결제 플랫폼이 아닙니다.** 공개 카탈로그의 앱은 무료 Apache-2.0 - 라이선스입니다. 상업적 / 유료 배포는 로드맵에 있습니다. diff --git a/content/docs/configure/api-access.de.mdx b/content/docs/configure/api-access.de.mdx deleted file mode 100644 index 2e03ccff..00000000 --- a/content/docs/configure/api-access.de.mdx +++ /dev/null @@ -1,140 +0,0 @@ ---- -title: API-Zugriff -description: Generierte REST-APIs, Authentifizierung und API-Schlüssel für Integrationen. -translation: - source_sha: 59e07888e7a8e425689a077f85312f83e2d9e55cf1cfe435d37dc30856f2d0a5 - guide_rev: 1 - mode: auto ---- - -Jedes im Artefakt deklarierte Objekt wird über eine generierte -REST-API bereitgestellt. Dieselben Endpunkte versorgen die UI, Integrationen -und Kunden-ETL-Skripte — es gibt keine separate „Integrations-API", die -gepflegt werden müsste. - -## Basis-URL - -```text -https:///api/v1 -``` - -Wichtige Schnittstellen: - -| Pfad | Zweck | -|---|---| -| `/api/v1/data/` | Generiertes CRUD für jedes Objekt (z. B. `/api/v1/data/account`) | -| `/api/v1/data//{id}` | Einzelnen Datensatz lesen/aktualisieren/löschen | -| `/api/v1/actions//` | Eine deklarative Aktion aufrufen (POST) | -| `/api/v1/auth/*` | Authentifizierung (Anmeldung, Sitzungen, OAuth, OIDC) | -| `/api/v1/meta/*` | Metadaten-APIs (Objekte, Felder, Ansichten), sofern aktiviert | -| `/api/v1/keys` | Erzeugt einen nur einmal angezeigten `sys_api_key` für den aufrufenden Benutzer (POST) | -| `/api/v1/batch` | Transaktionaler objektübergreifender Batch (POST) — ausschließlich atomar, jede Operation pro Objekt geprüft | -| `/api/v1/mcp` | Model-Context-Protocol-Server über Streamable HTTP — standardmäßig aktiv; deaktivierbar mit `OS_MCP_SERVER_ENABLED=false` | -| `/api/v1/health` | Liveness-/Readiness-Probe (keine Authentifizierung) | - -Das Präfix lautet standardmäßig `/api/v1` (der API-`basePath` von `/api` plus -die `version` `v1`) und ist im ObjectOS-Stack konfigurierbar. - -## Steuern, was offengelegt wird - -Die API-Offenlegung wird pro Objekt im Artefakt gesteuert, nicht am Gateway: - -- Setzen Sie `apiEnabled: false` auf einem Objekt, um es vollständig von der - REST-Oberfläche fernzuhalten (seine Routen liefern 404). -- Setzen Sie eine `apiMethods`-Whitelist (z. B. `['get', 'list']`), um ein - Objekt schreibgeschützt zu machen oder anderweitig einzuschränken, welche - Operationen erreichbar sind. - -Beide werden auf der REST-Ebene durchgesetzt — siehe -[REST-API → API-Oberfläche einschränken](/docs/reference/rest-api#restricting-the-api-surface). - -## Authentifizierungsoptionen - -Aufrufer können sich auf drei Arten authentifizieren: - -| Methode | Am besten geeignet für | Wie | -|---|---|---| -| Sitzungs-Cookie | Browser-/UI-Verkehr | Anmeldung über `/api/v1/auth/*`; Cookies sind auf den Projekt-Hostnamen beschränkt | -| Bearer-Zugriffstoken | Mobile, SPA, kurzlebige Server-Jobs | Anmeldedaten unter `/api/v1/auth/sign-in/email` austauschen und `Authorization: Bearer ` übergeben | -| API-Schlüssel | Server-zu-Server, ETL, langlebige Integrationen | Einen `sys_api_key` erstellen und als Bearer-Token übergeben | - -Alle drei durchlaufen dasselbe `AuthPlugin` und werden zu einem -`sys_user`-Kontext aufgelöst, den das `SecurityPlugin` anhand von -Berechtigungen und Datensatzzugriff auswertet. - -## API-Schlüssel - -API-Schlüssel sind erstklassige `sys_api_key`-Datensätze. Der Schlüsselwert -selbst wird gehasht gespeichert — nur das `prefix` und Metadaten bleiben -abfragbar, sodass ein durchgesickerter Schlüssel nicht aus der Datenbank -rekonstruiert werden kann. - -Es gibt zwei Wege, einen Schlüssel auszustellen: - -- **Console** — melden Sie sich als Administrator bei **Console → API Keys** - an, wählen Sie den besitzenden Benutzer, legen Sie optional ein Ablaufdatum - fest und kopieren Sie das angezeigte Geheimnis **einmalig**. -- **Self-Service-Endpunkt** — `POST /api/v1/keys` erzeugt einen Schlüssel für - den authentifizierten Aufrufer und gibt das rohe Geheimnis genau einmal - zurück. Der Schlüssel ist an den eigenen Benutzer des Aufrufers gebunden und - kann daher nicht zur Identitätsübernahme verwendet werden: - - ```bash - curl -X POST https://app.example.com/api/v1/keys \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d '{"name": "etl-pipeline"}' - # → { "id": "...", "name": "etl-pipeline", "prefix": "os_pk_…", "key": "os_pk_live_…" } - ``` - -Übergeben Sie den Schlüssel bei nachfolgenden Anfragen als Bearer-Token, als -`x-api-key`-Header oder als `Authorization: ApiKey`. Die REST-Daten- und -Metadaten-APIs authentifizieren ihn über denselben Verifier wie MCP, unter den -Berechtigungen und der Datensatz-Sicherheit des Schlüsselinhabers: - -```bash -curl https://app.example.com/api/v1/data/account \ - -H "x-api-key: os_pk_live_…" -``` - -Um einen Schlüssel zu widerrufen, führen Sie die Aktion `revoke_api_key` für -den entsprechenden `sys_api_key`-Datensatz aus (auch in der Console-UI -verfügbar). Der Widerruf wird ab der nächsten Anfrage sofort wirksam. - -## Paginierung, Filterung und Sortierung - -Generierte Listen-Endpunkte akzeptieren die standardmäßigen -ObjectStack-Abfrageparameter: - -| Parameter | Bedeutung | -|---|---| -| `?limit=` | Seitengröße (unterliegt einer serverseitigen Obergrenze) | -| `?offset=` oder `?cursor=` | Paginierung | -| `?filter=` | Serverseitige Filterung mit der ObjectQL-Filtersyntax | -| `?sort=` | Sortierausdruck (z. B. `-created_at`) | -| `?fields=` | Sparse-Feldauswahl | - -Die vollständige Filtergrammatik finden Sie in der Framework-Dokumentation — -die Laufzeitgrammatik ist die maßgebliche Quelle. - -## Ratenbegrenzung - -Verwenden Sie das `RateLimiter`-Primitiv des Frameworks (oder Ihr Ingress / -API-Gateway), um Limits pro IP und pro Identität anzuwenden. Empfohlene -Ausgangswerte sind unter [Production readiness](/docs/operate/production) -dokumentiert. - -## CORS - -Wenn Aufrufer in einem Browser mit einem anderen Origin ausgeführt werden, -konfigurieren Sie CORS am Ingress oder über die Middleware der Laufzeit. -Kombinieren Sie Wildcard-Origins **nicht** mit Anfragen, die Anmeldedaten -enthalten. - -## OpenAPI / Discovery - -Die Laufzeit kann ein OpenAPI-Dokument für die generierte REST-API -bereitstellen, wenn die entsprechende Funktion im Image enthalten ist. -Kundenintegrationen sollten Clients aus dem OpenAPI-Dokument pro Deployment -generieren, anstatt URLs von Hand zu erstellen, da Objektnamen und generierte -Routen dem bereitgestellten Artefakt folgen. diff --git a/content/docs/configure/api-access.es.mdx b/content/docs/configure/api-access.es.mdx deleted file mode 100644 index b5db7cf9..00000000 --- a/content/docs/configure/api-access.es.mdx +++ /dev/null @@ -1,140 +0,0 @@ ---- -title: Acceso a la API -description: APIs REST generadas, autenticación y claves de API para integraciones. -translation: - source_sha: 59e07888e7a8e425689a077f85312f83e2d9e55cf1cfe435d37dc30856f2d0a5 - guide_rev: 1 - mode: auto ---- - -Cada objeto declarado en el artefacto se expone a través de una API -REST generada. Los mismos endpoints alimentan la UI, las integraciones y -los scripts ETL de los clientes — no hay una "API de integración" separada -que mantener. - -## URL base - -```text -https:///api/v1 -``` - -Superficies destacadas: - -| Ruta | Propósito | -|---|---| -| `/api/v1/data/` | CRUD generado para cada objeto (p. ej. `/api/v1/data/account`) | -| `/api/v1/data//{id}` | Leer/actualizar/eliminar un registro individual | -| `/api/v1/actions//` | Invocar una acción declarativa (POST) | -| `/api/v1/auth/*` | Autenticación (inicio de sesión, sesiones, OAuth, OIDC) | -| `/api/v1/meta/*` | APIs de metadatos (objetos, campos, vistas) cuando está habilitado | -| `/api/v1/keys` | Genera un `sys_api_key` de un solo uso para el usuario que llama (POST) | -| `/api/v1/batch` | Batch transaccional entre objetos (POST) — solo atómico, cada operación validada por objeto | -| `/api/v1/mcp` | Servidor Model Context Protocol sobre Streamable HTTP — activo de forma predeterminada; se desactiva con `OS_MCP_SERVER_ENABLED=false` | -| `/api/v1/health` | Sonda de liveness/readiness (sin autenticación) | - -El prefijo es `/api/v1` de forma predeterminada (el `basePath` de la API, -`/api`, más la `version`, `v1`) y es configurable en el stack de ObjectOS. - -## Controlar qué se expone - -La exposición de la API se gobierna por objeto en el artefacto, no en la puerta -de enlace: - -- Establece `apiEnabled: false` en un objeto para mantenerlo fuera de la - superficie REST por completo (sus rutas devuelven 404). -- Establece una lista blanca `apiMethods` (p. ej. `['get', 'list']`) para hacer - un objeto de solo lectura o restringir de otro modo qué operaciones son - accesibles. - -Ambos se aplican en la capa REST; consulta -[API REST → Restringir la superficie de la API](/docs/reference/rest-api#restricting-the-api-surface). - -## Opciones de autenticación - -Los clientes pueden autenticarse de tres maneras: - -| Método | Ideal para | Cómo | -|---|---|---| -| Cookie de sesión | Tráfico de navegador/UI | Inicia sesión a través de `/api/v1/auth/*`; las cookies se limitan al nombre de host del proyecto | -| Token de acceso Bearer | Móvil, SPA, trabajos de servidor de corta duración | Intercambia credenciales en `/api/v1/auth/sign-in/email` y pasa `Authorization: Bearer ` | -| Clave de API | Servidor a servidor, ETL, integraciones de larga duración | Crea un `sys_api_key` y pásalo como token bearer | - -Las tres pasan por el mismo `AuthPlugin` y se resuelven en un contexto -`sys_user` que el `SecurityPlugin` evalúa frente a los permisos y el -acceso a registros. - -## Claves de API - -Las claves de API son registros `sys_api_key` de primera clase. El valor -de la clave en sí se almacena cifrado (hash) — solo el `prefix` y los -metadatos permanecen consultables, de modo que una clave filtrada no puede -reconstruirse a partir de la base de datos. - -Emite una clave de dos maneras: - -- **Console** — inicia sesión en **Console → API Keys** como administrador, - elige el usuario propietario, opcionalmente establece una fecha de - expiración y copia el secreto mostrado **una sola vez**. -- **Endpoint de autoservicio** — `POST /api/v1/keys` genera una clave para el - llamante autenticado y devuelve el secreto en bruto exactamente una vez. La - clave queda fijada al propio usuario del llamante, por lo que no puede usarse - para suplantar otra identidad: - - ```bash - curl -X POST https://app.example.com/api/v1/keys \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d '{"name": "etl-pipeline"}' - # → { "id": "...", "name": "etl-pipeline", "prefix": "os_pk_…", "key": "os_pk_live_…" } - ``` - -Pasa la clave en las solicitudes posteriores como token bearer, como cabecera -`x-api-key` o como `Authorization: ApiKey`. Las API REST de datos y metadatos -la autentican con el mismo verificador que MCP, bajo los permisos y la -seguridad a nivel de registro del propietario de la clave: - -```bash -curl https://app.example.com/api/v1/data/account \ - -H "x-api-key: os_pk_live_…" -``` - -Para revocar una clave, ejecuta la acción `revoke_api_key` en el registro -`sys_api_key` correspondiente (también disponible en la UI de Console). La -revocación surte efecto de inmediato en la siguiente solicitud. - -## Paginación, filtrado y ordenación - -Los endpoints de listado generados aceptan los parámetros de consulta -estándar de ObjectStack: - -| Parámetro | Significado | -|---|---| -| `?limit=` | Tamaño de página (sujeto a un límite máximo en el servidor) | -| `?offset=` o `?cursor=` | Paginación | -| `?filter=` | Filtrado en el servidor usando la sintaxis de filtros de ObjectQL | -| `?sort=` | Expresión de ordenación (p. ej. `-created_at`) | -| `?fields=` | Selección dispersa de campos | - -Consulta la documentación del framework para conocer la gramática completa -de filtros — la gramática del runtime es la fuente de verdad. - -## Limitación de tasa - -Usa la primitiva `RateLimiter` del framework (o tu ingress / gateway de -API) para aplicar límites por IP y por identidad. Los buckets iniciales -recomendados están documentados en [Production readiness](/docs/operate/production). - -## CORS - -Si los clientes se ejecutan en un navegador desde un origen diferente, -configura CORS en el ingress o mediante el middleware del runtime. **No** -combines orígenes con comodín con solicitudes que incluyan credenciales. - -## OpenAPI / descubrimiento - -El runtime puede servir un documento OpenAPI para la API REST generada -cuando la capacidad correspondiente está incluida en la imagen. Las -integraciones de los clientes deberían generar clientes a partir del -documento OpenAPI por despliegue en lugar de construir URLs a mano, -porque los nombres de los objetos y las rutas generadas siguen el -artefacto desplegado. diff --git a/content/docs/configure/api-access.fr.mdx b/content/docs/configure/api-access.fr.mdx deleted file mode 100644 index f77af88f..00000000 --- a/content/docs/configure/api-access.fr.mdx +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: Accès API -description: API REST générées, authentification et clés API pour les intégrations. -translation: - source_sha: 59e07888e7a8e425689a077f85312f83e2d9e55cf1cfe435d37dc30856f2d0a5 - guide_rev: 1 - mode: auto ---- - -Chaque objet déclaré dans l'artefact est exposé via une API REST générée. -Les mêmes points de terminaison alimentent l'interface utilisateur, les -intégrations et les scripts ETL des clients — il n'y a aucune « API -d'intégration » distincte à maintenir. - -## URL de base - -```text -https:///api/v1 -``` - -Surfaces notables : - -| Chemin | Objectif | -|---|---| -| `/api/v1/data/` | CRUD généré pour chaque objet (par ex. `/api/v1/data/account`) | -| `/api/v1/data//{id}` | Lire/mettre à jour/supprimer un enregistrement unique | -| `/api/v1/actions//` | Invoquer une action déclarative (POST) | -| `/api/v1/auth/*` | Authentification (connexion, sessions, OAuth, OIDC) | -| `/api/v1/meta/*` | API de métadonnées (objets, champs, vues) lorsqu'elles sont activées | -| `/api/v1/keys` | Génère une `sys_api_key` affichée une seule fois pour l'utilisateur appelant (POST) | -| `/api/v1/batch` | Batch transactionnel inter-objets (POST) — atomique uniquement, chaque opération contrôlée par objet | -| `/api/v1/mcp` | Serveur Model Context Protocol via Streamable HTTP — actif par défaut ; se désactive avec `OS_MCP_SERVER_ENABLED=false` | -| `/api/v1/health` | Sonde de vivacité/disponibilité (sans authentification) | - -Le préfixe est `/api/v1` par défaut (le `basePath` de l'API `/api` plus la -`version` `v1`) et il est configurable sur la stack ObjectOS. - -## Contrôler ce qui est exposé - -L'exposition de l'API est gouvernée par objet dans l'artefact, et non au niveau -de la passerelle : - -- Définissez `apiEnabled: false` sur un objet pour le garder entièrement hors de - la surface REST (ses routes renvoient 404). -- Définissez une liste blanche `apiMethods` (par ex. `['get', 'list']`) pour - rendre un objet en lecture seule ou restreindre autrement les opérations - accessibles. - -Les deux sont appliqués au niveau de la couche REST — voir -[API REST → Restreindre la surface d'API](/docs/reference/rest-api#restricting-the-api-surface). - -## Options d'authentification - -Les appelants peuvent s'authentifier de trois façons : - -| Méthode | Idéale pour | Comment | -|---|---|---| -| Cookie de session | Trafic navigateur/UI | Connectez-vous via `/api/v1/auth/*` ; les cookies sont limités au nom d'hôte du projet | -| Jeton d'accès Bearer | Mobile, SPA, tâches serveur à courte durée de vie | Échangez les identifiants à `/api/v1/auth/sign-in/email` et passez `Authorization: Bearer ` | -| Clé API | Serveur à serveur, ETL, intégrations à longue durée de vie | Créez une `sys_api_key` et passez-la comme jeton bearer | - -Les trois passent par le même `AuthPlugin` et se résolvent en un contexte -`sys_user` que le `SecurityPlugin` évalue par rapport aux permissions et à -l'accès aux enregistrements. - -## Clés API - -Les clés API sont des enregistrements `sys_api_key` de première classe. La -valeur de la clé elle-même est stockée hachée — seuls le `prefix` et les -métadonnées restent interrogeables, de sorte qu'une clé divulguée ne peut -pas être reconstituée à partir de la base de données. - -Émettez une clé de deux façons : - -- **Console** — connectez-vous à **Console → API Keys** en tant - qu'administrateur, choisissez l'utilisateur propriétaire, définissez - éventuellement une date d'expiration et copiez le secret affiché **une seule - fois**. -- **Endpoint en libre-service** — `POST /api/v1/keys` génère une clé pour - l'appelant authentifié et renvoie le secret brut exactement une fois. La clé - est rattachée au propre utilisateur de l'appelant et ne peut donc pas servir - à usurper une autre identité : - - ```bash - curl -X POST https://app.example.com/api/v1/keys \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d '{"name": "etl-pipeline"}' - # → { "id": "...", "name": "etl-pipeline", "prefix": "os_pk_…", "key": "os_pk_live_…" } - ``` - -Passez la clé sur les requêtes suivantes comme jeton bearer, comme en-tête -`x-api-key` ou comme `Authorization: ApiKey`. Les API REST de données et de -métadonnées l'authentifient via le même vérificateur que MCP, sous les -permissions et la sécurité au niveau des enregistrements du propriétaire de la -clé : - -```bash -curl https://app.example.com/api/v1/data/account \ - -H "x-api-key: os_pk_live_…" -``` - -Pour révoquer une clé, exécutez l'action `revoke_api_key` sur -l'enregistrement `sys_api_key` correspondant (également disponible dans -l'interface de la Console). La révocation prend effet immédiatement lors de -la requête suivante. - -## Pagination, filtrage et tri - -Les points de terminaison de liste générés acceptent les paramètres de -requête ObjectStack standard : - -| Paramètre | Signification | -|---|---| -| `?limit=` | Taille de page (soumise à un plafond côté serveur) | -| `?offset=` ou `?cursor=` | Pagination | -| `?filter=` | Filtrage côté serveur utilisant la syntaxe de filtre ObjectQL | -| `?sort=` | Expression de tri (par ex. `-created_at`) | -| `?fields=` | Sélection partielle de champs | - -Reportez-vous à la documentation du framework pour la grammaire de filtre -complète — la grammaire d'exécution fait foi. - -## Limitation de débit - -Utilisez la primitive `RateLimiter` du framework (ou votre ingress / API -gateway) pour appliquer des limites par IP et par identité. Les compartiments -de départ recommandés sont documentés dans [Préparation à la production](/docs/operate/production). - -## CORS - -Si les appelants s'exécutent dans un navigateur sur une origine différente, -configurez CORS au niveau de l'ingress ou via le middleware du runtime. Ne -combinez **pas** les origines génériques avec des requêtes avec -identifiants. - -## OpenAPI / découverte - -Le runtime peut servir un document OpenAPI pour l'API REST générée lorsque -la capacité correspondante est incluse dans l'image. Les intégrations -clients devraient générer leurs clients à partir du document OpenAPI propre -à chaque déploiement plutôt que de construire les URL à la main, car les -noms d'objets et les routes générées suivent l'artefact déployé. diff --git a/content/docs/configure/api-access.ja.mdx b/content/docs/configure/api-access.ja.mdx deleted file mode 100644 index 24dfa7f9..00000000 --- a/content/docs/configure/api-access.ja.mdx +++ /dev/null @@ -1,135 +0,0 @@ ---- -title: API アクセス -description: 統合のために生成される REST API、認証、API キーについて。 -translation: - source_sha: 59e07888e7a8e425689a077f85312f83e2d9e55cf1cfe435d37dc30856f2d0a5 - guide_rev: 1 - mode: auto ---- - -アーティファクトで宣言されたすべてのオブジェクトは、生成された REST API -を通じて公開されます。同じエンドポイントが UI、統合、顧客の ETL -スクリプトを支えており、別途維持すべき「統合用 API」は存在しません。 - -## ベース URL - -```text -https:///api/v1 -``` - -主なエンドポイント: - -| Path | 用途 | -|---|---| -| `/api/v1/data/` | 各オブジェクトに対して生成される CRUD（例: `/api/v1/data/account`） | -| `/api/v1/data//{id}` | 単一レコードの読み取り／更新／削除 | -| `/api/v1/actions//` | 宣言的アクションの呼び出し（POST） | -| `/api/v1/auth/*` | 認証（サインイン、セッション、OAuth、OIDC） | -| `/api/v1/meta/*` | 有効化されている場合のメタデータ API（オブジェクト、フィールド、ビュー） | -| `/api/v1/keys` | 呼び出しユーザー向けに一度だけ表示される `sys_api_key` を発行（POST） | -| `/api/v1/batch` | オブジェクト横断のトランザクショナルバッチ（POST）— アトミックのみ、各操作をオブジェクト単位でゲート | -| `/api/v1/mcp` | Streamable HTTP 経由の Model Context Protocol サーバー — デフォルトで有効。`OS_MCP_SERVER_ENABLED=false` で無効化 | -| `/api/v1/health` | 死活／準備状態のプローブ（認証不要） | - -プレフィックスのデフォルトは `/api/v1`（API の `basePath` である `/api` と -`version` である `v1` の組み合わせ）で、ObjectOS スタック上で構成可能です。 - -## 公開範囲の制御 - -API の公開はゲートウェイではなく、アーティファクト内のオブジェクト単位で制御されます: - -- オブジェクトに `apiEnabled: false` を設定すると、REST 表面から完全に外れます - （そのルートは 404 になります）。 -- `apiMethods` ホワイトリスト（例: `['get', 'list']`）を設定すると、オブジェクトを - 読み取り専用にしたり、到達可能な操作を制限したりできます。 - -どちらも REST レイヤーで強制適用されます。 -[REST API → API 表面の制限](/docs/reference/rest-api#restricting-the-api-surface) を参照してください。 - -## 認証オプション - -呼び出し元は次の 3 つの方法で認証できます: - -| 方法 | 適した用途 | やり方 | -|---|---|---| -| セッション Cookie | ブラウザ／UI のトラフィック | `/api/v1/auth/*` を通じてサインインします。Cookie はプロジェクトのホスト名にスコープされます | -| Bearer アクセストークン | モバイル、SPA、短命のサーバージョブ | `/api/v1/auth/sign-in/email` で資格情報を交換し、`Authorization: Bearer ` を渡します | -| API キー | サーバー間連携、ETL、長期間の統合 | `sys_api_key` を作成し、bearer トークンとして渡します | - -3 つの方法はいずれも同じ `AuthPlugin` を通過し、`SecurityPlugin` が権限と -レコードアクセスに対して評価する `sys_user` コンテキストに解決されます。 - -## API キー - -API キーはファーストクラスの `sys_api_key` レコードです。キーの値自体は -ハッシュ化して保存され、クエリ可能なのは `prefix` とメタデータのみです。 -そのため、漏洩したキーをデータベースから復元することはできません。 - -キーは次の 2 つの方法で発行できます: - -- **Console** — 管理者として **Console → API Keys** にサインインし、所有 - ユーザーを選択し、必要に応じて有効期限を設定して、表示されたシークレットを - **一度だけ**コピーします。 -- **セルフサービスエンドポイント** — `POST /api/v1/keys` は認証済みの呼び出し元 - に対してキーを発行し、生のシークレットをちょうど一度だけ返します。キーは - 呼び出し元自身のユーザーに固定されるため、別の ID へのなりすましには使用 - できません: - - ```bash - curl -X POST https://app.example.com/api/v1/keys \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d '{"name": "etl-pipeline"}' - # → { "id": "...", "name": "etl-pipeline", "prefix": "os_pk_…", "key": "os_pk_live_…" } - ``` - -以降のリクエストでは、キーを bearer トークン、`x-api-key` ヘッダー、または -`Authorization: ApiKey` として渡します。REST のデータ／メタデータ API はいずれも -MCP と同じ検証器で認証し、キー所有者の権限とレコードレベルセキュリティの下で -実行されます: - -```bash -curl https://app.example.com/api/v1/data/account \ - -H "x-api-key: os_pk_live_…" -``` - -キーを失効させるには、対応する `sys_api_key` レコードに対して -`revoke_api_key` アクションを実行します（Console UI でも利用可能）。 -失効は次のリクエストから即座に有効になります。 - -## ページネーション、フィルタリング、ソート - -生成されるリストエンドポイントは、標準の ObjectStack -クエリパラメーターを受け付けます: - -| パラメーター | 意味 | -|---|---| -| `?limit=` | ページサイズ（サーバー側の上限が適用されます） | -| `?offset=` または `?cursor=` | ページネーション | -| `?filter=` | ObjectQL のフィルター構文を使用したサーバー側フィルタリング | -| `?sort=` | ソート式（例: `-created_at`） | -| `?fields=` | スパースなフィールド選択 | - -完全なフィルター文法についてはフレームワークのドキュメントを参照してください。 -ランタイムの文法が信頼できる情報源です。 - -## レート制限 - -フレームワークの `RateLimiter` プリミティブ（または ingress / API -ゲートウェイ）を使用して、IP ごと・アイデンティティごとの制限を適用します。 -推奨される初期バケットは [本番環境への準備](/docs/operate/production) -に記載されています。 - -## CORS - -呼び出し元が異なるオリジンのブラウザで動作する場合は、ingress または -ランタイムのミドルウェアで CORS を構成します。ワイルドカードオリジンと -資格情報付きリクエストを**組み合わせないでください**。 - -## OpenAPI / ディスカバリー - -該当する機能がイメージに含まれている場合、ランタイムは生成された REST API -の OpenAPI ドキュメントを提供できます。オブジェクト名や生成されたルートは -デプロイされたアーティファクトに従うため、顧客の統合では URL を手作業で -組み立てるのではなく、デプロイごとの OpenAPI ドキュメントからクライアントを -生成してください。 diff --git a/content/docs/configure/api-access.ko.mdx b/content/docs/configure/api-access.ko.mdx deleted file mode 100644 index 278ba117..00000000 --- a/content/docs/configure/api-access.ko.mdx +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: API 액세스 -description: 통합을 위한 생성된 REST API, 인증 및 API 키. -translation: - source_sha: 59e07888e7a8e425689a077f85312f83e2d9e55cf1cfe435d37dc30856f2d0a5 - guide_rev: 1 - mode: auto ---- - -아티팩트에 선언된 모든 오브젝트는 생성된 REST API를 통해 노출됩니다. -동일한 엔드포인트가 UI, 통합, 고객 ETL 스크립트를 모두 구동하므로 -별도로 유지 관리해야 할 "통합 API"가 없습니다. - -## 기본 URL - -```text -https:///api/v1 -``` - -주요 엔드포인트: - -| 경로 | 용도 | -|---|---| -| `/api/v1/data/` | 각 오브젝트에 대해 생성된 CRUD (예: `/api/v1/data/account`) | -| `/api/v1/data//{id}` | 단일 레코드 읽기/업데이트/삭제 | -| `/api/v1/actions//` | 선언적 액션 호출 (POST) | -| `/api/v1/auth/*` | 인증 (로그인, 세션, OAuth, OIDC) | -| `/api/v1/meta/*` | 활성화된 경우 메타데이터 API (오브젝트, 필드, 뷰) | -| `/api/v1/keys` | 호출 사용자를 위해 한 번만 표시되는 `sys_api_key` 발급 (POST) | -| `/api/v1/batch` | 오브젝트 간 트랜잭션 배치 (POST) — 원자적 실행만 지원, 모든 작업을 오브젝트별로 게이트 | -| `/api/v1/mcp` | Streamable HTTP를 통한 Model Context Protocol 서버 — 기본 활성화, `OS_MCP_SERVER_ENABLED=false`로 비활성화 | -| `/api/v1/health` | 활성/준비 상태 프로브 (인증 없음) | - -접두사는 기본적으로 `/api/v1`(API `basePath`인 `/api`에 `version`인 `v1`을 -더한 값)이며 ObjectOS 스택에서 구성할 수 있습니다. - -## 노출 대상 제어 - -API 노출은 게이트웨이가 아니라 아티팩트 안에서 객체 단위로 제어됩니다: - -- 객체에 `apiEnabled: false`를 설정하면 REST 표면에서 완전히 제외됩니다(해당 - 라우트는 404). -- `apiMethods` 화이트리스트(예: `['get', 'list']`)를 설정하면 객체를 읽기 전용으로 - 만들거나 도달 가능한 작업을 그 밖의 방식으로 제한할 수 있습니다. - -이 둘은 REST 계층에서 강제됩니다 — -[REST API → Restricting the API surface](/docs/reference/rest-api#restricting-the-api-surface)을 -참조하세요. - -## 인증 옵션 - -호출자는 세 가지 방식으로 인증할 수 있습니다. - -| 방식 | 적합한 용도 | 방법 | -|---|---|---| -| 세션 쿠키 | 브라우저/UI 트래픽 | `/api/v1/auth/*`를 통해 로그인하며, 쿠키는 프로젝트 호스트명으로 범위가 지정됩니다 | -| Bearer 액세스 토큰 | 모바일, SPA, 단기 서버 작업 | `/api/v1/auth/sign-in/email`에서 자격 증명을 교환하고 `Authorization: Bearer `을 전달합니다 | -| API 키 | 서버 간 통신, ETL, 장기 통합 | `sys_api_key`를 생성하고 bearer 토큰으로 전달합니다 | - -세 가지 방식 모두 동일한 `AuthPlugin`을 거쳐 `sys_user` 컨텍스트로 -확인되며, `SecurityPlugin`이 이를 권한 및 레코드 액세스에 대해 평가합니다. - -## API 키 - -API 키는 일급 `sys_api_key` 레코드입니다. 키 값 자체는 해시되어 -저장되며 `prefix`와 메타데이터만 쿼리할 수 있으므로, 유출된 키를 -데이터베이스에서 재구성할 수 없습니다. - -키는 두 가지 방법으로 발급할 수 있습니다: - -- **Console** — 관리자 권한으로 **Console → API Keys**에 로그인하고, 소유 - 사용자를 선택하고, 선택적으로 만료일을 설정한 다음, 표시된 비밀 키를 **한 번** - 복사합니다. -- **셀프 서비스 엔드포인트** — `POST /api/v1/keys`는 인증된 호출자를 위해 키를 - 발급하고 원본 비밀 키를 정확히 한 번 반환합니다. 키는 호출자 본인의 사용자에 - 고정되므로 다른 ID를 사칭하는 데 사용할 수 없습니다: - - ```bash - curl -X POST https://app.example.com/api/v1/keys \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d '{"name": "etl-pipeline"}' - # → { "id": "...", "name": "etl-pipeline", "prefix": "os_pk_…", "key": "os_pk_live_…" } - ``` - -이후 요청에서는 키를 bearer 토큰, `x-api-key` 헤더 또는 `Authorization: ApiKey`로 -전달합니다. REST 데이터 및 메타데이터 API는 모두 MCP와 동일한 검증기로 이를 -인증하며, 키 소유자의 권한과 레코드 수준 보안 아래에서 실행됩니다: - -```bash -curl https://app.example.com/api/v1/data/account \ - -H "x-api-key: os_pk_live_…" -``` - -키를 취소하려면 해당 `sys_api_key` 레코드에서 `revoke_api_key` 액션을 -실행합니다(Console UI에서도 사용 가능). 취소는 다음 요청에서 즉시 -적용됩니다. - -## 페이지네이션, 필터링 및 정렬 - -생성된 목록 엔드포인트는 표준 ObjectStack 쿼리 매개변수를 허용합니다. - -| 매개변수 | 의미 | -|---|---| -| `?limit=` | 페이지 크기 (서버 측 상한 적용) | -| `?offset=` 또는 `?cursor=` | 페이지네이션 | -| `?filter=` | ObjectQL 필터 구문을 사용한 서버 측 필터링 | -| `?sort=` | 정렬 표현식 (예: `-created_at`) | -| `?fields=` | 희소 필드 선택 | - -전체 필터 문법은 프레임워크 문서를 참조하십시오 — 런타임 문법이 -소스 오브 트루스입니다. - -## 속도 제한 - -프레임워크의 `RateLimiter` 프리미티브(또는 인그레스 / API 게이트웨이)를 -사용하여 IP별 및 ID별 제한을 적용하십시오. 권장 시작 버킷은 -[Production readiness](/docs/operate/production)에 문서화되어 있습니다. - -## CORS - -호출자가 다른 출처의 브라우저에서 실행되는 경우, 인그레스 또는 -런타임의 미들웨어를 통해 CORS를 구성하십시오. 와일드카드 출처를 -자격 증명이 포함된 요청과 **결합하지 마십시오**. - -## OpenAPI / 디스커버리 - -이미지에 해당 기능이 포함된 경우, 런타임은 생성된 REST API에 대한 -OpenAPI 문서를 제공할 수 있습니다. 오브젝트 이름과 생성된 라우트는 -배포된 아티팩트를 따르므로, 고객 통합은 URL을 직접 작성하는 대신 -배포별 OpenAPI 문서에서 클라이언트를 생성해야 합니다. diff --git a/content/docs/configure/authentication.de.mdx b/content/docs/configure/authentication.de.mdx deleted file mode 100644 index 21f0eac0..00000000 --- a/content/docs/configure/authentication.de.mdx +++ /dev/null @@ -1,127 +0,0 @@ ---- -title: Authentifizierung -description: Konfigurieren Sie Anmeldung, Sitzungen, OAuth, OIDC/SSO und Device Flow. -translation: - source_sha: 13ce21012c87e2e40f4462cbcb38661242e4b3ddbfd001f52d0128bc64d07da9 - guide_rev: 1 - mode: auto ---- - -ObjectOS verwendet das ObjectStack-Authentifizierungs-Plugin, das auf -Better Auth basiert. Die Authentifizierung ist projektlokal: Jedes Projekt hat -seine eigenen Identitätstabellen und seinen eigenen Sitzungsbereich. - -## Was wird unterstützt - -Abhängig von der paketierten Anwendung und den aktivierten Einstellungen kann -ObjectOS Folgendes unterstützen: - -- Anmeldung per E-Mail/Passwort; -- Sitzungsverwaltung; -- Passwortzurücksetzung und E-Mail-Verifizierung; -- soziale OAuth-Anbieter wie Google, GitHub, Microsoft und Apple; -- Enterprise-OIDC/SSO wie Okta, Entra ID, Keycloak und Ping; -- Zwei-Faktor-Authentifizierung; -- Passkeys/WebAuthn; -- Magic Links; -- CLI-/Browser-Device-Flow. - -## Erforderliches Geheimnis - -Legen Sie fest: - -```bash -OS_AUTH_SECRET=replace-with-a-strong-random-secret -``` - -ObjectOS leitet aus diesem Wert und der Projektumgebungs-ID ein stabiles -projektspezifisches Geheimnis ab. Das bedeutet: - -- Sitzungen überstehen Container-Neustarts; -- Tokens aus einem Projekt können nicht in einem anderen Projekt wiederverwendet werden; -- das Rotieren von `OS_AUTH_SECRET` macht Sitzungen ungültig. - -Siehe [Environment variables](/docs/reference/environment-variables) für die -vollständige Liste der authentifizierungsbezogenen Einstellungen, einschließlich -des veralteten `AUTH_SECRET`-Alias. - -## Sitzungsisolierung - -In Bereitstellungen mit mehreren Projekten sind Cookies auf den Projekt-Hostnamen -beschränkt. ObjectOS vermeidet bewusst weitreichende Root-Domain-Cookies für -Projektsitzungen. Dadurch wird verhindert, dass eine Sitzung über Kundenprojekte -hinweg durchsickert. - -## Soziale Anmeldung - -Konfigurieren Sie die Anbieter-Anmeldedaten über Umgebungsvariablen oder -Systemeinstellungen, je nachdem, wie das Anwendungspaket die -Authentifizierungskonfiguration bereitstellt. - -Die Callback-URLs der Anbieter hängen vom Anbietertyp ab. ObjectStack stellt -zwei unterschiedliche Callback-Pfade bereit, die **nicht** austauschbar sind: - -| Anbietertyp | Callback-Pfad | -|---|---| -| Integrierte soziale Anbieter (Google, GitHub, Microsoft, Apple, …) | `/api/v1/auth/callback/` | -| Generisches OIDC / OAuth2 (Okta, Entra ID, Keycloak, Ping, …) | `/api/v1/auth/oauth2/callback/` | - -Beispiele: - -```text -https://crm.example.com/api/v1/auth/callback/google -https://crm.example.com/api/v1/auth/callback/microsoft -https://crm.example.com/api/v1/auth/oauth2/callback/okta -https://crm.example.com/api/v1/auth/oauth2/callback/entra -``` - -Konfigurieren Sie die passende Redirect-URI in der Anwendungsregistrierung des -Identitätsanbieters, bevor Sie den Anbieter in ObjectOS aktivieren. - -## Enterprise-OIDC/SSO - -OIDC-Anbieter werden als generische OAuth2-Anbieter registriert und verwenden den -Pfad `/api/v1/auth/oauth2/callback/`. Eine typische Konfiguration -erfordert: - -| Feld | Beschreibung | -|---|---| -| Provider id | Stabile ID wie `okta` oder `entra` (in der Callback-URL verwendet) | -| Display name | Schaltflächenbeschriftung, die Benutzern angezeigt wird | -| Discovery URL | `.well-known/openid-configuration`-Endpunkt | -| Client id | Anwendungs-Client-ID vom Identitätsanbieter | -| Client secret | Geheimnis, das in Umgebung oder verschlüsselten Einstellungen gespeichert ist | -| Scopes | Üblicherweise `openid email profile` | - -Bevorzugen Sie für Kundenbereitstellungen OIDC-Discovery-URLs gegenüber manuell -konfigurierten Authorization-/Token-/Userinfo-Endpunkten. - -## Plattform-SSO - -In cloud-verbundenen Bereitstellungen kann ObjectOS die Control-Plane-Anmeldung -als Plattform-SSO-Anbieter verwenden. Ein Builder, der bereits an der -Control Plane angemeldet ist, kann in eine Projektlaufzeit bereitgestellt werden, -ohne ein separates projektlokales Konto zu erstellen. - -Dies erfordert, dass die Control Plane und ObjectOS dasselbe -`OS_AUTH_SECRET`-Basisgeheimnis teilen. Deaktivieren Sie Plattform-SSO nur, wenn -der Kunde möchte, dass jedes Projekt eine vollständig separate Anmeldegrenze -besitzt. - -## Betriebsprüfungen - -Vor der Produktion: - -- bestätigen Sie, dass abgelaufene Tokens `401` zurückgeben; -- bestätigen Sie, dass die Abmeldung die aktive Sitzung widerruft; -- bestätigen Sie, dass die Passwortzurücksetzung andere Sitzungen widerruft, falls die Richtlinie dies erfordert; -- bestätigen Sie, dass die Callback-URLs mit der öffentlichen Projektdomäne übereinstimmen; -- bestätigen Sie, dass vertrauenswürdige Ursprünge nur genehmigte Domänen enthalten; -- bestätigen Sie, dass `OS_AUTH_SECRET` in einem Secret Manager gespeichert ist und nicht im Quellcode. - -## Nächste Schritte - -Die Authentifizierung legt fest, *wer* ein Benutzer ist. Um zu steuern, *worauf* -ein Benutzer nach der Anmeldung zugreifen kann, siehe -[Permissions](/docs/configure/permissions). Für Nicht-Browser-Clients und -Machine-to-Machine-Zugriff siehe [API access](/docs/configure/api-access). diff --git a/content/docs/configure/authentication.es.mdx b/content/docs/configure/authentication.es.mdx deleted file mode 100644 index 0b76ba4a..00000000 --- a/content/docs/configure/authentication.es.mdx +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: Autenticación -description: Configura el inicio de sesión, las sesiones, OAuth, OIDC/SSO y el flujo de dispositivos. -translation: - source_sha: 13ce21012c87e2e40f4462cbcb38661242e4b3ddbfd001f52d0128bc64d07da9 - guide_rev: 1 - mode: auto ---- - -ObjectOS utiliza el complemento de autenticación de ObjectStack, basado en -Better Auth. La autenticación es local al proyecto: cada proyecto tiene sus propias -tablas de identidad y su propio alcance de sesión. - -## Qué se admite - -Según la aplicación empaquetada y los ajustes habilitados, ObjectOS puede -admitir: - -- inicio de sesión con correo electrónico y contraseña; -- gestión de sesiones; -- restablecimiento de contraseña y verificación de correo electrónico; -- proveedores de OAuth social como Google, GitHub, Microsoft y Apple; -- OIDC/SSO empresarial como Okta, Entra ID, Keycloak y Ping; -- autenticación de dos factores; -- passkeys/WebAuthn; -- enlaces mágicos; -- flujo de dispositivos CLI/navegador. - -## Secreto requerido - -Configura: - -```bash -OS_AUTH_SECRET=replace-with-a-strong-random-secret -``` - -ObjectOS deriva un secreto estable por proyecto a partir de este valor y del -id del entorno del proyecto. Esto significa que: - -- las sesiones sobreviven a los reinicios de contenedores; -- los tokens de un proyecto no se pueden reutilizar en otro proyecto; -- rotar `OS_AUTH_SECRET` invalida las sesiones. - -Consulta [Environment variables](/docs/reference/environment-variables) para ver la -lista completa de ajustes relacionados con la autenticación, incluido el alias heredado `AUTH_SECRET`. - -## Aislamiento de sesiones - -En despliegues con varios proyectos, las cookies tienen su alcance limitado al nombre de host del proyecto. -ObjectOS evita intencionadamente las cookies amplias de dominio raíz para las sesiones -de proyecto. Esto impide que una sesión se filtre entre proyectos de distintos clientes. - -## Inicio de sesión social - -Configura las credenciales del proveedor mediante variables de entorno o ajustes -del sistema, según cómo el paquete de la aplicación exponga la configuración -de autenticación. - -Las URL de devolución de llamada del proveedor dependen del tipo de proveedor. ObjectStack expone -dos rutas de devolución de llamada distintas y **no** son intercambiables: - -| Tipo de proveedor | Ruta de devolución de llamada | -|---|---| -| Social integrado (Google, GitHub, Microsoft, Apple, …) | `/api/v1/auth/callback/` | -| OIDC / OAuth2 genérico (Okta, Entra ID, Keycloak, Ping, …) | `/api/v1/auth/oauth2/callback/` | - -Ejemplos: - -```text -https://crm.example.com/api/v1/auth/callback/google -https://crm.example.com/api/v1/auth/callback/microsoft -https://crm.example.com/api/v1/auth/oauth2/callback/okta -https://crm.example.com/api/v1/auth/oauth2/callback/entra -``` - -Configura la URI de redirección correspondiente en el registro de aplicación del -proveedor de identidad antes de habilitar el proveedor en ObjectOS. - -## OIDC/SSO empresarial - -Los proveedores OIDC se registran como proveedores OAuth2 genéricos y usan la -ruta `/api/v1/auth/oauth2/callback/`. Una configuración típica -requiere: - -| Campo | Descripción | -|---|---| -| Provider id | Id estable como `okta` o `entra` (usado en la URL de devolución de llamada) | -| Display name | Etiqueta del botón que se muestra a los usuarios | -| Discovery URL | Endpoint `.well-known/openid-configuration` | -| Client id | Id de cliente de la aplicación del proveedor de identidad | -| Client secret | Secreto almacenado en el entorno o en ajustes cifrados | -| Scopes | Normalmente `openid email profile` | - -Para los despliegues de clientes, prefiere las URL de descubrimiento OIDC en lugar de -endpoints de autorización/token/userinfo configurados manualmente. - -## SSO de plataforma - -En despliegues conectados a la nube, ObjectOS puede usar el inicio de sesión del plano -de control como proveedor de SSO de plataforma. Un creador que ya haya iniciado sesión en el -plano de control puede aprovisionarse en el entorno de ejecución de un proyecto sin crear -una cuenta local del proyecto independiente. - -Esto requiere que el plano de control y ObjectOS compartan el mismo secreto base -`OS_AUTH_SECRET`. Deshabilita el SSO de plataforma solo cuando el cliente -quiera que cada proyecto tenga un límite de inicio de sesión completamente independiente. - -## Comprobaciones operativas - -Antes de producción: - -- confirma que los tokens caducados devuelven `401`; -- confirma que el cierre de sesión revoca la sesión activa; -- confirma que el restablecimiento de contraseña revoca otras sesiones si la política lo requiere; -- confirma que las URL de devolución de llamada coinciden con el dominio público del proyecto; -- confirma que los orígenes de confianza incluyen solo dominios aprobados; -- confirma que `OS_AUTH_SECRET` se almacena en un gestor de secretos, no en el código fuente. - -## Próximos pasos - -La autenticación establece *quién* es un usuario. Para controlar *a qué* puede -acceder una vez que ha iniciado sesión, consulta [Permissions](/docs/configure/permissions). Para -clientes que no son navegadores y para el acceso de máquina a máquina, consulta -[API access](/docs/configure/api-access). diff --git a/content/docs/configure/authentication.fr.mdx b/content/docs/configure/authentication.fr.mdx deleted file mode 100644 index a19c20c4..00000000 --- a/content/docs/configure/authentication.fr.mdx +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: Authentification -description: Configurez la connexion, les sessions, OAuth, OIDC/SSO et le flux d'appareil. -translation: - source_sha: 13ce21012c87e2e40f4462cbcb38661242e4b3ddbfd001f52d0128bc64d07da9 - guide_rev: 1 - mode: auto ---- - -ObjectOS utilise le plugin d'authentification ObjectStack, propulsé par -Better Auth. L'authentification est locale au projet : chaque projet possède ses propres -tables d'identité et sa propre portée de session. - -## Ce qui est pris en charge - -Selon l'application packagée et les paramètres activés, ObjectOS peut -prendre en charge : - -- la connexion par e-mail/mot de passe ; -- la gestion des sessions ; -- la réinitialisation du mot de passe et la vérification de l'e-mail ; -- les fournisseurs OAuth sociaux tels que Google, GitHub, Microsoft et Apple ; -- l'OIDC/SSO d'entreprise tel qu'Okta, Entra ID, Keycloak et Ping ; -- l'authentification à deux facteurs ; -- les passkeys/WebAuthn ; -- les liens magiques ; -- le flux d'appareil CLI/navigateur. - -## Secret requis - -Définissez : - -```bash -OS_AUTH_SECRET=replace-with-a-strong-random-secret -``` - -ObjectOS dérive un secret stable propre au projet à partir de cette valeur et de -l'identifiant d'environnement du projet. Cela signifie que : - -- les sessions survivent aux redémarrages de conteneurs ; -- les jetons d'un projet ne peuvent pas être réutilisés sur un autre projet ; -- la rotation de `OS_AUTH_SECRET` invalide les sessions. - -Consultez [Environment variables](/docs/reference/environment-variables) pour la -liste complète des paramètres liés à l'authentification, y compris l'alias hérité `AUTH_SECRET`. - -## Isolation des sessions - -Dans les déploiements multi-projets, les cookies sont limités au nom d'hôte du projet. -ObjectOS évite intentionnellement les cookies de domaine racine larges pour les sessions -de projet. Cela empêche une session de fuiter d'un projet client à l'autre. - -## Connexion sociale - -Configurez les identifiants des fournisseurs via des variables d'environnement ou des -paramètres système, selon la manière dont le package applicatif expose la -configuration de l'authentification. - -Les URL de rappel des fournisseurs dépendent du type de fournisseur. ObjectStack expose -deux chemins de rappel distincts et ils ne sont **pas** interchangeables : - -| Type de fournisseur | Chemin de rappel | -|---|---| -| Social intégré (Google, GitHub, Microsoft, Apple, …) | `/api/v1/auth/callback/` | -| OIDC / OAuth2 générique (Okta, Entra ID, Keycloak, Ping, …) | `/api/v1/auth/oauth2/callback/` | - -Exemples : - -```text -https://crm.example.com/api/v1/auth/callback/google -https://crm.example.com/api/v1/auth/callback/microsoft -https://crm.example.com/api/v1/auth/oauth2/callback/okta -https://crm.example.com/api/v1/auth/oauth2/callback/entra -``` - -Configurez l'URI de redirection correspondante dans l'enregistrement de l'application -du fournisseur d'identité avant d'activer le fournisseur dans ObjectOS. - -## OIDC/SSO d'entreprise - -Les fournisseurs OIDC sont enregistrés comme des fournisseurs OAuth2 génériques et utilisent le -chemin `/api/v1/auth/oauth2/callback/`. Une configuration typique -requiert : - -| Champ | Description | -|---|---| -| Provider id | Identifiant stable tel que `okta` ou `entra` (utilisé dans l'URL de rappel) | -| Display name | Libellé du bouton affiché aux utilisateurs | -| Discovery URL | Point de terminaison `.well-known/openid-configuration` | -| Client id | Identifiant client de l'application provenant du fournisseur d'identité | -| Client secret | Secret stocké dans l'environnement ou dans des paramètres chiffrés | -| Scopes | Généralement `openid email profile` | - -Pour les déploiements clients, préférez les URL de découverte OIDC aux points de -terminaison authorization/token/userinfo configurés manuellement. - -## SSO de plateforme - -Dans les déploiements connectés au cloud, ObjectOS peut utiliser la connexion du -plan de contrôle comme fournisseur SSO de plateforme. Un constructeur déjà connecté au -plan de contrôle peut être provisionné dans le runtime d'un projet sans créer -un compte distinct local au projet. - -Cela nécessite que le plan de contrôle et ObjectOS partagent le même -secret de base `OS_AUTH_SECRET`. Désactivez le SSO de plateforme uniquement lorsque le client -souhaite que chaque projet possède une frontière de connexion complètement distincte. - -## Vérifications opérationnelles - -Avant la mise en production : - -- confirmez que les jetons expirés renvoient `401` ; -- confirmez que la déconnexion révoque la session active ; -- confirmez que la réinitialisation du mot de passe révoque les autres sessions si la politique l'exige ; -- confirmez que les URL de rappel correspondent au domaine public du projet ; -- confirmez que les origines de confiance n'incluent que des domaines approuvés ; -- confirmez que `OS_AUTH_SECRET` est stocké dans un gestionnaire de secrets, et non dans le code source. - -## Étapes suivantes - -L'authentification établit *qui* est un utilisateur. Pour contrôler *ce* à quoi il peut -accéder une fois connecté, consultez [Permissions](/docs/configure/permissions). Pour -les clients non navigateur et l'accès de machine à machine, consultez -[API access](/docs/configure/api-access). diff --git a/content/docs/configure/authentication.ja.mdx b/content/docs/configure/authentication.ja.mdx deleted file mode 100644 index 021e3db2..00000000 --- a/content/docs/configure/authentication.ja.mdx +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: 認証 -description: サインイン、セッション、OAuth、OIDC/SSO、デバイスフローを設定します。 -translation: - source_sha: 13ce21012c87e2e40f4462cbcb38661242e4b3ddbfd001f52d0128bc64d07da9 - guide_rev: 1 - mode: auto ---- - -ObjectOS は、Better Auth を基盤とする ObjectStack 認証プラグインを使用します。認証はプロジェクトローカルであり、各プロジェクトは独自のアイデンティティテーブルとセッションスコープを持ちます。 - -## サポートされる機能 - -パッケージ化されたアプリケーションと有効化された設定に応じて、ObjectOS は以下をサポートできます。 - -- メール／パスワードによるサインイン -- セッション管理 -- パスワードリセットとメール検証 -- Google、GitHub、Microsoft、Apple などのソーシャル OAuth プロバイダー -- Okta、Entra ID、Keycloak、Ping などのエンタープライズ OIDC/SSO -- 二要素認証 -- パスキー／WebAuthn -- マジックリンク -- CLI／ブラウザのデバイスフロー - -## 必須のシークレット - -次を設定します。 - -```bash -OS_AUTH_SECRET=replace-with-a-strong-random-secret -``` - -ObjectOS は、この値とプロジェクト環境 id から、安定したプロジェクトごとのシークレットを導出します。これにより以下が実現されます。 - -- セッションがコンテナの再起動後も維持される -- あるプロジェクトのトークンを別のプロジェクトで再利用できない -- `OS_AUTH_SECRET` をローテーションするとセッションが無効化される - -レガシーの `AUTH_SECRET` エイリアスを含む、認証関連の設定の完全な一覧については、[Environment variables](/docs/reference/environment-variables) を参照してください。 - -## セッションの分離 - -マルチプロジェクト構成のデプロイでは、Cookie はプロジェクトのホスト名にスコープされます。ObjectOS は、プロジェクトセッションに対して広範なルートドメイン Cookie を意図的に使用しません。これにより、セッションが顧客プロジェクト間で漏えいすることを防ぎます。 - -## ソーシャルログイン - -アプリケーションパッケージが認証設定をどのように公開するかに応じて、プロバイダーの認証情報を環境変数またはシステム設定を通じて設定します。 - -プロバイダーのコールバック URL はプロバイダーの種類によって異なります。ObjectStack は 2 つの異なるコールバックパスを公開しており、これらは互いに**入れ替えできません**。 - -| プロバイダーの種類 | コールバックパス | -|---|---| -| 組み込みソーシャル（Google、GitHub、Microsoft、Apple、…） | `/api/v1/auth/callback/` | -| 汎用 OIDC / OAuth2（Okta、Entra ID、Keycloak、Ping、…） | `/api/v1/auth/oauth2/callback/` | - -例: - -```text -https://crm.example.com/api/v1/auth/callback/google -https://crm.example.com/api/v1/auth/callback/microsoft -https://crm.example.com/api/v1/auth/oauth2/callback/okta -https://crm.example.com/api/v1/auth/oauth2/callback/entra -``` - -ObjectOS でプロバイダーを有効化する前に、アイデンティティプロバイダーのアプリケーション登録で、対応するリダイレクト URI を設定してください。 - -## エンタープライズ OIDC/SSO - -OIDC プロバイダーは汎用 OAuth2 プロバイダーとして登録され、`/api/v1/auth/oauth2/callback/` パスを使用します。一般的な設定には次が必要です。 - -| フィールド | 説明 | -|---|---| -| Provider id | `okta` や `entra` などの安定した id（コールバック URL で使用） | -| Display name | ユーザーに表示されるボタンのラベル | -| Discovery URL | `.well-known/openid-configuration` エンドポイント | -| Client id | アイデンティティプロバイダーのアプリケーション client id | -| Client secret | 環境変数または暗号化された設定に保存されるシークレット | -| Scopes | 通常は `openid email profile` | - -顧客向けのデプロイでは、手動で設定する authorization/token/userinfo エンドポイントよりも、OIDC ディスカバリ URL を優先してください。 - -## プラットフォーム SSO - -クラウド接続されたデプロイでは、ObjectOS はコントロールプレーンのログインをプラットフォーム SSO プロバイダーとして使用できます。すでにコントロールプレーンにサインインしているビルダーは、別のプロジェクトローカルアカウントを作成することなく、プロジェクトランタイムにプロビジョニングできます。 - -これには、コントロールプレーンと ObjectOS が同じ `OS_AUTH_SECRET` のベースシークレットを共有している必要があります。すべてのプロジェクトが完全に独立したログイン境界を持つことを顧客が望む場合にのみ、プラットフォーム SSO を無効化してください。 - -## 運用上のチェック - -本番環境に移行する前に、以下を確認します。 - -- 期限切れトークンが `401` を返すことを確認する -- ログアウトでアクティブなセッションが取り消されることを確認する -- ポリシーで必要とされる場合、パスワードリセットが他のセッションを取り消すことを確認する -- コールバック URL が公開プロジェクトドメインと一致することを確認する -- 信頼されたオリジンに承認済みのドメインのみが含まれることを確認する -- `OS_AUTH_SECRET` がソースコードではなくシークレットマネージャーに保存されていることを確認する - -## 次のステップ - -認証は、ユーザーが*誰*であるかを確立します。サインイン後に*何*にアクセスできるかを制御するには、[Permissions](/docs/configure/permissions) を参照してください。ブラウザ以外のクライアントやマシン間アクセスについては、[API access](/docs/configure/api-access) を参照してください。 diff --git a/content/docs/configure/authentication.ko.mdx b/content/docs/configure/authentication.ko.mdx deleted file mode 100644 index d77ef244..00000000 --- a/content/docs/configure/authentication.ko.mdx +++ /dev/null @@ -1,126 +0,0 @@ ---- -title: 인증 -description: 로그인, 세션, OAuth, OIDC/SSO 및 디바이스 플로우를 구성합니다. -translation: - source_sha: 13ce21012c87e2e40f4462cbcb38661242e4b3ddbfd001f52d0128bc64d07da9 - guide_rev: 1 - mode: auto ---- - -ObjectOS는 Better Auth로 구동되는 ObjectStack 인증 플러그인을 사용합니다. -인증은 프로젝트 로컬 방식입니다. 각 프로젝트는 자체 ID 테이블과 -세션 범위를 가집니다. - -## 지원 기능 - -패키징된 애플리케이션과 활성화된 설정에 따라 ObjectOS는 다음을 -지원할 수 있습니다. - -- 이메일/비밀번호 로그인; -- 세션 관리; -- 비밀번호 재설정 및 이메일 인증; -- Google, GitHub, Microsoft, Apple과 같은 소셜 OAuth 제공자; -- Okta, Entra ID, Keycloak, Ping과 같은 엔터프라이즈 OIDC/SSO; -- 2단계 인증; -- 패스키/WebAuthn; -- 매직 링크; -- CLI/브라우저 디바이스 플로우. - -## 필수 시크릿 - -다음을 설정하세요. - -```bash -OS_AUTH_SECRET=replace-with-a-strong-random-secret -``` - -ObjectOS는 이 값과 프로젝트 환경 id로부터 안정적인 프로젝트별 시크릿을 -파생합니다. 이는 다음을 의미합니다. - -- 세션이 컨테이너 재시작 후에도 유지됩니다; -- 한 프로젝트의 토큰을 다른 프로젝트에서 재사용할 수 없습니다; -- `OS_AUTH_SECRET`을 교체하면 세션이 무효화됩니다. - -레거시 `AUTH_SECRET` 별칭을 포함한 인증 관련 설정의 전체 목록은 -[Environment variables](/docs/reference/environment-variables)를 -참조하세요. - -## 세션 격리 - -다중 프로젝트 배포에서 쿠키는 프로젝트 호스트명으로 범위가 지정됩니다. -ObjectOS는 프로젝트 세션에 대해 광범위한 루트 도메인 쿠키를 의도적으로 -피합니다. 이는 세션이 고객 프로젝트 간에 유출되는 것을 방지합니다. - -## 소셜 로그인 - -애플리케이션 패키지가 인증 구성을 노출하는 방식에 따라 환경 변수 또는 -시스템 설정을 통해 제공자 자격 증명을 구성하세요. - -제공자 콜백 URL은 제공자 유형에 따라 다릅니다. ObjectStack은 두 가지 -서로 다른 콜백 경로를 노출하며 이들은 서로 **호환되지 않습니다**. - -| 제공자 유형 | 콜백 경로 | -|---|---| -| 내장 소셜 (Google, GitHub, Microsoft, Apple, …) | `/api/v1/auth/callback/` | -| 일반 OIDC / OAuth2 (Okta, Entra ID, Keycloak, Ping, …) | `/api/v1/auth/oauth2/callback/` | - -예시: - -```text -https://crm.example.com/api/v1/auth/callback/google -https://crm.example.com/api/v1/auth/callback/microsoft -https://crm.example.com/api/v1/auth/oauth2/callback/okta -https://crm.example.com/api/v1/auth/oauth2/callback/entra -``` - -ObjectOS에서 제공자를 활성화하기 전에 ID 제공자의 애플리케이션 -등록에서 일치하는 리디렉션 URI를 구성하세요. - -## 엔터프라이즈 OIDC/SSO - -OIDC 제공자는 일반 OAuth2 제공자로 등록되며 -`/api/v1/auth/oauth2/callback/` 경로를 사용합니다. 일반적인 -구성에는 다음이 필요합니다. - -| 필드 | 설명 | -|---|---| -| Provider id | `okta` 또는 `entra`와 같은 안정적인 id (콜백 URL에 사용됨) | -| Display name | 사용자에게 표시되는 버튼 레이블 | -| Discovery URL | `.well-known/openid-configuration` 엔드포인트 | -| Client id | ID 제공자의 애플리케이션 클라이언트 id | -| Client secret | 환경 또는 암호화된 설정에 저장되는 시크릿 | -| Scopes | 일반적으로 `openid email profile` | - -고객 배포의 경우 수동으로 구성된 authorization/token/userinfo -엔드포인트보다 OIDC 디스커버리 URL을 선호하세요. - -## 플랫폼 SSO - -클라우드에 연결된 배포에서 ObjectOS는 컨트롤 플레인 로그인을 플랫폼 -SSO 제공자로 사용할 수 있습니다. 이미 컨트롤 플레인에 로그인한 빌더는 -별도의 프로젝트 로컬 계정을 생성하지 않고도 프로젝트 런타임에 -프로비저닝될 수 있습니다. - -이를 위해서는 컨트롤 플레인과 ObjectOS가 동일한 `OS_AUTH_SECRET` 기본 -시크릿을 공유해야 합니다. 고객이 모든 프로젝트가 완전히 별도의 로그인 -경계를 소유하기를 원하는 경우에만 플랫폼 SSO를 비활성화하세요. - -## 운영 점검 - -프로덕션 전에: - -- 만료된 토큰이 `401`을 반환하는지 확인하세요; -- 로그아웃이 활성 세션을 취소하는지 확인하세요; -- 정책에서 요구하는 경우 비밀번호 재설정이 다른 세션을 취소하는지 - 확인하세요; -- 콜백 URL이 공개 프로젝트 도메인과 일치하는지 확인하세요; -- 신뢰할 수 있는 출처에 승인된 도메인만 포함되는지 확인하세요; -- `OS_AUTH_SECRET`이 소스가 아닌 시크릿 관리자에 저장되는지 - 확인하세요. - -## 다음 단계 - -인증은 사용자가 *누구*인지를 확립합니다. 로그인 후 사용자가 *무엇*에 -액세스할 수 있는지 제어하려면 [Permissions](/docs/configure/permissions)를 -참조하세요. 브라우저가 아닌 클라이언트 및 머신 간 액세스에 대해서는 -[API access](/docs/configure/api-access)를 참조하세요. diff --git a/content/docs/configure/permissions/meta.de.json b/content/docs/configure/permissions/meta.de.json index 75fe5fd0..beccef4f 100644 --- a/content/docs/configure/permissions/meta.de.json +++ b/content/docs/configure/permissions/meta.de.json @@ -1,4 +1,4 @@ { "title": "Berechtigungen", - "pages": ["index", "managing-access", "positions", "permission-sets", "record-access", "field-level-security"] + "pages": ["index", "managing-access", "positions", "permission-sets", "record-access", "hierarchy-visibility", "field-level-security"] } diff --git a/content/docs/configure/permissions/meta.es.json b/content/docs/configure/permissions/meta.es.json index bf5bfb1b..31734934 100644 --- a/content/docs/configure/permissions/meta.es.json +++ b/content/docs/configure/permissions/meta.es.json @@ -1,4 +1,4 @@ { "title": "Permisos", - "pages": ["index", "managing-access", "positions", "permission-sets", "record-access", "field-level-security"] + "pages": ["index", "managing-access", "positions", "permission-sets", "record-access", "hierarchy-visibility", "field-level-security"] } diff --git a/content/docs/configure/permissions/meta.fr.json b/content/docs/configure/permissions/meta.fr.json index aca9a171..0c465a83 100644 --- a/content/docs/configure/permissions/meta.fr.json +++ b/content/docs/configure/permissions/meta.fr.json @@ -1,4 +1,4 @@ { "title": "Permissions", - "pages": ["index", "managing-access", "positions", "permission-sets", "record-access", "field-level-security"] + "pages": ["index", "managing-access", "positions", "permission-sets", "record-access", "hierarchy-visibility", "field-level-security"] } diff --git a/content/docs/configure/permissions/meta.ja.json b/content/docs/configure/permissions/meta.ja.json index 6dae3abe..b6e43a63 100644 --- a/content/docs/configure/permissions/meta.ja.json +++ b/content/docs/configure/permissions/meta.ja.json @@ -1,4 +1,4 @@ { "title": "権限", - "pages": ["index", "managing-access", "positions", "permission-sets", "record-access", "field-level-security"] + "pages": ["index", "managing-access", "positions", "permission-sets", "record-access", "hierarchy-visibility", "field-level-security"] } diff --git a/content/docs/configure/permissions/meta.ko.json b/content/docs/configure/permissions/meta.ko.json index 099632bc..bb18da04 100644 --- a/content/docs/configure/permissions/meta.ko.json +++ b/content/docs/configure/permissions/meta.ko.json @@ -1,4 +1,4 @@ { "title": "권한", - "pages": ["index", "managing-access", "positions", "permission-sets", "record-access", "field-level-security"] + "pages": ["index", "managing-access", "positions", "permission-sets", "record-access", "hierarchy-visibility", "field-level-security"] } diff --git a/content/docs/configure/permissions/permission-sets.de.mdx b/content/docs/configure/permissions/permission-sets.de.mdx deleted file mode 100644 index 2609c5a4..00000000 --- a/content/docs/configure/permissions/permission-sets.de.mdx +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: Berechtigungssätze -description: Anwendungs-, Objekt-, Feld- und Systemberechtigungen erteilen. -translation: - source_sha: 3a15cf4a4b1be9a3e606541bf85e92e80b2588e92e8c100bfa318aa21ee31384 - guide_rev: 1 - mode: auto ---- - -Berechtigungssätze sind die wichtigste Möglichkeit, um Funktionen zu erteilen. Sie können -Benutzern direkt oder indirekt über [Rollen](/docs/configure/permissions/positions) zugewiesen werden. - -## Was Berechtigungssätze steuern - -| Berechtigungstyp | Beispiele | -|---|---| -| Anwendungszugriff | Benutzer kann CRM oder Console öffnen | -| Objektberechtigungen | Datensätze erstellen, lesen, aktualisieren, löschen | -| Feldberechtigungen | Ausgewählte Felder lesen oder aktualisieren | -| Systemberechtigungen | Auf Console zugreifen, Berichte ausführen, Daten exportieren | -| Integrationsberechtigungen | API-Schlüssel, Webhooks oder Admin-Aktionen verwenden | - -## Objektberechtigungen - -Objektberechtigungen beantworten: - -```text -Can this user perform this operation on this object at all? -``` - -Berechtigungssatz-Grants verwenden diese Flag-Namen (so wie sie vom -Berechtigungs-Evaluator des Security-Plugins durchgesetzt werden): - -| Flag | Bedeutung | -|---|---| -| `allowRead` | Lesen von Datensätzen, die durch Datensatzzugriffsregeln erlaubt sind | -| `allowCreate` | Datensätze erstellen | -| `allowEdit` | Aktualisieren von Datensätzen, die durch Datensatzzugriffsregeln erlaubt sind | -| `allowDelete` | Löschen von Datensätzen, die durch Datensatzzugriffsregeln erlaubt sind | -| `viewAllRecords` | Jeden Datensatz des Objekts lesen, unter Umgehung des Datensatzzugriffs | -| `modifyAllRecords` | Jeden Datensatz des Objekts aktualisieren oder löschen, unter Umgehung des Datensatzzugriffs; impliziert `viewAllRecords` für Lesevorgänge | - -[Datensatzzugriff](/docs/configure/permissions/record-access) ist weiterhin relevant, -sofern nicht `viewAllRecords` oder `modifyAllRecords` die normale -zeilenbasierte Grenze umgeht. Reservieren Sie diese Flags für -administrative Berechtigungssätze – sie stellen praktisch einen -mandantenweiten Superuser-Grant für dieses Objekt dar. - -## Systemberechtigungen - -Systemberechtigungen sind für Plattformaktionen wie: - -- Console-Zugriff; -- Benutzer verwalten; -- Rollen und Berechtigungssätze verwalten; -- Berichte ausführen; -- Berichte exportieren; -- Integrationen verwalten; -- Audit-Protokolle anzeigen. - -Halten Sie Systemberechtigungen von Berechtigungen für Geschäftsobjekte getrennt, damit -Administratoren sie einfach prüfen können. - -## Empfohlene Sätze - -Beginnen Sie mit einigen benannten Berechtigungssätzen: - -| Berechtigungssatz | Zweck | -|---|---| -| Basic User | Anmelden und auf die Hauptanwendung zugreifen | -| Setup Administrator | Benutzer, Rollen, Einstellungen und Diagnose verwalten | -| Report Viewer | Berichte und Dashboards anzeigen | -| Integration Operator | Webhooks/API-Schlüssel verwalten | -| Support User | Support-Objekte lesen/aktualisieren | - -Fügen Sie dann domänenspezifische Sätze für die Anwendung des Kunden hinzu. - -## Feldsicherheit (Anhang) - -Berechtigungssätze enthalten auch Grants auf Feldebene. Selbst wenn ein Benutzer -einen Datensatz lesen kann, können einzelne Felder ausgeblendet oder schreibgeschützt werden. - -### Zwei Modi - -| Modus | Wirkung | -|---|---| -| **Ausgeblendet** | Feld wird vollständig aus API-Antworten und Console-Ansichten entfernt | -| **Schreibgeschützt** | Feld wird zurückgegeben, aber Schreibvorgänge werden abgelehnt | - -### Wo es durchgesetzt wird - -Derselbe Evaluator, der Objektberechtigungen prüft, wendet Feldregeln -auf jedem Pfad an – REST, ObjectQL, generierte Console-Formulare, Exporte. Es -gibt keine „Hintertür“ über eine API auf niedrigerer Ebene. - -### Typische Muster - -| Anwendungsfall | Empfehlung | -|---|---| -| HR-Daten in `sys_user` (Gehalt, SSN) | Für alle ausblenden, außer für einen `HR`-Berechtigungssatz | -| Kennungen externer Systeme | Schreibgeschützt für Support, beschreibbar für Integrationsoperatoren | -| Interne Kosten vs. Kundenpreis in `product` | `cost` für den Vertrieb ausblenden, für die Finanzabteilung sichtbar machen | -| Notizfeld mit PHI | Ausblenden, sofern der Berechtigungssatz nicht die entsprechende klinische Rolle umfasst | - -### Hinweise zur Erstellung - -- Wählen Sie standardmäßig **Ausblenden** statt Schreibgeschützt, wenn das Feld - sensible Daten enthält – Schreibgeschützt gibt den Wert weiterhin in - Antworten und Protokollen preis. -- Bündeln Sie Feldregeln in Berechtigungssätzen, die einer realen Rolle entsprechen - (`HR Manager`, `Finance Read-only`), anstatt einen Satz pro - Feld zu erfinden – das erleichtert die Prüfung. -- Kombinieren Sie für Compliance-Anwendungsfälle Feldsicherheit mit der Aufbewahrung - von Audit-Protokollen, damit Sie im Nachhinein die Frage „Wer hat diese Zeile gesehen?“ beantworten können. diff --git a/content/docs/configure/permissions/permission-sets.es.mdx b/content/docs/configure/permissions/permission-sets.es.mdx deleted file mode 100644 index d7ef70d8..00000000 --- a/content/docs/configure/permissions/permission-sets.es.mdx +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: Conjuntos de permisos -description: Otorga permisos de aplicación, objeto, campo y sistema. -translation: - source_sha: 3a15cf4a4b1be9a3e606541bf85e92e80b2588e92e8c100bfa318aa21ee31384 - guide_rev: 1 - mode: auto ---- - -Los conjuntos de permisos son la forma principal de otorgar capacidades. Pueden -asignarse directamente a los usuarios o indirectamente a través de [roles](/docs/configure/permissions/positions). - -## Qué controlan los conjuntos de permisos - -| Tipo de permiso | Ejemplos | -|---|---| -| Acceso a la aplicación | El usuario puede abrir CRM o Console | -| Permisos de objeto | Crear, leer, actualizar, eliminar registros | -| Permisos de campo | Leer o actualizar campos seleccionados | -| Permisos de sistema | Acceder a Console, ejecutar informes, exportar datos | -| Permisos de integración | Usar claves de API, webhooks o acciones de administrador | - -## Permisos de objeto - -Los permisos de objeto responden: - -```text -Can this user perform this operation on this object at all? -``` - -Las concesiones de los conjuntos de permisos usan estos nombres de marca (tal como los aplica -el evaluador de permisos del plugin de seguridad): - -| Marca | Significado | -|---|---| -| `allowRead` | Leer los registros permitidos por las reglas de acceso a registros | -| `allowCreate` | Crear registros | -| `allowEdit` | Actualizar los registros permitidos por las reglas de acceso a registros | -| `allowDelete` | Eliminar los registros permitidos por las reglas de acceso a registros | -| `viewAllRecords` | Leer todos los registros del objeto, omitiendo el acceso a registros | -| `modifyAllRecords` | Actualizar o eliminar todos los registros del objeto, omitiendo el acceso a registros; implica `viewAllRecords` para las lecturas | - -El [acceso a registros](/docs/configure/permissions/record-access) sigue siendo relevante -a menos que `viewAllRecords` o `modifyAllRecords` omitan el límite normal -a nivel de fila. Reserva esas marcas para -conjuntos de permisos administrativos: son efectivamente una concesión de superusuario -para todo el tenant sobre ese objeto. - -## Permisos de sistema - -Los permisos de sistema son para acciones de la plataforma como: - -- acceso a Console; -- gestionar usuarios; -- gestionar roles y conjuntos de permisos; -- ejecutar informes; -- exportar informes; -- gestionar integraciones; -- ver registros de auditoría. - -Mantén los permisos de sistema separados de los permisos de objetos de negocio para que -los administradores puedan auditarlos fácilmente. - -## Conjuntos recomendados - -Comienza con algunos conjuntos de permisos con nombre: - -| Conjunto de permisos | Propósito | -|---|---| -| Basic User | Iniciar sesión y acceder a la aplicación principal | -| Setup Administrator | Gestionar usuarios, roles, configuraciones y diagnósticos | -| Report Viewer | Ver informes y paneles | -| Integration Operator | Gestionar webhooks/claves de API | -| Support User | Leer/actualizar objetos de soporte | - -Luego agrega conjuntos específicos del dominio para la aplicación del cliente. - -## Seguridad de campos (apéndice) - -Los conjuntos de permisos también incluyen concesiones a nivel de campo. Incluso cuando un usuario puede -leer un registro, ciertos campos pueden ocultarse o hacerse de solo lectura. - -### Dos modos - -| Modo | Efecto | -|---|---| -| **Oculto** | El campo se elimina por completo de las respuestas de la API y de las vistas de Console | -| **Solo lectura** | El campo se devuelve, pero se rechazan las escrituras | - -### Dónde se aplica - -El mismo evaluador que verifica los permisos de objeto aplica las reglas de campo -en cada ruta: REST, ObjectQL, formularios de Console generados, exportaciones. No -existe ninguna "puerta trasera" a través de una API de nivel inferior. - -### Patrones típicos - -| Caso de uso | Recomendación | -|---|---| -| Datos de RR. HH. en `sys_user` (salario, SSN) | Ocultar para todos excepto para un conjunto de permisos `HR` | -| Identificadores de sistemas externos | Solo lectura para soporte, modificables para operadores de integración | -| Costo interno frente a precio para el cliente en `product` | Ocultar `cost` a ventas, mostrarlo a finanzas | -| Campo de notas con PHI | Ocultar a menos que el conjunto de permisos incluya el rol clínico correspondiente | - -### Guía de autoría - -- Prefiere **ocultar** en lugar de solo lectura cuando el campo contenga - datos sensibles: el modo solo lectura aún filtra el valor en las respuestas y - los registros. -- Agrupa las reglas de campo en conjuntos de permisos que correspondan a un rol real - (`HR Manager`, `Finance Read-only`) en lugar de inventar un conjunto por - campo: es más fácil de auditar. -- Para casos de uso de cumplimiento, combina la seguridad de campos con la retención - de registros de auditoría para poder responder "¿quién vio esta fila?" después del hecho. diff --git a/content/docs/configure/permissions/permission-sets.fr.mdx b/content/docs/configure/permissions/permission-sets.fr.mdx deleted file mode 100644 index 08c9a82c..00000000 --- a/content/docs/configure/permissions/permission-sets.fr.mdx +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: Ensembles d'autorisations -description: Accorder des autorisations d'application, d'objet, de champ et système. -translation: - source_sha: 3a15cf4a4b1be9a3e606541bf85e92e80b2588e92e8c100bfa318aa21ee31384 - guide_rev: 1 - mode: auto ---- - -Les ensembles d'autorisations constituent le principal moyen d'accorder des capacités. Ils peuvent être -attribués directement aux utilisateurs ou indirectement via des [rôles](/docs/configure/permissions/positions). - -## Ce que contrôlent les ensembles d'autorisations - -| Type d'autorisation | Exemples | -|---|---| -| Accès aux applications | L'utilisateur peut ouvrir le CRM ou Console | -| Autorisations d'objet | Créer, lire, mettre à jour, supprimer des enregistrements | -| Autorisations de champ | Lire ou mettre à jour des champs sélectionnés | -| Autorisations système | Accéder à Console, exécuter des rapports, exporter des données | -| Autorisations d'intégration | Utiliser des clés API, des webhooks ou des actions d'administration | - -## Autorisations d'objet - -Les autorisations d'objet répondent à la question : - -```text -Can this user perform this operation on this object at all? -``` - -Les attributions d'ensembles d'autorisations utilisent ces noms d'indicateurs (tels qu'appliqués par -l'évaluateur d'autorisations du plugin de sécurité) : - -| Indicateur | Signification | -|---|---| -| `allowRead` | Lire les enregistrements autorisés par les règles d'accès aux enregistrements | -| `allowCreate` | Créer des enregistrements | -| `allowEdit` | Mettre à jour les enregistrements autorisés par les règles d'accès aux enregistrements | -| `allowDelete` | Supprimer les enregistrements autorisés par les règles d'accès aux enregistrements | -| `viewAllRecords` | Lire tous les enregistrements de l'objet, en contournant l'accès aux enregistrements | -| `modifyAllRecords` | Mettre à jour ou supprimer tous les enregistrements de l'objet, en contournant l'accès aux enregistrements ; implique `viewAllRecords` pour les lectures | - -L'[accès aux enregistrements](/docs/configure/permissions/record-access) reste pertinent -sauf si `viewAllRecords` ou `modifyAllRecords` contourne la -limite normale au niveau des lignes. Réservez ces indicateurs aux -ensembles d'autorisations administratifs — ils constituent en pratique une attribution de super-utilisateur -à l'échelle du locataire pour cet objet. - -## Autorisations système - -Les autorisations système concernent les actions de plateforme telles que : - -- l'accès à Console ; -- la gestion des utilisateurs ; -- la gestion des rôles et des ensembles d'autorisations ; -- l'exécution de rapports ; -- l'exportation de rapports ; -- la gestion des intégrations ; -- la consultation des journaux d'audit. - -Séparez les autorisations système des autorisations d'objet métier afin que -les administrateurs puissent les auditer facilement. - -## Ensembles recommandés - -Commencez avec quelques ensembles d'autorisations nommés : - -| Ensemble d'autorisations | Objectif | -|---|---| -| Utilisateur de base | Se connecter et accéder à l'application principale | -| Administrateur de configuration | Gérer les utilisateurs, les rôles, les paramètres et les diagnostics | -| Lecteur de rapports | Consulter les rapports et les tableaux de bord | -| Opérateur d'intégration | Gérer les webhooks et les clés API | -| Utilisateur du support | Lire/mettre à jour les objets de support | - -Ajoutez ensuite des ensembles spécifiques au domaine pour l'application du client. - -## Sécurité des champs (annexe) - -Les ensembles d'autorisations portent également des attributions au niveau des champs. Même lorsqu'un utilisateur peut -lire un enregistrement, des champs individuels peuvent être masqués ou rendus en lecture seule. - -### Deux modes - -| Mode | Effet | -|---|---| -| **Masqué** | Le champ est entièrement supprimé des réponses de l'API et des vues de Console | -| **Lecture seule** | Le champ est renvoyé mais les écritures sont rejetées | - -### Où il est appliqué - -Le même évaluateur qui vérifie les autorisations d'objet applique les règles de champ -sur chaque chemin — REST, ObjectQL, formulaires Console générés, exportations. Il -n'existe aucune « porte dérobée » via une API de plus bas niveau. - -### Schémas typiques - -| Cas d'usage | Recommandation | -|---|---| -| Données RH sur `sys_user` (salaire, numéro de sécurité sociale) | Masquer pour tout le monde sauf un ensemble d'autorisations `HR` | -| Identifiants de systèmes externes | Lecture seule pour le support, modifiable pour les opérateurs d'intégration | -| Coût interne vs. prix client sur `product` | Masquer `cost` aux commerciaux, le rendre visible aux équipes financières | -| Champ de notes contenant des RPS | Masquer sauf si l'ensemble d'autorisations inclut le rôle clinique pertinent | - -### Conseils de rédaction - -- Privilégiez par défaut le **masquage** plutôt que la lecture seule lorsque le champ contient - des données sensibles — la lecture seule laisse tout de même fuiter la valeur dans les réponses et - les journaux. -- Regroupez les règles de champ dans des ensembles d'autorisations qui correspondent à un rôle réel - (`HR Manager`, `Finance Read-only`) au lieu d'inventer un ensemble par - champ — c'est plus facile à auditer. -- Pour les cas d'usage de conformité, associez la sécurité des champs à la - rétention des journaux d'audit afin de pouvoir répondre après coup à la question « qui a vu cette ligne ? ». diff --git a/content/docs/configure/permissions/permission-sets.ja.mdx b/content/docs/configure/permissions/permission-sets.ja.mdx deleted file mode 100644 index 985fc50f..00000000 --- a/content/docs/configure/permissions/permission-sets.ja.mdx +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: 権限セット -description: アプリケーション、オブジェクト、フィールド、システムの権限を付与します。 -translation: - source_sha: 3a15cf4a4b1be9a3e606541bf85e92e80b2588e92e8c100bfa318aa21ee31384 - guide_rev: 1 - mode: auto ---- - -権限セットは、機能を付与するための主要な方法です。ユーザーに直接割り当てることも、[ロール](/docs/configure/permissions/positions)を介して間接的に割り当てることもできます。 - -## 権限セットが制御するもの - -| 権限タイプ | 例 | -|---|---| -| アプリケーションアクセス | ユーザーが CRM または Console を開ける | -| オブジェクト権限 | レコードの作成、読み取り、更新、削除 | -| フィールド権限 | 選択したフィールドの読み取りまたは更新 | -| システム権限 | Console へのアクセス、レポートの実行、データのエクスポート | -| 統合権限 | API キー、Webhook、または管理操作の使用 | - -## オブジェクト権限 - -オブジェクト権限は次の問いに答えます。 - -```text -Can this user perform this operation on this object at all? -``` - -権限セットの付与では、次のフラグ名を使用します（セキュリティプラグインの権限評価エンジンによって適用されます）。 - -| フラグ | 意味 | -|---|---| -| `allowRead` | レコードアクセスルールで許可されたレコードを読み取る | -| `allowCreate` | レコードを作成する | -| `allowEdit` | レコードアクセスルールで許可されたレコードを更新する | -| `allowDelete` | レコードアクセスルールで許可されたレコードを削除する | -| `viewAllRecords` | レコードアクセスをバイパスして、オブジェクトのすべてのレコードを読み取る | -| `modifyAllRecords` | レコードアクセスをバイパスして、オブジェクトのすべてのレコードを更新または削除する。読み取りに対しては `viewAllRecords` を含む | - -`viewAllRecords` または `modifyAllRecords` が通常の行レベルの境界をバイパスしない限り、[レコードアクセス](/docs/configure/permissions/record-access)は依然として重要です。これらのフラグは管理用の権限セットに限定してください。これらは、そのオブジェクトに対するテナント全体のスーパーユーザー付与に相当します。 - -## システム権限 - -システム権限は、次のようなプラットフォーム操作のためのものです。 - -- Console アクセス。 -- ユーザーの管理。 -- ロールおよび権限セットの管理。 -- レポートの実行。 -- レポートのエクスポート。 -- 統合の管理。 -- 監査ログの表示。 - -管理者が容易に監査できるよう、システム権限はビジネスオブジェクトの権限とは分けておきましょう。 - -## 推奨セット - -まず、いくつかの名前付き権限セットから始めましょう。 - -| 権限セット | 目的 | -|---|---| -| Basic User | ログインしてメインアプリケーションにアクセスする | -| Setup Administrator | ユーザー、ロール、設定、診断を管理する | -| Report Viewer | レポートとダッシュボードを表示する | -| Integration Operator | Webhook / API キーを管理する | -| Support User | サポートオブジェクトの読み取り/更新 | - -その後、顧客のアプリケーション向けにドメイン固有のセットを追加します。 - -## フィールドセキュリティ（付録） - -権限セットには、フィールドレベルの付与も含まれます。ユーザーがレコードを読み取れる場合でも、個々のフィールドを非表示にしたり読み取り専用にしたりできます。 - -### 2 つのモード - -| モード | 効果 | -|---|---| -| **非表示** | フィールドは API レスポンスや Console ビューから完全に除外される | -| **読み取り専用** | フィールドは返されるが、書き込みは拒否される | - -### 適用される場所 - -オブジェクト権限をチェックするのと同じ評価エンジンが、すべての経路（REST、ObjectQL、生成された Console フォーム、エクスポート）でフィールドルールを適用します。低レベルの API を経由した「裏口」は存在しません。 - -### 一般的なパターン - -| ユースケース | 推奨事項 | -|---|---| -| `sys_user` 上の HR データ（給与、SSN） | `HR` 権限セットを除くすべての人に対して非表示にする | -| 外部システムの識別子 | サポートには読み取り専用、統合オペレーターには書き込み可能にする | -| `product` 上の社内コストと顧客価格 | `cost` を営業には非表示にし、財務には表示する | -| PHI を含むメモフィールド | 権限セットに該当する臨床ロールが含まれない限り非表示にする | - -### 作成時のガイダンス - -- フィールドが機微なデータを保持する場合は、読み取り専用ではなく**非表示**をデフォルトにしてください。読み取り専用でも、値がレスポンスやログに漏れてしまいます。 -- フィールドごとに 1 つのセットを作成するのではなく、実際のロール（`HR Manager`、`Finance Read-only`）に合致する権限セットにフィールドルールをまとめてください。監査が容易になります。 -- コンプライアンスのユースケースでは、フィールドセキュリティと監査ログの保持を組み合わせることで、事後に「誰がこの行を見たか」という問いに答えられるようにしてください。 diff --git a/content/docs/configure/permissions/permission-sets.ko.mdx b/content/docs/configure/permissions/permission-sets.ko.mdx deleted file mode 100644 index 25592a4b..00000000 --- a/content/docs/configure/permissions/permission-sets.ko.mdx +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: 권한 집합(Permission Sets) -description: 애플리케이션, 객체, 필드, 시스템 권한을 부여합니다. -translation: - source_sha: 3a15cf4a4b1be9a3e606541bf85e92e80b2588e92e8c100bfa318aa21ee31384 - guide_rev: 1 - mode: auto ---- - -권한 집합은 기능을 부여하는 기본적인 방법입니다. 사용자에게 직접 할당하거나 -[역할](/docs/configure/permissions/positions)을 통해 간접적으로 할당할 수 있습니다. - -## 권한 집합이 제어하는 항목 - -| 권한 유형 | 예시 | -|---|---| -| 애플리케이션 접근 | 사용자가 CRM 또는 Console을 열 수 있음 | -| 객체 권한 | 레코드 생성, 읽기, 수정, 삭제 | -| 필드 권한 | 선택한 필드에 대한 읽기 또는 수정 | -| 시스템 권한 | Console 접근, 보고서 실행, 데이터 내보내기 | -| 통합 권한 | API 키, 웹훅 또는 관리자 작업 사용 | - -## 객체 권한 - -객체 권한은 다음 질문에 답합니다. - -```text -Can this user perform this operation on this object at all? -``` - -권한 집합 부여는 다음 플래그 이름을 사용합니다(보안 플러그인의 권한 평가기에서 -적용되는 방식과 동일). - -| 플래그 | 의미 | -|---|---| -| `allowRead` | 레코드 접근 규칙에 의해 허용된 레코드 읽기 | -| `allowCreate` | 레코드 생성 | -| `allowEdit` | 레코드 접근 규칙에 의해 허용된 레코드 수정 | -| `allowDelete` | 레코드 접근 규칙에 의해 허용된 레코드 삭제 | -| `viewAllRecords` | 레코드 접근을 우회하여 해당 객체의 모든 레코드 읽기 | -| `modifyAllRecords` | 레코드 접근을 우회하여 해당 객체의 모든 레코드 수정 또는 삭제. 읽기에 대해 `viewAllRecords`를 암묵적으로 포함 | - -`viewAllRecords` 또는 `modifyAllRecords`가 일반적인 행 수준 경계를 우회하지 않는 -한 [레코드 접근](/docs/configure/permissions/record-access)은 여전히 중요합니다. -이러한 플래그는 관리용 권한 집합에만 사용하세요. 이는 사실상 해당 객체에 대한 -테넌트 전역 슈퍼유저 권한 부여와 같습니다. - -## 시스템 권한 - -시스템 권한은 다음과 같은 플랫폼 작업을 위한 것입니다. - -- Console 접근; -- 사용자 관리; -- 역할 및 권한 집합 관리; -- 보고서 실행; -- 보고서 내보내기; -- 통합 관리; -- 감사 로그 보기. - -관리자가 쉽게 감사할 수 있도록 시스템 권한을 비즈니스 객체 권한과 분리하여 -유지하세요. - -## 권장 집합 - -몇 가지 명명된 권한 집합으로 시작하세요. - -| 권한 집합 | 목적 | -|---|---| -| Basic User | 로그인 및 메인 애플리케이션 접근 | -| Setup Administrator | 사용자, 역할, 설정 및 진단 관리 | -| Report Viewer | 보고서 및 대시보드 보기 | -| Integration Operator | 웹훅/API 키 관리 | -| Support User | 지원 객체 읽기/수정 | - -그런 다음 고객의 애플리케이션에 맞는 도메인별 집합을 추가하세요. - -## 필드 보안(부록) - -권한 집합은 필드 수준의 권한도 포함합니다. 사용자가 레코드를 읽을 수 있더라도 -개별 필드를 숨기거나 읽기 전용으로 만들 수 있습니다. - -### 두 가지 모드 - -| 모드 | 효과 | -|---|---| -| **숨김** | 필드가 API 응답과 Console 뷰에서 완전히 제거됨 | -| **읽기 전용** | 필드가 반환되지만 쓰기는 거부됨 | - -### 적용 위치 - -객체 권한을 확인하는 동일한 평가기가 모든 경로(REST, ObjectQL, 생성된 Console -폼, 내보내기)에서 필드 규칙을 적용합니다. 하위 수준 API를 통한 "뒷문"은 -존재하지 않습니다. - -### 일반적인 패턴 - -| 사용 사례 | 권장 사항 | -|---|---| -| `sys_user`의 HR 데이터(급여, SSN) | `HR` 권한 집합을 제외한 모든 사용자에게 숨김 | -| 외부 시스템 식별자 | 지원 담당자에게는 읽기 전용, 통합 운영자에게는 쓰기 가능 | -| `product`의 내부 원가 vs. 고객 가격 | 영업에게는 `cost`를 숨기고 재무 부서에 노출 | -| PHI가 포함된 메모 필드 | 권한 집합에 해당 임상 역할이 포함되지 않는 한 숨김 | - -### 작성 지침 - -- 필드에 민감한 데이터가 포함된 경우 읽기 전용보다 **숨김**을 기본값으로 - 사용하세요. 읽기 전용은 여전히 응답과 로그에 값을 노출합니다. -- 필드별로 하나의 집합을 만드는 대신, 실제 역할(`HR Manager`, - `Finance Read-only`)에 맞는 권한 집합에 필드 규칙을 묶으세요. 감사가 더 - 쉬워집니다. -- 규정 준수 사용 사례의 경우, 사후에 "누가 이 행을 보았는가?"에 답할 수 있도록 - 필드 보안을 감사 로그 보존과 함께 사용하세요. diff --git a/content/docs/configure/permissions/record-access.de.mdx b/content/docs/configure/permissions/record-access.de.mdx deleted file mode 100644 index b5aa714d..00000000 --- a/content/docs/configure/permissions/record-access.de.mdx +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Datensatzzugriff -description: Steuern Sie, welche Datensätze ein Benutzer sehen oder ändern kann. -translation: - source_sha: 17abeb2628a200cbbc2bf0a1297c94858fc37405d52019fe2adc6c58c6af5d7a - guide_rev: 1 - mode: auto ---- - -Der Datensatzzugriff steuert, welche Zeilen ein Benutzer sehen oder ändern -kann, nachdem die Objektberechtigungen den Vorgang erlaubt haben. - -## Mechanismen - -| Mechanismus | Zweck | -|---|---| -| Sicherheit auf Zeilenebene | Mandanten- oder Organisationsisolation durchsetzen | -| Freigaberegeln | Zugriff anhand deklarativer Kriterien gewähren | -| Datensatzfreigaben | Zugriff für einen bestimmten Benutzer, eine Rolle oder eine Gruppe gewähren | -| Eigentümer/Hierarchie | Zugriff über Eigentümer- oder Vorgesetztenstruktur gewähren | - -## Standardmäßige Mandantenisolation - -Das Sicherheits-Plugin setzt die Mandantenisolation über den Kontext des -aktuellen Benutzers durch. Für Standard-Plattformobjekte schützen -Standardregeln globale Tabellen, die das normale Organisationsfeld nicht -enthalten. - -Die praktische Erwartung des Kunden lautet: - -```text -Users only see records that belong to their organization or records -explicitly shared with them. -``` - -## Freigaberegeln - -Verwenden Sie Freigaberegeln für wiederkehrende Geschäftsrichtlinien: - -- alle Regionalmanager können Accounts in ihrer Region lesen; -- Support-Manager können eskalierte Fälle sehen; -- die Finanzabteilung kann genehmigte Rechnungen lesen; -- Auditoren können Datensätze lesen, die zur Prüfung markiert sind. - -## Datensatzfreigaben - -Verwenden Sie Datensatzfreigaben für Ausnahmen: - -- eine Opportunity mit einem Spezialisten teilen; -- temporären Zugriff während einer Eskalation gewähren; -- einer externen Integration Zugriff auf einen bestimmten Datensatz geben. - -## Fehlerbehebung bei der Sichtbarkeit - -Wenn ein Benutzer einen Datensatz nicht sehen kann, prüfen Sie in dieser -Reihenfolge: - -1. Ist der Benutzer authentifiziert und in der erwarteten Organisation? -2. Verfügt der Benutzer über die Objektberechtigung `read`? -3. Erlaubt die Sicherheit auf Zeilenebene den Datensatz? -4. Gibt es eine Freigaberegel, die gelten sollte? -5. Gibt es eine direkte Datensatzfreigabe? -6. Gehört der Datensatz einem Benutzer oder einer Rolle in der erwarteten Hierarchie? -7. Betrachtet der Benutzer das korrekte Projekt bzw. den korrekten Hostnamen? diff --git a/content/docs/configure/permissions/record-access.es.mdx b/content/docs/configure/permissions/record-access.es.mdx deleted file mode 100644 index 292b6832..00000000 --- a/content/docs/configure/permissions/record-access.es.mdx +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: Acceso a registros -description: Controla qué registros puede ver o modificar un usuario. -translation: - source_sha: 17abeb2628a200cbbc2bf0a1297c94858fc37405d52019fe2adc6c58c6af5d7a - guide_rev: 1 - mode: auto ---- - -El acceso a registros controla qué filas puede ver o modificar un usuario una vez -que los permisos de objeto permiten la operación. - -## Mecanismos - -| Mecanismo | Propósito | -|---|---| -| Seguridad a nivel de fila | Aplicar el aislamiento por inquilino u organización | -| Reglas de uso compartido | Conceder acceso según criterios declarativos | -| Comparticiones de registros | Conceder acceso a un usuario, rol o grupo específico | -| Propiedad/jerarquía | Conceder acceso a través de la estructura de propietario o responsable | - -## Aislamiento por inquilino predeterminado - -El complemento de seguridad aplica el aislamiento por inquilino a través del -contexto del usuario actual. Para los objetos estándar de la plataforma, las -reglas predeterminadas protegen las tablas globales que no contienen el campo de -organización habitual. - -La expectativa práctica del cliente es: - -```text -Users only see records that belong to their organization or records -explicitly shared with them. -``` - -## Reglas de uso compartido - -Usa las reglas de uso compartido para políticas de negocio repetibles: - -- todos los responsables regionales pueden leer las cuentas de su región; -- los responsables de soporte pueden ver los casos escalados; -- finanzas puede leer las facturas aprobadas; -- los auditores pueden leer los registros marcados para revisión de auditoría. - -## Comparticiones de registros - -Usa las comparticiones de registros para excepciones: - -- compartir una oportunidad con un especialista; -- conceder acceso temporal durante una escalación; -- dar acceso a una integración externa a un registro específico. - -## Resolución de problemas de visibilidad - -Cuando un usuario no puede ver un registro, comprueba en este orden: - -1. ¿El usuario está autenticado y en la organización esperada? -2. ¿El usuario tiene permiso de `read` sobre el objeto? -3. ¿La seguridad a nivel de fila permite el registro? -4. ¿Hay una regla de uso compartido que debería aplicarse? -5. ¿Hay una compartición directa del registro? -6. ¿El registro pertenece a un usuario o rol dentro de la jerarquía esperada? -7. ¿El usuario está viendo el proyecto/nombre de host correcto? diff --git a/content/docs/configure/permissions/record-access.fr.mdx b/content/docs/configure/permissions/record-access.fr.mdx deleted file mode 100644 index ee3885d9..00000000 --- a/content/docs/configure/permissions/record-access.fr.mdx +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: Accès aux enregistrements -description: Contrôlez quels enregistrements un utilisateur peut voir ou modifier. -translation: - source_sha: 17abeb2628a200cbbc2bf0a1297c94858fc37405d52019fe2adc6c58c6af5d7a - guide_rev: 1 - mode: auto ---- - -L'accès aux enregistrements contrôle quelles lignes un utilisateur peut voir ou -modifier une fois que les permissions d'objet autorisent l'opération. - -## Mécanismes - -| Mécanisme | Objectif | -|---|---| -| Sécurité au niveau des lignes | Imposer l'isolation par locataire ou organisation | -| Règles de partage | Accorder l'accès selon des critères déclaratifs | -| Partages d'enregistrement | Accorder l'accès à un utilisateur, un rôle ou un groupe spécifique | -| Propriété/hiérarchie | Accorder l'accès via la structure du propriétaire ou du responsable | - -## Isolation par locataire par défaut - -Le plugin de sécurité impose l'isolation par locataire à travers le contexte de -l'utilisateur actuel. Pour les objets standard de la plateforme, des règles par -défaut protègent les tables globales qui ne comportent pas le champ -d'organisation habituel. - -L'attente concrète du client est la suivante : - -```text -Users only see records that belong to their organization or records -explicitly shared with them. -``` - -## Règles de partage - -Utilisez les règles de partage pour les politiques métier récurrentes : - -- tous les responsables régionaux peuvent lire les comptes de leur région ; -- les responsables du support peuvent voir les cas escaladés ; -- la finance peut lire les factures approuvées ; -- les auditeurs peuvent lire les enregistrements marqués pour révision d'audit. - -## Partages d'enregistrement - -Utilisez les partages d'enregistrement pour les exceptions : - -- partager une opportunité avec un spécialiste ; -- accorder un accès temporaire lors d'une escalade ; -- donner à une intégration externe l'accès à un enregistrement spécifique. - -## Dépannage de la visibilité - -Lorsqu'un utilisateur ne peut pas voir un enregistrement, vérifiez dans cet ordre : - -1. L'utilisateur est-il authentifié et dans l'organisation attendue ? -2. L'utilisateur dispose-t-il de la permission `read` sur l'objet ? -3. La sécurité au niveau des lignes autorise-t-elle l'enregistrement ? -4. Existe-t-il une règle de partage qui devrait s'appliquer ? -5. Existe-t-il un partage d'enregistrement direct ? -6. L'enregistrement appartient-il à un utilisateur ou à un rôle dans la hiérarchie attendue ? -7. L'utilisateur consulte-t-il le bon projet/nom d'hôte ? diff --git a/content/docs/configure/permissions/record-access.ja.mdx b/content/docs/configure/permissions/record-access.ja.mdx deleted file mode 100644 index 78ee2c46..00000000 --- a/content/docs/configure/permissions/record-access.ja.mdx +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: レコードアクセス -description: ユーザーが閲覧または変更できるレコードを制御します。 -translation: - source_sha: 17abeb2628a200cbbc2bf0a1297c94858fc37405d52019fe2adc6c58c6af5d7a - guide_rev: 1 - mode: auto ---- - -レコードアクセスは、オブジェクト権限によって操作が許可された後に、ユーザーがどの行を閲覧または変更できるかを制御します。 - -## 仕組み - -| 仕組み | 目的 | -|---|---| -| 行レベルセキュリティ | テナントまたは組織の分離を強制する | -| 共有ルール | 宣言的な条件に基づいてアクセスを付与する | -| レコード共有 | 特定のユーザー、ロール、またはグループにアクセスを付与する | -| 所有権/階層 | 所有者またはマネージャー構造を通じてアクセスを付与する | - -## デフォルトのテナント分離 - -セキュリティプラグインは、現在のユーザーのコンテキストを通じてテナント分離を強制します。標準のプラットフォームオブジェクトでは、通常の組織フィールドを持たないグローバルテーブルをデフォルトルールが保護します。 - -実際の顧客の期待は次のとおりです。 - -```text -Users only see records that belong to their organization or records -explicitly shared with them. -``` - -## 共有ルール - -繰り返し適用されるビジネスポリシーには共有ルールを使用します。 - -- すべての地域マネージャーは自分の地域のアカウントを読み取ることができる。 -- サポートマネージャーはエスカレーションされたケースを閲覧できる。 -- 財務部門は承認済みの請求書を読み取ることができる。 -- 監査担当者は監査レビュー用にタグ付けされたレコードを読み取ることができる。 - -## レコード共有 - -例外的なケースにはレコード共有を使用します。 - -- 1つの商談をスペシャリストと共有する。 -- エスカレーション中に一時的なアクセスを付与する。 -- 外部連携に特定のレコードへのアクセスを与える。 - -## 表示に関するトラブルシューティング - -ユーザーがレコードを閲覧できない場合は、次の順序で確認します。 - -1. ユーザーは認証されており、想定された組織に所属していますか? -2. ユーザーはオブジェクトの `read` 権限を持っていますか? -3. 行レベルセキュリティはそのレコードを許可していますか? -4. 適用されるべき共有ルールはありますか? -5. 直接のレコード共有はありますか? -6. レコードは想定された階層内のユーザーまたはロールによって所有されていますか? -7. ユーザーは正しいプロジェクト/ホスト名を見ていますか? diff --git a/content/docs/configure/permissions/record-access.ko.mdx b/content/docs/configure/permissions/record-access.ko.mdx deleted file mode 100644 index 176a6a7b..00000000 --- a/content/docs/configure/permissions/record-access.ko.mdx +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: 레코드 접근 -description: 사용자가 어떤 레코드를 보거나 수정할 수 있는지 제어합니다. -translation: - source_sha: 17abeb2628a200cbbc2bf0a1297c94858fc37405d52019fe2adc6c58c6af5d7a - guide_rev: 1 - mode: auto ---- - -레코드 접근은 객체 권한이 작업을 허용한 후, 사용자가 어떤 행을 보거나 수정할 수 -있는지 제어합니다. - -## 메커니즘 - -| 메커니즘 | 목적 | -|---|---| -| 행 수준 보안 | 테넌트 또는 조직 격리 적용 | -| 공유 규칙 | 선언적 기준에 따라 접근 권한 부여 | -| 레코드 공유 | 특정 사용자, 역할 또는 그룹에 접근 권한 부여 | -| 소유권/계층 구조 | 소유자 또는 관리자 구조를 통해 접근 권한 부여 | - -## 기본 테넌트 격리 - -보안 플러그인은 현재 사용자의 컨텍스트를 통해 테넌트 격리를 적용합니다. 표준 -플랫폼 객체의 경우, 기본 규칙이 일반적인 조직 필드를 포함하지 않는 전역 -테이블을 보호합니다. - -실제 고객의 기대는 다음과 같습니다. - -```text -Users only see records that belong to their organization or records -explicitly shared with them. -``` - -## 공유 규칙 - -반복 가능한 비즈니스 정책에는 공유 규칙을 사용하세요. - -- 모든 지역 관리자는 자신의 지역에 있는 계정을 읽을 수 있습니다. -- 지원 관리자는 에스컬레이션된 케이스를 볼 수 있습니다. -- 재무 부서는 승인된 인보이스를 읽을 수 있습니다. -- 감사자는 감사 검토용으로 태그된 레코드를 읽을 수 있습니다. - -## 레코드 공유 - -예외 상황에는 레코드 공유를 사용하세요. - -- 하나의 기회를 전문가와 공유합니다. -- 에스컬레이션 중에 임시 접근 권한을 부여합니다. -- 외부 통합에 특정 레코드에 대한 접근 권한을 부여합니다. - -## 가시성 문제 해결 - -사용자가 레코드를 볼 수 없을 때는 다음 순서로 확인하세요. - -1. 사용자가 인증되었으며 예상한 조직에 속해 있습니까? -2. 사용자에게 객체 `read` 권한이 있습니까? -3. 행 수준 보안이 해당 레코드를 허용합니까? -4. 적용되어야 할 공유 규칙이 있습니까? -5. 직접 레코드 공유가 있습니까? -6. 레코드가 예상한 계층 구조 내의 사용자 또는 역할이 소유하고 있습니까? -7. 사용자가 올바른 프로젝트/호스트명을 보고 있습니까? diff --git a/content/docs/configure/storage.de.mdx b/content/docs/configure/storage.de.mdx deleted file mode 100644 index 344c4f3c..00000000 --- a/content/docs/configure/storage.de.mdx +++ /dev/null @@ -1,193 +0,0 @@ ---- -title: Speicher -description: Wo ObjectOS Dateien ablegt — lokale Festplatte, S3, R2, MinIO, Spaces. -translation: - source_sha: 7ec22c893adfedc9ade2e05655ab61ddd3b1aed89f9313707830fc2464f93e58 - guide_rev: 1 - mode: auto ---- - -ObjectOS-Dateien (Anhänge, Uploads, generierte Dokumente) laufen durch -den **Speicherdienst** — eine austauschbare Abstraktion mit zwei Adaptern: -**lokales Dateisystem** (Standard) und **S3-kompatibel** (Produktion). - -Der Dienst wird von `@objectstack/service-storage` bereitgestellt und ist -in Standalone- und Projekt-Boots standardmäßig aktiviert. - -## Wie Benutzer damit interagieren - -| Oberfläche | Verhalten | -|---|---| -| Console Datei-/Bildfelder | Der Browser lädt über vorab signierte URLs direkt in den Speicher hoch | -| REST `/api/v1/storage/*` | Programmatische Upload-/Download-Endpunkte | -| Objektfelder `file` / `image` | Werden als Upload-Widgets gerendert; Metadaten bleiben in `sys_file` erhalten | - -Dateien werden im Systemobjekt `sys_file` nachverfolgt — niemals als -rohe Pfade in Ihren Datensätzen. Das entkoppelt Ihr Datenmodell vom -Speicher-Backend. - -## Lokales Dateisystem (Standard) - -Geeignet für: Entwicklung, Single-Node-Deployments, Demos. - -```ts -// objectstack.config.ts (or wherever you assemble plugins) -import { StorageServicePlugin } from '@objectstack/service-storage'; - -new StorageServicePlugin({ - adapter: 'local', - local: { - rootDir: './uploads', - baseUrl: 'http://localhost:3000', // for presigned URLs - signingSecret: process.env.OS_STORAGE_SIGNING_SECRET, // optional; auto-generated if omitted - }, - presignedTtl: 3600, // seconds — TTL for presigned URLs - sessionTtl: 86400, // seconds — TTL for chunked upload sessions -}); -``` - -Im Standalone-Modus (`os start` ohne Projekt) konfiguriert die Laufzeitumgebung -den lokalen Speicher automatisch unter `.objectstack/data/uploads/`. Überschreiben -Sie das Stammverzeichnis mit der Umgebungsvariable `OS_STORAGE_ROOT`. - -**Die Produktionstauglichkeit hängt von der Form des Deployments ab:** - -- ✅ Desktop-Apps, interne Single-Node-Tools, Edge-/On-Prem-Appliances — - lokaler Speicher ist in Ordnung, solange das Verzeichnis `uploads/` - in Ihr Dateisystem-Backup einbezogen wird (oder bei Desktop-Apps in - einem vom Benutzer kontrollierten Sync-Ordner liegt). -- ❌ Multi-Node, Multi-AZ oder alles, was regionsübergreifende - Beständigkeit benötigt — verwenden Sie S3-kompatiblen Speicher. - -## S3-kompatibel (Produktion) - -Geeignet für: Produktion, Multi-Node, Beständigkeit + Lifecycle-Management. - -```bash -pnpm add @aws-sdk/client-s3 @aws-sdk/s3-request-presigner -``` - -```ts -import { StorageServicePlugin } from '@objectstack/service-storage'; - -new StorageServicePlugin({ - adapter: 's3', - s3: { - bucket: 'my-bucket', - region: 'us-east-1', - // omit credentials to use the AWS SDK's default chain - // (env, ~/.aws, IAM role) - }, -}); -``` - -Das AWS SDK liest Anmeldedaten aus seiner üblichen Kette: - -| Quelle | Umgebungsvariable | -|---|---| -| Standard-Umgebung | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION` | -| Session-Token | `AWS_SESSION_TOKEN` | -| Gemeinsame Konfiguration | `~/.aws/credentials`, `AWS_PROFILE` | -| IAM-Rolle | Automatisch auf EC2 / ECS / EKS / Lambda — keine Konfiguration | - -### Cloudflare R2 - -```ts -new StorageServicePlugin({ - adapter: 's3', - s3: { - bucket: 'my-bucket', - region: 'auto', - endpoint: 'https://.r2.cloudflarestorage.com', - forcePathStyle: false, - }, -}); -``` - -Anmeldedaten: R2 Access Key ID + Secret, übergeben über die Standard- -`AWS_*`-Umgebungsvariablen oder Ihren Secret Manager. - -### MinIO (selbst gehostet) - -```ts -new StorageServicePlugin({ - adapter: 's3', - s3: { - bucket: 'my-bucket', - region: 'us-east-1', - endpoint: 'http://minio.internal:9000', - forcePathStyle: true, - }, -}); -``` - -### DigitalOcean Spaces - -```ts -new StorageServicePlugin({ - adapter: 's3', - s3: { - bucket: 'my-bucket', - region: 'nyc3', - endpoint: 'https://nyc3.digitaloceanspaces.com', - forcePathStyle: false, - }, -}); -``` - -### S3-Bucket-Policy - -Der Speicher verwendet vorab signierte PUT-/GET-URLs. Empfohlene Bucket-Policy: - -- Jeglichen öffentlichen Zugriff blockieren. -- CORS: `PUT`/`GET` von Ihren ObjectOS-Hostnamen erlauben. -- Lifecycle: unvollständige Multipart-Uploads nach 1–7 Tagen ablaufen lassen; - mit `temp=true` markierte Objekte nach 24 Stunden ablaufen lassen. -- Versioning + Object Lock: optional, empfohlen für Compliance-Deployments. - -## REST-Oberfläche - -`@objectstack/client` ruft diese auf — normalerweise greifen Sie nicht direkt darauf zu: - -| Methode | Pfad | Zweck | -|---|---|---| -| POST | `/api/v1/storage/upload/presigned` | Eine vorab signierte Upload-URL abrufen | -| POST | `/api/v1/storage/upload/complete` | Einen abgeschlossenen Upload festschreiben | -| POST | `/api/v1/storage/upload/chunked` | Chunked-Upload beginnen | -| PUT | `/api/v1/storage/upload/chunked/:uploadId/chunk/:i` | Einen Chunk hochladen | -| POST | `/api/v1/storage/upload/chunked/:uploadId/complete` | Chunked-Upload abschließen | -| GET | `/api/v1/storage/upload/chunked/:uploadId/progress` | Fortschritt abfragen | -| GET | `/api/v1/storage/files/:fileId/url` | Eine vorab signierte Download-URL abrufen | - -Die Autorisierung pro Datei wird vom Permission-Evaluator des Security-Plugins -gegen das Objekt `sys_file` abgewickelt — Sie benötigen keine separaten -ACLs auf Speicherebene. - -## Live-Konfiguration - -Wenn der Settings-Dienst aktiviert ist (standardmäßig der Fall), kann ein -Administrator den Speicheradapter in **Console → Configuration → Storage** -ohne Neustart austauschen: - -- Adapter, Bucket, Region, Endpunkt auswählen; -- Anmeldedaten einfügen (im Ruhezustand verschlüsselt in `sys_setting`); -- vor dem Speichern auf **Test connection** klicken. - -Die Änderung gilt ab der nächsten Anfrage — kein Neustart erforderlich. - -## Dimensionierung - -| Ressource | Standard | Anpassbar | -|---|---|---| -| TTL für vorab signierte URLs | 1 Stunde | Plugin-Option `presignedTtl` | -| TTL für Chunked-Upload-Sitzungen | 24 Stunden | Plugin-Option `sessionTtl` | -| Maximaler Single-Part-Upload | Vom Backend vorgegeben (S3 = 5 GB) | — | -| Maximaler Chunked-Upload | Vom Backend vorgegeben (S3 = 5 TB) | — | - -## Wie es weitergeht - -- [System settings](/docs/configure/system-settings) — Live-Konfiguration - und der Settings-Dienst, der bei Speicher-Wechseln verwendet wird -- [Production Readiness](/docs/operate/production) — Checkliste, die die - Beständigkeit von Objektspeicher und Backups umfasst -- [`@objectstack/service-storage` on GitHub](https://github.com/objectstack-ai/objectstack/tree/main/packages/services/service-storage) — Quellcode und vollständige Optionsreferenz diff --git a/content/docs/configure/storage.es.mdx b/content/docs/configure/storage.es.mdx deleted file mode 100644 index 54e16e74..00000000 --- a/content/docs/configure/storage.es.mdx +++ /dev/null @@ -1,194 +0,0 @@ ---- -title: Almacenamiento -description: Dónde coloca ObjectOS los archivos — disco local, S3, R2, MinIO, Spaces. -translation: - source_sha: 7ec22c893adfedc9ade2e05655ab61ddd3b1aed89f9313707830fc2464f93e58 - guide_rev: 1 - mode: auto ---- - -Los archivos de ObjectOS (adjuntos, cargas, documentos generados) fluyen a través -del **servicio de almacenamiento** — una abstracción conectable con dos adaptadores: -**sistema de archivos local** (predeterminado) y **compatible con S3** (producción). - -El servicio lo proporciona `@objectstack/service-storage` y está -habilitado de forma predeterminada en los arranques standalone y de proyecto. - -## Cómo interactúan los usuarios con él - -| Superficie | Comportamiento | -|---|---| -| Campos de archivo/imagen de Console | El navegador carga directamente al almacenamiento mediante URLs prefirmadas | -| REST `/api/v1/storage/*` | Endpoints de carga/descarga programáticos | -| Campos `file` / `image` de objetos | Se renderizan como widgets de carga; los metadatos persisten en `sys_file` | - -Los archivos se rastrean en el objeto de sistema `sys_file` — nunca como rutas -sin procesar en tus registros. Eso desacopla tu modelo de datos del -backend de almacenamiento. - -## Sistema de archivos local (predeterminado) - -Ideal para: desarrollo, despliegues de un solo nodo, demostraciones. - -```ts -// objectstack.config.ts (or wherever you assemble plugins) -import { StorageServicePlugin } from '@objectstack/service-storage'; - -new StorageServicePlugin({ - adapter: 'local', - local: { - rootDir: './uploads', - baseUrl: 'http://localhost:3000', // for presigned URLs - signingSecret: process.env.OS_STORAGE_SIGNING_SECRET, // optional; auto-generated if omitted - }, - presignedTtl: 3600, // seconds — TTL for presigned URLs - sessionTtl: 86400, // seconds — TTL for chunked upload sessions -}); -``` - -En modo standalone (`os start` sin proyecto), el runtime configura -el almacenamiento local automáticamente en `.objectstack/data/uploads/`. Anula -el directorio raíz con la variable de entorno `OS_STORAGE_ROOT`. - -**La idoneidad para producción depende de la forma del despliegue:** - -- ✅ Aplicaciones de escritorio, herramientas internas de un solo nodo, dispositivos - edge / on-prem — el almacenamiento local funciona bien, siempre que el directorio - `uploads/` esté incluido en tu copia de seguridad del sistema de archivos (o resida - en una carpeta de sincronización controlada por el usuario en aplicaciones de escritorio). -- ❌ Multinodo, multi-AZ, o cualquier cosa que requiera durabilidad - entre regiones — usa almacenamiento compatible con S3. - -## Compatible con S3 (producción) - -Ideal para: producción, multinodo, durabilidad + gestión del ciclo de vida. - -```bash -pnpm add @aws-sdk/client-s3 @aws-sdk/s3-request-presigner -``` - -```ts -import { StorageServicePlugin } from '@objectstack/service-storage'; - -new StorageServicePlugin({ - adapter: 's3', - s3: { - bucket: 'my-bucket', - region: 'us-east-1', - // omit credentials to use the AWS SDK's default chain - // (env, ~/.aws, IAM role) - }, -}); -``` - -El AWS SDK lee las credenciales de su cadena habitual: - -| Origen | Variable de entorno | -|---|---| -| Entorno estándar | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION` | -| Token de sesión | `AWS_SESSION_TOKEN` | -| Configuración compartida | `~/.aws/credentials`, `AWS_PROFILE` | -| Rol de IAM | Automático en EC2 / ECS / EKS / Lambda — sin configuración | - -### Cloudflare R2 - -```ts -new StorageServicePlugin({ - adapter: 's3', - s3: { - bucket: 'my-bucket', - region: 'auto', - endpoint: 'https://.r2.cloudflarestorage.com', - forcePathStyle: false, - }, -}); -``` - -Credenciales: ID de clave de acceso de R2 + secreto, pasados mediante las -variables de entorno estándar `AWS_*` o tu gestor de secretos. - -### MinIO (autoalojado) - -```ts -new StorageServicePlugin({ - adapter: 's3', - s3: { - bucket: 'my-bucket', - region: 'us-east-1', - endpoint: 'http://minio.internal:9000', - forcePathStyle: true, - }, -}); -``` - -### DigitalOcean Spaces - -```ts -new StorageServicePlugin({ - adapter: 's3', - s3: { - bucket: 'my-bucket', - region: 'nyc3', - endpoint: 'https://nyc3.digitaloceanspaces.com', - forcePathStyle: false, - }, -}); -``` - -### Política de bucket de S3 - -El almacenamiento usa URLs prefirmadas PUT/GET. Política de bucket recomendada: - -- Bloquea todo el acceso público. -- CORS: permite `PUT`/`GET` desde tus nombres de host de ObjectOS. -- Ciclo de vida: caduca las cargas multiparte incompletas tras 1–7 días; caduca los - objetos etiquetados con `temp=true` tras 24 horas. -- Versionado + Object Lock: opcional, recomendado para despliegues - de cumplimiento normativo. - -## Superficie REST - -`@objectstack/client` llama a estos — normalmente no los invocas directamente: - -| Método | Ruta | Propósito | -|---|---|---| -| POST | `/api/v1/storage/upload/presigned` | Obtener una URL de carga prefirmada | -| POST | `/api/v1/storage/upload/complete` | Confirmar una carga finalizada | -| POST | `/api/v1/storage/upload/chunked` | Iniciar una carga por fragmentos | -| PUT | `/api/v1/storage/upload/chunked/:uploadId/chunk/:i` | Cargar un fragmento | -| POST | `/api/v1/storage/upload/chunked/:uploadId/complete` | Finalizar la carga por fragmentos | -| GET | `/api/v1/storage/upload/chunked/:uploadId/progress` | Consultar el progreso | -| GET | `/api/v1/storage/files/:fileId/url` | Obtener una URL de descarga prefirmada | - -La autorización por archivo la gestiona el evaluador de permisos del plugin de -seguridad contra el objeto `sys_file` — no necesitas ACLs separadas en la capa -de almacenamiento. - -## Configuración en vivo - -Cuando el servicio de settings está habilitado (lo está de forma predeterminada), un administrador puede -cambiar el adaptador de almacenamiento en **Console → Configuration → Storage** sin -reiniciar: - -- elige adaptador, bucket, región, endpoint; -- pega las credenciales (cifradas en reposo en `sys_setting`); -- haz clic en **Test connection** antes de guardar. - -El cambio se aplica en la siguiente petición — sin necesidad de reiniciar. - -## Dimensionamiento - -| Recurso | Predeterminado | Ajustable | -|---|---|---| -| TTL de URL prefirmada | 1 hora | Opción del plugin `presignedTtl` | -| TTL de sesión de carga por fragmentos | 24 horas | Opción del plugin `sessionTtl` | -| Carga máxima de una sola parte | Impuesta por el backend (S3 = 5 GB) | — | -| Carga máxima por fragmentos | Impuesta por el backend (S3 = 5 TB) | — | - -## A dónde ir después - -- [Configuración del sistema](/docs/configure/system-settings) — configuración - en vivo y el servicio de settings que utilizan los cambios de almacenamiento -- [Preparación para producción](/docs/operate/production) — lista de verificación que - incluye la durabilidad y la copia de seguridad del almacenamiento de objetos -- [`@objectstack/service-storage` en GitHub](https://github.com/objectstack-ai/objectstack/tree/main/packages/services/service-storage) — código fuente y referencia completa de opciones diff --git a/content/docs/configure/storage.fr.mdx b/content/docs/configure/storage.fr.mdx deleted file mode 100644 index 13329d40..00000000 --- a/content/docs/configure/storage.fr.mdx +++ /dev/null @@ -1,200 +0,0 @@ ---- -title: Stockage -description: Où ObjectOS place les fichiers — disque local, S3, R2, MinIO, Spaces. -translation: - source_sha: 7ec22c893adfedc9ade2e05655ab61ddd3b1aed89f9313707830fc2464f93e58 - guide_rev: 1 - mode: auto ---- - -Les fichiers ObjectOS (pièces jointes, téléversements, documents générés) -transitent par le **service de stockage** — une abstraction modulaire dotée -de deux adaptateurs : le **système de fichiers local** (par défaut) et le -mode **compatible S3** (production). - -Le service est fourni par `@objectstack/service-storage` et est activé par -défaut lors des démarrages autonomes et de projet. - -## Comment les utilisateurs interagissent avec lui - -| Surface | Comportement | -|---|---| -| Champs de fichier/image de la Console | Le navigateur téléverse directement vers le stockage via des URL présignées | -| REST `/api/v1/storage/*` | Points de terminaison programmatiques de téléversement/téléchargement | -| Champs `file` / `image` d'objet | Rendus sous forme de widgets de téléversement ; les métadonnées sont conservées dans `sys_file` | - -Les fichiers sont suivis dans l'objet système `sys_file` — jamais sous forme -de chemins bruts dans vos enregistrements. Cela découple votre modèle de -données du backend de stockage. - -## Système de fichiers local (par défaut) - -Adapté à : le développement, les déploiements mononœuds, les démos. - -```ts -// objectstack.config.ts (or wherever you assemble plugins) -import { StorageServicePlugin } from '@objectstack/service-storage'; - -new StorageServicePlugin({ - adapter: 'local', - local: { - rootDir: './uploads', - baseUrl: 'http://localhost:3000', // for presigned URLs - signingSecret: process.env.OS_STORAGE_SIGNING_SECRET, // optional; auto-generated if omitted - }, - presignedTtl: 3600, // seconds — TTL for presigned URLs - sessionTtl: 86400, // seconds — TTL for chunked upload sessions -}); -``` - -En mode autonome (`os start` sans projet), le runtime configure -automatiquement le stockage local sous `.objectstack/data/uploads/`. -Remplacez le répertoire racine avec la variable d'environnement -`OS_STORAGE_ROOT`. - -**L'adéquation à la production dépend de la forme du déploiement :** - -- ✅ Applications de bureau, outils internes mononœuds, équipements - edge / on-premise — le stockage local convient, tant que le répertoire - `uploads/` est inclus dans la sauvegarde de votre système de fichiers - (ou réside dans un dossier de synchronisation contrôlé par l'utilisateur - pour les applications de bureau). -- ❌ Multinœuds, multi-AZ, ou tout ce qui nécessite une durabilité - inter-régions — utilisez un stockage compatible S3. - -## Compatible S3 (production) - -Adapté à : la production, le multinœuds, la durabilité + la gestion du -cycle de vie. - -```bash -pnpm add @aws-sdk/client-s3 @aws-sdk/s3-request-presigner -``` - -```ts -import { StorageServicePlugin } from '@objectstack/service-storage'; - -new StorageServicePlugin({ - adapter: 's3', - s3: { - bucket: 'my-bucket', - region: 'us-east-1', - // omit credentials to use the AWS SDK's default chain - // (env, ~/.aws, IAM role) - }, -}); -``` - -Le SDK AWS lit les identifiants depuis sa chaîne habituelle : - -| Source | Variable d'environnement | -|---|---| -| Env standard | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION` | -| Jeton de session | `AWS_SESSION_TOKEN` | -| Config partagée | `~/.aws/credentials`, `AWS_PROFILE` | -| Rôle IAM | Automatique sur EC2 / ECS / EKS / Lambda — aucune configuration | - -### Cloudflare R2 - -```ts -new StorageServicePlugin({ - adapter: 's3', - s3: { - bucket: 'my-bucket', - region: 'auto', - endpoint: 'https://.r2.cloudflarestorage.com', - forcePathStyle: false, - }, -}); -``` - -Identifiants : ID de clé d'accès R2 + secret, transmis via les variables -d'environnement standard `AWS_*` ou votre gestionnaire de secrets. - -### MinIO (auto-hébergé) - -```ts -new StorageServicePlugin({ - adapter: 's3', - s3: { - bucket: 'my-bucket', - region: 'us-east-1', - endpoint: 'http://minio.internal:9000', - forcePathStyle: true, - }, -}); -``` - -### DigitalOcean Spaces - -```ts -new StorageServicePlugin({ - adapter: 's3', - s3: { - bucket: 'my-bucket', - region: 'nyc3', - endpoint: 'https://nyc3.digitaloceanspaces.com', - forcePathStyle: false, - }, -}); -``` - -### Politique de bucket S3 - -Le stockage utilise des URL présignées PUT/GET. Politique de bucket -recommandée : - -- Bloquer tout accès public. -- CORS : autoriser `PUT`/`GET` depuis le(s) nom(s) d'hôte de votre ObjectOS. -- Cycle de vie : expirer les téléversements multipart incomplets après - 1 à 7 jours ; expirer les objets étiquetés `temp=true` après 24 heures. -- Versioning + Object Lock : optionnel, recommandé pour les déploiements - soumis à des exigences de conformité. - -## Surface REST - -`@objectstack/client` appelle ces points de terminaison — vous ne les -sollicitez généralement pas directement : - -| Méthode | Chemin | Objectif | -|---|---|---| -| POST | `/api/v1/storage/upload/presigned` | Obtenir une URL de téléversement présignée | -| POST | `/api/v1/storage/upload/complete` | Valider un téléversement terminé | -| POST | `/api/v1/storage/upload/chunked` | Démarrer un téléversement fragmenté | -| PUT | `/api/v1/storage/upload/chunked/:uploadId/chunk/:i` | Téléverser un fragment | -| POST | `/api/v1/storage/upload/chunked/:uploadId/complete` | Terminer un téléversement fragmenté | -| GET | `/api/v1/storage/upload/chunked/:uploadId/progress` | Suivre la progression | -| GET | `/api/v1/storage/files/:fileId/url` | Obtenir une URL de téléchargement présignée | - -L'autorisation par fichier est gérée par l'évaluateur de permissions du -plugin de sécurité sur l'objet `sys_file` — vous n'avez pas besoin d'ACL -distinctes au niveau de la couche de stockage. - -## Configuration en direct - -Lorsque le service de paramètres est activé (c'est le cas par défaut), un -administrateur peut changer d'adaptateur de stockage dans -**Console → Configuration → Storage** sans redémarrer : - -- choisir l'adaptateur, le bucket, la région, l'endpoint ; -- coller les identifiants (chiffrés au repos dans `sys_setting`) ; -- cliquer sur **Test connection** avant d'enregistrer. - -Le changement s'applique à la requête suivante — aucun redémarrage requis. - -## Dimensionnement - -| Ressource | Par défaut | Ajustable | -|---|---|---| -| TTL d'URL présignée | 1 heure | Option de plugin `presignedTtl` | -| TTL de session de téléversement fragmenté | 24 heures | Option de plugin `sessionTtl` | -| Téléversement single-part max | Imposé par le backend (S3 = 5 Go) | — | -| Téléversement fragmenté max | Imposé par le backend (S3 = 5 To) | — | - -## Pour aller plus loin - -- [Paramètres système](/docs/configure/system-settings) — configuration en - direct et service de paramètres utilisé par les changements de stockage -- [Préparation à la production](/docs/operate/production) — liste de - contrôle incluant la durabilité et la sauvegarde du stockage d'objets -- [`@objectstack/service-storage` sur GitHub](https://github.com/objectstack-ai/objectstack/tree/main/packages/services/service-storage) — source et référence complète des options diff --git a/content/docs/configure/storage.ja.mdx b/content/docs/configure/storage.ja.mdx deleted file mode 100644 index 9f5a4411..00000000 --- a/content/docs/configure/storage.ja.mdx +++ /dev/null @@ -1,194 +0,0 @@ ---- -title: ストレージ -description: ObjectOS がファイルを保存する場所 — ローカルディスク、S3、R2、MinIO、Spaces。 -translation: - source_sha: 7ec22c893adfedc9ade2e05655ab61ddd3b1aed89f9313707830fc2464f93e58 - guide_rev: 1 - mode: auto ---- - -ObjectOS のファイル（添付ファイル、アップロード、生成されたドキュメント）は -**ストレージサービス** を経由します。これは 2 つのアダプターを備えた -プラガブルな抽象化レイヤーです。**ローカルファイルシステム**（デフォルト）と -**S3 互換**（本番環境）です。 - -このサービスは `@objectstack/service-storage` によって提供され、 -スタンドアロンおよびプロジェクトの起動時にデフォルトで有効になります。 - -## ユーザーはどのように操作するか - -| 操作面 | 動作 | -|---|---| -| Console のファイル / 画像フィールド | ブラウザが署名付き URL を介してストレージへ直接アップロード | -| REST `/api/v1/storage/*` | プログラムによるアップロード / ダウンロードのエンドポイント | -| オブジェクトの `file` / `image` フィールド | アップロードウィジェットとして描画され、メタデータは `sys_file` に永続化される | - -ファイルは `sys_file` システムオブジェクトで追跡されます。レコード内に -生のパスとして保存されることはありません。これにより、データモデルが -ストレージバックエンドから切り離されます。 - -## ローカルファイルシステム（デフォルト） - -適した用途: 開発、シングルノードのデプロイ、デモ。 - -```ts -// objectstack.config.ts (or wherever you assemble plugins) -import { StorageServicePlugin } from '@objectstack/service-storage'; - -new StorageServicePlugin({ - adapter: 'local', - local: { - rootDir: './uploads', - baseUrl: 'http://localhost:3000', // for presigned URLs - signingSecret: process.env.OS_STORAGE_SIGNING_SECRET, // optional; auto-generated if omitted - }, - presignedTtl: 3600, // seconds — TTL for presigned URLs - sessionTtl: 86400, // seconds — TTL for chunked upload sessions -}); -``` - -スタンドアロンモード（プロジェクトなしの `os start`）では、ランタイムが -`.objectstack/data/uploads/` 配下にローカルストレージを自動的に構成します。 -ルートディレクトリは `OS_STORAGE_ROOT` 環境変数で上書きできます。 - -**本番環境での適合性はデプロイの形態によって決まります:** - -- ✅ デスクトップアプリ、シングルノードの社内ツール、エッジ / オンプレミスの - アプライアンス — `uploads/` ディレクトリがファイルシステムのバックアップに - 含まれている（またはデスクトップアプリの場合はユーザー管理の同期フォルダー上に - 存在する）限り、ローカルストレージで問題ありません。 -- ❌ マルチノード、マルチ AZ、またはクロスリージョンの耐久性を必要とするもの — - S3 互換ストレージを使用してください。 - -## S3 互換（本番環境） - -適した用途: 本番環境、マルチノード、耐久性 + ライフサイクル管理。 - -```bash -pnpm add @aws-sdk/client-s3 @aws-sdk/s3-request-presigner -``` - -```ts -import { StorageServicePlugin } from '@objectstack/service-storage'; - -new StorageServicePlugin({ - adapter: 's3', - s3: { - bucket: 'my-bucket', - region: 'us-east-1', - // omit credentials to use the AWS SDK's default chain - // (env, ~/.aws, IAM role) - }, -}); -``` - -AWS SDK は通常のチェーンから認証情報を読み取ります: - -| ソース | 環境変数 | -|---|---| -| 標準の環境変数 | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION` | -| セッショントークン | `AWS_SESSION_TOKEN` | -| 共有設定 | `~/.aws/credentials`, `AWS_PROFILE` | -| IAM ロール | EC2 / ECS / EKS / Lambda 上では自動 — 設定不要 | - -### Cloudflare R2 - -```ts -new StorageServicePlugin({ - adapter: 's3', - s3: { - bucket: 'my-bucket', - region: 'auto', - endpoint: 'https://.r2.cloudflarestorage.com', - forcePathStyle: false, - }, -}); -``` - -認証情報: R2 のアクセスキー ID + シークレットを、標準の `AWS_*` 環境変数 -またはシークレットマネージャー経由で渡します。 - -### MinIO（セルフホスト） - -```ts -new StorageServicePlugin({ - adapter: 's3', - s3: { - bucket: 'my-bucket', - region: 'us-east-1', - endpoint: 'http://minio.internal:9000', - forcePathStyle: true, - }, -}); -``` - -### DigitalOcean Spaces - -```ts -new StorageServicePlugin({ - adapter: 's3', - s3: { - bucket: 'my-bucket', - region: 'nyc3', - endpoint: 'https://nyc3.digitaloceanspaces.com', - forcePathStyle: false, - }, -}); -``` - -### S3 バケットポリシー - -ストレージは署名付きの PUT/GET URL を使用します。推奨されるバケットポリシー: - -- すべてのパブリックアクセスをブロックする。 -- CORS: ObjectOS のホスト名から `PUT`/`GET` を許可する。 -- ライフサイクル: 未完了のマルチパートアップロードを 1〜7 日後に期限切れにする。 - `temp=true` のタグが付いたオブジェクトを 24 時間後に期限切れにする。 -- バージョニング + Object Lock: 任意。コンプライアンス対応のデプロイでは推奨。 - -## REST インターフェイス - -`@objectstack/client` がこれらを呼び出します。通常は直接アクセスする必要はありません: - -| メソッド | パス | 目的 | -|---|---|---| -| POST | `/api/v1/storage/upload/presigned` | 署名付きアップロード URL を取得する | -| POST | `/api/v1/storage/upload/complete` | 完了したアップロードをコミットする | -| POST | `/api/v1/storage/upload/chunked` | チャンクアップロードを開始する | -| PUT | `/api/v1/storage/upload/chunked/:uploadId/chunk/:i` | チャンクをアップロードする | -| POST | `/api/v1/storage/upload/chunked/:uploadId/complete` | チャンクアップロードを完了する | -| GET | `/api/v1/storage/upload/chunked/:uploadId/progress` | 進捗をポーリングする | -| GET | `/api/v1/storage/files/:fileId/url` | 署名付きダウンロード URL を取得する | - -ファイルごとの認可は、`sys_file` オブジェクトに対するセキュリティプラグインの -権限エバリュエーターによって処理されます。ストレージ層に個別の ACL を -用意する必要はありません。 - -## ライブ構成 - -設定サービスが有効になっている場合（デフォルトで有効です）、管理者は -**Console → Configuration → Storage** からストレージアダプターを再起動せずに -切り替えることができます: - -- アダプター、バケット、リージョン、エンドポイントを選択する。 -- 認証情報を貼り付ける（`sys_setting` 内で保存時に暗号化される）。 -- 保存する前に **Test connection** をクリックする。 - -変更は次のリクエストから適用されます。再起動は不要です。 - -## サイジング - -| リソース | デフォルト | 調整可能 | -|---|---|---| -| 署名付き URL の TTL | 1 時間 | `presignedTtl` プラグインオプション | -| チャンクアップロードセッションの TTL | 24 時間 | `sessionTtl` プラグインオプション | -| 単一パートアップロードの最大サイズ | バックエンドによる制限（S3 = 5 GB） | — | -| チャンクアップロードの最大サイズ | バックエンドによる制限（S3 = 5 TB） | — | - -## 次に読むべきもの - -- [システム設定](/docs/configure/system-settings) — ライブ構成と、 - ストレージの切り替えで使用される設定サービス -- [本番環境への準備](/docs/operate/production) — オブジェクトストレージの - 耐久性とバックアップを含むチェックリスト -- [GitHub 上の `@objectstack/service-storage`](https://github.com/objectstack-ai/objectstack/tree/main/packages/services/service-storage) — ソースとすべてのオプションのリファレンス diff --git a/content/docs/configure/storage.ko.mdx b/content/docs/configure/storage.ko.mdx deleted file mode 100644 index 871fbe4b..00000000 --- a/content/docs/configure/storage.ko.mdx +++ /dev/null @@ -1,191 +0,0 @@ ---- -title: 스토리지 -description: ObjectOS가 파일을 저장하는 위치 — 로컬 디스크, S3, R2, MinIO, Spaces. -translation: - source_sha: 7ec22c893adfedc9ade2e05655ab61ddd3b1aed89f9313707830fc2464f93e58 - guide_rev: 1 - mode: auto ---- - -ObjectOS 파일(첨부 파일, 업로드, 생성된 문서)은 -**스토리지 서비스**를 통해 흐릅니다 — 두 가지 어댑터를 갖춘 플러그형 추상화 계층으로, -**로컬 파일 시스템**(기본값)과 **S3 호환**(프로덕션)을 제공합니다. - -이 서비스는 `@objectstack/service-storage`에서 제공되며 -standalone 및 프로젝트 부팅 시 기본적으로 활성화됩니다. - -## 사용자가 상호작용하는 방식 - -| 인터페이스 | 동작 | -|---|---| -| Console 파일/이미지 필드 | 브라우저가 presigned URL을 통해 스토리지로 직접 업로드 | -| REST `/api/v1/storage/*` | 프로그래밍 방식의 업로드/다운로드 엔드포인트 | -| 객체 `file` / `image` 필드 | 업로드 위젯으로 렌더링되며, 메타데이터는 `sys_file`에 유지됨 | - -파일은 레코드에 원시 경로로 저장되는 것이 아니라 `sys_file` 시스템 객체에서 추적됩니다. -이를 통해 데이터 모델이 스토리지 백엔드로부터 분리됩니다. - -## 로컬 파일 시스템 (기본값) - -적합한 용도: 개발, 단일 노드 배포, 데모. - -```ts -// objectstack.config.ts (or wherever you assemble plugins) -import { StorageServicePlugin } from '@objectstack/service-storage'; - -new StorageServicePlugin({ - adapter: 'local', - local: { - rootDir: './uploads', - baseUrl: 'http://localhost:3000', // for presigned URLs - signingSecret: process.env.OS_STORAGE_SIGNING_SECRET, // optional; auto-generated if omitted - }, - presignedTtl: 3600, // seconds — TTL for presigned URLs - sessionTtl: 86400, // seconds — TTL for chunked upload sessions -}); -``` - -standalone 모드(프로젝트 없이 `os start`)에서는 런타임이 -`.objectstack/data/uploads/` 아래에 로컬 스토리지를 자동으로 구성합니다. -루트 디렉터리는 `OS_STORAGE_ROOT` 환경 변수로 재정의할 수 있습니다. - -**프로덕션 적합성은 배포 형태에 따라 달라집니다:** - -- ✅ 데스크톱 앱, 단일 노드 내부 도구, 엣지 / 온프레미스 - 어플라이언스 — `uploads/` 디렉터리가 파일 시스템 백업에 포함되어 있는 한 - (또는 데스크톱 앱의 경우 사용자가 관리하는 동기화 폴더에 위치하는 한) - 로컬 스토리지로 충분합니다. -- ❌ 멀티 노드, 멀티 AZ, 또는 리전 간 내구성이 필요한 경우 — - S3 호환 스토리지를 사용하세요. - -## S3 호환 (프로덕션) - -적합한 용도: 프로덕션, 멀티 노드, 내구성 + 수명 주기 관리. - -```bash -pnpm add @aws-sdk/client-s3 @aws-sdk/s3-request-presigner -``` - -```ts -import { StorageServicePlugin } from '@objectstack/service-storage'; - -new StorageServicePlugin({ - adapter: 's3', - s3: { - bucket: 'my-bucket', - region: 'us-east-1', - // omit credentials to use the AWS SDK's default chain - // (env, ~/.aws, IAM role) - }, -}); -``` - -AWS SDK는 일반적인 체인에서 자격 증명을 읽습니다: - -| 소스 | 환경 변수 | -|---|---| -| 표준 환경 변수 | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION` | -| 세션 토큰 | `AWS_SESSION_TOKEN` | -| 공유 구성 | `~/.aws/credentials`, `AWS_PROFILE` | -| IAM 역할 | EC2 / ECS / EKS / Lambda에서 자동 — 구성 불필요 | - -### Cloudflare R2 - -```ts -new StorageServicePlugin({ - adapter: 's3', - s3: { - bucket: 'my-bucket', - region: 'auto', - endpoint: 'https://.r2.cloudflarestorage.com', - forcePathStyle: false, - }, -}); -``` - -자격 증명: R2 액세스 키 ID + 시크릿으로, 표준 `AWS_*` -환경 변수나 시크릿 관리자를 통해 전달합니다. - -### MinIO (자체 호스팅) - -```ts -new StorageServicePlugin({ - adapter: 's3', - s3: { - bucket: 'my-bucket', - region: 'us-east-1', - endpoint: 'http://minio.internal:9000', - forcePathStyle: true, - }, -}); -``` - -### DigitalOcean Spaces - -```ts -new StorageServicePlugin({ - adapter: 's3', - s3: { - bucket: 'my-bucket', - region: 'nyc3', - endpoint: 'https://nyc3.digitaloceanspaces.com', - forcePathStyle: false, - }, -}); -``` - -### S3 버킷 정책 - -스토리지는 presigned PUT/GET URL을 사용합니다. 권장 버킷 정책: - -- 모든 퍼블릭 액세스 차단. -- CORS: ObjectOS 호스트명에서의 `PUT`/`GET` 허용. -- 수명 주기: 미완료 멀티파트 업로드는 1~7일 후 만료; `temp=true` 태그가 - 지정된 객체는 24시간 후 만료. -- 버전 관리 + Object Lock: 선택 사항이며, 규정 준수 배포에 권장됩니다. - -## REST 인터페이스 - -`@objectstack/client`가 이를 호출하므로 — 일반적으로 직접 호출할 필요는 없습니다: - -| 메서드 | 경로 | 용도 | -|---|---|---| -| POST | `/api/v1/storage/upload/presigned` | presigned 업로드 URL 가져오기 | -| POST | `/api/v1/storage/upload/complete` | 완료된 업로드 커밋 | -| POST | `/api/v1/storage/upload/chunked` | 청크 업로드 시작 | -| PUT | `/api/v1/storage/upload/chunked/:uploadId/chunk/:i` | 청크 업로드 | -| POST | `/api/v1/storage/upload/chunked/:uploadId/complete` | 청크 업로드 완료 | -| GET | `/api/v1/storage/upload/chunked/:uploadId/progress` | 진행 상황 폴링 | -| GET | `/api/v1/storage/files/:fileId/url` | presigned 다운로드 URL 가져오기 | - -파일별 권한 부여는 보안 플러그인의 권한 평가기가 `sys_file` 객체를 대상으로 -처리하므로 — 별도의 스토리지 계층 ACL이 필요하지 않습니다. - -## 실시간 구성 - -설정 서비스가 활성화되어 있으면(기본적으로 활성화됨), 관리자는 -재시작 없이 **Console → Configuration → Storage**에서 스토리지 어댑터를 -교체할 수 있습니다: - -- 어댑터, 버킷, 리전, 엔드포인트 선택; -- 자격 증명 붙여넣기(`sys_setting`에 저장 시 암호화됨); -- 저장하기 전에 **Test connection** 클릭. - -변경 사항은 다음 요청부터 적용됩니다 — 재시작이 필요 없습니다. - -## 사이징 - -| 리소스 | 기본값 | 조정 가능 여부 | -|---|---|---| -| Presigned URL TTL | 1시간 | `presignedTtl` 플러그인 옵션 | -| 청크 업로드 세션 TTL | 24시간 | `sessionTtl` 플러그인 옵션 | -| 최대 단일 파트 업로드 | 백엔드 제한 (S3 = 5 GB) | — | -| 최대 청크 업로드 | 백엔드 제한 (S3 = 5 TB) | — | - -## 다음 단계 - -- [System settings](/docs/configure/system-settings) — 실시간 - 구성 및 스토리지 교체에 사용되는 설정 서비스 -- [Production Readiness](/docs/operate/production) — 객체 스토리지 - 내구성 및 백업을 포함하는 체크리스트 -- [`@objectstack/service-storage` on GitHub](https://github.com/objectstack-ai/objectstack/tree/main/packages/services/service-storage) — 소스 및 전체 옵션 참조 diff --git a/content/docs/configure/system-settings.de.mdx b/content/docs/configure/system-settings.de.mdx deleted file mode 100644 index 41456c3e..00000000 --- a/content/docs/configure/system-settings.de.mdx +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: Systemeinstellungen -description: Konfigurieren Sie Mandanten- und Benutzereinstellungen über Manifeste und einen gemeinsamen K/V-Speicher. -translation: - source_sha: 1afa5ad1338dfcd2fe2139176d52b73679507a78ffc3c169f38620a87c6c59ac - guide_rev: 1 - mode: auto ---- - -ObjectStack enthält einen Einstellungsdienst für Laufzeit- und Plugin-Einstellungen. -ObjectOS stellt diese Einstellungen über die Console bereit, wenn das -Anwendungsartefakt die Einstellungsfähigkeit erfordert. - -## Einstellungsmodell - -Einstellungen werden per Code deklariert und als Werte gespeichert: - -| Ebene | Zweck | -|---|---| -| Settings Manifest | Definiert Felder, Beschriftungen, Standardwerte, Validierung, Sichtbarkeit und Aktionen | -| `sys_setting` | Speichert Mandanten-/Benutzer-K/V-Werte | -| Resolver | Liest den effektiven Wert | -| Console UI | Rendert standardisierte Einstellungsseiten | - -Plugins sollten für die übliche Konfiguration keine einmaligen -Einstellungstabellen erstellen. Sie sollten Einstellungsmanifeste deklarieren -und ObjectOS die Werte konsistent rendern und speichern lassen. - -## Auflösungsreihenfolge - -Jede Einstellung deklariert einen Geltungsbereich (`global`, `tenant` oder -`user`). Der Resolver durchläuft die Kaskade von der höchsten zur niedrigsten -Priorität, und der erste gesetzte Wert gewinnt: - -```text -Environment override (locked) -Global setting -Tenant setting -User setting -Manifest default -``` - -Umgebungs-Overrides sind gesperrt. Wird ein Wert über eine Umgebungsvariable -gesetzt, zeigt die Console UI ihn als vom Host verwaltet an und lehnt -Laufzeitänderungen ab. Ein gesperrter Wert an einer beliebigen Stelle weiter -oben in der Kette sperrt auch den effektiven Wert, sodass niedrigere -Geltungsbereiche ihn nicht überschreiben können. - -## Häufige Einstellungsbereiche - -Kundenseitige Einstellungen umfassen üblicherweise: - -| Bereich | Beispiele | -|---|---| -| E-Mail | SMTP-Host, Anbieter-API-Schlüssel, Absenderadresse, Test-E-Mail | -| Branding | Produktname, Logo-URL, Akzentfarbe, Standardthema | -| Feature-Flags | Funktionsschalter auf Mandantenebene | -| Speicher | Lokales Dateisystem oder Objektspeicher-Anmeldedaten | -| KI-Anbieter | Modellanbieter, API-Schlüssel, Budgetgrenzen | -| SSO | OIDC-Anbietereinstellungen und Verbindungstest | - -## Geheimnisse - -Passwort- und Anmeldedatenfelder sollten vom Einstellungsdienst verschlüsselt -oder als umgebungsverwaltete Werte bereitgestellt werden. Wenn ein -Secret-Provider konfiguriert ist, speichert der Einstellungsdienst den -Chiffretext in `sys_secret` und behält nur einen Handle in `sys_setting`. -Speichern Sie keine Geheimnisse in Artefakten, Compose-Dateien oder Git. - -## Testaktionen - -Einstellungsmanifeste können standardisierte Aktionsschaltflächen deklarieren, -zum Beispiel: - -- Test-E-Mail senden; -- SSO-Discovery testen; -- Objektspeicher-Anmeldedaten überprüfen; -- Webhook-Ziel validieren. - -Verwenden Sie diese Aktionen für Kunden-Setup-Abläufe, anstatt Betreiber -zu bitten, zuerst die Logs zu prüfen. - -## Verwandt - -Mehrere Einstellungsbereiche verfügen über eigene Konfigurationsanleitungen: - -- [E-Mail](/docs/configure/email) -- [Speicher](/docs/configure/storage) -- [KI-Anbieter](/docs/configure/ai) -- [Authentifizierung und SSO](/docs/configure/authentication) -- [Laufzeit](/docs/configure/runtime) diff --git a/content/docs/configure/system-settings.es.mdx b/content/docs/configure/system-settings.es.mdx deleted file mode 100644 index f75313fd..00000000 --- a/content/docs/configure/system-settings.es.mdx +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: Configuración del sistema -description: Configura los ajustes de tenant y de usuario mediante manifiestos y un almacén K/V compartido. -translation: - source_sha: 1afa5ad1338dfcd2fe2139176d52b73679507a78ffc3c169f38620a87c6c59ac - guide_rev: 1 - mode: auto ---- - -ObjectStack incluye un servicio de configuración para los ajustes de runtime y de plugins. -ObjectOS expone esos ajustes a través de la Console cuando el artefacto de la -aplicación requiere la capacidad de configuración. - -## Modelo de configuración - -Los ajustes se declaran mediante código y se almacenan como valores: - -| Capa | Propósito | -|---|---| -| Manifiesto de configuración | Define campos, etiquetas, valores predeterminados, validación, visibilidad y acciones | -| `sys_setting` | Almacena los valores K/V de tenant/usuario | -| Resolver | Lee el valor efectivo | -| Console UI | Renderiza las páginas de configuración estándar | - -Los plugins no deben crear tablas de configuración puntuales para -ajustes ordinarios. Deben declarar manifiestos de configuración y dejar que ObjectOS -renderice y almacene los valores de forma coherente. - -## Orden de resolución - -Cada ajuste declara un alcance (`global`, `tenant` o `user`). El -resolver recorre la cascada desde la mayor hasta la menor precedencia y el -primer valor establecido prevalece: - -```text -Environment override (locked) -Global setting -Tenant setting -User setting -Manifest default -``` - -Las anulaciones de entorno están bloqueadas. Si un valor se establece mediante una -variable de entorno, la Console UI lo muestra como gestionado por el host -y rechaza las ediciones en runtime. Un valor bloqueado en cualquier punto superior de la cadena también -bloquea el valor efectivo, de modo que los alcances inferiores no pueden ocultarlo. - -## Áreas de configuración comunes - -Los ajustes orientados al cliente suelen incluir: - -| Área | Ejemplos | -|---|---| -| Email | Host SMTP, clave de API del proveedor, dirección de remitente, correo de prueba | -| Branding | Nombre del producto, URL del logotipo, color de acento, tema predeterminado | -| Feature flags | Interruptores de funcionalidades a nivel de tenant | -| Storage | Credenciales de sistema de archivos local o de almacenamiento de objetos | -| Proveedores de IA | Proveedor del modelo, clave de API, límites de presupuesto | -| SSO | Ajustes del proveedor OIDC y prueba de conexión | - -## Secretos - -Los campos de contraseñas y credenciales deben cifrarse mediante el servicio de -configuración o proporcionarse como valores gestionados por el entorno. Cuando se configura un -proveedor de secretos, el servicio de configuración almacena el texto cifrado en -`sys_secret` y conserva únicamente un identificador en `sys_setting`. No almacenes -secretos en artefactos, archivos de compose ni Git. - -## Acciones de prueba - -Los manifiestos de configuración pueden declarar botones de acción estándar, como: - -- enviar correo de prueba; -- probar el descubrimiento de SSO; -- verificar las credenciales de almacenamiento de objetos; -- validar el destino de un webhook. - -Utiliza estas acciones para los flujos de configuración del cliente en lugar de pedir a los operadores -que inspeccionen primero los logs. - -## Relacionado - -Varias áreas de configuración tienen guías de configuración dedicadas: - -- [Email](/docs/configure/email) -- [Storage](/docs/configure/storage) -- [Proveedores de IA](/docs/configure/ai) -- [Autenticación y SSO](/docs/configure/authentication) -- [Runtime](/docs/configure/runtime) diff --git a/content/docs/configure/system-settings.fr.mdx b/content/docs/configure/system-settings.fr.mdx deleted file mode 100644 index bea0b789..00000000 --- a/content/docs/configure/system-settings.fr.mdx +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: Paramètres système -description: Configurez les paramètres de tenant et d'utilisateur à l'aide de manifestes et d'un magasin clé/valeur partagé. -translation: - source_sha: 1afa5ad1338dfcd2fe2139176d52b73679507a78ffc3c169f38620a87c6c59ac - guide_rev: 1 - mode: auto ---- - -ObjectStack inclut un service de paramètres pour les paramètres d'exécution et de plugins. -ObjectOS expose ces paramètres via la Console lorsque l'artefact -applicatif requiert la capacité de paramètres. - -## Modèle de paramètres - -Les paramètres sont déclarés par le code et stockés sous forme de valeurs : - -| Couche | Objectif | -|---|---| -| Manifeste de paramètres | Définit les champs, libellés, valeurs par défaut, validations, visibilité et actions | -| `sys_setting` | Stocke les valeurs K/V de tenant/utilisateur | -| Résolveur | Lit la valeur effective | -| Interface de la Console | Affiche les pages de paramètres standard | - -Les plugins ne devraient pas créer de tables de paramètres ponctuelles pour -la configuration ordinaire. Ils devraient déclarer des manifestes de paramètres et laisser ObjectOS -afficher et stocker les valeurs de manière cohérente. - -## Ordre de résolution - -Chaque paramètre déclare une portée (`global`, `tenant` ou `user`). Le -résolveur parcourt la cascade de la priorité la plus élevée à la plus basse, et la -première valeur définie l'emporte : - -```text -Environment override (locked) -Global setting -Tenant setting -User setting -Manifest default -``` - -Les surcharges d'environnement sont verrouillées. Si une valeur est définie via une -variable d'environnement, l'interface de la Console l'affiche comme gérée par l'hôte -et rejette les modifications à l'exécution. Une valeur verrouillée à n'importe quel niveau supérieur de la chaîne -verrouille également la valeur effective, de sorte que les portées inférieures ne peuvent pas la masquer. - -## Domaines de paramètres courants - -Les paramètres destinés aux clients incluent généralement : - -| Domaine | Exemples | -|---|---| -| Email | Hôte SMTP, clé API du fournisseur, adresse d'expéditeur, email de test | -| Image de marque | Nom du produit, URL du logo, couleur d'accentuation, thème par défaut | -| Indicateurs de fonctionnalités | Commutateurs de fonctionnalités au niveau du tenant | -| Stockage | Système de fichiers local ou identifiants de stockage d'objets | -| Fournisseurs d'IA | Fournisseur de modèle, clé API, limites de budget | -| SSO | Paramètres du fournisseur OIDC et test de connexion | - -## Secrets - -Les champs de mot de passe et d'identifiants devraient être chiffrés par le service -de paramètres ou fournis sous forme de valeurs gérées par l'environnement. Lorsqu'un fournisseur -de secrets est configuré, le service de paramètres stocke le texte chiffré dans -`sys_secret` et ne conserve qu'une référence dans `sys_setting`. Ne stockez pas -de secrets dans des artefacts, des fichiers compose ou Git. - -## Actions de test - -Les manifestes de paramètres peuvent déclarer des boutons d'action standard, tels que : - -- envoyer un email de test ; -- tester la découverte SSO ; -- vérifier les identifiants de stockage d'objets ; -- valider la cible d'un webhook. - -Utilisez ces actions pour les flux de configuration des clients plutôt que de demander aux opérateurs -d'inspecter d'abord les journaux. - -## Connexes - -Plusieurs domaines de paramètres disposent de guides de configuration dédiés : - -- [Email](/docs/configure/email) -- [Stockage](/docs/configure/storage) -- [Fournisseurs d'IA](/docs/configure/ai) -- [Authentification et SSO](/docs/configure/authentication) -- [Exécution](/docs/configure/runtime) diff --git a/content/docs/configure/system-settings.ja.mdx b/content/docs/configure/system-settings.ja.mdx deleted file mode 100644 index 0154bcf8..00000000 --- a/content/docs/configure/system-settings.ja.mdx +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: システム設定 -description: マニフェストと共有 K/V ストアを通じて、テナントおよびユーザーの設定を構成します。 -translation: - source_sha: 1afa5ad1338dfcd2fe2139176d52b73679507a78ffc3c169f38620a87c6c59ac - guide_rev: 1 - mode: auto ---- - -ObjectStack には、ランタイムおよびプラグインの設定を扱う設定サービスが含まれています。 -ObjectOS は、アプリケーションアーティファクトが設定機能を必要とする場合に、 -それらの設定を Console を通じて公開します。 - -## 設定モデル - -設定はコードによって宣言され、値として保存されます。 - -| レイヤー | 目的 | -|---|---| -| Settings Manifest | フィールド、ラベル、デフォルト値、検証、表示/非表示、アクションを定義します | -| `sys_setting` | テナント/ユーザーの K/V 値を保存します | -| Resolver | 有効な値を読み取ります | -| Console UI | 標準の設定ページをレンダリングします | - -プラグインは、通常の構成のために一回限りの設定テーブルを作成すべきではありません。 -設定マニフェストを宣言し、ObjectOS に値のレンダリングと保存を -一貫して任せるべきです。 - -## 解決順序 - -各設定はスコープ（`global`、`tenant`、または `user`）を宣言します。 -リゾルバは優先度の高いものから低いものへとカスケードをたどり、 -最初に設定されている値が採用されます。 - -```text -Environment override (locked) -Global setting -Tenant setting -User setting -Manifest default -``` - -環境オーバーライドはロックされています。値が環境変数を通じて設定されている場合、 -Console UI はそれをホストによって管理されていると表示し、ランタイムでの編集を -拒否します。チェーンの上位のいずれかでロックされた値があると、有効な値も -ロックされるため、下位のスコープはそれを上書きできません。 - -## 一般的な設定領域 - -顧客向けの設定には通常、以下が含まれます。 - -| 領域 | 例 | -|---|---| -| Email | SMTP ホスト、プロバイダー API キー、送信元アドレス、テストメール | -| Branding | 製品名、ロゴ URL、アクセントカラー、デフォルトテーマ | -| Feature flags | テナントレベルの機能スイッチ | -| Storage | ローカルファイルシステムまたはオブジェクトストレージの認証情報 | -| AI providers | モデルプロバイダー、API キー、予算上限 | -| SSO | OIDC プロバイダー設定および接続テスト | - -## シークレット - -パスワードや認証情報のフィールドは、設定サービスによって暗号化されるか、 -環境管理された値として提供されるべきです。シークレットプロバイダーが構成されている場合、 -設定サービスは暗号文を `sys_secret` に保存し、`sys_setting` にはハンドルのみを -保持します。シークレットをアーティファクト、compose ファイル、または Git に -保存しないでください。 - -## テストアクション - -設定マニフェストでは、次のような標準のアクションボタンを宣言できます。 - -- テストメールを送信する -- SSO ディスカバリをテストする -- オブジェクトストレージの認証情報を検証する -- webhook ターゲットを検証する - -オペレーターに最初にログを確認させるのではなく、顧客のセットアップフローには -これらのアクションを使用してください。 - -## 関連項目 - -いくつかの設定領域には専用の構成ガイドがあります。 - -- [Email](/docs/configure/email) -- [Storage](/docs/configure/storage) -- [AI providers](/docs/configure/ai) -- [Authentication and SSO](/docs/configure/authentication) -- [Runtime](/docs/configure/runtime) diff --git a/content/docs/configure/system-settings.ko.mdx b/content/docs/configure/system-settings.ko.mdx deleted file mode 100644 index f4658a67..00000000 --- a/content/docs/configure/system-settings.ko.mdx +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: 시스템 설정 -description: 매니페스트와 공유 K/V 스토어를 통해 테넌트 및 사용자 설정을 구성합니다. -translation: - source_sha: 1afa5ad1338dfcd2fe2139176d52b73679507a78ffc3c169f38620a87c6c59ac - guide_rev: 1 - mode: auto ---- - -ObjectStack에는 런타임 및 플러그인 설정을 위한 설정 서비스가 포함되어 -있습니다. ObjectOS는 애플리케이션 아티팩트가 설정 기능을 요구할 때 -Console을 통해 이러한 설정을 노출합니다. - -## 설정 모델 - -설정은 코드로 선언되며 값으로 저장됩니다. - -| 계층 | 목적 | -|---|---| -| 설정 매니페스트 | 필드, 레이블, 기본값, 검증, 가시성, 액션을 정의 | -| `sys_setting` | 테넌트/사용자 K/V 값을 저장 | -| 리졸버 | 유효 값을 읽음 | -| Console UI | 표준 설정 페이지를 렌더링 | - -플러그인은 일반적인 구성을 위해 일회성 설정 테이블을 만들어서는 안 -됩니다. 설정 매니페스트를 선언하고 ObjectOS가 값을 일관되게 -렌더링하고 저장하도록 해야 합니다. - -## 해석 순서 - -각 설정은 범위(`global`, `tenant`, 또는 `user`)를 선언합니다. -리졸버는 우선순위가 가장 높은 것부터 낮은 것까지 캐스케이드를 -따라가며, 설정된 첫 번째 값이 우선합니다. - -```text -Environment override (locked) -Global setting -Tenant setting -User setting -Manifest default -``` - -환경 재정의는 잠겨 있습니다. 값이 환경 변수를 통해 설정되면 Console -UI는 이를 호스트에 의해 관리되는 것으로 표시하고 런타임 편집을 -거부합니다. 체인 상단의 잠긴 값은 유효 값도 잠그므로, 하위 범위가 -이를 가릴 수 없습니다. - -## 일반적인 설정 영역 - -고객 대상 설정에는 일반적으로 다음이 포함됩니다. - -| 영역 | 예시 | -|---|---| -| Email | SMTP 호스트, 제공업체 API 키, 발신 주소, 테스트 이메일 | -| Branding | 제품명, 로고 URL, 강조 색상, 기본 테마 | -| Feature flags | 테넌트 수준 기능 스위치 | -| Storage | 로컬 파일 시스템 또는 객체 스토리지 자격 증명 | -| AI providers | 모델 제공업체, API 키, 예산 한도 | -| SSO | OIDC 제공업체 설정 및 연결 테스트 | - -## 시크릿 - -비밀번호 및 자격 증명 필드는 설정 서비스에 의해 암호화되거나 환경 -관리 값으로 제공되어야 합니다. 시크릿 제공자가 구성되면 설정 -서비스는 암호문을 `sys_secret`에 저장하고 `sys_setting`에는 핸들만 -보관합니다. 시크릿을 아티팩트, compose 파일 또는 Git에 저장하지 -마십시오. - -## 테스트 액션 - -설정 매니페스트는 다음과 같은 표준 액션 버튼을 선언할 수 있습니다. - -- 테스트 이메일 전송; -- SSO 디스커버리 테스트; -- 객체 스토리지 자격 증명 확인; -- 웹훅 대상 검증. - -운영자에게 먼저 로그를 검사하도록 요청하는 대신, 고객 설정 -플로우에 이러한 액션을 사용하십시오. - -## 관련 항목 - -여러 설정 영역에는 전용 구성 가이드가 있습니다. - -- [Email](/docs/configure/email) -- [Storage](/docs/configure/storage) -- [AI providers](/docs/configure/ai) -- [Authentication and SSO](/docs/configure/authentication) -- [Runtime](/docs/configure/runtime) diff --git a/content/docs/configure/webhooks.de.mdx b/content/docs/configure/webhooks.de.mdx deleted file mode 100644 index 19ef112d..00000000 --- a/content/docs/configure/webhooks.de.mdx +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: Webhooks -description: Ausgehende Webhook-Zustellung, Signierung und erneute Zustellversuche. -translation: - source_sha: 2340439a0cc171b6947e5e3bafdfa52f4dc5420de43807d081095feb9bd0b33e - guide_rev: 1 - mode: auto ---- - -ObjectOS verwendet ein persistentes **Outbox**-Modell für ausgehende -Webhooks. Wenn das Webhook-Plugin aktiviert ist, reihen -Geschäftsänderungen eine Zustellungszeile in die Warteschlange ein, und -ein Hintergrund-Dispatcher stellt sie mit erneuten Versuchen zu — sodass -ein langsamer oder nicht verfügbarer Empfänger niemals die auslösende -Transaktion blockiert. - -## Webhooks aktivieren - -Webhooks sind eine optionale Funktion. Das bereitgestellte ObjectOS-Image -muss `@objectstack/plugin-webhooks` enthalten, und das Anwendungsartefakt -muss Webhook-Abonnements registrieren (typischerweise als Datensätze -eines `sys_webhook`-Objekts). - -Wenn aktiviert, erscheinen zwei Objekte in der Console: - -| Objekt | Zweck | -|---|---| -| `sys_webhook` | Webhook-Abonnement (Ziel-URL, Ereignisfilter, Secret, Status) | -| `sys_webhook_delivery` | Zustellungsprotokoll (URL, Antwortcode, Anzahl der Versuche, Zeitstempel des erneuten Versuchs) | - -## Zustellungssemantik - -- **At-least-once.** Eine Zustellung kann nach einem vorübergehenden - Fehler erneut versucht werden; Empfänger müssen idempotent sein. -- **Persistent.** Zustellungen überstehen ObjectOS-Neustarts, da sie in - der Geschäftsdatenbank gespeichert sind. -- **Partitioniert.** Jeder Dispatcher-Worker beansprucht eine Partition - der Outbox, sodass Deployments den Versand horizontal skalieren können, - ohne doppelte Zustellung. -- **Begrenzte erneute Versuche.** Fehlgeschlagene Zustellungen werden mit - Backoff bis zu einer konfigurierbaren Obergrenze erneut versucht; - erschöpfte Zeilen verbleiben zur Inspektion in `sys_webhook_delivery`. - -## Signierung - -Jede Zustellung trägt identifizierende Header, damit Empfänger sie -weiterleiten, deduplizieren und verifizieren können: - -```text -X-Objectstack-Event: -X-Objectstack-Delivery: -X-Objectstack-Attempt: -``` - -Wenn ein Webhook-Abonnement über ein `secret` verfügt, signiert ObjectOS -außerdem jede Anfrage: - -```text -X-Objectstack-Signature: sha256= -``` - -Die Signatur ist `HMAC-SHA256(secret, body)`, berechnet über den rohen -Anfragetext. Verifizieren Sie sie auf dem Empfänger, bevor Sie der -Nutzlast vertrauen: - -```js -import { createHmac, timingSafeEqual } from 'node:crypto'; - -function verify(body, signatureHeader, secret) { - const expected = 'sha256=' + createHmac('sha256', secret).update(body).digest('hex'); - return timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected)); -} -``` - -Rotieren Sie Secrets, indem Sie ein neues Abonnement mit dem neuen Secret -ausstellen, beide für ein Übergangsfenster betreiben und dann das alte -deaktivieren. - -## Erwartungen an den Empfänger - -- Antworten Sie innerhalb weniger Sekunden mit `2xx`. Eine Antwort mit - `408`, `429` oder `5xx` (oder ein Timeout-/Transportfehler) ist erneut - versuchbar und wird mit Backoff erneut versucht. Jedes andere `4xx` - wird als dauerhafter Fehler behandelt und ohne weitere erneute Versuche - auf `dead` gesetzt. -- Der Dispatcher markiert eine Zustellung erst dann als erfolgreich, wenn - er ein `2xx` sieht, sodass ein fehlgeschlagener Empfänger die Zeile zur - Inspektion oder erneuten Zustellung in `sys_webhook_delivery` behält. -- Seien Sie idempotent — deduplizieren Sie anhand des - `X-Objectstack-Delivery`-Headers (der Zustellungs-ID) oder Ihrer eigenen - Ereignis-ID in der Nutzlast. - -## Fehlerbehandlung - -Wenn etwas fehlschlägt: - -1. Prüfen Sie `sys_webhook_delivery` auf die Zeile — `status`, - `response_code`, `response_body` und `attempts` werden aufgezeichnet. -2. Bestätigen Sie den ausgehenden Netzwerkzugriff von ObjectOS zum - Empfänger. -3. Wenn der Empfänger dauerhaft geändert wurde, aktualisieren Sie die - Abonnement-URL und stellen Sie die Zeile aus der Console erneut zu. -4. Für die Vorfallüberprüfung erfassen Audit-Logs (`sys_audit_log`) - Abonnementbearbeitungen, aber keine Nutzlasten — Nutzlasten verbleiben - in der Outbox. - -## Betriebstipps - -- Platzieren Sie keine Secrets in Webhook-URLs (Query-Strings werden - protokolliert). -- Verwenden Sie einen dedizierten Empfänger-Hostnamen, damit Sie Last - abwerfen können, indem Sie ihn am Edge blockieren, ohne die - Hauptanwendung zu beeinträchtigen. -- Beobachten Sie die Dispatcher-Latenz — eine wachsende Outbox bedeutet - in der Regel, dass der Empfänger beeinträchtigt ist. diff --git a/content/docs/configure/webhooks.es.mdx b/content/docs/configure/webhooks.es.mdx deleted file mode 100644 index 270c5f94..00000000 --- a/content/docs/configure/webhooks.es.mdx +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: Webhooks -description: Entrega, firma y reintentos de webhooks salientes. -translation: - source_sha: 2340439a0cc171b6947e5e3bafdfa52f4dc5420de43807d081095feb9bd0b33e - guide_rev: 1 - mode: auto ---- - -ObjectOS utiliza un modelo de **outbox** persistente para los webhooks -salientes. Cuando el plugin de webhooks está habilitado, los cambios de -negocio encolan una fila de entrega y un despachador en segundo plano la -entrega con reintentos, de modo que un receptor lento o no disponible -nunca bloquea la transacción de origen. - -## Habilitar webhooks - -Los webhooks son una capacidad opcional. La imagen de ObjectOS desplegada -debe incluir `@objectstack/plugin-webhooks`, y el artefacto de la -aplicación debe registrar las suscripciones de webhook (normalmente como -registros de un objeto `sys_webhook`). - -Cuando están habilitados, aparecen dos objetos en la Console: - -| Objeto | Propósito | -|---|---| -| `sys_webhook` | Suscripción de webhook (URL de destino, filtro de eventos, secreto, estado) | -| `sys_webhook_delivery` | Registro de entrega (URL, código de respuesta, número de intentos, marca de tiempo de reintento) | - -## Semántica de entrega - -- **Al menos una vez.** Una entrega puede reintentarse tras un fallo - transitorio; los receptores deben ser idempotentes. -- **Persistente.** Las entregas sobreviven a los reinicios de ObjectOS - porque se almacenan en la base de datos de negocio. -- **Particionada.** Cada worker del despachador reclama una partición del - outbox para que los despliegues puedan escalar horizontalmente el - despacho sin entregas duplicadas. -- **Reintentos acotados.** Las entregas fallidas se reintentan con backoff - hasta un límite configurable; las filas agotadas permanecen en - `sys_webhook_delivery` para su inspección. - -## Firma - -Cada entrega lleva cabeceras de identificación para que los receptores -puedan enrutarla, deduplicarla y verificarla: - -```text -X-Objectstack-Event: -X-Objectstack-Delivery: -X-Objectstack-Attempt: -``` - -Cuando una suscripción de webhook tiene un `secret`, ObjectOS también -firma cada solicitud: - -```text -X-Objectstack-Signature: sha256= -``` - -La firma es `HMAC-SHA256(secret, body)` calculada sobre el cuerpo crudo de -la solicitud. Verifícala en el receptor antes de confiar en el payload: - -```js -import { createHmac, timingSafeEqual } from 'node:crypto'; - -function verify(body, signatureHeader, secret) { - const expected = 'sha256=' + createHmac('sha256', secret).update(body).digest('hex'); - return timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected)); -} -``` - -Rota los secretos emitiendo una nueva suscripción con el nuevo secreto, -ejecutando ambas durante una ventana de transición y deshabilitando luego -la antigua. - -## Expectativas del receptor - -- Responde con `2xx` en unos pocos segundos. Una respuesta `408`, `429` o - `5xx` (o un timeout/error de transporte) es reintentable y se reintenta - con backoff. Cualquier otro `4xx` se trata como un fallo permanente y se - mueve a `dead` sin más reintentos. -- El despachador **no** marca una entrega como exitosa hasta que ve un - `2xx`, por lo que un receptor fallido mantiene la fila en - `sys_webhook_delivery` para su inspección o reentrega. -- Sé idempotente: deduplica usando la cabecera `X-Objectstack-Delivery` (el - identificador de entrega) o tu propio identificador de evento en el - payload. - -## Manejo de fallos - -Cuando algo falla: - -1. Revisa la fila en `sys_webhook_delivery`: se registran `status`, - `response_code`, `response_body` y `attempts`. -2. Confirma el acceso de red saliente desde ObjectOS al receptor. -3. Si el receptor cambió de forma permanente, actualiza la URL de la - suscripción y reentrega la fila desde la Console. -4. Para la revisión de incidentes, los registros de auditoría - (`sys_audit_log`) capturan las ediciones de las suscripciones, pero no - los payloads; los payloads permanecen en el outbox. - -## Consejos operativos - -- No pongas secretos en las URLs de los webhooks (las cadenas de consulta - quedan registradas). -- Usa un nombre de host de receptor dedicado para poder descargar tráfico - bloqueándolo en el borde sin afectar a la aplicación principal. -- Vigila el retraso del despachador: un outbox que crece normalmente - significa que el receptor está degradado. diff --git a/content/docs/configure/webhooks.fr.mdx b/content/docs/configure/webhooks.fr.mdx deleted file mode 100644 index d6abacc9..00000000 --- a/content/docs/configure/webhooks.fr.mdx +++ /dev/null @@ -1,116 +0,0 @@ ---- -title: Webhooks -description: Livraison, signature et nouvelles tentatives des webhooks sortants. -translation: - source_sha: 2340439a0cc171b6947e5e3bafdfa52f4dc5420de43807d081095feb9bd0b33e - guide_rev: 1 - mode: auto ---- - -ObjectOS utilise un modèle d'**outbox** persistant pour les webhooks -sortants. Lorsque le plugin de webhooks est activé, les changements -métier mettent en file d'attente une ligne de livraison, et un -distributeur en arrière-plan la livre avec des nouvelles tentatives — -de sorte qu'un récepteur lent ou indisponible ne bloque jamais la -transaction d'origine. - -## Activer les webhooks - -Les webhooks sont une capacité optionnelle. L'image ObjectOS déployée -doit inclure `@objectstack/plugin-webhooks`, et l'artefact applicatif -doit enregistrer des abonnements de webhooks (généralement sous forme -d'enregistrements d'un objet `sys_webhook`). - -Une fois activés, deux objets apparaissent dans la Console : - -| Objet | Rôle | -|---|---| -| `sys_webhook` | Abonnement au webhook (URL cible, filtre d'événements, secret, statut) | -| `sys_webhook_delivery` | Journal de livraison (URL, code de réponse, nombre de tentatives, horodatage de la nouvelle tentative) | - -## Sémantique de livraison - -- **Au moins une fois.** Une livraison peut être retentée après un - échec transitoire ; les récepteurs doivent être idempotents. -- **Persistante.** Les livraisons survivent aux redémarrages d'ObjectOS - car elles sont stockées dans la base de données métier. -- **Partitionnée.** Chaque worker du distributeur revendique une - partition de l'outbox, de sorte que les déploiements peuvent mettre à - l'échelle horizontalement la distribution sans double livraison. -- **Nouvelles tentatives bornées.** Les livraisons échouées sont - retentées avec un délai progressif jusqu'à un plafond configurable ; - les lignes épuisées restent dans `sys_webhook_delivery` pour - inspection. - -## Signature - -Chaque livraison comporte des en-têtes d'identification afin que les -récepteurs puissent l'acheminer, la dédupliquer et la vérifier : - -```text -X-Objectstack-Event: -X-Objectstack-Delivery: -X-Objectstack-Attempt: -``` - -Lorsqu'un abonnement de webhook possède un `secret`, ObjectOS signe -également chaque requête : - -```text -X-Objectstack-Signature: sha256= -``` - -La signature est `HMAC-SHA256(secret, body)`, calculée sur le corps brut -de la requête. Vérifiez-la côté récepteur avant de faire confiance à la -charge utile : - -```js -import { createHmac, timingSafeEqual } from 'node:crypto'; - -function verify(body, signatureHeader, secret) { - const expected = 'sha256=' + createHmac('sha256', secret).update(body).digest('hex'); - return timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected)); -} -``` - -Faites tourner les secrets en créant un nouvel abonnement avec le -nouveau secret, en exécutant les deux pendant une fenêtre de transition, -puis en désactivant l'ancien. - -## Attentes côté récepteur - -- Répondez avec un `2xx` en quelques secondes. Une réponse `408`, `429` - ou `5xx` (ou un délai d'attente / une erreur de transport) est - retentable et donne lieu à une nouvelle tentative avec délai - progressif. Tout autre `4xx` est traité comme un échec permanent et - déplacé vers `dead` sans nouvelle tentative. -- Le distributeur ne marque **pas** une livraison comme réussie tant - qu'il ne reçoit pas un `2xx` ; ainsi, un récepteur défaillant conserve - la ligne dans `sys_webhook_delivery` pour inspection ou nouvelle - livraison. -- Soyez idempotent — dédupliquez sur l'en-tête `X-Objectstack-Delivery` - (l'identifiant de livraison) ou sur votre propre identifiant - d'événement dans la charge utile. - -## Gestion des échecs - -Lorsqu'une erreur survient : - -1. Consultez la ligne dans `sys_webhook_delivery` — `status`, - `response_code`, `response_body` et `attempts` y sont enregistrés. -2. Vérifiez l'accès réseau sortant d'ObjectOS vers le récepteur. -3. Si le récepteur a été modifié de façon permanente, mettez à jour - l'URL de l'abonnement et relivrez la ligne depuis la Console. -4. Pour l'analyse des incidents, les journaux d'audit - (`sys_audit_log`) capturent les modifications d'abonnement mais pas - les charges utiles — celles-ci restent dans l'outbox. - -## Conseils opérationnels - -- Ne placez pas de secrets dans les URL de webhook (les chaînes de - requête sont journalisées). -- Utilisez un nom d'hôte de récepteur dédié afin de pouvoir délester la - charge en le bloquant en périphérie sans affecter l'application - principale. -- Surveillez le retard du distributeur — un outbox qui grossit signifie - généralement que le récepteur est dégradé. diff --git a/content/docs/configure/webhooks.ja.mdx b/content/docs/configure/webhooks.ja.mdx deleted file mode 100644 index e8445d02..00000000 --- a/content/docs/configure/webhooks.ja.mdx +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: Webhooks -description: アウトバウンド Webhook の配信、署名、リトライ。 -translation: - source_sha: 2340439a0cc171b6947e5e3bafdfa52f4dc5420de43807d081095feb9bd0b33e - guide_rev: 1 - mode: auto ---- - -ObjectOS はアウトバウンド Webhook に永続的な **アウトボックス** モデルを -使用します。Webhook プラグインが有効になっている場合、業務上の変更によって -配信行がキューに追加され、バックグラウンドのディスパッチャーがリトライ付きで -配信します。これにより、受信側が遅延したり利用できなかったりしても、元の -トランザクションがブロックされることはありません。 - -## Webhook の有効化 - -Webhook はオプションの機能です。デプロイされた ObjectOS イメージに -`@objectstack/plugin-webhooks` が含まれている必要があり、アプリケーション -アーティファクトが Webhook サブスクリプション（通常は `sys_webhook` -オブジェクトのレコードとして）を登録する必要があります。 - -有効化すると、Console に 2 つのオブジェクトが表示されます。 - -| オブジェクト | 目的 | -|---|---| -| `sys_webhook` | Webhook サブスクリプション（ターゲット URL、イベントフィルター、シークレット、ステータス） | -| `sys_webhook_delivery` | 配信ログ（URL、レスポンスコード、試行回数、リトライのタイムスタンプ） | - -## 配信のセマンティクス - -- **At-least-once（最低 1 回）。** 一時的な障害の後に配信がリトライされる - ことがあります。受信側は冪等である必要があります。 -- **永続的。** 配信は業務データベースに保存されるため、ObjectOS の再起動後も - 保持されます。 -- **パーティション化。** 各ディスパッチャーワーカーはアウトボックスの - パーティションを取得するため、デプロイメントは二重配信なしで配信を水平 - スケールできます。 -- **リトライ回数の上限あり。** 失敗した配信は設定可能な上限までバックオフ - 付きでリトライされます。リトライを使い切った行は調査のために - `sys_webhook_delivery` に残ります。 - -## 署名 - -すべての配信には、受信側がルーティング、重複排除、検証できるように識別用の -ヘッダーが含まれます。 - -```text -X-Objectstack-Event: -X-Objectstack-Delivery: -X-Objectstack-Attempt: -``` - -Webhook サブスクリプションに `secret` が設定されている場合、ObjectOS は -すべてのリクエストにも署名します。 - -```text -X-Objectstack-Signature: sha256= -``` - -署名は、生のリクエストボディに対して計算された -`HMAC-SHA256(secret, body)` です。ペイロードを信頼する前に、受信側で検証 -してください。 - -```js -import { createHmac, timingSafeEqual } from 'node:crypto'; - -function verify(body, signatureHeader, secret) { - const expected = 'sha256=' + createHmac('sha256', secret).update(body).digest('hex'); - return timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected)); -} -``` - -シークレットをローテーションするには、新しいシークレットで新しい -サブスクリプションを発行し、移行期間中は両方を稼働させてから、古いものを -無効化します。 - -## 受信側に求められること - -- 数秒以内に `2xx` で応答してください。`408`、`429`、`5xx` のレスポンス - （またはタイムアウト／トランスポートエラー）はリトライ可能で、バックオフ - 付きでリトライされます。その他の `4xx` は永続的な障害として扱われ、 - それ以上のリトライなしで `dead` に移されます。 -- ディスパッチャーは `2xx` を確認するまで配信を成功とマークしません。 - そのため、受信に失敗すると、その行は調査または再配信のために - `sys_webhook_delivery` に残ります。 -- 冪等にしてください。`X-Objectstack-Delivery` ヘッダー（配信 ID）または - ペイロード内の独自のイベント ID で重複排除します。 - -## 障害への対処 - -何かが失敗した場合は次のとおりです。 - -1. `sys_webhook_delivery` で該当の行を確認します。`status`、 - `response_code`、`response_body`、`attempts` が記録されています。 -2. ObjectOS から受信側へのアウトバウンドネットワークアクセスを確認します。 -3. 受信側が恒久的に変更された場合は、サブスクリプションの URL を更新し、 - Console から行を再配信します。 -4. インシデントレビューのために、監査ログ（`sys_audit_log`）には - サブスクリプションの編集は記録されますが、ペイロードは記録されません。 - ペイロードはアウトボックスに残ります。 - -## 運用のヒント - -- Webhook URL にシークレットを入れないでください（クエリ文字列はログに - 記録されます）。 -- 専用の受信側ホスト名を使用すると、メインアプリに影響を与えることなく、 - エッジでブロックして負荷を切り離すことができます。 -- ディスパッチャーの遅延を監視してください。アウトボックスが増加し続ける - 場合、通常は受信側が劣化していることを意味します。 diff --git a/content/docs/configure/webhooks.ko.mdx b/content/docs/configure/webhooks.ko.mdx deleted file mode 100644 index 5e1aaa49..00000000 --- a/content/docs/configure/webhooks.ko.mdx +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: 웹훅 -description: 아웃바운드 웹훅 전달, 서명, 재시도. -translation: - source_sha: 2340439a0cc171b6947e5e3bafdfa52f4dc5420de43807d081095feb9bd0b33e - guide_rev: 1 - mode: auto ---- - -ObjectOS는 아웃바운드 웹훅을 위해 영구적인 **outbox** 모델을 사용합니다. -웹훅 플러그인이 활성화되면 비즈니스 변경 사항이 전달 행을 큐에 추가하고, -백그라운드 디스패처가 재시도와 함께 이를 전달합니다 — 따라서 느리거나 -응답하지 않는 수신자가 원래의 트랜잭션을 절대 차단하지 않습니다. - -## 웹훅 활성화 - -웹훅은 선택적 기능입니다. 배포된 ObjectOS 이미지에는 -`@objectstack/plugin-webhooks`가 포함되어야 하며, 애플리케이션 아티팩트는 -웹훅 구독을 등록해야 합니다(일반적으로 `sys_webhook` 객체의 레코드 형태). - -활성화되면 Console에 두 개의 객체가 나타납니다: - -| 객체 | 용도 | -|---|---| -| `sys_webhook` | 웹훅 구독(대상 URL, 이벤트 필터, 시크릿, 상태) | -| `sys_webhook_delivery` | 전달 로그(URL, 응답 코드, 시도 횟수, 재시도 타임스탬프) | - -## 전달 시맨틱 - -- **최소 한 번(At-least-once).** 일시적 실패 이후 전달이 재시도될 수 있으므로, - 수신자는 멱등성을 보장해야 합니다. -- **영구성(Persistent).** 전달 정보는 비즈니스 데이터베이스에 저장되므로 - ObjectOS 재시작 후에도 유지됩니다. -- **파티셔닝(Partitioned).** 각 디스패처 워커는 outbox의 파티션을 점유하므로, - 배포 환경에서 중복 전달 없이 디스패치를 수평으로 확장할 수 있습니다. -- **제한된 재시도(Bounded retries).** 실패한 전달은 구성 가능한 상한선까지 - 백오프와 함께 재시도되며, 소진된 행은 검사를 위해 `sys_webhook_delivery`에 - 남습니다. - -## 서명 - -모든 전달에는 수신자가 라우팅, 중복 제거, 검증할 수 있도록 식별 헤더가 -포함됩니다: - -```text -X-Objectstack-Event: -X-Objectstack-Delivery: -X-Objectstack-Attempt: -``` - -웹훅 구독에 `secret`이 있는 경우, ObjectOS는 모든 요청에 서명도 추가합니다: - -```text -X-Objectstack-Signature: sha256= -``` - -서명은 원시 요청 본문에 대해 계산된 `HMAC-SHA256(secret, body)`입니다. -페이로드를 신뢰하기 전에 수신자에서 이를 검증하십시오: - -```js -import { createHmac, timingSafeEqual } from 'node:crypto'; - -function verify(body, signatureHeader, secret) { - const expected = 'sha256=' + createHmac('sha256', secret).update(body).digest('hex'); - return timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected)); -} -``` - -시크릿을 교체하려면 새 시크릿으로 새 구독을 발급하고, 전환 기간 동안 두 -구독을 함께 실행한 다음, 이전 구독을 비활성화하십시오. - -## 수신자 기대 사항 - -- 몇 초 이내에 `2xx`로 응답하십시오. `408`, `429`, 또는 `5xx` 응답(또는 - 타임아웃/전송 오류)은 재시도 가능하며 백오프와 함께 재시도됩니다. 그 외의 - `4xx`는 영구적 실패로 처리되어 추가 재시도 없이 `dead` 상태로 이동됩니다. -- 디스패처는 `2xx`를 확인하기 전까지 전달을 성공으로 표시하지 **않으므로**, - 실패한 수신자의 행은 검사나 재전달을 위해 `sys_webhook_delivery`에 - 유지됩니다. -- 멱등성을 보장하십시오 — `X-Objectstack-Delivery` 헤더(전달 id) 또는 - 페이로드 내 자체 이벤트 id를 기준으로 중복을 제거하십시오. - -## 실패 처리 - -문제가 발생하면: - -1. 해당 행에 대해 `sys_webhook_delivery`를 확인하십시오 — `status`, - `response_code`, `response_body`, `attempts`가 기록됩니다. -2. ObjectOS에서 수신자로의 아웃바운드 네트워크 액세스를 확인하십시오. -3. 수신자가 영구적으로 변경된 경우, 구독 URL을 업데이트하고 Console에서 해당 - 행을 재전달하십시오. -4. 사고 검토 시, 감사 로그(`sys_audit_log`)는 구독 편집 사항을 기록하지만 - 페이로드는 기록하지 않습니다 — 페이로드는 outbox에 남습니다. - -## 운영 팁 - -- 웹훅 URL에 시크릿을 넣지 마십시오(쿼리 문자열은 로그에 기록됩니다). -- 전용 수신자 호스트네임을 사용하면 메인 앱에 영향을 주지 않고 엣지에서 - 차단하여 부하를 분산할 수 있습니다. -- 디스패처 지연을 모니터링하십시오 — outbox가 계속 증가하는 것은 보통 - 수신자가 성능 저하 상태임을 의미합니다.