adventure-table

P0 — 實作規格

Phase：P0 — Character Core + SRD / Rules Foundation
本文件只定義 P0 各 Subphase 完成後什麼必須成立。具體 DB schema、API、檔案結構與程式接線放在同目錄的 開發設計方針.md。

最後更新：2026-08-29

---

1. P0 目標與 Subphase 原則

P0 要建立 Adventure Table 後續角色與規則功能共用的第一層地基：

1. 角色需要的 SRD 5.1 reference content 在系統內可正式使用。
2. Character 核心資料可以被建立、保存、讀回。
3. Digital Character Sheet 可以正確顯示角色。
4. 常用角色衍生數值由 Server 規則層計算。
5. 角色 Build 與 Current State 明確分離。
6. P0 的資料表示能力不能阻止 P1 的完整 Character Builder / Multiclass。

P0 不是完整創角器，也不是多人跑團功能。

P0 固定拆成六個可獨立實作、驗證與 commit 的 Subphases：

P0-A — Project Foundation
↓
P0-B — Character-Relevant SRD Foundation
↓
P0-C — Character Core & Persistence
↓
P0-D — Character Rules & Backend API
↓
P0-E — Character Sheet & State UI
↓
P0-F — Full P0 Integration & Closeout

不得跳過前置 Subphase 直接做後面的功能；每個 Subphase 完成時都必須先達到該節的完成條件，再進下一個。

---

2. P0 最終完成定義

P0-F 關門時，應能做到以下完整流程：

啟動專案
↓
載入並驗證 Character-Relevant SRD 5.1 reference data
↓
載入一名已存在的 Character
↓
Server 計算 Character Sheet 所需衍生數值
↓
Web UI 以三頁 Character Sheet 顯示
↓
修改 Current State（例如 HP / Prepared Spells / Spell Slot 使用狀態 / Condition / Inventory）
↓
保存
↓
重新啟動／重新載入
↓
Character Build 不變，Current State 保持最後保存結果

同時，P0 必須能承載一名合法的高等 Multiclass 角色資料，例如：

Human Fighter 5 / Wizard 5，Character Level 10。

這不代表 P0 要從 UI 一級一級建立這名角色；完整 Builder 與 progression validation 屬 P1。

---

P0-A — Project Foundation

目標

建立後續 P0 能持續實作與驗證的最小可執行 Web 專案地基。

P0-A 完成時至少必須成立：

• React + TypeScript + Vite frontend 可啟動。
• FastAPI backend 可啟動。
• PostgreSQL 可由專案本身連線。
• SQLAlchemy / Alembic baseline 可運作。
• Docker Compose 可啟動 P0 所需服務。
• pytest、Vitest、Playwright 都有可執行的 baseline。
• Backend 有最小 health/readiness 檢查。
• Frontend 能載入最小 app shell，證明前後端開發環境站得起來。

P0-A 不建立 Character、Combat、Room、Adventure、AI Runtime 等功能。

完成條件

• fresh checkout 依專案說明可啟動 frontend、backend、database。
• Alembic baseline migration 可執行。
• backend health check 成功。
• pytest / Vitest / Playwright baseline 都能跑且全綠。
• 沒有為 P0-B 以後建立未使用的大型 domain module。

---

P0-B — Character-Relevant SRD Foundation

目標

建立正式可用的 SRD content framework，並只導入 P0 / P1 角色系統真正需要的 SRD 5.1 structured reference content。

至少涵蓋：

• Race / racial traits
• Class
• SRD Subclass
• Background
• Features / Traits
• Feats（SRD 5.1 有提供者）
• Ability / Skill / Saving Throw reference
• Equipment
• Weapons
• Armor
• Adventuring Gear / Items
• Spells
• Conditions
• Damage Types
• Languages
• 角色規則需要的其他 reusable structured constants / references

要求：

• Reference entry 必須有穩定識別方式，角色不能靠顯示名稱硬連結資料。
• Reference data 要能通過 schema validation。
• Reference 之間的必要引用要能被驗證。
• 保留資料來源／ruleset / licensing 所需資訊。
• Mandatory schema / reference 錯誤必須 fail-fast，不得靜默略過。
• SRD definition 存在，不代表對應 gameplay mechanics 都要在 P0 自動化。

例如：Fireball 的 spell definition 可在 P0 存在；Tactical AoE 是 P5。

Monster / Beast 明確延後

P0-B 不導入：

• Monster stat blocks
• Beast stat blocks
• Monster Actions / Traits
• Monster-specific spellcasting representation
• CR / XP encounter-oriented data normalization
• Combat-only Monster schema / validation

