Domain Maps
Domain Maps 是「我要改某個功能」之前的索引。P0 domains 已整理主要責任、資料流、source、tests 與風險；P1 domains 先保留入口。
P0 domains
Points / ledger / watch time
P0 complete| 面向 | 入口 |
|---|---|
| 做什麼 | 把 Twitch viewer activity 轉成可花用 points，維護 watch sessions、points transactions、balances 與 spend/claim 邊界。 |
| 主要資料流 | extension heartbeat → watch service → points service → PostgreSQL ledger / balance。 |
| API handlers | watch_handler.go, points_handler.go, spend_handler.go, internal_points_handler.go |
| Services | watch_service.go, points_service.go, spend_service.go, tachiya_client.go |
| Models | points.go, watch_session.go, watch_stats.go, tachi_balance.go, coupon_redemption.go |
| Tests | watch_service_test.go, points_service_test.go, spend_service_test.go, tachiya_client_test.go |
| Related docs | Watch-to-points design, Sequence diagram, Tokenomics |
踩雷點：
- Ledger 必須能解釋每次加扣點，避免只改 balance 忘記 transaction。
- Coupon redemption 會跨 tachiya / Saleor，扣點與 external redemption id 要避免 double spend。
- 改 migration 時要檢查 backfill、NOT NULL default、rollback 與 deployment order。
Auth / identity
P0 complete| 面向 | 入口 |
|---|---|
| 做什麼 | 管 Twitch / Google / email / SIWE 身份、refresh token、JWT、role / permission 與 protected API。 |
| 主要資料流 | provider credential → auth service → user / auth provider / refresh token → middleware → domain route。 |
| API handlers | auth_handler.go, email_auth_handler.go, user_handler.go, address_handler.go |
| Services | auth_service.go, email_auth_service.go, user_service.go, siwe.go, oauth_token_crypto.go |
| Middleware | auth.go, internal_auth.go, rate_limit.go |
| Models | user.go, auth_provider.go, refresh_token.go, email_auth.go |
| Tests | auth_service_test.go, auth_handler_test.go, auth_test.go, rbac_handler_test.go |
| Related docs | Auth architecture, Backend permissions |
踩雷點：
- Auth 變更通常會影響 extension、dashboard 與 internal handlers，要檢查 token propagation。
- OAuth token / refresh token 不可出現在 log、URL query 或 PR artifacts。
- SIWE / wallet signature 需要驗證 nonce、expiration、chain id 與 signer ownership。
Extension / sidepanel
P0 complete| 面向 | 入口 |
|---|---|
| 做什麼 | Chrome sidepanel / Twitch extension runtime，處理登入、心跳、點數顯示、coupon shop、claim / raffle panels。 |
| 主要資料流 | Twitch context / extension storage → React hooks → API service → tachigo API。 |
| App entry | main.tsx, app/App.tsx, TwitchApp.tsx |
| Hooks | useHeartbeat.ts, useTPoint.ts, useTwitch.ts, useRaffleResult.ts |
| API client | services/api.ts, couponRedeem.ts, extension/storage.ts |
| UI panels | CouponShopPanel.tsx, ClaimPanel.tsx, RaffleResultPanel.tsx |
| Tests | useTPoint.test.tsx, api.test.ts, runtime-config.test.ts, storage.test.ts |
| Related docs | Chrome sidepanel migration, Extension UI prompts |
踩雷點：
- Heartbeat 可能遇到 stale closure、重複送出或 viewer context 尚未 ready。
- Extension runtime config 與 API base URL 不要寫死到 production-only 假設。
- i18n 文字需同步
en、zh-TW、zh-CN，避免 UI key 缺漏。
P1 domains
| Domain | 狀態 | 入口 |
|---|---|---|
| Raffle / airdrop | Coming soon | raffle_service.go, airdrop_service.go |
| Claim / spend / coupon redemption | Coming soon | claim_service.go, spend_service.go |
| Dashboard | Coming soon | apps/dashboard/src/App.tsx, dataProvider.ts |
| Tachiya commerce integration | Coming soon | tachiya_client.go, tachiya |
| AI workflow / PR scope policy | Coming soon | Codex autonomous workflow, PR scope policy |