給家庭的學習產品
Ray The Whale 不是單次背單字工具，而是把「生活中的輸入」變成「可持續複習資產」的家庭學習系統。
RAY THE WHALE SPECS
同一份規格，兩種閱讀視角
這一頁把產品規格拆成「給家長/使用者」與「給技術同學」兩段。前半段先回答你會得到什麼，後半段再說明系統如何落地與如何驗證。
FOR FAMILIES
先看你會怎麼用
低摩擦四步循環
拍照或輸入 -> AI 抽取 -> 家長確認 -> 每日短練，孩子每天只面對真正值得複習的內容。
透明可追蹤
功能、進度、規格公開同步，家長能看到我們做到哪裡，也能知道下一步要做什麼。
核心學習閉環
01
錄入
圖片圈圖、圖片筆記、手動單詞、手動詞組都走同一 Intake 流水線。
02
識別
OCR/LLM 產出預覽詞條，明確標示成功、失敗與可重試狀態。
03
確認
家長可編輯、刪除或部分提交，確保入庫前是可控資料。
04
學習
根據每日上限與記憶曲線進行短時段複習，完成後回到 Ray 進度回饋。
為什麼要先預覽再入庫？
因為家庭場景中的原始輸入可能有噪音。先預覽可以把錯詞、重複詞和不需要內容先過濾，保持詞庫乾淨。
可以只用手機操作嗎？
可以。核心流程（錄入、預覽、詞庫、每日學習、我的設定）都支持手機視口，Web/iPad 只是更寬視圖。
如果識別失敗怎麼辦？
系統會返回失敗原因並提供重試入口；同一批次會保留可成功項目，避免整批重來。
FOR ENGINEERS
再看這套系統怎麼實作
Client Surface
apps/web（官網 + /app）與 apps/mobile（uni-app H5-first）共享 contracts 與核心資料語義。
Next.js 15, TypeScript, Tailwind, Playwright
API & Worker
apps/api 提供 v1 契約接口；apps/worker 處理 OCR/異步任務，狀態寫回 message timeline。
NestJS, BullMQ, Redis, systemd services
Domain & Shared
domains/* 封裝業務邏輯，shared/* 承載 contracts/database/utils/storage，保障多端一致。
Monorepo, TS project references, PostgreSQL migrations
核心 API 契約
POST
/v1/messages/intake統一 4 種錄入場景，創建 intake job。
POST
/v1/preview/confirm部分成功提交，返回 committedItems/failedItems/summary。
POST
/v1/ocr/tasks/:id/retry對可重試失敗任務做鑑權重試。
POST
/v1/integrations/feishu/eventsFeishu webhook ingress，轉入同一 intake pipeline。
GET
/v1/ray/home聚合 Ray 首頁進度、連續天數與今日任務狀態。
本地質量門禁
pnpm typecheck
pnpm lint
pnpm build
pnpm --filter @ray/mobile test:e2e
規格文檔索引
發布策略
默認走 GitHub Action `Deploy Spectrum`，僅在 Action 因平台/憑據失敗時才回退本機 `deploy/deploy-spectrum.sh`。