01 — CORA 系統架構深度解析

第一章：CORA 是什麼 #

1.1 產品定位

CORA（Cognitive Orchestration & Reasoning Architecture）是一個部署在客戶自有伺服器上的企業 AI 平台。

與通用 AI 助手（ChatGPT、Copilot）的關鍵差異：

1.2 商業模式

CORA 收費結構：
├── 授權費（年繳）      — 按使用人數 / 部門數
├── 部署費（一次性）     — FDE 到場部署 + 培訓
├── 駐場支援費（月繳）   — 前 3 個月的 FDE 支援
└── LLM API 費用（代收） — 按實際 token 用量

1.3 目標客戶

第二章：系統架構總覽 #

2.1 六層架構

┌──────────────────────────────────────────────┐
│          使用者層（Web 控制台）                │
│  Captain's Deck │ Watchtower │ Engine Room    │
│  Observer       │ Synapse Chat│ Forge         │
├──────────────────────────────────────────────┤
│          Gateway 層（入口 + 安全）             │
│  多通道路由 │ IntentGuard │ 五層防禦         │
├──────────────────────────────────────────────┤
│          Spine 層（中央調度）                  │
│  Orchestrator │ Synapse Agent │ EventBus     │
├──────────────────────────────────────────────┤
│          Axion 層（數據分析 + AI 引擎）        │
│  Data Fabric │ AI Engine │ BI │ Security     │
├──────────────────────────────────────────────┤
│          Ontology 層（知識圖譜）               │
│  Apache AGE │ CoraObject │ 關係定義          │
├──────────────────────────────────────────────┤
│          基礎設施層                            │
│  PostgreSQL+pgvector+AGE │ Redis │ Temporal  │
└──────────────────────────────────────────────┘

2.2 子系統職責對照表

2.3 資料流向

一個典型的使用者請求流程：

使用者在 Slack 發訊息「上個月的營收報告」
  │
  ▼
Gateway 接收 Slack webhook
  → SlackChannelAdapter 驗證 HMAC 簽名
  → 解析為 IncomingMessage
  │
  ▼
IntentGuard 五層檢查
  → 第 1 層：輸入過濾（無注入模式）
  → 第 2 層：語意分析（正常請求）
  → 第 3 層：邊界檢查（在授權範圍內）
  → 通過 ✓
  │
  ▼
Spine Orchestrator 路由
  → 識別意圖：finance_report
  → 載入 FinanceSkillPack
  │
  ▼
Synapse Agent 執行
  → LLM 決定使用 get_monthly_revenue 工具
  → 呼叫 Axion · Data Fabric 查詢 ERP
  → 取得數據
  → LLM 組織回覆
  │
  ▼
Gateway 發送回覆
  → 透過 SlackChannelAdapter 發送 Block Kit 訊息
  → 使用者在 Slack 收到格式化的營收報告
  │
  ▼
審計紀錄
  → AuditEventBus 記錄完整決策軌跡
  → Watchtower 可查看

第三章：Spine — 中央調度引擎 #

3.1 SpineOrchestrator

Spine 是 CORA 的「大腦」，所有請求都經過它分發：

# 簡化的路由邏輯
class SpineOrchestrator:
    async def route(self, message: IncomingMessage):
        # 1. 安全檢查（Governance Agent）
        if not await self.governance.check_permission(message):
            return deny()

        # 2. 意圖識別 → 選擇 Skill Pack
        skill = self.skill_manager.match(message.content)

        # 3. 派發給 Synapse Agent 執行
        response = await self.synapse.invoke(message, tools=skill.get_tools())

        # 4. 記錄審計軌跡
        await self.audit_bus.emit(event)

        return response

3.2 Synapse Agent（LangGraph 狀態機）

Synapse 是每個使用者的 AI 助理，用 LangGraph 實作的 10 節點狀態機：

input_guard → context_loader → sentiment_analyzer → router
  → skill_gate → middleware → reasoner → tool_executor
  → observer → memory_extractor

FDE 需要知道的：

• Synapse 是無狀態的（狀態由外部傳入）
• 系統 Prompt 由 PersonaEngine 根據使用者角色動態生成
• 每次對話都經過 IntentGuard 安全檢查
• 工具選擇由 SkillManager 的漸進式揭露控制

3.3 EventBus

所有子系統之間的通訊都透過 EventBus：

# 發布事件
event_bus.publish(SystemEvent(type="ORDER_CREATED", payload={...}))

# 訂閱事件
event_bus.subscribe("ORDER_*", handler_function)
event_bus.subscribe("*", audit_logger)  # 審計模組訂閱所有事件

FDE 實務： EventBus 事件會即時推送到 Observer Console 的 WebSocket，這是除錯時最有用的工具。

第四章：Gateway — 入口與安全 #

4.1 多通道適配器

每個適配器都實作 ChannelAdapter ABC：

• verify_request() — 驗證請求真實性（HMAC）
• parse_request() — 正規化為 IncomingMessage
• send_message() — 發送回覆

4.2 IntentGuard 五層防禦

FDE 實務： IntentGuard 預設全部啟用，不需要配置。但如果客戶有特殊的安全政策（例如更嚴格的 PII 規則），需要修改 config/secretary_policy_default.yaml。

4.3 Rate Limiting

RateLimitMiddleware 已內建於 Spine API：

• 全域限流（預設 10 req/s，burst 20）
• 每客戶限流（per-IP 或 per-user）
• CRITICAL 優先級可繞過限流
• 設定方式：環境變數 RATE_LIMIT_REQUESTS_PER_SECOND

第五章：Knowledge Graph（Apache AGE） #

5.1 為什麼需要圖資料庫

客戶的組織結構天然是圖：

部門 A ──[管轄]──→ 員工 X
部門 A ──[使用]──→ 系統 ERP
員工 X ──[負責]──→ 專案 P
專案 P ──[依賴]──→ 供應商 S

用傳統 SQL 做多跳查詢（「誰跟這個專案有關？」）需要遞迴 CTE，效能差且難寫。用 Apache AGE（PostgreSQL 圖擴展）可以直接寫 Cypher：

MATCH (p:Project {name: '專案P'})-[*1..3]-(related)
RETURN DISTINCT related

5.2 CORA 的圖資料模型

CoraObject（頂層基類）
├── id: UUID
├── created_at / updated_at
├── access_groups: ["admin", "public"]  ← RBAC
└── embedding: vector                   ← pgvector 向量搜尋

CoraRelation（邊）
├── id: UUID
├── relation_name: "managed_by"
├── source_id → target_id
└── properties: {"since": "2025-01-01"}

5.3 FDE 操作：AGE 圖查詢

-- 載入 AGE
LOAD 'age';
SET search_path = ag_catalog, "$user", public;

-- 建立節點
SELECT * FROM cypher('cora_graph', $$
  CREATE (d:Department {cora_id: 'dept-001', name: '財務部'})
  RETURN d
$$) AS (v agtype);

-- 查詢 2 跳關聯
SELECT * FROM cypher('cora_graph', $$
  MATCH (a {cora_id: 'dept-001'})-[*1..2]-(b)
  RETURN DISTINCT b
$$) AS (b agtype);

FDE 實務： 部署時需要確認 AGE 擴展已安裝（init-extensions.sql 會自動處理），並在 Alembic migration 中初始化圖（006_age_graph.py）。

第六章：SimCorp 與 Demo Choreographer #

6.1 SimCorp 是什麼

SimCorp 是 CORA 的虛擬企業模擬引擎，用於：

• 展覽演示（模擬一家 120 人企業的日常營運）
• 客戶 POC（讓客戶在自己的模擬環境中體驗 CORA）
• 壓力測試（模擬大量事件驗證系統穩定性）

