diff --git a/content/docs/configure/data-sources.de.mdx b/content/docs/configure/data-sources.de.mdx deleted file mode 100644 index 9820a84..0000000 --- a/content/docs/configure/data-sources.de.mdx +++ /dev/null @@ -1,268 +0,0 @@ ---- -title: Datasources -description: "Verbinden Sie ObjectOS mit Ihren bestehenden Geschäftsdatenbanken, routen Sie Objekte dorthin und lassen Sie AI die Daten abfragen — nativ." -translation: - source_sha: c1e0954576877e1498f592a5b73c5848b9cefbfe3e27a962bd809d3b2db132b9 - guide_rev: 1 - mode: auto ---- - -Eine **Datasource** ist eine benannte Verbindung zu einem externen -Datenspeicher. Indem Sie Datasources deklarieren, richten Sie ObjectOS auf -die Datenbanken aus, mit denen Ihr Unternehmen bereits arbeitet — ein -produktives PostgreSQL, ein Reporting-MySQL-Replikat, ein -MongoDB-Cluster — und binden dann Objekte daran. Sobald ein Objekt -gebunden ist, arbeitet alles andere in der Plattform (die -REST-/GraphQL-API, Berechtigungen, Flows, Dashboards und **AI-Agents**) -einheitlich gegen diese Daten, ohne sich darum zu kümmern, wo die Zeilen -physisch liegen. - -Dies ist einer der praktischsten Einführungspfade von ObjectOS: Statt ein -Legacy-System zu migrieren, verbinden Sie sich damit, modellieren die -Tabellen, die Sie interessieren, als Objekte und **erweitern es um -AI-native Fähigkeiten** — Chat, Analyse, Automatisierung — auf Daten, die -genau dort bleiben, wo sie sind. - -## Was eine Datasource ist - -Jede Datasource ist ein einfaches Objekt, das von `DatasourceSchema` -validiert wird. Die Kernfelder: - -| Feld | Zweck | -|---|---| -| `name` | Eindeutiger Bezeichner (`^[a-z_][a-z0-9_]*$`), den Objekte referenzieren | -| `label` | Menschenlesbarer Anzeigename | -| `driver` | Welcher Treiber die Verbindung verwaltet (`postgres`, `mysql`, `sqlite`, `mongodb`, `memory` oder ein per Plugin beigesteuerter Treiber) | -| `config` | Treiberspezifische Verbindungseinstellungen (Host, Datenbank, Anmeldedaten, …) | -| `pool` | Dimensionierung des Verbindungspools (`min`, `max`, Timeouts) | -| `readReplicas` | Optionale schreibgeschützte Replikat-Konfigurationen | -| `capabilities` | Überschreiben, was der Treiber als push-down-fähig ausweist | -| `healthCheck` | Intervall/Timeout der Liveness-Prüfung | -| `active` | Ob die Verbindung aktiviert ist | - -Die mitgelieferten Treiber sind: - -| Treiber-Paket | `driver` | Backends | -|---|---|---| -| `@objectstack/driver-sql` | `postgres`, `mysql`, `sqlite` | PostgreSQL, MySQL, SQLite (über knex) | -| `@objectstack/driver-mongodb` | `mongodb` | MongoDB | -| `@objectstack/driver-memory` | `memory` | In-Process (Tests, Demos) | -| `@objectstack/driver-sqlite-wasm` | `sqlite` (WASM) | SQLite in WebContainers / Browser | - -## Datasources deklarieren - -Datasources werden im Stack deklariert und mit `defineStack` -zusammengesetzt. Definieren Sie jede Verbindung als typisiertes -`Datasource`-Objekt und führen Sie sie dann unter `datasources` auf: - -```ts -// src/datasources/business.datasource.ts -import type { Datasource } from '@objectstack/spec'; - -// Mit einer BESTEHENDEN Produktionsdatenbank verbinden. Anmeldedaten kommen -// aus der Umgebung — niemals Secrets inline im Quellcode. -export const BusinessDb: Datasource = { - name: 'business_primary', - label: 'Business System (Postgres)', - driver: 'postgres', - config: { - connection: { - host: process.env.BIZ_DB_HOST, - port: Number(process.env.BIZ_DB_PORT ?? 5432), - user: process.env.BIZ_DB_USER, - password: process.env.BIZ_DB_PASSWORD, - database: process.env.BIZ_DB_NAME, - }, - }, - pool: { min: 1, max: 10 }, - active: true, -}; -``` - -```ts -// objectstack.config.ts -import { defineStack } from '@objectstack/spec'; -import * as objects from './src/objects/index.js'; -import { BusinessDb } from './src/datasources/business.datasource.js'; - -export default defineStack({ - manifest: { id: 'app.example.crm-extend', namespace: 'biz', version: '1.0.0' }, - datasources: [BusinessDb], - objects: Object.values(objects), -}); -``` - -> Es gibt **keinen** `defineDatasource()`-Helfer. Eine Datasource ist -> einfach ein `Datasource`-Objekt, das Sie im `datasources`-Array -> platzieren — genau so, wie es der `examples/app-crm`-Stack im -> Framework-Repo tut. - -## Objekte an eine Datasource binden - -Jedes Objekt hat ein `datasource`-Feld. Es ist standardmäßig auf -`'default'` (die primäre Datenbank) gesetzt. Setzen Sie es, um ein -bestimmtes Objekt auf eines Ihrer verbundenen Systeme zu routen: - -```ts -import { ObjectSchema, Field } from '@objectstack/spec/data'; - -export const Customer = ObjectSchema.create({ - name: 'biz_customer', - label: 'Customer', - datasource: 'business_primary', // ← Lese-/Schreibvorgänge gehen an die Business-DB - fields: { - name: Field.text({ label: 'Name', required: true }), - email: Field.text({ label: 'Email' }), - tier: Field.select({ label: 'Tier', options: [/* … */] }), - }, -}); -``` - -### Zentralisiertes Routing mit `datasourceMapping` - -Objekte einzeln zu binden ist für eine Handvoll in Ordnung. Für ganze -Namespaces oder Pakete deklarieren Sie Routing-Regeln einmal im Stack. -Regeln werden der Reihe nach ausgewertet (oder nach `priority`); die erste -Übereinstimmung gewinnt: - -```ts -export default defineStack({ - datasources: [BusinessDb, AnalyticsReplica], - datasourceMapping: [ - { namespace: 'biz', datasource: 'business_primary' }, - { objectPattern: 'report_*', datasource: 'analytics_replica' }, - { package: 'com.example.logs', datasource: 'business_primary' }, - { default: true, datasource: 'default' }, - ], -}); -``` - -Eine Regel matcht nach `namespace`, `package`, `objectPattern` (Glob) oder -`default` und benennt die Ziel-`datasource`. So bleiben Entscheidungen zur -Datenresidenz an einem Ort, statt über die Objektdateien verstreut zu sein. - -## Objekte aus bestehenden Tabellen generieren - -Sie müssen nicht für jede Tabelle ein Objekt von Hand schreiben. Der -schnellste Weg, ein Legacy-Schema heute in ObjectOS zu bringen, besteht -darin, **einen Coding-Agent (Claude Code) die Business-Tabellen scannen und -Objektdefinitionen auf Quellcode-Ebene generieren zu lassen** — eine -`*.object.ts`-Datei pro Tabelle, genau in der Form, die das Framework -erwartet. - -Die Referenz-App [`hotcrm`](https://github.com/objectstack-ai/hotcrm) ist -das kanonische Beispiel für diese Form: Jede Tabelle ist eine -`src/objects/.object.ts`-Datei, die `ObjectSchema.create({ … })` mit -`Field.*`-Definitionen verwendet, alles zusammengesetzt von `defineStack`. -Ein typischer Ablauf: - -1. **Verbinden** Sie die Business-Datenbank als Datasource (siehe oben). -2. **Richten Sie Claude Code auf das Schema.** Bitten Sie es, die - verbundene Datenbank zu introspektieren — Tabellennamen, Spalten, Typen, - Fremdschlüssel — und eine `ObjectSchema.create`-Datei pro Tabelle zu - generieren, wobei SQL-Spalten auf `Field.*`-Typen und Fremdschlüssel auf - `Field.lookup(...)` abgebildet werden. Setzen Sie die `datasource` jedes - Objekts auf Ihre Verbindung (oder verlassen Sie sich auf - `datasourceMapping`). -3. **Prüfen & verfeinern** Sie die generierten Objekte — fügen Sie Labels, - Feldgruppen, Validierungen und Berechtigungen hinzu. Die Ausgabe ist - gewöhnlicher Quellcode, der Ihnen gehört und den Sie committen, genau wie - `hotcrm/src/objects/*.object.ts`. -4. **Ausführen.** Die Objekte lesen und schreiben jetzt Ihre bestehenden - Tabellen über die gebundene Datasource. - -Da die generierten Objekte einfacher Quellcode sind, haben Sie volle -Kontrolle: Behalten Sie, was passt, lassen Sie Spalten weg, die Sie nicht -offenlegen wollen, und legen Sie ObjectOS-Funktionen (History-Tracking, -Aktivitäten, Sharing-Regeln) auf einer Datenbank ab, die die Plattform nie -besitzen musste. - -## Capability-bewusste Abfrage-Pushdown - -Jede Datasource weist `DatasourceCapabilities` aus — ob sie Filter, -Sortierung, Pagination, Aggregationen, Joins, Volltextsuche, Transaktionen -und mehr verarbeiten kann. ObjectQL nutzt dies, um zu entscheiden, was an -die Datenbank **heruntergeschoben** wird und was im Speicher ausgewertet -wird: - -| Capability | Effekt bei Unterstützung | -|---|---| -| `queryFilters` | `WHERE`-Klauseln laufen in der Datenbank | -| `querySorting` / `queryPagination` | `ORDER BY` / `LIMIT` laufen serverseitig | -| `queryAggregations` | `GROUP BY` / Aggregate laufen serverseitig | -| `joins` | Joins verwandter Objekte laufen serverseitig | -| `fullTextSearch` | Suche trifft einen nativen Index | -| `readOnly` | Die Verbindung lehnt Schreibvorgänge ab | - -Eine leistungsfähige SQL-Datasource schiebt nahezu alles herunter; eine -eingeschränkte oder schreibgeschützte Quelle liefert dieselben -Abfrageergebnisse, nur mit mehr Arbeit in der Engine. Sie können den -ausgewiesenen Satz pro Datasource über das `capabilities`-Feld -überschreiben, wenn Sie es besser wissen als die Treiber-Vorgabe. - -## AI über verbundenen Daten - -Sobald Tabellen als Objekte modelliert sind, **arbeitet die AI-Schicht -kostenlos auf ihnen**. Die Agents und Tools von ObjectOS — -`list_objects`, `describe_object`, `query_records`, `aggregate_data` und -der Data-Chat-Agent — laufen alle über ObjectQL, das jedes Objekt zu seiner -gebundenen Datasource routet. Das bedeutet: - -- Ein Benutzer kann **Fragen in natürlicher Sprache** zu Daten stellen, die - im Legacy-Business-System liegen, und die Antwort wird gegen die echten - Zeilen berechnet. -- Tool-Calls und Abfragen respektieren die **Berechtigungen des - aufrufenden Benutzers** — AI sieht nie mehr, als der angemeldete Benutzer - sehen darf. -- Dieselben Agents, Flows und Dashboards funktionieren, egal ob ein Objekt - von der primären Datenbank oder einem externen Business-System gestützt - wird. - -Siehe [AI-Service](/docs/configure/ai) und -[AI Agents](/docs/build/agents) dafür, wie Sie die Chat- und -Agent-Schichten verdrahten, und [Runtime](/docs/configure/runtime) für die -Konfiguration der primären Datenbank, die die `default`-Datasource stützt. - -## Sicherheitshinweise - -- **Niemals Anmeldedaten inline.** Beziehen Sie Host/User/Passwort aus - Umgebungsvariablen (oder einem Secrets-Manager), wie oben gezeigt. -- **Verwenden Sie schreibgeschützte Verbindungen** für Systeme, in die Sie - nicht schreiben wollen — setzen Sie die `readOnly`-Capability der Quelle - (oder einen schreibgeschützten DB-Benutzer), damit ein versehentlicher - Schreibvorgang die Produktion nicht erreichen kann. -- **Mit Berechtigungen eingrenzen.** Objekt- und feldbezogene - Berechtigungen gelten für verbundene Daten genauso wie für native - Objekte. - -## Roadmap: In-Product External Datasource Federation - -Der obige Ablauf — eine Datenbank verbinden, Objekte modellieren, sie mit -einem Coding-Agent generieren — funktioniert heute mit den mitgelieferten -Bausteinen. Eine reichhaltigere, **schlüsselfertige -Federation**-Erfahrung befindet sich unter -[ADR-0015](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0015-external-datasource-federation.md) -in aktiver Konzeption (Status: *Proposed*). Geplant, **noch nicht -ausgeliefert**: - -- Ein `schemaMode` (`managed` / `external` / `validate-only`), sodass - ObjectOS sich an Tabellen binden kann, die es **nicht** besitzt, ohne zu - versuchen, sie zu migrieren. -- Ein `external`-Bindungs-Unterdatensatz auf Objekten, der Objektfelder auf - bestehende Spalten abbildet. -- Ein `os datasource introspect` / `validate` CLI, um ein Schema zu - importieren und Objekte in einem Schritt zu scaffolden. -- **Sicherheits-Gates** zur Boot- und Schreibzeit für extern besessene - Schemata sowie ein Studio-Assistent für den gesamten Ablauf. - -Bis diese verfügbar sind, bevorzugen Sie den dokumentierten Pfad: -deklarieren Sie die Datasource, binden Sie Objekte (generiert oder von Hand -geschrieben) und verifizieren Sie zuerst gegen eine Nicht-Produktionskopie. - -## Wie es weitergeht - -- [Runtime](/docs/configure/runtime) — die primäre Datenbank hinter `default` -- [AI-Service](/docs/configure/ai) — Chat, Embeddings, RAG, MCP -- [AI Agents](/docs/build/agents) — deklarative Agents über Ihren Objekten -- [Objects](/docs/build/objects) — die `ObjectSchema.create`-Autorenoberfläche -- [`examples/app-crm` Datasources](https://github.com/objectstack-ai/objectstack/tree/main/examples/app-crm/src/datasources) — ein echtes Beispiel für Datasource + Routing diff --git a/content/docs/configure/data-sources.es.mdx b/content/docs/configure/data-sources.es.mdx deleted file mode 100644 index 5269518..0000000 --- a/content/docs/configure/data-sources.es.mdx +++ /dev/null @@ -1,261 +0,0 @@ ---- -title: Fuentes de datos -description: Conecta ObjectOS a tus bases de datos de negocio existentes, enruta objetos hacia ellas y deja que la IA consulte los datos — de forma nativa. -translation: - source_sha: c1e0954576877e1498f592a5b73c5848b9cefbfe3e27a962bd809d3b2db132b9 - guide_rev: 1 - mode: auto ---- - -Un **datasource** es una conexión con nombre a un almacén de datos externo. -Al declarar datasources, apuntas ObjectOS hacia las bases de datos sobre las -que tu negocio ya funciona — un PostgreSQL de producción, una réplica MySQL -de reporting, un clúster MongoDB — y luego vinculas objetos a ellas. Una vez -que un objeto está vinculado, todo lo demás en la plataforma (la API -REST/GraphQL, los permisos, los flows, los dashboards y los **agents de IA**) -trabaja sobre esos datos de manera uniforme, sin importar dónde residen -físicamente las filas. - -Esta es una de las vías de adopción más prácticas de ObjectOS: en lugar de -migrar un sistema heredado, te conectas a él, modelas como objetos las tablas -que te interesan y lo **extiendes con capacidades nativas de IA** — chat, -análisis, automatización — sobre datos que permanecen exactamente donde -están. - -## Qué es un datasource - -Cada datasource es un objeto sencillo validado por `DatasourceSchema`. Los -campos principales: - -| Campo | Propósito | -|---|---| -| `name` | Identificador único (`^[a-z_][a-z0-9_]*$`) que los objetos referencian | -| `label` | Nombre legible para mostrar | -| `driver` | Qué driver gestiona la conexión (`postgres`, `mysql`, `sqlite`, `mongodb`, `memory`, o un driver aportado por un plugin) | -| `config` | Ajustes de conexión específicos del driver (host, base de datos, credenciales, …) | -| `pool` | Dimensionamiento del pool de conexiones (`min`, `max`, tiempos de espera) | -| `readReplicas` | Configuraciones opcionales de réplicas de solo lectura | -| `capabilities` | Sobrescribe lo que el driver anuncia que puede delegar (push down) | -| `healthCheck` | Intervalo/tiempo de espera de la sonda de actividad | -| `active` | Si la conexión está habilitada | - -Los drivers incluidos son: - -| Paquete del driver | `driver` | Backends | -|---|---|---| -| `@objectstack/driver-sql` | `postgres`, `mysql`, `sqlite` | PostgreSQL, MySQL, SQLite (vía knex) | -| `@objectstack/driver-mongodb` | `mongodb` | MongoDB | -| `@objectstack/driver-memory` | `memory` | En proceso (tests, demos) | -| `@objectstack/driver-sqlite-wasm` | `sqlite` (WASM) | SQLite en WebContainers / navegador | - -## Declarar datasources - -Los datasources se declaran en el stack y se ensamblan con `defineStack`. -Define cada conexión como un objeto `Datasource` tipado y luego enuméralos -bajo `datasources`: - -```ts -// src/datasources/business.datasource.ts -import type { Datasource } from '@objectstack/spec'; - -// Conéctate a una base de datos de producción EXISTENTE. Las credenciales -// provienen del entorno — nunca incluyas secretos en línea en el código. -export const BusinessDb: Datasource = { - name: 'business_primary', - label: 'Business System (Postgres)', - driver: 'postgres', - config: { - connection: { - host: process.env.BIZ_DB_HOST, - port: Number(process.env.BIZ_DB_PORT ?? 5432), - user: process.env.BIZ_DB_USER, - password: process.env.BIZ_DB_PASSWORD, - database: process.env.BIZ_DB_NAME, - }, - }, - pool: { min: 1, max: 10 }, - active: true, -}; -``` - -```ts -// objectstack.config.ts -import { defineStack } from '@objectstack/spec'; -import * as objects from './src/objects/index.js'; -import { BusinessDb } from './src/datasources/business.datasource.js'; - -export default defineStack({ - manifest: { id: 'app.example.crm-extend', namespace: 'biz', version: '1.0.0' }, - datasources: [BusinessDb], - objects: Object.values(objects), -}); -``` - -> **No** existe un helper `defineDatasource()`. Un datasource es simplemente -> un objeto `Datasource` que colocas en el array `datasources` — exactamente -> como hace el stack `examples/app-crm` en el repositorio del framework. - -## Vincular objetos a un datasource - -Cada objeto tiene un campo `datasource`. Su valor predeterminado es -`'default'` (la base de datos primaria). Establécelo para enrutar un objeto -específico hacia uno de tus sistemas conectados: - -```ts -import { ObjectSchema, Field } from '@objectstack/spec/data'; - -export const Customer = ObjectSchema.create({ - name: 'biz_customer', - label: 'Customer', - datasource: 'business_primary', // ← las lecturas/escrituras van a la BD de negocio - fields: { - name: Field.text({ label: 'Name', required: true }), - email: Field.text({ label: 'Email' }), - tier: Field.select({ label: 'Tier', options: [/* … */] }), - }, -}); -``` - -### Enrutamiento centralizado con `datasourceMapping` - -Vincular objetos uno por uno está bien para unos pocos. Para espacios de -nombres o paquetes enteros, declara las reglas de enrutamiento una sola vez -en el stack. Las reglas se evalúan en orden (o por `priority`); gana la -primera coincidencia: - -```ts -export default defineStack({ - datasources: [BusinessDb, AnalyticsReplica], - datasourceMapping: [ - { namespace: 'biz', datasource: 'business_primary' }, - { objectPattern: 'report_*', datasource: 'analytics_replica' }, - { package: 'com.example.logs', datasource: 'business_primary' }, - { default: true, datasource: 'default' }, - ], -}); -``` - -Una regla coincide por `namespace`, `package`, `objectPattern` (glob) o -`default`, y nombra el `datasource` de destino. Esto mantiene las decisiones -de residencia de datos en un solo lugar en vez de dispersas por los archivos -de objetos. - -## Generar objetos a partir de tablas existentes - -No tienes que escribir a mano un objeto por cada tabla. La forma más rápida -de incorporar hoy un esquema heredado a ObjectOS es **usar un agente de -codificación (Claude Code) para escanear las tablas de negocio y generar -definiciones de objetos a nivel de código fuente** — un archivo -`*.object.ts` por tabla, exactamente con la forma que el framework espera. - -La aplicación de referencia [`hotcrm`](https://github.com/objectstack-ai/hotcrm) -es el ejemplo canónico de esa forma: cada tabla es un archivo -`src/objects/.object.ts` que usa `ObjectSchema.create({ … })` con -definiciones `Field.*`, todo ensamblado por `defineStack`. Un flujo típico: - -1. **Conecta** la base de datos de negocio como un datasource (arriba). -2. **Apunta Claude Code al esquema.** Pídele que introspeccione la base de - datos conectada — nombres de tablas, columnas, tipos, claves foráneas — y - genere un archivo `ObjectSchema.create` por tabla, mapeando las columnas - SQL a tipos `Field.*` y las claves foráneas a `Field.lookup(...)`. - Establece el `datasource` de cada objeto a tu conexión (o apóyate en - `datasourceMapping`). -3. **Revisa y refina** los objetos generados — añade labels, grupos de - campos, validaciones y permisos. La salida es código fuente ordinario que - te pertenece y confirmas, igual que `hotcrm/src/objects/*.object.ts`. -4. **Ejecuta.** Los objetos ahora leen y escriben en tus tablas existentes a - través del datasource vinculado. - -Como los objetos generados son código fuente sencillo, obtienes control -total: conserva lo que encaja, descarta las columnas que no quieras exponer y -superpón funciones de ObjectOS (seguimiento de historial, actividades, -reglas de compartición) sobre una base de datos que la plataforma nunca tuvo -que poseer. - -## Delegación de consultas según capacidades - -Cada datasource anuncia `DatasourceCapabilities` — si puede manejar filtros, -ordenación, paginación, agregaciones, joins, búsqueda de texto completo, -transacciones y más. ObjectQL usa esto para decidir qué **delegar (push -down)** a la base de datos frente a qué evaluar en memoria: - -| Capacidad | Efecto cuando se admite | -|---|---| -| `queryFilters` | Las cláusulas `WHERE` se ejecutan en la base de datos | -| `querySorting` / `queryPagination` | `ORDER BY` / `LIMIT` se ejecutan en el servidor | -| `queryAggregations` | `GROUP BY` / agregados se ejecutan en el servidor | -| `joins` | Los joins de objetos relacionados se ejecutan en el servidor | -| `fullTextSearch` | La búsqueda usa un índice nativo | -| `readOnly` | La conexión rechaza las escrituras | - -Un datasource SQL capaz delega casi todo; una fuente limitada o de solo -lectura obtiene los mismos resultados de consulta, solo que con más trabajo -hecho en el motor. Puedes sobrescribir el conjunto anunciado por datasource -mediante el campo `capabilities` cuando sepas más que el valor -predeterminado del driver. - -## IA sobre datos conectados - -Una vez que las tablas se modelan como objetos, **la capa de IA funciona -sobre ellas sin esfuerzo adicional**. Los agents y herramientas de ObjectOS -— `list_objects`, `describe_object`, `query_records`, `aggregate_data` y el -agente de chat de datos — pasan todos por ObjectQL, que enruta cada objeto a -su datasource vinculado. Eso significa: - -- Un usuario puede **hacer preguntas en lenguaje natural** sobre datos que - residen en el sistema de negocio heredado, y la respuesta se calcula contra - las filas reales. -- Las llamadas a herramientas y las consultas respetan los **permisos del - usuario que las realiza** — la IA nunca ve más de lo que el usuario que ha - iniciado sesión tiene permitido. -- Los mismos agents, flows y dashboards funcionan tanto si un objeto está - respaldado por la base de datos primaria como por un sistema de negocio - externo. - -Consulta [AI Service](/docs/configure/ai) y -[AI Agents](/docs/build/agents) para saber cómo conectar las capas de chat y -de agents, y [Runtime](/docs/configure/runtime) para la configuración de la -base de datos primaria que respalda el datasource `default`. - -## Notas de seguridad - -- **Nunca incluyas credenciales en línea.** Obtén host/usuario/contraseña de - variables de entorno (o de un gestor de secretos) como se muestra arriba. -- **Usa conexiones de solo lectura** para sistemas en los que no pretendes - escribir — establece la capacidad `readOnly` de la fuente (o un usuario de - BD de solo lectura) para que una escritura accidental no pueda llegar a - producción. -- **Limita el alcance con permisos.** Los permisos a nivel de objeto y de - campo se aplican a los datos conectados exactamente igual que a los objetos - nativos. - -## Hoja de ruta: federación de datasources externos en el producto - -El flujo anterior — conectar una base de datos, modelar objetos, generarlos -con un agente de codificación — funciona hoy con los bloques de construcción -incluidos. Una experiencia de **federación llave en mano** más rica está en -diseño activo bajo -[ADR-0015](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0015-external-datasource-federation.md) -(estado: *Propuesto*). Previsto, pero **aún no disponible**: - -- Un `schemaMode` (`managed` / `external` / `validate-only`) para que - ObjectOS pueda vincularse a tablas que **no** posee sin intentar - migrarlas. -- Un subregistro de vinculación `external` en los objetos que mapea los - campos del objeto a columnas existentes. -- Una CLI `os datasource introspect` / `validate` para importar un esquema y - generar objetos en un solo paso. -- **Barreras de seguridad** en el arranque y en la escritura para esquemas de - propiedad externa, además de un asistente de Studio para todo el flujo. - -Hasta que eso llegue, prefiere la vía documentada: declara el datasource, -vincula objetos (generados o escritos a mano) y verifica primero contra una -copia que no sea de producción. - -## Adónde ir después - -- [Runtime](/docs/configure/runtime) — la base de datos primaria detrás de `default` -- [AI Service](/docs/configure/ai) — chat, embeddings, RAG, MCP -- [AI Agents](/docs/build/agents) — agents declarativos sobre tus objetos -- [Objects](/docs/build/objects) — la superficie de autoría `ObjectSchema.create` -- [datasources de `examples/app-crm`](https://github.com/objectstack-ai/objectstack/tree/main/examples/app-crm/src/datasources) — un ejemplo real de datasource + enrutamiento diff --git a/content/docs/configure/data-sources.fr.mdx b/content/docs/configure/data-sources.fr.mdx deleted file mode 100644 index 05087df..0000000 --- a/content/docs/configure/data-sources.fr.mdx +++ /dev/null @@ -1,273 +0,0 @@ ---- -title: Sources de données -description: Connectez ObjectOS à vos bases de données métier existantes, routez-y les objets, et laissez l'IA interroger les données — nativement. -translation: - source_sha: c1e0954576877e1498f592a5b73c5848b9cefbfe3e27a962bd809d3b2db132b9 - guide_rev: 1 - mode: auto ---- - -Une **datasource** est une connexion nommée vers un magasin de données -externe. En déclarant des datasources, vous pointez ObjectOS vers les -bases de données sur lesquelles votre activité repose déjà — un -PostgreSQL de production, un réplica MySQL de reporting, un cluster -MongoDB — puis vous y liez des objets. Une fois qu'un objet est lié, -tout le reste de la plateforme (l'API REST/GraphQL, les permissions, -les flux, les tableaux de bord et les **agents IA**) fonctionne sur ces -données de manière uniforme, sans se soucier de l'endroit où les lignes -résident physiquement. - -C'est l'un des chemins d'adoption les plus concrets d'ObjectOS : au lieu -de migrer un système hérité, vous vous y connectez, vous modélisez les -tables qui vous intéressent en tant qu'objets, et vous **l'enrichissez de -capacités natives IA** — chat, analyse, automatisation — par-dessus des -données qui restent exactement là où elles sont. - -## Ce qu'est une datasource - -Chaque datasource est un simple objet validé par `DatasourceSchema`. Les -champs principaux : - -| Champ | Rôle | -|---|---| -| `name` | Identifiant unique (`^[a-z_][a-z0-9_]*$`) référencé par les objets | -| `label` | Nom d'affichage lisible par un humain | -| `driver` | Quel driver gère la connexion (`postgres`, `mysql`, `sqlite`, `mongodb`, `memory`, ou un driver fourni par un plugin) | -| `config` | Paramètres de connexion spécifiques au driver (hôte, base de données, identifiants, …) | -| `pool` | Dimensionnement du pool de connexions (`min`, `max`, délais d'expiration) | -| `readReplicas` | Configurations de réplicas en lecture seule (optionnel) | -| `capabilities` | Surcharge ce que le driver annonce pouvoir pousser vers la base | -| `healthCheck` | Intervalle/délai d'expiration de la sonde de vivacité | -| `active` | Si la connexion est activée | - -Les drivers livrés sont : - -| Package de driver | `driver` | Backends | -|---|---|---| -| `@objectstack/driver-sql` | `postgres`, `mysql`, `sqlite` | PostgreSQL, MySQL, SQLite (via knex) | -| `@objectstack/driver-mongodb` | `mongodb` | MongoDB | -| `@objectstack/driver-memory` | `memory` | In-process (tests, démos) | -| `@objectstack/driver-sqlite-wasm` | `sqlite` (WASM) | SQLite dans WebContainers / navigateur | - -## Déclarer des datasources - -Les datasources sont déclarées sur le stack et assemblées avec -`defineStack`. Définissez chaque connexion comme un objet `Datasource` -typé, puis listez-les sous `datasources` : - -```ts -// src/datasources/business.datasource.ts -import type { Datasource } from '@objectstack/spec'; - -// Se connecter à une base de données de production EXISTANTE. Les -// identifiants proviennent de l'environnement — ne jamais inscrire de -// secrets en dur dans le code source. -export const BusinessDb: Datasource = { - name: 'business_primary', - label: 'Business System (Postgres)', - driver: 'postgres', - config: { - connection: { - host: process.env.BIZ_DB_HOST, - port: Number(process.env.BIZ_DB_PORT ?? 5432), - user: process.env.BIZ_DB_USER, - password: process.env.BIZ_DB_PASSWORD, - database: process.env.BIZ_DB_NAME, - }, - }, - pool: { min: 1, max: 10 }, - active: true, -}; -``` - -```ts -// objectstack.config.ts -import { defineStack } from '@objectstack/spec'; -import * as objects from './src/objects/index.js'; -import { BusinessDb } from './src/datasources/business.datasource.js'; - -export default defineStack({ - manifest: { id: 'app.example.crm-extend', namespace: 'biz', version: '1.0.0' }, - datasources: [BusinessDb], - objects: Object.values(objects), -}); -``` - -> Il n'y a **aucun** helper `defineDatasource()`. Une datasource est -> simplement un objet `Datasource` que vous placez dans le tableau -> `datasources` — exactement comme le fait le stack `examples/app-crm` -> dans le dépôt du framework. - -## Lier des objets à une datasource - -Chaque objet possède un champ `datasource`. Sa valeur par défaut est -`'default'` (la base de données primaire). Définissez-le pour router un -objet spécifique vers l'un de vos systèmes connectés : - -```ts -import { ObjectSchema, Field } from '@objectstack/spec/data'; - -export const Customer = ObjectSchema.create({ - name: 'biz_customer', - label: 'Customer', - datasource: 'business_primary', // ← lectures/écritures vers la base métier - fields: { - name: Field.text({ label: 'Name', required: true }), - email: Field.text({ label: 'Email' }), - tier: Field.select({ label: 'Tier', options: [/* … */] }), - }, -}); -``` - -### Routage centralisé avec `datasourceMapping` - -Lier les objets un par un convient pour une poignée d'entre eux. Pour des -espaces de noms ou des packages entiers, déclarez les règles de routage -une seule fois sur le stack. Les règles sont évaluées dans l'ordre (ou par -`priority`) ; la première correspondance l'emporte : - -```ts -export default defineStack({ - datasources: [BusinessDb, AnalyticsReplica], - datasourceMapping: [ - { namespace: 'biz', datasource: 'business_primary' }, - { objectPattern: 'report_*', datasource: 'analytics_replica' }, - { package: 'com.example.logs', datasource: 'business_primary' }, - { default: true, datasource: 'default' }, - ], -}); -``` - -Une règle correspond par `namespace`, `package`, `objectPattern` (glob) -ou `default`, et nomme la `datasource` cible. Cela maintient les décisions -de résidence des données en un seul endroit au lieu de les disperser dans -les fichiers d'objets. - -## Générer des objets à partir de tables existantes - -Vous n'avez pas à écrire à la main un objet pour chaque table. La manière -la plus rapide aujourd'hui d'intégrer un schéma hérité dans ObjectOS est -d'**utiliser un agent de codage (Claude Code) pour scanner les tables -métier et générer des définitions d'objets au niveau du code source** — -un fichier `*.object.ts` par table, exactement dans la forme attendue par -le framework. - -L'application de référence [`hotcrm`](https://github.com/objectstack-ai/hotcrm) -est l'exemple canonique de cette forme : chaque table est un fichier -`src/objects/.object.ts` utilisant `ObjectSchema.create({ … })` -avec des définitions `Field.*`, le tout assemblé par `defineStack`. Un -flux typique : - -1. **Connectez** la base de données métier en tant que datasource - (ci-dessus). -2. **Pointez Claude Code vers le schéma.** Demandez-lui d'introspecter la - base de données connectée — noms de tables, colonnes, types, clés - étrangères — et de générer un fichier `ObjectSchema.create` par table, - en mappant les colonnes SQL vers des types `Field.*` et les clés - étrangères vers `Field.lookup(...)`. Définissez la `datasource` de - chaque objet sur votre connexion (ou reposez-vous sur - `datasourceMapping`). -3. **Révisez et affinez** les objets générés — ajoutez des libellés, des - groupes de champs, des validations et des permissions. La sortie est du - code source ordinaire que vous possédez et committez, tout comme - `hotcrm/src/objects/*.object.ts`. -4. **Exécutez.** Les objets lisent et écrivent désormais dans vos tables - existantes via la datasource liée. - -Comme les objets générés sont du simple code source, vous gardez un -contrôle total : conservez ce qui convient, supprimez les colonnes que -vous ne souhaitez pas exposer, et superposez les fonctionnalités ObjectOS -(suivi de l'historique, activités, règles de partage) par-dessus une base -de données que la plateforme n'a jamais eu à posséder. - -## Pushdown des requêtes selon les capacités - -Chaque datasource annonce ses `DatasourceCapabilities` — si elle peut -gérer les filtres, le tri, la pagination, les agrégations, les jointures, -la recherche plein texte, les transactions, et plus encore. ObjectQL -utilise cela pour décider ce qu'il **pousse** vers la base de données par -rapport à ce qu'il évalue en mémoire : - -| Capacité | Effet lorsqu'elle est prise en charge | -|---|---| -| `queryFilters` | Les clauses `WHERE` s'exécutent dans la base de données | -| `querySorting` / `queryPagination` | `ORDER BY` / `LIMIT` s'exécutent côté serveur | -| `queryAggregations` | `GROUP BY` / agrégats s'exécutent côté serveur | -| `joins` | Les jointures entre objets liés s'exécutent côté serveur | -| `fullTextSearch` | La recherche utilise un index natif | -| `readOnly` | La connexion rejette les écritures | - -Une datasource SQL capable pousse presque tout vers la base ; une source -limitée ou en lecture seule obtient les mêmes résultats de requête, avec -simplement davantage de travail effectué dans le moteur. Vous pouvez -surcharger l'ensemble annoncé par datasource via le champ `capabilities` -lorsque vous en savez plus que la valeur par défaut du driver. - -## L'IA sur des données connectées - -Une fois les tables modélisées en tant qu'objets, **la couche IA -fonctionne dessus gratuitement**. Les agents et outils d'ObjectOS — -`list_objects`, `describe_object`, `query_records`, `aggregate_data` et -l'agent de chat sur les données — passent tous par ObjectQL, qui route -chaque objet vers sa datasource liée. Cela signifie que : - -- Un utilisateur peut **poser des questions en langage naturel** sur des - données qui résident dans le système métier hérité, et la réponse est - calculée sur les vraies lignes. -- Les appels d'outils et les requêtes respectent les **permissions de - l'utilisateur appelant** — l'IA ne voit jamais plus que ce que - l'utilisateur connecté est autorisé à voir. -- Les mêmes agents, flux et tableaux de bord fonctionnent qu'un objet soit - adossé à la base de données primaire ou à un système métier externe. - -Consultez [Service IA](/docs/configure/ai) et -[AI Agents](/docs/build/agents) pour savoir comment câbler les couches de -chat et d'agents, et [Runtime](/docs/configure/runtime) pour la -configuration de la base de données primaire qui sous-tend la datasource -`default`. - -## Notes de sécurité - -- **N'inscrivez jamais d'identifiants en dur.** Récupérez - l'hôte/l'utilisateur/le mot de passe depuis des variables - d'environnement (ou un gestionnaire de secrets) comme montré ci-dessus. -- **Utilisez des connexions en lecture seule** pour les systèmes dans - lesquels vous n'avez pas l'intention d'écrire — définissez la capacité - `readOnly` de la source (ou un utilisateur de base de données en lecture - seule) afin qu'une écriture accidentelle ne puisse pas atteindre la - production. -- **Limitez la portée avec les permissions.** Les permissions au niveau - des objets et des champs s'appliquent aux données connectées exactement - comme aux objets natifs. - -## Feuille de route : fédération de sources de données externes intégrée au produit - -Le flux ci-dessus — connecter une base de données, modéliser des objets, -les générer avec un agent de codage — fonctionne dès aujourd'hui avec les -briques livrées. Une expérience de **fédération clé en main** plus riche -est en cours de conception active sous -[ADR-0015](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0015-external-datasource-federation.md) -(statut : *Proposed*). Prévu, **pas encore livré** : - -- Un `schemaMode` (`managed` / `external` / `validate-only`) afin - qu'ObjectOS puisse se lier à des tables qu'il ne **possède pas** sans - essayer de les migrer. -- Un sous-enregistrement de liaison `external` sur les objets, mappant les - champs d'objet vers des colonnes existantes. -- Une CLI `os datasource introspect` / `validate` pour importer un schéma - et générer le squelette des objets en une seule étape. -- Des **garde-fous de sécurité** au démarrage et à l'écriture pour les - schémas appartenant à des systèmes externes, plus un assistant Studio - pour l'ensemble du flux. - -En attendant que ceux-ci arrivent, préférez le chemin documenté : -déclarez la datasource, liez les objets (générés ou écrits à la main), et -vérifiez d'abord sur une copie hors production. - -## Pour aller plus loin - -- [Runtime](/docs/configure/runtime) — la base de données primaire derrière `default` -- [Service IA](/docs/configure/ai) — chat, embeddings, RAG, MCP -- [AI Agents](/docs/build/agents) — agents déclaratifs sur vos objets -- [Objects](/docs/build/objects) — la surface d'écriture `ObjectSchema.create` -- [Sources de données de `examples/app-crm`](https://github.com/objectstack-ai/objectstack/tree/main/examples/app-crm/src/datasources) — un exemple réel de datasource + routage diff --git a/content/docs/configure/data-sources.ja.mdx b/content/docs/configure/data-sources.ja.mdx deleted file mode 100644 index cbc34cb..0000000 --- a/content/docs/configure/data-sources.ja.mdx +++ /dev/null @@ -1,180 +0,0 @@ ---- -title: データソース -description: ObjectOS を既存のビジネスデータベースに接続し、オブジェクトをそこへルーティングして、AI にそのデータをネイティブにクエリさせます。 -translation: - source_sha: c1e0954576877e1498f592a5b73c5848b9cefbfe3e27a962bd809d3b2db132b9 - guide_rev: 1 - mode: auto ---- - -**データソース**とは、外部データストアへの名前付き接続です。データソースを宣言することで、ObjectOS をビジネスがすでに稼働しているデータベース — 本番の PostgreSQL、レポート用の MySQL レプリカ、MongoDB クラスター — に向け、そこへオブジェクトをバインドします。オブジェクトが一度バインドされると、プラットフォームの他のすべて（REST/GraphQL API、権限、フロー、ダッシュボード、そして **AI エージェント**）が、行が物理的にどこにあるかを気にすることなく、そのデータに対して一様に動作します。 - -これは ObjectOS の最も実践的な導入経路の 1 つです。レガシーシステムを移行する代わりに、それに接続し、関心のあるテーブルをオブジェクトとしてモデル化し、まさにあるべき場所にとどまるデータの上に **AI ネイティブな機能** — チャット、分析、自動化 — を**拡張**します。 - -## データソースとは - -各データソースは `DatasourceSchema` によって検証されるプレーンなオブジェクトです。コアとなるフィールド: - -| フィールド | 目的 | -|---|---| -| `name` | オブジェクトが参照する一意の識別子（`^[a-z_][a-z0-9_]*$`） | -| `label` | 人間が読める表示名 | -| `driver` | 接続を処理するドライバー（`postgres`、`mysql`、`sqlite`、`mongodb`、`memory`、またはプラグインが提供するドライバー） | -| `config` | ドライバー固有の接続設定（ホスト、データベース、認証情報、…） | -| `pool` | コネクションプールのサイジング（`min`、`max`、タイムアウト） | -| `readReplicas` | 任意の読み取り専用レプリカ設定 | -| `capabilities` | ドライバーがプッシュダウン可能と公表する内容を上書き | -| `healthCheck` | 死活監視プローブの間隔／タイムアウト | -| `active` | 接続を有効にするかどうか | - -同梱されているドライバーは以下のとおりです: - -| ドライバーパッケージ | `driver` | バックエンド | -|---|---|---| -| `@objectstack/driver-sql` | `postgres`、`mysql`、`sqlite` | PostgreSQL、MySQL、SQLite（knex 経由） | -| `@objectstack/driver-mongodb` | `mongodb` | MongoDB | -| `@objectstack/driver-memory` | `memory` | インプロセス（テスト、デモ） | -| `@objectstack/driver-sqlite-wasm` | `sqlite`（WASM） | WebContainers / ブラウザ上の SQLite | - -## データソースの宣言 - -データソースはスタック上で宣言され、`defineStack` で組み立てられます。各接続を型付きの `Datasource` オブジェクトとして定義し、それらを `datasources` の下に列挙します: - -```ts -// src/datasources/business.datasource.ts -import type { Datasource } from '@objectstack/spec'; - -// 既存の本番データベースに接続します。認証情報は環境から取得します — -// ソースにシークレットをインラインで書かないでください。 -export const BusinessDb: Datasource = { - name: 'business_primary', - label: 'Business System (Postgres)', - driver: 'postgres', - config: { - connection: { - host: process.env.BIZ_DB_HOST, - port: Number(process.env.BIZ_DB_PORT ?? 5432), - user: process.env.BIZ_DB_USER, - password: process.env.BIZ_DB_PASSWORD, - database: process.env.BIZ_DB_NAME, - }, - }, - pool: { min: 1, max: 10 }, - active: true, -}; -``` - -```ts -// objectstack.config.ts -import { defineStack } from '@objectstack/spec'; -import * as objects from './src/objects/index.js'; -import { BusinessDb } from './src/datasources/business.datasource.js'; - -export default defineStack({ - manifest: { id: 'app.example.crm-extend', namespace: 'biz', version: '1.0.0' }, - datasources: [BusinessDb], - objects: Object.values(objects), -}); -``` - -> `defineDatasource()` ヘルパーは**存在しません**。データソースとは、`datasources` 配列に配置する単なる `Datasource` オブジェクトです — フレームワークリポジトリの `examples/app-crm` スタックがまさにそうしているとおりです。 - -## オブジェクトをデータソースにバインドする - -すべてのオブジェクトは `datasource` フィールドを持ちます。デフォルトは `'default'`（プライマリデータベース）です。特定のオブジェクトを接続済みシステムの 1 つにルーティングするには、これを設定します: - -```ts -import { ObjectSchema, Field } from '@objectstack/spec/data'; - -export const Customer = ObjectSchema.create({ - name: 'biz_customer', - label: 'Customer', - datasource: 'business_primary', // ← 読み書きはビジネス DB へ行く - fields: { - name: Field.text({ label: 'Name', required: true }), - email: Field.text({ label: 'Email' }), - tier: Field.select({ label: 'Tier', options: [/* … */] }), - }, -}); -``` - -### `datasourceMapping` による集中ルーティング - -オブジェクトを 1 つずつバインドするのは少数なら問題ありません。名前空間やパッケージ全体については、ルーティングルールをスタック上で一度だけ宣言します。ルールは順番（または `priority`）に評価され、最初にマッチしたものが優先されます: - -```ts -export default defineStack({ - datasources: [BusinessDb, AnalyticsReplica], - datasourceMapping: [ - { namespace: 'biz', datasource: 'business_primary' }, - { objectPattern: 'report_*', datasource: 'analytics_replica' }, - { package: 'com.example.logs', datasource: 'business_primary' }, - { default: true, datasource: 'default' }, - ], -}); -``` - -ルールは `namespace`、`package`、`objectPattern`（glob）、または `default` でマッチし、ターゲットの `datasource` を指定します。これにより、データレジデンシーの判断がオブジェクトファイル全体に散らばるのではなく、1 か所にまとまります。 - -## 既存テーブルからのオブジェクト生成 - -すべてのテーブルについて手作業でオブジェクトを書く必要はありません。今日レガシースキーマを ObjectOS に取り込む最速の方法は、**コーディングエージェント（Claude Code）を使ってビジネステーブルをスキャンし、ソースレベルのオブジェクト定義を生成する**ことです — テーブルごとに 1 つの `*.object.ts` ファイルを、フレームワークが期待するまさにその形で。 - -[`hotcrm`](https://github.com/objectstack-ai/hotcrm) リファレンスアプリは、その形の標準的な例です。各テーブルは `Field.*` 定義を持つ `ObjectSchema.create({ … })` を使った `src/objects/.object.ts` ファイルであり、すべてが `defineStack` によって組み立てられます。典型的なフロー: - -1. ビジネスデータベースをデータソースとして**接続**します（上記）。 -2. **Claude Code をスキーマに向けます。** 接続されたデータベース — テーブル名、カラム、型、外部キー — をイントロスペクトし、テーブルごとに 1 つの `ObjectSchema.create` ファイルを生成し、SQL カラムを `Field.*` 型へ、外部キーを `Field.lookup(...)` へマッピングするよう依頼します。各オブジェクトの `datasource` を接続先に設定するか、`datasourceMapping` に頼ります。 -3. 生成されたオブジェクトを**レビューして精緻化**します — ラベル、フィールドグループ、バリデーション、権限を追加します。出力は、`hotcrm/src/objects/*.object.ts` とまったく同じように、あなたが所有しコミットする通常のソースです。 -4. **実行します。** オブジェクトは、バインドされたデータソースを通じて、既存のテーブルを読み書きするようになります。 - -生成されたオブジェクトはプレーンなソースなので、完全な制御が得られます。フィットするものは残し、公開したくないカラムは捨て、プラットフォームが一度も所有する必要のなかったデータベースの上に ObjectOS の機能（履歴追跡、アクティビティ、共有ルール）を重ねられます。 - -## ケーパビリティを考慮したクエリプッシュダウン - -各データソースは `DatasourceCapabilities` を公表します — フィルター、ソート、ページネーション、集計、結合、全文検索、トランザクションなどを処理できるかどうかです。ObjectQL はこれを使って、何をデータベースに**プッシュダウン**し、何をメモリ内で評価するかを決定します: - -| ケーパビリティ | サポート時の効果 | -|---|---| -| `queryFilters` | `WHERE` 句がデータベースで実行される | -| `querySorting` / `queryPagination` | `ORDER BY` / `LIMIT` がサーバー側で実行される | -| `queryAggregations` | `GROUP BY` / 集計がサーバー側で実行される | -| `joins` | 関連オブジェクトの結合がサーバー側で実行される | -| `fullTextSearch` | 検索がネイティブインデックスにヒットする | -| `readOnly` | 接続が書き込みを拒否する | - -高機能な SQL データソースはほぼすべてをプッシュダウンします。制限のある、または読み取り専用のソースでも同じクエリ結果が得られますが、エンジン内でより多くの処理が行われるだけです。ドライバーのデフォルトより自分の方が把握している場合は、`capabilities` フィールドを使ってデータソースごとに公表されるセットを上書きできます。 - -## 接続データに対する AI - -テーブルがオブジェクトとしてモデル化されると、**AI レイヤーはそれらに対して無償で動作します**。ObjectOS のエージェントとツール — `list_objects`、`describe_object`、`query_records`、`aggregate_data`、そしてデータチャットエージェント — はすべて ObjectQL を経由し、各オブジェクトをバインドされたデータソースへルーティングします。これは次のことを意味します: - -- ユーザーはレガシービジネスシステムにあるデータについて**自然言語で質問**でき、その答えは実際の行に対して計算されます。 -- ツール呼び出しとクエリは**呼び出しユーザーの権限**を尊重します — AI はサインインしているユーザーに許可された以上のものを決して見ません。 -- 同じエージェント、フロー、ダッシュボードは、オブジェクトがプライマリデータベースに支えられていても外部ビジネスシステムに支えられていても動作します。 - -チャットとエージェントのレイヤーを接続する方法については [AI サービス](/docs/configure/ai) と [AI Agents](/docs/build/agents) を、`default` データソースを支えるプライマリデータベースの設定については [Runtime](/docs/configure/runtime) を参照してください。 - -## セキュリティに関する注意 - -- **認証情報をインラインで書かないでください。** 上記のように、ホスト／ユーザー／パスワードを環境変数（またはシークレットマネージャー）から取得してください。 -- 書き込むつもりのないシステムには**読み取り専用接続を使用してください** — ソースの `readOnly` ケーパビリティ（または読み取り専用 DB ユーザー）を設定して、誤った書き込みが本番に到達できないようにします。 -- **権限でスコープを限定してください。** オブジェクトレベルおよびフィールドレベルの権限は、ネイティブオブジェクトとまったく同じように接続データにも適用されます。 - -## ロードマップ: 製品内の外部データソースフェデレーション - -上記のフロー — データベースを接続し、オブジェクトをモデル化し、コーディングエージェントで生成する — は、同梱のビルディングブロックで今日機能します。よりリッチな**ターンキー型フェデレーション**体験が [ADR-0015](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0015-external-datasource-federation.md)（ステータス: *Proposed*）の下で活発に設計中です。計画されている、**まだ出荷されていない**もの: - -- ObjectOS が、所有して**いない**テーブルを移行しようとせずにバインドできるようにする `schemaMode`（`managed` / `external` / `validate-only`）。 -- オブジェクトのフィールドを既存のカラムにマッピングする、オブジェクト上の `external` バインディングサブレコード。 -- スキーマをインポートして 1 ステップでオブジェクトをスキャフォールドする `os datasource introspect` / `validate` CLI。 -- 外部所有のスキーマに対する起動時および書き込み時の**安全ゲート**、加えてフロー全体のための Studio ウィザード。 - -それらが実現するまでは、ドキュメント化された経路を優先してください。データソースを宣言し、オブジェクト（生成またはハンドライト）をバインドし、まず非本番のコピーに対して検証します。 - -## 次に読むべきもの - -- [Runtime](/docs/configure/runtime) — `default` の背後にあるプライマリデータベース -- [AI サービス](/docs/configure/ai) — チャット、埋め込み、RAG、MCP -- [AI Agents](/docs/build/agents) — オブジェクトに対する宣言的なエージェント -- [Objects](/docs/build/objects) — `ObjectSchema.create` の作成サーフェス -- [`examples/app-crm` datasources](https://github.com/objectstack-ai/objectstack/tree/main/examples/app-crm/src/datasources) — 実際のデータソース + ルーティングの例 diff --git a/content/docs/configure/data-sources.ko.mdx b/content/docs/configure/data-sources.ko.mdx deleted file mode 100644 index 4c4e1f6..0000000 --- a/content/docs/configure/data-sources.ko.mdx +++ /dev/null @@ -1,180 +0,0 @@ ---- -title: 데이터 소스 -description: ObjectOS를 기존 비즈니스 데이터베이스에 연결하고, 객체를 해당 데이터베이스로 라우팅하며, AI가 데이터를 네이티브하게 쿼리하도록 하세요. -translation: - source_sha: c1e0954576877e1498f592a5b73c5848b9cefbfe3e27a962bd809d3b2db132b9 - guide_rev: 1 - mode: auto ---- - -**datasource**는 외부 데이터 저장소에 대한 이름이 지정된 연결입니다. 데이터 소스를 선언함으로써 ObjectOS를 비즈니스가 이미 운영 중인 데이터베이스 — 프로덕션 PostgreSQL, 리포팅용 MySQL 복제본, MongoDB 클러스터 — 로 지정한 다음, 객체를 거기에 바인딩합니다. 객체가 일단 바인딩되면 플랫폼의 나머지 모든 것(REST/GraphQL API, 권한, 플로우, 대시보드, 그리고 **AI 에이전트**)이 행이 물리적으로 어디에 있는지 신경 쓰지 않고 해당 데이터에 대해 균일하게 동작합니다. - -이것은 ObjectOS의 가장 실용적인 도입 경로 중 하나입니다: 레거시 시스템을 마이그레이션하는 대신, 거기에 연결하고, 관심 있는 테이블을 객체로 모델링한 다음, 데이터를 있는 그대로 두면서 그 위에 **AI 네이티브 기능** — 채팅, 분석, 자동화 — 으로 확장합니다. - -## 데이터 소스란 - -각 데이터 소스는 `DatasourceSchema`로 검증되는 평범한 객체입니다. 핵심 필드는 다음과 같습니다: - -| 필드 | 용도 | -|---|---| -| `name` | 객체가 참조하는 고유 식별자 (`^[a-z_][a-z0-9_]*$`) | -| `label` | 사람이 읽을 수 있는 표시 이름 | -| `driver` | 연결을 처리하는 드라이버 (`postgres`, `mysql`, `sqlite`, `mongodb`, `memory`, 또는 플러그인이 제공하는 드라이버) | -| `config` | 드라이버별 연결 설정 (host, database, 자격 증명, …) | -| `pool` | 연결 풀 크기 (`min`, `max`, 타임아웃) | -| `readReplicas` | 선택적 읽기 전용 복제본 구성 | -| `capabilities` | 드라이버가 푸시다운할 수 있다고 알리는 내용을 재정의 | -| `healthCheck` | 활성 상태 프로브 간격/타임아웃 | -| `active` | 연결 활성화 여부 | - -기본 제공되는 드라이버는 다음과 같습니다: - -| 드라이버 패키지 | `driver` | 백엔드 | -|---|---|---| -| `@objectstack/driver-sql` | `postgres`, `mysql`, `sqlite` | PostgreSQL, MySQL, SQLite (knex 경유) | -| `@objectstack/driver-mongodb` | `mongodb` | MongoDB | -| `@objectstack/driver-memory` | `memory` | 인프로세스 (테스트, 데모) | -| `@objectstack/driver-sqlite-wasm` | `sqlite` (WASM) | WebContainers / 브라우저의 SQLite | - -## 데이터 소스 선언하기 - -데이터 소스는 스택에 선언되며 `defineStack`으로 조립됩니다. 각 연결을 타입이 지정된 `Datasource` 객체로 정의한 다음, `datasources` 아래에 나열하세요: - -```ts -// src/datasources/business.datasource.ts -import type { Datasource } from '@objectstack/spec'; - -// 기존 프로덕션 데이터베이스에 연결합니다. 자격 증명은 환경에서 -// 가져옵니다 — 소스에 비밀 값을 인라인으로 넣지 마세요. -export const BusinessDb: Datasource = { - name: 'business_primary', - label: 'Business System (Postgres)', - driver: 'postgres', - config: { - connection: { - host: process.env.BIZ_DB_HOST, - port: Number(process.env.BIZ_DB_PORT ?? 5432), - user: process.env.BIZ_DB_USER, - password: process.env.BIZ_DB_PASSWORD, - database: process.env.BIZ_DB_NAME, - }, - }, - pool: { min: 1, max: 10 }, - active: true, -}; -``` - -```ts -// objectstack.config.ts -import { defineStack } from '@objectstack/spec'; -import * as objects from './src/objects/index.js'; -import { BusinessDb } from './src/datasources/business.datasource.js'; - -export default defineStack({ - manifest: { id: 'app.example.crm-extend', namespace: 'biz', version: '1.0.0' }, - datasources: [BusinessDb], - objects: Object.values(objects), -}); -``` - -> `defineDatasource()` 헬퍼는 **없습니다**. 데이터 소스는 `datasources` 배열에 넣는 `Datasource` 객체일 뿐입니다 — 프레임워크 저장소의 `examples/app-crm` 스택이 하는 것과 정확히 동일합니다. - -## 객체를 데이터 소스에 바인딩하기 - -모든 객체에는 `datasource` 필드가 있습니다. 기본값은 `'default'`(기본 데이터베이스)입니다. 특정 객체를 연결된 시스템 중 하나로 라우팅하려면 이 값을 설정하세요: - -```ts -import { ObjectSchema, Field } from '@objectstack/spec/data'; - -export const Customer = ObjectSchema.create({ - name: 'biz_customer', - label: 'Customer', - datasource: 'business_primary', // ← 읽기/쓰기가 비즈니스 DB로 전달됨 - fields: { - name: Field.text({ label: 'Name', required: true }), - email: Field.text({ label: 'Email' }), - tier: Field.select({ label: 'Tier', options: [/* … */] }), - }, -}); -``` - -### `datasourceMapping`을 사용한 중앙 집중식 라우팅 - -객체를 하나씩 바인딩하는 것은 소수일 때는 괜찮습니다. 네임스페이스나 패키지 전체에 대해서는 스택에 라우팅 규칙을 한 번 선언하세요. 규칙은 순서대로(또는 `priority`에 따라) 평가되며, 첫 번째 일치가 우선합니다: - -```ts -export default defineStack({ - datasources: [BusinessDb, AnalyticsReplica], - datasourceMapping: [ - { namespace: 'biz', datasource: 'business_primary' }, - { objectPattern: 'report_*', datasource: 'analytics_replica' }, - { package: 'com.example.logs', datasource: 'business_primary' }, - { default: true, datasource: 'default' }, - ], -}); -``` - -규칙은 `namespace`, `package`, `objectPattern`(glob), 또는 `default`로 일치하며, 대상 `datasource`를 지정합니다. 이렇게 하면 데이터 거주(data-residency) 결정이 객체 파일 전반에 흩어지는 대신 한곳에 모입니다. - -## 기존 테이블에서 객체 생성하기 - -모든 테이블에 대해 객체를 손으로 작성할 필요는 없습니다. 오늘날 레거시 스키마를 ObjectOS로 가져오는 가장 빠른 방법은 **코딩 에이전트(Claude Code)를 사용하여 비즈니스 테이블을 스캔하고 소스 수준의 객체 정의를 생성**하는 것입니다 — 테이블당 하나의 `*.object.ts` 파일로, 프레임워크가 기대하는 형태 그대로입니다. - -[`hotcrm`](https://github.com/objectstack-ai/hotcrm) 레퍼런스 앱이 그 형태의 표준 예시입니다: 각 테이블은 `Field.*` 정의와 함께 `ObjectSchema.create({ … })`를 사용하는 `src/objects/.object.ts` 파일이며, 모두 `defineStack`으로 조립됩니다. 일반적인 흐름은 다음과 같습니다: - -1. 비즈니스 데이터베이스를 데이터 소스로 **연결**합니다(위 참조). -2. **Claude Code를 스키마로 지정합니다.** 연결된 데이터베이스 — 테이블 이름, 컬럼, 타입, 외래 키 — 를 인트로스펙션하고, SQL 컬럼을 `Field.*` 타입에 매핑하고 외래 키를 `Field.lookup(...)`에 매핑하여 테이블당 하나의 `ObjectSchema.create` 파일을 생성하도록 요청하세요. 각 객체의 `datasource`를 연결로 설정하거나(또는 `datasourceMapping`에 의존하세요). -3. 생성된 객체를 **검토하고 다듬습니다** — 레이블, 필드 그룹, 검증, 권한을 추가하세요. 출력은 `hotcrm/src/objects/*.object.ts`와 마찬가지로 여러분이 소유하고 커밋하는 일반적인 소스입니다. -4. **실행합니다.** 이제 객체는 바인딩된 데이터 소스를 통해 기존 테이블을 읽고 씁니다. - -생성된 객체가 평범한 소스이기 때문에 완전한 제어권을 갖습니다: 맞는 것은 유지하고, 노출하고 싶지 않은 컬럼은 버리고, 플랫폼이 소유할 필요가 전혀 없었던 데이터베이스 위에 ObjectOS 기능(이력 추적, 활동, 공유 규칙)을 계층화하세요. - -## 기능 인식 쿼리 푸시다운 - -각 데이터 소스는 `DatasourceCapabilities`를 알립니다 — 필터, 정렬, 페이지네이션, 집계, 조인, 전문(full-text) 검색, 트랜잭션 등을 처리할 수 있는지 여부입니다. ObjectQL은 이를 사용하여 데이터베이스에 **푸시다운**할 것과 메모리에서 평가할 것을 결정합니다: - -| 기능 | 지원될 때의 효과 | -|---|---| -| `queryFilters` | `WHERE` 절이 데이터베이스에서 실행됨 | -| `querySorting` / `queryPagination` | `ORDER BY` / `LIMIT`이 서버 측에서 실행됨 | -| `queryAggregations` | `GROUP BY` / 집계가 서버 측에서 실행됨 | -| `joins` | 관련 객체 조인이 서버 측에서 실행됨 | -| `fullTextSearch` | 검색이 네이티브 인덱스를 사용함 | -| `readOnly` | 연결이 쓰기를 거부함 | - -기능이 풍부한 SQL 데이터 소스는 거의 모든 것을 푸시다운합니다. 제한적이거나 읽기 전용인 소스는 동일한 쿼리 결과를 얻지만, 더 많은 작업이 엔진에서 수행됩니다. 드라이버 기본값보다 더 잘 알고 있을 때는 `capabilities` 필드를 통해 데이터 소스별로 알려진 기능 집합을 재정의할 수 있습니다. - -## 연결된 데이터에 대한 AI - -테이블이 일단 객체로 모델링되면 **AI 계층이 무료로 그 위에서 동작합니다**. ObjectOS의 에이전트와 도구 — `list_objects`, `describe_object`, `query_records`, `aggregate_data`, 그리고 데이터 채팅 에이전트 — 는 모두 ObjectQL을 거치며, ObjectQL은 각 객체를 바인딩된 데이터 소스로 라우팅합니다. 이것이 의미하는 바는: - -- 사용자가 레거시 비즈니스 시스템에 있는 데이터에 대해 **자연어로 질문할 수 있고**, 답은 실제 행에 대해 계산됩니다. -- 도구 호출과 쿼리는 **호출하는 사용자의 권한**을 존중합니다 — AI는 로그인한 사용자에게 허용된 것보다 더 많이 보지 못합니다. -- 동일한 에이전트, 플로우, 대시보드가 객체가 기본 데이터베이스에 의해 뒷받침되든 외부 비즈니스 시스템에 의해 뒷받침되든 동작합니다. - -채팅 및 에이전트 계층을 연결하는 방법은 [AI 서비스](/docs/configure/ai)와 [AI Agents](/docs/build/agents)를 참고하고, `default` 데이터 소스를 뒷받침하는 기본 데이터베이스 구성은 [Runtime](/docs/configure/runtime)을 참고하세요. - -## 보안 참고 사항 - -- **자격 증명을 인라인으로 넣지 마세요.** 위에서 보여준 것처럼 host/user/password를 환경 변수(또는 시크릿 매니저)에서 가져오세요. -- 쓸 의도가 없는 시스템에는 **읽기 전용 연결을 사용하세요** — 소스의 `readOnly` 기능(또는 읽기 전용 DB 사용자)을 설정하여 우발적인 쓰기가 프로덕션에 도달하지 못하게 하세요. -- **권한으로 범위를 지정하세요.** 객체 및 필드 수준 권한은 네이티브 객체에 적용되는 것과 정확히 동일하게 연결된 데이터에 적용됩니다. - -## 로드맵: 제품 내 외부 데이터 소스 페더레이션 - -위의 흐름 — 데이터베이스 연결, 객체 모델링, 코딩 에이전트로 생성 — 은 기본 제공 빌딩 블록으로 오늘날 동작합니다. 더 풍부한 **턴키(turn-key) 페더레이션** 경험이 [ADR-0015](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0015-external-datasource-federation.md)(상태: *Proposed*) 아래에서 활발히 설계되고 있습니다. 계획되어 있지만 **아직 출시되지 않은** 것들: - -- ObjectOS가 소유하지 **않은** 테이블을 마이그레이션하려 시도하지 않고 바인딩할 수 있도록 하는 `schemaMode`(`managed` / `external` / `validate-only`). -- 객체 필드를 기존 컬럼에 매핑하는 객체의 `external` 바인딩 하위 레코드. -- 한 단계로 스키마를 가져오고 객체를 스캐폴딩하는 `os datasource introspect` / `validate` CLI. -- 외부 소유 스키마에 대한 부팅 시점 및 쓰기 시점 **안전 게이트**, 그리고 전체 흐름을 위한 Studio 마법사. - -이것들이 출시되기 전까지는 문서화된 경로를 선호하세요: 데이터 소스를 선언하고, 객체를 바인딩하고(생성된 것이든 손으로 작성한 것이든), 먼저 비프로덕션 사본에 대해 검증하세요. - -## 다음으로 갈 곳 - -- [Runtime](/docs/configure/runtime) — `default` 뒤에 있는 기본 데이터베이스 -- [AI 서비스](/docs/configure/ai) — 채팅, 임베딩, RAG, MCP -- [AI Agents](/docs/build/agents) — 객체에 대한 선언적 에이전트 -- [Objects](/docs/build/objects) — `ObjectSchema.create` 작성 인터페이스 -- [`examples/app-crm` 데이터 소스](https://github.com/objectstack-ai/objectstack/tree/main/examples/app-crm/src/datasources) — 실제 데이터 소스 + 라우팅 예제 diff --git a/content/docs/configure/data-sources.zh-Hans.mdx b/content/docs/configure/data-sources.zh-Hans.mdx deleted file mode 100644 index 003e700..0000000 --- a/content/docs/configure/data-sources.zh-Hans.mdx +++ /dev/null @@ -1,215 +0,0 @@ ---- -title: 数据源 -description: 把 ObjectOS 接入你现有的业务数据库,路由对象,并让 AI 原生地查询这些数据。 -translation: - source_sha: c1e0954576877e1498f592a5b73c5848b9cefbfe3e27a962bd809d3b2db132b9 - guide_rev: 1 - mode: auto ---- - -**数据源(datasource)** 是一个指向外部数据存储的具名连接。通过声明数据源, -你可以把 ObjectOS 指向企业本就在运行的数据库 —— 生产环境的 PostgreSQL、 -做报表的 MySQL 只读副本、MongoDB 集群 —— 然后把对象绑定到它们之上。对象一旦 -绑定,平台里的其它一切(REST/GraphQL API、权限、流程、仪表盘,以及 **AI Agent**) -都会统一地作用于这些数据,而不关心数据物理上存在哪里。 - -这是 ObjectOS 最实用的落地路径之一:你不必迁移遗留系统,而是连上它、把你关心 -的表建模成对象,再在**保持数据原地不动**的前提下,为它叠加 AI 原生能力 —— -对话、分析、自动化。 - -## 数据源是什么 - -每个数据源都是由 `DatasourceSchema` 校验的普通对象。核心字段: - -| 字段 | 用途 | -|---|---| -| `name` | 对象引用的唯一标识(`^[a-z_][a-z0-9_]*$`) | -| `label` | 可读的展示名 | -| `driver` | 处理连接的驱动(`postgres`、`mysql`、`sqlite`、`mongodb`、`memory`,或插件贡献的驱动) | -| `config` | 驱动相关的连接设置(host、database、凭据……) | -| `pool` | 连接池大小(`min`、`max`、超时) | -| `readReplicas` | 可选的只读副本配置 | -| `capabilities` | 覆盖驱动声明的可下推能力 | -| `healthCheck` | 存活探测的间隔/超时 | -| `active` | 连接是否启用 | - -已发布的驱动: - -| 驱动包 | `driver` | 后端 | -|---|---|---| -| `@objectstack/driver-sql` | `postgres`、`mysql`、`sqlite` | PostgreSQL、MySQL、SQLite(经 knex) | -| `@objectstack/driver-mongodb` | `mongodb` | MongoDB | -| `@objectstack/driver-memory` | `memory` | 进程内(测试、演示) | -| `@objectstack/driver-sqlite-wasm` | `sqlite`(WASM) | WebContainer / 浏览器中的 SQLite | - -## 声明数据源 - -数据源声明在 stack 上,并由 `defineStack` 汇编。把每个连接定义成一个带类型的 -`Datasource` 对象,再列入 `datasources`: - -```ts -// src/datasources/business.datasource.ts -import type { Datasource } from '@objectstack/spec'; - -// 连接一个【已有的】生产数据库。凭据来自环境变量 —— 切勿把密钥写死在源码里。 -export const BusinessDb: Datasource = { - name: 'business_primary', - label: 'Business System (Postgres)', - driver: 'postgres', - config: { - connection: { - host: process.env.BIZ_DB_HOST, - port: Number(process.env.BIZ_DB_PORT ?? 5432), - user: process.env.BIZ_DB_USER, - password: process.env.BIZ_DB_PASSWORD, - database: process.env.BIZ_DB_NAME, - }, - }, - pool: { min: 1, max: 10 }, - active: true, -}; -``` - -```ts -// objectstack.config.ts -import { defineStack } from '@objectstack/spec'; -import * as objects from './src/objects/index.js'; -import { BusinessDb } from './src/datasources/business.datasource.js'; - -export default defineStack({ - manifest: { id: 'app.example.crm-extend', namespace: 'biz', version: '1.0.0' }, - datasources: [BusinessDb], - objects: Object.values(objects), -}); -``` - -> **不存在** `defineDatasource()` 这样的辅助函数。数据源就是你放进 `datasources` -> 数组里的一个 `Datasource` 对象 —— 与框架仓库里 `examples/app-crm` stack 的做法 -> 完全一致。 - -## 把对象绑定到数据源 - -每个对象都有 `datasource` 字段,默认是 `'default'`(主数据库)。把它设为你已连接 -的某个系统,即可路由特定对象: - -```ts -import { ObjectSchema, Field } from '@objectstack/spec/data'; - -export const Customer = ObjectSchema.create({ - name: 'biz_customer', - label: 'Customer', - datasource: 'business_primary', // ← 读写都走业务库 - fields: { - name: Field.text({ label: 'Name', required: true }), - email: Field.text({ label: 'Email' }), - tier: Field.select({ label: 'Tier', options: [/* … */] }), - }, -}); -``` - -### 用 `datasourceMapping` 做集中路由 - -逐个绑定对象适合少量场景。要路由整个命名空间或包,就在 stack 上声明一次路由规则。 -规则按顺序(或按 `priority`)求值,首个命中者生效: - -```ts -export default defineStack({ - datasources: [BusinessDb, AnalyticsReplica], - datasourceMapping: [ - { namespace: 'biz', datasource: 'business_primary' }, - { objectPattern: 'report_*', datasource: 'analytics_replica' }, - { package: 'com.example.logs', datasource: 'business_primary' }, - { default: true, datasource: 'default' }, - ], -}); -``` - -规则可按 `namespace`、`package`、`objectPattern`(glob)或 `default` 匹配,并指定 -目标 `datasource`。这样数据驻留的决策集中在一处,而不是散落在各个对象文件里。 - -## 从既有表生成对象 - -你不必为每张表手写对象。如今把遗留 schema 引入 ObjectOS 最快的方式,是**用编码 -Agent(Claude Code)扫描业务表并生成源码级的对象定义** —— 每张表一个 -`*.object.ts` 文件,形态正是框架所期望的。 - -[`hotcrm`](https://github.com/objectstack-ai/hotcrm) 参考应用就是这种形态的范例: -每张表是一个 `src/objects/.object.ts` 文件,用 `ObjectSchema.create({ … })` -加 `Field.*` 定义,全部由 `defineStack` 汇编。典型流程: - -1. **连接**业务数据库为数据源(见上)。 -2. **让 Claude Code 对准 schema。** 让它内省已连接的数据库 —— 表名、列、类型、 - 外键 —— 为每张表生成一个 `ObjectSchema.create` 文件,把 SQL 列映射到 `Field.*` - 类型、把外键映射到 `Field.lookup(...)`。给每个对象设好 `datasource`(或交给 - `datasourceMapping`)。 -3. **审阅与打磨**生成的对象 —— 补上 label、字段分组、校验与权限。产物就是你拥有 - 并提交的普通源码,和 `hotcrm/src/objects/*.object.ts` 一样。 -4. **运行。** 这些对象此刻便通过绑定的数据源读写你既有的表。 - -因为生成的对象是普通源码,你拥有完全的控制权:保留合适的、丢弃不想暴露的列,并在 -一个平台从不需要拥有的数据库之上叠加 ObjectOS 的能力(历史追踪、活动、共享规则)。 - -## 能力感知的查询下推 - -每个数据源都会声明 `DatasourceCapabilities` —— 是否支持过滤、排序、分页、聚合、 -连接、全文检索、事务等。ObjectQL 据此决定哪些**下推**到数据库、哪些在内存中求值: - -| 能力 | 支持时的效果 | -|---|---| -| `queryFilters` | `WHERE` 子句在数据库执行 | -| `querySorting` / `queryPagination` | `ORDER BY` / `LIMIT` 在服务端执行 | -| `queryAggregations` | `GROUP BY` / 聚合在服务端执行 | -| `joins` | 关联对象的连接在服务端执行 | -| `fullTextSearch` | 检索命中原生索引 | -| `readOnly` | 该连接拒绝写入 | - -一个能力完备的 SQL 数据源几乎能把所有操作下推;能力受限或只读的数据源得到相同的 -查询结果,只是引擎要多做一些工作。当你比驱动更清楚时,可通过 `capabilities` 字段 -按数据源覆盖其声明的能力集。 - -## 在已连接数据上用 AI - -一旦表被建模为对象,**AI 层就免费可用**。ObjectOS 的 Agent 与工具 —— -`list_objects`、`describe_object`、`query_records`、`aggregate_data` 以及 -data-chat agent —— 都经由 ObjectQL,后者会把每个对象路由到它绑定的数据源。这意味着: - -- 用户可以用**自然语言提问**那些存放在遗留业务系统里的数据,答案是针对真实记录 - 计算出来的。 -- 工具调用与查询遵守**调用者本人的权限** —— AI 永远看不到超出登录用户被允许范围 - 的内容。 -- 不论对象由主数据库还是外部业务系统支撑,同一批 Agent、流程、仪表盘都照常工作。 - -参见 [AI 服务](/docs/configure/ai) 与 [AI Agent](/docs/build/agents) 了解如何接好 -对话与 Agent 层,以及 [运行时](/docs/configure/runtime) 了解支撑 `default` 数据源 -的主数据库配置。 - -## 安全须知 - -- **切勿把凭据写死。** 像上面那样从环境变量(或密钥管理器)读取 host/user/password。 -- **对不打算写入的系统使用只读连接** —— 设置数据源的 `readOnly` 能力(或使用只读 - 的数据库账号),让误写无法触及生产。 -- **用权限收口。** 对象级与字段级权限对已连接数据的约束,与原生对象完全一致。 - -## 路线图:产品内置的外部数据源联邦 - -上面的流程 —— 连接数据库、建模对象、用编码 Agent 生成 —— 借助已发布的能力今天就 -能用。更完善的**一键式联邦**体验正在 -[ADR-0015](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0015-external-datasource-federation.md) -下积极设计中(状态:*Proposed*)。计划中、**尚未发布**的内容: - -- `schemaMode`(`managed` / `external` / `validate-only`),让 ObjectOS 能绑定到它 - **并不拥有**的表,而不去尝试迁移它们。 -- 对象上的 `external` 绑定子记录,把对象字段映射到既有列。 -- `os datasource introspect` / `validate` CLI,一步导入 schema 并脚手架出对象。 -- 面向外部所属 schema 的启动期与写入期**安全闸门**,以及覆盖整个流程的 Studio 向导。 - -在它们落地之前,请优先采用已记录的路径:声明数据源、绑定对象(生成的或手写的), -并先在非生产副本上验证。 - -## 下一步去哪 - -- [运行时](/docs/configure/runtime) —— `default` 背后的主数据库 -- [AI 服务](/docs/configure/ai) —— 对话、嵌入、RAG、MCP -- [AI Agent](/docs/build/agents) —— 作用于你对象之上的声明式 Agent -- [对象](/docs/build/objects) —— `ObjectSchema.create` 的编写界面 -- [`examples/app-crm` 数据源](https://github.com/objectstack-ai/objectstack/tree/main/examples/app-crm/src/datasources) —— 一个真实的数据源 + 路由示例 diff --git a/content/docs/configure/data-sources.zh-Hant.mdx b/content/docs/configure/data-sources.zh-Hant.mdx deleted file mode 100644 index 0e3eb5c..0000000 --- a/content/docs/configure/data-sources.zh-Hant.mdx +++ /dev/null @@ -1,216 +0,0 @@ ---- -# @generated zh-Hant from zh-Hans -- do not edit. Edit the English source, then regenerate: pnpm --filter @objectos/docs gen:zh-hant -title: 資料來源 -description: 把 ObjectOS 接入你現有的業務資料庫,路由物件,並讓 AI 原生地查詢這些資料。 -translation: - source_sha: c1e0954576877e1498f592a5b73c5848b9cefbfe3e27a962bd809d3b2db132b9 - guide_rev: 1 - mode: auto ---- - -**資料來源(datasource)** 是一個指向外部資料儲存的具名連線。通過宣告資料來源, -你可以把 ObjectOS 指向企業本就在執行的資料庫 —— 生產環境的 PostgreSQL、 -做報表的 MySQL 只讀副本、MongoDB 叢集 —— 然後把物件繫結到它們之上。物件一旦 -繫結,平臺裡的其它一切(REST/GraphQL API、許可權、流程、儀表盤,以及 **AI Agent**) -都會統一地作用於這些資料,而不關心資料物理上存在哪裡。 - -這是 ObjectOS 最實用的落地路徑之一:你不必遷移遺留系統,而是連上它、把你關心 -的表建模成物件,再在**保持資料原地不動**的前提下,為它疊加 AI 原生能力 —— -對話、分析、自動化。 - -## 資料來源是什麼 - -每個資料來源都是由 `DatasourceSchema` 校驗的普通物件。核心欄位: - -| 欄位 | 用途 | -|---|---| -| `name` | 物件引用的唯一標識(`^[a-z_][a-z0-9_]*$`) | -| `label` | 可讀的展示名 | -| `driver` | 處理連線的驅動(`postgres`、`mysql`、`sqlite`、`mongodb`、`memory`,或外掛貢獻的驅動) | -| `config` | 驅動相關的連線設定(host、database、憑據……) | -| `pool` | 連線池大小(`min`、`max`、超時) | -| `readReplicas` | 可選的只讀副本配置 | -| `capabilities` | 覆蓋驅動宣告的可下推能力 | -| `healthCheck` | 存活探測的間隔/超時 | -| `active` | 連線是否啟用 | - -已釋出的驅動: - -| 驅動包 | `driver` | 後端 | -|---|---|---| -| `@objectstack/driver-sql` | `postgres`、`mysql`、`sqlite` | PostgreSQL、MySQL、SQLite(經 knex) | -| `@objectstack/driver-mongodb` | `mongodb` | MongoDB | -| `@objectstack/driver-memory` | `memory` | 程序內(測試、演示) | -| `@objectstack/driver-sqlite-wasm` | `sqlite`(WASM) | WebContainer / 瀏覽器中的 SQLite | - -## 宣告資料來源 - -資料來源宣告在 stack 上,並由 `defineStack` 彙編。把每個連線定義成一個帶型別的 -`Datasource` 物件,再列入 `datasources`: - -```ts -// src/datasources/business.datasource.ts -import type { Datasource } from '@objectstack/spec'; - -// 连接一个【已有的】生产数据库。凭据来自环境变量 —— 切勿把密钥写死在源码里。 -export const BusinessDb: Datasource = { - name: 'business_primary', - label: 'Business System (Postgres)', - driver: 'postgres', - config: { - connection: { - host: process.env.BIZ_DB_HOST, - port: Number(process.env.BIZ_DB_PORT ?? 5432), - user: process.env.BIZ_DB_USER, - password: process.env.BIZ_DB_PASSWORD, - database: process.env.BIZ_DB_NAME, - }, - }, - pool: { min: 1, max: 10 }, - active: true, -}; -``` - -```ts -// objectstack.config.ts -import { defineStack } from '@objectstack/spec'; -import * as objects from './src/objects/index.js'; -import { BusinessDb } from './src/datasources/business.datasource.js'; - -export default defineStack({ - manifest: { id: 'app.example.crm-extend', namespace: 'biz', version: '1.0.0' }, - datasources: [BusinessDb], - objects: Object.values(objects), -}); -``` - -> **不存在** `defineDatasource()` 這樣的輔助函式。資料來源就是你放進 `datasources` -> 數組裡的一個 `Datasource` 物件 —— 與框架倉庫裡 `examples/app-crm` stack 的做法 -> 完全一致。 - -## 把物件繫結到資料來源 - -每個物件都有 `datasource` 欄位,預設是 `'default'`(主資料庫)。把它設為你已連線 -的某個系統,即可路由特定物件: - -```ts -import { ObjectSchema, Field } from '@objectstack/spec/data'; - -export const Customer = ObjectSchema.create({ - name: 'biz_customer', - label: 'Customer', - datasource: 'business_primary', // ← 读写都走业务库 - fields: { - name: Field.text({ label: 'Name', required: true }), - email: Field.text({ label: 'Email' }), - tier: Field.select({ label: 'Tier', options: [/* … */] }), - }, -}); -``` - -### 用 `datasourceMapping` 做集中路由 - -逐個繫結物件適合少量場景。要路由整個名稱空間或包,就在 stack 上宣告一次路由規則。 -規則按順序(或按 `priority`)求值,首個命中者生效: - -```ts -export default defineStack({ - datasources: [BusinessDb, AnalyticsReplica], - datasourceMapping: [ - { namespace: 'biz', datasource: 'business_primary' }, - { objectPattern: 'report_*', datasource: 'analytics_replica' }, - { package: 'com.example.logs', datasource: 'business_primary' }, - { default: true, datasource: 'default' }, - ], -}); -``` - -規則可按 `namespace`、`package`、`objectPattern`(glob)或 `default` 匹配,並指定 -目標 `datasource`。這樣資料駐留的決策集中在一處,而不是散落在各個物件檔案裡。 - -## 從既有表生成物件 - -你不必為每張表手寫物件。如今把遺留 schema 引入 ObjectOS 最快的方式,是**用編碼 -Agent(Claude Code)掃描業務表並生成原始碼級的物件定義** —— 每張表一個 -`*.object.ts` 檔案,形態正是框架所期望的。 - -[`hotcrm`](https://github.com/objectstack-ai/hotcrm) 參考應用就是這種形態的範例: -每張表是一個 `src/objects/.object.ts` 檔案,用 `ObjectSchema.create({ … })` -加 `Field.*` 定義,全部由 `defineStack` 彙編。典型流程: - -1. **連線**業務資料庫為資料來源(見上)。 -2. **讓 Claude Code 對準 schema。** 讓它內省已連線的資料庫 —— 表名、列、型別、 - 外部索引鍵 —— 為每張表生成一個 `ObjectSchema.create` 檔案,把 SQL 列對映到 `Field.*` - 型別、把外部索引鍵對映到 `Field.lookup(...)`。給每個物件設好 `datasource`(或交給 - `datasourceMapping`)。 -3. **審閱與打磨**生成的物件 —— 補上 label、欄位分組、校驗與許可權。產物就是你擁有 - 並提交的普通原始碼,和 `hotcrm/src/objects/*.object.ts` 一樣。 -4. **執行。** 這些物件此刻便通過繫結的資料來源讀寫你既有的表。 - -因為生成的物件是普通原始碼,你擁有完全的控制權:保留合適的、丟棄不想暴露的列,並在 -一個平臺從不需要擁有的資料庫之上疊加 ObjectOS 的能力(歷史追蹤、活動、共享規則)。 - -## 能力感知的查詢下推 - -每個資料來源都會宣告 `DatasourceCapabilities` —— 是否支援過濾、排序、分頁、聚合、 -連線、全文檢索、事務等。ObjectQL 據此決定哪些**下推**到資料庫、哪些在記憶體中求值: - -| 能力 | 支援時的效果 | -|---|---| -| `queryFilters` | `WHERE` 子句在資料庫執行 | -| `querySorting` / `queryPagination` | `ORDER BY` / `LIMIT` 在服務端執行 | -| `queryAggregations` | `GROUP BY` / 聚合在服務端執行 | -| `joins` | 關聯物件的連線在服務端執行 | -| `fullTextSearch` | 檢索命中原生索引 | -| `readOnly` | 該連線拒絕寫入 | - -一個能力完備的 SQL 資料來源幾乎能把所有操作下推;能力受限或只讀的資料來源得到相同的 -查詢結果,只是引擎要多做一些工作。當你比驅動更清楚時,可通過 `capabilities` 欄位 -按資料來源覆蓋其宣告的能力集。 - -## 在已連線資料上用 AI - -一旦表被建模為物件,**AI 層就免費可用**。ObjectOS 的 Agent 與工具 —— -`list_objects`、`describe_object`、`query_records`、`aggregate_data` 以及 -data-chat agent —— 都經由 ObjectQL,後者會把每個物件路由到它繫結的資料來源。這意味著: - -- 使用者可以用**自然語言提問**那些存放在遺留業務系統裡的資料,答案是針對真實記錄 - 計算出來的。 -- 工具呼叫與查詢遵守**呼叫者本人的許可權** —— AI 永遠看不到超出登入使用者被允許範圍 - 的內容。 -- 不論物件由主資料庫還是外部業務系統支撐,同一批 Agent、流程、儀表盤都照常工作。 - -參見 [AI 服務](/docs/configure/ai) 與 [AI Agent](/docs/build/agents) 瞭解如何接好 -對話與 Agent 層,以及 [執行時](/docs/configure/runtime) 瞭解支撐 `default` 資料來源 -的主資料庫配置。 - -## 安全須知 - -- **切勿把憑據寫死。** 像上面那樣從環境變數(或金鑰管理器)讀取 host/user/password。 -- **對不打算寫入的系統使用只讀連線** —— 設定資料來源的 `readOnly` 能力(或使用只讀 - 的資料庫賬號),讓誤寫無法觸及生產。 -- **用許可權收口。** 物件級與欄位級許可權對已連線資料的約束,與原生物件完全一致。 - -## 路線圖:產品內建的外部資料來源聯邦 - -上面的流程 —— 連線資料庫、建模物件、用編碼 Agent 生成 —— 藉助已釋出的能力今天就 -能用。更完善的**一鍵式聯邦**體驗正在 -[ADR-0015](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0015-external-datasource-federation.md) -下積極設計中(狀態:*Proposed*)。計劃中、**尚未釋出**的內容: - -- `schemaMode`(`managed` / `external` / `validate-only`),讓 ObjectOS 能繫結到它 - **並不擁有**的表,而不去嘗試遷移它們。 -- 物件上的 `external` 繫結子記錄,把物件欄位對映到既有列。 -- `os datasource introspect` / `validate` CLI,一步匯入 schema 並腳手架出物件。 -- 面向外部所屬 schema 的啟動期與寫入期**安全閘門**,以及覆蓋整個流程的 Studio 嚮導。 - -在它們落地之前,請優先採用已記錄的路徑:宣告資料來源、繫結物件(生成的或手寫的), -並先在非生產副本上驗證。 - -## 下一步去哪 - -- [執行時](/docs/configure/runtime) —— `default` 背後的主資料庫 -- [AI 服務](/docs/configure/ai) —— 對話、嵌入、RAG、MCP -- [AI Agent](/docs/build/agents) —— 作用於你物件之上的宣告式 Agent -- [物件](/docs/build/objects) —— `ObjectSchema.create` 的編寫介面 -- [`examples/app-crm` 資料來源](https://github.com/objectstack-ai/objectstack/tree/main/examples/app-crm/src/datasources) —— 一個真實的資料來源 + 路由示例 diff --git a/content/docs/extend-existing-systems.de.mdx b/content/docs/extend-existing-systems.de.mdx deleted file mode 100644 index f4ae444..0000000 --- a/content/docs/extend-existing-systems.de.mdx +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: Bestehende Systeme erweitern -description: Verbinde ObjectOS mit den Geschäftssystemen, die du bereits betreibst, und ergänze KI-native Abfrage, Analyse und Automatisierung — ohne Migration. -translation: - source_sha: 42c3777ffcd0a04595702771b91a9d63c55c7d9ea53ec9bb4da477b74d74b63a - guide_rev: 1 - mode: auto ---- - -Die meisten Teams, die ObjectOS evaluieren, haben bereits ein System of -Record — ein CRM, ein ERP, ein Ticketing-Tool, ein selbstgebautes Back -Office, das auf einer produktiven SQL- oder MongoDB-Datenbank läuft. Die -Frage lautet selten „Sollten wir es wegwerfen und neu bauen?". Sie -lautet „Können wir das, was wir bereits haben, **KI-nativ** machen, -ohne eine riskante Migration?" - -Genau diesen Weg beschreibt diese Seite: **Verbinde ObjectOS mit deiner -bestehenden Datenbank, modelliere die Tabellen, die dir wichtig sind, -als Objekte und lass KI-Agenten diese Daten abfragen, analysieren und -darauf handeln** — unter deinen Berechtigungen, auf deiner -Infrastruktur, ohne dass das Originalsystem angetastet wird. - -## Die Form des Schritts - -Du ersetzt dein Geschäftssystem nicht. Du stellst ObjectOS *daneben* und -richtest es auf dieselbe Datenbank: - -1. **Verbinde** die bestehende Datenbank als [Datasource](/docs/configure/data-sources). - Die Anmeldedaten kommen aus deiner Umgebung; die Verbindung kann - read-only sein, wenn du nur analysieren möchtest. -2. **Modelliere** die Tabellen als Objekte — von Hand oder indem du einen - Coding-Agenten das Schema scannen und quellbasierte Objektdateien für - dich generieren lässt. -3. **Binde** jedes Objekt an die Datasource (pro Objekt oder mit einer - Routing-Regel für einen ganzen Namespace). -4. **Nutze KI** — sobald eine Tabelle ein Objekt ist, arbeitet jeder - Agent, jedes Tool, jeder Flow und jedes Dashboard damit, automatisch - an die richtige Datenbank geroutet. - -An der Legacy-Anwendung ändert sich nichts. Die Datensätze bleiben, wo -sie sind. ObjectOS wird die KI-native, berechtigungsbewusste -Oberfläche obendrauf. - -## Warum das ohne Neuschreiben funktioniert - -| Bedenken | Wie ObjectOS damit umgeht | -|---|---| -| „Wir können die Daten nicht verschieben" | Die Daten werden nie verschoben. ObjectOS verbindet sich mit deiner Datenbank an Ort und Stelle. | -| „Wir können keine Schreibzugriffe auf die Produktion riskieren" | Binde Objekte an eine **read-only**-Datasource (oder einen read-only DB-Benutzer). Analysiere zuerst sicher; aktiviere Schreibzugriffe gezielt. | -| „Jede Tabelle zu modellieren ist wochenlange Arbeit" | Ein Coding-Agent scannt das Schema und generiert eine Objektdatei pro Tabelle — du prüfst und verfeinerst, du tippst nichts von Hand. | -| „Man kann KI nicht mit unseren Daten vertrauen" | Agenten laufen als der **angemeldete Benutzer** und gehorchen den Berechtigungen auf Objekt-, Datensatz- und Feldebene. Sie sehen nie mehr als die Person hinter ihnen. | -| „Unsere Daten dürfen unser Netzwerk nicht verlassen" | ObjectOS läuft in deiner Umgebung. Geschäftsdaten und Prompts bleiben innerhalb deines Perimeters. | - -## Objekte mit einem Coding-Agenten generieren - -Der schnellste Weg, ein bestehendes Schema einzubinden, ist die -Verwendung eines Coding-Agenten (wie Claude Code), um die -**Geschäftstabellen zu scannen und quellbasierte Objektdefinitionen zu -generieren** — eine `*.object.ts`-Datei pro Tabelle. - -Die Referenz-App [`hotcrm`](https://github.com/objectstack-ai/hotcrm) -zeigt die genaue Form, die diese Ausgabe annehmen sollte: Jede Tabelle -wird zu einer `src/objects/.object.ts` mit -`ObjectSchema.create({ … })` mit typisierten `Field.*`-Definitionen und -`Field.lookup(...)` für Fremdschlüssel, zusammengesetzt durch -`defineStack`. Der Agent introspiziert deine verbundene Datenbank, -mappt Spalten auf Feldtypen und schreibt Objekte, die dir gehören und -die du commitest. Du behältst, was passt, lässt Spalten weg, die du -nicht freigeben willst, und ergänzt obendrauf Labels, Validierungen und -Berechtigungen. - -Siehe [Data Sources](/docs/configure/data-sources) für den -vollständigen, schrittweisen Authoring-Leitfaden. - -## Was du am ersten Tag bekommst - -Sobald die Tabellen als Objekte modelliert und an deine bestehende -Datenbank gebunden sind: - -- **Natürlichsprachliche Analyse.** Nutzer stellen Fragen zu den echten - Datensätzen — „welche Deals sind dieses Quartal abgerutscht und wem - gehören sie?" — und die Antwort wird über ObjectQL gegen Live-Daten - berechnet. -- **Gesteuerte Automatisierung.** Flows und Aktionen können dieselben - Daten lesen und (wo erlaubt) schreiben, wobei jeder Schritt auditiert - wird. -- **Eine generierte API und Console.** REST-/GraphQL-Endpunkte und - Admin-Bildschirme stammen aus denselben Metadaten — keine zusätzliche - Integrationsschicht. -- **Ein einziges Berechtigungsmodell.** Die Grenze, die für Menschen - gilt, gilt identisch für KI-Traffic. - -## Wohin das führt - -Der obige Ablauf funktioniert heute mit ausgelieferten Bausteinen. Ein -reichhaltigeres, **schlüsselfertiges Federations**-Erlebnis — -einstufiger Schema-Import, Bindung extern verwalteter Schemas und -eingebaute Sicherheits-Gates — ist in aktiver Konzeption unter -[ADR-0015](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0015-external-datasource-federation.md) -(Status: *Proposed*). Bis es soweit ist, ist der dokumentierte Weg — -verbinden, modellieren, binden, abfragen — die unterstützte Art, ein -bestehendes System zu erweitern. - -## Hier starten - -- [Data Sources](/docs/configure/data-sources) — eine Datenbank verbinden, Objekte binden, Abfragen routen -- [AI Agents](/docs/build/agents) — deklarative Agenten über deinen Objekten -- [Permissions](/docs/configure/permissions) — das Modell, das KI erbt -- [Quickstart](/docs/quickstart) — eine Runtime in Minuten aufsetzen diff --git a/content/docs/extend-existing-systems.es.mdx b/content/docs/extend-existing-systems.es.mdx deleted file mode 100644 index b19f2d6..0000000 --- a/content/docs/extend-existing-systems.es.mdx +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: Extiende sistemas existentes -description: Conecta ObjectOS a los sistemas de negocio que ya operas, y luego añade consulta, análisis y automatización nativos de IA — sin una migración. -translation: - source_sha: 42c3777ffcd0a04595702771b91a9d63c55c7d9ea53ec9bb4da477b74d74b63a - guide_rev: 1 - mode: auto ---- - -La mayoría de los equipos que evalúan ObjectOS ya tienen un sistema de -registro — un CRM, un ERP, una herramienta de tickets, un back office -hecho en casa sobre una base de datos SQL o MongoDB de producción. La -pregunta rara vez es "¿deberíamos tirarlo y reconstruirlo?". Es "¿podemos -hacer que lo que ya tenemos sea **nativo de IA**, sin una migración -arriesgada?" - -Ese es exactamente el camino que describe esta página: **conecta ObjectOS -a tu base de datos existente, modela como objetos las tablas que te -importan, y deja que los agentes de IA consulten, analicen y actúen sobre -esos datos** — bajo tus permisos, en tu infraestructura, con el sistema -original intacto. - -## La forma de la jugada - -No reemplazas tu sistema de negocio. Pones ObjectOS *al lado* de él y lo -apuntas a la misma base de datos: - -1. **Conecta** la base de datos existente como un [datasource](/docs/configure/data-sources). - Las credenciales provienen de tu entorno; la conexión puede ser de - solo lectura si solo quieres analizar. -2. **Modela** las tablas como objetos — a mano, o dejando que un agente - de codificación escanee el esquema y genere por ti archivos de objetos - a nivel de código fuente. -3. **Vincula** cada objeto al datasource (por objeto, o con una regla de - enrutamiento para todo un namespace). -4. **Usa IA** — en el momento en que una tabla es un objeto, cada agente, - herramienta, flujo y panel funciona sobre ella, enrutado - automáticamente a la base de datos correcta. - -Nada de la aplicación heredada cambia. Las filas permanecen donde están. -ObjectOS se convierte en la superficie nativa de IA y consciente de -permisos por encima. - -## Por qué esto funciona sin una reescritura - -| Preocupación | Cómo lo maneja ObjectOS | -|---|---| -| "No podemos mover los datos" | Los datos nunca se mueven. ObjectOS se conecta a tu base de datos en su lugar. | -| "No podemos arriesgar escrituras en producción" | Vincula los objetos a un datasource de **solo lectura** (o a un usuario de BD de solo lectura). Analiza con seguridad primero; habilita las escrituras deliberadamente. | -| "Modelar cada tabla son semanas de trabajo" | Un agente de codificación escanea el esquema y genera un archivo de objeto por tabla — tú revisas y refinas, no escribes a mano. | -| "No se puede confiar a la IA nuestros datos" | Los agentes se ejecutan como el **usuario que ha iniciado sesión** y obedecen los permisos a nivel de objeto, de registro y de campo. Nunca ven más que la persona detrás de ellos. | -| "Nuestros datos no pueden salir de nuestra red" | ObjectOS se ejecuta en tu entorno. Los datos de negocio y los prompts permanecen dentro de tu perímetro. | - -## Generar objetos con un agente de codificación - -La forma más rápida de incorporar un esquema existente es usar un agente -de codificación (como Claude Code) para **escanear las tablas de negocio -y generar definiciones de objetos a nivel de código fuente** — un archivo -`*.object.ts` por tabla. - -La app de referencia [`hotcrm`](https://github.com/objectstack-ai/hotcrm) -muestra la forma exacta que debería tomar esa salida: cada tabla se -convierte en un `src/objects/.object.ts` usando -`ObjectSchema.create({ … })` con definiciones tipadas de `Field.*` y -`Field.lookup(...)` para las claves foráneas, ensamblado por -`defineStack`. El agente introspecciona tu base de datos conectada, mapea -las columnas a tipos de campo, y escribe objetos de los que eres dueño y -que confirmas. Conservas lo que encaja, descartas las columnas que no -quieres exponer, y añades etiquetas, validaciones y permisos por encima. - -Consulta [Data Sources](/docs/configure/data-sources) para la guía de -autoría completa, paso a paso. - -## Lo que obtienes el primer día - -Una vez que las tablas están modeladas como objetos vinculados a tu base -de datos existente: - -- **Análisis en lenguaje natural.** Los usuarios hacen preguntas sobre los - registros reales — "¿qué tratos se escaparon este trimestre y quién los - gestiona?" — y la respuesta se calcula sobre datos en vivo a través de - ObjectQL. -- **Automatización gobernada.** Los flujos y las acciones pueden leer y - (donde esté permitido) escribir los mismos datos, con cada paso - auditado. -- **Una API y una Console generadas.** Los endpoints REST/GraphQL y las - pantallas de administración provienen de los mismos metadatos — sin una - capa de integración adicional. -- **Un único modelo de permisos.** El límite que se aplica a los humanos - se aplica de forma idéntica al tráfico de IA. - -## Hacia dónde se dirige esto - -El flujo anterior funciona hoy con bloques de construcción ya -disponibles. Una experiencia de **federación llave en mano** más rica — -importación de esquemas en un solo paso, vinculación de esquemas de -propiedad externa, y barreras de seguridad integradas — está en diseño -activo bajo [ADR-0015](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0015-external-datasource-federation.md) -(estado: *Propuesto*). Hasta que llegue, el camino documentado — -conectar, modelar, vincular, consultar — es la forma soportada de -extender un sistema existente. - -## Empieza aquí - -- [Data Sources](/docs/configure/data-sources) — conecta una base de datos, vincula objetos, enruta consultas -- [AI Agents](/docs/build/agents) — agentes declarativos sobre tus objetos -- [Permissions](/docs/configure/permissions) — el modelo que la IA hereda -- [Quickstart](/docs/quickstart) — levanta un runtime en minutos diff --git a/content/docs/extend-existing-systems.fr.mdx b/content/docs/extend-existing-systems.fr.mdx deleted file mode 100644 index a8e9e23..0000000 --- a/content/docs/extend-existing-systems.fr.mdx +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: Étendre les systèmes existants -description: Connectez ObjectOS aux systèmes métier que vous exploitez déjà, puis ajoutez requêtes, analyses et automatisations natives IA — sans migration. -translation: - source_sha: 42c3777ffcd0a04595702771b91a9d63c55c7d9ea53ec9bb4da477b74d74b63a - guide_rev: 1 - mode: auto ---- - -La plupart des équipes qui évaluent ObjectOS disposent déjà d'un système -de référence — un CRM, un ERP, un outil de ticketing, un back-office -maison reposant sur une base de données SQL ou MongoDB en production. La -question n'est presque jamais « devrions-nous tout jeter et reconstruire ? ». -C'est « pouvons-nous rendre **natif IA** ce que nous avons déjà, sans -migration risquée ? » - -C'est exactement le parcours que décrit cette page : **connecter -ObjectOS à votre base de données existante, modéliser comme objets les -tables qui vous intéressent, et laisser les agents IA interroger, -analyser et agir sur ces données** — sous vos permissions, sur votre -infrastructure, le système d'origine restant intact. - -## La forme de la démarche - -Vous ne remplacez pas votre système métier. Vous placez ObjectOS *à -côté* de lui et le pointez vers la même base de données : - -1. **Connectez** la base de données existante comme [datasource](/docs/configure/data-sources). - Les identifiants proviennent de votre environnement ; la connexion - peut être en lecture seule si vous souhaitez uniquement analyser. -2. **Modélisez** les tables comme objets — à la main, ou en laissant un - agent de codage analyser le schéma et générer pour vous des fichiers - d'objets au niveau du code source. -3. **Liez** chaque objet à la datasource (par objet, ou avec une règle de - routage pour tout un espace de noms). -4. **Utilisez l'IA** — dès qu'une table est un objet, chaque agent, - outil, flux et tableau de bord fonctionne dessus, routé - automatiquement vers la bonne base de données. - -Rien ne change dans l'application héritée. Les lignes restent là où elles -sont. ObjectOS devient la surface native IA et consciente des -permissions par-dessus. - -## Pourquoi cela fonctionne sans réécriture - -| Préoccupation | Comment ObjectOS la gère | -|---|---| -| « Nous ne pouvons pas déplacer les données » | Les données ne se déplacent jamais. ObjectOS se connecte à votre base de données sur place. | -| « Nous ne pouvons pas risquer des écritures en production » | Liez les objets à une datasource en **lecture seule** (ou à un utilisateur de base de données en lecture seule). Analysez d'abord en toute sécurité ; activez les écritures délibérément. | -| « Modéliser chaque table prend des semaines » | Un agent de codage analyse le schéma et génère un fichier d'objet par table — vous révisez et affinez, vous ne tapez pas tout à la main. | -| « On ne peut pas confier nos données à l'IA » | Les agents s'exécutent en tant qu'**utilisateur connecté** et obéissent aux permissions au niveau des objets, des enregistrements et des champs. Ils ne voient jamais plus que la personne qui se trouve derrière eux. | -| « Nos données ne peuvent pas quitter notre réseau » | ObjectOS s'exécute dans votre environnement. Les données métier et les prompts restent à l'intérieur de votre périmètre. | - -## Générer des objets avec un agent de codage - -Le moyen le plus rapide d'importer un schéma existant est d'utiliser un -agent de codage (tel que Claude Code) pour **analyser les tables métier -et générer des définitions d'objets au niveau du code source** — un -fichier `*.object.ts` par table. - -L'application de référence [`hotcrm`](https://github.com/objectstack-ai/hotcrm) -montre la forme exacte que devrait prendre cette sortie : chaque table -devient un `src/objects/.object.ts` utilisant -`ObjectSchema.create({ … })` avec des définitions `Field.*` typées et -`Field.lookup(...)` pour les clés étrangères, assemblées par -`defineStack`. L'agent introspecte votre base de données connectée, -mappe les colonnes vers des types de champs, et écrit des objets que vous -possédez et committez. Vous gardez ce qui convient, supprimez les -colonnes que vous ne voulez pas exposer, et ajoutez par-dessus des -libellés, des validations et des permissions. - -Consultez [Data Sources](/docs/configure/data-sources) pour le guide de -création complet, étape par étape. - -## Ce que vous obtenez dès le premier jour - -Une fois les tables modélisées comme objets liés à votre base de données -existante : - -- **Analyse en langage naturel.** Les utilisateurs posent des questions - sur les enregistrements réels — « quelles affaires ont glissé ce - trimestre et qui en est responsable ? » — et la réponse est calculée - sur des données en direct via ObjectQL. -- **Automatisation gouvernée.** Les flux et actions peuvent lire et (là - où c'est autorisé) écrire les mêmes données, chaque étape étant - auditée. -- **Une API et une Console générées.** Les points de terminaison - REST/GraphQL et les écrans d'administration proviennent des mêmes - métadonnées — aucune couche d'intégration supplémentaire. -- **Un seul modèle de permissions.** La frontière qui s'applique aux - humains s'applique à l'identique au trafic IA. - -## Vers où cela se dirige - -Le parcours ci-dessus fonctionne aujourd'hui avec les briques déjà -livrées. Une expérience de **fédération clé en main** plus riche — -import de schéma en une étape, liaison de schéma détenu en externe et -garde-fous de sécurité intégrés — est en cours de conception active sous -[ADR-0015](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0015-external-datasource-federation.md) -(statut : *Proposed*). En attendant son arrivée, le parcours documenté — -connecter, modéliser, lier, interroger — est la manière prise en charge -d'étendre un système existant. - -## Commencer ici - -- [Data Sources](/docs/configure/data-sources) — connecter une base de données, lier des objets, router les requêtes -- [AI Agents](/docs/build/agents) — des agents déclaratifs au-dessus de vos objets -- [Permissions](/docs/configure/permissions) — le modèle dont l'IA hérite -- [Quickstart](/docs/quickstart) — mettez un runtime en place en quelques minutes diff --git a/content/docs/extend-existing-systems.ja.mdx b/content/docs/extend-existing-systems.ja.mdx deleted file mode 100644 index 6563f40..0000000 --- a/content/docs/extend-existing-systems.ja.mdx +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: 既存システムを拡張する -description: すでに運用しているビジネスシステムに ObjectOS を接続し、移行なしで AI ネイティブなクエリ、分析、自動化を追加します。 -translation: - source_sha: 42c3777ffcd0a04595702771b91a9d63c55c7d9ea53ec9bb4da477b74d74b63a - guide_rev: 1 - mode: auto ---- - -ObjectOS を評価しているほとんどのチームは、すでにシステムオブレコードを -持っています — CRM、ERP、チケッティングツール、あるいは本番の SQL や -MongoDB データベース上に乗った自前のバックオフィスです。問われるのは -たいてい「捨てて作り直すべきか？」ではありません。「すでにあるものを、 -リスクの高い移行なしに **AI ネイティブ** にできるか？」です。 - -このページが説明するのはまさにその道筋です。**ObjectOS を既存の -データベースに接続し、必要なテーブルをオブジェクトとしてモデル化し、 -AI エージェントにそのデータをクエリ・分析・操作させる** — あなたの権限の -もとで、あなたのインフラ上で、元のシステムには一切手を加えずに。 - -## この移行のかたち - -ビジネスシステムを置き換えるわけではありません。ObjectOS をその *隣に* -置き、同じデータベースを指し示します。 - -1. 既存のデータベースを [datasource](/docs/configure/data-sources) として - **接続** します。認証情報は環境から取得され、分析だけが目的なら接続を - 読み取り専用にできます。 -2. テーブルをオブジェクトとして **モデル化** します — 手作業でもよいですし、 - コーディングエージェントにスキーマをスキャンさせて、ソースレベルの - オブジェクトファイルを生成させることもできます。 -3. 各オブジェクトを datasource に **バインド** します（オブジェクトごとに、 - または名前空間全体に対するルーティングルールで）。 -4. **AI を使う** — テーブルがオブジェクトになった瞬間、あらゆる - エージェント、ツール、フロー、ダッシュボードがその上で動作し、適切な - データベースへ自動的にルーティングされます。 - -レガシーアプリケーションに関しては何も変わりません。行はそのままの場所に -留まります。ObjectOS はその上に乗る AI ネイティブで権限を意識したサーフェスに -なります。 - -## なぜ書き直しなしで機能するのか - -| 懸念 | ObjectOS の対処方法 | -|---|---| -| 「データを動かせない」 | データは一切動きません。ObjectOS はあなたのデータベースにそのまま接続します。 | -| 「本番への書き込みはリスクが大きすぎる」 | オブジェクトを **読み取り専用** の datasource（または読み取り専用の DB ユーザー）にバインドします。まず安全に分析し、書き込みは意図的に有効化します。 | -| 「すべてのテーブルをモデル化するのは何週間もかかる」 | コーディングエージェントがスキーマをスキャンし、テーブルごとに 1 つのオブジェクトファイルを生成します — あなたはレビューして調整するだけで、手入力はしません。 | -| 「AI に我々のデータを任せられない」 | エージェントは **サインインしたユーザー** として実行され、オブジェクト・レコード・フィールドレベルの権限に従います。その背後にいる人物以上のものを見ることは決してありません。 | -| 「我々のデータはネットワークの外に出せない」 | ObjectOS はあなたの環境内で動作します。ビジネスデータとプロンプトはあなたの境界の内側に留まります。 | - -## コーディングエージェントによるオブジェクトの生成 - -既存のスキーマを取り込む最速の方法は、コーディングエージェント -（Claude Code など）を使って **ビジネステーブルをスキャンし、ソースレベルの -オブジェクト定義を生成する** ことです — テーブルごとに 1 つの -`*.object.ts` ファイルです。 - -[`hotcrm`](https://github.com/objectstack-ai/hotcrm) リファレンスアプリは、 -その出力が取るべき正確なかたちを示しています。各テーブルは型付けされた -`Field.*` 定義と外部キー用の `Field.lookup(...)` を持つ -`src/objects/.object.ts` となり、`ObjectSchema.create({ … })` を使って -記述され、`defineStack` によって組み立てられます。エージェントは接続された -データベースを内省し、カラムをフィールド型にマッピングし、あなたが所有し -コミットするオブジェクトを書き出します。あなたは合うものを残し、公開したくない -カラムを削除し、その上にラベル、検証、権限を追加します。 - -完全なステップバイステップの作成ガイドについては -[Data Sources](/docs/configure/data-sources) を参照してください。 - -## 初日に得られるもの - -テーブルが既存のデータベースにバインドされたオブジェクトとしてモデル化 -されると、 - -- **自然言語による分析。** ユーザーは実際のレコードについて質問し — - 「今四半期にずれ込んだ案件はどれで、その担当者は誰か？」— その答えは - ObjectQL を通じてライブデータに対して計算されます。 -- **ガバナンスの効いた自動化。** フローとアクションは同じデータを読み取り、 - （許可されている場合は）書き込むことができ、すべてのステップが監査されます。 -- **生成された API と Console。** REST/GraphQL エンドポイントと管理画面は - 同じメタデータから生成されます — 余分な統合レイヤーは不要です。 -- **ひとつの権限モデル。** 人間に適用される境界が、AI トラフィックにも - まったく同じように適用されます。 - -## これからの方向性 - -上記のフローは、すでに出荷されているビルディングブロックで今日機能します。 -より豊かな **ターンキーのフェデレーション** 体験 — ワンステップの -スキーマインポート、外部所有スキーマのバインディング、組み込みの安全ゲート — -は [ADR-0015](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0015-external-datasource-federation.md) -（ステータス: *Proposed*）のもとで活発に設計が進められています。それが -実現するまでは、文書化された道筋 — 接続、モデル化、バインド、クエリ — -が既存システムを拡張するサポート済みの方法です。 - -## ここから始める - -- [Data Sources](/docs/configure/data-sources) — データベースを接続し、オブジェクトをバインドし、クエリをルーティングする -- [AI Agents](/docs/build/agents) — オブジェクト上で動作する宣言的なエージェント -- [Permissions](/docs/configure/permissions) — AI が継承するモデル -- [Quickstart](/docs/quickstart) — 数分でランタイムを立ち上げる diff --git a/content/docs/extend-existing-systems.ko.mdx b/content/docs/extend-existing-systems.ko.mdx deleted file mode 100644 index b7aabdd..0000000 --- a/content/docs/extend-existing-systems.ko.mdx +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: 기존 시스템 확장하기 -description: 이미 운영 중인 비즈니스 시스템에 ObjectOS를 연결한 다음, 마이그레이션 없이 AI 네이티브 쿼리, 분석, 자동화를 더하세요. -translation: - source_sha: 42c3777ffcd0a04595702771b91a9d63c55c7d9ea53ec9bb4da477b74d74b63a - guide_rev: 1 - mode: auto ---- - -ObjectOS를 검토하는 대부분의 팀은 이미 기록 시스템을 가지고 있습니다 — CRM, -ERP, 티켓팅 도구, 프로덕션 SQL 또는 MongoDB 데이터베이스 위에 자리한 자체 -제작 백오피스 같은 것들입니다. 문제는 좀처럼 "이것을 버리고 다시 만들어야 -할까?"가 아닙니다. 그것은 "위험한 마이그레이션 없이, 이미 가지고 있는 것을 -**AI 네이티브**로 만들 수 있을까?"입니다. - -이 페이지가 설명하는 것이 바로 그 길입니다: **기존 데이터베이스에 ObjectOS를 -연결하고, 관심 있는 테이블을 객체로 모델링한 다음, AI 에이전트가 그 데이터를 -쿼리하고 분석하고 그에 따라 행동하게 하는 것** — 여러분의 권한 아래에서, -여러분의 인프라 위에서, 원래 시스템은 그대로 둔 채로 말입니다. - -## 이 변화의 형태 - -여러분은 비즈니스 시스템을 대체하지 않습니다. ObjectOS를 그 *옆에* 두고 -동일한 데이터베이스를 가리키게 합니다: - -1. 기존 데이터베이스를 [데이터소스](/docs/configure/data-sources)로 - **연결**합니다. 자격 증명은 환경에서 가져오며, 분석만 하려는 경우 - 연결은 읽기 전용일 수 있습니다. -2. 테이블을 객체로 **모델링**합니다 — 직접 손으로 하거나, 코딩 에이전트가 - 스키마를 스캔하여 소스 수준의 객체 파일을 여러분을 위해 생성하게 - 합니다. -3. 각 객체를 데이터소스에 **바인딩**합니다(객체별로, 또는 네임스페이스 - 전체에 대한 라우팅 규칙으로). -4. **AI를 사용**합니다 — 테이블이 객체가 되는 순간, 모든 에이전트, 도구, - 플로우, 대시보드가 그 위에서 작동하며, 자동으로 올바른 데이터베이스로 - 라우팅됩니다. - -레거시 애플리케이션에 대해서는 아무것도 변하지 않습니다. 행은 있던 자리에 -그대로 있습니다. ObjectOS는 그 위에 얹히는 AI 네이티브, 권한 인식 표면이 -됩니다. - -## 다시 작성하지 않고도 이것이 작동하는 이유 - -| 우려 사항 | ObjectOS가 처리하는 방식 | -|---|---| -| "데이터를 옮길 수 없습니다" | 데이터는 절대 옮겨지지 않습니다. ObjectOS는 여러분의 데이터베이스에 있는 그대로 연결합니다. | -| "프로덕션에 쓰기를 감행할 수 없습니다" | 객체를 **읽기 전용** 데이터소스(또는 읽기 전용 DB 사용자)에 바인딩하세요. 먼저 안전하게 분석하고, 쓰기는 신중하게 활성화하세요. | -| "모든 테이블을 모델링하는 것은 몇 주의 작업입니다" | 코딩 에이전트가 스키마를 스캔하여 테이블당 객체 파일 하나를 생성합니다 — 여러분은 검토하고 다듬을 뿐, 손으로 타이핑하지 않습니다. | -| "AI에게 우리 데이터를 맡길 수 없습니다" | 에이전트는 **로그인한 사용자**로 실행되며 객체, 레코드, 필드 수준의 권한을 따릅니다. 그들은 그 뒤에 있는 사람보다 더 많은 것을 결코 보지 못합니다. | -| "우리 데이터는 네트워크를 벗어날 수 없습니다" | ObjectOS는 여러분의 환경에서 실행됩니다. 비즈니스 데이터와 프롬프트는 여러분의 경계 내부에 머뭅니다. | - -## 코딩 에이전트로 객체 생성하기 - -기존 스키마를 가져오는 가장 빠른 방법은 코딩 에이전트(예: Claude Code)를 -사용하여 **비즈니스 테이블을 스캔하고 소스 수준의 객체 정의를 생성**하는 -것입니다 — 테이블당 `*.object.ts` 파일 하나씩. - -[`hotcrm`](https://github.com/objectstack-ai/hotcrm) 레퍼런스 앱은 그 -결과물이 취해야 할 정확한 형태를 보여줍니다: 각 테이블은 타입이 지정된 -`Field.*` 정의와 외래 키를 위한 `Field.lookup(...)`를 사용하는 -`ObjectSchema.create({ … })`로 `src/objects/.object.ts`가 되며, -`defineStack`으로 조립됩니다. 에이전트는 연결된 데이터베이스를 인트로스펙트하고, -컬럼을 필드 타입에 매핑하며, 여러분이 소유하고 커밋하는 객체를 작성합니다. -맞는 것은 유지하고, 노출하고 싶지 않은 컬럼은 버리며, 그 위에 레이블, -유효성 검사, 권한을 추가합니다. - -전체 단계별 작성 가이드는 [데이터소스](/docs/configure/data-sources)를 -참조하세요. - -## 첫날에 얻는 것 - -테이블이 기존 데이터베이스에 바인딩된 객체로 모델링되고 나면: - -- **자연어 분석.** 사용자가 실제 레코드에 대해 질문하고 — "이번 분기에 - 지연된 거래는 어떤 것이고 누가 담당인가요?" — 그 답은 ObjectQL을 통해 - 실시간 데이터에 대해 계산됩니다. -- **거버넌스가 적용된 자동화.** 플로우와 액션은 동일한 데이터를 읽고 - (허용된 경우) 쓸 수 있으며, 모든 단계가 감사됩니다. -- **생성된 API와 Console.** REST/GraphQL 엔드포인트와 관리 화면이 동일한 - 메타데이터에서 나옵니다 — 추가 통합 계층이 없습니다. -- **하나의 권한 모델.** 사람에게 적용되는 경계가 AI 트래픽에도 동일하게 - 적용됩니다. - -## 이것이 향하는 곳 - -위의 흐름은 이미 출시된 빌딩 블록으로 오늘날 작동합니다. 더 풍부한 -**턴키 페더레이션** 경험 — 한 단계 스키마 가져오기, 외부 소유 스키마 -바인딩, 내장 안전 게이트 — 는 -[ADR-0015](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0015-external-datasource-federation.md) -아래에서 활발히 설계 중입니다(상태: *Proposed*). 그것이 도착하기 전까지, -문서화된 경로 — 연결, 모델링, 바인딩, 쿼리 — 가 기존 시스템을 확장하는 -지원되는 방식입니다. - -## 여기서 시작하세요 - -- [데이터소스](/docs/configure/data-sources) — 데이터베이스 연결, 객체 바인딩, 쿼리 라우팅 -- [AI 에이전트](/docs/build/agents) — 여러분의 객체 위에서 작동하는 선언적 에이전트 -- [권한](/docs/configure/permissions) — AI가 상속하는 모델 -- [Quickstart](/docs/quickstart) — 몇 분 안에 런타임을 띄우기 diff --git a/content/docs/extend-existing-systems.zh-Hans.mdx b/content/docs/extend-existing-systems.zh-Hans.mdx deleted file mode 100644 index 0c3315d..0000000 --- a/content/docs/extend-existing-systems.zh-Hans.mdx +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: 扩展现有系统 -description: 将 ObjectOS 连接到你已经在运行的业务系统，然后为其加上 AI 原生的查询、分析与自动化能力 —— 无需迁移。 -translation: - source_sha: 42c3777ffcd0a04595702771b91a9d63c55c7d9ea53ec9bb4da477b74d74b63a - guide_rev: 1 - mode: auto ---- - -大多数评估 ObjectOS 的团队都已经有一套记录系统 —— 一个 CRM、一个 -ERP、一个工单工具，或者一个跑在生产 SQL 或 MongoDB 数据库上的自研后办公 -系统。问题很少是 "我们是否应该把它丢掉重建？"，而是 "我们能不能让已有的 -东西变得 **AI 原生**，又不必经历一次有风险的迁移？" - -这正是本页所描述的路径：**将 ObjectOS 连接到你 -现有的数据库，把你关心的表建模为对象，并让 AI -Agent 查询、分析这些数据并对其采取行动** —— 在你的权限之下、 -在你的基础设施之上，且原系统毫发无损。 - -## 这一步的形状 - -你不会替换你的业务系统。你把 ObjectOS 放在它*旁边*， -让二者指向同一个数据库： - -1. **连接**：把现有数据库作为[数据源](/docs/configure/data-sources)接入。 - 凭据来自你的环境；如果你只想做分析，连接可以是 - 只读的。 -2. **建模**：把表建模为对象 —— 手工进行，或者让一个编码 - Agent 扫描 schema 并为你生成源码级的对象文件。 -3. **绑定**：把每个对象绑定到数据源（按对象绑定，或用针对 - 整个命名空间的路由规则）。 -4. **使用 AI**：一旦某张表成为对象，每个 Agent、工具、流程 - 和仪表盘都能在它之上工作，并被自动路由到正确的数据库。 - -遗留应用的任何方面都不会改变。数据行保持原位。 -ObjectOS 成为其上层那个 AI 原生、感知权限的界面。 - -## 为什么这样行得通且无需重写 - -| 顾虑 | ObjectOS 如何应对 | -|---|---| -| "我们没法移动数据" | 数据从不移动。ObjectOS 就地连接到你的数据库。 | -| "我们不能冒险对生产库写入" | 把对象绑定到**只读**数据源（或一个只读的数据库用户）。先安全地分析；再有意识地开启写入。 | -| "把每张表都建模需要几周时间" | 一个编码 Agent 扫描 schema，并为每张表生成一个对象文件 —— 你审阅并打磨，而不是逐个手敲。 | -| "AI 不能托付我们的数据" | Agent 以**登录用户**的身份运行，并遵守对象级、记录级和字段级权限。它们看到的内容绝不会超过其背后的那个人。 | -| "我们的数据不能离开网络" | ObjectOS 运行在你的环境里。业务数据与提示词都留在你的边界之内。 | - -## 用编码 Agent 生成对象 - -把一个现有 schema 引入进来最快的方式，是使用一个编码 Agent -（例如 Claude Code）来**扫描业务表并生成 -源码级的对象定义** —— 每张表对应一个 `*.object.ts` 文件。 - -[`hotcrm`](https://github.com/objectstack-ai/hotcrm) 参考应用 -展示了这类输出应当呈现的确切形态：每张表都成为一个 -`src/objects/.object.ts`，使用 `ObjectSchema.create({ … })` 配合 -带类型的 `Field.*` 定义，并用 `Field.lookup(...)` 表示外键， -由 `defineStack` 组装。该 Agent 内省你已连接的 -数据库，把列映射到字段类型，并写出归你所有、由你 -提交的对象。你保留合适的部分，丢弃不想暴露的列，并在其上 -添加标签、校验与权限。 - -完整的、逐步的编写指南见[数据源](/docs/configure/data-sources)。 - -## 第一天你就能得到什么 - -一旦这些表被建模为绑定到你现有数据库的对象： - -- **自然语言分析。** 用户就真实记录提问 —— - "这个季度哪些交易延期了，分别归谁负责？" —— - 答案会通过 ObjectQL 针对实时数据计算得出。 -- **受治理的自动化。** 流程与动作可以读取并（在允许时） - 写入同一份数据，每一步都被审计。 -- **生成的 API 与 Console。** REST/GraphQL 端点与管理 - 界面来自同一份元数据 —— 无需额外的集成层。 -- **统一的权限模型。** 适用于人类的边界，会原封不动地 - 同样适用于 AI 流量。 - -## 它的走向 - -上述流程在今天就能通过已发布的构建块运转。一种更丰富的、 -**开箱即用的联邦**体验 —— 一步式 schema 导入、外部 -拥有的 schema 绑定，以及内建的安全闸门 —— 正在 -[ADR-0015](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0015-external-datasource-federation.md) -下积极设计中（状态：*Proposed*）。在它落地之前，这条已记录的 -路径 —— 连接、建模、绑定、查询 —— 就是扩展现有系统的受支持方式。 - -## 从这里开始 - -- [数据源](/docs/configure/data-sources) —— 连接数据库、绑定对象、路由查询 -- [AI Agent](/docs/build/agents) —— 构建在你对象之上的声明式 Agent -- [权限](/docs/configure/permissions) —— AI 所继承的模型 -- [Quickstart](/docs/quickstart) —— 几分钟内搭起一个运行时 diff --git a/content/docs/extend-existing-systems.zh-Hant.mdx b/content/docs/extend-existing-systems.zh-Hant.mdx deleted file mode 100644 index 78a2002..0000000 --- a/content/docs/extend-existing-systems.zh-Hant.mdx +++ /dev/null @@ -1,94 +0,0 @@ ---- -# @generated zh-Hant from zh-Hans -- do not edit. Edit the English source, then regenerate: pnpm --filter @objectos/docs gen:zh-hant -title: 擴充套件現有系統 -description: 將 ObjectOS 連線到你已經在執行的業務系統，然後為其加上 AI 原生的查詢、分析與自動化能力 —— 無需遷移。 -translation: - source_sha: 42c3777ffcd0a04595702771b91a9d63c55c7d9ea53ec9bb4da477b74d74b63a - guide_rev: 1 - mode: auto ---- - -大多數評估 ObjectOS 的團隊都已經有一套記錄系統 —— 一個 CRM、一個 -ERP、一個工單工具，或者一個跑在生產 SQL 或 MongoDB 資料庫上的自研後辦公 -系統。問題很少是 "我們是否應該把它丟掉重建？"，而是 "我們能不能讓已有的 -東西變得 **AI 原生**，又不必經歷一次有風險的遷移？" - -這正是本頁所描述的路徑：**將 ObjectOS 連線到你 -現有的資料庫，把你關心的表建模為物件，並讓 AI -Agent 查詢、分析這些資料並對其採取行動** —— 在你的許可權之下、 -在你的基礎設施之上，且原系統毫髮無損。 - -## 這一步的形狀 - -你不會替換你的業務系統。你把 ObjectOS 放在它*旁邊*， -讓二者指向同一個資料庫： - -1. **連線**：把現有資料庫作為[資料來源](/docs/configure/data-sources)接入。 - 憑據來自你的環境；如果你只想做分析，連線可以是 - 只讀的。 -2. **建模**：把表建模為物件 —— 手工進行，或者讓一個編碼 - Agent 掃描 schema 併為你生成原始碼級的物件檔案。 -3. **繫結**：把每個物件繫結到資料來源（按物件繫結，或用針對 - 整個名稱空間的路由規則）。 -4. **使用 AI**：一旦某張表成為物件，每個 Agent、工具、流程 - 和儀表盤都能在它之上工作，並被自動路由到正確的資料庫。 - -遺留應用的任何方面都不會改變。資料行保持原位。 -ObjectOS 成為其上層那個 AI 原生、感知許可權的介面。 - -## 為什麼這樣行得通且無需重寫 - -| 顧慮 | ObjectOS 如何應對 | -|---|---| -| "我們沒法行動數據" | 資料從不移動。ObjectOS 就地連線到你的資料庫。 | -| "我們不能冒險對生產庫寫入" | 把物件繫結到**只讀**資料來源（或一個只讀的資料庫使用者）。先安全地分析；再有意識地開啟寫入。 | -| "把每張表都建模需要幾周時間" | 一個編碼 Agent 掃描 schema，併為每張表生成一個物件檔案 —— 你審閱並打磨，而不是逐個手敲。 | -| "AI 不能託付我們的資料" | Agent 以**登入使用者**的身份執行，並遵守物件級、記錄級和欄位級許可權。它們看到的內容絕不會超過其背後的那個人。 | -| "我們的資料不能離開網路" | ObjectOS 執行在你的環境裡。業務資料與提示詞都留在你的邊界之內。 | - -## 用編碼 Agent 生成物件 - -把一個現有 schema 引入進來最快的方式，是使用一個編碼 Agent -（例如 Claude Code）來**掃描業務表並生成 -原始碼級的物件定義** —— 每張表對應一個 `*.object.ts` 檔案。 - -[`hotcrm`](https://github.com/objectstack-ai/hotcrm) 參考應用 -展示了這類輸出應當呈現的確切形態：每張表都成為一個 -`src/objects/.object.ts`，使用 `ObjectSchema.create({ … })` 配合 -帶型別的 `Field.*` 定義，並用 `Field.lookup(...)` 表示外部索引鍵， -由 `defineStack` 組裝。該 Agent 內省你已連線的 -資料庫，把列對映到欄位型別，並寫出歸你所有、由你 -提交的物件。你保留合適的部分，丟棄不想暴露的列，並在其上 -新增標籤、校驗與許可權。 - -完整的、逐步的編寫指南見[資料來源](/docs/configure/data-sources)。 - -## 第一天你就能得到什麼 - -一旦這些表被建模為繫結到你現有資料庫的物件： - -- **自然語言分析。** 使用者就真實記錄提問 —— - "這個季度哪些交易延期了，分別歸誰負責？" —— - 答案會通過 ObjectQL 針對即時資料計算得出。 -- **受治理的自動化。** 流程與動作可以讀取並（在允許時） - 寫入同一份資料，每一步都被審計。 -- **生成的 API 與 Console。** REST/GraphQL 端點與管理 - 介面來自同一份後設資料 —— 無需額外的整合層。 -- **統一的許可權模型。** 適用於人類的邊界，會原封不動地 - 同樣適用於 AI 流量。 - -## 它的走向 - -上述流程在今天就能通過已釋出的構建塊運轉。一種更豐富的、 -**開箱即用的聯邦**體驗 —— 一步式 schema 匯入、外部 -擁有的 schema 繫結，以及內建的安全閘門 —— 正在 -[ADR-0015](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0015-external-datasource-federation.md) -下積極設計中（狀態：*Proposed*）。在它落地之前，這條已記錄的 -路徑 —— 連線、建模、繫結、查詢 —— 就是擴充套件現有系統的受支援方式。 - -## 從這裡開始 - -- [資料來源](/docs/configure/data-sources) —— 連線資料庫、繫結物件、路由查詢 -- [AI Agent](/docs/build/agents) —— 構建在你物件之上的宣告式 Agent -- [許可權](/docs/configure/permissions) —— AI 所繼承的模型 -- [Quickstart](/docs/quickstart) —— 幾分鐘內搭起一個執行時