Cosmic Story v2 架構——深入剖析。

專為工程師、產品經理、記者與合作夥伴探查者而設。完整的流程管線、四個 MongoDB 集合、EDA 事件、V-Model 的嚴謹度、效能目標、安全性與無障礙設計——全都在同一頁上。

  • Soulwise-story 是一個全新的 NestJS 模組，與既有的 cosmic-story 模組並存。功能模組之間沒有任何直接匯入。
  • 四個 MongoDB 集合：soulwise_persons、soulwise_chapters、soulwise_journal_entries、soulwise_resonances。本文以 AES-256 加密，並依各自服務的查詢建立索引。
  • 透過 BullMQ 佇列進行非同步生成，逾時設定為 28 秒。事件僅在資料庫提交後才由 EventEmitter2 發出——不會出現幽靈收件項目。
  • V-Model 規格：119 項需求，零落差。後端覆蓋率目標為服務的 85% 陳述式；前端為 Pinia store 的 90%。

再看一次這條流程，附上工程細節

每個步驟都有一個服務、一份合約與一個事件。

  1. 觸發

    一個使用者動作——「為姊妹生成今日篇章」——或是排程的 cron 工作，例如週日 9 a.m. 的回顧，或每 6 小時一次的天象更新。

  2. 佇列

    這項工作會進入名為 soulwise-chapter-generation 的 BullMQ 佇列，並設有 28 秒的硬性逾時限制。執行過久的工作會被中止，並向使用者回報「請再試一次」。

  3. 組合

    ChapterGenerationService 會將四大要素的提示——人物脈絡、占星、訊號、節奏——組合成單一輸入。沒有任何原始使用者個資會原封不動地進入提示；所有內容都會先經過清理。

  4. 生成

    系統會透過 AI_GENERATION_ADAPTER 符號權杖呼叫 AI 服務供應商，供應商可隨時替換。在繼續之前，會先檢查回應的長度、結構與安全性。

  5. 後處理

    此時會發生四件事：危機分類器會檢查是否出現危機語言；面向標籤擷取器會拉出一到三個星象標籤；反斷言過濾器會移除禁用的措辭；內文則以平台管理的金鑰進行 AES-256 加密。

  6. 保存

    這份成品會寫入對應的 MongoDB 集合——章節、日記條目、共鳴——並建立 userId 與 personId 索引以便快速查詢。先進行軟刪除；個人識別資訊則在 30 天後硬刪除。

  7. 通知

    資料庫提交後，會觸發一個 EventEmitter2 事件——CHAPTER_COMPLETED、JOURNAL_CREATED。通知模組接收後會建立一則收件匣項目，並可選擇發送推播（每天最多一次，並尊重勿擾時段）。

  8. 呈現

    前端會透過已驗證的 API 呼叫拉取這份成品。Hub 會以新內容重新渲染。若你當時離線，快取會提供昨天的畫面，新成品則會在重新連線時出現。

從觸發到呈現共七個步驟，每一步都以它實際的功能命名。

四個集合

依各自負責回應的查詢建立索引。

soulwise_persons

相簿項目。在 userId、status、deletedAt 上建立索引。先進行軟刪除；個資則在 30 天後硬刪除。

soulwise_chapters

由 AI 撰寫的篇章，本文加密。在 personId、userId、generatedAt 上建立索引。相位標籤另存為獨立陣列，方便快速篩選。

soulwise_journal_entries

由你親自撰寫的省思，本文加密。在 userId、personId、createdAt 上建立索引。本文建立文字索引以供搜尋。每則項目皆有「私密——請勿提供給 Luminara」的標記。

soulwise_resonances

每段關係皆有四個維度的分數。在 personId 上建立唯一索引。每次寫入篇章或札記後，透過服務呼叫重新計算。

EDA 事件

