adventure-table

P1 — 實作規格

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

最後更新：2026-08-29

1. P1 目標與 Subphase 原則

P0 已建立 Character-Relevant SRD、Character identity、immutable Build Version、mutable Current State、角色相關 Rules Layer、Character Sheet 與 Current State UI。P1 不重做這些地基，而是在現有正式模型上完成 Character Workshop / Builder。

P1 關門時必須做到：

使用者可以從網站建立合法的 D&D 5e 2014 SRD 角色。
可直接建立高等角色，但規則上仍等效執行 Lv1 → target level 的逐級 progression。
支援 Single-class、Subclass、Multiclass、ASI / Feat、Class / Race / Background structural choices。
支援完整角色用 Spell progression：Known、Spellbook、Prepared eligibility、Always Prepared / Granted、multiclass spell slots 與 Pact Magic。
Character Build Draft 與正式 immutable Character Version 分離。
Level Up 使用同一套 Builder Engine，Confirm 後建立新的 immutable Build Version。
Current State 不因 Build workflow 被重建；Level Up 只做必要且可解釋的 reconciliation。
所有正式規則結果由 Server authoritative rules / builder domain 產生；Frontend 不複製一套 D&D progression engine。

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

P1-A — Builder Domain & Draft Foundation
↓
P1-B — Character Creation Basics
↓
P1-C — Class Progression & Multiclass
↓
P1-D — ASI, Feat & Structural Choices
↓
P1-E — Spellcasting Progression
↓
P1-F — Equipment, Review & Character Creation
↓
P1-G — Level Up & Character Versions
↓
P1-H — Full P1 Integration & Closeout

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

2. P1 已拍板產品行為

以下是 P1 規劃前已確認的行為，實作不得自行改成另一套流程。

Ability Score 建立方式

P1 Builder 提供：

Standard Array
Point Buy
Manual Input

Manual Input 用於輸入實體骰出的結果或手動數值；不在 P1 內建立正式骰子系統。正式 Roll System 屬 P3。

Builder 必須把 ability generation 的輸入與 Race / ASI / Feat 等永久 Build 效果分開處理，最後才編譯成 P0 已定義的 resolved Build Ability Scores。Numeric Override 仍是獨立層，不得與 Manual Input 混成同一概念。

Level Up HP

Character Level 1 使用該 starting class 規則的首級 HP。
後續 Level 可選 Fixed Average 或 Manual Rolled Result。
P1 不提供正式 Roll HP 按鈕；如果玩家用實體骰或其他方式擲出結果，將結果輸入 Manual Rolled Result。
每級實際採用的 base HP gain 必須保存進 Build，延續 P0 hp_progression 的可重建語意。

Starting Equipment

P1 正式處理 Class / Background Starting Equipment 與 nested equipment choices，Confirm Character 時只初始化一次 live Inventory。

P1 不做 Starting Gold 購物流程。 需要以金幣建立特殊角色時，可於角色建立後依既有 Current State / Inventory 機制調整；不為創角建立 Shop 子系統。

Level Up Current State Reconciliation

Level Up Confirm 時：

Max HP 變化時，保留原本已受傷的 HP 差額。例如 30 / 40 升級後 Max HP 變 48，Current HP 變 38 / 48。
舊 Spell Slots / Class Resources 不因升級自動回滿；保留既有消耗，新增加的 capacity 可立即使用。
新取得的 Hit Die 直接加入 Available Hit Dice。
Conditions、Temporary HP、Inventory 等 live Current State 原樣保留，除非新 Build 使其超出正式 state invariant。
Prepared Spells 若在新 Build 下仍合法就保留；若因 Build Correction / Edit 變成不合法，Confirm 前必須要求修正，不得偷偷刪除。

P1 不承接 Import / Export 與 MCP 外殼

P1 Character Workshop 使用 P0 已存在的 Server persistence 完成 Create / Manage / Level Up / Version History。

以下不塞進 P1：

正式 Character JSON Import / Export；留給 P7。
Character Builder MCP / Site Tool transport、AI Join Token、Seat / Role / Permission；留到對應 AI / Room Phase。