這不是遺漏，而是刻意的 scope cut。P0～P3 沒有需要完整怪物戰鬥資料的驗收；以上資料明確延後到：

P4-A — Quick Combat 的第一個 Subphase

P4-A 開工時再依當時 Combat 需求設計具體 Monster Template schema / API；P0 不提前設計。

完成條件

• 所有 P0 定義的 character-relevant category 可完整載入。
• stable key 唯一且可解析。
• required cross-reference validation 全綠。
• duplicate key / missing field / dangling reference / malformed enum 等負向案例會明確失敗。
• Race / Class / Spell / Equipment / Condition 等 P0 會用的 entry 可由 stable key 查得。
• P0 repository 中不需要為 Monster / Beast 建正式資料檔或 schema 才能通過本階段驗收。

---

P0-C — Character Core & Persistence

目標

建立 Character 的正式資料模型與 persistence，使複雜角色可以在沒有 Builder、Rules UI、Room 或 Combat 的情況下可靠保存與讀回。

Character Core

Character 至少要能表示：

• Identity：名稱與基本角色識別資訊。
• Ruleset / content references。
• Race。
• Character Level。
• 一個或多個 Class 與各自 Class Level。
• Class level acquisition order。
• Subclass（存在時）。
• Ability Scores。
• Proficiencies。
• Saving Throw proficiencies。
• Skills。
• Features / Traits。
• Feats。
• Spell-related Build data。
• Starting Equipment 的 Build 選擇／初始化資料。
• Current Inventory state。
• Optional Roleplay / Biography data。
• Numeric Override 所需資料表示能力。

P0 不要求完整檢查「玩家是否依合法創角流程選到這些資料」，但資料本身必須可被 schema / reference validation 正確讀取。

Character Version = Build Version

P0 必須分開：

• Character identity
• immutable Character Build Version
• mutable Current State

Character Version 就是不可變的 Build Version，不包含 live Current State。

舊 Build Version 一旦建立不可原地修改。P0 只需要正式支援 version 1 與目前版本指標；Level Up Draft / Validate / Confirm 與 Version History UI 屬 P1。

Build 與 Current State 分離

Build 包含：

• Race / Class / Subclass
• Level progression
• Ability Scores
• Proficiencies
• Features / Feats
• Spell access / Spellbook / Known Spells / Always-prepared / Granted access
• Hit Dice 總數與骰型
• Max HP 所需的 level-by-level HP progression data
• Starting Equipment 的選擇／初始化資料
• 長期角色設定與 Numeric Override

Current State 包含：

• Current HP
• Temporary HP
• Conditions / temporary effects
• Prepared Spells
• 已使用／剩餘的 Spell Slot 等消耗型資源
• Available Hit Dice
• 整份目前 Inventory：item reference、quantity、equipped / carried 等 live state
• 其他 session 間必須延續的角色目前狀態

Prepared Spells 是可反覆變動的選擇，不得因為重新準備法術就建立新的 Build Version。

Inventory 的目前內容也不屬於 Build。角色撿到、丟掉、使用、裝備或卸下 Item，都只改 Current State；Build 中的 Starting Equipment 只用來產生角色最初的 Inventory，不是之後持續重算 Inventory 的來源。

Ability Score 表示

Ability Scores 表示角色永久 Build 選擇全部解析後、但尚未套用 Numeric Override 的 Build Score。

Human racial increase、ASI、Feat 等永久 Build 效果若已屬於該 Build，必須已反映在保存的 Ability Score 中；之後 Rules Engine 不得再因 race reference 重複套同一加成。

Spell Access

Build 的 spell access 與 Current State Prepared selection 必須分開。

Build access 至少能區分：

• Known
• Spellbook
• Always Prepared
• Granted

Prepared 不得作為 Build access type。

Wizard Spellbook 屬 Build；Wizard 目前準備哪些法術屬 Current State。

HP Progression

Build 必須保留每個 Character Level 實際採用的 base HP gain，順序能與 class progression 對齊。

P0 fixture 使用 fixed value 只是測試基準，不代表全產品永遠只支援 fixed HP；P1 若支援 rolled HP，只需保存該級實際採用的 base HP gain。

Hit Dice

• Hit Dice 總數與骰型屬 Build / 可由 class progression derive。
• Available Hit Dice 屬 Current State。
• Multiclass 必須保留不同骰型，不得合成一個模糊 total。

Character Persistence

P0-C 必須支援：

