Echo/Assets/_Project/Docs/TaskSystem_Technical_Reference.md

TaskSystem 技术参考

本文档定义并说明项目内的“任务系统（TaskSystem）”以及它如何驱动任务面板 UI（TaskPanel）。

相关脚本：

• Assets/_Project/Scripts/Core/TaskSystem/TaskService.cs
• Assets/_Project/Scripts/Core/TaskSystem/TaskData.cs
• Assets/_Project/Scripts/UI/Tasks/TaskPanelController.cs
• Assets/_Project/Scripts/UI/Tasks/TaskListItemView.cs

相关 UI 搭建与布局参考：

• Assets/_Project/Docs/TaskSystem_UI_Setup.md

1. 设计目标

• 任务数据与 UI 解耦：代码不硬编码层级路径，通过 Inspector 槽位绑定 UI。
• 列表项可做成 Prefab：运行时动态实例化到 ScrollView Content。
• 任务状态可被外部系统调用修改：支持添加、移除、状态切换（待做/完成/超时）。
• 超时逻辑由任务系统统一处理：当任务设置了超时时间，自动切换为“超时”状态。

2. 数据模型

2.1 TaskData（任务静态数据）

文件：TaskData.cs

• 类型：ScriptableObject
• 字段：
  • id：任务 ID（全局唯一）
  • shortName：短任务名（列表显示）
  • description：任务描述（详情显示）

用途：

• 设计人员可以在 Project 里创建多个 TaskData 资源，作为“任务定义库”。

2.2 TaskEntry（任务运行时状态）

文件：TaskEntry.cs

• 运行时由 TaskService 创建与维护
• 字段：
  • id / data
  • status：Todo | Completed | Expired
  • addedAt：加入时间（秒）
  • expiresAt：过期时间（秒，0 表示不超时）
  • scheduledRemoveAt：计划移除时间（秒，0 表示不自动移除）

3. 任务状态与规则

状态枚举：TaskStatus（TaskStatus.cs）

• Todo：待做
• Completed：完成
• Expired：超时

规则（当前版本由系统统一规定）：

• 添加任务默认状态为 Todo
• 当任务设置了 timeoutSeconds > 0：
  • 到达 expiresAt 后，系统会自动将状态改为 Expired
• 任务移除策略：
  • 默认不自动移除（autoRemove...AfterSeconds < 0）
  • 可在 TaskService Inspector 中设置：
    • autoRemoveCompletedAfterSeconds
    • autoRemoveExpiredAfterSeconds
  • 当状态切为 Completed/Expired 时，会按配置自动排期移除

时间基准：

• TaskService.useUnscaledTime = true 时，使用 Time.unscaledTime
• false 时，使用 Time.time

4. TaskService（系统 API）

文件：TaskService.cs

4.1 调用方式

• 推荐：在外部脚本中通过 Inspector 挂引用（Slot）调用
• 可选：使用单例 TaskService.Instance（前提是场景里存在一个 TaskService）

4.2 公开 API（最常用）

• 添加（若已存在则失败）：
  • bool AddTask(TaskData data, float timeoutSeconds = -1f)
• 添加或更新（若已存在则更新 data，并可选重置状态）：
  • TaskEntry AddOrUpdateTask(TaskData data, float timeoutSeconds = -1f, bool resetStatusToTodo = false)
• 移除：
  • bool RemoveTask(string taskId)
• 改状态：
  • bool SetTaskStatus(string taskId, TaskStatus status)
• 查询：
  • bool TryGetTask(string taskId, out TaskEntry task)
  • IReadOnlyList<TaskEntry> Tasks

4.3 事件（用于驱动 UI）

• Changed：任意任务列表/任务内容变化都会触发
• 细粒度事件（可按需订阅）：
  • TaskAdded
  • TaskUpdated
  • TaskRemoved
  • TaskStatusChanged

5. UI 对接（TaskPanel）

5.1 TaskPanelController（面板控制器）

文件：TaskPanelController.cs

它做的事情：

• 监听 TaskService.Changed，重建列表
• 实例化 taskItemPrefab 到 listContent
• 点击列表项时，更新右侧详情文本（titleText/detailText）

Inspector 需要绑定的槽位：

• taskService：场景里的 TaskService
• listContent：Scroll View 的 Viewport/Content
• taskItemPrefab：任务按钮 Prefab（带 TaskListItemView）
• detailText：右侧详情 TMP
• titleText：可选（右侧标题 TMP）

5.2 TaskListItemView（列表项视图）

文件：TaskListItemView.cs

它做的事情：

• 通过 Reach 的 ButtonManager.SetText() 设置按钮文本
• 按任务状态设置按钮的 Icon 与颜色（待做/完成/超时）
• 将按钮 onClick 绑定为“通知 TaskPanelController 选中该任务”

Inspector 需要绑定的槽位：

• button：Reach 的 ButtonManager（可不填，会在 Awake 尝试自动从同物体 GetComponent）
• todoIcon/completedIcon/expiredIcon：三种状态的 Icon（Sprite）

6. 编辑器搭建步骤（从 0 到能跑）

目标场景：

• Assets/_Project/Scenes/Test/UI_Test.unity

6.1 创建 TaskData 资产

1. Project 里新建文件夹（建议）：Assets/_Project/Data/Tasks
2. 右键 -> Create -> TaskSystem -> Task Data
3. 填写：
   • id（例如：task_open_door）
   • shortName（例如：打开仓库门）
   • description（例如：去工具间找到钥匙，然后打开仓库门。）

6.2 制作任务列表项 Prefab（按钮）

1. 在 UI_Test 场景里，选中你当前用于测试的任务按钮（例如 BtnTaskPrefab）
2. 确认该按钮上存在 Reach 的 ButtonManager 组件
3. Add Component：TaskListItemView
4. （可选但推荐）Add Component：Layout Element，设置 Preferred Height（例如 56/64），让列表项高度稳定
5. 将该按钮拖拽到 Project 生成 Prefab（建议放：Assets/_Project/Prefabs/UI/Tasks/TaskListItem.prefab）

6.3 在场景中加入 TaskService

1. Hierarchy 新建空物体：TaskSystem
2. Add Component：Core.TaskSystem.TaskService
3. 配置（可选）：
   • Dont Destroy On Load：是否跨场景保留
   • Auto Remove Completed/Expired After Seconds：是否自动移除

6.4 绑定 TaskPanelController

1. 在 UI_Test 场景中选中 TaskPanelRoot（或你认为最合适的面板根）
2. Add Component：UI.Tasks.TaskPanelController
3. 依次绑定槽位：
   • Task Service -> TaskSystem(TaskService)
   • List Content -> Left_TaskList/Scroll View/Viewport/Content
   • Task Item Prefab -> 第 6.2 步创建的 Prefab
   • Detail Text -> Right_TaskDetails/DetailText
   • Title Text ->（可选）右侧标题 TMP

6.5 （可选）使用 TaskBootstrap 快速验证 UI

1. 在 TaskSystem 物体上 Add Component：Core.TaskSystem.TaskBootstrap
2. Tasks To Add 列表中拖入若干 TaskData
3. （可选）设置 Timeout Seconds，观察任务在超时后自动变为“超时”

7. 外部系统如何调用（示例）

示例：当玩家触发某个交互后，完成任务：

• 在你的交互脚本里持有一个 TaskService 引用（Inspector 槽位）
• 调用：
  • taskService.SetTaskStatus(taskId, TaskStatus.Completed);

示例：添加一个限时任务：

• taskService.AddTask(taskData, timeoutSeconds: 60f);