AI GO 系統串接指南

本文檔完整說明第三方應用（Integrations）如何透過「引用」與「API」串接 AI GO 系統，涵蓋所有可被引用的 API Endpoint、資料表（Table）、Custom Table（動態資料表）、Schema 與欄位定義。

1. 系統總覽與架構

1.1 系統定位

AI GO 是一套企業級 PaaS ERP 平台，提供會計、銷售、採購、庫存、CRM、HR、MRP、專案管理等完整模組。透過 Integration（整合） 機制，第三方開發者可建立自建應用（Self-Built App），安全地存取 AI GO 的企業資料。

1.2 三種應用存取模式

本文檔聚焦於 Self-Built（自建）模式，這是第三方整合的核心使用場景。

1.3 整體架構流程

sequenceDiagram
    participant Dev as 開發者（管理端）
    participant AIGO as AI GO API
    participant App as 第三方應用

    Note over Dev,App: === 第一階段：建立整合 ===
    Dev->>AIGO: POST /integrations（建立自建應用）
    AIGO-->>Dev: 回傳 app_id, slug

    Dev->>AIGO: POST /integrations/{app_id}/api-keys（產生 API Key）
    AIGO-->>Dev: 回傳 sk_live_xxx...（僅此一次）

    Note over Dev,App: === 第二階段A：設定系統表引用 ===
    Dev->>AIGO: GET /refs/available-tables（查看可引用的表）
    Dev->>AIGO: GET /refs/tables/{name}/columns（查看欄位）
    Dev->>AIGO: POST /refs/apps/{app_id}（建立引用 + 設定權限）

    Note over Dev,App: === 第二階段B：建立 Custom Table ===
    Dev->>AIGO: 在 AI GO 管理介面建立 Custom Table 及欄位定義

    Note over Dev,App: === 第三階段：發布 ===
    Dev->>AIGO: POST /integrations/{app_id}/publish（發布引用設定）
    AIGO-->>Dev: 快照 columns + permissions 為 published 版本

    Note over Dev,App: === 第四階段：存取資料 ===
    App->>AIGO: GET /open/proxy/{table}（系統資料表）
    AIGO-->>App: 回傳已授權欄位的資料（tenant 隔離）
    App->>AIGO: GET /open/data/objects/{slug}/records（Custom Table）
    AIGO-->>App: 回傳 Custom Table 記錄（tenant 隔離）

2. 認證機制

2.1 API Key Server-to-Server 認證（主要方式）

適用於 Self-Built 應用的後端對後端通訊。

API Key 格式：sk_live_ + 64 字元十六進位隨機字串

使用方式：在每個 HTTP 請求的 Header 中攜帶：

X-API-Key: sk_live_a1b2c3d4e5f6...

驗證流程：

系統會自動驗證 API Key 的有效性與所屬應用，並自動取得 app_id 和 tenant_id（不需額外傳遞）。無效或已撤銷的 Key 會回傳 401 Unauthorized。

安全建議：

• API Key 僅在建立時回傳一次完整明文，請妥善保存
• 建議將 Key 存放於環境變數或密鑰管理服務，不要寫入程式碼
• 定期輪換 Key（撤銷舊 Key → 建立新 Key）
• 同一整合可建立多把 Key（如 Production / Staging 分離）

2.2 Custom App User 認證

AI GO 平台為自建整合提供完整的獨立用戶認證系統，包含：

• Email + 密碼：註冊 / 登入
• OAuth 第三方登入：LINE、Google、Facebook 等（參見 §2.4）
• JWT Access Token + Refresh Token Rotation
• Builder 端用戶管理：啟用 / 停用 / 刪除

重要：Independent 模式不需要第三方開發者自行建立認證系統。AI GO 已提供現成的認證 API，開發者只需要呼叫這些端點即可為自己的應用實現完整的用戶註冊與登入功能。

2.3.1 認證流程總覽

sequenceDiagram
    participant User as 終端用戶
    participant App as 第三方前端
    participant AIGO as AI GO API

    alt Email + 密碼
        User->>App: 填寫註冊 / 登入表單
        App->>AIGO: POST /custom-app-auth/{slug}/register 或 login
        AIGO-->>App: { access_token, refresh_token, user }
    else OAuth 登入（如 LINE）
        User->>App: 點擊 LINE 登入
        App->>AIGO: GET /custom-app-oauth/{slug}/line/authorize
        AIGO-->>User: 302 重導 LINE 授權頁
        User->>AIGO: 授權回呼
        AIGO-->>App: 302 redirect?oauth_token=<base64 encoded tokens>
    end

    Note over App: 儲存 access_token + refresh_token

    App->>AIGO: GET /custom-app-auth/{slug}/me（Bearer Token）
    AIGO-->>App: { user info }

    Note over App: Token 即將過期時
    App->>AIGO: POST /custom-app-auth/{slug}/refresh
    AIGO-->>App: { new access_token, new refresh_token }

路徑說明：所有 Custom App User 認證端點以 app_slug（非 app_id）作為路徑參數。slug 可在整合詳情頁面的標題旁查看（12 位元十六進位字串）。系統也支援以 subdomain 替代 slug。

2.3.2 註冊（Register）

POST /api/v1/custom-app-auth/{app_slug}/register

認證：無需認證（公開端點）

Request Body：

{
  "email": "user@example.com",
  "password": "my_secure_password",
  "display_name": "王小明"
}

Response 201 Created：

{
  "access_token": "eyJhbGciOiJIUzI1NiI...",
  "refresh_token": "a1b2c3d4e5f6...",
  "expires_in": 900,
  "token_type": "Bearer",
  "user": {
    "id": "uuid",
    "custom_app_id": "uuid",
    "tenant_id": "uuid",
    "email": "user@example.com",
    "display_name": "王小明",
    "avatar_url": null,
    "extra_data": {},
    "is_active": true,
    "last_login_at": null,
    "created_at": "2026-04-01T00:00:00Z",
    "updated_at": null
  }
}

錯誤碼：

2.3.3 登入（Login）

POST /api/v1/custom-app-auth/{app_slug}/login

認證：無需認證（公開端點）

Request Body：

{
  "email": "user@example.com",
  "password": "my_secure_password"
}

Response 200 OK：格式同 §2.3.2 註冊 的 Response

錯誤碼：

2.3.4 取得當前用戶（Me）

