新手礼包

## 做什么

给玩家提供一个**起始特性「良心商人」**。
选了这个特性后，**第 1、7、14、21……天（每 7 天）**会有一位商人上门：

- **第一次来访**：送一个储藏箱（直接放柜台上）＋ 打进 100 现金
- **后续来访**：只当买家，每次以高于普通收购价收购你出手的物品
---
## 特性效果

| 项目 | 说明 |
|---|---|
| 首次来访 | 送 1 个储藏箱（白送）＋ 100 现金 |
| 后续来访 | 每 7 天一次，只当买家，不再送礼 |
| 收购范围 | 全游戏 + 所有已装 Mod 的物品（自动枚举） |
| 收购价加成 | 默认 +15%（可在 cfg 调） |
| 杂项买家 | 每种物品只收 1 件（可在 cfg 关） |
| 顾客预算 | 15 × (10 + 游戏天数)，随天数增长 |
| 不可逮捕 | 商人不能被玩家逮捕或开枪 |
| 违禁品收购 | 违禁值只按 50% 计算（详情见下文） |

---
## 基本玩法

### 第一次来访

第1天开门后，商人会排在顾客队列里（下一位客人）。他上门时会：
1. 把储物箱直接放到你柜台上（默认「白送」，归你所有）
2. 向你的账户存入100现金
3. 弹出屏幕通知：`良心商人把储藏箱放上了柜台`
**注意**：首访商人只有你**真正接待**（进对话）才算完成。如果第 1 天你直接跳过或没进店，**第 7 天他会继续以「首访」身份来**，直到你正式接待过一次为止。

### 后续来访

每 7 天（第 7、14、21……天）商人会来一次，只当买家，不再送礼。

---

## 违禁品机制
当玩家把违禁品卖给**其他顾客**时，游戏会按「违禁等级 + 物品价值」记一笔违禁值。
同样的物品卖给**良心商人**时，这笔违禁值只按 **50%** 计算。
- 普通顾客不受影响，仍按 100% 计算
- 日志里会出现：`良心商人违禁值修正: N -> M（50%）`
---

## 配置项

在 `UserData/MelonPreferences.cfg` 的 `[良心商人]` 段：

| 配置项 | 默认 | 说明 |
|---|---|---|
| `Enabled` | 开 | 总开关 |
| `FreeGift` | 开 | true = 白送；false = 要花钱买 |
| `DirectToInventory` | 关 | 跳过顾客，直接把箱子塞进仓库（排障用） |
| `VarietyBuy` | 开 | 每种物品只收 1 件 |
| `BuyPriceBonus` | 15 | 比普通收购价多 15% |
| `Language` | zh | 语言（zh / en，需重启生效） |

⚠️ 从 1.4.x 升级的用户，配置不会自动迁移，请重设一次。
---
## 硬编码参数（不可调）

| 项 | 值 |
|---|---|
| 判定为「第一天」的天数 | 1 |
| 首次来访赠送的现金 | 100 |
| 送来的储藏箱 ID | storage_bay |
| 来访间隔 | 每 7 天 |
| 顾客预算 | 15 × (10 + 游戏天数) |
| 违禁值百分比 | 50 |
---

## 注意事项

### 必须在新档开局勾选特性

只有**新建存档时勾选「良心商人」起始特性**才会生效。

老存档（已经开档很久的）中途加装 mod 是**不会**触发的。已激活后可以在「状态」面板看到特性图标和描述。

### 每个存档独立
所有状态（首访日、上次来访日、已派送日、礼金是否已发）**按存档槽隔离**。切换存档不会互相污染。

首次访问可以跳过，但会持续派遣
第 1 天商人到访时：
- **接待** → 领箱子 + 100 现金，转「回头客」状态
**跳过**（不进对话／直接过夜） → 第 7 天他会继续以「首访」身份来
直到你正式接待过一次，才会转「回头客」。

### 崩档不补偿

`NewbieGift` 存档是**即时落盘**的，与游戏存档（跨日才写）不完全同步。
- 如果你在 Day 1 商人流程中途 Alt+F4，重进游戏回到 Day 1 开局
游戏里的箱子、现金会丢，但 mod 存档已经记录「首访完成」
- **模组不会重新补发**首访礼品
这是已知行为，请知悉。

### 与玩家自建储物箱区分
mod 送出的箱子会打一个内部 tag（`NEWBIE_GIFT_DELIVERED`），用来和玩家自己造的储藏箱区分。
- 你自己摆的 storage_bay **不会**影响 mod 的派发逻辑
商人照常来、照常送礼
---

## 兼容性

与以下 mod 无冲突：
- **NotEnoughItems / ProbablyStolenItemManager**：它们添加的物品会自动进入良心商人的收购范围
- **自定义仓库（SaveBagExpand）**：扩容、分页逻辑互不干扰
- **更多设备升级 / 自定义容器升级**：仅读取物品目录，不修改任何容器或网格
- **XIAOWO 系列 / 钓鱼 / 酿酒 / 料理**：所有新物品自动被纳入收购范围
---

## 排障

### 商人没上门？
按顺序检查：

1. **特性没选？** 新档开局时有没有勾选「良心商人」起始特性
2. **是不是拜访日？** 只在第 1、7、14、21……天触发
3. **当天已来过？** 同一天不会重复来访
4. **存档槽冲突？** 每个存档独立判定，切换存档后请重新开门
### 查看日志

游戏目录下 `MelonLoader/Latest.log` 搜索 `[良心商人]`：
[良心商人] 运行时枚举共 N 个物品 ID（目录 29 成功 / 0 失败）
[良心商人] 良心商人收货 ID 已装填：N 个
[良心商人] 第 N 天，【首次访问】良心商人已派出（预算 N）
[良心商人] 已上架到柜台: storage_bay（白送，tag=NEWBIE_GIFT_DELIVERED）
[良心商人] 违禁值修正: N -> M（50%）
文本

- 前 4 行对应派送流程各阶段
- 第5行仅在玩家向良心商人出售违禁品时出现
- 如果一行都没有，说明特性未激活或被判定挡住