adventure-table

P1 — 測試指南

Phase：P1 — Character Builder Complete
本文件定義 P1 各 Subphase 如何驗收。P1-H 必須最終證明 實作規格.md 的 AC-P1-01 ～ AC-P1-12，而不是只證明「Wizard 可以按下一步」。

最後更新：2026-08-29

1. 測試原則

P1 的測試證據分為：

Builder Domain / Choice Resolver Unit Tests
D&D Progression / Structural Validation Tests
Draft Persistence / Repository Tests
Character Version / State Reconciliation Tests
API Tests
Frontend Vitest
Playwright Real-backend E2E
Migration / P0 Regression
P1-H Full Regression / Manual Smoke

每個 Subphase 必須先通過自己的測試再進下一個；不要把 P1-A～G 的驗證全部拖到 P1-H。

所有 Builder fixture 必須 deterministic、可程式建立，不依賴人工先在 UI 建角色。

測試必須分清：

Draft legality
Build compile result
Current State seed / reconciliation
Character Sheet derived result

不能只 assert HTTP 200 或 can_confirm=true。

三份 P1 文件的 Subphase 標題必須完全一致。

P1-A — Builder Domain & Draft Foundation

對應主要契約：AC-P1-01、AC-P1-11、AC-P1-12 的基礎。

Draft Schema / Partial State

至少測：

Create Draft 可以只有最小 identity / target level 等 partial input。
缺 Race / Class / Ability 等時 Draft 本身仍可 Save。
同一 Draft進行 full validation 時回 blocking_error，而不是 Pydantic parse整份 Draft失敗。
Draft payload extra / malformed field依正式 schema被拒絕。
Draft mode / source character / base version組合非法時被拒絕。

Draft Persistence

流程：

Create Draft
↓
PATCH partial choices
↓
close DB / app session
↓
GET Draft

預期：

input完整保留。
deterministic choice selections仍能對應。
validation可以重新計算。
沒有建立 characters / character_versions / character_states rows。

Cancel

Create Draft
↓
Save
↓
Cancel / DELETE

預期：

Draft不存在或標為不可繼續。
正式 Character tables沒有任何新角色。
P0 fixture不受影響。

Validation Result

至少有固定案例分別產生：

blocking_error
warning
non_standard

每筆 issue assertion：

machine-readable code。
severity。
path / choice id。
can_confirm 正確。

Choice ID Stability

同一 Draft / same source：

GET
reload server-side view
GET again

Choice ID必須一致。

修改不相關欄位（例如 Character name）也不能導致所有 choice ids重生。

Draft Revision（若實作）

若採 optimistic revision：

revision 7 PATCH成功 → 8。
另一個仍帶 expected 7 的 PATCH → machine-readable stale revision error。
不允許舊 payload覆蓋新 Draft。

P0 Regression

P1-A 每次 CI 至少重跑：

P0 Character schema tests。
P0 persistence tests。
P0 Character API / Sheet tests。
P0 State mutation tests。

P1-A 關門

incomplete Draft可 save/reload/cancel。
validation DTO穩定。
choice ids穩定。
Draft不污染正式 Character。
P0 regression全綠。

P1-B — Character Creation Basics

對應主要契約：AC-P1-02、AC-P1-11。

Character Workshop API / UI

至少驗：

Existing P0 fixture出現在 Character list。
Create Character建立 Draft，不立即建立 Character。
Resume Draft可以重新進 Builder。
Open existing Character仍進 P0 Character Sheet。

Race / Subrace

針對 SRD content fixture至少驗：

valid race可選。
valid subrace只可掛在正確 race。
mismatched race/subrace → blocking error。
race grants / traits / choices在 Builder summary可見。
Compile後 Race permanent effects只反映一次。

Background

Production SRD 5.1 目前只有 Acolyte，因此測試必須把『內容只有一筆』和『Builder 機制只能處理一筆』分開。

至少：

production Acolyte valid background ref可 resolve。
mechanical grants / proficiencies可進 Draft summary。
optional roleplay空白不阻塞。
invalid background key → machine-readable invalid choice / reference error。
使用 test-only normalized Background fixtures 補足多筆 selector、choose N、language / tool / proficiency choices 與 invalid option cases；test fixture 不寫回 data/srd5.1/ production content。

