# 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 校验与引用完整性检查