orbit/docs/examples/task-query.md

业务键与时间范围查询示例

源码：task-query/main.go。本例提交三个模拟对象任务，不启动Worker，演示精确业务键、创建时间区间和任务摘要分页。

准备与运行

按SDK初始化步骤迁移数据库、初始化专用开发队列及普通提交/读取/取消凭据，启动当前Orbit服务。从仓库根目录执行：

cd examples
ORBIT_URL=http://127.0.0.1:8080 \
  ORBIT_CREDENTIALS_FILE=../.local/development.credentials.json \
  go run ./task-query

也可使用ORBIT_TOKEN与ORBIT_QUEUE_ID，环境值优先。无需额外管理权限，凭据秘密不输出。队列应有至少三个未终结任务空位；每次运行的处理器与业务键带独立标识，避免已有任务干扰。

实际调用与结果

1. 使用不同提交身份创建两个完全相同业务键、format分别为text/json的任务，以及一个业务键只相差尾部空格的任务。业务键含中文、加号、百分号及重音字符。读取前两个任务确认各自输入保留，改参数没有覆盖原任务。
2. 用服务端回执中的CreatedAt设置包含起点、不包含终点的时间范围，避免依赖客户端时钟同步。
3. ListTasks按原键、WAITING状态和创建区间查询，每页1条，沿NextCursor遍历；仅匹配前两个任务。
4. 将created_before设为第二个任务的精确创建时间，确认它被排除，只剩第一个任务。
5. 分别取消本例三个任务，保留任务、受理与取消审计。

预期输出：

matched=2 pages=2 before_excluded=true original_payload_preserved=true cancelled=3

重复运行创建新的独立样本。代码没有外部业务副作用，也不删除数据库历史。失败非零退出，可能留下已受理任务；用回执、业务键和时间范围查询后核对，各任务总时限60秒，当前示例没有Worker会进入未开始超时处理。

本例通过business_key关联不同参数的任务，不表示覆盖、自动取消或自动代替原工作，来源仍为DIRECT。需要重新执行原冻结参数时使用带证据的人工重试；不能用新任务身份绕过未知业务效果核查。

完整参数、游标兼容和异常说明见查询契约。翻页时保持所有筛选，发生INVALID_ARGUMENT不要丢弃过滤条件“兜底查全部”。状态变化的跨页结果不是快照，不能当作完整审计导出。

make integration 会在一次性MySQL中运行此示例及实际HTTP SDK回归，验证原键/尾部空格、时间边界、分页、变更条件拒绝，以及取消后创建时间不改变。