D&D（龙与地下城）跑团辅助应用的核心目标不是替代DM与实体聚会，而是把角色卡维护、规则查询、掷骰结算、先攻追踪、法术检索这些打断沉浸感的后台操作收敛进单机可离线运行的移动端。ReactNative+Expo启动，单向数据流，规则引擎与UI彻底分离，静态规则数据（SRD/5eAPI缓存）与动态角色数据（AsyncStorage/SQLite）分层存储，是这类项目落地最稳的结构。
一、总体分层架构
1.表现层（screens/components）：角色卡页、骰子页、先攻追踪页、法术书页、战役笔记页，ReactNavigationv5的Stack+Drawer串联，FlatList渲染长列表（法术/装备/历史），StyleSheet中心化颜色与间距常量。
2.状态层（ReduxToolkit/Context+useReducer）：全局存掷骰模板、当前战役、主题、历史记录；角色实例用规范化结构，避免深层嵌套不可更新。
3.规则引擎层（purefunctions/lib/character.ts类）：只算不渲染，输入基础值返回调整值、豁免、技能加值、先攻、被动感知，便于单测与换规则书（5e/Pathfinder）。
4.静态数据层（data/*.json或dnd5eapi.co缓存）：种族、职业、背景、法术、怪物、专长、装备，只读，首次拉取后落本地。
5.持久层（AsyncStorage/ExpoSQLite/Realm）：角色卡JSON、掷骰模板、战役笔记、离线缓存；AsyncStorage存小KV，SQLite存掷骰历史与多角色关系更合适。
二、角色卡数据模型（ICharacter结构要点）
基础存盘字段：playerName、name、race（9核心种族）、class（12核心职业）、background、level(1-20)、experience、alignment、proficiency、inspiration、abilities（STR/DEX/CON/INT/WIS/CHA六维原始值）、skills（18项技能熟练标记）、savingThrows、equipment[]、spellsKnown[]、spellSlots、hitPoints/curHP/maxHP、armorClass、initiative、gold、notes。
衍生值不落盘，由Character类getter实时算：
•属性调整值：Math.floor((score-10)/2)
•熟练加值：Math.floor((level-1)/4)+2（1级+2，5级+3，17级+6）
-技能加值=对应属性调整值+（熟练?熟练加值:0）
•豁免同上逻辑
•先攻=DEX调整值+d20
•被动感知=10+察觉技能加值
修改STR从15→16，触发重算链：调整值+2→+3，运动技能、力量豁免、近战命中全部联动刷新，UI订阅状态自动更新。
三、骰子模块实现（通用表达式解析）
核心函数接收"2d6+3"、"1d20+DEX+PB"这类notation：
functionrollDie(sides){returnMath.floor(Math.random()*sides)+1;}
functionparseNotation(exprctx){
//ctx={STR_MODDEX_MODPB...}
//拆分数量d面数/加值/属性令牌，累加随机与修正
}
functionrollNotation(exprctx){
const{countsidesflat}=tokenize(expr);
lettotal=flat;
for(leti=0;i<count;i++)total+=rollDie(sides);
returntotal;
}
支持d4~d100、优势/劣势（骰两次取高/低）、暴击翻倍、熟练与属性令牌替换。结果写历史栈，DM可存“哥布林攻击模板”“火球伤害模板”一键连掷，Modalize弹窗管理模板，落AsyncStorage键dice_templates。
四、先攻追踪与战斗模块
Encounter结构：participants[{idnameinitiativetype:'pc'|'npc'hpacconditions[]}]，按initiative降序排回合队列。Round推进时标记当前行动者，支持插入新参与者、延时、倒地/死亡状态、条件计时（昏迷2回合等）。战斗日志append进战役笔记，撤销靠不可变更新快照。
攻击结算流程：选攻击者→选武器→选目标→attackBonus=abilityMod+PB(ifproficient)+magicMod→d20+bonusvs目标AC→命中后damage=parseNotation(weapon.damagectx)→暴击翻倍→扣HP→反馈面板显示命中/闪避/重击。
五、法术书与规则查询
首次启动拉https://www.dnd5eapi.co/api/2014/spells索引，按需拉详情缓存进SQLite；法术书页存角色已知/准备法术index列表，autocomplete-input检索，collapsible展示施法时间/范围/成分/描述/升环效果。离线优先读缓存，无网进详情提示未下载。
六、持久化与导出
角色卡JSON序列化characters/{guid}.json概念映射到AsyncStorage键或SQLite行；提供导出字符串/导入还原，换机不断档。多角色切换走Redux当前activeCharacterId，落app_state键。
七、目录范式参考
App.js
/navigation(Stack+Drawer)
/screens(CharacterSheet/DiceRoller/InitiativeTracker/SpellBook/CampaignNotes)
/components(StatRow/SkillList/HpBar/DiceHistoryModal)
/lib(character.ts/dice.ts/rules5e.ts)
/store(reduxslices:character/dice/campaign)
/data(races.json/classes.json/spells_cache)
/storage(asyncStoragewrappers/sqlitehelper)
/constants(colors.ts/layout.ts)
Hooks（useState/useEffect/useCallback）写组件，纯函数写规则，Redux管跨页状态，AsyncStorage/SQLite管落盘，ReactNavigation管路由——改规则只动/lib，改界面只动/screens，改存档只动/storage，三层互不污染。
D&D移动端辅助器的本质是把SRD规则写成纯函数、把角色状态写成可序列化文档、把掷骰写成可解析表达式，RN只负责把这三件事在离线环境下跑顺。
一、总体分层架构
1.表现层（screens/components）：角色卡页、骰子页、先攻追踪页、法术书页、战役笔记页，ReactNavigationv5的Stack+Drawer串联，FlatList渲染长列表（法术/装备/历史），StyleSheet中心化颜色与间距常量。
2.状态层（ReduxToolkit/Context+useReducer）：全局存掷骰模板、当前战役、主题、历史记录；角色实例用规范化结构，避免深层嵌套不可更新。
3.规则引擎层（purefunctions/lib/character.ts类）：只算不渲染，输入基础值返回调整值、豁免、技能加值、先攻、被动感知，便于单测与换规则书（5e/Pathfinder）。
4.静态数据层（data/*.json或dnd5eapi.co缓存）：种族、职业、背景、法术、怪物、专长、装备，只读，首次拉取后落本地。
5.持久层（AsyncStorage/ExpoSQLite/Realm）：角色卡JSON、掷骰模板、战役笔记、离线缓存；AsyncStorage存小KV，SQLite存掷骰历史与多角色关系更合适。
二、角色卡数据模型（ICharacter结构要点）
基础存盘字段：playerName、name、race（9核心种族）、class（12核心职业）、background、level(1-20)、experience、alignment、proficiency、inspiration、abilities（STR/DEX/CON/INT/WIS/CHA六维原始值）、skills（18项技能熟练标记）、savingThrows、equipment[]、spellsKnown[]、spellSlots、hitPoints/curHP/maxHP、armorClass、initiative、gold、notes。
衍生值不落盘，由Character类getter实时算：
•属性调整值：Math.floor((score-10)/2)
•熟练加值：Math.floor((level-1)/4)+2（1级+2，5级+3，17级+6）
-技能加值=对应属性调整值+（熟练?熟练加值:0）
•豁免同上逻辑
•先攻=DEX调整值+d20
•被动感知=10+察觉技能加值
修改STR从15→16，触发重算链：调整值+2→+3，运动技能、力量豁免、近战命中全部联动刷新，UI订阅状态自动更新。
三、骰子模块实现（通用表达式解析）
核心函数接收"2d6+3"、"1d20+DEX+PB"这类notation：
functionrollDie(sides){returnMath.floor(Math.random()*sides)+1;}
functionparseNotation(exprctx){
//ctx={STR_MODDEX_MODPB...}
//拆分数量d面数/加值/属性令牌，累加随机与修正
}
functionrollNotation(exprctx){
const{countsidesflat}=tokenize(expr);
lettotal=flat;
for(leti=0;i<count;i++)total+=rollDie(sides);
returntotal;
}
支持d4~d100、优势/劣势（骰两次取高/低）、暴击翻倍、熟练与属性令牌替换。结果写历史栈，DM可存“哥布林攻击模板”“火球伤害模板”一键连掷，Modalize弹窗管理模板，落AsyncStorage键dice_templates。
四、先攻追踪与战斗模块
Encounter结构：participants[{idnameinitiativetype:'pc'|'npc'hpacconditions[]}]，按initiative降序排回合队列。Round推进时标记当前行动者，支持插入新参与者、延时、倒地/死亡状态、条件计时（昏迷2回合等）。战斗日志append进战役笔记，撤销靠不可变更新快照。
攻击结算流程：选攻击者→选武器→选目标→attackBonus=abilityMod+PB(ifproficient)+magicMod→d20+bonusvs目标AC→命中后damage=parseNotation(weapon.damagectx)→暴击翻倍→扣HP→反馈面板显示命中/闪避/重击。
五、法术书与规则查询
首次启动拉https://www.dnd5eapi.co/api/2014/spells索引，按需拉详情缓存进SQLite；法术书页存角色已知/准备法术index列表，autocomplete-input检索，collapsible展示施法时间/范围/成分/描述/升环效果。离线优先读缓存，无网进详情提示未下载。
六、持久化与导出
角色卡JSON序列化characters/{guid}.json概念映射到AsyncStorage键或SQLite行；提供导出字符串/导入还原，换机不断档。多角色切换走Redux当前activeCharacterId，落app_state键。
七、目录范式参考
App.js
/navigation(Stack+Drawer)
/screens(CharacterSheet/DiceRoller/InitiativeTracker/SpellBook/CampaignNotes)
/components(StatRow/SkillList/HpBar/DiceHistoryModal)
/lib(character.ts/dice.ts/rules5e.ts)
/store(reduxslices:character/dice/campaign)
/data(races.json/classes.json/spells_cache)
/storage(asyncStoragewrappers/sqlitehelper)
/constants(colors.ts/layout.ts)
Hooks（useState/useEffect/useCallback）写组件，纯函数写规则，Redux管跨页状态，AsyncStorage/SQLite管落盘，ReactNavigation管路由——改规则只动/lib，改界面只动/screens，改存档只动/storage，三层互不污染。
D&D移动端辅助器的本质是把SRD规则写成纯函数、把角色状态写成可序列化文档、把掷骰写成可解析表达式，RN只负责把这三件事在离线环境下跑顺。