# 28 · 商店系统

> **命名空间** `BaseGames.World.Shop`  
> **所属文档集** [← 返回索引](./README.md) · [总览](./00_Overview.md)  
> **依赖** `BaseGames.Core.Events` · `BaseGames.Dialogue`（IInteractable）· `BaseGames.UI` · `BaseGames.Player`（PlayerStats）

---

## 目录

1. [系统总览](#1-系统总览)
2. [ShopItemSO — 商品数据](#2-shopitemso--商品数据)
3. [ShopInventorySO — 商店库存](#3-shopinventoryso--商店库存)
4. [价格规则](#4-价格规则)
5. [补货时机](#5-补货时机)
6. [ShopController — 运行时逻辑](#6-shopcontroller--运行时逻辑)
7. [商店 UI（ShopPanel）](#7-商店-uishoppanel)
8. [IInteractable 集成](#8-iinteractable-集成)
9. [SaveData 集成](#9-savedata-集成)
10. [事件频道](#10-事件频道)
11. [编辑器友好设计](#11-编辑器友好设计)

---

## 1. 系统总览

```
商店系统职责:
  ├─ ShopItemSO         → 商品数据 SO（名称、图标、价格、效果）
  ├─ ShopInventorySO    → 商店库存 SO（商品列表、最大货位数、补货策略）
  ├─ ShopController     → 运行时逻辑（购买校验、Geo 扣减、库存更新）
  ├─ ShopPanel          → UI 面板（商品格、预览、购买确认）
  └─ ShopNPC            → IInteractable 实现，触发商店打开
```

**零耦合原则**：`ShopController` 通过 SO 事件频道发布 `OnItemPurchased`，不直接调用 `PlayerStats.AddGeo()`；`PlayerStats` 监听并自行扣减。

---

## 2. ShopItemSO — 商品数据

```csharp
[CreateAssetMenu(menuName = "World/Shop/ShopItem")]
public class ShopItemSO : ScriptableObject
{
    [Header("基础信息")]
    public string   itemId;           // 全局唯一 ID，如 "Item_HealthPotion_Small"
    public string   displayName;      // 显示名称（本地化 key）
    [TextArea(2, 5)]
    public string   description;      // 描述文本

    [Header("外观")]
    public Sprite   icon;             // 商品图标

    [Header("价格")]
    public int      basePrice;        // 基础价格（Geo）
    public bool     isUnique;         // 是否唯一购买（购买后从库存移除且不补货）

    [Header("商品类型")]
    public ShopItemType itemType;     // HealthRestoration / CharmItem / KeyItem / ConsumableBuff

    [Header("效果（根据类型填写）")]
    public int      healthRestoreAmount;   // itemType = HealthRestoration 时
    public CharmSO  charmReference;        // itemType = CharmItem 时（引用 CharmSO）
    public string   keyItemId;             // itemType = KeyItem 时（唯一 ID）

    [Header("限购")]
    public int      maxPurchaseCount;  // -1 = 无限购买；> 0 = 限购次数
}

public enum ShopItemType
{
    HealthRestoration,  // 恢复 HP
    CharmItem,          // 魅力（装备系统）
    KeyItem,            // 关键物品（触发 OnCollectiblePickedUp 事件）
    ConsumableBuff,     // 临时增益（如攻击力提升 30s）
    MapFragment,        // 地图碎片（扩展地图显示区域）
}
```

**资产存放路径**：`Assets/ScriptableObjects/Shop/Items/`  
**命名规范**：`Item_{Category}_{Name}.asset`

---

## 3. ShopInventorySO — 商店库存

```csharp
[CreateAssetMenu(menuName = "World/Shop/ShopInventory")]
public class ShopInventorySO : ScriptableObject
{
    [Header("商店信息")]
    public string       shopId;           // 全局唯一 ID，如 "Shop_Forest_Merchant"
    public string       shopkeeperName;   // 商人名称（用于对话）
    public Sprite       shopkeeperPortrait; // 头像

    [Header("库存配置")]
    [Tooltip("商店默认库存（所有可售商品）")]
    public List<ShopItemSO> defaultInventory;

    [Tooltip("最大同时陈列货位（-1 = 无限制，显示全部）")]
    public int          maxDisplaySlots = -1;

    [Header("补货策略")]
    public RestockPolicy restockPolicy;   // 见 §5

    [Tooltip("存档点补货：每次激活存档点后重置已售出的可补货商品")]
    public bool         restockOnSavePoint = true;

    [Tooltip("仅补货一次性消耗品，唯一商品（isUnique）永不补货")]
    public bool         neverRestockUnique = true;
}

public enum RestockPolicy
{
    Never,           // 售出即消失，不补货（稀有魅力/关键物品商店）
    OnSavePoint,     // 每次激活存档点后补货（默认商人）
    OnBossDefeat,    // 击败当前区域 Boss 后一次性补货
    Periodic,        // 按真实时间补货（如每 24 小时，依赖 SaveData 时间戳）
}
```

**资产存放路径**：`Assets/ScriptableObjects/Shop/`  
**命名规范**：`Shop_{Region}_{Name}.asset`

---

## 4. 价格规则

### 基础价格表（参考）

| 商品类型 | 价格范围 | 示例 |
|---------|---------|------|
| 小型 HP 回复（1 HP）| 50–80 Geo | 蜂蜜球 |
| 大型 HP 回复（全量）| 200–350 Geo | 生命果 |
| 魅力（1 Notch）| 120–180 Geo | 快速斩 |
| 魅力（2 Notch）| 200–280 Geo | 强化冲刺 |
| 魅力（3 Notch）| 350–480 Geo | 毒刺 |
| 地图碎片（区域）| 150–200 Geo | 森林区地图 |
| 关键物品 | 策划自定 | 铁门钥匙 |

### 折扣机制（可选，P2）

```csharp
// ShopController 中可选折扣计算
public int GetActualPrice(ShopItemSO item)
{
    float discount = _discountCharmEquipped ? 0.8f : 1.0f; // 护符折扣示例
    return Mathf.RoundToInt(item.basePrice * discount);
}
```

---

## 5. 补货时机

### OnSavePoint 补货流程

```
玩家激活存档点
  │
  ▼
OnSavePointActivated 事件频道（VoidEventChannelSO）
  │
  ▼
ShopController.OnSavePointActivated()
  │
  ├─ 遍历所有已售出的可补货商品（!isUnique && maxPurchaseCount == -1）
  └─ 将其从 _soldItems 集合中移除（标记为"重新可购买"）
```

### OnBossDefeat 补货流程

```
OnBossDefeated 事件频道（StringEventChannelSO，payload = bossId）
  │
  ▼
ShopController.OnBossDefeated(string bossId)
  │
  └─ 若 _inventory.restockPolicy == OnBossDefeat：执行补货
```

---

## 6. ShopController — 运行时逻辑

```csharp
namespace BaseGames.World.Shop
{
    public class ShopController : MonoBehaviour
    {
        // ── 配置 ─────────────────────────────────────────────────
        [SerializeField] ShopInventorySO       _inventory;
        [SerializeField] VoidEventChannelSO    _onSavePointActivated;
        [SerializeField] StringEventChannelSO  _onBossDefeated;
        [SerializeField] IntEventChannelSO     _onPlayerGeoChanged;    // 监听 Geo 变化
        [SerializeField] ShopTransactionEvent  _onItemPurchased;       // 发布购买事件

        // ── 运行时状态 ─────────────────────────────────────────────
        HashSet<string> _soldUniqueItems = new();          // 唯一已购商品 ID
        Dictionary<string, int> _purchaseCount = new();   // 各商品购买次数

        int _playerGeo; // 从 PlayerStats 同步

        void OnEnable()
        {
            _onSavePointActivated.OnEventRaised += HandleSavePoint;
            _onBossDefeated.OnEventRaised       += HandleBossDefeated;
            _onPlayerGeoChanged.OnEventRaised   += geo => _playerGeo = geo;
        }

        void OnDisable()
        {
            _onSavePointActivated.OnEventRaised -= HandleSavePoint;
            _onBossDefeated.OnEventRaised       -= HandleBossDefeated;
            _onPlayerGeoChanged.OnEventRaised   -= geo => _playerGeo = geo;
        }

        /// <summary>尝试购买商品。成功返回 true，失败返回 false + 失败原因。</summary>
        public bool TryPurchase(ShopItemSO item, out ShopPurchaseResult result)
        {
            // 1. Geo 是否足够
            int price = GetActualPrice(item);
            if (_playerGeo < price)
            {
                result = ShopPurchaseResult.InsufficientGeo;
                return false;
            }
            // 2. 是否已售罄（唯一商品）
            if (item.isUnique && _soldUniqueItems.Contains(item.itemId))
            {
                result = ShopPurchaseResult.SoldOut;
                return false;
            }
            // 3. 是否超出限购次数
            if (item.maxPurchaseCount > 0)
            {
                _purchaseCount.TryGetValue(item.itemId, out int count);
                if (count >= item.maxPurchaseCount)
                {
                    result = ShopPurchaseResult.PurchaseLimitReached;
                    return false;
                }
            }
            // 4. 执行购买
            _purchaseCount[item.itemId] = _purchaseCount.GetValueOrDefault(item.itemId) + 1;
            if (item.isUnique) _soldUniqueItems.Add(item.itemId);
            _onItemPurchased.Raise(new ShopTransaction { Item = item, GeoSpent = price });
            result = ShopPurchaseResult.Success;
            return true;
        }

        public int GetActualPrice(ShopItemSO item) => item.basePrice; // 可扩展折扣逻辑

        public bool IsAvailable(ShopItemSO item)
        {
            if (item.isUnique && _soldUniqueItems.Contains(item.itemId)) return false;
            if (item.maxPurchaseCount > 0)
            {
                _purchaseCount.TryGetValue(item.itemId, out int c);
                return c < item.maxPurchaseCount;
            }
            return true;
        }

        public IReadOnlyList<ShopItemSO> GetDisplayInventory()
        {
            // 过滤不可购买商品，按 maxDisplaySlots 截取
            var available = _inventory.defaultInventory
                .Where(IsAvailable)
                .ToList(); // 此处 LINQ 仅在 UI 打开时调用，非热路径
            if (_inventory.maxDisplaySlots > 0 && available.Count > _inventory.maxDisplaySlots)
                return available.Take(_inventory.maxDisplaySlots).ToList();
            return available;
        }

        void HandleSavePoint()
        {
            if (_inventory.restockPolicy == RestockPolicy.OnSavePoint)
                Restock();
        }

        void HandleBossDefeated(string _)
        {
            if (_inventory.restockPolicy == RestockPolicy.OnBossDefeat)
                Restock();
        }

        void Restock()
        {
            // 移除非唯一商品的购买记录，使其重新可购
            var keysToRemove = _purchaseCount.Keys
                .Where(id =>
                {
                    var item = _inventory.defaultInventory.Find(i => i.itemId == id);
                    return item != null && !item.isUnique;
                })
                .ToList();
            foreach (var key in keysToRemove)
                _purchaseCount.Remove(key);
        }
    }

    public enum ShopPurchaseResult { Success, InsufficientGeo, SoldOut, PurchaseLimitReached }

    public struct ShopTransaction
    {
        public ShopItemSO Item;
        public int        GeoSpent;
    }
}
```

### ShopTransactionEvent 频道

```csharp
// ShopTransaction 事件频道（自定义类型频道）
[CreateAssetMenu(menuName = "Events/ShopTransactionEvent")]
public class ShopTransactionEvent : BaseEventChannel<ShopTransaction> { }
```

---

## 7. 商店 UI（ShopPanel）

### 面板结构（UXML）

```
ShopPanel
├── ShopHeader
│   ├── ShopkeeperPortrait
│   └── ShopkeeperName
├── ItemGrid (ScrollView)
│   └── ShopItemCell × N
│       ├── ItemIcon
│       ├── ItemName
│       └── PriceLabel（含 GeoIcon）
├── ItemPreviewPanel
│   ├── PreviewIcon (large)
│   ├── PreviewName
│   ├── PreviewDescription
│   ├── PriceTag
│   └── BuyButton
└── PlayerGeoDisplay
    ├── GeoIcon
    └── GeoAmount
```

### ShopPanel.cs（UI 逻辑）

```csharp
namespace BaseGames.World.Shop
{
    public class ShopPanel : MonoBehaviour
    {
        [SerializeField] ShopController _controller;

        UIDocument    _doc;
        VisualElement _itemGrid;
        Label         _geoLabel;
        ShopItemSO    _selectedItem;

        void OnEnable()
        {
            _doc      = GetComponent<UIDocument>();
            _itemGrid = _doc.rootVisualElement.Q("ItemGrid");
            _geoLabel = _doc.rootVisualElement.Q<Label>("GeoAmount");

            _doc.rootVisualElement.Q<Button>("BuyButton").clicked += OnBuyClicked;
            Refresh();
        }

        public void Refresh()
        {
            _itemGrid.Clear();
            foreach (var item in _controller.GetDisplayInventory())
            {
                var cell = CreateItemCell(item);
                _itemGrid.Add(cell);
            }
        }

        VisualElement CreateItemCell(ShopItemSO item)
        {
            var cell = new VisualElement();
            cell.AddToClassList("shop-item-cell");
            // icon, name, price
            var icon  = new Image { image = item.icon.texture };
            var name  = new Label(item.displayName);
            var price = new Label($"{_controller.GetActualPrice(item)} Geo");
            cell.Add(icon); cell.Add(name); cell.Add(price);
            cell.RegisterCallback<ClickEvent>(_ => SelectItem(item));
            if (!_controller.IsAvailable(item))
                cell.AddToClassList("sold-out");
            return cell;
        }

        void SelectItem(ShopItemSO item)
        {
            _selectedItem = item;
            var root = _doc.rootVisualElement;
            root.Q<Image>("PreviewIcon").image        = item.icon.texture;
            root.Q<Label>("PreviewName").text         = item.displayName;
            root.Q<Label>("PreviewDescription").text  = item.description;
            root.Q<Label>("PriceTag").text            = $"{_controller.GetActualPrice(item)} Geo";
        }

        void OnBuyClicked()
        {
            if (_selectedItem == null) return;
            bool ok = _controller.TryPurchase(_selectedItem, out var result);
            if (!ok)
            {
                // 显示失败原因（Geo 不足 / 已售罄）
                Debug.Log($"购买失败: {result}");
                return;
            }
            Refresh();
            SelectItem(_selectedItem); // 刷新预览（可能变为 Sold Out）
        }
    }
}
```

---

## 8. IInteractable 集成

`ShopNPC` 实现 `IInteractable`，玩家交互后打开商店面板：

```csharp
namespace BaseGames.World.Shop
{
    public class ShopNPC : MonoBehaviour, IInteractable
    {
        [SerializeField] ShopController   _shopController;
        [SerializeField] VoidEventChannelSO _onShopOpened;
        [SerializeField] VoidEventChannelSO _onShopClosed;

        // IInteractable
        public bool CanInteract => true;  // 商人始终可交互

        public void Interact(Transform player)
        {
            _onShopOpened.Raise();        // UIManager 监听并显示 ShopPanel
        }

        public void OnPlayerEnterRange(Transform player) { /* 显示交互提示 */ }
        public void OnPlayerExitRange()                  { /* 隐藏交互提示 */ }
    }
}
```

### 商店打开/关闭流程

```
玩家按 [F] 交互
  │
  ▼
ShopNPC.Interact()
  └─ OnShopOpened.Raise()
  │
  ▼
UIManager 监听 OnShopOpened
  └─ ShopPanel.gameObject.SetActive(true)
  └─ InputReaderSO.EnableUIInput()       // 切换到 UI Action Map
  │
  ▼
玩家关闭商店
  └─ OnShopClosed.Raise()
  └─ InputReaderSO.EnableGameplayInput()
```

---

## 9. SaveData 集成

商店状态需持久化，确保重启游戏后唯一商品不会"复活"：

### SaveData 商店字段

```json
"shops": {
  "Shop_Forest_Merchant": {
    "soldUniqueItems": ["Item_Charm_QuickSlash", "Item_MapFragment_Forest"],
    "purchaseCounts": {
      "Item_HealthPotion_Small": 3,
      "Item_HealthPotion_Large": 1
    }
  }
}
```

### 读/写接口

```csharp
// ShopController
public ShopSaveData GetSaveData() => new ShopSaveData
{
    SoldUniqueItems = _soldUniqueItems.ToList(),
    PurchaseCounts  = new Dictionary<string, int>(_purchaseCount),
};

public void LoadSaveData(ShopSaveData data)
{
    _soldUniqueItems = new HashSet<string>(data.SoldUniqueItems);
    _purchaseCount   = new Dictionary<string, int>(data.PurchaseCounts);
}
```

> `ShopSaveData` 存储在 `SaveData.shops` 字典中，键为 `ShopInventorySO.shopId`。

---

## 10. 事件频道

| 频道 | 类型 | 说明 |
|------|------|------|
| `OnShopOpened.asset` | `VoidEventChannelSO` | 商店打开（UIManager 监听）|
| `OnShopClosed.asset` | `VoidEventChannelSO` | 商店关闭 |
| `OnItemPurchased.asset` | `ShopTransactionEvent` | 商品购买成功（PlayerStats 监听，扣 Geo + 应用效果）|

**`PlayerStats` 监听 `OnItemPurchased` 并执行效果**：

```csharp
// PlayerStats.OnEnable()
_onItemPurchased.OnEventRaised += ApplyShopItem;

void ApplyShopItem(ShopTransaction tx)
{
    AddGeo(-tx.GeoSpent);                    // 扣 Geo
    switch (tx.Item.itemType)
    {
        case ShopItemType.HealthRestoration:
            Heal(tx.Item.healthRestoreAmount);
            break;
        case ShopItemType.CharmItem:
            // EquipmentManager 也监听此事件，自动添加到背包
            break;
        case ShopItemType.KeyItem:
            _onCollectiblePickedUp.Raise(tx.Item.keyItemId);
            break;
    }
}
```

---

## 11. 编辑器友好设计

### ShopInventorySO 自定义 Inspector

```csharp
[CustomEditor(typeof(ShopInventorySO))]
public class ShopInventorySOEditor : Editor
{
    public override VisualElement CreateInspectorGUI()
    {
        var root = new VisualElement();
        InspectorElement.FillDefaultInspector(root, serializedObject, this);

        // 库存统计
        var stats = new Foldout { text = "库存统计" };
        var inv = (ShopInventorySO)target;
        stats.Add(new Label($"商品总数: {inv.defaultInventory.Count}"));
        stats.Add(new Label($"唯一商品: {inv.defaultInventory.Count(i => i != null && i.isUnique)}"));
        stats.Add(new Label($"价格范围: {(inv.defaultInventory.Where(i=>i!=null).Select(i=>i.basePrice).DefaultIfEmpty(0).Min())} ~ " +
                            $"{(inv.defaultInventory.Where(i=>i!=null).Select(i=>i.basePrice).DefaultIfEmpty(0).Max())} Geo"));
        root.Add(stats);
        return root;
    }
}
```