P1 必須把 Builder domain service 設計成未來可被 Human UI 與 AI Tool 共用，但不提前建立 MCP infrastructure。

3. P1 最終完成定義

P1-H 關門時，至少可完成以下流程：

Character Workshop
↓
Create Character
↓
建立可保存的 Builder Draft
↓
Basic / Race / Background
↓
Ability Scores / Proficiencies
↓
逐級 Class Progression
↓
Subclass / Multiclass / ASI / Feat / Feature Choices
↓
Spell Progression
↓
Starting Equipment
↓
Review
↓
Server full validation
↓
Confirm
↓
Character + immutable Build Version 1 + initial Current State
↓
開啟既有 Character Sheet

高等角色建立必須等效於：

Lv1 choice
↓
Lv2 choice
↓
...
↓
Target Level choice

不能只讓使用者輸入：

Fighter = 5
Wizard = 5

然後跳過 acquisition order、starting-class grants、multiclass prerequisites、Subclass timing、ASI / Feat timing、HP progression 與 Spell progression。

P1 也必須完成：

Existing Character
↓
Level Up Draft
↓
Add Level / New Choices
↓
Validate
↓
Review State Reconciliation
↓
Confirm
↓
New immutable Build Version
↓
Old Version remains immutable

P1-A — Builder Domain & Draft Foundation

目標

在 P0 正式 CharacterBuild / CharacterState / CharacterRepository 之上建立 Builder 專用 domain layer 與 Draft lifecycle，讓「未填完的角色」不需要偽裝成合法 CharacterBuild。

Draft 與正式 Build 分離

P1-A 必須有正式 Builder Draft 表示能力，至少可區分：

Create Character Draft。
未來 P1-G 使用的 Level Up / Build Edit / Correction Draft mode。
Draft 來源 Character / Build Version（若存在）。
Target Level。
Partial selections。
Builder-specific choice provenance。
Initial Current State seed choices（若建立角色需要）。

Draft 可以不完整；正式 CharacterBuild 不可以。

因此流程固定是：

Builder Draft
↓
Builder Compiler / Resolver
↓
Validation Result
↓
合法時才產生 CharacterBuild candidate

不得為了保存半成品，把 P0 CharacterBuild 大量欄位改成 optional。

Validation Result

Builder validation 至少分：

blocking_error
warning
non_standard

每筆問題需要 machine-readable code、可定位的 field / choice path，以及給 UI 顯示的訊息。

blocking_error：不可 Confirm。
warning：可 Confirm。
non_standard：表示 Numeric Override 等刻意偏離 calculated value 的情況，可 Confirm但必須可見。

Choice Representation

P1-A 建立可重用 choice model，之後 Race / Background / Class / Feature / Equipment / Spell 都使用同一個基本概念，不為每一種選擇做獨立的一次性 UI contract。

至少能表示：

choose N。
reference options。
nested choice。
category / filtered option set。
required / optional choice。
prerequisite / disabled reason。
deterministic choice id，使 Draft reload 後仍能對到同一個選擇。

Draft Persistence

Draft 必須：

Save / Reload。
Browser reload 後可繼續。
Cancel 不修改正式 Character。
Draft validation 失敗不留下半套正式 Build Version。
Create Draft 不會先建立一隻破損 Character。

P0 Regression

P1-A 不得破壞：

P0 fixture load。
P0 Character Sheet。
Current State mutation。
P0 Character Build / State persistence。

完成條件

可建立一份 incomplete Create Draft 並 Save / Reload。
Draft 可以產生 machine-readable validation result。
Draft Cancel 後正式 Character tables 沒有多出半成品。
合法的 P0 Fighter 5 / Wizard 5 Build 仍可經現有 repository 正常讀取。
P0 full regression 保持全綠。

P1-B — Character Creation Basics

目標

建立 Character Workshop 與 Builder Wizard 的前半段，使使用者可以完成建立角色所需的基本身份、Race / Subrace、Background、Ability Scores 與 starting proficiencies / skills choices。