6.2 Profile YAML

每個模擬環境由一份 Profile YAML 定義：

company:
  name: "Nexus Global Industries"
  industry: "manufacturing"
  size: "medium"

departments:
  - id: executive
    name: "Executive Office"
    head: emp-ceo

employees:
  - id: emp-ceo
    name: "David Chen"
    role: "CEO"
    personality: "decisive, data-driven"

scenarios:
  - id: supplier-disruption
    triggers:
      - at: "day:0+hour:14"
        events:
          - type: "supply_chain.disruption"

6.3 Demo Choreographer

展覽用的控制器，讓展場人員按一個按鈕就能觸發場景：

POST /api/demo/load    — 載入劇本
POST /api/demo/start   — 開始演示
POST /api/demo/next    — 下一個場景
POST /api/demo/reset   — 重置
GET  /api/demo/state   — 取得狀態（含講稿、提示）

FDE 實務： 客戶 POC 時，為客戶建立專屬的 SimCorp Profile（參考 simcorp-profiles/ 下的範本），模擬客戶自己的組織結構。

第七章：控制台巡覽 #

7.1 六個面板

7.2 FDE 最常用的面板

1. Engine Room — 部署後確認系統健康、管理連接器
2. Observer Console — 除錯時觀察即時事件流
3. Forge Console — 配置新的資料連接器
4. Watchtower — 向客戶稽核部門展示合規能力

第八章：Synapse Agent 與 Skill Pack #

8.1 Skill Pack 架構

class SkillPack(ABC):
    name: str           # 例如 "healthcare_admin_v1"
    description: str    # 路由用的簡短描述

    def get_loaders() → List[Tool]:        # Level 1：總是可見
    def get_functional_tools() → List[Tool]: # Level 2：觸發後載入

8.2 現有 Skill Pack

8.3 FDE 如何客製化

客戶可能需要專屬工具。FDE 不需要寫程式，但需要知道如何：

1. 啟用/停用特定 Skill Pack
2. 調整系統 Prompt（透過 PersonaEngine）
3. 設定權限矩陣（哪些角色能用哪些工具）

第九章：Foresight Engine（Z+ 架構） #

9.1 四階段管線

Stage 1: 場景建立（ScenarioBuilder）
  → 解析使用者問題：「如果預算縮減 20% 會怎樣？」
  → 輸出：結構化場景定義

Stage 2: 資料充實（ForesightEnricher）
  → 從 Knowledge Graph 查詢影響鏈
  → 從 Data Fabric 拉取相關數據
  → 輸出：EnrichedContext（含數據引用）

Stage 3: 模擬推理（ForesightSimulator）
  → 主路徑：LLM 推理 + Logic Engine 規則驗證
  → 可選：SimCorp 組織行為模擬
  → 輸出：SimulationResult（風險 + 建議 + 信心度）

Stage 4: 報告產出（ReportAgent）
  → ReACT 循環生成結構化報告
  → 輸出：Markdown 報告 + 數據引用

9.2 FDE 實務

• Foresight 需要 LLM API Key 才能運行（Stage 2-3 依賴 LLM）
• 如果客戶不需要預測功能，可以不配置（其他功能不受影響）
• 預測品質取決於 Knowledge Graph 中的數據豐富度 — FDE 在部署時建立的組織架構圖越完整，Foresight 越準確

第十章：EventBus 與即時事件流 #

10.1 EventBus 架構

SystemEvent {
  id: UUID
  type: "ORDER_CREATED"    ← 事件類型（用於訂閱篩選）
  source: "erp_connector"  ← 來源
  payload: { ... }         ← 事件資料
  priority: HIGH           ← 優先級
}

訂閱模式：

• event_bus.subscribe("ORDER_*", handler) — 萬用字元
• event_bus.subscribe("*", audit_logger) — 全部事件

10.2 WebSocket 即時推送

EventBus 事件自動橋接到 WebSocket：

EventBus.publish()
  → event_to_ws_bridge()
  → ws_manager.broadcast()
  → Observer Console 即時顯示

10.3 Webhook 出站

配置 WEBHOOK_OUTBOUND_URLS 環境變數，CORA 會將事件推送到外部系統：

• HMAC-SHA256 簽名（X-CORA-Signature header）
• 自動 retry（3 次 + 指數退避）
• 可篩選事件類型

L1 考核準備 #

筆試範圍（60 題，80 分通過）

實機操作考核（8 題，全部完成）

1. 在 Observer Console 找到最近 5 分鐘的事件
2. 在 Watchtower 查看一筆審計紀錄的完整軌跡
3. 在 Captain's Deck 找到供應鏈健康度 KPI
4. 用 Synapse Chat 查詢「上個月的訂單數量」
5. 在 AGE 中用 Cypher 查詢一個節點的 2 跳關聯
6. 說明一個 Slack 訊息從進入到回覆的完整子系統路徑
7. 觸發 SimCorp 的「供應鏈中斷」場景並觀察 Observer 事件流
8. 找到 IntentGuard 攔截了一個 Prompt Injection 的審計紀錄

02 — CORA 部署操作手冊

第一章：Docker Compose 服務架構 #

1.1 服務清單

# docker-compose.yaml 包含以下服務：

postgres        — PostgreSQL 15 + pgvector + Apache AGE（圖資料庫）
redis           — 快取 + 會話管理
temporal        — 工作流引擎（長時間任務編排）
api             — CORA Spine API（FastAPI，主服務）
worker          — Temporal Worker（背景工作處理）
mock-erp        — 模擬 ERP（僅開發/展示用）
client-portal   — Synapse Chat 前端
god-mode-console — God-Mode 管理面板

1.2 服務依賴鏈

postgres ─┬─→ temporal ─→ api ─→ worker
           │              ↑
redis ────┘              │
                   client-portal

啟動順序很重要： postgres 和 redis 必須先 healthy，temporal 才能啟動；temporal healthy 後 api 才能啟動。Docker Compose 的 depends_on: condition: service_healthy 已處理好。

1.3 展覽版 vs 正式部署版

FDE 部署時使用 docker-compose.yaml 為基礎， 根據客戶需求加入所需的控制台服務。

第二章：伺服器準備 #

2.1 硬體需求

2.2 初始化腳本

在全新的 Ubuntu 22.04 上執行：

# 1. 系統更新
sudo apt update && sudo apt upgrade -y

# 2. 安裝 Docker
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

# 3. 安裝 Docker Compose
sudo apt install -y docker-compose-plugin

# 4. 安裝常用工具
sudo apt install -y git curl wget htop jq

# 5. 設定防火牆
sudo ufw allow 22/tcp    # SSH
sudo ufw allow 80/tcp    # HTTP
sudo ufw allow 443/tcp   # HTTPS
sudo ufw enable

# 6. 驗證
docker --version
docker compose version

2.3 目錄結構

# 在伺服器上建立工作目錄
mkdir -p /opt/cora
cd /opt/cora

# 從 Git 拉取（或 SCP 打包檔案）
git clone https://github.com/sivahuang77/cora.git .

第三章：部署流程 #

3.1 環境變數配置

複製範本並編輯：

cp .env.exhibition.template .env

必須設定的變數：

# ── 基礎 ──
POSTGRES_PASSWORD=<強密碼，至少 16 字元>
JWT_SECRET_KEY=<隨機字串，至少 32 字元>

# ── LLM（至少一個） ──
OPENAI_API_KEY=sk-xxx
# 或
ANTHROPIC_API_KEY=sk-ant-xxx
# 或
GOOGLE_API_KEY=AIza-xxx

# ── 如果有域名 ──
DOMAIN=cora.customer.com

