關於／部署
關於 HiZex AI，以及 Herald 怎麼交付到您手上
Herald 以 Node 22 打包成單一容器映像，跑 api、worker、console 三個 process，加上 Postgres 與 Redis。可以在我們的雲上、您的機房裡，或兩者之間。
關於
HiZex AI：把對話搬進組織已經在用的管道
HiZex AI 開發兩個互補的產品：HiZex Herald（LINE 優先的通知、報名、簽核與客服平台）與 HiZex Avatar（AI 語音／視訊顧問）。Herald 起源於某大學的校園訊息平台設計案，把「通知是對話的特例」做成一套可稽核的引擎。
HiZex Herald
一個入口、多種管道、可對話、可稽核。單位擁有內容與受眾；名單、同意、配額、審核、稽核由平台統一。
HiZex Avatar
文字對話走到需要「人」的時候，帶著脈絡交給 AI 語音／視訊顧問；結果與事實回流 Herald。
三個原則
個資留在客戶端；規則寫進資料庫約束而非承辦人的判斷；少了任何鄰居只降級、不當機。
公司資訊、團隊與聯絡地址 【待補】；聯絡：hello@hizexai.com。
三種選項
雲端、On-prem、混合
雲端託管
由 HiZex AI 在 hizexai.com 營運您的租戶。您提供管道憑證（LINE channel、SMTP、Meta app）與 SSO 設定；資料庫在您指定的區域。
On-prem 發行版映像
交付 herald:dist（esbuild 打包，無原始碼、無 sourcemap）、compose 檔、.env.example、授權 JWT。映像內容可檢查：不含任何 .ts。
混合
Herald 與名單在您的網段；共用 AI core（知識／記憶／LLM）與 HiZex Avatar 在雲端或同網段。缺少鄰居只降級、不當機。
node scripts/build-dist.mjs # esbuild → dist/app/{api,worker,console}.js
docker build -f Dockerfile.dist -t herald:dist . # bundle + production deps + migrations
docker compose -f docker-compose.yml -f docker-compose.app.yml -f docker-compose.dist.yml \
--profile herald --profile context up -d --build授權
授權 JWT 綁客戶、到期與功能
- 機制
- 設定 HERALD_LICENSE_PUBLIC_KEY（RS256 公鑰）後，啟動必須帶有效的 HERALD_LICENSE（HiZex AI 簽發的 JWT：客戶、到期、功能）
- 寬限
- 過期有 14 天寬限並警示，之後拒絕啟動
- 開發
- 未設公鑰＝開發模式不檢查
- 交付清單
- herald:dist、共用 AI core 映像（可選）、三個 compose 檔、.env.example、授權 JWT、文件（可選擇性提供）
資料留存原則
個資留在客戶端
Herald 是對象／地址／同意的系統紀錄，所以它必須跑在資料應該在的地方。
系統紀錄在 Postgres
所有狀態、帳本、稽核在您的 Postgres；沒有外部佇列。Redis 只放可重建的東西（限流視窗、nonce）。
憑證只在伺服器
LINE token、SMTP 密碼、VAPID key 由 vault / KMS 注入環境變數，當 adapter 建構參數；瀏覽器永遠拿不到。.env 不進映像。
訊息不含機敏內容
成績、金額、諮商紀錄被內容政策擋在型別層；push 只有一句話與一個動作，細節在 SSO 後面。
AI 記憶可撤銷、可遺忘
記憶事實有有效期、可撤銷；「全部遺忘」一鍵清除並留稽核。永遠不含成績與金額。
保存期限由您訂
delivery、inbox、對話、問卷回應、稽核各自有建議期限；程式提供刪除工作，不提供「永久」。
雲端託管時
資料庫在您指定的區域，HiZex AI 只持有營運所需的最小權限；名單匯出一律留稽核。
| 資料 | 建議保存 | 到期動作 |
|---|---|---|
| 投遞明細、渲染 payload | 6 個月 | 刪除明細，保留訊息統計 |
| 訊息中心項目 | 封存後 12 個月 | 刪除 |
| 對話紀錄 | 6 個月 | 刪除；標籤保留 |
| 問卷、報名回應 | pattern 關閉後 12 個月 | 刪除，保留報表快照 |
| 稽核 | 5 年 | 歸檔 |
| 同意（含撤回） | 撤回後 5 年 | 歸檔 |
網域拓樸
hizexai.com 與 hizex.ai 怎麼互指
| 網域 | 服務 | 內容 |
|---|---|---|
| hizexai.com | Herald api | 對外：LINE／Meta／Email webhook、系統事件、訊息中心 API、Avatar 回呼；/docs 為 OpenAPI |
| console.hizexai.com | Herald console | 內網或 SSO 後；不對公網 |
| hizex.ai（app.hizex.ai） | HiZex Avatar 前端 | LINE 卡片連過去的頁面 /zh-TW/service/{uuid}?ctx= |
| api.hizex.ai | Avatar dispatcher | /join_room、/api/handoff/session |
| livekit.hizex.ai | LiveKit | WebRTC |
| 內網 | 共用 AI core | 只被 Herald／Avatar 後端呼叫，不對外 |
| 外部平台 | 要填的 URL |
|---|---|
| LINE Developers | Webhook https://hizexai.com/v1/webhooks/line-messaging |
| Meta（WhatsApp／Messenger） | Callback …/v1/webhooks/whatsapp-cloud、…/messenger；verify token |
| 業務系統 | POST https://hizexai.com/v1/events/{source}，HMAC key |
| HiZex Avatar → Herald | POST …/v1/webhooks/avatar、GET …/v1/handoffs/{id}（X-Handoff-Key） |
on-prem 時以您的網域取代 hizexai.com；連結白名單必須含您的網域、hizexai.com、hizex.ai 與 liff.line.me。
安全
簽章、同意、mock 守衛
| 入口 | 驗簽 | 其他 |
|---|---|---|
| LINE webhook | X-Line-Signature HMAC-SHA256，constant-time 比對；依 destination 選 secret | body ≤ 1 MB、事件 ≤ 100／請求；先驗簽再 parse |
| 系統事件 | X-PU-Signature v1=HMAC-SHA256(secret, ts.body)，±300 s，nonce 重放保護 | 重放回 202 duplicate；金鑰可兩把並存供輪替 |
| Avatar 回呼 | 同系統事件 | 身分連結 best-effort |
| Email provider | x-email-signature HMAC；未設定 secret 全部拒絕 | 只接受 bounce / complaint |
| Producer API | per-unit credential：Bearer hub_<id>_<secret>；DB 只存 sha256 | 範圍限定分類、受眾維度、個別指定 |
| 主控台 | SSO（OIDC、JWKS 驗簽）；session cookie HttpOnly、SameSite | 開放轉址防護；CORS 只允許 console 網域 |
| 使用者端 | LINE id token 向 LINE 驗證 | 未綁定 → 401 |
同意在最外層
受眾查詢的型別上無法表達同意範圍；resolver 一律 ∩ hasConsent(scope)。撤回立即生效於下一次解析。
Mock 守衛
LINE_MOCK、EMAIL_MOCK、SSO_MOCK、CAMPUS_MOCK 各自一個開關；NODE_ENV=production 開著任何一個就拒絕啟動；PGlite 僅限開發。
限流
對外可達的前綴共用滑動視窗（每 bucket 60 次／分鐘），bucket 依 producer key → 使用者 → IP；Redis 跨副本共用。