Character Workshop

P1-B 建立 Character Workshop 基本入口，至少包含：

Existing Characters list。
Create Character。
Resume active Create Draft。
Open Character Sheet。

P1 此時不需要 Room / Account / Ownership 系統。

Builder Wizard 基本骨架

固定維持單一 Wizard + Summary 的產品方向。

P1-B 至少完成：

Step 1 — Basic
Step 2 — Race + Background
Step 3 — Ability / Starting Proficiencies

後續 Class / Spell / Equipment step 可以先顯示 disabled / not-yet-implemented phase state，但不得假裝已完成。

Basic

至少：

Name。
Target Character Level。
Ruleset 固定 D&D 5e 2014。
Optional alignment / roleplay fields 不阻擋 Builder。

Target Level 可以直接選高等級；真正逐級 Class progression 在 P1-C 完成。

Race / Subrace / Background

Builder 必須：

從 ContentRegistry / builder content adapter 取得可用項目。
顯示 mechanical grants 與必要 choices。
支援 SRD Race / Subrace 關係。
Background mechanical grants 可正確進入 Draft。
Optional Roleplay 不得變成必填。

P1 必須保留擴充非 SRD content 的能力，但不要求現在加入 PHB 全內容。

P1-B Complete 指 Background Builder 機制完整，不代表 Built-in Background library 完整。 目前 SRD 5.1 normalized content 只有 Acolyte；正式內容數量不足時不得降低 resolver / validation 的機制驗收標準。

Ability Scores

正式支援：

Standard Array
Point Buy
Manual Input

要求：

generation input、racial permanent modifier、ASI / Feat permanent modifier、Numeric Override 必須是不同階段。
Builder Summary 能顯示 base → permanent grants → resolved Build Score → override 後 effective value 的必要差異。
Race bonus 不得因 reload 或 Character Sheet 計算重複套用。
Point Buy legality 由 Server 驗證，不能只靠 frontend disabled button。
Manual Input 若超出 normal generation legality，必須由既定 non-standard / override 路徑處理，而不是靜默當合法標準角色。

Starting Skills / Proficiencies

至少處理：

Race grants / choices。
Background grants / choices。
Starting class 尚未選定前可延後的 class proficiency choices。
Duplicate / incompatible choice 必須有可理解的 validation / disabled reason。

UI Selector 原則

Race、Background、Skill、Proficiency 等中大型 reference list 使用 P0 已驗證過的 searchable / keyboard-accessible combobox pattern；不能退回只能逐項滑動的巨大 <select>。

完成條件

可以從 Character Workshop 開一份 Create Draft。
Basic / Race / Background / Ability / starting choice 可以從 UI 編輯並 reload 保留。
三種 Ability 方法都有 backend validation。
Optional Roleplay 全空不阻塞。
Race permanent ability effect只套一次。
還沒完成 Class progression 時 Draft 可保存；執行 Draft full validation 時必須產生 blocking_error 且 can_confirm=false。P1-B 尚未要求 P1-F 的 Confirm endpoint 存在。

P1-C — Class Progression & Multiclass

目標

建立真正的 level-by-level Class progression，使 Builder 能合法建立 Lv1～Lv20 Single-class 與 Multiclass 角色，並正確處理 starting class、multiclass grants、Subclass timing 與 HP progression。

Level-by-Level Rail

Builder 必須顯示實際 Character Level progression，例如：

Lv1 Fighter
Lv2 Fighter
Lv3 Fighter — Subclass
Lv4 Fighter — ASI/Feat（P1-D 完成）
Lv5 Fighter
Lv6 Wizard
Lv7 Wizard
...

每一格代表一個實際 Character Level acquisition event，而不是單純 class-level totals。

Starting Class

Lv1 class 決定 starting-class grants，包括該規則來源定義的：

Saving Throw proficiencies。
Armor / Weapon / Tool proficiencies。
Starting skill choices。
Starting equipment eligibility。
Lv1 HP 行為。

後續 multiclass 進入同一職業時不得重新拿 starting-class-only grants。