# ── 客戶識別 ──
CORA_INSTANCE_ID=inst-customer-001
CORA_INSTANCE_NAME=客戶公司名稱

安全提醒：

• 密碼用 openssl rand -base64 24 產生
• .env 檔案權限設為 600：chmod 600 .env
• 絕不將 .env 加入 git

3.2 建構映像檔

# 建構所有服務（首次約 10-15 分鐘）
docker compose build --parallel

# 特別注意：postgres 映像含 AGE 編譯，需要較長時間

3.3 啟動服務

# 啟動基礎設施
docker compose up -d postgres redis

# 等待 postgres 和 redis 健康
docker compose ps  # 確認 status = healthy

# 啟動核心服務
docker compose up -d temporal
sleep 10  # 等待 temporal 初始化

docker compose up -d api worker

# 驗證
curl http://localhost:8000/health
# 預期：{"status": "ok", "temporal_connected": true}

3.4 初始化資料庫

# 執行 Alembic migration
docker exec cora-api python3 -m alembic upgrade head

# 初始化 AGE 圖資料庫
docker exec cora-postgres psql -U cora_user -d cora_db -c "
  CREATE EXTENSION IF NOT EXISTS vector;
  CREATE EXTENSION IF NOT EXISTS age;
  LOAD 'age';
  SET search_path = ag_catalog, \"\$user\", public;
  SELECT create_graph('cora_graph');
"

3.5 驗證部署

# 完整健康檢查
curl http://localhost:8000/health/ready | jq

# 預期回應：
# {
#   "status": "green",
#   "checks": {
#     "database": {"status": "green"},
#     "temporal": {"status": "green"},
#     "synapse": {"status": "green"},
#     "forge": {"status": "green"},
#     "gateway": {"status": "green"}
#   }
# }

第四章：SSL 與域名配置 #

4.1 使用 Let's Encrypt

# 安裝 certbot
sudo apt install -y certbot python3-certbot-nginx

# 申請憑證（需要域名 DNS 已指向此伺服器）
sudo certbot certonly --standalone -d cora.customer.com --email ops@citrux.ai --agree-tos

# 憑證位置：
# /etc/letsencrypt/live/cora.customer.com/fullchain.pem
# /etc/letsencrypt/live/cora.customer.com/privkey.pem

4.2 Nginx 反向代理

安裝 Nginx 並配置：

sudo apt install -y nginx

將 infrastructure/nginx/exhibition.conf 複製到 /etc/nginx/sites-available/cora 並修改域名，然後：

sudo ln -s /etc/nginx/sites-available/cora /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

4.3 路由對照表

第五章：資料庫管理 #

5.1 PostgreSQL + AGE

日常操作：

# 進入 psql
docker exec -it cora-postgres psql -U cora_user -d cora_db

# 查看 AGE 圖狀態
LOAD 'age';
SET search_path = ag_catalog, "$user", public;
SELECT * FROM ag_catalog.ag_graph;

# 查看表格
\dt

# 查看 migration 版本
SELECT version_num FROM alembic_version;

5.2 備份與還原

# 備份（含 AGE 圖資料）
docker exec cora-postgres pg_dump -U cora_user -d cora_db > backup_$(date +%Y%m%d).sql

# 還原
docker exec -i cora-postgres psql -U cora_user -d cora_db < backup_20260317.sql

# 驗證
./scripts/backup-restore-test.sh

5.3 排程備份

# 加入 crontab（每天凌晨 3 點備份）
(crontab -l; echo "0 3 * * * docker exec cora-postgres pg_dump -U cora_user -d cora_db | gzip > /opt/cora/backups/backup_\$(date +\%Y\%m\%d).sql.gz") | crontab -

第六章：監控配置 #

6.1 啟用 Prometheus + Grafana

# 啟動監控 profile
docker compose --profile monitoring up -d prometheus grafana

# Grafana 存取：http://伺服器IP:3100
# 預設帳號：admin / admin（首次登入後修改）

6.2 Prometheus 指標端點

CORA 的指標端點：http://api:8000/api/v1/observability/metrics

已預設追蹤的指標：

• http_requests_total — 請求總數（by status code）
• http_request_duration_seconds — 延遲分佈
• llm_prompt_tokens_total — LLM prompt token 用量
• llm_completion_tokens_total — LLM completion token 用量

6.3 重要告警閾值

第七章：備份與災備 #

7.1 備份策略

7.2 災難復原程序

1. 準備新伺服器（按第二章步驟）
2. 部署 CORA（按第三章步驟）
3. 還原 PostgreSQL 備份
4. 還原 .env 設定
5. 重啟所有服務
6. 驗證 /health/ready
7. 通知客戶恢復服務

預期 RTO（恢復時間目標）：2-4 小時

L2 考核準備 #

考核方式

限時 4 小時，在一台全新的 Ubuntu 22.04 VM 上，獨立完成以下任務：

總分 100，通過門檻 70 分。

常見失敗原因

1. .env 忘記設定 POSTGRES_PASSWORD（postgres 啟動失敗）
2. Temporal 還沒 healthy 就啟動 api（api 無法連線）
3. AGE 擴展未安裝（migration 失敗）
4. 防火牆未開 443 port（HTTPS 不通）
5. LLM API Key 過期或額度不足（Synapse 無法回應）

03 — 資料整合指南

第一章：Data Fabric 架構 #

1.1 連接器框架

所有資料源連接器都實作 ConnectorBase 介面：

ConnectorBase (ABC)
├── connect(config)        → 建立連線
├── disconnect()           → 斷開連線
├── discover_schema()      → 自動發現資料結構（表格、欄位、型別）
├── sync(mode)             → 同步資料（FULL / INCREMENTAL）
└── health_check()         → 檢查連線健康狀態

1.2 可用連接器清單

1.3 韌性層

所有連接器都內建韌性機制：

@with_retry(max_attempts=3, base_delay=1.0, max_delay=10.0)
async def connect(self, config):
    ...

• 自動重試： 連線失敗時指數退避重試（最多 3 次）
• 電路熔斷： 連續 5 次失敗自動熔斷，60 秒後半開測試
• FDE 不需要額外配置韌性層 — 它已內建在所有連接器中

第二章：資料庫連接 #

2.1 PostgreSQL

客戶環境常見情境： 客戶的 ERP 或自有系統使用 PostgreSQL

# .env 設定
DATA_FABRIC_PG_HOST=192.168.1.100
DATA_FABRIC_PG_PORT=5432
DATA_FABRIC_PG_USER=readonly_user
DATA_FABRIC_PG_PASSWORD=xxx
DATA_FABRIC_PG_DATABASE=erp_production

FDE 操作步驟：

1. 向客戶 IT 申請唯讀帳號（永遠不要用 admin/root 帳號）
2. 確認網路可達：telnet 192.168.1.100 5432
3. 在 CORA 中註冊連接器（透過 Forge Console 或 API）
4. 執行 Schema Discovery 確認能看到表格
5. 執行 Health Check 確認連線穩定

安全原則：

• 永遠使用唯讀帳號
• 密碼透過 Forge 加密儲存（Fernet AES-128-CBC）
• 連線字串不寫在程式碼中

2.2 Oracle

客戶環境常見情境： 政府機關的核心系統多使用 Oracle

DATA_FABRIC_ORACLE_HOST=10.0.1.50
DATA_FABRIC_ORACLE_PORT=1521
DATA_FABRIC_ORACLE_SERVICE=GOVDB
DATA_FABRIC_ORACLE_USER=cora_readonly
DATA_FABRIC_ORACLE_PASSWORD=xxx

特別注意：