GET /api/v1/custom-app-auth/{app_slug}/me

認證：Bearer Token（Access Token）

Authorization: Bearer eyJhbGciOiJIUzI1NiI...

Response 200 OK：

{
  "id": "uuid",
  "custom_app_id": "uuid",
  "tenant_id": "uuid",
  "email": "user@example.com",
  "display_name": "王小明",
  "avatar_url": "https://...",
  "extra_data": {},
  "is_active": true,
  "last_login_at": "2026-04-01T12:00:00Z",
  "created_at": "2026-04-01T00:00:00Z",
  "updated_at": null
}

錯誤碼：

2.3.5 刷新 Token（Refresh）

POST /api/v1/custom-app-auth/{app_slug}/refresh

認證：無需 Bearer Token（公開端點，需 refresh_token 作為 Body 參數）

Request Body：

{
  "refresh_token": "a1b2c3d4e5f6..."
}

Response 200 OK：格式同 §2.3.2 註冊 的 Response（包含全新的 access_token 和 refresh_token）

⚠️ Token Rotation：每次 refresh 成功後，舊的 Refresh Token 立即失效（撤銷）。請務必儲存並使用回傳的新 refresh_token。

錯誤碼：

2.3.6 登出（Logout）

POST /api/v1/custom-app-auth/{app_slug}/logout

認證：Bearer Token（Access Token）

Request Body：

{
  "refresh_token": "a1b2c3d4e5f6..."
}

Response 200 OK：

{
  "message": "已登出"
}

2.3.7 ext/ 端點群：Custom App User 專用 API

以下端點需以 Custom App User Token（Bearer）認證，適用於 Independent 模式的前端直接存取資料：

使用方式：

# 使用 Custom App User Token 存取系統資料表
curl -H "Authorization: Bearer <access_token>" \
     https://api.ai-go.app/api/v1/ext/proxy/customers

# 使用 Custom App User Token 存取 Custom Table
curl -H "Authorization: Bearer <access_token>" \
     https://api.ai-go.app/api/v1/ext/data/objects/group_tour/records

與 Open Proxy 的區別：