Add Class Level / Multiclass

P1-C 支援：

在 progression rail 某個新 Character Level 選擇既有 class 繼續升級。
合法時加入新 class。
保存 acquisition order。
Character Level 與各 Class Level 分離 derive。
Multiclass prerequisites 由 Server structural validation enforce。
新 class 只取得 2014 multiclass 規則允許的 proficiencies / grants。

如果 prerequisite 不合法：

UI 可 disabled 並顯示原因。
Backend 仍必須拒絕繞過 UI 的非法 Draft / Confirm。

Subclass

底層名稱統一 subclass。
Subclass availability 依該 class 的 class-level timing。
到 required timing 時必須選擇的 subclass 若未選，Draft 為 blocking error。
太早選 subclass 必須 structural validation fail。
每個 class 最多一個 active subclass selection，延續 P0 Build invariant。

Class Features

到達 class level 時，無額外 user choice 的 granted features 可由 Builder Compiler 自動 resolve 進 Build。

有 user choice 的 feature 先建立 required choice record；完整 generic structural selection 在 P1-D 關門。

HP Progression

Character Lv1 使用 starting class 首級 HP規則。
Lv2+ 每個 Character Level 記錄該次 class hit die 對應的 Fixed Average 或 Manual Rolled Result。
Multiclass 新職業的第一個 class level如果不是 Character Lv1，不得拿 full first-level hit die max。
每級實際 base HP gain 必須與 class progression 1:1 對齊並可重建 P0 hp_progression。

Earlier Choice Change

使用者修改較早 level 的 class 時，Builder 必須重新計算後續 legality：

原選擇若仍合法可保留。
變成不合法的 dependent choice 必須標為 needs review / blocking。
不得保留一份 UI 看起來正常、Server Compile 卻會產生矛盾 Build 的 hidden stale state。

完成條件

可建立合法 Lv1～Lv20 Single-class progression。
可建立合法 Multiclass progression 並保存 acquisition order。
Starting class 與 multiclass class grants 可被區分。
Multiclass prerequisite 正反向案例全通過。
Subclass timing 正反向案例全通過。
HP progression 可使用 fixed / manual result 且與每級 class 對齊。
Existing P0 Fighter 5 / Wizard 5 structure可由 P1 progression engine重建出等價 class order / HP shape。

P1-D — ASI, Feat & Structural Choices

目標

補齊 Class / Race / Background / Feature progression 中需要玩家選擇的 structural mechanics，正式完成 ASI / Feat、prerequisite、choice count 與 reusable choice resolver。

ASI Timing

ASI eligibility 依 Class Level progression，不是 total Character Level。

Multiclass 角色不可因 total level 到達某數字就憑空拿 ASI；必須是某個 class 到達對應 progression timing。

data/srd5.1/levels.json 的 ability_score_bonuses 是截至該 Class Level 的累計 ASI opportunity 數，不是『這一級新取得幾次 ASI』。因此只有 cumulative value 相較前一個該職業 Class Level 增加時，本級才產生新的 ASI / Feat opportunity；既有非零 cumulative value 不得讓後續每級重複產生 ASI。

ASI Choice

Builder 支援 2014 ASI 的合法選擇形式，並由 Server enforce：

選擇數量。
Ability 上限與規則限制。
同一 level 的 ASI 不可重複領取。
permanent score change 編譯進 Build resolved Ability Scores。

Numeric Override 不可偽裝成 ASI choice。

Feat Choice

若該 progression node 允許 Feat：

從已載入的 built-in / future custom Feat references 選擇。
prerequisite 為 structural validation。
prerequisite 不合法時 disabled / blocking，並顯示原因。
SRD 目前只有 SRD 內容提供的 Feat；P1 Complete 指機制完整，不代表內建完整 PHB feat library。

Numeric Override 與 Structural Prerequisite

Numeric Override 可改 effective numeric value，但不能直接 bypass structural rule。

例如某 Feat 需要 Ability prerequisite：

Calculated Build Score 不足
↓
不可選

