技術規劃

架構與路線圖

呢頁係 Mallows.ai 嘅 living 技術計劃 — 由而家嘅單用戶 calendar insights 引擎，一路演變成多租戶產品：日常工具、billing、transcription 智能分析、team／manager 協作、HR／組織分析、香港公司秘書服務，同 lead generation。內容會跟住產品進度持續更新。

架構概覽

現時嘅 stack：單一 Node process、自家寫嘅 router、JSON 檔案儲存（src/lib/store.ts，用 atomic temp+rename 寫入，未有真正嘅 DB）、Google OAuth 靠 raw fetch 實現（src/lib/google.ts）、signed-cookie session 冇 session table（src/lib/session.ts）、用 APP_SECRET 做 AES-256-GCM 加密嘅 refresh token（src/lib/crypto.ts），同一個純計算、冇 I/O 嘅 insights 引擎（src/lib/insights.ts）。部署方式係 Docker → ECR → Coolify → EC2，透過 GitHub Actions，預設 region 係 ap-southeast-1。

你嘅瀏覽器未能顯示架構圖：前端 → API 層 → 資料庫／背景任務 → 外部整合。

隨住路線圖推進，有三項架構轉變係無可避免：

  • JSON 儲存 → Postgres — 而家嘅 JSON 檔案有並行寫入嘅 race condition，team／HR／公司秘書都需要跨用戶 aggregation query，公司秘書嗰邊仲要 companies／directors／shareholders 嘅 relational integrity。
  • 真正嘅 router + background job queue + object storage — 一旦日常工具（PDF／OCR／圖片處理）同 transcription 上線，呢啲操作又慢又食 CPU，唔可以卡住 request thread；上傳嘅檔案亦都唔可以淨係放喺 JSON 儲存或者 ephemeral container disk。
  • 真正嘅 organizations + memberships 多租戶模型 — 取代而家每個用戶身上嗰個隱含嘅 domain 字串，因為 team／HR／公司秘書／billing 全部都需要呢個模型。

未來仲需要新增嘅整合：一個識廣東話嘅 speech-to-text provider、一個 LLM API（用嚟做 summarization、會議紀錄草擬、outreach 草擬 — 現有嘅 insights.ts 會維持純計算，唔會加 LLM）、Stripe（HKD／SGD，per-seat 同 usage-metered billing 都要支援），同埋一個延後先做嘅文件／e-Stamping 整合（畀香港公司秘書服務嘅股份轉讓印花稅文件用）。由第一日開始，DB 同 object storage 都會擺喺 ap-southeast-1，因為 HK／SG 嘅 data-residency 考量。

AI Com Sec：需要新增的證據與溝通層

公司 Dashboard、文件庫和公司日曆現時可組合出「已知事項」的工作台；但要成為可追溯的 AI 公司秘書，不能把 OCR／AI 建議直接寫入公司資料，也不能把「文件已上載」或「已提醒」當成法定完成。以下是下一個基礎設施增量，會和現時公司資料分開保存：

  • 文件版本及來源欄位 — 每個擬寫入欄位保留 source document、版本／hash、頁碼、抽取方法、信心度及衝突資料；只在指定核對人接受後，才成為 verified fact。
  • 年度工作實例 — 每個公司、每個死線的資料準備、草稿、待簽、客戶確認已遞交、遞交證明已核對、完成，連同 filing／支持文件關聯。現時計算出的日曆事項沒有這個完成狀態，故不能顯示為「已完成」。
  • 文件生成與 EDM outbox — NAR1／日後 ND2A 的模板版本、輸入資料快照、草稿 hash 和核對紀錄；EDM 另存預覽、審批、排程、送達／失敗及客戶行動。預覽不等於已寄。
  • 公司範圍審計帳 — 針對核對、接受／拒絕、狀態變更、文件生成和通知的 append-only 安全 metadata；現時一般 audit log 不應被說成法定證據帳。

私隱邊界：原始公司文件可能含住址、身份證明及稅務資料。任何文件分析必須先有清晰通知／同意、可選手動輸入、資料最小化和 provider／處理地披露；AI 助手只可使用明示選取、經遮罩的公司範圍摘要，不能自動發信或遞交。