• Oracle 使用 Service Name（不是 Database Name）
• oracledb 使用 thin 模式（不需要 Oracle Client）
• 如果客戶用 RAC（Real Application Clusters），需要 SID 或 Service Name

2.3 SQL Server

客戶環境常見情境： 使用微軟體系的政府機關或企業

DATA_FABRIC_MSSQL_HOST=192.168.1.200
DATA_FABRIC_MSSQL_PORT=1433
DATA_FABRIC_MSSQL_USER=cora_readonly
DATA_FABRIC_MSSQL_PASSWORD=xxx
DATA_FABRIC_MSSQL_DATABASE=CityGovDB

特別注意：

• SQL Server 預設 port 1433，但客戶可能改過
• Windows 認證 vs SQL 認證 — CORA 目前僅支援 SQL 認證
• 如果客戶使用 Azure SQL，連線字串格式不同

第三章：IM 平台整合 #

3.1 Slack

目的： 讓員工在 Slack 中直接跟 CORA 對話

步驟：

1. 客戶 IT 建立 Slack App
   • 前往 https://api.slack.com/apps → Create New App
   • 選擇「From scratch」→ 輸入 App 名稱（建議「CORA」）
   • 選擇客戶的 Workspace
2. 設定權限（OAuth Scopes）

   Bot Token Scopes:
   - chat:write（發送訊息）
   - app_mentions:read（讀取 @CORA 提及）
   - im:history（讀取 DM）
   - im:write（發送 DM）
   - files:read（讀取上傳檔案）
   - users:read（讀取使用者資訊）

3. 安裝到 Workspace → 取得 Bot Token (xoxb-xxx)
4. 設定 Event Subscriptions
   • Request URL: https://cora.customer.com/api/v1/gateway/slack/events
   • 訂閱事件：app_mention、message.im
5. 在 CORA 環境變數中設定

   SLACK_BOT_TOKEN=xoxb-xxx
   SLACK_SIGNING_SECRET=xxx  （在 App 的 Basic Information 頁面）

6. 重啟 CORA API → Slack adapter 自動啟動
7. 驗證： 在 Slack 中 @CORA 發訊息，確認收到回覆

3.2 Microsoft Teams

步驟：

1. 在 Azure Portal 註冊 Bot Channel Registration
2. 取得 App ID + App Password
3. 設定環境變數：

   TEAMS_APP_ID=xxx
   TEAMS_APP_PASSWORD=xxx
   TEAMS_TENANT_ID=xxx

4. 在 Teams Admin Center 安裝 Bot
5. 驗證

3.3 Email（IMAP 收信 + SMTP 發信）

步驟：

1. 客戶提供一個專用信箱（例如 cora@customer.com）
2. 取得 IMAP/SMTP 設定：

   EMAIL_IMAP_HOST=imap.customer.com
   EMAIL_IMAP_PORT=993
   EMAIL_IMAP_USER=cora@customer.com
   EMAIL_IMAP_PASSWORD=xxx
   SMTP_HOST=smtp.customer.com
   SMTP_PORT=587
   SMTP_USER=cora@customer.com
   SMTP_PASSWORD=xxx

3. 重啟 CORA API → Email adapter 開始 polling
4. 發一封測試信到 cora@customer.com，確認 CORA 回覆

第四章：SSO 身份整合 #

4.1 Azure AD（最常見）

步驟：

1. 客戶 IT 在 Azure AD 中註冊 Application
   • Redirect URI: https://cora.customer.com/api/v1/auth/sso/callback
   • 勾選 openid、email、profile 權限
2. 取得：Application (client) ID、Client Secret、Tenant ID
3. 設定環境變數：

   AZURE_AD_CLIENT_ID=xxx
   AZURE_AD_CLIENT_SECRET=xxx
   AZURE_AD_TENANT_ID=xxx
   AZURE_AD_REDIRECT_URI=https://cora.customer.com/api/v1/auth/sso/callback
   AZURE_AD_ALLOWED_DOMAINS=customer.com

4. 驗證：瀏覽器開啟 CORA → 點擊「使用公司帳號登入」→ 跳轉 Azure AD → 登入成功

4.2 Google Workspace

流程類似 Azure AD，在 Google Cloud Console 設定 OAuth2 Client。

4.3 Okta

流程類似，在 Okta Admin Console 建立 OIDC Application。

FDE 常見問題：

• Redirect URI 必須完全一致（包含 https 和路徑）
• 允許的域名設定錯誤會導致登入失敗
• 客戶的 Azure AD 可能有條件式存取原則阻擋第三方 App

第五章：ERP 整合（Dolibarr） #

5.1 Dolibarr 連接

DOLIBARR_API_URL=http://erp.customer.com:8888/api/index.php
DOLIBARR_API_KEY=xxx  （在 Dolibarr 管理後台取得）

可查詢的資料：

• 產品清單 + 庫存
• 客戶/供應商（第三方）
• 訂單
• 庫存水位

5.2 其他 ERP 系統

如果客戶使用 SAP、Oracle ERP、Dynamics 365 等非 Dolibarr 的 ERP：

• 使用 REST API 連接器 連接 ERP 的 API
• 或使用 資料庫連接器 直接連接 ERP 的後端資料庫（需唯讀帳號）

第六章：醫療資料整合（FHIR / HL7） #

6.1 FHIR R4 連接

適用： 支援 FHIR 的 HIS/EMR 系統

FHIR_SERVER_URL=https://fhir.hospital.com/r4
FHIR_CLIENT_ID=xxx     （SMART on FHIR 認證）
FHIR_CLIENT_SECRET=xxx

可查詢的資源：

• Patient（病患）
• Encounter（就診紀錄）
• Observation（檢驗結果、生命徵象）
• MedicationRequest（用藥醫囑）
• DiagnosticReport（檢查報告）
• AllergyIntolerance（過敏史）

6.2 HL7 v2.x 整合

適用： 使用傳統 HL7 v2 的 HIS 系統

HL7 v2 是訊息格式，不是 API。整合方式：

1. HIS 發送 HL7 訊息到 CORA 的監聽端口（MLLP 協議）
2. CORA 的 HL7v2Parser 解析 ADT/ORU/ORM 訊息
3. 解析後的資料存入 Knowledge Graph

支援的訊息類型：

• ADT（入院/轉科/出院）
• ORU（檢驗結果）
• ORM（醫囑開立）

第七章：整合驗證清單 #

每完成一個資料源的連接，FDE 必須驗證：

常見問題排解 #

04 — 安全與合規配置指南

第一章：五層防禦架構配置 #

1.1 各層職責與配置

1.2 權限矩陣設定

在 config/secretary_policy_default.yaml 中定義：

roles:
  executive:
    allowed_tools: ["*"]
    data_access: ["financial", "operational", "hr_summary"]
    restricted: ["individual_salary", "medical_records"]

  manager:
    allowed_tools: ["office", "crm", "erp", "finance"]
    data_access: ["department_own"]
    restricted: ["other_department", "executive_compensation"]

  employee:
    allowed_tools: ["office", "crm"]
    data_access: ["own_records"]
    restricted: ["financial", "hr", "audit"]

  auditor:
    allowed_tools: ["audit"]
    data_access: ["audit_logs", "compliance_reports"]
    restricted: ["modify_data"]

FDE 操作： 與客戶 IT 主管確認角色定義和權限邊界，然後修改此 YAML 檔案。

1.3 PII 偵測設定

PrivacyGuard 預設偵測以下 PII 類型：

• 電子郵件地址
• 電話號碼
• 身分證字號 / 統一編號
• 信用卡號
• 病歷號（醫療場景）

