Technical design / 技術設計工作台
從開發前置條件到資料模型、畫面流程與服務合約，讓產品、工程及營運使用同一份設計。
填寫開發前置設定 ↓本頁是設計文件與設定筆記。App 畫面按鈕只示範流程。QBear schema 及設定表已建立；開發前置設定登入後儲存到 Supabase。
延續項目手冊架構：Flutter 手機 App、Supabase 身份與資料庫、受控 Voice Gateway。公仔是角色與 QR 載體；手機收音及播放是 MVP 假設，硬件語音另行設計。
畫面、登入狀態、相機／咪高峰權限、商店購買及顯示伺服器餘額。UI 不自行加減秒數，也不直接更新 ownership 或 ledger。
從已驗證 JWT 取家長身份；每次檢查公仔所有權、同意及限時。交易統一鎖序；Gateway 只可在有效租約內傳送及生成音訊。
填入非機密設定與負責人，登入授權帳戶後儲存到 Supabase。每個環境獨立版本，可從其他瀏覽器登入載入。
使用此專案的 Supabase Auth 電郵／密碼登入。只有 QBear.configuration_editors 內的帳戶可讀寫；此登入只用於設計設定。
尚未登入。密碼不會儲存在配置內。
QBear在指定 Supabase 專案的 PostgreSQL 建立 schema，並非另建 database。保留精確名稱 QBear：所有 SQL 引用用 "QBear".table_name；未加引號會轉為小寫。
BEGIN;
CREATE SCHEMA IF NOT EXISTS "QBear";
COMMENT ON SCHEMA "QBear" IS
'QBear project: parents, dolls, wallets and voice-session accounting';
REVOKE ALL ON SCHEMA "QBear" FROM PUBLIC, anon;
-- Configuration access is restricted by editor-membership RLS.
GRANT USAGE ON SCHEMA "QBear" TO authenticated, service_role;
COMMIT;
-- Verify after execution; expected result: QBear
SELECT nspname FROM pg_namespace WHERE nspname = 'QBear';MVP 建議保持 QBear 不暴露於 Data API，App 經業務 API 存取。service_role 只放後端且須驗證所有權。未來直讀需要 exposed schema、逐表 SELECT grant 與 ownership RLS；App 不直接寫餘額。Supabase custom schemas 官方文件。
| 資料表 | 保存內容 | 存取 |
|---|---|---|
QBear.configuration_editors | user_id → auth.users、created_at | 管理員配置授權名單；登入者只讀自己的資格，不可自行授權。 |
QBear.project_configuration | environment 主鍵、settings JSONB（全部 30 欄）、revision、updated_at、updated_by | 僅指定編輯者可讀寫；server timestamp／revision；版本衝突拒絕覆蓋。 |
透過 public.qbear_load_configuration / qbear_save_configuration 讀寫，兩者均 SECURITY INVOKER，保留 RLS。QBear 無需加入 exposed schemas；匿名使用者不能呼叫或存取設定。Secrets 只記錄參照名稱。
| QBear 資料表 | 欄位與關係 | 約束及存取 |
|---|---|---|
parents / consents | parents.id → auth.users.id；status；consents.parent_id、version、accepted_at、revoked_at | 只設家長身份；版本化同意；停用／撤回立即阻止新 session。 |
dolls | id UUID PK、serial、owner_id → parents、character_id、state | serial UNIQUE；只讀自己公仔；綁定經 redeem。 |
wallets | doll_id → dolls（PK）、balance_seconds bigint、reserved_seconds bigint、revision | CHECK balance ≥ reserved ≥ 0；available = balance − reserved。 |
sessions | id、doll_id → dolls、parent_id、state、fence_epoch、started_at、closed_at | partial UNIQUE(doll_id) WHERE state IN ('connecting','active','paused')；timestamptz 時間戳。 |
leases | id、session_id → sessions、granted_seconds、settled_seconds、expires_at、state | 每 session 一個 open lease；0 ≤ settled ≤ granted ≤ 15；到期硬停止。 |
ledger | id、doll_id → dolls、session_id、delta_seconds、kind、dedupe_key、created_at | dedupe_key UNIQUE；追加式，不覆寫；補償用新分錄。 |
purchases | id、parent_id、doll_id、store、environment、transaction_key、product_id、state | UNIQUE(store, environment, transaction_key)；驗證完成才加額。 |
qr_codes | id、doll_id、token_hash、pepper_version、redeemed_at、revoked_at | token_hash UNIQUE；HMAC 雜湊；App 不讀；原碼不進 log。 |
outbox / audit | id、event_key、actor、resource、狀態、重試／審計時間 | event_key UNIQUE；outbox 隨交易提交；不存原始語音或 QR secret。 |
owner_id、parent_id 等外鍵查詢欄位建索引；ledger(doll_id, created_at)、leases(state, expires_at)。UUID 作 ID、bigint 作整數秒。餘額以帳本核對，不得負可用額度。
每表啟用 RLS 作額外防線；使用者可讀資料與秘密／付款原文分開。如增加直讀，以 auth.uid() 與 owner 限制行；UPDATE 同時有 USING + WITH CHECK。保留期限由前置設定決策落實。
依據：Supabase RLS 官方文件。完整 migration、policy 及刪除方案留待後續開發，需將原手冊 SQL 基線的物件與關聯一致遷移到 "QBear"，不能混用 public 版本。
點選畫面或線框內的按鈕查看流向。示範資料固定，沒有登入、相機、語音或付款功能。
首頁另有「增值」及「家長設定」分支。額度不足 → 家長增值 → 商店驗證 → 返回首頁。撤回同意 → 停止語音 → 重新同意。
由家長登入，陪好奇心一起長大。
家長是帳戶持有人；兒童無獨立登入。已有登入及有效同意可直接到首頁。
格式錯誤、OTP 過期、網絡失敗及未同意：停留原畫面並提供修正／重試，不建立 session。
Auth → POST /v1/consents → GET /v1/dolls
掃描包裝內防拆標籤的秘密碼。
入口 URL 的 GET 不直接兌換；公仔外部入口與防拆秘密碼分開。碼至少 128 bit CSPRNG；只存帶 pepper 的 HMAC 雜湊。
無效碼、已兌換、429、回應遺失：同冪等鍵重試；同家長同碼返回原結果，不重複贈送。
POST /v1/activations/redeem
每隻公仔獨立錢包；available = balance − reserved。
無公仔 → 啟動提示；0 秒 → 禁止開始及提供家長增值；已有 session → 返回現有對話；載入失敗 → 重試，不把快取餘額作權威值。
GET /v1/dolls · /v1/dolls/{id}/wallet
AI 陪伴 · 時間為固定示例
你可以問：「今天有甚麼小故事？」
connecting → ready／listening ↔ speaking → paused → closing → closed。咪高峰有明確指示；背景立即停止媒體。
權限拒絕、逾時、供應商故障、0 秒、安全 gate 或 lease 到期：停止聲音並說明原因。20 秒無互動自動暫停；App heartbeat 不延長租約。
POST /v1/sessions · /pause · /resume · /close
使用量、餘額與 revision 由 close API 回傳，不能以畫面倒數推算。
close 回應遺失 → 結算中；同冪等鍵重試或讀 session。不得本地重扣，pending 不顯示完成。
POST /v1/sessions/{id}/close · GET /v1/dolls/{id}/ledger
驗證成功才加額；pending 不加秒。
purchase intent 綁定家長、公仔與商品，再開商店原生 sheet；App 回傳成功不代表後端已驗證。
取消、pending、驗證失敗、重複通知及退款。退款追加補償分錄；不足額時停用待營運處理，不造成負可用秒數。
POST /v1/purchase-intents · /v1/purchases/verify
敏感操作重新驗證家長；上限由後端按家庭時區與帳本計算，不能以手機時鐘繞過。
更新衝突 → 重讀；刪除 pending → 顯示狀態。不能只刪 auth user 留有效 session；後端即時查停用狀態。
PATCH /v1/parent-settings · POST /v1/consents · DELETE /v1/account
目前：01 登入／同意。點選可看流程，不執行 App 功能。
API 前綴為設定的 API URL + /v1。HTTPS、驗證家長 JWT、從 token 取身份；body 的 parent_id 不作授權。寫操作有 request_id、Idempotency-Key 與 body hash；同鍵不同 body 回 409。
| 方法與路徑 | 輸入 → 輸出 | 規則 |
|---|---|---|
GET /dolls | JWT／公仔 → 公仔、balance／reserved／available／revision、分頁帳本 | 每次檢查 ownership；跨家庭不可見。 |
POST /activations/redeem | qr_token、consent_version → doll_id、granted_seconds、revision | 一次綁定並送 3,600 秒。 |
POST /sessions | doll_id、device_nonce → session_id、Gateway token、protocol、expires_at | connecting 不扣額；30 秒未 ready 清理；每公仔一個 session。 |
POST /sessions/{id}/pause | 冪等鍵 → state、settled_seconds、wallet revision | pause／close 停媒體、結算、釋放；resume 重查限制並發新 token／lease。 |
POST /purchase-intents | doll_id、store、product_id → intent；intent_id＋receipt → pending／credited | 交易身份去重；正式／sandbox 分開。 |
GET /parent-settings | 上限、家庭時區、version → 新設定／version | 家長驗證；版本衝突 409；後端 enforcement。 |
POST /consents | 同意／撤回、event ID／類別、重新驗證 → 狀態或 202 job | 停用優先於媒體；安全回報最小資料。 |
POST /internal/leases/* | 可信累積用量／平台通知 → 結算／接受事件 | Gateway mTLS／服務簽章；webhook 驗簽去重；不給 App。 |
驗同意 → HMAC → 鎖 QR → wallet → 綁 owner → +3,600 → 唯一 ledger → redeemed → outbox → commit。鎖序由 QR（如有）→ wallet → session → lease，所有交易一致。同家長同碼返回原結果。
Gateway ready 預留最多 15 秒，每 5 秒提交可信累積毫秒；檢查 fence、期限及 event 去重。消耗同時減 balance 與 reserved，釋放只減 reserved；每 session 一個 open lease。
intent → 商店 → server verify → 鎖 wallet → 去重 purchase → 加額 → ledger → outbox → commit。取消、pending、驗證失敗不加額。
累積毫秒中途 floor、最終一次 ceil；跨租約留餘數。到期／DB 故障／gate 不可用即停媒體。只扣持久化可信證據，未知尾段由營運承擔。
401 登入；403 / 404 不可存取；402 秒數不足；409 綁定、version 或冪等衝突；422 修正輸入；429 按 retry-after；503 暫停後重試。逾時不代表交易失敗，用相同冪等鍵或查狀態；只對可重試錯誤採有抖動的退避。
Feature 分為 auth / activation / dolls / voice / wallet / purchases / parent，各有 screen、狀態控制器、repository 與 typed DTO。共用 HTTP client 處理 JWT refresh、request ID 與錯誤映射；repository 為資料入口。voice 狀態機驅動 UI，與音訊 transport 分離；開發時確認並鎖定 Flutter／SDK 版本。
目前已交付設計 HTML、QBear schema 及雲端設定儲存；Flutter App、語音、付款與業務資料表尚未開發。