分階段路線圖

以下順序反映真正嘅依賴關係，唔淨係功能優先次序。✓ 代表已經完成，◐ 代表部分完成，○ 代表仲未開始（計劃中）。

Phase 0 — 基礎建設

呢個 phase 卡住之後所有 phase。

  • ✓Google OAuth + domain restriction、加密 refresh token、signed session、JSON 儲存、Recapped insights 引擎、dashboard、Docker／Coolify／EC2 pipeline、config resolution — 呢啲已經全部上線已完成
  • ✓Postgres 部署 + 手寫 numbered migration tool（runMigrations()，喺 server 啟動時自動執行），保留 store.ts 現有嘅 function signature 唔使改 caller已完成
  • ✓organizations + memberships schema，取代咗隱含嘅 domain／admin heuristic，並且由現有用戶 backfill已完成
  • ✓insights.ts（16 種工作人格）同其他核心 lib 已經有 node:test 測試覆蓋已完成
  • ○喺日常工具將 route 數量推過大約 15 條之前，先升級 router（或者轉用 Hono）— 而家 server.ts 已經有 80+ routes，遠超呢個門檻，仍然未做，需要盡快重新評估計劃中
  • ○S3-class object storage + signed URL；Postgres jobs table + worker process — 而家仲未有實際使用場景需要呢個計劃中
Phase 1 — 日常工具

冇 org／billing 依賴，最快可以上線。

  • ✓PDF 操作（compress／merge／split／電子簽名）、檔案格式轉換、圖片壓縮、雙語 OCR、QR code、短網址／redirect link + click 分析 — PDF 密碼保護因為技術限制（pdf-lib 冇 encryption 支援）永久取消已完成
  • ✓每個 endpoint 都加咗 usage-metering hook（recordUsage），畀將來 billing 用已完成
Phase 2 — Billing

需要 Phase 0 嘅 org 模型 + Phase 1 嘅 usage 數據。

  • ✓Stripe 整合（test-mode scaffolding）、subscriptions table 擴充咗 Stripe 欄位、checkout／portal／webhook routes、雙語 OCR 已經 gate 咗做 Pro-only 功能已完成
  • ○需要真實 Stripe test／live keys（STRIPE_SECRET_KEY、STRIPE_WEBHOOK_SECRET、STRIPE_PRICE_ID_PRO_HKD、STRIPE_PRICE_ID_PRO_SGD）先可以做真正嘅 checkout／webhook end-to-end 驗證計劃中
Phase 3 — Transcription 智能分析
  • ○Speech-to-text provider spike（廣東話準確度係關鍵評核標準）、job-queue pipeline、LLM summarization 連 token／cost logging、雙語輸出計劃中
Phase 4 — Calendar 分析擴展
  • ✓Calendar write-scope 同意流程（獨立於讀取版連接，/auth/google/write-start）、自動封鎖嘅 focus time（/api/focus-time/generate，per-run opt-in）、時區重疊建議（timezoneOverlap.ts，純函數）、通知摘要（POST /api/internal/send-weekly-digests，由 INTERNAL_CRON_SECRET 保護——仍然需要外部 scheduler 實際觸發呢個 endpoint，未喺呢度接埋）已完成
Phase 5 — Team／manager 協作

硬性依賴 Phase 0 嘅 org 模型。

  • ✓跨用戶 aggregation query layer（src/lib/aggregates.ts），honour 返 sharesAggregates consent flag，淨係彙總已經同意分享嘅成員數據已完成
  • ○Heatmap、1:1 assistant、站立會議摘要、burnout 訊號計劃中
Phase 6 — HR／組織分析

依賴 Phase 5。

  • ✓全機構成本彙總（重用 Phase 5 嘅 aggregation layer）+ consent-gated engagement dashboard（hr-dashboard.html，org-admin only）已完成
  • ✓HK／SG 法定假期日曆（2026／2027，來源：政府憲報／勞工處、MOM／data.gov.sg）已完成
  • ✓MPF／CPF 供款死線提示（來源：mpfa.org.hk、cpf.gov.sg）已完成