合法 Numeric Override 使 effective score 達到 prerequisite
↓
可以選

但 Override 不可改：

Subclass timing。
ASI occurrence count。
Feature eligibility。
Selection count。
Class progression。

Generic Structural Choice Resolver

P1-D 必須能承載 SRD 角色 progression 真正出現的 reusable choice shapes，例如：

Choose N proficiencies。
Language choice。
Tool / weapon / armor related choice。
Fighting style / feature option。
Nested feature choice。
ASI or Feat branch。

不要為每個 class hardcode 一套專屬 React form。

完成條件

ASI timing 依 class level正確運作，且 ability_score_bonuses cumulative value 不會被誤讀成每級 occurrence。
ASI 永久能力變化只進 Build 一次。
Feat prerequisite 正反向測試全綠。
Numeric Override 能影響 numeric prerequisite，但不能繞過 structural timing / count。
SRD classes / races / backgrounds 需要的 P1 structural choice 都能由共用 resolver 表示或由明確 adapter 轉換。
Blocking choice 未完成時不可 Confirm。

P1-E — Spellcasting Progression

目標

把 P0「可以保存 Spell access / Prepared state」提升成 Builder 能依 class / subclass / level progression 正確建立施法角色與 multiclass spell resources。

Spellcasting Profile

每個施法來源需要獨立 profile，至少知道：

source class / subclass / feature。
spellcasting ability。
access model。
known / spellbook / prepared eligibility。
cantrip / spell progression。
resource pool type。

同一個 spell 若從不同 source 取得，不得因 spell name 相同而失去 source identity。

Spell Access

Build 長期 access 延續 P0：

known
spellbook
always_prepared
granted

一般 prepared 仍不是 Build access type。

Wizard

Builder 必須處理：

Spellbook 長期 access。
初始／升級時 Wizard 規則允許加入 spellbook 的選擇。
Prepared eligibility / limit validation。
初始 Prepared selection 只作為 Current State seed，不寫進 Build access type。

Prepared Casters

Cleric / Druid / Paladin 等準備型來源：

Build 保存長期 eligibility / source profile，不需要把每日 prepared list 固化成 Build Version。
Create Character 時可設定 initial prepared selection，保存進初始 Current State。
Prepared 少於上限可以合法存在；超過或選到不合法來源必須失敗。

Known-spell Casters

Bard / Ranger / Sorcerer / Warlock 等 Known model：

Known selection 屬 Build。
Known count / spell level eligibility 依 progression enforce。
規則允許的 level-up replacement 由同一 Builder workflow 表示，而不是直接改 raw Build JSON。

Always Prepared / Granted

由 class / subclass / feature 永久賦予者：

屬 Build。
不需要每日重新加入 prepared list。
不應錯誤計入一般 prepared selection count，若規則來源定義為不計入。

Multiclass Spell Slots

P1-E 正式完成 P0 延後的 multiclass caster-level / combined spell-slot progression：

一般 multiclass spell slot capacity 依 D&D 5e 2014 caster contribution 規則計算。
各 class Spell Access 仍分開。
Combined slots 不等於角色突然取得其他 class spell list access。

Pact Magic

Warlock Pact Magic 使用獨立 SpellResourcePool / resource representation：

不與一般 multiclass Spell Slots 合成成單一模糊 pool。
Character Sheet / Builder Summary 可清楚區分。
SRD levels.json 對 Warlock 仍使用 spell_slots_level_N 這組一般欄位名稱；pool 類型必須先由 spellcasting source / class identity 判定，不能靠欄位名稱推斷。 Warlock slot-shaped values 不得被一般 multiclass combined-slot aggregation 吃進去。

Initial Resource State

Create Character Confirm 時：

新角色的 spell resources 依 Build capacity 初始化。
Prepared list 寫 Current State。
Spellbook / Known / Always Prepared 寫 Build。

完成條件

Wizard Spellbook vs Prepared separation 從 Builder UI 到 persistence 全程正確。
Prepared caster / Known caster 至少各有代表 fixture 通過。
Multiclass combined slot progression 有固定正反向案例。
Pact Magic 與一般 slots 分池。
Same spell different source 可保留 source identity。
Spell choice legality 由 Server enforce，Frontend 不自行當 authority。

