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 或精确名称，<bundle> 接受 bundleId 或精确名称：

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

list 和 get 返回当前草稿，而不是已发布版本的可变视图。成功响应的 data 结构分别是 TimerDefinitionView[] 和 TimerDefinitionView：

{
  "bundleId": "flower-operation",
  "timerKey": "daily-report-trigger",
  "workspaceId": 1430,
  "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 Manifest schema 8.0.0 使用统一 resources 数组。一个可安装的 Timer 引用是：

{
  "schemaVersion": "8.0.0",
  "resources": [
    {
      "resourceType": "TIMER",
      "resourceKey": "daily-report-trigger",
      "semanticVersion": "1.0.0"
    }
  ],
  "dependencies": []
}

用 CLI 离线修改和校验 Manifest：

baijimu bundle manifest timer list @bundle.json --json
baijimu bundle manifest timer add @bundle.json --timer-key daily-report-trigger --semantic-version 1.0.0 --json
baijimu bundle manifest timer remove @bundle.json --timer-key daily-report-trigger --json
baijimu bundle manifest validate @bundle.json --json

resourceType 必须是大写 TIMER，semanticVersion 必须是完整、精确的严格 SemVer。 Manifest 不携带 Definition、工作区 ID、数据库 ID、运行态 Timer ID 或安装实例信息。

安装、升级和卸载收敛

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

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

查询实际状态和执行记录

先取得目标工作区的 applicationRuntimeId，再查询当前已物化状态：

baijimu runtime app timer status <workspaceId> <applicationRuntimeId> --json

成功响应的 data 包含 appId、version、versionNumber、apiGatewayUrl、 enabledTimerCount 和 timers。每个运行态 Timer 都包含 id、resourceLocator、 resourceKey、resourceVersion、enabled、调度字段以及 sourceBundleId、sourceBundleVersionId、sourceBundleInstallId。排障时应从这里复制 完整 resourceLocator，不要只猜 timerKey。

查询执行记录：

baijimu runtime app timer executions <workspaceId> <applicationRuntimeId> <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。

两个运行态查询都校验当前用户对 applicationRuntimeId 的访问权限。Timer 被 Manifest 删除或 Bundle 卸载后不再出现在活动配置中；已产生的执行审计记录按平台保留策略保存，但活动 Timer 查询 不承诺在资源移除后仍能用原 timerId 继续定位它。