Timer 定义、发布与运行态

Timer 是 Bundle 拥有的版本化资源。作者先维护一个以 bundleId + timerKey 标识的草稿， 再发布不可变的精确 SemVer，最后在 Bundle Manifest 中引用该版本。安装方不直接创建平台 Timer；Runtime 根据已安装 Bundle 的目标资源集合统一物化和收敛。

机器可读定义

当前公开定义合同是 1.0.0：

• JSON Schema
• CRON 完整示例
• EVERY 完整示例
• AT 完整示例

timerKey 不在 Definition JSON 内；它是 Bundle 内稳定且不可修改的资源 Key，由命令参数提供。 Definition 只包含下列字段，未知字段会被拒绝：

{
  "name": "每日门店运营汇总",
  "description": "每天 09:00 生成并分发门店运营日报",
  "target": {
    "businessId": "flower-operation.report-service",
    "method": "generateDailyReport",
    "params": {
      "scope": "ALL_STORES"
    }
  },
  "schedule": {
    "type": "CRON",
    "expression": "0 0 9 * * * *",
    "timezone": "Asia/Shanghai"
  },
  "enabled": true
}

字段规则：

• name 为 1–200 个 Unicode 字符；description 可省略或为 null，字符串时为 1–2000 个字符；两者不能有首尾空白。
• target.businessId 是安装后要调用的模块完整 businessId，target.method 是该模块公开的方法；params 可为任意 JSON 值，也可省略或为 null。
• CRON 使用 cron crate 的 7 段表达式（秒、分、时、日、月、周、年），并要求合法 IANA 时区。
• EVERY.everyMs 是毫秒整数，最小值为 300000。
• AT.at 是 RFC 3339 date-time，只执行一次；完成后保持禁用，不会在下一次相同目标态收敛时重复执行。
• 所有循环型 Timer 的相邻触发间隔不得小于 5 分钟。JSON Schema 能表达 EVERY 的下限；CRON 的间隔由 Definition 服务和 Runtime 再做语义校验。
• enabled: false 表示资源仍随 Bundle 安装和升级物化，但运行态保持禁用；它不等价于从 Manifest 删除资源。

草稿和不可变版本

以下命令中的 <WORKSPACE_ID> 是工作区数字 ID，<bundle> 接受 bundleId 或精确名称：

baijimu bundle timer list --workspace-id <WORKSPACE_ID> <bundle> --json
baijimu bundle timer get --workspace-id <WORKSPACE_ID> <bundle> <timerKey> --json
baijimu bundle timer create --workspace-id <WORKSPACE_ID> <bundle> --definition @timer.json --json
baijimu bundle timer update --workspace-id <WORKSPACE_ID> <bundle> <timerKey> --definition @timer.json --json
baijimu bundle timer publish --workspace-id <WORKSPACE_ID> <bundle> <timerKey> <semanticVersion> --json

创建时不提供身份；Owner 返回的 object.timerKey 用于后续读取、编辑和冻结。list 返回对象目录（object 与 name），get 返回当前作者定义：

{
  "object": {"type": "TIMER", "timerKey": "owner-returned-timer-id"},
  "definition": {
    "name": "每日门店运营汇总",
    "description": null,
    "target": {
      "businessId": "flower-operation.report-service",
      "method": "generateDailyReport",
      "params": null
    },
    "schedule": {
      "type": "EVERY",
      "everyMs": 86400000
    },
    "enabled": true
  }
}

作者入口校验当前用户对 Bundle 的管理权限。发布后，该 timerKey + semanticVersion 的内容不可修改；继续编辑草稿不会改变已发布版本。

加入 Bundle Manifest

在 Bundle 项目的 Git 工作树选择已经冻结的 Timer，CLI 自动保存 Owner 返回的领域身份：

baijimu bundle manifest catalog <bundle> timer --workspace-id <WORKSPACE_ID>
baijimu bundle manifest include <bundle> timer --workspace-id <WORKSPACE_ID> \
  --file baijimu.bundle.json --object-id <ownerReturnedTimerId> --version 1.0.0
baijimu bundle manifest validate @baijimu.bundle.json