客製化方式： 如果客戶有特殊的敏感欄位定義（例如內部員工編號也視為 PII），可在 PrivacyGuard 設定中新增偵測規則。

第二章：加密設定 #

2.1 傳輸加密（TLS）

• Nginx 的 SSL 配置已在部署手冊（02）中說明
• 確認所有外部通訊都走 HTTPS
• 內部服務間通訊在 Docker network 內，不經過公開網路

2.2 靜態加密（Fernet）

CORA 使用 Fernet（AES-128-CBC + HMAC-SHA256）加密所有儲存的憑證：

# 產生正式環境加密金鑰
CORA_ENCRYPTION_KEY=$(python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())")

重要：

• 如果未設定 CORA_ENCRYPTION_KEY，系統會使用開發用的 fallback key — 這在正式環境是不安全的
• 合規稽核（HIPAA §164.312(e)）會檢查此項

2.3 JWT 金鑰

# 產生正式環境 JWT 金鑰
JWT_SECRET_KEY=$(openssl rand -base64 48)

JWT 用於：

• 使用者登入後的 session token
• SSO callback 後的身份驗證
• API 存取控制

第三章：合規政策配置 #

3.1 ISO 27001（企業客戶）

CORA 已內建 26 項 ISO 27001:2022 Annex A 控制項的對照。FDE 需要：

1. 執行 runtime compliance check：

   curl https://cora.customer.com/api/v1/compliance/audit | jq

2. 確認 compliance score ≥ 85%
3. 將結果記錄在部署驗收文件中

3.2 HIPAA（醫療客戶）

使用 config/hospital_compliance_policy.yaml：

hipaa_security_rule:
  controls:
    - id: "HIPAA-312a1"
      name: "Unique User Identification"
      check: "verify_unique_user_ids"
      severity: required
    # ... 7 項技術安全措施

FDE 操作：

1. 確認 hospital_compliance_policy.yaml 已載入
2. 執行 HIPAA compliance check
3. 確認所有 required 控制項為 pass
4. 向客戶稽核部門展示 Watchtower 的審計軌跡

3.3 個資法（政府客戶 / 台灣）

台灣個資法要求：

• 個資蒐集前需告知當事人
• 個資使用不得逾越特定目的
• 個資需有安全維護措施
• 個資外洩需通知主管機關

CORA 對應功能：

• PrivacyGuard 自動偵測 PII
• access_groups 控制誰能看什麼
• 完整審計軌跡（Watchtower）
• 加密儲存（Fernet）

第四章：SSO 安全強化 #

4.1 OAuth State 儲存

CORA 的 SSO State Store 支援 Redis 或記憶體：

# 正式環境必須用 Redis（支援多實例部署 + 狀態不因重啟遺失）
REDIS_URL=redis://localhost:6379

4.2 Allowed Domains

限制只有客戶的網域才能登入：

AZURE_AD_ALLOWED_DOMAINS=customer.com
# 或
OKTA_ALLOWED_DOMAINS=customer.com,subsidiary.com

忘記設定 allowed_domains 會導致任何人都能用同一 IdP 登入！

4.3 Session 管理

• JWT Token 預設 24 小時過期
• Refresh Token 支援 token rotation
• 可強制登出所有 session：POST /api/v1/auth/revoke-all

第五章：Rate Limiting 配置 #

5.1 環境變數

RATE_LIMIT_ENABLED=true
RATE_LIMIT_REQUESTS_PER_SECOND=10
RATE_LIMIT_BURST_SIZE=20
RATE_LIMIT_EXEMPT_PATHS=/health,/api/v1/health

5.2 Per-Tenant 限流

如果客戶是多租戶部署：

# 在 API lifespan 中設定
middleware.set_tenant_limit("tenant-a", requests_per_second=50, burst_size=100)

第六章：部署前安全檢查清單 #

每次部署完成後，FDE 必須逐項確認：

12 項全部通過才算部署完成。

05 — 產業手冊：企業製造

第一章：製造業客戶概覽 #

1.1 典型客戶樣貌

• 員工數：100-500 人
• 部門：行政、工程/生產、品管、業務、財務、人資、IT、物流/倉儲、法務
• 核心系統：ERP（生產排程、庫存、訂單）、CRM（客戶管理）、MES（製造執行）
• 通訊工具：Slack 或 Teams + Email
• 痛點優先序：供應鏈反應速度 > 跨部門協調 > 資料孤島 > 合規審計

1.2 SimCorp 參考 Profile

simcorp-profiles/enterprise.yaml — Nexus Global Industries（120 人製造企業）

第二章：關鍵業務流程 #

2.1 供應鏈管理

現狀痛點： 供應商通知延遲時，物流→工程→業務→財務→高管的通知鏈需要 2-3 天

CORA 解法：

• Gateway 接收供應商通知（Email 或 Webhook）
• Spine 自動派發到 5 個部門的 Synapse Agent
• Axion 分析庫存影響 + 替代供應商搜尋
• Foresight 預測延遲延長的風險
• Captain's Deck 即時更新 KPI

展示重點： Observer Console 的 30 秒供應鏈中斷 cascade

2.2 生產品質管理

現狀痛點： 品質問題從發現到通知相關部門太慢

CORA 解法：

• 品管人員透過 Synapse Chat 回報品質問題
• Spine 自動通知工程部 + 物流部（影響出貨）
• Knowledge Graph 查詢受影響的客戶訂單
• Watchtower 記錄完整的品質處理軌跡

2.3 合規審計

現狀痛點： ISO 9001 / ISO 14001 審計前要手動整理文件，花 1-2 週

CORA 解法：

• Compliance Engine 持續追蹤控制項狀態
• Watchtower 提供即時可查的審計軌跡
• 一鍵產出合規報告

第三章：部署配置重點 #

3.1 必裝連接器

3.2 建議的 Skill Pack 配置

啟用：
✅ OfficeSkillPack（文件處理）
✅ FinanceSkillPack（財務查詢）
✅ ERPSkillPack（ERP 操作）
✅ CRMSkillPack（客戶管理）
✅ AuditSkillPack（合規審計）
✅ LogisticsSkillPack（物流查詢）

選用：
☐ HealthcareAdminSkillPack（不適用）

3.3 KPI 配置（Captain's Deck）

建議配置的 8 項 KPI：

1. 訂單達成率
2. 生產稼動率
3. 庫存周轉天數
4. 供應鏈健康度
5. 品質不良率
6. 客訴處理時間
7. 員工加班時數
8. 合規稽核分數

第四章：客製化 SimCorp Profile #

為客戶建立專屬的模擬 Profile 用於 POC：

1. 複製 simcorp-profiles/enterprise.yaml
2. 修改公司名稱、部門結構、員工數量
3. 新增客戶特有的外部實體（供應商、客戶）
4. 調整場景觸發條件（使用客戶實際會遇到的場景）
5. 測試 POC Demo 流程

06 — 產業手冊：醫療院所

第一章：醫療客戶概覽 #

1.1 典型客戶樣貌

• 規模：200-1000 床區域醫院
• 部門：行政、急診、外科、內科、護理、藥劑、放射、檢驗、病歷、IT、財務、人資
• 核心系統：HIS（醫院資訊系統）、EMR（電子病歷）、LIS（檢驗）、PACS（影像）
• 通訊：院內公文系統 + Email，部分使用 Teams/Slack
• 最高優先： 病患隱私（HIPAA / 個資法）> 合規審計 > 營運效率

1.2 與企業客戶的關鍵差異

第二章：醫療法規重點 #

2.1 HIPAA Security Rule（美國 / 國際標準）

FDE 必須確保 §164.312 技術安全措施全部到位：

2.2 台灣醫院評鑑

衛福部的醫院評鑑會檢查：