P1-F — Equipment, Review & Character Creation

目標

補齊 Starting Equipment、完整 Review 與 Create Character Confirm，第一次完成「從空白到正式角色」的全流程。

Starting Equipment Choice Resolver

P1-F 必須正式處理 SRD Class / Background 中的：

automatic starting equipment。
choose A / B。
nested choice。
equipment category choice。
quantity。
Background equipment grants。

P1 不做 Starting Gold shopping path。

Build Choice vs Live Inventory

延續 P0：

Starting Equipment selection
= Build choice / initialization source

Live Inventory
= Current State

Create Confirm 時 Starting Equipment 只初始化一次 Current State inventory。

之後 reload、Character Sheet 開啟或 state mutation 時，不得重新由 Build 洗掉 live Inventory。

Review

Review 至少顯示：

Basic / Race / Background。
Character Level / class progression / subclasses。
Ability Scores 與 derived summary。
Proficiencies / Skills。
Features / Feats。
Spell access / initial prepared state / resource pools。
Starting Equipment。
Warnings。
Non-standard Values / Numeric Overrides。

Review 必須清楚區分：

Build data。
Initial Current State seed。

Confirm

Create Confirm 必須是 Server atomic workflow：

Load Draft
↓
Re-resolve latest content / rules
↓
Full structural validation
↓
Compile CharacterBuild
↓
Build initial CharacterState
↓
Create Character
↓
Create immutable Build Version 1
↓
Create Current State
↓
Set current_version_id
↓
Commit

任何一步失敗：

不得留下 Character without Version。
不得留下 Version without State。
Draft 保留，讓使用者修正。

Version 1 Metadata Baseline

P1-F 是 Builder 第一次正式建立 Character Version 1 的 Subphase，因此 version metadata 的 baseline 也必須在 P1-F 定義完成：

P1 以前既有的 P0 Character Version migration 後標為 version_kind=legacy；不得因缺乏 builder provenance 假裝成 P1 create。
P1-F Builder Create 產生的 Version 1 必須標為 version_kind=create。
Create Version 1 的 parent_version_id / correction lineage 欄位為 null。
P1-G 再開始使用 level_up / build_edit / correction 與 parent / superseded lineage；不得到 P1-G 才回頭猜 P1-F 建出的 Version 1 類型。

Warnings vs Blocking

Blocking structural error：Confirm disabled / backend reject。
Warning：允許 Confirm。
Non-standard numeric value：允許 Confirm，但 Review 必須明顯顯示 calculated/current/origin。

Character Sheet Handoff

Confirm 成功後可直接進既有：

/characters/:characterId

P1 不另外做一份 Builder-only Character Sheet。

完成條件

從空 Draft 可經 UI 建立正式 Lv1 角色。
可直接建立合法高等 Single-class / Multiclass 角色。
Nested Starting Equipment choices 可完成並正確初始化 Inventory。
Starting Gold 不出現在 P1標準流程。
Confirm atomicity 負向測試通過。
Builder 建立的 Version 1 明確為 version_kind=create、無 parent / correction lineage；P0 舊 Version migration 為 legacy。
Create 後 reload / server restart 角色仍可由 P0 Character Sheet 正確顯示。
live Inventory 不被 Starting Equipment reload 重建。

P1-G — Level Up & Character Versions

目標

讓既有 Character 使用同一 Builder Engine 進行 Level Up、版本建立、Version History 與必要的 Build correction / versioned Build edit。

Level Up Draft

流程：

Current Build Version
↓
Clone into Level Up Draft
↓
Add one Character Level
↓
選 Class / Subclass / ASI / Feat / Feature / Spell / HP choices
↓
Validate
↓
State Reconciliation Preview
↓
Confirm
↓
New immutable Build Version

Level Up UI 只需要突出本級新增／改變的選擇，不必逼使用者重新走完整 Create Wizard；底層仍使用同一 progression / validation / compiler。