Standard Array

測試：

合法 assignment通過。
同一 array value被超額使用 / assignment數量錯誤 → fail。
六個 ability都完成才不再有 missing ability blocking issue。
Race permanent effect套用後 resolved Build Scores符合 expected fixture。

具體 Standard Array數字以 P1 rules data / test fixture為準，不在本指南複製規則表。

Point Buy

至少：

合法 budget example通過。
超出 budget → fail。
單項低於 / 高於 normal point-buy範圍 → fail。
frontend即使手動改 request也不能繞過 backend validation。
Compile後 race grants只套一次。

Manual Input

至少：

合法的實體骰結果輸入可通過。
normal generation以外的輸入不應被靜默當標準合法 Build；依實作應產 blocking / non-standard route。
Numeric Override是獨立資料，不因 method=manual自動建立 override。

Ability Source Ordering

固定 fixture驗：

base generation
+ race/subrace permanent grants
= resolved Build score

P1-D後再增加 ASI / Feat。

Character Sheet重新計算時不再加 race grant第二次。

Starting Skills / Proficiencies

至少測：

choose N數量正確。
少選 → blocking。
多選 → blocking。
option不在合法集合 → blocking。
duplicate selection → blocking或由規則允許的 replacement flow處理。

Vitest

至少覆蓋：

Character Workshop list / Create entry。
Wizard step navigation。
Searchable Race / Background / Skill combobox keyboard操作。
disabled option reason可見。
Summary會跟 server response更新。

Playwright

Real backend：

/characters
→ Create Character
→ 填 Name / Target Level
→ Race / Background
→ Ability method
→ Save
→ browser reload

reload後所有輸入與已選 reference保留。

P1-B 關門

三種 Ability method backend+UI全綠。
Race/Subrace/Background/starting choices可保存。
searchable selector可鍵盤操作。
尚未選 Class時 Draft full validation 產 blocking_error 且 can_confirm=false；P1-B 不依賴 P1-F Confirm endpoint。

P1-C — Class Progression & Multiclass

對應主要契約：AC-P1-03、AC-P1-04。

Ordered Progression

建立 deterministic scenarios：

Fighter 1→5
Fighter 1→5 → Wizard 1→5
Wizard 1 → Fighter 1 → Wizard 2...

每個 scenario assert：

total Character Level。
per-class Level。
starting class。
exact acquisition order。
compiled class_progression[]。

Direct High-level Create

UI直接 Target Level 10仍必須有 10 個 progression nodes。

禁止只送：

fighter=5, wizard=5

卻無法知道順序。

Starting Class Grants

至少以兩個不同 class順序驗：

Fighter → Wizard
Wizard → Fighter

預期 starting saves / proficiencies等依 Lv1 class不同；後加入 class只取得 multiclass grants。

Multiclass Prerequisite

至少：

legal ability prerequisite → Add Class可用。
target class prerequisite不足 → disabled + backend blocking。
existing class prerequisite不滿足的負向案例（依 2014 multiclass rules / data）→ backend blocking。
Numeric Override若使有效 ability合法，P1-D整合後可通過。

Subclass Timing

每個代表 class至少測：

timing前沒有強制 subclass。
required timing到達未選 → blocking。
timing到達合法 subclass → pass。
提前注入 subclass → fail。
subclass不屬於該 class → fail。

Automatic Features

到達 level後：

expected automatic feature refs出現在 compiled Build。
未到 level的 feature不出現。
修改 earlier class progression後 stale feature不殘留。

HP — First Character Level

驗：

Lv1 starting class使用first-level HP rule。
Lv1不能選 fixed average / manual rolled代替規則要求的 first-level base。

HP — Later Levels

至少：

fixed average合法並保存實際 base gain。
manual rolled合法並保存輸入結果。
非法 die/result range → fail。
Multiclass新職業的第一個 class level若是 Character Lv6，不得拿 first-character-level max。

HP Alignment

len(hp_progression) == len(class_progression) == character_level。

修改中間 level後 compile / reload仍保持1:1。

Downstream Invalidation

流程：

建合法 Lv10 Draft
↓
修改 Lv3 class

預期：

後續仍合法 selections保留。
不合法 subclass/features/selections變 blocking needs-review。
不會 server crash或靜默換成別的選擇。

Playwright