• 資訊安全管理制度
• 病歷資料保護措施
• 系統備援機制

FDE 須在部署驗收文件中附上 CORA 的安全配置清單。

2.3 個資法特別條款（醫療）

醫療個資屬於「特種個人資料」，蒐集和處理有更嚴格限制。CORA 的 access_groups 機制確保只有 clinical_staff 角色能存取病患資料。

第三章：CORA 醫療功能 #

3.1 行政智慧化（Phase H1 — 可立即部署）

3.2 臨床資料整合（Phase H2 — 需 HIS 配合）

• FHIR R4 連接器 → 讀取病患、醫囑、檢驗
• HL7 v2 解析器 → 接收 ADT/ORU/ORM 訊息
• 臨床本體模型 → Patient / Encounter / MedicationOrder / LabResult

3.3 臨床決策支援（Phase H3 — 進階）

• 藥物交互作用引擎（15 個內建交互對）
• ICD-10 編碼引擎（25 個內建碼 + 可擴充）
• 臨床警報引擎（8 條危急值 + 3 條營運規則）
• ESI 檢傷分類（5 級）

第四章：醫療部署特別注意事項 #

4.1 PHI 存取控制（必做）

# config/secretary_policy_default.yaml
roles:
  clinical_staff:
    data_access: ["patient", "encounter", "medication", "lab_result"]
  admin_staff:
    data_access: ["scheduling", "budget", "procurement", "equipment"]
    restricted: ["patient", "medication", "lab_result"]
  executive:
    data_access: ["kpi", "compliance", "budget"]
    restricted: ["individual_patient_data"]

4.2 審計模組啟用（必做）

確認 6 個醫療審計模組全部啟用：

• phi_privacy（PHI 存取監控）
• medication_safety（用藥安全）
• clinical_safety（臨床決策追蹤）
• credential_scope（憑證管理）
• billing_integrity（帳務完整性）
• info_barriers（資訊隔離 — 42 CFR Part 2）

4.3 備援要求（高於企業標準）

醫院不能接受長時間停機：

• 必須設定 自動 PostgreSQL 備份（每小時而非每天）
• 建議 設定多台伺服器的主從架構（如果客戶預算允許）
• 必須 測試災難復原程序（RTO 目標 < 1 小時）

4.4 網路隔離

醫院通常有嚴格的網路分段：

• 臨床網段（HIS/EMR）
• 行政網段（Email/ERP）
• 公共網段（WiFi）

CORA 伺服器通常放在行政網段，如果需要連接 HIS，需要客戶 IT 開放跨網段通訊。

第五章：醫療客戶培訓特別設計 #

5.1 受眾分層

5.2 培訓禁忌

• 不要在臨床區域做培訓（會影響病患照護）
• 不要使用真實病患資料做 Demo（使用 SimCorp 模擬資料）
• 不要預設所有人都會用電腦（護理站可能還在用紙本）

07 — 產業手冊：政府機關

第一章：政府客戶概覽 #

1.1 典型客戶樣貌

• 規模：100-500 位公務員
• 部門：市長/首長室、財政、公共工程、社會服務、公共安全、都市規劃、法務、人事、IT、市民服務
• 核心系統：公文系統、戶政系統、財務系統、GIS（地理資訊）
• 通訊：公文 + Email（很少用 Slack/Teams）
• 資料庫：Oracle 或 SQL Server 居多
• 最高優先： 資料主權 > 合規 > 透明度 > 效率

1.2 政府 vs 企業的關鍵差異

第二章：政府法規重點 #

2.1 政府採購法

• 金額超過公告門檻需要公開招標
• FDE 不參與採購流程（這是業務和法務的工作）
• 但 FDE 需要配合製作「技術規格書」供招標使用

2.2 個人資料保護法

政府持有大量市民個資（戶籍、稅務、社福、犯罪紀錄等）。

• CORA 必須部署在政府機房內（不能用外部雲端）
• 所有個資存取必須有審計軌跡
• 跨機關資料共享需要法律授權

2.3 資訊公開法

媒體或民眾可以申請資訊公開（類似 FOIA）。

• CORA 的 Watchtower 審計日誌可以作為「AI 決策透明度」的證據
• 這是對政府客戶的賣點：「每個 AI 建議都有跡可循」

2.4 政府資安法規

• 資通安全管理法（資安法）
• 分級分類：CORA 需要符合「機密」或「敏感」等級的防護要求
• 定期資安稽核

第三章：CORA 政府解決方案 #

3.1 跨局處協調

痛點： 預算縮減、緊急事件（水管破裂、颱風）需要多個局處協調，靠公文太慢

CORA 解法：

• Spine 自動派發緊急事件到相關局處的 Synapse Agent
• Knowledge Graph 查詢局處間的依賴關係
• Foresight 預測影響範圍
• Captain's Deck 讓首長即時看到全局

3.2 預算管理

痛點： 經費縮減時，各局處影響評估要開好幾天的會

CORA 解法：

• Axion · Data Fabric 拉取各局處預算使用率
• AI Engine 分析可縮減項目
• Foresight 預測「如果再砍 10% 會影響什麼」

3.3 合規與透明度

痛點： 稽核準備費時、資訊公開申請處理慢

CORA 解法：

• Watchtower 的審計軌跡隨時可查
• Compliance Engine 自動產出合規報告

第四章：政府部署特別注意 #

4.1 部署在政府機房

• 必須地端部署（不能用 AWS/GCP/Azure）
• 伺服器由客戶 IT 準備，FDE 到場安裝
• 可能沒有外網（需要離線安裝 Docker image）
• 離線部署方式： 在有網路的環境先 docker save 打包映像，用 USB 帶到機房 docker load

4.2 Oracle 資料庫連接

政府系統大多使用 Oracle：

• 使用 oracledb thin 模式（不需安裝 Oracle Client）
• 向客戶 DBA 申請唯讀帳號
• 注意 Oracle 的字元集設定（繁體中文可能是 ZHT16BIG5 或 AL32UTF8）

4.3 公文系統整合

CORA 目前不直接整合公文系統，但可以：

• 透過 Email adapter 接收公文通知
• 透過 REST API 連接器連接公文系統的 API（如果有的話）

4.4 使用者抗拒處理

政府公務員可能擔心 AI 取代他們的工作。

FDE 話術：

「CORA 不是取代公務員，而是幫助公務員更有效率。
就像 Excel 沒有取代會計師，而是讓會計師做更重要的分析。
CORA 處理重複性的查詢和通知，讓你們有時間做更有價值的判斷。」

第五章：政府客戶培訓設計 #

5.1 受眾分層

5.2 培訓場地

• 政府通常有訓練教室（要提前預約）
• 確認有投影設備和網路
• 不要在辦公區做培訓（公務員不方便離開座位太久）

5.3 培訓文件

政府客戶特別需要「紙本文件」：

• 印刷版使用手冊
• 教育訓練簽到表（他們需要存檔）
• 系統管理員手冊（交接用）

08 — 客戶需求訪談方法

第一章：訪談前準備 #

1.1 客戶研究

出場前至少做以下功課：

1.2 事前問卷

在正式訪談前，請業務發給客戶一份簡單問卷：

1. 貴公司目前使用哪些主要 IT 系統？（ERP、CRM、HIS 等）
2. 目前哪些工作流程最需要改善？
3. 貴公司員工主要使用哪些溝通工具？（Slack / Teams / Email）
4. 是否有特定的合規要求？（ISO、HIPAA、個資法等）
5. 是否有偏好的部署方式？（公有雲 / 私有雲 / 地端）
6. 預期的上線時程？

1.3 出場裝備

第二章：SPIN 訪談法 #