Phase 7 — 香港公司秘書服務

全新領域，排喺核心基礎設施驗證之後；schema 以外嘅部分要另做研究先可以繼續。

  • ✓公司秘書領域模型（companies、directors、shareholders／register of members、significant controllers、charges、filings、股份交易、買回程序）已完成
  • ✓Companies／directors／shareholders／registers schema 喺 Postgres 入面，具備完整 relational integrity已完成
  • ✓Annual Return／NAR1 申報追蹤已完成
  • ✓公司法定申報日曆（/company-calendar）— 跨公司彙總 BR 續期、NAR1（私人／擔保／公眾公司三種計法）、利得稅（N／D／M code）、Employer's Return、MPF、押記登記等死線，每個項目都有來源引用；公司秘書頁面亦加咗「下一個死線」提示橫額已完成
  • ✓HK 法律／稅務／MPF 法定要求參考頁（/compliance-reference）— 完整引用公司條例、利得稅、僱傭條例／MPF 法例嘅死線同罰則，未生效嘅建議（例如 MPF 供款上下限調整）明確標示為「未生效」已完成
  • ✓董事任免、股份登記冊、變更登記資料流程（住址／公司名稱／組織章程）+ 股份買回（buyback）流程已完成
  • ✓股份轉讓印花稅文件生成 — Bought Note／Sold Note PDF 自動化，重用已計算嘅印花稅／過戶資料已完成
  • ✓Significant Controllers Register（SCR）同 Charges（押記登記／解除）— 基本新增／終止資格、登記／解除已經有 route + UI；NR2 表格、法定通知死線自動追蹤等深入子情境仍未實現（見 情境矩陣）已完成
  • ○AI Com Sec 證據層：文件版本／頁碼來源、候選資料→人手核對→verified fact、年度工作實例、遞交證明／支持文件關聯及公司範圍審計帳。現時文件庫及日曆未有這些狀態，因此不會把文件上載或提醒等同完成。計劃中
  • ○受審批的 EDM outbox：系統內視覺預覽、客戶／公司／期間範圍、排程、送達／失敗／回覆紀錄；不自動發送，亦不讓 AI 自行遞交。計劃中
  • ○法定文件 preflight：NAR1 清楚標為草稿（未核對／未簽／未遞交）；ND2A 由申報事項追蹤升級至可核對的官方文件生成，並顯示所用資料來源。計劃中
  • ○由會議 transcript 自動生成 AGM／董事會會議紀錄（重用 Phase 3，硬性依賴、暫時卡住）計劃中
  • ○實際 e-Stamping 政府系統提交（唔淨係計算＋生成文件）— 需要真正嘅政府 API 存取，目前冇渠道計劃中
Phase 8 — Lead generation

重新包裝 Phase 1／3／4 嘅功能，畀 sales／BD 用，需要 Phase 0 嘅 org 模型。

  • ✓咭片 OCR 變 leads、活動 QR code 收集（公開 lead-capture 表格）、warm-intro mapping（同 calendar collaborator 數據比對）、跟進提示（due/overdue 清單）已完成
  • ✓HK／SG 公司註冊查冊：SG（ACRA／data.gov.sg）有真正免費公開 API，已經整合；HK（Companies Registry／ICRIS）冇公開 API，做咗連去官方網站嘅連結已完成
  • ○Meeting→CRM 同步（依賴 Phase 3 transcription，暫時未做）；跟進提示現時淨係 in-app 清單，未有 email 通知計劃中
Phase 9 — AI 保安與法規

刻意 descope — 呢個 phase 淨係一個決策點，唔係工程路線圖。

  • ✓Domain-restricted Google 登入（已經覆蓋咗基本嘅信任訊號）已完成
  • ○淨係決定 partner／resell 方案（例如 Microsoft Purview／Okta），唔會自建 DLP／SSO／audit-log；最多做一個輕量嘅「信任頁」計劃中
而家你可以先免費攞你嘅 Work Recap →