至少一條：

Create target Lv10
→ level rail逐級選 Fighter 5 / Wizard 5
→ 選 subclass
→ 設 HP methods
→ reload

assert rail順序與已填資料保留。

P1-C 關門

Lv1～Lv20 ordered progression unit tests全綠。
multiclass prerequisite正反向全綠。
starting-class grants / subclass timing / HP progression全綠。
P0 Fighter5/Wizard5 shape可由 engine重建。

P1-D — ASI, Feat & Structural Choices

對應主要契約：AC-P1-05。

ASI Timing by Class Level

建立 multiclass scenario，讓 total level與某 class ASI timing不同。

assert：

total Character Level本身不產生 ASI。
只有對應 class level progression node出現 ASI / Feat choice。

ASI Cumulative Data Trap

直接使用 production levels.json 的 Fighter level rows 驗 cumulative semantics：

Fighter Lv4: cumulative 1, previous 0 → delta 1 → 1 個 ASI/Feat node
Fighter Lv5: cumulative 1, previous 1 → delta 0 → 0 個 node
Fighter Lv6: cumulative 2, previous 1 → delta 1 → 1 個 ASI/Feat node

必測負向：

若 adapter 把 ability_score_bonuses > 0 當本級 occurrence，Lv5 測試必須失敗。
對全部 SRD class levels parameterized 驗 delta >= 0。
本級 node 數必須等於 delta，不是只驗 boolean。
Multiclass scenario 的 previous value 取同一 class 前一個 Class Level，不取前一個 Character Level。

ASI Structural Validation

至少測：

合法單一 ability increase form。
合法分配 form。
少選 / 多選 → fail。
超過 normal ability cap → fail或依規則資料處理。
同一 progression node重複領 ASI → fail。

Feat

以 SRD可用 Feat fixture：

prerequisite滿足 → selectable。
prerequisite不足 → disabled / blocking。
unknown feat ref → fail。
Feat不是該 ASI node的合法 branch時 → fail。

Numeric Override + Prerequisite

固定案例：

calculated ability不足 prerequisite
→ feat fail

加入合法 Numeric Override使 effective ability達標
→ feat pass

另驗：

Numeric Override
→ 不能讓 Lv1 Fighter提早選 Lv3 subclass
→ 不能創造額外 ASI occurrence
→ 不能把 choose 2改成 choose 3

Generic Choice Resolver

對目前 SRD實際存在的 choice shapes做 parameterized tests：

reference option。
choose N。
nested choice。
category-filtered choice。
feature option。

測試應由 representative content entries驅動，不只手刻 dummy object。

Selection Trace / Provenance（若實作）

若 Build新增 builder trace：

Compile後 trace與resolved Build一致。
reload後可用 trace重建 Draft。
修改 trace raw payload不能繞過 compiler validation。
trace不作第二套 rules truth。

UI / E2E

至少一條高等 Fighter：

progress to ASI level
→ 選 ASI
→ Summary能力更新
→ 改成 Feat
→ prerequisite提示
→ Review未來可讀

P1-D 關門

ASI timing/count/cap全綠。
Feat prerequisite正反向全綠。
Numeric Override與structural rule邊界全綠。
generic structural choices不需要每個 class一套 hardcoded form。

P1-E — Spellcasting Progression

對應主要契約：AC-P1-06、AC-P1-10 的 spell state部分。

Representative Spell Fixtures

至少建立：

Wizard — Spellbook + Prepared。
Prepared caster — Cleric或Druid。
Known caster — Sorcerer / Bard / Ranger代表。
Two-source multiclass caster — 驗 combined slots。
Wizard / Warlock或其他含 Warlock組合 — 驗 Pact Magic分池。

Wizard Spellbook

至少：

合法初始 spellbook count / levels通過。
多選 / 少選 required spellbook choices → fail。
不在 Wizard spell eligibility的 spell → fail。
spell level超過當下可取得 → fail。
Compile產 spellbook Build access。

Wizard Prepared

initial prepared selection進 Current State seed。
Prepared不建立 access_type="prepared"。
prepared超 limit → fail。
prepared不在 spellbook / legal source → fail。
少於 limit允許。

Prepared Caster

驗：

