commit 2e1b58bada2d41330b779e00bf5723073c014529
Author: chenchun <chenchun@virtheart.com>
Date:   Tue Apr 28 19:19:20 2026 +0800

    docs: 添加项目文档和图表文件
    
    添加游戏设计文档、技术架构文档、数值经济文档等内容
    新增Mermaid图表文件描述系统架构和流程
    包含README说明文档结构和阅读顺序

diff --git a/docs/01-游戏总览.md b/docs/01-游戏总览.md
new file mode 100644
index 0000000..d48cc9e
--- /dev/null
+++ b/docs/01-游戏总览.md
@@ -0,0 +1,89 @@
+# 01 游戏总览
+
+## 1.1 一句话定位
+
+一款以废土生存为主题的“放置式资源管理 + 轻量地图探索 + 数据驱动内容”的单人游戏：玩家在有限的时间与状态压力下做取舍，逐步建立可持续的生存与发展体系。
+
+## 1.2 核心体验支柱
+
+- 取舍：资源永远不够，必须在食物/水/药品/弹药/工具耐久/辐射代价之间做选择
+- 节奏：短期目标（活下去）与中长期目标（科技/基地能力/地图推进）交织
+- 风险收益：每次出行都是一次投资决策；回来的战利品要覆盖时间与损耗
+- 叙事驱动探索：地点的文本、事件、任务把“活着”变成“有目的地活着”
+- 数据驱动内容扩展：用统一模板快速新增物品、配方、地点、敌人、事件与任务
+
+## 1.3 目标用户
+
+- 喜欢：生存压力、规划、资源管理、废土题材、文字叙事
+- 不强依赖：操作反应、复杂连招、长时间高强度战斗
+- 典型画像：
+  - “计划型玩家”：愿意研究配方与风险表，追求最优路线
+  - “叙事探索型玩家”：愿意读文本、做选择，喜欢收集线索
+
+## 1.4 平台与交互
+
+- 平台：Web（PC 优先）+ Mobile Web（触控适配）
+- 交互特征：
+  - 少输入、少打断：主要交互为点击/长按/选择项
+  - 信息密度高：状态与背包始终可见或一键展开
+  - 允许碎片化：随时暂停/自动存档/快速保存
+
+## 1.5 核心循环（高层）
+
+```mermaid
+flowchart LR
+  A[基地：整理与制作] --> B[准备：补给与装备]
+  B --> C[出行：移动到地点]
+  C --> D[探索：资源/事件/任务]
+  D --> E{遭遇？}
+  E -->|战斗| F[战斗与消耗]
+  E -->|非战斗事件| G[选择与结果]
+  F --> H[回收：战利品/伤病/污染]
+  G --> H
+  H --> I[发展：科技/工具/基地能力]
+  I --> A
+```
+
+对应源文件：[core-loop.mmd](./diagrams/core-loop.mmd)
+
+## 1.6 玩法层级拆解
+
+- 层级 0：时间推进
+  - 一切压力来源（饥饿、口渴、精力、理智、辐射、资源刷新）都绑定时间
+- 层级 1：生存循环（活下去）
+  - 维持状态在安全区间内，避免死亡/崩溃/失控 debuff
+- 层级 2：出行循环（赚回成本）
+  - 把“时间与状态损耗”转化为“资源与信息”
+- 层级 3：发展循环（越活越轻松）
+  - 通过制作/科技/基地设施降低单位收益成本，扩大可探索范围
+- 层级 4：叙事与推进（给活下去一个理由）
+  - 任务链、地点线索、关键抉择，逐步解锁新区域与新系统
+
+## 1.7 失败与目标（面向可持续设计）
+
+- 失败状态（Fail State）
+  - 生命值归零
+  - 理智崩溃导致不可逆负面状态（可作为硬失败或软失败）
+  - 某些灾害/剧情节点触发“撤离失败”等结束条件（可选）
+- 目标结构（Goals）
+  - 短期：活过前 N 天、修复基础设施、拿到某关键工具
+  - 中期：解锁某关键科技树、找到避难所入口/关键 NPC
+  - 长期：完成主线任务、建立稳定生产链、探索全地图
+
+## 1.8 内容规模（建议基线）
+
+为保证“可玩 + 可扩展”同时可控，建议最小可发布版本（MVP）规模：
+
+- 地点：15–25 个（含基地/过渡点/资源点/剧情点）
+- 物品：150–250 个（食物/材料/工具/装备/任务物品）
+- 配方：120–200 条（制作/烹饪/锻造/过滤/医疗）
+- 敌人：20–35 类（含变种与精英）
+- 事件：80–150 条（通用事件 + 地点事件 + 灾害事件）
+- 任务：25–40 条（主线 8–12，支线 17–28）
+
+## 1.9 非目标（避免范围失控）
+
+- 不做：高强度动作战斗、复杂物理模拟、多人联机
+- 不做：大规模实时建造与自由摆放（可做“设施槽位”式抽象）
+- 不做：硬核 Roguelike 随机生成全世界（保留局部探索图/遭遇表随机）
+
diff --git a/docs/02-GDD-游戏设计总文档.md b/docs/02-GDD-游戏设计总文档.md
new file mode 100644
index 0000000..7a20280
--- /dev/null
+++ b/docs/02-GDD-游戏设计总文档.md
@@ -0,0 +1,169 @@
+# 02 GDD（游戏设计总文档）
+
+## 2.1 产品概述
+
+- 类型：废土生存 / 放置式资源管理 / 轻探索 / 文字叙事
+- 视角与表现：以 UI 与文本驱动为主，辅以轻量图标与状态反馈
+- 核心差异点：
+  - “时间推进 + 状态压力”让所有决策可量化
+  - “地点 = 内容容器”，不同地点有独立的资源结构/事件池/敌人池/任务触发
+  - 数据驱动内容体系，便于持续运营式更新（即使是单机）
+
+## 2.2 设计原则（约束全项目）
+
+- 数据驱动优先：内容（物品/配方/地点/敌人/事件/任务）尽量不写死在逻辑层
+- 边界清晰：系统之间通过统一的“消耗/产出/条件/结果”接口组合
+- 可解释：数值与概率尽量可在 UI 上给到提示（风险等级、预期收益范围、影响因素）
+- 可扩展：新增内容不应引发代码级联改动，最多新增配置与少量通用规则
+- 可测试：每个系统都应提供可验证的输入输出与可重放的随机种子
+
+## 2.3 核心循环（系统级）
+
+```mermaid
+sequenceDiagram
+  participant P as 玩家
+  participant UI as 客户端UI
+  participant SIM as Simulation(时间/状态)
+  participant CT as Content(配置与表)
+  participant EVT as Event(事件引擎)
+  participant CMB as Combat(战斗引擎)
+  participant SAV as Save(存档)
+
+  P->>UI: 选择地点/动作
+  UI->>SIM: 请求推进时间(Δt)
+  SIM->>CT: 读取状态消耗/刷新规则
+  SIM->>EVT: 抽取事件(按地点/权重/条件)
+  EVT-->>UI: 返回事件(文本/选项/结果预览)
+  alt 触发战斗
+    UI->>CMB: 初始化战斗(玩家/敌人/距离/武器)
+    CMB-->>UI: 回合结果/日志
+  end
+  UI->>SAV: 自动存档/快速保存
+```
+
+对应源文件：[architecture-core-loop.mmd](./diagrams/architecture-core-loop.mmd)
+
+## 2.4 时间与节奏
+
+### 2.4.1 时间粒度
+
+- 基础粒度：分钟（UI 显示到分钟）
+- 推进来源：
+  - 被动流逝：玩家停留、整理、观察等
+  - 行为消耗：制作、采集、移动、休息、战斗
+  - 加速：长行为用“进度条 + 快速推进”呈现，避免等待
+
+### 2.4.2 节奏设计（建议）
+
+- 早期（0–3 天）：生存建立期，强调“水/食物/基础工具”
+- 中期（3–15 天）：系统展开期，强调“制作链与地图推进”
+- 后期（15+ 天）：挑战与叙事收束，强调“灾害、精英敌人、关键任务抉择”
+
+## 2.5 玩家状态系统（总览）
+
+状态分三类：
+
+- 生存状态：饥饿、口渴、精力、生命、体温/感染（可选）
+- 精神与污染：理智、辐射（或污染值）
+- 成长属性：力量/敏捷/智力/感知/幸运等（决定阈值、战斗与事件成功率）
+
+关键要求：
+
+- 状态都有“自然消耗曲线”
+- 状态变化会触发“阈值效果”（软惩罚优先，硬惩罚谨慎）
+- 状态变化必须能被日志/提示解释（为什么掉这么快、怎么恢复）
+
+## 2.6 物品与背包（总览）
+
+- 物品分类：食物、材料、工具、武器、护甲、弹药、任务物品、消耗品
+- 容量设计：以“格子/体积/重量”三者之一为主（建议体积），并提供容器（箱子/基地仓库）
+- 耐久：工具/武器/护甲具备耐久；耐久影响效率或失效
+- 可堆叠：材料、弹药、部分消耗品可堆叠；任务物品通常不可堆叠
+
+## 2.7 制作与科技树（总览）
+
+### 2.7.1 制作台与技能域
+
+- 制作台类别：手工、工坊、锻造、烹饪、过滤/净水、医疗、科研
+- 制作输出：新物品、设施升级、配方解锁、状态变化（如烹饪恢复）
+
+### 2.7.2 科技树原则
+
+- 以“能力解锁”为主，不以“数值膨胀”为主
+- 每条科技都明确：
+  - 解锁哪些配方/地点能力/装备槽
+  - 降低哪些成本（时间/材料/损耗）
+  - 带来哪些新风险（辐射副作用/更高敌人强度）
+
+## 2.8 地图与地点（总览）
+
+地图是“地点图（Graph）”，地点之间通过路径连接：
+
+- 路径属性：距离/时间成本、风险等级、可用交通方式（步行/车/地铁隧道等）
+- 地点属性：
+  - 资源点：可采集资源与刷新规则
+  - 垃圾点：高随机、偏材料
+  - 敌人池：按权重与条件刷新
+  - 事件池：通用+地点专属+任务事件
+  - 设施：交易/休息/制作/治疗/情报
+
+## 2.9 事件系统（总览）
+
+事件是叙事与玩法的粘合剂，要求可配置、可组合、可追踪：
+
+- 触发方式：进入地点/停留时间/状态阈值/拥有物品/完成任务
+- 表现：文本 + 选项（0–4 个）
+- 结果：消耗/获得/状态变化/战斗/解锁/标记
+- 结果应支持：
+  - 固定结果
+  - 概率结果（基于属性/装备修正）
+  - 延迟结果（标记到未来某天或下一次进入）
+
+## 2.10 战斗系统（总览）
+
+定位：轻量战斗，不喧宾夺主；战斗是“风险的一种表现形式”。
+
+建议采用“距离 + 回合选项”的战斗模型：
+
+- 关键变量：距离、武器射程、命中率、护甲减伤、体力/精力消耗、逃跑概率
+- 玩家选项：攻击、防御、前进、后退、逃跑、技能（可选）
+- 结果反馈：清晰的战斗日志 + 对状态与耐久的影响解释
+
+## 2.11 任务与叙事（总览）
+
+任务系统用于：
+
+- 引导玩家穿过系统学习曲线
+- 解锁新区域/新系统
+- 提供长期目标与世界观信息
+
+任务类型：
+
+- 主线：推动核心区域与关键真相
+- 支线：地点故事、NPC 委托、资源链解锁
+- 动态任务：基于当前状态（缺水/高辐射/缺弹药）生成的生存委托（可选）
+
+## 2.12 灾害与世界压力（总览）
+
+灾害是“节奏调节器”：
+
+- 类型：沙尘暴、酸雨、辐射风暴、虫潮、断水期等
+- 作用方式：
+  - 改变某段时间的消耗曲线（更渴/更冷）
+  - 改变地点风险与收益（资源更少、敌人更强）
+  - 提供临时奖励窗口（例如灾后遗留物）
+
+## 2.13 存档与可重玩
+
+- 自动存档：关键节点（回基地、完成任务、重大事件后）
+- 快速保存：手动触发（用于策略试错）
+- 多档位：支持本地多槽与云端绑定（可选）
+- 可重玩策略：事件池权重、遭遇表、探索地图使用随机种子，保证“可控随机”
+
+## 2.14 UI/UX 总原则
+
+- 始终告诉玩家“为什么”：状态变化、失败原因、事件概率来源
+- 重要信息常驻：核心生存状态、背包容量、当前地点风险提示
+- 复杂信息分层：高级计算放在悬浮/详情面板，不挤占主界面
+- 对移动端友好：触控目标足够大，避免长列表滚动卡死
+
diff --git a/docs/03-系统设计.md b/docs/03-系统设计.md
new file mode 100644
index 0000000..fb41990
--- /dev/null
+++ b/docs/03-系统设计.md
@@ -0,0 +1,331 @@
+# 03 系统设计
+
+本文档以“可实现、可平衡、可扩展”为目标，对核心系统做可落地的规格定义。所有系统尽量以统一的“条件/消耗/产出/冷却/概率/标记”表达，便于数据驱动与复用。
+
+## 3.1 时间系统
+
+### 3.1.1 时间推进来源
+
+- 被动流逝：玩家停留在地点、整理背包、阅读日志
+- 行为推进：制作、采集、移动、休息、治疗、战斗
+- 加速推进：长行为可在 UI 显示进度条并快速推进
+
+### 3.1.2 时间推进的副作用（统一执行顺序）
+
+一次时间推进 `advanceTime(Δt)` 必须按固定顺序执行，避免“先后顺序导致结果不可解释”：
+
+1. 计算状态消耗（饥饿/口渴/精力/理智/辐射等）
+2. 计算 Buff/Debuff 结算（按 interval 或按时间累计）
+3. 地点资源刷新与生长
+4. 敌人刷新窗口推进（遭遇表/权重）
+5. 灾害计时与效果更新
+6. 触发“基于时间”的任务/事件检查
+7. 写入日志与可视化提示
+
+```mermaid
+flowchart TD
+  A[advanceTime Δt] --> B[状态消耗]
+  B --> C[Buff结算]
+  C --> D[资源生长]
+  D --> E[遭遇/敌人刷新]
+  E --> F[灾害结算]
+  F --> G[任务/事件检查]
+  G --> H[日志与提示]
+```
+
+对应源文件：[time-pipeline.mmd](./diagrams/time-pipeline.mmd)
+
+### 3.1.3 可测试性要求
+
+- `advanceTime(Δt)` 必须是纯逻辑可重放：输入（状态/地点/随机种子）确定，输出确定
+- 所有随机必须可注入 seed，避免线上“无法复现”的 bug
+
+## 3.2 状态系统（生存/精神/污染）
+
+### 3.2.1 核心状态列表（建议）
+
+- 生命（HP）：硬失败边界
+- 饥饿：低饥饿降低恢复、降低命中/逃跑等
+- 口渴：比饥饿更急迫，强约束出行时长
+- 精力：约束连续行动；低精力叠加负面 Buff
+- 理智：驱动叙事与事件；低理智引发幻觉/误判/不可控选择（可选）
+- 辐射/污染：长期压力；影响上限、引发变异与负面状态
+
+### 3.2.2 状态表示与阈值
+
+每个状态至少包含：
+
+- `value` 当前值
+- `min/max` 上下限（或软上限）
+- `regen/decay` 每分钟变化或由公式计算
+- `thresholds` 阈值效果表（进入阈值时添加/移除 Buff）
+
+阈值效果建议优先“软惩罚”，例如：
+
+- 饥饿过低：移动耗时增加、制作速度降低、战斗命中降低
+- 口渴过低：理智下降加快、出行事件风险上升
+- 辐射过高：最大生命/精力上限下降，物品治疗效率降低
+
+### 3.2.3 Buff/Debuff 设计
+
+Buff 必须具备可解释来源与可清除/可缓解路径：
+
+- 来源：事件、食物、药物、环境、灾害、装备、技能
+- 结算：按时间间隔（interval）或按行动（onAction）触发
+- 堆叠：定义 stack 规则（叠加、刷新时长、取最大/取和）
+
+## 3.3 物品、背包与容器
+
+### 3.3.1 物品分类
+
+- 食物：恢复饥饿/精力，可能增加辐射或降低理智
+- 饮水：恢复口渴，可能增加辐射
+- 材料：用于制作、交易、修理
+- 工具：提高采集/制作效率，通常有耐久
+- 武器/护甲：战斗相关
+- 药品：治疗/解毒/抗辐射
+- 任务物品：推动剧情，通常不可丢弃或有提示
+
+### 3.3.2 容量模型（推荐：体积）
+
+- `volume`：物品占用体积
+- `stackLimit`：最大堆叠
+- 背包容量 `bagCapacity`：体积上限
+- 容器（箱子/仓库）容量 `storageCapacity`：体积上限
+
+设计理由：
+
+- 体积比“格子”更适合废土资源管理的“取舍”表达
+- 体积比“重量”更少涉及物理与移动速度耦合，平衡更稳定
+
+### 3.3.3 耐久与损耗
+
+- 工具/装备耐久下降来源：使用、战斗、环境事件
+- 耐久影响方式：
+  - 低耐久降低效率/命中/防护
+  - 耐久为 0 时失效或损坏
+- 修理策略：
+  - 基地可修理（消耗材料 + 时间）
+  - 野外可应急修理（更高成本/更低效率）
+
+## 3.4 制作、烹饪、锻造与科研
+
+### 3.4.1 配方数据结构（通用）
+
+每条配方至少包含：
+
+- `id/name`
+- `workbenchType`（手工/工坊/锻造/烹饪/过滤/医疗/科研）
+- `requirements`：科技/设施/属性阈值/工具条件
+- `inputs`：消耗物品与数量
+- `outputs`：产出物品与数量（支持概率）
+- `timeCost`：时间消耗（分钟）
+- `energyCost`：精力消耗（可选）
+- `byproducts`：副产物（垃圾、污染等）
+
+### 3.4.2 科技树（能力导向）
+
+科技树节点建议分为三类：
+
+- 解锁类：解锁制作台/地点能力/新区域
+- 优化类：降低时间成本、降低材料损耗、提高成功率
+- 风险类：引入强力收益同时引入副作用（辐射、灾害触发概率等）
+
+### 3.4.3 制作失败与变体（提升可玩性）
+
+可选机制：
+
+- 失败：按成功率产生损耗/产出降低/副产物增加
+- 变体：同一配方可因材料替代产生不同品质/副作用
+- 品质：普通/良好/精良（品质影响耐久/效果/价值）
+
+## 3.5 地图、地点与移动
+
+### 3.5.1 地点图（Graph）结构
+
+- 节点：地点（基地、路口、资源点、剧情点）
+- 边：路径（时间成本、风险等级、交通方式）
+
+### 3.5.2 移动消耗
+
+移动的成本由三部分组成：
+
+- 时间成本（基础时间 * 路径系数）
+- 状态消耗（按时间推进的消耗 + 额外精力消耗）
+- 风险成本（途中遭遇概率、受伤概率、资源损耗）
+
+### 3.5.3 地点模板（用于内容生产）
+
+每个地点应配置：
+
+- `tags`：地洞/村庄/废墟/丛林/避难所等
+- `dangerLevel`：风险等级（用于 UI 提示与遭遇权重）
+- `resourceNodes`：可采集资源与刷新规则
+- `trashNodes`：随机垃圾池与刷新规则
+- `encounterTable`：敌人/事件权重表
+- `services`：交易/休息/制作/治疗/情报
+- `questHooks`：进入/停留/条件触发的任务节点
+
+## 3.6 采集、垃圾与资源刷新
+
+### 3.6.1 资源节点（可预测收益）
+
+资源节点用于提供“可规划收益”：
+
+- 刷新规则：按时间增长（线性/分段）、上限、特殊条件（肥料/净水）
+- 采集成本：工具、时间、精力
+- 产出：固定 + 少量随机波动
+
+### 3.6.2 垃圾节点（高随机收益）
+
+垃圾节点用于提供“惊喜与赌博”：
+
+- 产出：低价值材料为主，少量稀有掉落
+- 风险：可能触发负面事件（感染/辐射/敌人）
+
+### 3.6.3 风险收益标注（UI 需求）
+
+每个采集/垃圾行为都要显示：
+
+- 预估耗时（分钟）
+- 预估消耗（口渴/精力）
+- 风险提示（可能战斗/可能辐射/可能受伤）
+
+## 3.7 事件系统（详细）
+
+### 3.7.1 事件结构
+
+事件由三部分构成：
+
+- `trigger`：触发条件（地点/时间/状态/物品/任务进度）
+- `content`：文本与选项（可插入变量）
+- `effects`：结果链（消耗/获得/状态变化/标记/战斗/跳转）
+
+### 3.7.2 选项与概率
+
+选项结果支持：
+
+- 固定结果
+- 概率结果（权重表）
+- 属性检定（属性→成功率→不同结果）
+- 资源检定（消耗某物品才可选）
+
+### 3.7.3 事件结果链（可组合）
+
+结果链建议采用“原子效果”组合：
+
+- `addItem/removeItem`
+- `addStatus`
+- `addBuff/removeBuff`
+- `setFlag`（任务标记、世界标记）
+- `startCombat`
+- `teleport`（移动到新地点）
+- `unlockRecipe/unlockPlace`
+- `log`（统一日志格式）
+
+## 3.8 战斗系统（详细）
+
+### 3.8.1 战斗定位
+
+战斗用于表达风险，避免成为主玩法；战斗时间应可控，且“逃跑始终可行但有代价”。
+
+### 3.8.2 战斗模型（距离 + 回合）
+
+关键变量：
+
+- `distance`：双方距离（离散或连续）
+- `range`：武器有效射程
+- `hitRate`：命中率（基于距离、状态、装备、掩体）
+- `damage`：伤害（基础值 * 修正）
+- `armor`：减伤/免伤机制
+- `stamina/energy`：战斗行动消耗
+
+玩家动作：
+
+- 进攻：消耗弹药/耐久，可能造成伤害
+- 防御：降低被命中或降低伤害
+- 前进/后退：改变距离，影响下一回合命中率与逃跑
+- 逃跑：成功则结束战斗并触发“撤离成本”（掉落/受伤/时间损失）
+
+```mermaid
+stateDiagram-v2
+  [*] --> Init
+  Init --> PlayerTurn
+  PlayerTurn --> Resolve
+  Resolve --> EnemyTurn
+  EnemyTurn --> Resolve
+  Resolve --> CheckEnd
+  CheckEnd --> PlayerTurn: 未结束
+  CheckEnd --> Escape: 逃跑成功
+  CheckEnd --> Win: 敌人死亡
+  CheckEnd --> Lose: 玩家死亡/崩溃
+  Escape --> [*]
+  Win --> [*]
+  Lose --> [*]
+```
+
+对应源文件：[combat-state.mmd](./diagrams/combat-state.mmd)
+
+### 3.8.3 战斗掉落与后果
+
+- 掉落不只是奖励，也是内容容器（任务物品、线索、稀有材料）
+- 战斗后果必须可见：
+  - 伤口/感染（持续性 debuff）
+  - 辐射暴露
+  - 装备耐久下降
+  - 弹药消耗与补给压力
+
+## 3.9 任务系统（详细）
+
+### 3.9.1 任务状态机
+
+任务建议包含：
+
+- `NotStarted` 未触发
+- `Active` 进行中
+- `Completed` 完成（领取奖励）
+- `Failed` 失败（可选）
+- `Locked` 锁定（条件不足）
+
+### 3.9.2 任务目标类型
+
+- 拥有/交付物品
+- 到达地点/探索次数
+- 击败敌人
+- 制作某物
+- 触发某事件/做出某选择
+- 生存到某天/某时间窗口
+
+### 3.9.3 奖励设计
+
+奖励优先给“能力”而非单纯资源：
+
+- 解锁新配方、新地点服务、新设施槽位
+- 给关键工具/装备（降低后续成本）
+- 给叙事线索与地图标记
+
+## 3.10 灾害系统（详细）
+
+灾害由三段组成：
+
+- 预警期：给玩家准备窗口（提示与倒计时）
+- 爆发期：改变规则（消耗曲线、遭遇权重、资源刷新）
+- 残留期：提供短期机会（灾后掉落、特殊事件）
+
+灾害必须满足：
+
+- 可配置开始条件（天数区间、概率、任务触发）
+- 可配置影响范围（全局/特定区域）
+- 对 UI 有清晰展示（倒计时、当前影响）
+
+## 3.11 交易与经济系统（简化版）
+
+交易系统建议为“基于稀缺度的动态标价”：
+
+- 基础价：物品配置中的 `baseValue`
+- 地点修正：不同地点对物品类别有偏好（倍率）
+- 供需修正：根据玩家近期交易记录做轻微浮动，避免刷钱
+- 风险定价：高风险区域的补给更贵、材料更便宜
+
+经济更完整设计见：[05-数值与经济.md](./05-%E6%95%B0%E5%80%BC%E4%B8%8E%E7%BB%8F%E6%B5%8E.md)
+
diff --git a/docs/04-内容与数据字典.md b/docs/04-内容与数据字典.md
new file mode 100644
index 0000000..1fe144e
--- /dev/null
+++ b/docs/04-内容与数据字典.md
@@ -0,0 +1,272 @@
+# 04 内容与数据字典
+
+本文档定义新项目的“数据驱动内容”规范：字段含义、约束与复用策略。目标是让内容策划能够在不改代码的情况下扩展大部分内容，同时让程序具备稳定、可验证的数据接口。
+
+## 4.1 总体约束
+
+- 所有配置都必须有 `id`（稳定、不可随意改名），并且支持本地化 `name/desc`。
+- 配置要可增量加载：按“基础数据 → 扩展包（DLC/活动）”分层，不互相覆盖时尽量追加。
+- 任何“逻辑分支”都尽量用配置表达（条件表达式、标签、权重表、效果链），避免硬编码。
+
+## 4.2 通用结构
+
+### 4.2.1 标签（Tags）
+
+标签用于跨系统复用与筛选，避免重复字段：
+
+- 物品标签：`food`, `water`, `medicine`, `scrap`, `tool`, `weapon`, `armor`, `ammo`, `quest`
+- 地点标签：`home`, `settlement`, `ruins`, `tunnel`, `forest`, `vault`, `radiated`, `safe`
+- 事件标签：`combat`, `trade`, `moral`, `hazard`, `story`
+- 敌人标签：`human`, `mutant`, `insect`, `beast`, `robot`
+
+### 4.2.2 条件（Condition）
+
+用于事件/任务/配方/解锁等系统的统一条件表达：
+
+- 状态阈值：`status.hunger >= 20`
+- 物品拥有：`inventory.has("water_purified", 1)`
+- 科技完成：`tech.has("water_filter_1")`
+- 地点/标记：`world.flag("met_mysterious_trader") == true`
+- 时间：`time.day >= 5 && time.hour >= 18`
+
+实现建议：条件采用受限表达式语言（DSL）或 JSON 结构化条件，避免 `eval`。
+
+### 4.2.3 效果（Effect）
+
+所有可配置结果尽量拆成原子效果并支持链式组合：
+
+- `AddItem/RemoveItem`
+- `AddStatus`（可正可负）
+- `AddBuff/RemoveBuff`
+- `SetFlag`（任务/世界标记）
+- `UnlockRecipe/UnlockTech/UnlockPlaceService`
+- `StartCombat`
+- `Teleport`
+- `Log`
+
+## 4.3 物品（Item）
+
+### 4.3.1 字段定义（建议）
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---:|:---:|---|
+| id | string | 是 | 稳定唯一 ID |
+| name | string | 是 | 显示名 |
+| desc | string | 否 | 描述文本 |
+| type | string | 是 | `food/material/tool/weapon/armor/ammo/quest/medicine` |
+| tags | string[] | 否 | 标签，用于筛选与规则复用 |
+| rarity | string | 否 | `common/uncommon/rare/epic` |
+| stackLimit | number | 否 | 堆叠上限，默认 1 |
+| volume | number | 否 | 占用体积，默认 1 |
+| durability | {max:number} | 否 | 耐久，存在则可损耗 |
+| effects | Effect[] | 否 | 使用后效果链（食物/药品等） |
+| equipSlot | string | 否 | `weapon/head/body/foot` 等 |
+| combat | object | 否 | 武器/护甲战斗参数 |
+| baseValue | number | 否 | 基础交易价值 |
+| craftable | boolean | 否 | 是否可制作（方便筛选 UI） |
+
+### 4.3.2 武器/护甲 combat 字段（建议）
+
+- 武器：
+  - `damageMin/damageMax`
+  - `range`
+  - `hitBonus`
+  - `ammoType`（可空：近战）
+  - `critChance/critMult`
+- 护甲：
+  - `armor`
+  - `dodgeBonus`
+  - `radiationResist`（可选）
+
+### 4.3.3 物品效果（使用）
+
+食物/药品/饮水等用 `effects` 表达，避免写死：
+
+```json
+{
+  "id": "water_purified",
+  "name": "净水",
+  "type": "water",
+  "stackLimit": 10,
+  "volume": 1,
+  "effects": [
+    {"type": "AddStatus", "status": "thirst", "value": 25},
+    {"type": "AddStatus", "status": "radiation", "value": -2}
+  ]
+}
+```
+
+## 4.4 状态（Status）与阈值
+
+### 4.4.1 字段定义
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---:|:---:|---|
+| id | string | 是 | `hunger/thirst/energy/life/san/radiation` 等 |
+| name | string | 是 | 显示名 |
+| desc | string | 否 | 说明 |
+| min/max | number | 是 | 上下限 |
+| value | number | 否 | 默认初值 |
+| decayPerMin | number | 否 | 每分钟自然变化（负数表示下降） |
+| thresholds | Threshold[] | 否 | 阈值效果表 |
+
+### 4.4.2 Threshold 定义
+
+- `atOrBelow` 或 `atOrAbove`
+- `applyBuff` / `removeBuff`
+- `uiHint`（用于提示玩家原因）
+
+## 4.5 Buff/Debuff（Buff）
+
+### 4.5.1 字段定义
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---:|:---:|---|
+| id | string | 是 | 稳定唯一 ID |
+| name/desc | string | 是 | 显示 |
+| type | string | 是 | `good/bad/neutral` |
+| durationMin | number | 否 | 持续分钟数，空表示永久直到清除 |
+| stack | object | 否 | 堆叠规则（maxStacks/refreshPolicy） |
+| tickIntervalMin | number | 否 | 结算间隔 |
+| effects | Effect[] | 否 | 结算效果（例如每 10 分钟掉理智） |
+| modifiers | object | 否 | 属性修正（命中/速度/消耗倍率） |
+
+## 4.6 配方与科技（Recipe / Tech）
+
+### 4.6.1 配方（Recipe）
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---:|:---:|---|
+| id/name | string | 是 | 标识 |
+| workbenchType | string | 是 | `hand/workshop/forge/cook/filter/med/lab` |
+| requirements | Condition[] | 否 | 条件集合 |
+| inputs | {itemId:string,count:number}[] | 是 | 消耗 |
+| outputs | {itemId:string,count:number,weight?:number}[] | 是 | 产出（可做权重表） |
+| timeCostMin | number | 是 | 耗时 |
+| energyCost | number | 否 | 精力消耗 |
+| sideEffects | Effect[] | 否 | 副作用（辐射、疲劳等） |
+
+### 4.6.2 科技（Tech）
+
+科技节点建议用“解锁能力”表达：
+
+- 解锁配方：`unlockRecipes`
+- 解锁地点服务：`unlockServices`
+- 永久修正：`modifiers`（例如制作耗时倍率 -10%）
+- 前置：`requires`（其他科技、状态阈值、完成任务）
+
+## 4.7 地图与地点（Map / Place）
+
+### 4.7.1 地点 Place
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---:|:---:|---|
+| id/name | string | 是 | 标识 |
+| tags | string[] | 否 | `home/ruins/vault` 等 |
+| dangerLevel | number | 是 | 0–10 |
+| services | string[] | 否 | `trade/rest/craft/heal/info` |
+| resourceNodes | ResourceNode[] | 否 | 可采集资源 |
+| trashNodes | TrashNode[] | 否 | 垃圾池 |
+| encounterTable | EncounterEntry[] | 否 | 遭遇权重表 |
+| eventPools | string[] | 否 | 事件池 ID（通用+地点专属） |
+| questHooks | QuestHook[] | 否 | 任务触发钩子 |
+
+### 4.7.2 路径 Edge
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---:|:---:|---|
+| from/to | string | 是 | 起终点地点 ID |
+| travelTimeMin | number | 是 | 基础耗时 |
+| risk | number | 否 | 途中风险修正（影响遭遇概率） |
+| conditions | Condition[] | 否 | 需要某工具/科技才能通行 |
+
+### 4.7.3 资源节点 ResourceNode
+
+- `id/name`
+- `refreshMin`：刷新/生长间隔
+- `maxStock`：最大存量
+- `growsPerRefresh`：每次生长数量
+- `harvestCost`：时间/精力/工具
+- `outputs`：产出物品权重表
+
+### 4.7.4 垃圾节点 TrashNode
+
+- `refreshMin`
+- `risk`：触发负面事件概率加成
+- `lootTable`：掉落权重表
+
+## 4.8 敌人（Enemy）
+
+### 4.8.1 字段定义
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---:|:---:|---|
+| id/name | string | 是 | 标识 |
+| tags | string[] | 否 | 类别标签 |
+| level | number | 否 | 用于难度缩放 |
+| life | number | 是 | 生命 |
+| attack | {min:number,max:number} | 是 | 攻击 |
+| armor | number | 否 | 护甲 |
+| range | number | 否 | 射程 |
+| hitRate | number | 否 | 命中 |
+| skills | string[] | 否 | 技能 ID 列表 |
+| lootTable | LootEntry[] | 否 | 掉落表 |
+
+## 4.9 事件（Event）
+
+### 4.9.1 字段定义
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---:|:---:|---|
+| id | string | 是 | 事件 ID |
+| tags | string[] | 否 | `combat/story/hazard` 等 |
+| conditions | Condition[] | 否 | 触发条件 |
+| weight | number | 否 | 权重，默认 1 |
+| text | string | 是 | 主文本 |
+| options | Option[] | 否 | 选项列表（0–4） |
+
+Option：
+
+- `text`
+- `conditions`
+- `check`（属性检定配置，可选）
+- `effects`（成功/失败效果链）
+
+## 4.10 任务（Quest）
+
+### 4.10.1 字段定义
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---:|:---:|---|
+| id/title | string | 是 | 标识 |
+| type | string | 是 | `main/side/dynamic` |
+| desc | string | 否 | 描述 |
+| prereq | Condition[] | 否 | 前置条件 |
+| steps | QuestStep[] | 是 | 阶段目标 |
+| rewards | Effect[] | 否 | 完成奖励 |
+| failConditions | Condition[] | 否 | 失败条件（可选） |
+
+QuestStep 支持目标：
+
+- `ReachPlace`
+- `CollectItem`
+- `DefeatEnemy`
+- `CraftRecipe`
+- `TriggerEvent`
+- `SurviveDays`
+
+## 4.11 日志（Log）与可观测性
+
+为了让系统可解释、可测试、可回放：
+
+- 所有关键变化都写日志：
+  - 状态变化（原因、数值）
+  - 战斗结果（命中/伤害/距离）
+  - 事件结果（选项、成功/失败、消耗/获得）
+  - 任务推进（步骤变化）
+- 日志结构化，支持筛选与上报：
+  - `timestamp`
+  - `category`
+  - `message`
+  - `payload`（可选）
+
diff --git a/docs/05-数值与经济.md b/docs/05-数值与经济.md
new file mode 100644
index 0000000..412ffd5
--- /dev/null
+++ b/docs/05-数值与经济.md
@@ -0,0 +1,185 @@
+# 05 数值与经济
+
+本文档定义“可平衡、可解释、可长期扩展”的数值与经济框架。它不追求一次性写死所有数字，而是给出可控的变量、公式、调参旋钮与验收指标。
+
+## 5.1 数值目标
+
+- 让玩家在早期真实感到压力：水/食物/精力是硬约束
+- 让玩家通过发展获得“效率红利”：单位收益成本逐渐下降
+- 让探索推进具备“门槛”：风险等级、补给消耗、科技/工具解锁
+- 让战斗成为“可接受的风险”：收益够好但不会变成主要刷怪玩法
+- 让经济不崩：避免无限刷钱、避免一条路线通吃
+
+## 5.2 资源分类（经济视角）
+
+### 5.2.1 主资源（驱动生存与循环）
+
+- 水（口渴恢复物）：最紧迫的出行约束
+- 食物（饥饿恢复物）：次紧迫，但影响长期效率
+- 精力（行动力）：限制连续行动与战斗强度
+- 时间：最核心的隐性资源（所有收益都必须用时间支付）
+
+### 5.2.2 发展资源（驱动成长）
+
+- 材料：制作与修理的基础
+- 科技点/知识：解锁能力
+- 工具与设施：降低单位成本的关键资产
+
+### 5.2.3 风险资源（负向资产）
+
+- 辐射/污染：长期压力与上限削弱
+- 伤病/感染：持续 debuff，要求治疗成本
+- 装备耐久损耗：把收益的一部分“税收化”
+
+## 5.3 经济闭环（宏观）
+
+```mermaid
+flowchart LR
+  T[时间] --> C1[状态消耗]
+  C1 -->|逼迫补给| S[补给消耗品]
+  T --> A[行动：探索/采集/制作/战斗]
+  A --> R[产出：资源/线索/装备]
+  R --> U[发展：设施/科技/工具]
+  U -->|效率提升| A
+  A -->|风险| D[伤病/辐射/损耗]
+  D -->|治疗/修理| S
+```
+
+对应源文件：[economy-loop.mmd](./diagrams/economy-loop.mmd)
+
+## 5.4 时间成本与状态消耗模型（推荐）
+
+### 5.4.1 基础消耗
+
+定义每分钟消耗：
+
+- `hungerDecayPerMin`
+- `thirstDecayPerMin`
+- `energyDecayPerMin`
+- `sanDecayPerMin`（可选）
+
+基础消耗不是常数，而是受环境/负重/灾害/状态阈值影响：
+
+```
+effectiveDecay = baseDecay
+  * envMultiplier(place, disaster)
+  * burdenMultiplier(carryVolumeRatio)
+  * debuffMultiplier(activeBuffs)
+  * difficultyMultiplier(mode)
+```
+
+### 5.4.2 行为额外消耗
+
+行为额外消耗用于表达“劳动强度差异”：
+
+- 移动：额外精力消耗（与距离/负重相关）
+- 采集：额外精力消耗（与工具等级相关）
+- 制作：额外精力消耗（与工作台类型相关）
+- 战斗：回合动作消耗（与武器类型相关）
+
+### 5.4.3 设计验收指标
+
+- 早期（第 1 天）玩家不做出行，仅靠初始补给应能维持 6–12 小时游戏内时间
+- 早期玩家一次“短途出行”应能带回足以覆盖这次消耗的净收益（否则挫败）
+- 中期玩家应能通过发展把“净收益/小时”提升至少 2–3 倍
+
+## 5.5 风险收益模型（探索/采集）
+
+### 5.5.1 预期收益（Expected Value）
+
+每个地点/行为都应可估算：
+
+```
+EV = Σ (lootValue_i * probability_i) - (timeCost * timeValue) - (riskCost)
+```
+
+其中：
+
+- `lootValue` 不是纯金币，而是按“对生存/发展贡献”折算的价值
+- `timeValue` 可按“口渴最稀缺”的原则折算
+- `riskCost` = 伤病概率 * 伤病价值 + 辐射概率 * 辐射价值 + 战斗概率 * 预计损耗
+
+### 5.5.2 风险提示与 UI
+
+即使底层用 EV 平衡，UI 也不必展示公式，但必须展示：
+
+- 该行动耗时与消耗
+- 风险等级（低/中/高/致命）
+- 可能主要收益（材料类/补给类/装备类/线索类）
+
+## 5.6 战斗数值框架（轻量但可调）
+
+### 5.6.1 核心参数
+
+- 命中率：
+  - 基础命中：`baseHit`
+  - 距离惩罚：`distancePenalty`
+  - 状态修正：饥饿/精力低下惩罚
+  - 装备修正：武器精度、护目镜等
+- 伤害：
+  - `damage = roll(min,max) * (1 + buffs) - armorReduction`
+- 逃跑：
+  - `escapeChance = baseEscape + agilityBonus - enemyThreat + distanceFactor`
+
+### 5.6.2 战斗与资源的耦合
+
+战斗必须消耗资源，否则会变成无限刷怪：
+
+- 弹药消耗（远程）
+- 耐久消耗（近战/护甲）
+- 精力消耗（每回合）
+
+### 5.6.3 战斗奖励约束
+
+- 普通战斗奖励：覆盖本次战斗平均消耗即可（不要过高）
+- 精英/剧情战斗奖励：可提供能力级奖励（关键材料/蓝图/线索）
+
+## 5.7 制作与科技的成本结构
+
+### 5.7.1 成本三角
+
+每个配方应至少消耗其中两项，避免“单一路线通吃”：
+
+- 材料成本
+- 时间成本
+- 风险成本（副作用/辐射/失败概率）
+
+### 5.7.2 科技的收益类型
+
+科技收益按优先级：
+
+1. 解锁能力（新工具、新地点服务、新配方域）
+2. 降低单位成本（时间/材料/损耗）
+3. 提升上限（背包容量、耐久上限、状态上限）
+4. 纯数值提升（尽量少，且必须有对手提升或新风险）
+
+## 5.8 交易与货币体系（可选）
+
+如果引入货币，建议用于“把垃圾变现”与“补给短缺”，而不是让玩家通过买卖取代制作：
+
+- 货币来源：出售垃圾/完成委托/特殊事件
+- 货币去向：购买补给、购买情报、购买修理服务、支付通行费
+- 防刷策略：
+  - 商人资金有限（每日刷新）
+  - 供需轻微动态调价
+  - 稀有物资只卖不收（或收购价极低）
+
+## 5.9 难度与模式
+
+难度不建议简单放大消耗，而是改变“可用策略集合”：
+
+- 休闲：更多提示、较低负面阈值惩罚、更慢消耗
+- 标准：推荐体验
+- 硬核：补给更稀缺、灾害更频繁、战斗逃跑更难，但稀有掉落更好
+
+## 5.10 平衡流程（落地方法）
+
+- 建立“基准路线”：
+  - 新手路线（前 3 天）
+  - 探索路线（推进 3 个核心区域）
+  - 战斗路线（主打狩猎或清剿）
+- 为每条路线定义 KPI：
+  - 存活率、平均净收益/小时、关键科技达成天数
+- 使用可重放种子跑模拟（自动化）：
+  - 抽样 1000 次出行，统计 EV 分布与失败率
+
diff --git a/docs/06-关卡与地图.md b/docs/06-关卡与地图.md
new file mode 100644
index 0000000..30a0bdd
--- /dev/null
+++ b/docs/06-关卡与地图.md
@@ -0,0 +1,179 @@
+# 06 关卡与地图
+
+本文档定义地图结构、地点模板、探索内容生产方法与推进节奏。新项目地图采用“地点图（Graph）+ 地点内内容容器”的方式：世界是可控的、可叙事的，随机性发生在地点内的遭遇与探索过程中。
+
+## 6.1 地图结构：地点图（Graph）
+
+### 6.1.1 核心概念
+
+- 地点（Place）：玩家可停留并进行行为的节点
+- 路径（Edge）：连接地点，定义移动成本与途中风险
+- 区域（Region）：地点集合（例如：地洞区域、村庄周边、森林边缘、避难所外环）
+
+### 6.1.2 地图拓扑建议
+
+- 以基地为中心做“同心层级”：
+  - 第 1 圈：低风险补给点与教学点（1–3 个地点）
+  - 第 2 圈：资源点与第一个交易点（3–6 个地点）
+  - 第 3 圈：高风险废墟与关键剧情点（6–10 个地点）
+  - 第 4 圈：特殊区域（避难所/地铁/污染区）（8–12 个地点）
+- 每圈至少提供 2 条推进路径，避免“唯一最优路线”
+
+```mermaid
+flowchart TB
+  H[基地] --- A[低风险补给点]
+  H --- B[教学废墟]
+  A --- C[村庄/交易点]
+  B --- D[城市废墟]
+  C --- E[森林边缘]
+  D --- F[地铁入口]
+  E --- G[避难所外围]
+  F --- G
+```
+
+对应源文件：[map-topology.mmd](./diagrams/map-topology.mmd)
+
+## 6.2 地点设计模板（内容生产标准）
+
+每个地点必须能回答：
+
+- 这里有什么（资源、信息、威胁）
+- 这里为什么值得来（独特收益或任务）
+- 这里如何与系统交织（状态压力、战斗、制作、交易）
+
+### 6.2.1 必填字段
+
+- 基础信息：
+  - `id/name/desc`
+  - `tags`
+  - `dangerLevel`（0–10）
+- 行为入口（UI 按入口生成按钮）：
+  - `actions`（采集/翻找/休息/交易/制作/调查/潜入等）
+- 内容容器：
+  - `resourceNodes`
+  - `trashNodes`
+  - `eventPools`
+  - `encounterTable`
+  - `questHooks`
+- 规则修正：
+  - `modifiers`（例如该地口渴消耗 *1.2，辐射增长 +0.1/min）
+
+### 6.2.2 地点的“独特性”清单
+
+为了避免地点同质化，每个地点至少具备以下之一：
+
+- 独有资源（仅此地产出或权重显著更高）
+- 独有事件（地点专属事件池）
+- 独有服务（交易品类偏好、修理、情报）
+- 独有敌人（或精英变体）
+- 独有推进（主线/支线关键节点）
+
+## 6.3 移动与途中遭遇
+
+### 6.3.1 移动成本
+
+路径定义：
+
+- `travelTimeMin`：基础耗时
+- `risk`：途中遭遇修正
+- `conditions`：需要的工具/科技/标记
+
+移动时结算：
+
+1. `advanceTime(travelTimeMin)`
+2. 计算途中遭遇概率：`baseEncounterChance * risk * envMultiplier`
+3. 若触发遭遇：从“途中事件池”抽取（战斗/事件/发现）
+
+### 6.3.2 途中遭遇类型（建议比例）
+
+- 事件型（50%）：迷路、发现补给、陷阱、陌生人求助
+- 战斗型（35%）：劫匪、野兽、虫群
+- 奖励型（15%）：短暂机会（坠毁物、遗留车厢）
+
+## 6.4 地点内探索：资源/垃圾/调查
+
+### 6.4.1 三类探索入口
+
+- 资源采集（可预测）
+  - 产出稳定，成本稳定，适合规划
+- 垃圾翻找（高随机）
+  - 产出随机，可能触发风险事件
+- 调查（叙事与线索）
+  - 产出线索/任务进度/地图标记，可能触发剧情战斗
+
+### 6.4.2 探索次数与枯竭
+
+地点应有“可探索度/热度”概念，避免无限刷：
+
+- 每次探索增加 `heat`
+- `heat` 上升会：
+  - 降低资源与垃圾的期望收益
+  - 提高风险事件/敌人概率
+- 回基地或经过一定时间 `heat` 下降
+
+## 6.5 区域推进与门槛（Progression Gates）
+
+推进门槛不建议用“纯等级限制”，优先用“能力门槛”：
+
+- 工具门槛：需要撬棍/手电/防毒面具/滤水器
+- 补给门槛：需要携带足够水（更长路径）
+- 风险门槛：需要抗辐射药或护甲
+- 知识门槛：需要获得线索或完成任务解锁通道
+
+## 6.6 地点内容池与复用
+
+### 6.6.1 事件池分层
+
+- `global`：通用事件（任何地点可发生，按标签过滤）
+- `region`：区域事件（例如森林专属）
+- `place`：地点专属事件（强化独特性）
+- `quest`：任务事件（优先级最高，满足条件必触发或权重极高）
+
+### 6.6.2 敌人表分层
+
+同样分层并允许标签过滤：
+
+- `globalEncounter`
+- `regionEncounter`
+- `placeEncounter`
+- `eliteEncounter`（条件触发）
+
+## 6.7 探索地图（局部随机）（可选）
+
+若引入“探索地图”（类似一次出行的局部迷宫/格子）：
+
+- 世界地图负责“去哪儿”
+- 探索地图负责“怎么搜”
+
+设计要求：
+
+- 生成要可重放（seed）
+- 每张探索地图有：
+  - 入口/出口
+  - 若干资源点/事件点/敌人点
+  - 一个“关键点”（宝箱/线索/小 Boss）
+
+## 6.8 地点清单建议（示例骨架）
+
+建议先做一条可完整游玩的推进链（示例）：
+
+- 基地（Home）
+- 近郊小路（Road）
+- 废弃便利店（Store）
+- 村庄集市（Village Market，交易点）
+- 城市边缘（City Edge）
+- 老地铁口（Subway Entrance）
+- 污染下水道（Sewer）
+- 避难所外围（Vault Outer）
+- 避难所入口（Vault Gate，主线关卡）
+
+## 6.9 关卡验收清单（面向可交付）
+
+- 每个地点有明确独特性（见 6.2.2）
+- 每个地点至少有：
+  - 1 个资源节点或 1 个垃圾节点
+  - 1 个地点专属事件
+  - 1 个可触发的任务钩子（主线或支线）
+- 从基地到第一个交易点的推进，不依赖运气也能完成
+- 至少两条路线可以进入中期区域（避免单路线卡死）
+
diff --git a/docs/07-UX与界面信息架构.md b/docs/07-UX与界面信息架构.md
new file mode 100644
index 0000000..42b49f3
--- /dev/null
+++ b/docs/07-UX与界面信息架构.md
@@ -0,0 +1,156 @@
+# 07 UX 与界面信息架构
+
+本文档面向 UI/UX、客户端与策划，定义信息架构、主要界面、关键交互与可用性约束。该项目的 UI 是“游戏本体”：核心玩法发生在信息读取与决策上，因此 UI 的清晰度与节奏控制优先级极高。
+
+## 7.1 设计目标
+
+- 让玩家在 5 秒内回答三个问题：
+  - 我在哪（地点/时间/风险）
+  - 我现在状态如何（生存状态与主要威胁）
+  - 我下一步能做什么（行动入口与成本）
+- 避免“信息黑箱”：所有关键数值变化必须可追溯原因
+- 支持碎片化：移动端单手可操作，任何时候可暂停/保存
+
+## 7.2 信息架构（IA）
+
+### 7.2.1 顶层导航
+
+推荐采用“主界面一屏 + 抽屉/面板”的结构：
+
+- 常驻区：
+  - 顶部：时间、地点名、风险提示、灾害提示
+  - 左侧/上方：核心状态条（饥饿/口渴/精力/生命/理智/辐射）
+  - 右侧/下方：背包摘要（容量、关键补给数量）
+- 主操作区：
+  - 地点内容（可做的事）
+  - 事件/战斗显示区
+  - 日志/信息提示区
+
+```mermaid
+flowchart TB
+  A[顶部栏：时间/地点/灾害] --> B[状态区：生存状态]
+  B --> C[主操作区：地点动作/事件/战斗]
+  C --> D[信息区：日志/提示/详情]
+  B --> E[背包/仓库面板]
+  C --> F[制作/科技面板]
+  C --> G[任务面板]
+```
+
+对应源文件：[ui-ia.mmd](./diagrams/ui-ia.mmd)
+
+### 7.2.2 主要面板
+
+- 背包面板：
+  - 分类筛选、搜索（可选）
+  - 物品详情（来源/用途/效果/交易价值/耐久）
+  - 一键整理（按类型/价值/用途排序）
+- 制作面板：
+  - 工作台分区（手工/工坊/锻造/烹饪/过滤/医疗/科研）
+  - 配方筛选：可制作/缺材料/缺条件
+  - 成本预览：材料/时间/精力/副作用
+- 任务面板：
+  - 主线/支线/动态任务分组
+  - 当前步骤与下一目标
+  - 任务影响提示（解锁了什么）
+- 地图面板：
+  - 地点图（节点与连接）
+  - 每个地点风险、预估耗时、可用服务
+  - 路线预估：总耗时与补给消耗
+
+## 7.3 关键交互规范
+
+### 7.3.1 “行动按钮”的统一规格
+
+每个行动入口（采集/翻找/移动/制作/休息/治疗）必须在按钮或悬浮层里显示：
+
+- 耗时（分钟）
+- 主要消耗（口渴/精力/耐久/弹药）
+- 风险提示（战斗概率、辐射概率、受伤概率）
+- 产出类型提示（材料/补给/线索）
+
+### 7.3.2 事件交互
+
+事件 UI 结构：
+
+- 文本区：事件描述（支持变量插入，如当前地点名）
+- 选项区：0–4 个选项，置灰不可选并说明原因
+- 结果区：选择后展示结果摘要 + 详细日志入口
+
+可选：对“检定类选项”展示成功率区间或影响因素提示（不必暴露全部公式）。
+
+### 7.3.3 战斗交互
+
+战斗界面必须让玩家看懂：
+
+- 距离与射程关系（可视化条）
+- 当前命中率（或“高/中/低”）
+- 本回合可用行动（攻击/防御/前进/后退/逃跑）
+- 行动成本（弹药/精力/耐久）
+
+战斗日志：
+
+- 每回合输出结构化日志（命中/伤害/减伤/距离变化）
+- 日志可滚动，可复制（用于反馈与 QA）
+
+## 7.4 新手引导（Onboarding）
+
+建议采用“轻量引导 + 任务驱动学习”：
+
+- 第一次打开：
+  - 解释核心状态条与时间推进
+  - 提示“任何行动都有成本”
+- 前 30 分钟的任务链：
+  1. 找水 → 2. 找食物 → 3. 做出第一个工具 → 4. 去交易点 → 5. 解锁第一个科技
+
+引导要求：
+
+- 不使用大量弹窗打断
+- 以任务提示 + 高亮操作入口为主
+
+## 7.5 可用性与无障碍
+
+- 触控目标：最小 44px
+- 颜色对比：状态条颜色与背景满足可读性
+- 文本可缩放：移动端支持字体放大
+- 动效：
+  - 时间加速/进度条需可取消或可暂停
+  - 低性能设备避免大量 DOM 动画
+
+## 7.6 通知与日志策略
+
+### 7.6.1 消息优先级
+
+- P0：死亡/濒死、关键资源耗尽（缺水）、重大剧情选择
+- P1：战斗开始/结束、灾害开始/结束、重要任务推进
+- P2：普通状态阈值变化（饥饿偏低）、制作完成
+- P3：常规资源刷新（仅在详情中可见）
+
+### 7.6.2 信息密度控制
+
+- 主界面只展示“决策需要的信息”
+- 其余信息通过：
+  - 悬浮详情
+  - 日志面板
+  - 事件详情页
+
+## 7.7 多端适配策略
+
+- PC：
+  - 三栏布局（状态/背包/主操作+信息）
+  - 鼠标悬浮展示细节
+- Mobile：
+  - 单栏纵向布局
+  - 背包与详情用抽屉/底部弹层
+  - 长按替代悬浮
+
+## 7.8 界面清单（MVP）
+
+- 主界面（地点 + 行动入口 + 日志）
+- 背包/仓库
+- 制作/科技
+- 地图
+- 任务
+- 战斗
+- 事件详情（可选）
+- 设置（音量/文本速度/难度/存档管理）
+
diff --git a/docs/08-技术架构与代码导读.md b/docs/08-技术架构与代码导读.md
new file mode 100644
index 0000000..a9bcef3
--- /dev/null
+++ b/docs/08-技术架构与代码导读.md
@@ -0,0 +1,185 @@
+# 08 技术架构与代码导读
+
+本文档定义“新项目重制版”的目标技术架构，并说明为何要从旧版的全局脚本结构迁移到现代工程化。该文档同时作为程序端的模块边界约定，避免后期职责混乱与重复实现。
+
+## 8.1 技术目标
+
+- 现代工程化：TypeScript、模块化、自动化测试、CI
+- 数据驱动：内容配置可热更新（至少开发期热更新），线上可增量发布内容包
+- 可重放：随机数与模拟可注入 seed，便于复现与平衡
+- 可观测：结构化日志与埋点，便于 QA/分析
+- 可扩展：系统之间低耦合，内容扩展不引发代码级联改动
+
+## 8.2 总体架构（客户端）
+
+推荐架构分层：
+
+- Presentation（UI 层）：界面渲染与交互
+- Application（应用层）：用例编排（例如“执行一次采集”）
+- Domain（领域层）：规则与模型（状态、战斗、事件、任务、时间推进）
+- Data（数据层）：内容配置加载、存档读写、远端 API
+
+```mermaid
+flowchart TB
+  UI[UI: React/Canvas/纯DOM均可] --> APP[Application: 用例与指令]
+  APP --> DOM[Domain: 规则引擎与模型]
+  DOM --> RNG[RNG: 可注入种子]
+  APP --> DATA[Data: 配置/存档/API]
+  DATA --> CT[Content: 表与包]
+  DATA --> SAV[Save: 本地/云端]
+  DATA --> NET[Net: 后端API]
+```
+
+对应源文件：[architecture-client.mmd](./diagrams/architecture-client.mmd)
+
+## 8.3 关键模块与职责边界
+
+### 8.3.1 Simulation（时间推进）
+
+职责：
+
+- `advanceTime(Δt)`：统一时间推进管线
+- 结算状态消耗、Buff tick、资源刷新、灾害计时
+- 对外暴露“结算结果摘要”用于 UI 提示（不直接操作 UI）
+
+边界：
+
+- 不负责事件抽取（由 EventEngine 负责）
+- 不直接读写存档（由 SaveService 负责）
+
+### 8.3.2 Inventory（背包与容器）
+
+职责：
+
+- 容量计算（体积/堆叠）
+- 移入移出、消耗、掉落
+- 装备槽与耐久更新
+
+边界：
+
+- 不负责“物品效果执行”（由 EffectEngine 执行）
+
+### 8.3.3 EffectEngine（效果执行器）
+
+职责：
+
+- 执行配置化效果链：AddItem、AddStatus、AddBuff、SetFlag、StartCombat 等
+- 保障效果执行顺序与事务性（可选：失败回滚）
+
+边界：
+
+- 不包含具体内容逻辑；内容差异通过配置表达
+
+### 8.3.4 EventEngine（事件引擎）
+
+职责：
+
+- 事件池管理（全局/区域/地点/任务）
+- 条件过滤、权重抽取
+- 选项检定（属性/资源/标记）
+- 返回事件给 UI；结果通过 EffectEngine 执行
+
+### 8.3.5 CombatEngine（战斗引擎）
+
+职责：
+
+- 依据双方数据初始化战斗场景（距离、回合）
+- 执行玩家动作与敌人 AI
+- 输出结构化战斗日志
+
+边界：
+
+- 不直接改变全局状态；通过 EffectEngine 或 CombatResult 由上层应用写回
+
+### 8.3.6 QuestEngine（任务引擎）
+
+职责：
+
+- 任务状态机（NotStarted/Active/Completed）
+- 监听世界事件（到达地点、获得物品、完成战斗等）
+- 驱动任务事件池与奖励发放
+
+### 8.3.7 ContentService（内容服务）
+
+职责：
+
+- 加载基础包与扩展包（版本、依赖、覆盖策略）
+- 提供按 ID 与按标签检索能力
+- 提供校验：唯一性、引用完整性、字段类型、循环依赖检查
+
+## 8.4 数据与配置组织（建议）
+
+### 8.4.1 文件结构建议
+
+- `content/base/*.json`：基础内容
+- `content/packs/<packId>/*.json`：扩展包
+- `content/locales/zh-CN.json`：文本本地化
+- `content/schema/*.json`：JSON Schema（用于校验）
+
+### 8.4.2 依赖与覆盖策略
+
+- 包必须声明：
+  - `packId`
+  - `version`
+  - `dependsOn`（可选）
+  - `overrides`（可选，覆盖的目标与字段）
+- 默认策略：追加；只有明确声明 overrides 才允许覆盖
+
+## 8.5 随机与可重放
+
+### 8.5.1 RNG 注入原则
+
+- 任何概率行为必须来自同一个 RNG 实例（或可追踪的子 RNG）
+- 每次行动生成子种子，保证“局部随机独立、整体可重放”
+
+### 8.5.2 重放数据
+
+为了复现 bug：
+
+- 记录：初始 seed、玩家输入序列（动作与选项）、版本号、内容包版本
+- 可导出一份 replay 文件给 QA
+
+## 8.6 存档体系（概览）
+
+存档应分层：
+
+- `PlayerState`：状态、背包、装备、位置、任务进度
+- `WorldState`：时间、地点资源存量、世界标记、灾害状态
+- `ContentVersion`：内容包版本（用于兼容与迁移）
+
+存档详细见：[09-存档与后端.md](./09-%E5%AD%98%E6%A1%A3%E4%B8%8E%E5%90%8E%E7%AB%AF.md)
+
+## 8.7 旧版 TinyWaste 代码结构速览（用于迁移参考）
+
+旧版项目（当前仓库）具备典型特点：
+
+- 入口由 [loader.js](file:///Users/virtheart/Documents/CloneProjects/TinyWaste/data/loader.js) 动态加载多个 `data/*.min.js`
+- 大量全局变量保存游戏状态（例如 `PLAYER_STATUS/BAG_DATA/MAP_DATA` 等）
+- 时间推进由 [updateSysClock](file:///Users/virtheart/Documents/CloneProjects/TinyWaste/data/lib.js#L460-L510) 驱动，依赖 `setTimeout` 递归
+- 快进逻辑在 [costTimeFunc](file:///Users/virtheart/Documents/CloneProjects/TinyWaste/data/action.js#L587-L682) 内实现，快进过程中暂停计时器
+- 战斗 UI 与逻辑混在一起（见 [battleObj](file:///Users/virtheart/Documents/CloneProjects/TinyWaste/data/action.js#L2486-L2605)）
+
+迁移目标：
+
+- 将“全局状态 + DOM 操作”拆解为“领域模型 + 纯逻辑结算 + UI 渲染”
+- 保留数据驱动思想，但用 Schema 与工具链保障质量
+
+## 8.8 安全与反作弊（基础）
+
+即使是单人游戏，也建议做到：
+
+- 云端存档接口鉴权（token）
+- 存档校验与限流，避免被滥用
+- 客户端不保存敏感密钥
+
+## 8.9 工程化与质量
+
+- TypeScript 全覆盖
+- 单元测试：
+  - 时间推进管线
+  - 事件抽取
+  - 战斗计算
+  - 存档迁移
+- 内容校验：
+  - CI 中运行 Schema 校验与引用完整性检查
+
diff --git a/docs/09-存档与后端.md b/docs/09-存档与后端.md
new file mode 100644
index 0000000..ad17f54
--- /dev/null
+++ b/docs/09-存档与后端.md
@@ -0,0 +1,154 @@
+# 09 存档与后端
+
+本文档定义新项目的存档模型与后端接口。目标：稳定、可迁移、可扩展、可观测。即使是单机为主，也建议提供云端存档能力以支持跨设备与版本兼容。
+
+## 9.1 存档设计目标
+
+- 数据完整：可恢复到任意一个确定状态
+- 可迁移：版本升级可做增量迁移
+- 可校验：避免异常/作弊数据导致崩档
+- 可压缩：存档体积可控，读写快速
+
+## 9.2 存档分层与结构
+
+存档建议由三部分组成：
+
+- `meta`：版本、时间戳、校验、内容包版本
+- `player`：玩家状态与资产
+- `world`：世界状态（时间、地点资源、灾害、标记）
+
+```json
+{
+  "meta": {
+    "saveVersion": 3,
+    "contentVersion": {"base": "1.0.0", "packs": {"event_pack_01": "1.0.0"}},
+    "createdAt": 1730000000000,
+    "updatedAt": 1730001234000,
+    "checksum": "sha256:..."
+  },
+  "player": {
+    "name": "Player",
+    "placeId": "home",
+    "stats": {"life": 80, "hunger": 40, "thirst": 60, "energy": 30, "san": 50, "radiation": 10},
+    "attributes": {"str": 4, "agi": 5, "int": 6, "per": 5, "luck": 3},
+    "inventory": [{"itemId": "water_purified", "count": 2, "durability": null}],
+    "equipment": {"weapon": "knife_01", "body": "jacket_01"},
+    "buffs": [{"buffId": "infection_1", "startedAt": 1730000500000, "stacks": 1}],
+    "quests": {"active": ["q_main_01"], "completed": ["q_tutorial_01"]}
+  },
+  "world": {
+    "time": {"baseTime": 0, "minutesFromStart": 1234},
+    "flags": {"met_trader": true},
+    "places": {
+      "ruins_store": {
+        "heat": 3,
+        "resourceStock": {"water_dirty": 0, "scrap_metal": 2},
+        "lastRefreshAt": 1730001200000
+      }
+    },
+    "disaster": {"activeId": "sandstorm", "endsAt": 1730003000000}
+  }
+}
+```
+
+## 9.3 存档写入策略
+
+- 自动存档触发点（建议）：
+  - 回到基地
+  - 完成任务步骤
+  - 战斗结束
+  - 灾害开始/结束
+  - 重要事件选择后
+- 快速保存：
+  - UI 提供手动保存按钮
+  - 保存期间不阻塞主线程（使用异步/worker）
+- 防止坏档：
+  - 写入采用“双缓冲”：先写临时，再替换正式
+  - 写入失败保留上一份
+
+## 9.4 存档校验与迁移
+
+### 9.4.1 校验（客户端与服务端）
+
+- Schema 校验：字段类型、必填字段、范围
+- 引用校验：itemId/placeId/questId 必须存在于内容库
+- 数值校验：状态上下限、背包容量、堆叠上限
+
+### 9.4.2 迁移（SaveVersion）
+
+- 每次内容/结构变化提升 `saveVersion`
+- 迁移必须是纯函数：`migrate(save_vN) -> save_vN+1`
+- 迁移记录：
+  - 变更点
+  - 默认值策略
+  - 兼容策略（删字段/改名/拆分）
+
+## 9.5 后端能力范围（建议）
+
+后端建议至少提供：
+
+- 账号与鉴权（匿名账号也可）
+- 云端存档 CRUD
+- 内容包版本与更新清单（可选）
+- 运行日志/错误上报（可选）
+
+## 9.6 API 约定（REST 示例）
+
+### 9.6.1 鉴权
+
+- 登录（匿名/设备绑定）：
+  - `POST /api/v1/auth/anonymous`
+  - 返回 `accessToken/refreshToken`
+- 请求头：
+  - `Authorization: Bearer <accessToken>`
+
+### 9.6.2 存档接口
+
+- 列表：
+  - `GET /api/v1/saves`
+- 读取：
+  - `GET /api/v1/saves/{slotId}`
+- 写入（覆盖）：
+  - `PUT /api/v1/saves/{slotId}`
+  - Body：完整存档 JSON
+  - 服务端校验通过后写入
+- 删除：
+  - `DELETE /api/v1/saves/{slotId}`
+
+### 9.6.3 并发与冲突
+
+使用乐观锁：
+
+- 存档 meta 带 `etag` 或 `rev`
+- 更新时带 `If-Match: <etag>`
+- 冲突返回 409，客户端提示“本地与云端不一致”
+
+## 9.7 速率限制与滥用防护
+
+- 写入频率限制：例如每分钟最多 10 次
+- 存档大小限制：例如 1MB
+- 结构化错误码，避免泄漏服务端信息
+
+## 9.8 旧版 PHP 存档参考（当前仓库）
+
+当前仓库包含简单的 PHP+MySQL 存档端点：
+
+- [save.php](file:///Users/virtheart/Documents/CloneProjects/TinyWaste/save.php)：按 `key/data/overwrite` 写入 `record(key,data)`，并校验 `data` 是 JSON
+- [load.php](file:///Users/virtheart/Documents/CloneProjects/TinyWaste/load.php)：按 `key` 读取
+
+新项目不建议继续沿用 SAE 环境变量模式与弱协议，建议升级为标准鉴权、版本控制与迁移机制。
+
+```mermaid
+sequenceDiagram
+  participant C as Client
+  participant API as Save API
+  participant DB as Database
+  C->>API: PUT /saves/{slotId} (save, If-Match)
+  API->>API: 校验Schema/引用/数值
+  API->>DB: 写入(事务)
+  DB-->>API: ok
+  API-->>C: 200 (new etag)
+```
+
+对应源文件：[save-flow.mmd](./diagrams/save-flow.mmd)
+
diff --git a/docs/10-本地运行与发布.md b/docs/10-本地运行与发布.md
new file mode 100644
index 0000000..0f1c45f
--- /dev/null
+++ b/docs/10-本地运行与发布.md
@@ -0,0 +1,87 @@
+# 10 本地运行与发布
+
+本文档定义新项目的本地开发、构建、发布与环境管理规范。目标：让任何新同学在最短步骤内跑起来、可调试、可测试、可发布。
+
+## 10.1 环境与工具链（建议）
+
+- Node.js：LTS
+- 包管理：pnpm（或 npm/yarn 任选其一，但全项目统一）
+- 语言：TypeScript
+- 代码规范：ESLint + Prettier（统一格式）
+- 测试：Vitest/Jest（单元），Playwright（端到端，可选）
+
+## 10.2 运行模式
+
+### 10.2.1 开发模式
+
+- 本地开发服务器
+- 支持热更新（UI 与内容配置）
+- 支持注入调试指令：
+  - 跳时间
+  - 生成物品
+  - 强制触发事件
+  - 固定随机种子
+
+### 10.2.2 生产模式
+
+- 静态资源构建输出（CDN 可部署）
+- API 指向正式后端
+- Debug 功能默认关闭（需权限或环境开关）
+
+## 10.3 配置管理
+
+推荐三层配置：
+
+- `default`：默认配置（安全值）
+- `env`：按环境覆盖（dev/staging/prod）
+- `runtime`：运行时下发（如内容包更新列表）
+
+必须遵循：
+
+- 配置不写死在代码里，使用环境变量/配置文件
+- 任何密钥不得进入仓库
+
+## 10.4 内容包发布流程（建议）
+
+内容包与代码版本解耦：
+
+1. 内容策划提交内容包（JSON + 校验通过）
+2. CI 跑 Schema 校验、引用检查、权重表检查
+3. 内容包发布到 CDN/对象存储
+4. 后端返回最新内容包清单与版本号
+5. 客户端启动时拉取并缓存（可按需更新）
+
+## 10.5 发布策略
+
+### 10.5.1 版本号约定
+
+- 客户端版本：SemVer
+- 内容包版本：SemVer
+- 存档版本：整数递增 `saveVersion`
+
+### 10.5.2 回滚策略
+
+- 客户端回滚：CDN 指向上一个构建
+- 内容包回滚：清单回滚到上一版本
+- 存档兼容：
+  - 向前兼容：旧存档可迁移到新版本
+  - 向后兼容：新存档回滚到旧版本通常不可行，需提示
+
+## 10.6 监控与日志（建议）
+
+- 客户端错误上报：
+  - JS 异常
+  - 资源加载失败
+  - 存档校验失败
+- 关键事件埋点：
+  - 新手完成率
+  - 出行次数/死亡原因
+  - 关键科技解锁天数
+  - 任务链完成率
+
+## 10.7 旧版仓库运行注意（仅用于参考）
+
+当前仓库是静态网页 + AJAX 动态加载脚本，且在 [loader.js](file:///Users/virtheart/Documents/CloneProjects/TinyWaste/data/loader.js#L15-L23) 有域名跳转逻辑，本地直接打开可能会跳转到线上域名。旧版本地跑需要静态服务器并绕过域名限制。
+
+新项目不会延续这种加载方式，会采用现代构建输出与模块化加载。
+
diff --git a/docs/11-QA测试用例与验收清单.md b/docs/11-QA测试用例与验收清单.md
new file mode 100644
index 0000000..44a8600
--- /dev/null
+++ b/docs/11-QA测试用例与验收清单.md
@@ -0,0 +1,155 @@
+# 11 QA 测试用例与验收清单
+
+本文档面向 QA 与开发，覆盖核心链路的测试用例、回归点与验收清单。该项目是系统驱动游戏，测试重点是“时间推进与状态结算一致性”“配置驱动内容正确性”“随机可重放”。
+
+## 11.1 测试范围
+
+- 核心循环：基地→准备→移动→探索/事件→战斗→回收→发展
+- 系统：时间推进、状态、Buff、资源刷新、制作、事件、战斗、任务、灾害、交易、存档
+- 非功能：性能、可用性、异常恢复、兼容性（PC/Mobile）
+
+## 11.2 通用测试要求
+
+- 随机可重放：
+  - 每个测试用例记录 seed
+  - 复现 bug 必须能通过 replay 或 seed+操作序列重放
+- 日志可观测：
+  - 每次状态变化、事件结果、战斗结算都可在日志中看到结构化信息
+- 配置校验：
+  - 引用完整性（itemId/placeId/eventId）
+  - 权重表合法（权重>0、总权重合理、不会空抽）
+  - 条件表达式合法（不会运行时报错）
+
+## 11.3 Smoke（冒烟）用例（每次发布必测）
+
+### 11.3.1 启动与基础交互
+
+- 启动进入主界面，显示时间/地点/状态条/行动入口
+- 打开背包与详情，无崩溃
+- 打开地图与任务面板，无崩溃
+- 暂停/继续功能正常
+
+### 11.3.2 核心循环可闭环
+
+- 从基地移动到一个邻近地点
+- 执行一次采集或翻找，时间推进与状态消耗正确
+- 触发一次事件并选择选项，结果生效
+- 回基地，自动存档触发
+
+## 11.4 系统测试用例（详细）
+
+### 11.4.1 时间推进管线
+
+- 用例：执行 `advanceTime(10min)`
+  - 期望：饥饿/口渴/精力按配置曲线变化
+  - 期望：Buff tick 按 interval 结算
+  - 期望：资源节点按刷新规则增长且不超过上限
+  - 期望：灾害倒计时/持续时间正确更新
+
+边界：
+
+- Δt = 0（不应产生变化）
+- 超大 Δt（例如 24h）仍应按相同规则分段/累计结算，避免溢出
+
+### 11.4.2 状态阈值与 Buff
+
+- 触发阈值（例如口渴<阈值）应自动添加 debuff
+- 从阈值恢复应自动移除 debuff
+- Buff 堆叠规则：
+  - 刷新时长 vs 增加层数
+  - 到期移除是否正确
+
+### 11.4.3 背包与容量
+
+- 堆叠上限：超过上限应拆分或拒绝
+- 容量上限：超过容量应拒绝拾取或强制丢弃（按设计）
+- 装备槽互斥：同槽位只能装备一件
+- 耐久为 0：装备失效逻辑正确
+
+### 11.4.4 制作与科技
+
+- 缺材料：按钮置灰并提示缺少项
+- 缺条件：提示缺科技/缺设施/缺工具
+- 制作完成：
+  - 扣除输入
+  - 增加产出
+  - 推进时间与消耗正确
+- 科技解锁：
+  - 新配方可见
+  - 新地点服务解锁
+  - 永久修正生效
+
+### 11.4.5 事件系统
+
+- 事件抽取：
+  - 事件池为空时降级到全局池或给出提示（按设计）
+  - 条件过滤正确
+  - 权重抽取符合统计（抽样 1000 次）
+- 选项：
+  - 不满足条件应置灰并说明原因
+  - 检定成功/失败结果正确执行
+- 效果链：
+  - 顺序正确（先扣资源后给奖励等）
+  - 任一效果失败时的处理符合设计（允许部分成功或事务回滚）
+
+### 11.4.6 战斗系统
+
+- 初始化：
+  - 双方属性正确
+  - 距离与射程正确
+- 回合动作：
+  - 攻击：命中率受距离/状态影响
+  - 防御：降低被命中或降低伤害
+  - 前进/后退：距离变化正确
+  - 逃跑：概率正确，逃跑后果正确（掉落/受伤/时间损失）
+- 结束：
+  - 胜利掉落正确
+  - 失败进入死亡/失败流程
+  - 战斗日志完整可读
+
+### 11.4.7 任务系统
+
+- 任务触发：满足条件应进入 Active
+- 任务步骤推进：到达地点/交付物品/击败敌人等正确推进
+- 完成奖励：效果链正确执行
+- 失败（如有）：失败条件触发后状态正确
+
+### 11.4.8 灾害系统
+
+- 预警期提示与倒计时正确
+- 爆发期规则改变正确（消耗倍率、遭遇权重、资源刷新）
+- 结束后恢复默认规则
+- 灾害与事件/任务交互不冲突（优先级一致）
+
+### 11.4.9 存档
+
+- 自动存档触发点：回基地/战斗结束/重要事件后
+- 快速保存：不阻塞主线程，保存成功提示
+- 读档：
+  - 所有状态恢复一致
+  - 地点资源存量一致
+  - 任务进度一致
+  - 内容版本不一致时提示并迁移
+
+## 11.5 兼容性测试
+
+- PC：
+  - Chrome/Edge/Safari（macOS）
+- Mobile：
+  - iOS Safari
+  - Android Chrome
+
+## 11.6 性能与稳定性
+
+- 长时间运行（模拟 3 小时游戏内循环）不出现内存持续增长
+- 连续时间加速不出现卡死
+- 大背包（200+物品条目）滚动与操作流畅
+
+## 11.7 发布验收清单（Gate）
+
+- 核心循环可闭环（可从基地出发并持续发展）
+- 主要系统无阻塞性 bug（卡死/坏档/无法推进）
+- 内容校验全通过（Schema + 引用）
+- 随机可重放（seed + 操作序列可复现）
+- 关键数据埋点与错误上报可用（如项目需要）
+
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..cb486e3
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,31 @@
+# TinyWaste（新项目重制版）文档目录
+
+本目录是基于 TinyWaste 核心体验进行“全新重做”的项目级文档集合，面向策划、程序、美术、QA、运营等不同角色，目标是：
+
+- 让团队对产品方向、系统边界、数据结构、技术架构形成一致认知
+- 让内容生产与迭代具备可规模化的规范与流程
+- 让后续实现与测试有明确验收标准
+
+## 阅读顺序
+
+- 先读：[01-游戏总览.md](./01-%E6%B8%B8%E6%88%8F%E6%80%BB%E8%A7%88.md)
+- 再读：[02-GDD-游戏设计总文档.md](./02-GDD-%E6%B8%B8%E6%88%8F%E8%AE%BE%E8%AE%A1%E6%80%BB%E6%96%87%E6%A1%A3.md)
+- 然后按职责选择：
+  - 系统与内容：[03-系统设计.md](./03-%E7%B3%BB%E7%BB%9F%E8%AE%BE%E8%AE%A1.md)、[04-内容与数据字典.md](./04-%E5%86%85%E5%AE%B9%E4%B8%8E%E6%95%B0%E6%8D%AE%E5%AD%97%E5%85%B8.md)、[06-关卡与地图.md](./06-%E5%85%B3%E5%8D%A1%E4%B8%8E%E5%9C%B0%E5%9B%BE.md)
+  - 数值平衡：[05-数值与经济.md](./05-%E6%95%B0%E5%80%BC%E4%B8%8E%E7%BB%8F%E6%B5%8E.md)
+  - 交互与界面：[07-UX%E4%B8%8E%E7%95%8C%E9%9D%A2%E4%BF%A1%E6%81%AF%E6%9E%B6%E6%9E%84.md](./07-UX%E4%B8%8E%E7%95%8C%E9%9D%A2%E4%BF%A1%E6%81%AF%E6%9E%B6%E6%9E%84.md)
+  - 技术实现：[08-技术架构与代码导读.md](./08-%E6%8A%80%E6%9C%AF%E6%9E%B6%E6%9E%84%E4%B8%8E%E4%BB%A3%E7%A0%81%E5%AF%BC%E8%AF%BB.md)、[09-存档与后端.md](./09-%E5%AD%98%E6%A1%A3%E4%B8%8E%E5%90%8E%E7%AB%AF.md)、[10-本地运行与发布.md](./10-%E6%9C%AC%E5%9C%B0%E8%BF%90%E8%A1%8C%E4%B8%8E%E5%8F%91%E5%B8%83.md)
+  - 测试与验收：[11-QA%E6%B5%8B%E8%AF%95%E7%94%A8%E4%BE%8B%E4%B8%8E%E9%AA%8C%E6%94%B6%E6%B8%85%E5%8D%95.md](./11-QA%E6%B5%8B%E8%AF%95%E7%94%A8%E4%BE%8B%E4%B8%8E%E9%AA%8C%E6%94%B6%E6%B8%85%E5%8D%95.md)
+
+## 图与源文件
+
+- 所有文档中的图均使用 Mermaid 绘制。
+- 每张图的 Mermaid 源文件会同步保存在 [diagrams/](./diagrams/) 目录下，便于复用与再加工。
+
+## 术语表（简版）
+
+- 生存状态：影响玩家行动与存活概率的连续数值（饥饿、口渴、精力、理智、辐射等）。
+- 时间推进：游戏内时间前进触发状态消耗、资源生长、事件刷新等。
+- 风险收益：一次出行/探索的收益（资源/信息）与风险（伤害/污染/时间消耗）之间的平衡。
+- 数据驱动：绝大多数内容由配置定义，代码仅提供通用规则与执行器。
+
diff --git a/docs/diagrams/architecture-client.mmd b/docs/diagrams/architecture-client.mmd
new file mode 100644
index 0000000..e63cf44
--- /dev/null
+++ b/docs/diagrams/architecture-client.mmd
@@ -0,0 +1,8 @@
+flowchart TB
+  UI[UI: React/Canvas/纯DOM均可] --> APP[Application: 用例与指令]
+  APP --> DOM[Domain: 规则引擎与模型]
+  DOM --> RNG[RNG: 可注入种子]
+  APP --> DATA[Data: 配置/存档/API]
+  DATA --> CT[Content: 表与包]
+  DATA --> SAV[Save: 本地/云端]
+  DATA --> NET[Net: 后端API]
diff --git a/docs/diagrams/architecture-core-loop.mmd b/docs/diagrams/architecture-core-loop.mmd
new file mode 100644
index 0000000..0071824
--- /dev/null
+++ b/docs/diagrams/architecture-core-loop.mmd
@@ -0,0 +1,19 @@
+sequenceDiagram
+  participant P as 玩家
+  participant UI as 客户端UI
+  participant SIM as Simulation(时间/状态)
+  participant CT as Content(配置与表)
+  participant EVT as Event(事件引擎)
+  participant CMB as Combat(战斗引擎)
+  participant SAV as Save(存档)
+
+  P->>UI: 选择地点/动作
+  UI->>SIM: 请求推进时间(Δt)
+  SIM->>CT: 读取状态消耗/刷新规则
+  SIM->>EVT: 抽取事件(按地点/权重/条件)
+  EVT-->>UI: 返回事件(文本/选项/结果预览)
+  alt 触发战斗
+    UI->>CMB: 初始化战斗(玩家/敌人/距离/武器)
+    CMB-->>UI: 回合结果/日志
+  end
+  UI->>SAV: 自动存档/快速保存
diff --git a/docs/diagrams/combat-state.mmd b/docs/diagrams/combat-state.mmd
new file mode 100644
index 0000000..611da70
--- /dev/null
+++ b/docs/diagrams/combat-state.mmd
@@ -0,0 +1,14 @@
+stateDiagram-v2
+  [*] --> Init
+  Init --> PlayerTurn
+  PlayerTurn --> Resolve
+  Resolve --> EnemyTurn
+  EnemyTurn --> Resolve
+  Resolve --> CheckEnd
+  CheckEnd --> PlayerTurn: 未结束
+  CheckEnd --> Escape: 逃跑成功
+  CheckEnd --> Win: 敌人死亡
+  CheckEnd --> Lose: 玩家死亡/崩溃
+  Escape --> [*]
+  Win --> [*]
+  Lose --> [*]
diff --git a/docs/diagrams/core-loop.mmd b/docs/diagrams/core-loop.mmd
new file mode 100644
index 0000000..513bcf9
--- /dev/null
+++ b/docs/diagrams/core-loop.mmd
@@ -0,0 +1,11 @@
+flowchart LR
+  A[基地：整理与制作] --> B[准备：补给与装备]
+  B --> C[出行：移动到地点]
+  C --> D[探索：资源/事件/任务]
+  D --> E{遭遇？}
+  E -->|战斗| F[战斗与消耗]
+  E -->|非战斗事件| G[选择与结果]
+  F --> H[回收：战利品/伤病/污染]
+  G --> H
+  H --> I[发展：科技/工具/基地能力]
+  I --> A
diff --git a/docs/diagrams/economy-loop.mmd b/docs/diagrams/economy-loop.mmd
new file mode 100644
index 0000000..4ac5afe
--- /dev/null
+++ b/docs/diagrams/economy-loop.mmd
@@ -0,0 +1,9 @@
+flowchart LR
+  T[时间] --> C1[状态消耗]
+  C1 -->|逼迫补给| S[补给消耗品]
+  T --> A[行动：探索/采集/制作/战斗]
+  A --> R[产出：资源/线索/装备]
+  R --> U[发展：设施/科技/工具]
+  U -->|效率提升| A
+  A -->|风险| D[伤病/辐射/损耗]
+  D -->|治疗/修理| S
diff --git a/docs/diagrams/map-topology.mmd b/docs/diagrams/map-topology.mmd
new file mode 100644
index 0000000..8ca25c5
--- /dev/null
+++ b/docs/diagrams/map-topology.mmd
@@ -0,0 +1,9 @@
+flowchart TB
+  H[基地] --- A[低风险补给点]
+  H --- B[教学废墟]
+  A --- C[村庄/交易点]
+  B --- D[城市废墟]
+  C --- E[森林边缘]
+  D --- F[地铁入口]
+  E --- G[避难所外围]
+  F --- G
diff --git a/docs/diagrams/save-flow.mmd b/docs/diagrams/save-flow.mmd
new file mode 100644
index 0000000..4a708d4
--- /dev/null
+++ b/docs/diagrams/save-flow.mmd
@@ -0,0 +1,9 @@
+sequenceDiagram
+  participant C as Client
+  participant API as Save API
+  participant DB as Database
+  C->>API: PUT /saves/{slotId} (save, If-Match)
+  API->>API: 校验Schema/引用/数值
+  API->>DB: 写入(事务)
+  DB-->>API: ok
+  API-->>C: 200 (new etag)
diff --git a/docs/diagrams/time-pipeline.mmd b/docs/diagrams/time-pipeline.mmd
new file mode 100644
index 0000000..c50a20a
--- /dev/null
+++ b/docs/diagrams/time-pipeline.mmd
@@ -0,0 +1,8 @@
+flowchart TD
+  A[advanceTime Δt] --> B[状态消耗]
+  B --> C[Buff结算]
+  C --> D[资源生长]
+  D --> E[遭遇/敌人刷新]
+  E --> F[灾害结算]
+  F --> G[任务/事件检查]
+  G --> H[日志与提示]
diff --git a/docs/diagrams/ui-ia.mmd b/docs/diagrams/ui-ia.mmd
new file mode 100644
index 0000000..3f569a3
--- /dev/null
+++ b/docs/diagrams/ui-ia.mmd
@@ -0,0 +1,7 @@
+flowchart TB
+  A[顶部栏：时间/地点/灾害] --> B[状态区：生存状态]
+  B --> C[主操作区：地点动作/事件/战斗]
+  C --> D[信息区：日志/提示/详情]
+  B --> E[背包/仓库面板]
+  C --> F[制作/科技面板]
+  C --> G[任务面板]