• /ext/* 端點使用 Bearer Token（Custom App User Token），tenant_id 和 custom_app_id 從 Token payload 自動解析
• /open/* 端點使用 API Key（X-API-Key），適用於後端 Server-to-Server 呼叫
• 兩者共用相同的引用白名單和資料過濾引擎

2.3.8 網域白名單（Origin 檢查）

設定 allowed_origins 後，Custom App Auth 端點（register / login 等）會檢查 HTTP Origin header：

⚠️ Port 注意事項：Port 是 Origin 的一部分（RFC 6454），例如 http://localhost:3000 ≠ http://localhost:8000。設定白名單時需包含完整的 scheme://host:port。

2.3.9 Builder 端用戶管理 API

以下端點供整合管理者（Builder）在 AI GO 管理介面中管理 Custom App 的用戶，需主站 JWT 認證（builder.access 權限）：

停用或刪除用戶後，該用戶的認證快取會立即清除，已發出的 Access Token 在快取 TTL（60 秒）後將無法使用。

2.3 OAuth 第三方登入（LINE 等）

自建整合可額外設定 OAuth Provider（如 LINE Login），讓終端用戶透過第三方帳號直接登入。

2.4.1 前置設定

Builder 需在 AI GO 管理介面為 App 設定 OAuth Provider：

1. 進入整合管理 → 選擇 App → 設定 Tab
2. 填入 Provider 的 Client ID 和 Client Secret（系統會以 AES-256 加密儲存）
3. 在第三方平台（如 LINE Developers Console）設定 Callback URL 為：

https://<YOUR_API_HOST>/api/v1/custom-app-oauth/{app_slug}/{provider}/callback

2.4.2 OAuth 端點清單

目前支援的 provider 值：line（LINE Login）。Google、Facebook、GitHub 等架構已就緒。

2.4.3 OAuth 登入流程

sequenceDiagram
    participant User as 終端用戶
    participant App as 第三方前端
    participant AIGO as AI GO API
    participant LINE as LINE Login

    App->>AIGO: GET /{slug}/auth-providers
    AIGO-->>App: [{ "provider": "line" }]

    User->>App: 點擊 LINE 登入按鈕
    App->>AIGO: GET /{slug}/line/authorize
    AIGO-->>User: 302 → LINE 授權頁
    User->>LINE: 同意授權
    LINE-->>AIGO: callback?code=xxx&state=yyy

    alt 有 email
        AIGO-->>App: 302 → {app_url}?oauth_token=<base64>
        Note over App: base64 解碼得到<br/>{ access_token, refresh_token, user }
    else 無 email
        AIGO-->>App: 302 → {app_url}?oauth_pending=<token>
        App->>User: 顯示補填 email 表單
        User->>App: 輸入 email
        App->>AIGO: POST /{slug}/oauth/complete-email
        AIGO-->>App: { access_token, refresh_token, user }
    end

2.4.4 OAuth Token 傳遞方式

OAuth 登入成功後，系統透過 query parameter 將 token 回傳至 App 的 live_url：

前端解碼範例：

// OAuth 登入成功後解碼 token
const params = new URLSearchParams(window.location.search);
const encoded = params.get('oauth_token');
if (encoded) {
  const decoded = JSON.parse(atob(encoded));
  // decoded = { access_token, refresh_token, expires_in, user }
  localStorage.setItem('access_token', decoded.access_token);
  localStorage.setItem('refresh_token', decoded.refresh_token);
}

2.4.5 OAuth 帳號綁定行為

⚠️ OAuth 用戶的 password_hash 為 null，無法使用 Email + 密碼登入。若需要啟用密碼登入，用戶需另行設定密碼。

2.4 Token 技術規格

Custom App User 認證使用的 Token 機制：

Access Token JWT Payload 範例

{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "custom_app_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tenant_id": "11111111-2222-3333-4444-555555555555",
  "auth_type": "custom_app_user",
  "scope": "app_runtime",
  "iat": 1711929600,
  "exp": 1711930500
}

關鍵區分：auth_type 欄位固定為 "custom_app_user"，/ext/* 端點會據此驗證身份。

2.4.1 Quick Start：30 分鐘完成整合

以下是端對端整合的最小步驟：

Step 1 — 建立整合並取得 API Key：

# 在 AI GO 管理介面建立新整合
# 取得 app_slug（如 e9abbb866184）和 API Key（如 sk_live_xxx）

Step 2 — 設定網域白名單：

在設定 Tab 中將前端 Origin（如 https://myapp.example.com）加入白名單。

Step 3 — 前端串接範例（JavaScript）：

const API_BASE = 'https://api.ai-go.app/api/v1';
const APP_SLUG = 'e9abbb866184';

// ── 1. 使用者註冊 ──
async function register(email, password, displayName) {
  const res = await fetch(`${API_BASE}/custom-app-auth/${APP_SLUG}/register`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email, password, display_name: displayName }),
  });
  const data = await res.json();
  if (!res.ok) throw new Error(data.detail);
  
  // 儲存 token
  localStorage.setItem('access_token', data.access_token);
  localStorage.setItem('refresh_token', data.refresh_token);
  return data.user;
}

// ── 2. 使用者登入 ──
async function login(email, password) {
  const res = await fetch(`${API_BASE}/custom-app-auth/${APP_SLUG}/login`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email, password }),
  });
  const data = await res.json();
  if (!res.ok) throw new Error(data.detail);
  
  localStorage.setItem('access_token', data.access_token);
  localStorage.setItem('refresh_token', data.refresh_token);
  return data.user;
}

// ── 3. 使用 Token 存取資料 ──
async function fetchCustomers() {
  const token = localStorage.getItem('access_token');
  const res = await fetch(`${API_BASE}/ext/proxy/customers`, {
    headers: { 'Authorization': `Bearer ${token}` },
  });
  return res.json();
}

// ── 4. Token 刷新 ──
async function refreshTokens() {
  const refreshToken = localStorage.getItem('refresh_token');
  const res = await fetch(`${API_BASE}/custom-app-auth/${APP_SLUG}/refresh`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ refresh_token: refreshToken }),
  });
  const data = await res.json();
  if (!res.ok) throw new Error(data.detail);
  
  // ⚠️ 務必更新兩個 token（Token Rotation）
  localStorage.setItem('access_token', data.access_token);
  localStorage.setItem('refresh_token', data.refresh_token);
  return data;
}

Step 4 — 後端 Server-to-Server 存取資料（Python）：

import requests

API_KEY = 'sk_live_a1b2c3d4...'
API_BASE = 'https://api.ai-go.app/api/v1'

# 直接用 API Key 存取資料（不涉及用戶認證）
resp = requests.get(
    f'{API_BASE}/open/proxy/customers',
    headers={'X-API-Key': API_KEY},
)
print(resp.json())

3. 整合管理 API

前綴：/api/v1/integrations 認證：主站 JWT（需 builder.access 權限）

3.1 列出所有整合

GET /api/v1/integrations

Response 200 OK：

[
  {
    "id": "uuid",
    "tenant_id": "uuid",
    "name": "我的 ERP 整合",
    "slug": "e9abbb866184",
    "subdomain": "my-erp",
    "live_url": "https://my-erp.example.com",
    "allowed_origins": ["https://my-erp.example.com"],
    "api_key_count": 2,
    "created_at": "2026-03-01T00:00:00Z",
    "updated_at": "2026-03-20T00:00:00Z"
  }
]

3.2 建立新整合

POST /api/v1/integrations

Response 201 Created：IntegrationDetail 物件

3.3 取得整合詳情

GET /api/v1/integrations/{app_id}

Response 200 OK：

{
  "id": "uuid",
  "tenant_id": "uuid",
  "name": "...",
  "slug": "...",
  "subdomain": null,
  "live_url": null,
  "allowed_origins": [],
  "access_mode": "self_built",
  "created_at": "...",
  "updated_at": "..."
}

3.4 重新命名

PATCH /api/v1/integrations/{app_id}/name

3.5 更新設定

PATCH /api/v1/integrations/{app_id}/settings

3.6 刪除整合

DELETE /api/v1/integrations/{app_id}

Response 204 No Content（連帶刪除所有 API Keys）

3.7 API Key 管理

列出 API Keys

GET /api/v1/integrations/{app_id}/api-keys

Response 200 OK：

[
  {
    "id": "uuid",
    "app_id": "uuid",
    "key_prefix": "sk_live_a1b2",
    "name": "Production Key",
    "is_active": true,
    "last_used_at": "2026-03-20T12:00:00Z",
    "expires_at": null,
    "created_at": "2026-03-01T00:00:00Z"
  }
]

建立 API Key

POST /api/v1/integrations/{app_id}/api-keys

Response 201 Created：

{
  "id": "uuid",
  "app_id": "uuid",
  "key_prefix": "sk_live_a1b2",
  "name": "Production Key",
  "api_key": "sk_live_a1b2c3d4e5f6g7h8...",
  "created_at": "..."
}

⚠️ api_key 欄位僅在建立時回傳一次，請立即妥善保存。

撤銷 API Key

DELETE /api/v1/integrations/{app_id}/api-keys/{key_id}

Response 204 No Content

3.8 發布審核流程

引用設定修改後，需通過「發布」才能在 Open Proxy 中生效。

發布整合

POST /api/v1/integrations/{app_id}/publish

行為：

• 有 builder.publish 權限 → 直接發布（自動 approved）
• 無 builder.publish 權限 → 建立 pending 申請等候審核

列出發布申請

GET /api/v1/integrations/{app_id}/publish-requests

核准 / 拒絕 / 取消發布申請

POST /api/v1/integrations/{app_id}/publish-requests/{req_id}/approve
POST /api/v1/integrations/{app_id}/publish-requests/{req_id}/reject
POST /api/v1/integrations/{app_id}/publish-requests/{req_id}/cancel

• approve：需 builder.publish 權限
• reject：需 builder.publish 權限，Body: { "reject_reason": "..." }
• cancel：僅申請者本人可取消

取得發布狀態

GET /api/v1/integrations/{app_id}/publish-status

Response：

{
  "can_publish": true,
  "is_locked": false,
  "pending_request": null,
  "published_at": "2026-03-20T00:00:00Z"
}

4. 引用系統 API

前綴：/api/v1/refs 認證：主站 JWT（需 builder.access 權限）

引用（Reference）是 AI GO 的資料授權核心機制。每個整合必須先建立引用，指定要存取哪些表的哪些欄位，以及具備什麼操作權限。

4.1 列出可引用的表

GET /api/v1/refs/available-tables

Response 200 OK：

[
  { "name": "customers", "comment": "客戶" },
  { "name": "sale_orders", "comment": "銷售訂單" },
  { "name": "product_products", "comment": "" }
]

4.2 取得表的欄位資訊

GET /api/v1/refs/tables/{table_name}/columns

Response 200 OK：

[
  {
    "name": "name",
    "type": "VARCHAR",
    "nullable": false,
    "is_system": false
  },
  {
    "name": "email",
    "type": "VARCHAR",
    "nullable": true,
    "is_system": false
  },
  {
    "name": "customer_id",
    "type": "UUID",
    "nullable": true,
    "is_system": false,
    "is_fk": true,
    "fk_target": "customers.id"
  }
]

4.3 引用 CRUD

列出 App 的所有引用

GET /api/v1/refs/apps/{app_id}

建立引用

POST /api/v1/refs/apps/{app_id}

更新引用

PATCH /api/v1/refs/{ref_id}

刪除引用

DELETE /api/v1/refs/{ref_id}

4.4 權限值說明

4.5 不可引用的表

系統核心表（如身份驗證、租戶管理、權限設定、稽核紀錄等）因安全原因永遠不可被引用。嘗試引用這些表時，API 會回傳 403 此表不可引用。

可引用的表清單請透過 GET /api/v1/refs/available-tables API 查詢。

4.6 系統欄位

以下欄位由系統自動管理，寫入時會被自動排除：

4.7 共用業務欄位：custom_data（JSONB）

所有功能性資料表皆包含 custom_data 欄位，專為第三方應用儲存業態專屬的自訂資料設計。

使用方式：在建立引用時將 custom_data 加入 columns 清單：

{
  "table_name": "customers",
  "columns": ["id", "name", "email", "custom_data"],
  "permissions": ["read", "create", "update"]
}

⚠️ 若引用的 columns 中未包含 custom_data，則該 App 在讀取時不會看到此欄位，寫入時也會被自動忽略。

5. 資料代理 Proxy API（Open Proxy）

前綴：/api/v1/open/proxy 認證：API Key（X-API-Key Header） 資料隔離：自動以 Key 所屬的 tenant_id 做 row-level 過濾 引用版本：使用已發布（published）的引用快照

5.0 三套 Proxy 對照表

系統提供三套 Proxy 端點，共用同一個核心查詢引擎，差異僅在認證方式與引用版本：

重要：自建應用透過 Open Proxy 同樣支援完整的進階查詢功能（filters、search、order_by、select、count_only 等），並非只有 limit / offset。使用 POST /{table_name}/query 即可。

External Proxy 認證說明：External Proxy（/ext/proxy/）需使用 Custom App User Token（Bearer）認證，適用於 Independent 模式的前端直接存取資料。Token 的取得方式請參閱 §2.3 Custom App User 認證。

5.1 簡單查詢

GET /api/v1/open/proxy/{table_name}?limit=100&offset=0

Response 200 OK：

[
  {
    "id": "uuid",
    "name": "客戶 A",
    "email": "a@example.com",
    "phone": "0912345678"
  }
]

5.2 進階查詢

POST /api/v1/open/proxy/{table_name}/query

Request Body：

{
  "filters": [
    { "column": "status", "op": "eq", "value": "active" },
    { "column": "amount_total", "op": "gte", "value": 1000 }
  ],
  "order_by": [
    { "column": "created_at", "direction": "desc" }
  ],
  "search": "關鍵字",
  "search_columns": ["name", "email"],
  "select_columns": ["id", "name", "email"],
  "limit": 50,
  "offset": 0,
  "count_only": false
}

Filter 運算子

Filter 組合邏輯

• 多個 filter 之間以 AND 連接
• 不支援 OR 組合（例外：search 功能在多個搜尋欄之間使用 OR）
• 不支援巢狀分組條件（如 (A AND B) OR (C AND D)）
• 若需要 BETWEEN 效果，可組合 gte + lte 兩個 filter

範例 — 查詢金額 ≥ 1000 且狀態為 active 的銷售訂單：

{
  "filters": [
    { "column": "amount_total", "op": "gte", "value": 1000 },
    { "column": "state", "op": "eq", "value": "sale" }
  ]
}

Search 全文搜尋行為

• search 會對 search_columns（或所有授權非 id 欄位）執行 ILIKE '%keyword%'
• 多個搜尋欄之間以 OR 連接（任一欄位命中即回傳）
• search 與 filters 之間為 AND（兩者同時滿足）
• 搜尋時欄位值會被 cast 為 text 型別，因此也可搜尋數值或 UUID 欄位

count_only 模式

設定 "count_only": true 時，僅回傳符合條件的總筆數（filters 與 search 均生效）：

{ "total": 42 }

5.3 新增記錄

[!WARNING] Proxy API 操作不觸發業務單據自動生成 (Workflow Triggers) 透過 Proxy API 新增或更新業務資料（如將訂單 state 改為 sale），系統 不會 自動建立後續單據（如自動產生出貨單、發票）。Proxy API 為「資料層代理」，第三方應用需自行 INSERT 所有相關單據，但特定欄位（如已開票量、付款狀態等）系統會自動維護。各表的「自動觸發流程（Triggers）」請參閱第 8 章。

POST /api/v1/open/proxy/{table_name}

Request Body：

{
  "name": "新客戶",
  "email": "new@example.com",
  "phone": "0912345678",
  "custom_data": {
    "passport_no": "A123456789",
    "travel_pref": ["eco", "window_seat"]
  }
}

custom_data 接受任意 JSON 結構（物件、陣列、巢狀皆可）。

Response 201 Created：

{
  "id": "uuid",
  "created_at": "2026-03-24T00:00:00Z",
  "data": {
    "name": "新客戶",
    "email": "new@example.com",
    "custom_data": "{\"passport_no\": \"A123456789\"}"
  }
}

tenant_id 由系統自動注入，不需手動提供。

5.4 更新記錄

PATCH /api/v1/open/proxy/{table_name}/{row_id}

Request Body：

{
  "name": "更新後名稱",
  "phone": "0987654321"
}

Response 200 OK：

{ "id": "uuid", "updated": true }

5.5 刪除記錄

DELETE /api/v1/open/proxy/{table_name}/{row_id}

Response 204 No Content

5.6 自動型別轉換

Proxy 會自動將字串轉為對應的 PostgreSQL 型別：

⚠️ UUID 欄位注意事項：

• 所有以 _id 結尾的欄位（如 product_id、order_id）在寫入時會自動嘗試轉為 UUID 型別
• 若值為空字串 ""，系統會自動轉為 NULL（避免 PostgreSQL 型別錯誤）
• 若值不是合法的 UUID 格式（如 LINE ID U1234567890），則保留原始字串

5.7 AI GO 簽核系統整合 (Approval Workflow)

💡 適用於：POST, PATCH, DELETE 等任何會修改資料的 Proxy 操作。

AI GO 提供了彈性的簽核工作流引擎。當系統管理員在後台為特定資料表（例如 sale_orders）設定了簽核關卡時，您的 Proxy API 呼叫將會自動受到簽核系統的審查攔截。

攔截與 API 旁路機制 (Bypass)

1. 一般情況 (攔截)：當簽核流程被觸發，API 操作不會直接生效。相反的，系統會：
   • 針對 POST (Insert-then-flag)：先行新增未生效的記錄，確保取得 ID 後供參照。
   • 針對 PATCH / DELETE (Pre-guard)：完全暫停對資料庫的實際改動，將異動內容封裝進入「簽核申請單」中等待判斷。
   • 您的 API 呼叫會收到帶有 approval_status: "pending" 的回傳值。
2. API 旁路 (Bypass)：若管理員在後台開啟了對應工作流的「允許 API 旁路」選項，第三方 API 將可以無視簽核規則強制寫入資料。系統僅會在背景紀錄一筆 Bypass Audit Log 供後續稽核追蹤。

被攔截時的回傳格式

當未開啟旁路，且操作觸發了簽核條件時，API 不會回傳標準的成功格式，而是如下：

Update 操作被攔截的範例：

{
  "id": "e305d21a-e75b-42e1-886d-a1112345abcd",
  "updated": false,
  "approval_status": "pending",
  "approval_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "approval_message": "此更新需要簽核審批（2 層），已建立申請"
}

開發者注意事項：在串接有潛在簽核規則的 Table（如採購單、銷貨單、請假單等）時，請務必在處理 API Response 中捕捉 approval_status === "pending" 這個屬性，避免將 Pending 視為實際的修改成功。

6. Custom Table API（動態資料表）

前綴：/api/v1/open/data 認證：API Key（X-API-Key Header） 資料隔離：自動以 Key 所屬的 tenant_id 做 row-level 過濾 引用白名單：不適用（Custom Table 隸屬於 App 本身，不走引用機制）

6.0 Custom Table 與系統資料表的差異

AI GO 提供兩種資料儲存方式，分別使用不同的 API 端點：

⚠️ 常見錯誤：請勿使用 /open/proxy/ 端點存取 Custom Table。Custom Table 不是實體 PostgreSQL 表，不存在於引用系統中，使用 Proxy 端點會收到 403 App 未被授權存取表 錯誤。

6.1 Custom Table 概念說明

Custom Table 是 AI GO 的動態資料庫系統，允許每個 App 自行定義資料表結構：

• CustomObject（資料表定義）：邏輯上等同一張「表」，包含名稱和 api_slug（API 識別碼）
• CustomField（欄位定義）：每個 Object 可定義多個欄位（名稱、型別、是否必填等）
• CustomRecord（資料記錄）：實際資料以 JSONB 格式儲存在 data 欄位中

erDiagram
    CustomObject ||--o{ CustomField : "has fields"
    CustomObject ||--o{ CustomRecord : "has records"
    CustomObject {
        UUID id PK
        UUID app_id FK
        string name
        string api_slug
    }
    CustomField {
        UUID id PK
        UUID object_id FK
        string name
        string field_key
        string field_type
        boolean is_required
        int sequence
    }
    CustomRecord {
        UUID id PK
        UUID object_id FK
        JSONB data
    }

6.2 列出 App 的 Custom Table

GET /api/v1/open/data/objects

Response 200 OK：

[
  {
    "id": "uuid",
    "tenant_id": "uuid",
    "app_id": "uuid",
    "name": "團體行程",
    "api_slug": "group_tour",
    "created_at": "2026-03-20T00:00:00Z",
    "updated_at": "2026-03-20T00:00:00Z",
    "fields": [
      {
        "id": "uuid",
        "object_id": "uuid",
        "name": "行程名稱",
        "field_key": "tour_name",
        "field_type": "text",
        "is_required": true,
        "sequence": 10
      },
      {
        "id": "uuid",
        "object_id": "uuid",
        "name": "金額",
        "field_key": "amount",
        "field_type": "number",
        "is_required": false,
        "sequence": 20
      }
    ]
  }
]

回傳的 fields 陣列包含完整的欄位定義，可用於動態生成表單或表格。

6.3 列出 Custom Table 的記錄

GET /api/v1/open/data/objects/{obj_id}/records

路徑參數：

Response 200 OK：

[
  {
    "id": "uuid",
    "tenant_id": "uuid",
    "object_id": "uuid",
    "data": {
      "tour_name": "日本東京五日遊",
      "amount": 35000,
      "departure_date": "2026-05-01"
    },
    "created_at": "2026-03-20T00:00:00Z",
    "updated_at": "2026-03-20T00:00:00Z"
  },
  {
    "id": "uuid",
    "tenant_id": "uuid",
    "object_id": "uuid",
    "data": {
      "tour_name": "韓國首爾三日遊",
      "amount": 18000,
      "departure_date": "2026-06-15"
    },
    "created_at": "2026-03-21T00:00:00Z",
    "updated_at": "2026-03-21T00:00:00Z"
  }
]

data 欄位為 JSONB，其結構由 Custom Table 的 fields 定義決定。

6.4 新增記錄

POST /api/v1/open/data/objects/{obj_id}/records

路徑參數：obj_id 支援 UUID 或 api_slug

Request Body：

{
  "data": {
    "tour_name": "泰國曼谷四日遊",
    "amount": 22000,
    "departure_date": "2026-07-20",
    "max_people": 30,
    "itinerary": ["大皇宮", "水上市場", "芭達雅"]
  }
}

data 接受任意 JSON 結構，包含物件、陣列、巢狀結構等。field_key 對應 Custom Table 的欄位定義。

Response 201 Created：

{
  "id": "uuid",
  "tenant_id": "uuid",
  "object_id": "uuid",
  "data": {
    "tour_name": "泰國曼谷四日遊",
    "amount": 22000,
    "departure_date": "2026-07-20",
    "max_people": 30,
    "itinerary": ["大皇宮", "水上市場", "芭達雅"]
  },
  "created_at": "2026-03-29T00:00:00Z",
  "updated_at": null
}

tenant_id 由系統根據 API Key 自動注入，不需手動提供。

6.5 更新記錄

PATCH /api/v1/open/data/records/{record_id}

路徑參數：

Request Body：

{
  "data": {
    "amount": 25000,
    "status": "confirmed"
  }
}

更新為合併模式（Merge）：僅覆寫傳入的欄位，未傳入的欄位保持不變。例如上例只會更新 amount 和新增 status，其餘欄位（如 tour_name）不受影響。

Response 200 OK：

{
  "id": "uuid",
  "tenant_id": "uuid",
  "object_id": "uuid",
  "data": {
    "tour_name": "泰國曼谷四日遊",
    "amount": 25000,
    "departure_date": "2026-07-20",
    "max_people": 30,
    "itinerary": ["大皇宮", "水上市場", "芭達雅"],
    "status": "confirmed"
  },
  "created_at": "2026-03-29T00:00:00Z",
  "updated_at": "2026-03-29T01:00:00Z"
}

6.6 刪除記錄

DELETE /api/v1/open/data/records/{record_id}

Response 200 OK：

{
  "message": "已刪除",
  "id": "uuid"
}

6.7 欄位型別說明

由於 data 是 JSONB 欄位，實際上可以儲存任意 JSON 結構（陣列、巢狀物件等），field_type 主要用於 UI 表單顯示和前端驗證。

6.8 Custom Table 完整使用範例

以下展示第三方旅行社 ERP 系統串接 Custom Table 的完整流程：

# ── 第一步：取得 API Key 後，查看 App 有哪些 Custom Table ──
curl -H "X-API-Key: sk_live_a1b2c3d4e5f6..." \
     https://api.ai-go.app/api/v1/open/data/objects

# 回應範例：
# [
#   {
#     "id": "...", "name": "團體行程", "api_slug": "group_tour",
#     "fields": [{"field_key": "tour_name", "field_type": "text"}, ...]
#   },
#   {
#     "id": "...", "name": "訂單紀錄", "api_slug": "booking",
#     "fields": [{"field_key": "customer_name", ...}, ...]
#   }
# ]


# ── 第二步：用 api_slug 列出「團體行程」的所有記錄 ──
curl -H "X-API-Key: sk_live_a1b2c3d4e5f6..." \
     https://api.ai-go.app/api/v1/open/data/objects/group_tour/records


# ── 第三步：新增一筆行程記錄 ──
curl -X POST \
     -H "X-API-Key: sk_live_a1b2c3d4e5f6..." \
     -H "Content-Type: application/json" \
     -d '{
       "data": {
         "tour_name": "沖繩四日遊",
         "amount": 28000,
         "departure_date": "2026-08-10",
         "max_people": 25
       }
     }' \
     https://api.ai-go.app/api/v1/open/data/objects/group_tour/records


# ── 第四步：更新記錄（Merge 模式，僅更新指定欄位）──
curl -X PATCH \
     -H "X-API-Key: sk_live_a1b2c3d4e5f6..." \
     -H "Content-Type: application/json" \
     -d '{"data": {"amount": 32000, "status": "full"}}' \
     https://api.ai-go.app/api/v1/open/data/records/{record_id}


# ── 第五步：刪除記錄 ──
curl -X DELETE \
     -H "X-API-Key: sk_live_a1b2c3d4e5f6..." \
     https://api.ai-go.app/api/v1/open/data/records/{record_id}

6.9 與 Open Proxy 的端點對照

如果您同時需要存取系統資料表（如 customers）和 Custom Table，請注意使用不同的 API 端點：

# ── 存取系統資料表（如客戶）→ 使用 Open Proxy ──
curl -H "X-API-Key: sk_live_xxx" \
     https://api.ai-go.app/api/v1/open/proxy/customers

# ── 存取 Custom Table（如團體行程）→ 使用 Open Custom Data ──
curl -H "X-API-Key: sk_live_xxx" \
     https://api.ai-go.app/api/v1/open/data/objects/group_tour/records

7. 可引用的資料表與 Schema 完整清單

以下列出所有可被引用的資料表（僅適用於 Open Proxy，Custom Table 請參閱 §6）。 每張表皆包含 id(UUID)、created_at(timestamptz)、updated_at(timestamptz)、tenant_id(UUID) 四個系統欄位，以及 custom_data(JSONB) 自訂資料欄位（參見 §4.7），以下不重複列出。

7.1 客戶模組

customers — 客戶

customer_levels — 客戶等級

customer_tags — 客戶標籤

customer_tag_rel — 客戶-標籤關聯

customer_tag_prices — 標籤專屬價

7.2 供應商模組

suppliers — 供應商

7.3 產品模組

product_categories — 產品分類

product_templates — 產品範本

product_products — 產品變體

product_price_tiers — 階梯定價

product_supplierinfo — 供應商價格

7.4 銷售模組

sale_orders — 銷售訂單

📌 自動觸發流程 (Triggers)

• 新增或更新此表（以及 sale_order_lines）時，系統會自動比對出貨量與開票量，並重新計算更新本訂單的 invoice_status（no, to_invoice, invoiced）。

sale_order_lines — 銷售訂單明細

7.5 採購模組

purchase_orders — 採購訂單

📌 自動觸發流程 (Triggers)

• 新增或更新此表（以及 purchase_order_lines）時，系統會自動重新計算更新本訂單的開票狀態。

purchase_order_lines — 採購訂單明細

7.6 會計模組

⚠️ 核心會計邏輯與專屬 API 提醒 請注意：若您直接使用 Open Proxy API 對 account_moves 與 account_move_lines 進行 INSERT，系統不會觸發會計防呆與自動化處理（例如：自動取號、防呆自動平衡分錄等），這可能導致借貸不平的髒資料產生。

若您正在開發獨立的會計/發票整合系統，強烈建議您全面改用 AI GO 專屬的會計業務 API：

1. POST /api/v1/accounting/vouchers (建立傳票：自動設定 entry 與 mapping)
2. POST /api/v1/accounting/vouchers/{id}/post (過帳傳票：自動依據結算差額插入「自動平衡分錄」並生成 Voucher Number)

在專屬 API 中，只要偵測到 Debit ≠ Credit，系統會自動幫您墊入一筆「自動平衡分錄」將總金額強制打平，確保會計約束不崩潰！詳細 Endpoint 規格請見系統的 /docs Swagger 頁面。

account_moves — 會計傳票/發票

📌 自動觸發流程 (Triggers)

• 更新此發票或其明細，以及關聯付款對帳時（account_payments），系統會自動重新計算這張發票的付款狀態 payment_state（如 paid, partial, not_paid）。

account_move_lines — 傳票明細行

會計模組還包含 account_accounts、account_journals、account_taxes、account_payment_terms、account_fiscal_positions、account_payments、account_bank_statements、account_move_templates 等表，結構請透過 GET /refs/tables/{table_name}/columns API 即時查詢。

7.7 庫存模組

stock_warehouses — 倉庫

stock_locations — 庫位

stock_pickings — 揀貨單/調撥單

stock_moves — 庫存移動

📌 自動觸發流程 (Triggers)

• 更新此表的狀態時，系統會自動重新計算關聯揀貨單 (stock_pickings) 的部分出入庫完成狀態。

stock_quants — 庫存量

📌 關於庫存量維護 (Triggers)：新增或更新 stock_move_lines (庫存移動明細) 時，系統會自動計算並更新對應庫位商品的保留數量 (stock_quants.reserved_quantity)。

庫存模組還包含 stock_lots、stock_picking_types、stock_move_lines、stock_routes、stock_rules、stock_packages、stock_scraps、stock_warehouse_orderpoints、stock_landed_costs、stock_picking_batches、delivery_carriers、inventory_check_batches、inventory_check_items、inventory_converts、freight_groups、freight_group_tiers 等表。

7.8 CRM 模組

crm_leads — 商機

還包含 crm_stages、crm_teams、crm_team_members、crm_lost_reasons、crm_tags、crm_recurring_plans、crm_activities 等表。

7.9 HR 人力資源模組

hr_employees — 員工

📌 自動觸發流程 (Triggers)

• 出勤 (hr_attendances)：新增或更新出勤紀錄時，會自動更新對應員工目前的出勤狀態。
• 請假 (hr_leaves)：請假單狀態更新為 validate（核准）時，會自動扣除該員工可用休假額度（hr_leave_allocations）。
• 工時 (hr_timesheets)：填寫工時表會自動累加 project_tasks.effective_hours（任務實際工時），並更新專案任務進度百分比。

還包含 hr_departments、hr_jobs、hr_work_locations、hr_attendances、hr_leave_types、hr_leaves、hr_leave_allocations、hr_expense_sheets、hr_expenses、hr_skill_types、hr_skills、hr_timesheets、hr_work_entry_types、hr_work_entries 等表。

7.10 MRP 製造模組

mrp_productions — 生產訂單

📌 自動觸發流程 (Triggers)

• 更新關聯工單 (mrp_workorders) 的狀態時，系統會自動結算並刷新本生產訂單的完成進度。

還包含 mrp_workcenters、mrp_boms、mrp_bom_lines、mrp_bom_byproducts、mrp_routing_workcenters、mrp_workorders、mrp_unbuilds 等表。

7.11 專案管理模組

project_projects — 專案

📌 自動觸發流程 (Triggers)

• 建立或刪除關聯任務 (project_tasks) 時，系統會自動維護並更新此專案主檔的總任務數 (task_count)。

project_tasks — 任務

還包含 project_project_stages、project_task_types、project_milestones、project_tags、project_roles、project_collaborators、project_task_recurrences、project_updates 等表。

7.12 核心參考表

countries — 國家

currencies — 幣別

uom_uom — 計量單位

還包含 country_states、currency_rates、languages、uom_categories、ir_sequences 等表。

7.13 其他模組

所有表的完整欄位可透過 GET /api/v1/refs/tables/{table_name}/columns 即時查詢。

8. 錯誤碼與限制

8.1 HTTP 狀態碼

8.2 常見錯誤訊息

8.3 速率限制

系統對所有 API 請求實施 Per-App 速率限制。超過限制時回傳 429 Too Many Requests。

8.4 安全注意事項

• 所有資料查詢自動以 tenant_id 做 row-level 隔離，無法跨租戶存取
• tenant_id 由 API Key 自動決定，無法偽造
• 寫入操作時，系統欄位（id、created_at、updated_at、tenant_id）會被自動排除
• 欄位名稱經正則驗證（^[a-zA-Z_][a-zA-Z0-9_]*$），防止 SQL 注入
• 僅允許白名單運算子，不接受任意 SQL

9. Proxy 查詢完整安全機制與功能限制

9.1 安全驗證流程

每次 Proxy 呼叫都會依序執行以下驗證：

① AppDataReference 白名單驗證
   → 檢查 App 是否有對目標表的引用（Open Proxy 需已發布快照）
② CRUD 權限檢查
   → 引用的 permissions 必須包含所需操作（read / create / update / delete）
③ 黑名單表檢查
   → 14 張系統核心表永遠不可存取
④ 欄位白名單驗證
   → filter / select / insert / update 的欄位必須在授權的 columns 清單中
⑤ 欄位名稱正則驗證
   → 只允許 ^[a-zA-Z_][a-zA-Z0-9_]*$，防止 SQL 注入
⑥ 運算子白名單驗證
   → 只接受 11 種已定義運算子（eq, ne, gt, gte, lt, lte, like, ilike, in, is_null, is_not_null）
⑦ Tenant 隔離注入
   → 所有查詢自動加上 WHERE tenant_id = :tid（不可跨租戶）
⑧ 系統欄位保護
   → INSERT / UPDATE 時自動排除 id, created_at, updated_at, tenant_id

9.2 Open Proxy 存取方式對照

9.3 已知查詢功能限制

9.4 Filter 欄位驗證規則彙整

提示：所有表的最新欄位結構可透過 GET /api/v1/refs/tables/{table_name}/columns 動態取得，包含型別、是否 Nullable、外鍵指向等資訊。建議在開發時搭配此 API 使用。

10. Enum 值速查附錄

所有 VARCHAR 型別但僅接受固定值的欄位完整清單。

• [DB]：有 PostgreSQL CHECK CONSTRAINT，寫入非法值會直接報錯 400 / 500
• [建議]：無資料庫約束，為系統建議值；前後端介面以此為準，API 不會拒絕其他值但可能導致顯示異常

10.1 客戶模組

10.2 供應商模組

10.3 產品模組

10.4 銷售模組

10.5 採購模組

10.6 會計模組

10.7 庫存模組

10.8 CRM 模組

10.9 HR 人力資源模組

10.10 MRP 製造模組

10.11 專案管理模組

10.12 公告模組

10.13 固定資產模組

10.14 金融/銀行模組

10.15 核心參考表

10.16 系統管理模組

使用提示：

• 查詢 filter 時，enum 欄位使用 eq 運算子精確比對，例如 {"column": "state", "op": "eq", "value": "draft"}
• 查詢多個 enum 值可使用 in 運算子，例如 {"column": "state", "op": "in", "value": ["draft", "sent"]}
• 新增/更新記錄時，[DB] 約束的 enum 欄位必須使用清單中的值，否則會收到 400 / 500 錯誤

11. 第三方應用實戰指南（Best Practices & Gotchas）

[!TIP] 彙整第三方開發者常見痛點，包含資料隔離機制、查詢防呆、遷移腳本與 CI/CD 注意事項。

11.1 多應用共享租戶 (Multi-App Tenant) 的最佳實踐

[!IMPORTANT] 為什麼這很重要？ 在 AI GO 系統中，同一個租戶（Tenant）可能同時啟用多套 Custom App（例如：同時有「訂房平台」與「電商商城」），如果不進行資料隔離，使用者的商城頁面就會看見「高級海景房」被當成商品販售。

建議擴充內容：

• Data Domain Separation (App Domain) 策略：強制規範所有使用到共用表（如 product_templates、sale_orders）的 Custom App，必須在創建資料時注入識別用的領域標籤（例如 custom_data: { "app_domain": "ec-platform" }）。
• Proxy 層面攔截實作：如果您是在前端實作 API Request 攔截器（Interceptor）或是撰寫了自有的 API Proxy 層，建議在 create 與 list 動作中，自動幫請求補上 app_domain 的篩選或預設欄位，實現全站「無感隔離」。

11.2 PostgreSQL JSONB 查詢的格式陷阱 (Gotchas)

[!WARNING] 陷阱警告！ JSON 序列化後的空格特性，會導致直覺寫法的 ilike 查詢失敗。

建議擴充內容：

• 字串查詢特性：AI GO 將 custom_data 以 JSONB 格式儲存於資料庫中。當您使用開放代理 API (如 /query 端點) 進行 ilike 過濾時，若使用精準的 {"app_domain":"ec-platform"} 作為條件，通常會匹配不到資料。
• 解決方案：因為 PostgreSQL 在將 JSONB 物件序列化成字串（Text）進行比較時，常在 JSON 冒號後面自動加上空格（{"app_domain": "ec-platform"}）。因此，建議寫法應為寬鬆字串匹配：
  • ❌ 錯誤寫法：custom_data::text ilike '%"app_domain":"ec-platform"%'
  • ✅ 正確寫法：custom_data::text ilike '%app_domain%ec-platform%'

11.3 API Proxy 的安全存取控制 (Access & Auth Models)

[!CAUTION] 某些系統核心表（如 sale_order_lines）擁有底層的硬性權限保護，不允許任意增刪。

建議擴充內容：

• 區分 Open Proxy 與 Ext Proxy：明列哪些場景（如公開型錄讀取）可使用 API Key，哪些場景（如消費者自主結帳）必須強制使用 Bearer Token（Custom App User Token）。
• Capability Matrix 限制：針對特定的表，即使您有該表的 Delete 引用，如果遇到底層防呆機制（例如：無法刪除已結帳訂單的明細），API 會回應 403 Forbidden 錯誤，請直接導引客戶至「AI GO 管理員介面」進行圖文操作或授權退款。

11.4 資料遷移腳本範例 (Data Migration Boilerplate)

[!TIP] 當應用程式發展至第二階段（例如後期才加入資料隔離網），不可避免需要批量更新舊有歷史資料的 custom_data。

Node.js Migration Script 範例： 為了確保向前相容，您可以在本地準備一支批次腳本來自動更新：

const axios = require('axios');
const API_URL = 'https://api.ai-go.app/api/v1/open/proxy/product_templates/query';
const API_KEY = 'sk_live_xxxxxx';

async function migrate() {
    let offset = 0;
    while (true) {
        // 先查出尚無標籤的紀錄 (僅示意，請依實際情況運用)
        const resp = await axios.post(API_URL, {
            limit: 100,
            offset: offset
        }, { headers: { 'X-API-Key': API_KEY } });

        const products = resp.data.data || [];
        if (products.length === 0) break;

        for (const p of products) {
            // 檢查且對每筆舊資料 PATCH 加入 app_domain
            if (!p.custom_data || !p.custom_data.app_domain) {
                await axios.patch(`https://api.ai-go.app/api/v1/open/proxy/product_templates/${p.id}`, {
                    custom_data: { ...(p.custom_data || {}), app_domain: 'ec-platform' }
                }, { headers: { 'X-API-Key': API_KEY } });
            }
        }
        offset += 100;
        console.log(`Migrated batch offset ${offset}`);
    }
}
migrate();

11.5 端到端部署與 CI/CD (E2E Deployment)

建議擴充內容：

• 環境變數同步規範：在將前端應用推播至 Vercel 或 GitHub Actions 進行建置前，請務必再三確認 .env.production 或 CI/CD Secrets 儀表板中的 VITE_API_BASE、VITE_APP_SLUG 與 AIGO_API_KEY 皆已正確配置為 Production 環境對應的值。
• Repository Visibility 提醒：若您使用了 Vercel 的自動化拉取原始碼部署功能（Git Integration），必須賦予 Vercel 應用讀取該 Private GitHub Repository 的權限。若建置過程中發生模組丟失錯誤，請檢查儲存庫權限，或斟酌將原始碼庫設為 Public。