legal class-list spell + legal level可 prepared。
illegal class spell → fail。 -超 prepared limit → fail。
Prepared list變更只影響 Current State seed / state，不改 Build access truth。

若 P1-E調整 Prepared schema，必須加入 P0 Wizard fixture compatibility test。

Known Caster

known count依 progression。
known spell level eligibility。
level up replacement合法 remove/add。
replacement不會修改舊 Build Version。

Always Prepared / Granted

至少一個 subclass / feature來源：

entry存在 Build。
source identity正確。
不需放進 daily prepared selection才有效。
counts-against-limit語意依 rules data正確。

Same Spell Different Source

建立同一 spell由兩個 source取得的 scenario：

Build entry ids不 collision。
spellcasting ability / source profile可區分。
Character Sheet / Builder Summary不把來源丟掉。

Multiclass Spell Slot Progression

使用固定 progression scenarios比對 D&D 5e 2014 rules data預期。

至少含：

single full caster baseline。
full + half caster combination。
multiple caster sources。
non-caster level不錯誤貢獻 caster level。

不要只測一個 Lv10數字；測 boundary / floor behavior。

Pact Magic

Warlock Pact pool與normal slots分開。
multiclass普通 slots增加不改 Pact pool identity。
resource usage可分別追蹤。
直接用 production Warlock Lv3 row 驗證：即使 upstream 是 spell_slots_level_2 = 2，adapter仍分類為 Pact Magic，不能進 normal combined-slot pool。
Wizard / Warlock multiclass 固定驗 normal combined slots 的輸出不包含 Warlock slot-shaped values，同時 Pact pool仍保留自己的 slot level / count。
加一個 adapter-level regression：pool classification 先看 source/profile identity，再解析 spell_slots_level_N；禁止以欄位名稱判斷 pool type。

Resource Capacity Invariant

若 State維持 used + remaining：

initial state sum == capacity。
malformed state sum != capacity → validation fail。
capacity變化後 reconciliation helper產合法 state。

若 migration成usage-only：

P0 state migration測試必須全綠。

P1-E 關門

Prepared / Known / Spellbook / Always Prepared分層全綠。
multiclass slots固定 expectations全綠。
Pact Magic分池全綠。
P0 Wizard fixture migration / Character Sheet全綠。

P1-F — Equipment, Review & Character Creation

對應主要契約：AC-P1-07、AC-P1-08、AC-P1-11。

Equipment Choice Shapes

從實際 SRD class data挑 representative nested options，至少覆蓋：

automatic equipment。
A/B branch。
counted reference。
nested choice。
equipment category。
quantity。

每個 scenario assertion：

available options正確。
selected count正確。 -非法 injected equipment key / category → fail。

No Starting Gold Path

P1 UI / API標準 Builder：

不出現 Starting Gold shopping step。
不要求 Shop service。
equipment resolver不因沒有 economy subsystem而失敗。

Starting Equipment Compile

assert：

Draft choices → CharacterBuild.starting_equipment[] deterministic。
entry ids unique。
quantity正確。
Build save/reload相同。

Initial Inventory

Create Confirm後：

Build Starting Equipment
→ initial State inventory

assert第一次一致。

接著：

remove / add / quantity / equip state mutation
→ reload

assert live Inventory保持最後 State，不由 Build重新洗回。

Initial HP / Hit Dice / Resources

Create Confirm fixture：

current HP = authoritative Max HP。
Temp HP = 0。
Hit Dice available = Build total。
resources = full initial capacity。
conditions empty。
prepared selection = Draft initial state choice。

Review DTO

至少測：

Build summary欄位完整。
Initial State section與 Build section分開。
warnings可見。
non-standard calculated/current/origin可見。
blocking issue使 can_confirm=false。

Confirm Atomicity

故意在不同階段造成失敗：

invalid latest content ref。
blocking structural issue。
invalid initial state。
DB insert failure simulation（可由 transaction test / repository test完成）。

預期每次：

沒有 partial Character。
沒有 orphan Version。
沒有 orphan State。
Draft仍可修正。

Version 1 Metadata Baseline

P1-F migration / Create Confirm至少驗：

P0 deterministic fixture升到 P1 schema後既有 version標為 version_kind=legacy，Build payload canonical equivalent不變。
P1-F Builder Create產生的 Version 1 為 version_kind=create。
Create Version 1 的 parent_version_id / correction lineage為 null。
reload / server restart後 metadata不漂移。