{
  "schemaVersion": "2.0.0",
  "definition": {
    "timers": [{"timerKey": "owner-returned-timer-id", "semanticVersion": "1.0.0"}]
  }
}

示例身份只是结构说明，以目录实际返回值为准。semanticVersion 必须是精确 SemVer。 纳入清单不复制 Definition 或运行态任务；审查并提交 Git 后再发布 Bundle。

安装、升级和卸载收敛

Runtime 以每个 Application Runtime 中全部有效 Bundle 安装账本为权威目标集合，并使用完整 ResourceLocator = environmentKey/bundleId/TIMER/resourceKey 区分资源：

每次安装、升级或卸载在提交 Bundle 最终状态前先执行 Timer replace 收敛。收敛失败会使当前 Bundle Operation 失败，不会把安装记录错误地提交为已完成。运行态任务保存来源 Bundle、版本、 安装实例和 ResourceLocator；这些字段由平台生成，作者不能在 Definition 或 Manifest 中填写。

查询实际状态和执行记录

workspaceId 和 applicationRuntimeId 是两种不同身份，不能互换。先从 Runtime 服务目录响应 data.applicationRuntimeId 读取目标工作区当前 Runtime ID，再查询当前已物化状态：

baijimu runtime services list --workspace-id <WORKSPACE_ID> --json
baijimu runtime app timer status --workspace-id <WORKSPACE_ID> <APPLICATION_RUNTIME_ID> --json

成功响应的 data 包含 appId、version、versionNumber、apiGatewayUrl、 enabledTimerCount 和 timers。每个运行态 Timer 都包含 id、resourceLocator、 resourceKey、resourceVersion、enabled、调度字段，以及执行授权字段 executionAuthorizationStatus、executionSubjectUserId、executionSubjectWorkspaceId 和 executionAuthorizationRevision。BOUND 表示当前活跃 ServiceReference 的来源 Timer、目标方法、 工作区和执行用户全部匹配；MISSING 表示没有活跃绑定；MISMATCHED 表示绑定存在但身份或目标不一致。 userId、createdBy、updatedBy 是配置变更审计字段，不能用来判断触发时以谁的身份执行。 排障时应从这里复制完整 resourceLocator，不要只猜 timerKey。

Bundle 安装或升级时，Runtime 把安装操作中已经校验的 executionSubjectUserId 写入独立的 ServiceReference 授权绑定，并只把不透明 Token 交给 Timer。Timer 触发时，gateway 校验该 Token， 向目标 Module 注入可信用户和工作区；Module 启动 Workflow 时，Workflow Engine 从可信请求上下文 保存实例的 executionSubjectUserId，worker 后续调用 Module 时继续使用这个实例字段。调用方传入的 metadata.requestUserId 会在持久化前删除，不能覆盖执行用户；--metadata 只应用于触发来源等可观测业务信息。

查询执行记录：

baijimu runtime app timer executions --workspace-id <WORKSPACE_ID> <APPLICATION_RUNTIME_ID> <timerId> \
  --resource-locator <environmentKey/bundleId/TIMER/resourceKey> \
  --status success --limit 50 --offset 0 --json

resourceLocator 是推荐的精确身份。为兼容既有运行态可以省略；如果同一 Runtime 中存在多个 同名 timerId，则必须提供 resourceLocator，或在旧运行态中使用 --business-id 消歧。 status 可选值为 pending、running、success、failed、timeout、cancelled。 limit 取值为 1–1000，默认 50；offset 从 0 开始。 响应 data 包含 taskId、resourceLocator、timerId、count、limit、offset 和 executions。执行项沿用 Timer Runtime 的 snake_case 审计字段，例如 execution_id、 attempt_number、scheduled_at、started_at、completed_at、response_status_code、 duration_ms、error_type 和 error_message。

两个运行态查询都要求有效的签名用户凭证，校验当前用户是 <WORKSPACE_ID> 的有效成员，并验证 <APPLICATION_RUNTIME_ID> 确实归属该工作区。Timer 被 Manifest 删除或 Bundle 卸载后不再出现在活动配置中；已产生的执行审计记录按平台保留策略保存，但活动 Timer 查询 不承诺在资源移除后仍能用原 timerId 继续定位它。