adventure-table

Adventure Table — 技術棧討論

本文件只用來討論 Adventure Table 的基礎技術棧，不是全專案架構規格，也不是任何 Phase 的實作設計。

討論完成後，正式採用的基礎技術選型會寫入對應的 開發設計方針.md；各 Phase 的資料模型、API、權限、事件、Snapshot、Combat、Tactical 等實作細節，等該 Phase 開工時再設計。

若本文件與 規格企劃.md 衝突，以產品規格為準。

最後更新：2026-08-29

---

一、目前要決定的範圍

現在只先決定：

• 前端主要語言與框架。
• 後端主要語言與框架。
• 主要資料庫。
• AI 接入的基本技術方向。
• 基本測試工具。
• 第一版部署大方向。

現在不提前決定：

• Character / Campaign / Combat 的 DB schema。
• Entity ID 策略。
• CharacterVersion / Snapshot / GameTransaction 的具體資料結構。
• Room / DM / Owner / AI Token schema。
• WebSocket event schema。
• Tactical renderer。
• 各 Phase 的 module / service / API 拆法。

這些會在對應 Phase 的 開發設計方針.md 再決定。

---

二、目前推薦技術棧

領域	目前推薦	備註
Frontend	React + TypeScript + Vite	高互動 SPA；不需要 SEO / SSR
Routing	React Router 或同級方案	實作時再定
UI Styling	Tailwind CSS	可替換
Server State	TanStack Query	可替換
Local UI State	React state / context；必要時 Zustand	Zustand 非必需
Backend	Python + FastAPI	適合規則邏輯、API、WebSocket
Validation	Pydantic	適合 structured rules / action / content data
Database	PostgreSQL	關聯資料與 transaction 需求明顯
ORM	SQLAlchemy	可替換，但目前優先
Migration	Alembic	與 SQLAlchemy 搭配
AI Integration	MCP Python SDK	外部 AI 透過 MCP / Site Tools 接入；網站本身不接 LLM API
Python Tests	pytest	Rules / backend 主測試工具
Frontend Tests	Vitest	Component / utility
E2E	Playwright	真實 UI workflow
Deployment	Docker Compose	第一版朋友私用，避免過度架構

版本號不在本文件鎖死；真正開工時使用當下受支援的 stable / LTS line。

---

三、為什麼 Frontend 選 React + TypeScript + Vite

Adventure Table 是高度互動的 Web Application，主要畫面會包含：

• Character Sheet / Builder
• Inventory / Spell UI
• Room / Session UI
• Exploration / Chat
• Quick Combat
• 後續 Tactical Combat

React 適合大量重複、互動式 UI component；TypeScript 可以降低欄位與 API contract 的錯誤。

目前選 Vite 而不是 Next.js，主要因為：

• 沒有 SEO 需求。
• 產品主要是登入後的 client-heavy application。
• 真正 backend 會由 FastAPI 負責。
• 不需要為了 SSR / Server Components 多維護一個 Node server runtime。
• build 後可直接以靜態檔部署。

如果之後真的出現 Next.js 才能明顯解決的需求，再重新評估即可。

---

四、為什麼 Backend 選 Python + FastAPI + Pydantic

P0 / P1 會有大量 D&D 5e 規則與結構驗證，例如：

• Ability / Skill / Save 計算。
• Class / Multiclass progression。
• Spell access / resource。
• Numeric Override vs Structural Validation。
• SRD reference data validation。

Python 可讀性高、測試方便，也符合現有技能。

FastAPI 提供：

• HTTP API。
• OpenAPI。
• WebSocket。
• Request / Response validation integration。

Pydantic 則適合大量結構化資料驗證。

MCP 並不是 Python 獨有優勢；選 Python 的主要原因仍是 Rules / validation / data processing 與維護性。

---

五、為什麼 Database 選 PostgreSQL

Adventure Table 後續會有大量彼此有關聯的持久資料，例如 Character、Campaign、Session、Seat、Combat、Timeline 等。

需要的能力包括：

• Transaction。
• Referential integrity。
• Migration。
• 長期 persistence。
• 必要時使用 JSONB 保留部分彈性。

因此目前 PostgreSQL 比 MongoDB 更適合作為主要 DB。

實際 table、JSONB 邊界、ID strategy 等全部留到各 Phase 的開發設計再決定。

---

六、AI Integration 基本方向

產品規格已確定：

• 網站本身不接 LLM API。
• AI 由使用者自己的外部 AI Session 提供。
• AI 經 MCP / Site Tools 正式加入桌內。
• Human UI 與 AI Tool 必須使用同一套 backend game logic。

因此目前只先選擇 MCP Python SDK 作為 AI adapter 的候選實作工具。

MCP Tool 的具體拆法、Join Token、Seat scope、reconnect、visibility 等，等 P2 / P3 開發設計時再定。

---

七、目前保留的全域工程原則

這些不是某個 library choice，而是產品規格直接要求的開發原則：

1. Server 是唯一 Game State truth。
2. Human UI 與 AI Tool 共用同一套 backend game logic。
3. 秘密由 Server 隔離，不靠 UI 隱藏或 Prompt 約束。
4. Frontend 不單獨持有正式 Game State。
5. 第一版優先 Modular Monolith，不主動拆 Microservices。
6. 不要因為未來可能需要，就提前建立 Redis / Kafka / Kubernetes 等基礎設施。

至於這些原則在某個 Phase 具體怎麼落地，由該 Phase 的 開發設計方針.md 決定。

---

八、現在刻意延後的選擇

以下沒有必要在 P0 前決定：

• Tactical Map 使用 PixiJS、Konva、Canvas 或其他方案：P5 再選。
• Redis / NATS / RabbitMQ：真的遇到需求再評估。
• S3-compatible object storage：有部署需求再選。
• 搜尋 / Vector DB：有明確 retrieval 問題再評估。
• Microservices：第一版不做。

---

九、目前結論

如果現在開始 P0，基礎開發環境暫定：

Frontend
React + TypeScript + Vite

Backend
Python + FastAPI + Pydantic

Database
PostgreSQL + SQLAlchemy + Alembic

AI
MCP Python SDK
External AI only

Testing
pytest + Vitest + Playwright

Deployment
Docker Compose

這份文件到這裡就足夠。

下一步不是繼續設計全專案架構，而是進入 P0 的實作規格與開發設計。

This site is open source. Improve this page.