2.1 框架說明

SPIN 是一套經過驗證的顧問式銷售訪談方法：

2.2 注意事項

要做的：

• 多聽少說（70% 聽、30% 說）
• 用客戶的語言重述確認（「所以你的意思是...對嗎？」）
• 紀錄具體的數字（多少人、多少時間、多少成本）
• 問「為什麼」至少 3 次（深入根因）

不要做的：

• 不要一開始就介紹 CORA 功能（先聽需求）
• 不要用技術術語（說「AI 助理」不要說「LangGraph 狀態機」）
• 不要承諾做不到的事（不確定就說「我確認後回覆」）
• 不要批評客戶現有系統

第三章：訪談結構（60 分鐘） #

3.1 開場（5 分鐘）

「感謝 [客戶名] 安排這次會議。
今天我想先了解貴公司目前的工作流程和挑戰，
然後看看 CORA 能在哪些方面幫上忙。
我會先問一些問題，大概 30 分鐘，
之後如果時間允許，我可以快速展示一下系統。
可以嗎？」

3.2 現狀了解（15 分鐘）

3.3 問題挖掘（20 分鐘）

3.4 影響量化（10 分鐘）

對每個痛點追問：

• 「這個問題大概多常發生？」（頻率）
• 「每次大概影響幾個人？花多少時間？」（規模）
• 「有沒有造成過什麼嚴重的後果？」（風險）
• 「如果有工具能解決，你覺得最大的好處是什麼？」（價值）

3.5 Demo + 收尾（10 分鐘）

如果時間允許，展示 CORA 的某個與客戶痛點相關的功能：

• 供應鏈中斷 → 展示 Observer Console 事件流
• 合規審計 → 展示 Watchtower 審計軌跡
• KPI 可視度 → 展示 Captain's Deck

收尾話術：

「感謝今天的分享。根據我的了解，CORA 可以在 [痛點1] 和 [痛點2] 方面幫到你們。
我會在 3 個工作天內提供一份部署方案書，裡面會有具體的架構、時程和費用。
同時如果您方便，我想跟您的 IT 團隊再約一次技術訪談，
確認系統環境的細節。可以嗎？」

第四章：訪談紀錄撰寫 #

4.1 紀錄範本

（參考 12 號教材附錄 A 的完整範本）

每次訪談結束後 24 小時內 完成訪談紀錄，包含：

1. 客戶背景 — 產業、規模、部門
2. 核心需求 — 按優先序排列（最多 5 個）
3. 痛點描述 — 用客戶的原話記錄
4. 技術環境 — 系統清單、資料庫、IM 工具、SSO
5. 時程期望 — 希望何時上線
6. FDE 判斷 — 建議的配置、預估天數、主要風險

4.2 需求拆解

將客戶的描述性需求拆解為 CORA 可對應的功能：

第五章：常見客戶類型應對 #

5.1 技術導向客戶（IT 主管/CTO）

• 他們會問架構、API、安全、效能
• 準備好： 架構圖、API 文件、五層防禦說明
• 注意： 不要簡化技術細節，他們希望看到深度

5.2 業務導向客戶（CEO/營運長）

• 他們關心 ROI、時程、案例
• 準備好： Before/After 數字（2-3 天 → 30 秒）、其他客戶案例
• 注意： 不要講太多技術，聚焦在「這對你的業務有什麼好處」

5.3 合規導向客戶（稽核/法務）

• 他們關心審計軌跡、資料保護、認證
• 準備好： Watchtower 展示、ISO 27001/HIPAA 對照表、加密說明
• 注意： 他們需要看到證據，不只是說明

5.4 抗拒型客戶

• 「我們試過 AI 了，沒用」「AI 不安全」
• 應對： 不要反駁。問「你之前的經驗是什麼？」然後針對具體問題回應
• 差異化： 「CORA 不同的地方是它跑在你自己的伺服器上，而且每個決策都可以在 Watchtower 追蹤」

09 — 客戶培訓交付指南

第一章：培訓設計原則 #

1.1 核心原則

1. 角色分群 — CEO 和工程師不應該聽同一堂課
2. 動手優先 — 每 15 分鐘講述後必須有 10 分鐘實作
3. 用客戶的語言 — 不說「Synapse Agent」，說「你的 AI 助理」
4. 解決他們的問題 — 用客戶自己的業務場景做範例
5. 留下可帶走的 — 培訓結束發快速參考卡

1.2 標準培訓架構（2 小時）

00:00 - 00:05  歡迎 + 議程說明
00:05 - 00:20  CORA 是什麼（用客戶的語境解釋）
00:20 - 00:35  登入操作 + 基本巡覽
00:35 - 00:50  動手練習 1：用 Synapse Chat 問 3 個問題
00:50 - 01:00  休息
01:00 - 01:20  角色分組：CEO/管理/一般/IT/稽核
01:20 - 01:40  動手練習 2：各組完成自己角色的 3 個任務
01:40 - 01:50  常見問題 + 故障排除
01:50 - 02:00  Q&A + 回饋表

第二章：分群培訓內容 #

2.1 高管組（30 分鐘）

對象： CEO、副總、部門主管

面板： Captain's Deck

內容：

• 打開 Captain's Deck → 看 KPI
• 點擊一個 KPI → 看部門明細
• 問 Synapse：「本月營收跟上個月比如何？」
• 看 Foresight：「如果供應商延遲 3 週會怎樣？」

2.2 一般員工組（30 分鐘）

對象： 所有部門的一般員工

面板： Synapse Chat

內容：

• 登入 Synapse Chat
• 練習問 3 個工作相關的問題
• 了解 AI 能做什麼 / 不能做什麼
• 遇到問題找誰

2.3 IT 組（60 分鐘）

對象： IT 部門

面板： Engine Room + 系統管理

內容：

• Engine Room 巡覽（系統健康、連接器狀態）
• 如何查看系統日誌
• 如何重啟服務
• 如何新增使用者帳號
• FDE 駐場期間的通訊方式和升級流程

2.4 稽核組（30 分鐘）

對象： 稽核/合規/法務

面板： Watchtower

內容：

• 查看審計日誌
• 搜尋特定使用者的操作紀錄
• 產出合規報告
• 了解五層防禦架構

第三章：培訓後交付物 #

3.1 快速參考卡（單頁雙面）

正面：

CORA 快速上手
- 登入：https://cora.yourcompany.com
- 使用公司帳號登入（SSO）
- 在 Synapse Chat 中輸入問題
- 常用指令：「查詢本月訂單」「上週加班時數」

背面：

遇到問題？
- AI 回答不正確 → 重新描述你的問題
- 無法登入 → 聯絡 IT 部門
- 系統異常 → 聯絡 IT 部門 → 升級給 FDE

3.2 培訓回饋表

1. 這次培訓對你的工作有幫助嗎？（1-5）
2. 培訓內容的難度適中嗎？（太簡單 / 剛好 / 太難）
3. 你最想用 CORA 做什麼？（開放題）
4. 有什麼建議？（開放題）

10 — 駐場支援手冊

第一章：駐場支援概覽 #

1.1 三個月的目標

1.2 駐場頻率

• 第 1 月：每週到場 2-3 天
• 第 2 月：每週到場 1-2 天
• 第 3 月：每週到場 1 天 + 遠端支援
• 退場後：遠端支援（依合約）

第二章：第 1 月 — 穩定化 #

2.1 每日例行檢查

# 每天到場後第一件事
curl https://cora.customer.com/health/ready | jq
docker compose ps
docker compose logs --tail=50 api | grep ERROR

2.2 常見問題處理

2.3 週報

每週五提交週報給客戶 IT 主管和 Citrux 內部：