• Character 保存。
• Character 重新讀取。
• Build 與 Current State 分別保存。
• Build Version immutable。
• Server / application session 重建後資料仍存在。
• 同一角色 Save → Reload 後沒有未預期資料遺失。
• Starting Equipment 初始化後，不會在 Reload 時重新覆寫 live Inventory。

標準 Fixture

P0-C 建立固定驗證角色：

Human Fighter 5 / Wizard 5，Character Level 10

至少包含：

• Resolved Build Ability Scores：STR 16 / DEX 14 / CON 14 / INT 16 / WIS 10 / CHA 8；Human racial increase 已包含。
• Fighter → Wizard 的 class acquisition order。
• HP progression：10, 6, 6, 6, 6, 4, 4, 4, 4, 4。
• Fighter / Wizard feature references。
• Wizard Spellbook access entries 放 Build。
• Wizard Prepared entries 放 Current State。
• Spell Slot current state。
• Hit Dice total：5d10 + 5d6；initial available：5d10 + 5d6。
• Build starting equipment 初始化資料。
• Live Inventory：至少 Chain Mail、Shield、Longsword、Healing Potion ×2。
• Current HP / Temp HP / Condition baseline。

標準 fixture 保持無 Numeric Override。

完成條件

• fixture 可以 seed、Save、Reload。
• Character Level 10、Fighter 5 / Wizard 5 與 class order 都能保留。
• Build / State 有明確不同的 persisted representation。
• 修改 HP、Prepared、Condition、resource、Available Hit Dice、live Inventory 不會建立新 Build Version。
• Build payload 在純 State mutation 前後保持不變。
• Starting Equipment reload regression 通過。
• Optional Roleplay 全空仍是合法角色。

---

P0-D — Character Rules & Backend API

目標

在 P0-C 的正式 Character model 上建立 Server authoritative rules calculation、CharacterSheetDTO 與 P0 所需 backend API。

Character Derived Calculations

Server 規則層至少提供：

• Ability Modifier
• Total Character Level
• Per-class Level
• Proficiency Bonus
• Skill Modifier
• Saving Throw Modifier
• Passive Perception
• Armor Class
• Initiative Modifier
• Spell Save DC
• Spell Attack Modifier
• Max HP
• Hit Dice total / available 的 sheet representation

規則計算至少遵守：

Build Ability Score
↓
Apply Ability Numeric Override（若有）
↓
Effective Ability Score
↓
Ability / Skill / Save / Spell / HP calculation
↓
Apply remaining Numeric Overrides
↓
CharacterSheetDTO

• AC 必須讀取 Current State 中目前 equipped Armor / Shield，再套 AC override。
• Max HP 使用 Build hp_progression + effective CON modifier，再套 Max HP override。
• 目前有效的 CON modifier 應套用所有 Character Levels。
• Hit Dice total 由 Build derive；available 由 State 取得。
• Prepared 狀態由 State 取得，不把 Spellbook 自動當成 prepared。
• Numeric Override 只改指定數值，不代表合法性／結構規則被繞過。

API 能力

P0 至少提供：

• Reference Content query。
• Character read。
• Character Sheet read model。
• Current State mutation。

State mutation 至少能承載：

• Current HP
• Temporary HP
• Prepared Spells
• Conditions
• Spell / class resource usage
• Available Hit Dice
• live Inventory add / remove / quantity / equipped state

P0 不提供 production Character Builder workflow；fixture 可由 developer seed command 建立。

Numeric Override Variant

由標準 fixture 建立固定 test variant：

ability:strength = 18
ac = 19
max_hp = 80

至少預期：

• Effective STR = 18，STR modifier = +4。
• Athletics = +8。
• STR Save = +8。
• AC = 19。
• Max HP = 80。
• Race / Class / Feature / Spell access / Starting Equipment 等結構資料不因 override 改變。

P0 Multiclass Spellcasting 邊界

Fighter（非 Eldritch Knight）5 / Wizard 5 的 spell slot progression 等同 Wizard 5，不會觸發多個 caster class 的 caster-level aggregation。

因此 P0 fixture 只證明：

• Multiclass data 可表示。
• Class order 可保留。
• Spell source / access / prepared state 可分離。

完整 multiclass caster-level / combined spell-slot progression validation 屬 P1。

完成條件

標準 fixture 至少算出：

項目	預期
Total Character Level	10
Fighter Level	5
Wizard Level	5
Proficiency Bonus	+4
STR Save	+7
CON Save	+6
Athletics	+7
Arcana	+7
Perception	+4
Passive Perception	14
AC（Chain Mail + Shield）	18
Wizard Spell Save DC	15
Wizard Spell Attack	+7
Max HP	74