Double Submit / Idempotency

快速重複 Confirm：

不得建立兩隻 Character。
第二次應回同一結果或明確 draft-already-confirmed error，依實作 contract固定。

Full Create Playwright

至少一條 non-caster與一條 caster：

/characters
→ Create
→ 完整 Wizard
→ Review
→ Confirm
→ /characters/:id
→ reload

assert Character Sheet關鍵摘要與 Builder Review一致。

P1-F 關門

從空白可建正式角色。
high-level/multiclass Create可 Confirm。
Starting Equipment / live Inventory隔離全綠。
atomicity / double submit全綠。
P1-F version metadata baseline / P0 legacy migration全綠。
real-backend E2E全綠。

P1-G — Level Up & Character Versions

對應主要契約：AC-P1-09、AC-P1-10。

Version Metadata Continuity

P1-F 已完成 schema migration / legacy backfill；P1-G 驗證後續版本沿用同一 metadata contract：

P0 fixture version仍可讀且維持 version_kind=legacy。
P1-F 建出的 Builder Version 1維持 version_kind=create。
P1-G 新增 Version 才使用 level_up / build_edit / correction。
parent / superseded lineage使用 P1-F 既有欄位／lineage table，不建立第二套。
Build payload canonical內容不被 metadata migration / lineage write改寫。

Level Up Draft

建立既有 Character：

current version N
↓
create level_up draft

assert：

base_version_id = current version id。
Draft含原 Build可重建選擇。
target level = N Build level + 1。
current Character / State在 Draft建立時不變。

Level Up Confirm

assert：

new version number = old + 1。
current_version_id指向新 version。
old Build payload byte/canonical equivalent不變。
parent/base metadata正確。
Character Sheet讀新 Build。

Cancel

Level Up Draft Cancel：

version count不增加。
current version id不變。
Current State canonical equivalent不變。

Stale Base

流程：

Create Draft A from v3
Create Draft B from v3
Confirm B -> v4
Confirm A

A必須被拒絕 stale_build_version；不可建立覆蓋v4的v5 based on stale data。

HP Reconciliation

固定案例：

old current/max = 30/40
new max = 48

預期：

38/48

另測：

current full HP時max增加 → 仍full（因 damage delta 0）。
傷害大於新max的 correction edge → clamp到合法0..newmax並產 warning / documented result。
Numeric max HP override變更同樣走同一 helper。

Spell Slot / Resource Reconciliation

固定 usage fixture：

old capacity有已使用 resource。
Level Up capacity增加。
new used保持，新增 capacity變 remaining。
不變成全滿。

capacity下降 correction：

used clamp不超新 capacity。
remaining不負數。
preview有 warning。

Hit Dice Reconciliation

普通升級：

新取得 die total +1。
available +1。
舊已用掉的 dice不補回。

multiclass切換不同 hit die：

新 die加到正確 die type。

correction total下降：

available clamp合法。
warning可見。

Prepared Reconciliation

Scenario A：新 Build仍允許既有 prepared → 完整保留。

Scenario B：Build correction移除 spell access → prepared變非法：

preview blocking。
Confirm拒絕。
state不被silent mutate。

使用者修正 prepared choice後才可 Confirm。

Inventory / Conditions Preservation

Level Up前先建立非初始 Current State：

inventory增加冒險物品。
Potion quantity已減少。
Shield unequipped。
Condition存在。
Temp HP存在。

Level Up Confirm後assert上述保持，除非明確 invariant需要調整。

Version History

API / UI：

所有 versions按順序可見。
current version marker正確。
version kind / parent可見。
old version detail只顯 Build snapshot，不假裝有當時 live HP / Inventory。

Correction

流程：

current v4
→ Correct Build Draft
→ Confirm
→ v5 correction

assert：

v4不刪、不改。
v5 lineage指向v4。
若標 superseded，History能看出關係。

P1-G 關門

immutable version history全綠。
stale base guard全綠。
HP/resource/hit dice/prepared/inventory reconciliation全綠。
Level Up real-backend E2E全綠。

P1-H — Full P1 Integration & Closeout

P1-H 對應 AC-P1-01 ～ AC-P1-12 全部。

Full Backend Regression

至少跑：

