版本发布

版本是配置变更生效的唯一通道——改配置不等于上线，发布到 RELEASE 才生效（见 devapp.md 生效模型）。

管理应用版本：基于当前配置建版本、查列表/详情、预检审批、发布、查状态。参数用对应命令的 --help 查询。版本用 --unified-app-id 定位，单个版本再加 --version-id；corpId/userId 系统注入，CLI 不传。

典型流程

permission add（requiredApproval=true 写入版本变更）
  → version create        创建版本
  → version check-approval 预检是否需审批 / 审批人
  → version publish        发布（含高敏权限需 --confirmed-sensitive）
  → version status         轮询发布/审批状态

新应用如果 version list 返回空，先 version create，用返回的 versionId 继续 check-approval/publish；不要因列表空误判无可发布内容。

创建版本

默认不要传 --version，不传时服务端基于最新已发布版本自动递增。只有用户明确要指定时才填 --version，且必须大于最新 RELEASE 版本，否则服务端返回 62018（版本号需高于上个版本号）。

创建成功后，后续 get/check-approval/publish 必须用 create 返回的 versionId；不要通过 list 猜最新版本。如果创建没返回 versionId，停止并报错。

check-approval 与 publish

check-approval 只查审批要求和候选审批人，不发布。publish 是真实发布；含高敏权限要加 --confirmed-sensitive，灰度选人模式用 --approver-user-id 指定审批人。

区分两个"预检"：--dry-run 是 CLI 层的预览不调上游；check-approval 是服务端查审批要求不发布。发布前建议先 check-approval。

发布/预检不返回动作枚举 result，看结构化字段判断下一步：

字段	含义	下一步
`requiresApproval=false` + `publishable=true`	不需审批，`check-approval` 通过	可以执行 `version publish`
`requiresApproval=true` + `approvalMode=SELECT_APPROVER`	需从候选人里选审批人	展示 `approvalOptions[].label`，让用户选后再 `publish --approver-user-id`
`requiresApproval=true` + `approvalMode=ENTERPRISE_SELF_BUILT`	企业自建审核	不传 `--approver-user-id`，直接 `publish` 提交审批
`published=true`	本次 `publish` 已直接发布	回读 `version status/get` 验证 `versionStatus=RELEASE`
`approvalSubmitted=true`	本次 `publish` 已提交审批	保存 `processId`，轮询 `version status`

SELECT_APPROVER 时 CLI 会把原始 approvalCandidates 增强为更容易展示的字段：

approvalPromptText：预渲染的成品选择文案（带 A./B. 序号 + 姓名（userId: xxx））；agent 原样展示这一段即可，无需自己遍历结构。
approvalOptions[]：结构化选项数组，字段包括 label/name/userId/mainAdmin/index/key，供需要结构化数据时使用。
completionState=WAITING_FOR_APPROVER_SELECTION、actionRequired=select_approver、mustAskUser=true：必须等待用户选择，不能默认取第一个。

展示审批人时，优先原样展示 approvalPromptText；需结构化时用 approvalOptions[].label（格式 姓名（userId: xxx），mainAdmin=true 时标注“主管理员”，仅 name 为空才退回 userId: xxx）。发布时把用户选中的 userId 传给 --approver-user-id。

审批模式 approvalMode：

approvalMode	含义	下一步
`SELECT_APPROVER`	灰度选人，需在候选审批人里选一个	展示候选，不自动取第一个
`ENTERPRISE_SELF_BUILT`	企业自建审核	不传 `--approver-user-id`，按企业自建流程等待

版本状态

version create/list/get/status 统一返回 versionStatus：

versionStatus	含义	下一步
`INIT`	已创建或有待发布变更，未发布	可 `check-approval`/`publish`
`AUDIT`	发布审核中	不要重复发布；即使没返回 `processStatus` 也按审核中处理
`RELEASE`	已发布生效	完成，可验证权限/机器人/网页等能力
`GRAY`	灰度	按灰度流程，不要当全量已发布

version status 的 processStatus 只在存在审批流程且后端透出时有值。versionStatus=AUDIT 但没 processStatus/processInstanceId 时不要判失败，仍是审核中。

processStatus	含义	下一步
`UNDER_REVIEW`	审批中	等待，必要时把 `processInstanceId` 给用户去钉钉客户端看
`PASS`	审批通过	继续回读，确认是否进 `RELEASE`
`FAIL`	审批拒绝	展示 `processComment`，改后重新建/发版本
`WITHDRAW` / `CANCEL`	撤回或取消	回到发布前，重新 `check-approval`/`publish`
`PUBLISH_FAILED`	审批后发布失败	展示错误，重查版本状态和后端错误

遇到未列出的状态值，不要猜语义；原样展示，回读 version get/status 或查文档/后台。

错误处理

情况	处理
`check-approval` 提示需审批	按返回选审批人，再 `publish --approver-user-id`
发布报高敏权限未确认	加 `--confirmed-sensitive` 重新发布
`ServiceResult.success=false`	透传 `errorCode/errorMsg`

发现命令

调用任何方法前先查清楚再敲：

# 浏览命令组下的子命令与 flag
dws dev app version --help

# 查某方法的必填参数、类型、默认值
dws dev <command-path> --help

按 --help 输出构造 flag；不要凭旧 schema 名称猜参数。

5.6 KiB Raw Blame History Unescape Escape