另外：

• unequip Shield 後 calculated AC = 16，Build 不變。
• effective CON modifier +3、無 Max HP override 時 Max HP = 84，證明 74 不是 hardcode。
• Numeric Override variant 固定 expectation 全通過。
• State PATCH 成功後重新 GET Sheet 反映 Server authoritative result。
• Invalid state request 必須原子失敗，不留下半套更新。

---

P0-E — Character Sheet & State UI

目標

讓使用者在瀏覽器中真正查看已存在角色，並操作 P0 需要的 Current State；P0-E 不是 Character Builder。

Digital Character Sheet

Character Sheet 第一版固定三頁。

Header — 三頁都顯示

• Name
• Level
• HP
• AC
• Conditions

Page 1 — Attributes / Skills

至少顯示：

• Ability Scores / Modifiers
• Skills
• Saving Throws
• Passive Perception
• Hit Dice：Available / Total，multiclass 依骰型分列
• Features / Traits
• Conditions / temporary effects
• Optional Roleplay / Biography 區域（可收合）

Roleplay / Biography 可包含：Alignment、Personality、Ideal、Bond、Flaw、Biography、Goals、Relationships、Roleplay Guidance；全部 optional，不得因空白阻止角色存在或顯示。

Page 2 — Spells

至少顯示：

• Spell references
• Source class / source feature
• Known / Spellbook / Always-prepared 等 Build access 區別
• Prepared / Unprepared Current State
• Spellcasting ability
• Spell Save DC / Spell Attack
• Spell Slot / resource current state

P0 的重點是正確表示與顯示；完整合法選法與升級流程屬 P1。

Page 3 — Inventory

至少顯示 Current State 中的：

• Item / Equipment reference
• Quantity
• Equipped / carried 等 P0 需要的基本狀態
• Weapon / Armor 主要可讀規則資訊
• Consumable 當前數量

Inventory 必須能在不修改 Build 的情況下新增、移除與改變 live state。

Current State UI

P0-E 至少要能從 UI 操作或完成對應 persistence 流程：

• Current HP
• Temporary HP
• Conditions
• Spell Slot / resource state
• Available Hit Dice
• Inventory quantity
• Inventory equipped state
• Inventory add / remove entry（可採最小可測介面，不必做 Loot 系統）

Prepared Spells 的 model、API persistence 與 Sheet display 必須正確；P0 不要求完整 Prepare-Spells Wizard。

P0 也不要求完整 Short Rest Spend-Hit-Die workflow。

Server Authoritative

Frontend 不自行重算正式 D&D derived state。

Mutation flow 必須是：

UI action
↓
Server validate + persist
↓
Server 回傳／重新取得 authoritative state
↓
UI 更新

不得依賴只存在 browser memory 的正式角色狀態。

完成條件

• /characters/:characterId 可直接開啟 P0 fixture。
• 三頁與固定 Header 可操作。
• Page 1 清楚顯示 d10 5/5 與 d6 5/5。
• Page 2 可區分 Spellbook / Prepared。
• Page 3 顯示 live Inventory，不從 Starting Equipment 重建。
• HP / Temp HP / Condition / resource / Hit Dice / Inventory 等 P0 State mutation 在 reload 後保持。
• Roleplay 全空不造成必填阻擋。
• 不依賴 Room / Campaign / Session / Combat / AI 才能使用 Character Sheet。

---

P0-F — Full P0 Integration & Closeout

目標

P0-F 不新增新的大型產品功能；它負責把 P0-A～P0-E 串成可重現、可回歸、可人工操作的完整 P0，並證明以下 Acceptance Contracts 全部成立。

AC-P0-01 — SRD 資料可完整載入

啟動時所有 P0 定義的 character-relevant SRD 5.1 類別可被載入；schema / required reference 錯誤必須明確失敗，不得靜默略過。

Monster / Beast 不屬於 AC-P0-01，已延後 P4-A。

AC-P0-02 — Reference 查詢

後端可依穩定 key 取得指定 Race / Class / Spell / Equipment / Condition 等 P0 reference entry。

AC-P0-03 — Character Save / Reload

建立／載入一名 P0 fixture Character，保存後重新讀取，Build 與 Current State 資料一致。

AC-P0-04 — Build / State 隔離