Base Version Guard

Level Up Draft 必須記住 base_version_id。

若 Draft 建立後 Character current version 已被其他 Build workflow 改變：

舊 Draft Confirm 必須拒絕。
不能把舊 base 上的結果覆蓋新 version。

P1 不需要先建立 Room concurrency 系統，但 Build Version stale-base guard 必須存在。

New Version

Confirm 後：

建立新的 immutable Character Build Version。
current_version_id 指向新 version。
舊 version payload 不修改。
Version number 單調增加。
使用 P1-F 已建立的 version metadata baseline，寫入 level_up / build_edit / correction kind 與 parent / correction lineage 供 History 顯示。

Version History

至少可查看：

Version number。
Created time。
Version kind：create / level_up / build_edit / correction 等。
Parent / base version。
Build summary。
Current version indicator。
Superseded / correction lineage（若適用）。

History 是 Build history，不是 Current State save history。

Correction / Build Edit

P1 需要 versioned Build edit 基礎，因為：

升級選錯需要 corrected version。
Wizard 冒險途中加入 Spellbook 是 Build change。
後續 Human DM Build edit 會需要同一條正式 Build workflow。

P1 不做 P2 的 Role / Permission，但 domain 必須能以 Build Draft → Validate → Confirm 建新 Version，而不是 raw update 舊 JSONB。

State Reconciliation

Level Up / Build Edit Confirm 時由 Server 產生 reconciliation preview 並原子套用。

HP

保留 damage delta：

old_damage = old_max_hp - old_current_hp
new_current_hp = new_max_hp - old_damage

結果仍需 clamp / validate 在合法 Current State 範圍內。

一般升級增加 Max HP 不等於 Long Rest，不直接補滿到 Max HP。

Spell Slots / Class Resources

保留舊消耗。
Capacity 增加時新增部分可使用。
不因 Level Up 將原本已用掉的資源全部回滿。
Build Correction 若使 capacity 下降，Server 必須產生明確 reconciliation warning / result，不允許 state 超過新上限。

Hit Dice

普通 Level Up 新取得 Hit Die：

Total 由新 Build derive。
新增加的 die 直接加入 available。
舊 available / spent 狀態保持。

Prepared Spells

新 Build 仍合法的 prepared selection 保留。
變成不合法者在 Confirm 前列為 blocking reconciliation issue。
不靜默 remove。

Other Current State

除非 invariant 要求修正，以下保留：

Temporary HP。
Conditions。
Temporary Effects。
Inventory / equipped / quantity。
Currency / Consumables（若當時 schema 已存在）。
其他 live state。

Cancel

Level Up / Build Edit Draft Cancel：

current Build Version 不變。
Current State 不變。
不產生空 Version。

完成條件

Existing Character 可從 UI Level Up 並建立 Version N+1。
old Version canonical Build payload 完全不變。
stale base draft Confirm 被拒絕。
HP / resources / Hit Dice / prepared / inventory reconciliation 符合本節規則。
Version History 可查看所有 Build Versions。
Correction 不刪舊 version，而是新增 corrected version / lineage。
Cancel 不改正式 Build / State。

P1-H — Full P1 Integration & Closeout

目標

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

AC-P1-01 — Draft 與正式 Character 隔離

Incomplete / invalid Builder Draft 可保存、reload、cancel，但不會建立破損 Character / Build Version / Current State。

AC-P1-02 — Character Creation Basics

Basic、Race / Subrace、Background、Standard Array / Point Buy / Manual Ability、starting proficiencies / skills 可由 UI 建立並由 Server validate。

AC-P1-03 — Level-by-Level Progression

直接建立高等角色仍保留每個 Character Level 的 class acquisition order、starting class 差異、Subclass timing 與 HP progression。

AC-P1-04 — Multiclass Structural Rules

Multiclass prerequisite、starting-class vs multiclass grants、total Character Level / per-class Level 分離全部由 Server enforce。

AC-P1-05 — ASI / Feat / Structural Choice