pytest

包含：

P0 ContentRegistry。
P0 Character schema/persistence/rules/API。
P1 Draft / choice resolver。
P1 Ability / progression / multiclass。
P1 ASI / Feat / structural choices。
P1 spellcasting。
P1 equipment / confirm。
P1 version / reconciliation。

Content / Rules Data Validation

data/srd5.1/ Character-Relevant content仍全綠。
P1新增 data/rules/dnd5e-2014/（若有）有 schema / manifest / required-value validation。
Monster / Beast仍不成為 P1 dependency。

Alembic

必須驗：

fresh DB從零升到 head。
P0 schema升到 P1 head。
deterministic P0 fixture在 migration後仍可 load。
P1 Draft / version metadata tables正常。

Frontend

npm install / ci
TypeScript build
Vitest

至少覆蓋：

Character Workshop。
Builder Wizard / rail / summary。
searchable selectors。
validation rendering。
Review。
Version History。
responsive critical layout。

Playwright — Create Lv1

完整 real backend：

Workshop
→ Create Lv1
→ Race / Background
→ Ability
→ Class / choices
→ Equipment
→ Review
→ Confirm
→ Sheet
→ reload

Playwright — Direct High-level Multiclass

至少一條 target high level：

逐級 class rail。
multiclass。
subclass。
ASI / Feat。
spells（若 caster scenario）。
Review / Confirm。

Confirm後讀 Character Sheet與Version 1。

Playwright — Level Up

Open existing character
→ Level Up
→ Add class level
→ choices
→ reconciliation preview
→ Confirm
→ Sheet
→ Version History

Browser Reload Draft Persistence

在 Builder中途 reload：

current step可重建或回合理 default step。
Draft choices不丟失。
server validation summary一致。

Server Restart Persistence

PostgreSQL full stack：

Create Draft / Character
↓
restart backend
↓
reload

Draft / Character / Version / Current State全部從 DB回復，不依賴 process memory。

P0 Character Sheet Regression

既有 P0 fixture：

Sheet三頁可開。
HP / Temp HP / Condition / Prepared / Slots / Hit Dice / Inventory mutation可用。
Shield unequip AC regression仍正確。
Build/State isolation仍成立。

Representative P1 Fixtures

至少有以下 categories 的 deterministic acceptance：

Scenario	驗證重點
Lv1 non-caster	starting grants / ability / equipment / initial State
High-level Fighter	subclass / ASI / Feat / HP progression
High-level Wizard	spellbook / prepared / slots
Prepared caster	prepared eligibility / State separation
Known caster	known progression / replacement
Fighter / Wizard	class order / P0 compatibility
two-source caster multiclass	combined slots / source separation
Warlock multiclass	Pact Magic pool separation

具體數值存 test fixtures / rules data，文件不建立第二份規則表。

Negative Full-flow Cases

至少從 API層嘗試繞過 UI：

illegal multiclass。
early subclass。
extra ASI / feat。
feat prerequisite不足。
invalid spell level/source。
over prepared limit。
invalid equipment option。
confirm incomplete Draft。
stale level-up base。

全部必須 Server拒絕且不留下 partial commit。

Manual Smoke

至少人工檢查：

Character Workshop desktop。
Create Builder desktop。
Create Builder mobile width。
Level rail可讀性。
searchable long spell/equipment selector。
Review warnings / non-standard values清楚。
Level Up reconciliation preview可理解。
Version History不讓人誤以為是HP存檔。
Confirm後 Character Sheet銜接自然。

P1-H 關門條件

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

P1-A～P1-G 各自完成條件通過。
AC-P1-01 ～ AC-P1-12 全部有自動或明確人工證據。
backend tests全綠。
Content / rules data validation全綠。
Alembic fresh + P0→P1 upgrade全綠。
frontend build / Vitest全綠。
Playwright Create / high-level / Level Up全綠。
Draft browser reload / backend restart persistence已驗證。
Version immutability / stale base已驗證。
State reconciliation已驗證。
P0 full regression保持全綠。
Monster / Beast scope仍留 P4-A。
沒有為 P2 / P3 / P7提前建立 Room、AI token、Roll system、Import/Export subsystem。

P1-H 關門後才開始依當時 codebase規劃 P2 Subphases。

This site is open source. Improve this page.