修改 Current HP、Temporary HP、Prepared Spells、Condition、Spell Slot 使用狀態、Available Hit Dice，或對 live Inventory 新增／移除／改 quantity／改 equipped 狀態時，不會改變 Race / Class / Ability / Feature / Spell access / Spellbook / Starting Equipment 等 Build 資料，也不會產生新的 Build Version。

AC-P0-05 — Derived Calculation

標準 fixture 的 Ability Modifier、Proficiency Bonus、Skill、Save、Passive Perception、AC、Spell Save DC / Spell Attack、Max HP 等結果符合 D&D 5e 2014 規則；另以固定 Numeric Override variant 驗證 override 後的 authoritative derived result。

AC-P0-06 — 三頁 Character Sheet

Web UI 能顯示固定 Header 與三頁：Attributes / Skills、Spells、Inventory；Page 1 能依骰型顯示 Hit Dice Available / Total；optional Roleplay 空白時仍可正常使用。

AC-P0-07 — Current State Persistence

修改 HP / Prepared Spells / resource / Hit Dice / condition / inventory 後重新載入頁面與重啟 server，狀態保持一致，Build Version 不變。

AC-P0-08 — Multiclass 承載能力

系統可載入並正確顯示一名 Human Fighter 5 / Wizard 5（Character Level 10）fixture；能分辨 total level、各 class level、class order、不同來源的 features / spells，以及 5d10 + 5d6 的 Hit Dice 結構。

本契約不代表 P0 已驗證 multiclass caster-level / combined spell-slot progression。

AC-P0-09 — 前端不自行產生 authoritative derived state

Character Sheet 使用 Server 回傳的 authoritative Character Sheet / derived data；重新整理後結果一致，不依賴只存在 browser memory 的正式角色狀態。

AC-P0-10 — P0 Scope Guard

P0 可以在沒有 Room、Campaign、Session、AI、Combat、Adventure 的情況下獨立啟動與驗收。

P0-F 關門條件

只有以下全部成立才可進 P1：

• P0-A～P0-E 各自的完成條件已通過。
• Character-Relevant SRD content validation 全綠。
• backend rules / persistence / API tests 全綠。
• frontend tests 全綠。
• Playwright P0 核心流程全綠。
• Fighter 5 / Wizard 5 fixture 可穩定 Save / Reload / display。
• Prepared Spells、Hit Dice available 與 live Inventory 的 Current State persistence 已驗證。
• Starting Equipment reload regression 已驗證。
• 標準 fixture與 Numeric Override variant 的固定 derived expectations 全通過。
• Server restart / fresh application session persistence 已驗證。
• 三頁 Character Sheet 人工 smoke test 通過。
• Monster / Beast data 沒有被重新偷偷拉回 P0 scope；P4-A 承接註記仍存在。
• 沒有為 P1 以後功能提前建立未使用的大型 subsystem。

P0 收尾後，再以實際完成的 codebase 為基礎規劃 P1 與 P1-A～P1-x。

---

3. P1 相容要求

P0 不可以採用會立即阻止以下能力的表示方式：

• Multiclass。
• Character Level 與 Class Level 分離。
• Class acquisition order。
• Starting class 與後續 multiclass 的差異。
• Subclass progression。
• ASI / Feat progression。
• Spell 來源追蹤。
• Spell Access 與 Spell Resource 分離。
• Wizard Spellbook 與 Prepared Spell State 分離。
• Known / Spellbook / Always-prepared 等 Build access 與 Prepared Current State 分離。
• Starting Equipment Build choice 與 live Inventory Current State 分離。
• Level-by-level HP gain 可被保存，未來能承載 fixed / rolled HP。
• Character Build versioning / Level Up。

這些只要求相容，不要求 P0 提前做完整 P1 Builder。

---

4. 明確不屬於 P0

以下不在 P0 實作：

• Monster / Beast stat blocks、Monster Actions / Traits 與 combat-only Monster content；延後 P4-A。
• 完整 Character Builder wizard。
• 從 Level 1 逐級合法選擇到高等角色。
• Level Up workflow。
• 完整 Multiclass prerequisite validation UI。
• Multiclass caster-level / spell-slot progression validation。
• P1 的 Character Version History UI。
• Room / Campaign / Session / Seat。
• Human / AI controller handoff。
• MCP Join / AI gameplay tools。
• Roll system。
• Exploration。
• Quick Combat。
• Tactical Combat / Map。
• Adventure Importer / AI DM Runtime。
• Snapshot / Restore / Export。
• Shop / Loot / Quest / Rest workflow。

若 P0 實作為了這些後續功能加入大量提前設計，視為 scope creep。

This site is open source. Improve this page.