嚴格規則：事件只會在資料庫提交（commit）之後才觸發。跨模組相依透過 Symbol 注入權杖（injection token）處理，絕不使用 forwardRef。功能模組之間不得有直接的服務對服務（service-to-service）匯入。

  • SoulwiseEvents.CHAPTER_COMPLETED — SoulwiseEvents.CHAPTER_COMPLETED — 在章節經過加密並持久化儲存後觸發。Notifications-v2 會監聽此事件；建立收件匣項目；並可選擇性發送推播。
  • SoulwiseEvents.JOURNAL_CREATED — SoulwiseEvents.JOURNAL_CREATED — 在日誌項目經過加密並持久化儲存後觸發。Resonance 服務會監聽此事件；並觸發重新計算。
  • SoulwiseEvents.PERSON_BIRTH_UPDATED — SoulwiseEvents.PERSON_BIRTH_UPDATED — 在某人的出生資料變更後觸發。合盤快取會失效。
  • SoulwiseEvents.PUSH_REQUESTED — SoulwiseEvents.PUSH_REQUESTED — 依 notifications-v2 合約規範；遵守推播額度與勿擾時段。

V 模型規格嚴謹度

119 項可追溯需求，零缺口。每項需求都向前對應到一個測試案例（UTP、ITP、STP、E2E），並向後對應到一則使用者故事。20 則使用者故事。15 項功能性需求。12 類非功能性需求。8 道全域驗收關卡。

效能合約

章節生成在 95% 的請求中達到 30 秒或更快，以 BullMQ 工作時長分布為衡量基準。API 在 1,000 名並行使用者下，GET 的 p99 延遲達到 500 毫秒或更佳，以 k6 負載測試衡量。前端在模擬 4G 環境下 TTI 達到 3 秒或更快，以 Lighthouse CI 衡量。

安全性合約

日誌與章節內文在靜態儲存時採用 AES-256 加密，並使用平台管理的金鑰。傳輸過程採用 TLS 1.2+；並進行 HTTP→HTTPS 轉址。JWT 存取權杖（access token）的有效期為 1 小時，更新權杖（refresh token）的有效期為 30 天，並於更新時輪替。採用軟刪除機制，並在硬刪除個人識別資訊（PII）前保留 30 天的緩衝期。

無障礙合約

全域遵循 prefers-reduced-motion 設定——GSAP 動畫會轉為純粹的淡入淡出。每個互動元素都附有 VoiceOver 與 TalkBack 標籤。每次發布前都會在 iOS 與 Android 上手動驗證。

為什麼要另建獨立的 soulwise-story 模組，而不是擴充 cosmic-story？

因為上游規格等同重建這項功能，而在既有模組內重建，要嘛會破壞 v1 的體驗，要嘛得先分支再合併。新建模組能讓 v1 維持原狀，讓 v2 充分驗證，並在準備就緒時順利遷移。

為什麼選 MongoDB 而不是 Postgres？

現有的 My Zodiac AI 後端就架在 MongoDB 上；若要更換，等於做出與這項功能無關的基礎架構決策。再者，文件模型也很適合章節與日誌條目——巢狀、長度不一、以加密 blob 形式儲存。

為什麼佇列選用 BullMQ？

BullMQ 跑在 Redis 上，而 Redis 早已在技術堆疊中用於工作階段與速率限制。不需新增任何基礎架構。內建的重試、逾時與可觀測性，足以滿足章節生成的需求，無須額外自訂配置。

上游規格實際上記錄在哪裡？

內部儲存庫。本頁的數字與契約是上游 V-Model 文件的摘要轉述。My Zodiac AI 部落格叢集上的公開工程文章（標記為「cosmic-story-v2」）會更深入地剖析這次開發的特定環節。

立即體驗 My Zodiac AI

當 Soulwise 掀起浪潮之際，我們的旗艦占星應用程式早已在你手中。

下載自App Store取得應用程式Google Play

星座內容僅供反思與娛樂之用。此處所述的 Cosmic Story v2 功能仍在開發中；是否推出可能隨時變動，恕不另行通知。