实现两级存档系统（注册表式数据收集）并接入游戏时间

doc/SaveSystem.md

@@ -0,0 +1,139 @@
+# 存档系统（SaveSystem）使用说明
+
+Autoload 单例，路径 `res://src/Core/SaveSystem.gd`，已在 `project.godot` 注册。
+
+## 架构
+
+两级存档：
+
+```
+存档组 SaveGroup（一次轮回/一个角色）          profiles.json 中一条记录
+  └── 存档槽 SaveSlot（进度快照）              user://saves/profile_{组id}/slot_{时间戳}.json
+```
+
+- 每个"新游戏"创建一个组，组 id 由 SaveSystem 分配（1、2、3…）
+- 每次 `save()` 在组下**新建**一个槽，槽与组数量无上限
+- 存档文件为 JSON，含 `version`、`date`、`data` 三段，`data` 为各系统数据合并后的字典
+
+## 核心接口
+
+| 接口 | 说明 |
+| --- | --- |
+| `create_profile() -> int` | 新建存档组，返回组 id。主菜单"新游戏"调用 |
+| `get_profiles() -> Array[Dictionary]` | 组列表，每条含 `id / name / created / last_date` |
+| `save(profile_id, data = {}) -> String` | 保存游戏，返回槽文件名。`data` 缺省时自动收集各系统数据 |
+| `load(profile_id, slot_name) -> Dictionary` | 读取槽位数据，槽不存在或版本高于当前返回 `{}` |
+| `list_slots(profile_id) -> Array[Dictionary]` | 组下槽列表（`name / date`），最新在前 |
+| `delete_slot(profile_id, slot_name)` | 删除槽位 |
+| `register_saver(callable) -> void` | 注册数据提供者（见下） |
+| `collect_data() -> Dictionary` | 手动收集所有注册系统的数据 |
+
+## 各系统如何接入存档
+
+新增需要存档的系统只需两步，**无需改动 SaveSystem**：
+
+```gdscript
+# 例：SectSystem.gd
+extends Node
+
+func _ready() -> void:
+	SaveSystem.register_saver(_to_save_dict)
+
+## 提供存档数据，返回字典，key 用系统名避免冲突
+func _to_save_dict() -> Dictionary:
+	return {
+		"sect": {
+			"name": sect_name,
+			"resources": resources,
+			"members": members,
+		},
+	}
+
+## 读档时恢复（由 MainGame 在 load 后按 key 分发调用）
+func load_from_dict(d: Dictionary) -> void:
+	if not d.has("sect"):
+		return
+	var sect: Dictionary = d["sect"]
+	sect_name = sect.get("name", "")
+	...
+```
+
+约定：
+- 每个系统实现 `_to_save_dict()`（提供数据）和 `load_from_dict()`（恢复状态）
+- key 用系统名（如 `"sect"`），避免系统间冲突
+- 读档用 `d.get(key, {})` / `.get(field, 默认值)` 容错，保证旧档兼容
+- 只把**游戏内数据**放进去；会话参数（当前 mode、profile_id 等）由 GameState 管理，不落档
+
+### 示例：GameState 保存游戏时间
+
+GameState 是 Autoload（持久对象），在其 `_ready` 中注册：
+
+```gdscript
+# GameState.gd
+extends Node
+
+var year: int = 1
+var month: int = 1
+
+func _ready() -> void:
+	SaveSystem.register_saver(_to_save_dict)
+
+## 提供存档数据：key 为 "game_time"，值是游戏时间字段
+func _to_save_dict() -> Dictionary:
+	return {
+		"game_time": {
+			"year": year,
+			"month": month,
+		},
+	}
+
+## 读档恢复（MainGame 在 load 后调用 GameState.load_from_dict(data)）
+func load_from_dict(d: Dictionary) -> void:
+	var t: Dictionary = d.get("game_time", {})
+	year = int(t.get("year", 1))
+	month = int(t.get("month", 1))
+```
+
+存档后 JSON 中的形态：
+
+```json
+"game_time": { "year": 12, "month": 7 }
+```
+
+要点：
+- `register_saver` 只接收无参 Callable，方法名直接传，**不要**写成 `register_saver(_to_save_dict())`（那是调用而不是注册）
+- `year`/`month` 读档用 `get()` 带默认值，旧存档没有该字段时也能启动
+
+## 存档与读档流程
+
+### 存档（回合结算 / 月度结算 / 关窗前）
+
+```gdscript
+# TimeSystem 月度结算处
+var slot := SaveSystem.save(GameState.profile_id)
+print("已保存：%s" % slot)
+```
+
+### 读档（主菜单进入游戏）
+
+```gdscript
+# MainGame 场景启动时
+var data := SaveSystem.load(GameState.profile_id, GameState.save_slot)
+if data.is_empty():
+	push_error("存档读取失败")
+	return
+# 按 key 分发给各系统恢复
+SectSystem.load_from_dict(data)
+...
+
+# 主菜单：列出组和槽供选择
+var profiles := SaveSystem.get_profiles()
+var slots := SaveSystem.list_slots(pid)   # 选中某组后
+GameState.request_load_game(pid, slot["name"])
+```
+
+## 存档时机建议（回合制）
+
+- **每月结算时**自动 `save()` 一次，覆盖当前组新建槽
+- **关窗前**（`NOTIFICATION_WM_CLOSE_REQUEST`）补存一次，避免丢失当月操作
+- 不需要手动存档 UI；如担心槽无限增长，可加"保留最近 N 槽"的清理逻辑