ASI timing 依 class progression；Feat prerequisite / selection count / feature choice 等 structural rules 不可用 raw payload 或 Numeric Override 繞過。

AC-P1-06 — Spellcasting Progression

Known / Spellbook / Prepared State / Always Prepared / Granted 正確分層；multiclass slots 與 Pact Magic 正確表示；source identity 保留。

AC-P1-07 — Starting Equipment / Inventory Initialization

Class / Background Starting Equipment nested choices 可 resolve；Confirm 時只初始化一次 live Inventory；P1 無 Starting Gold shop workflow。

AC-P1-08 — Atomic Create Confirm

合法 Draft 可原子建立 Character + Build Version 1 + Current State；任何失敗不留下半套正式資料。

AC-P1-09 — Level Up Versioning

Level Up 從 current Build 建 Draft，Confirm 建立新的 immutable Version；old version 不變；stale base 不可覆蓋 current version。

AC-P1-10 — Current State Reconciliation

Level Up 不等同 Rest：HP 保留 damage delta、已消耗 resources 不回滿、新 Hit Die 可用、Prepared 合法者保留、Inventory / Conditions 等 live state 保留。

AC-P1-11 — Server Authoritative Builder

Frontend 只負責呈現 Draft / available choices / validation / summary；正式 eligibility、progression、derived Build candidate 與 Confirm validation 由 Server domain 決定。

AC-P1-12 — P0 Regression / P1 Independence

P0 Character Sheet / Current State / SRD / persistence 全部保持可用；P1 不需要 Room、Campaign、Session、Combat、AI/MCP、Adventure、Snapshot / Export 才能建立與升級角色。

4. P1 代表驗證角色

P1-H 至少保留多組 deterministic fixtures / builder scenarios，不再只靠一隻 P0 Fighter 5 / Wizard 5。

至少涵蓋：

Lv1 non-caster：驗 starting class、skills、equipment、initial state。
High-level single-class Fighter：驗 Subclass、ASI / Feat、class-level timing。
High-level Wizard：驗 Spellbook、prepared state、spell progression。
Prepared caster：驗 prepared eligibility 與 Current State separation。
Known-spell caster：驗 known count / replacement progression。
Fighter / Wizard multiclass：重建 P0 代表結構並驗 acquisition order。
Two spellcasting-source multiclass：驗 combined slot calculation與 spell access分離。
Warlock multiclass：驗 Pact Magic獨立 pool。

具體角色數值與 spell / equipment 選擇放在 test fixture / rules data，不在本文件重複維護規則數字。

5. P2 相容要求

P1 不提前設計 Room / Seat / Role / Controller，但 P1 的 Character / Builder API 不可採用會立即阻止以下能力的方式：

P2 將 Character 放進 Campaign Roster / Player Seat。
Human DM 未來可透過 permission layer 進行 versioned Build Edit。
Player 自己 Level Up 走正式 Builder workflow，而不是 raw Build mutation。
AI Player 代玩時不能因 Controller 身分自行改 Build。
AI Builder Tool 未來可呼叫與 Human UI 共用的 Builder domain service。

P1 不需要現在建立 user ownership、DM key、AI token 或 session permission table。

6. 明確不屬於 P1

以下不在 P1 實作：

Room / Campaign / Session / Seat。
Character Ownership / Account system。
Human / AI Controller handoff。
MCP / Site Tool transport、AI Join Token。
正式 Dice / Roll System；包含創角 Ability / HP 的 server roll。
XP system；MVP 使用 Milestone。
Starting Gold shopping workflow。
Shop / Loot / Rest workflow。
Character JSON Import / Export；正式資料可攜性留 P7。
Combat / Initiative / Attack / Damage / Condition automation。
Tactical Map。
Adventure Importer / AI DM Runtime。
Snapshot / Restore / Campaign Timeline。
Monster / Beast stat blocks；仍由 P4-A 承接。
完整 PHB / 非 SRD content library；非 SRD 資料依需求逐步加入。

若 P1 為了上述功能提前建立大量未使用 subsystem，視為 scope creep。

This site is open source. Improve this page.