本週摘要：
- 系統可用率：99.8%
- 總使用者數：45 人（+12）
- 總查詢數：320 次
- 解決的問題：3 個
- 下週計畫：推廣到財務部

待解決問題：
1. [問題描述] — 預計 [日期] 解決

第三章：第 2 月 — 深化使用 #

3.1 使用率追蹤

透過 /api/v1/usage/summary 追蹤：

• 每週活躍使用者數
• 每部門使用頻率
• 最常使用的功能
• 使用率低的部門（需要額外輔導）

3.2 進階功能推廣

3.3 客製化調整

根據第 1 月收集到的回饋：

• 調整 Skill Pack 配置
• 新增或修改 system prompt
• 新增資料源連接
• 調整權限矩陣

第四章：第 3 月 — 交接 #

4.1 客戶 IT 培訓（維運交接）

4.2 交接文件

FDE 在退場前必須交付：

4.3 退場報告

提交給 Citrux 內部：

客戶名稱：
部署日期：
駐場期間：
系統配置摘要：
使用者數：
月活躍率：
主要成效：
遺留問題：
客戶回饋：
建議事項：

第五章：SLA 與升級流程 #

5.1 回應時間

5.2 升級路徑

使用者回報問題
  → 客戶 IT 初步排查
  → FDE 遠端支援
  → FDE 到場處理
  → 升級至 Citrux 技術團隊
  → 升級至 Citrux 工程團隊

11 — 故障排除與問題升級

第一章：排查流程 #

1.1 五步排查法

1. 確認症狀 → 使用者看到什麼？錯誤訊息是什麼？
2. 檢查健康 → curl /health/ready → 哪個服務 red/yellow？
3. 查看日誌 → docker compose logs --tail=100 [服務名]
4. 縮小範圍 → 是哪一層的問題？（網路/服務/資料庫/LLM）
5. 修復或升級 → 能修就修，不能修就升級

1.2 健康檢查快速診斷

curl -s https://cora.customer.com/health/ready | jq

第二章：常見問題排解 #

2.1 服務啟動類

2.2 使用者操作類

2.3 資料整合類

2.4 效能類

第三章：日誌查看 #

3.1 各服務日誌位置

# Spine API 日誌（最常看）
docker compose logs --tail=200 api

# Temporal Worker 日誌
docker compose logs --tail=100 worker

# PostgreSQL 日誌
docker compose logs --tail=100 postgres

# Nginx 日誌
docker compose logs --tail=100 nginx

# 即時追蹤（跟隨模式）
docker compose logs -f api

3.2 常見日誌關鍵字

第四章：升級判斷 #

4.1 何時自己處理 vs 升級

自己處理：

• 服務重啟後恢復
• 設定檔修改後解決
• 使用者操作問題（教學即可）
• 已知問題的已知解法

升級到 Citrux 技術團隊：

• 重啟後問題仍然存在
• 程式碼層面的 Bug
• 效能問題找不到根因
• 安全事件（真正的攻擊）
• 資料遺失或損毀

4.2 升級時需要提供的資訊

1. 問題描述（使用者看到什麼）
2. 重現步驟
3. /health/ready 的回應
4. 相關日誌（最近 200 行）
5. 最近是否有做過任何變更
6. 嚴重度判斷（P1/P2/P3/P4）

4.3 升級聯絡方式

• Slack 頻道： #fde-support（內部）
• 緊急電話： [公司緊急電話]
• 工單系統： [工單系統 URL]

第五章：預防性維護 #

5.1 每週檢查清單

5.2 每月檢查清單

12 — FDE 認證考核標準

認證等級定義 #

L1 考核：CORA 架構筆試 + 實機操作 #

筆試（60 題，100 分）

題型分佈：

範圍與出題比例：

通過標準：≥ 80 分

實機操作（8 題，全部完成）

每題限時 5 分鐘，在已部署的 CORA 環境中操作：

通過標準：8 題全部完成

L2 考核：獨立部署 #

考核環境

• 全新的 Ubuntu 22.04 VM（由考官提供）
• 已連接網路（可下載 Docker image）
• 考生自帶 CORA 原始碼（USB 或 git clone）
• 限時 4 小時

評分表

總分 100，通過門檻 70 分

L3 考核：產業知識 + 客戶訪談 #

考核方式

學員選擇一個產業垂直（企業/醫療/政府），完成以下三項任務：

任務一：客戶訪談角色扮演（30 分）

• 考官扮演客戶 CIO/IT 主管（有預設的需求劇本）
• 學員扮演 FDE，進行 30 分鐘需求訪談
• 訪談結束後提交訪談紀錄

任務二：部署方案書（40 分）

根據訪談結果，在 2 小時內撰寫一份部署方案書，包含：

任務三：客戶培訓設計（30 分）

為客戶設計一份 2 小時的使用者培訓大綱：

L3 總分 100，通過門檻 70 分，且任一任務不低於 50%

L5 認證考核：端到端模擬交付 #

考核場景

考官在考前 24 小時公佈場景（三選一抽籤）：

• 場景 A： 200 人區域醫院，現有 HIS + 護理站系統，需要 CORA 行政智慧化
• 場景 B： 150 人製造企業，使用 Dolibarr ERP + Slack，需要供應鏈風險管理
• 場景 C： 180 人市政府，有 Oracle 資料庫 + 公文系統，需要跨局處協調

五天考核流程

評分維度

評分方式

• 3 位評審委員獨立評分（去掉最高和最低取平均，或 3 人平均）
• 每個維度 0-10 分
• 加權後總分 0-100 分

通過標準

• 總分 ≥ 70 分
• 任一維度不低於 5 分（任一項低於 5 分即為不及格，即使總分超過 70）

不及格處理

• 第一次不及格：2 週後可重考（同一場景或不同場景）
• 第二次不及格：需要重修 L3-L4 後才能再次報考
• 第三次不及格：退出 FDE 培訓計劃

持續教育要求 #

FDE-2 認證後的季度要求

觀察期機制

FDE-3 升級條件

附錄：考核文件範本 #

A. 訪談紀錄範本

客戶名稱：________________
日期：__________________
訪談對象：_______________（職稱）
FDE：__________________

一、客戶背景
- 產業：
- 員工人數：
- 現有 IT 系統：

二、核心需求（按優先序）
1.
2.
3.

三、痛點描述
-
-

四、技術環境
- 作業系統：
- 資料庫：
- IM 工具：
- SSO 提供者：

五、時程期望
- 希望上線時間：
- 可配合的測試時間：

六、預算範圍
-

七、FDE 初步判斷
- 適合的 CORA 配置：
- 預估部署天數：
- 主要風險：

B. 部署方案書大綱

一、專案摘要
二、客戶需求分析
三、CORA 系統架構（含客戶環境整合圖）
四、部署時程與里程碑
五、資料整合計畫
六、安全與合規配置
七、使用者培訓計畫
八、風險評估與緩解
九、驗收標準
十、駐場支援計畫（3 個月）

C. 培訓大綱範本

第一部分（30 分鐘）：CORA 是什麼
- 產品介紹（5 分鐘）
- 與你的工作有什麼關係（10 分鐘）
- 登入操作（15 分鐘）

第二部分（45 分鐘）：日常使用
- Synapse Chat 基本操作（15 分鐘）
- 動手練習：問 3 個問題（15 分鐘）
- 常見問題 FAQ（15 分鐘）

第三部分（30 分鐘）：角色專屬（分組）
- CEO 組：Captain's Deck 導覽
- IT 組：Engine Room 導覽
- 稽核組：Watchtower 導覽

第四部分（15 分鐘）：Q&A + 回饋