chore: initial commit

2026-05-08 11:04:00 +08:00
commit f55d2a57c3
6278 changed files with 866081 additions and 0 deletions
--- a/Docs/DesignSpec/12_EconomySystem.md
+++ b/Docs/DesignSpec/12_EconomySystem.md
@@ -0,0 +1,165 @@
+# 12 · 经济系统规范
+
+> **所属文档集** [← 返回索引](./README.md)  
+> **摘要**：Geo 货币体系、商店系统、掉落经济平衡与消费循环设计。
+
+---
+
+## 目录
+
+1. [经济设计原则](#1-经济设计原则)
+2. [Geo 货币体系](#2-geo-货币体系)
+3. [商店系统](#3-商店系统)
+4. [物品数据模型](#4-物品数据模型)
+5. [经济平衡参数](#5-经济平衡参数)
+6. [经济事件目录](#6-经济事件目录)
+
+---
+
+## 1. 经济设计原则
+
+| 原则 | 说明 |
+|------|------|
+| **单一货币** | 只有 Geo，避免多货币系统带来的混乱 |
+| **死亡有意义** | 遗骸机制使 Geo 有风险感，强化决策权重 |
+| **非强制消费** | 所有商店物品为锦上添花，不买也能通关 |
+| **价格成长** | 后期物品价格随区域进程递增 |
+
+---
+
+## 2. Geo 货币体系
+
+### 2.1 Geo 获取来源
+
+| 来源 | 数量范围 | 说明 |
+|------|---------|------|
+| 击杀普通敌人 | 1-15 | 随敌人等级变化 |
+| 击杀精英怪 | 20-60 | |
+| 击杀 Boss | 100-500 | |
+| 拾取 GeoCache 收集品 | 固定值 | 地图中隐藏的 Geo 堆 |
+| 出售物品 | 物品定价 50% | 部分物品可出售 |
+| 完成 NPC 任务 | 任务奖励 | |
+
+### 2.2 Geo 消耗途径
+
+| 途径 | 数量范围 | 说明 |
+|------|---------|------|
+| 商店购买护符 | 100-1200 | 主要消耗 |
+| 商店购买消耗品 | 20-200 | |
+| Notch 扩展 | 递增（150/300/500...）| 扩展护符槽位 |
+| 门控通行费 | 固定值 | 某些区域收费通道 |
+| NPC 服务 | 固定值 | 特殊 NPC 的服务费 |
+
+### 2.3 Geo 上限
+
+| 规则 | 说明 |
+|------|------|
+| 携带上限 | 无上限（设计上不设置）|
+| 遗骸上限 | 携带量全部转为遗骸 |
+| 显示格式 | 整数，无小数点 |
+
+---
+
+## 3. 商店系统
+
+### 3.1 商店数据模型
+
+```
+DataModel ShopData {
+    shopId          : ID
+    shopkeeperNpcId : ID                  // 关联 NPC
+    ──────────────────────────────────
+    inventory       : List<ShopItemEntry>
+    refreshCondition: Optional<RefreshCondition>  // 何时刷新库存
+    welcomeText     : String
+}
+
+DataModel ShopItemEntry {
+    itemId          : Ref<ItemData>
+    basePrice       : Integer
+    stock           : Optional<Integer>   // null = 无限库存
+    availableCondition: Optional<GateCondition>  // 解锁条件（null=始终可购）
+    discountFlags   : Optional<Flags<DiscountSource>>  // 折扣来源
+}
+```
+
+### 3.2 购买流程
+
+```
+玩家在商店 UI 选择物品并确认购买:
+  → 检查玩家 Geo >= itemPrice
+  ├─ 不足 → 显示"Geo 不足"提示，取消
+  └─ 足够 →
+      → 扣除 playerGeo -= itemPrice
+      → 将物品加入玩家库存（或直接应用效果）
+      → 若有 stock，stock -= 1
+      → stock == 0 时，从列表中移除该项
+      → 发出 OnShopPurchase 事件
+```
+
+---
+
+## 4. 物品数据模型
+
+```
+DataModel ItemData {
+    itemId          : ID
+    displayName     : String
+    description     : String
+    ──────────────────────────────────
+    itemType        : ItemType            // 护符/消耗品/关键道具/图鉴
+    stackable       : Boolean
+    maxStack        : Optional<Integer>   // null = 无限叠加
+    ──────────────────────────────────
+    useEffect       : Optional<Ref<UseEffectData>> // 使用效果（消耗品）
+    sellValue       : Optional<Integer>   // null = 不可出售
+}
+```
+
+### 4.1 物品类型
+
+| 类型 | 说明 | 叠加 |
+|------|------|------|
+| `Charm` | 护符，装备型 | 不叠加（每种只有 1 个）|
+| `Consumable` | 消耗品，使用即激活效果 | 叠加，最多 9 个/槽 |
+| `KeyItem` | 关键道具，推进剧情/开门 | 不叠加 |
+| `LoreItem` | 世界观物品，加入图鉴 | 不叠加 |
+| `Map` | 区域地图碎片 | 不叠加 |
+
+---
+
+## 5. 经济平衡参数
+
+### 5.1 区域 Geo 密度（参考）
+
+| 游戏阶段 | 单次刷怪平均 Geo | 护符平均价格 |
+|---------|---------------|------------|
+| 早期区域（1-2 区）| 5-20 | 100-300 |
+| 中期区域（3-4 区）| 15-50 | 400-700 |
+| 后期区域（5+ 区）| 40-120 | 800-1200 |
+
+> **平衡原则**：购买一件中期护符约需清扫 2-3 个房间的敌人，不应过长也不应过短。
+
+### 5.2 Notch 扩展价格表
+
+| 第 N 次扩展 | 价格（Geo）|
+|-----------|-----------|
+| 1 | 150 |
+| 2 | 300 |
+| 3 | 500 |
+| 4 | 800 |
+| 5 | 1200 |
+| 6+ | 递增 500/次 |
+
+---
+
+## 6. 经济事件目录
+
+| 事件 | 触发时机 | 载荷 |
+|------|---------|------|
+| `OnGeoChanged` | Geo 数量变化 | `delta: Integer, newTotal: Integer` |
+| `OnShopOpened` | 打开商店 | `shopId` |
+| `OnShopPurchase` | 完成购买 | `shopId, itemId, price` |
+| `OnItemAcquired` | 获得任何物品 | `itemId, source` |
+| `OnItemUsed` | 使用消耗品 | `itemId` |
+| `OnNotchExpanded` | 扩展护符槽 | `newNotchCount, geoCost` |