# 工作流候选与测试资源公共说明

这些接口用于按任务测试项目、提交候选、确认提案，以及读取和恢复历史。候选提交、用户接受、应用发布和业务作业完成是四个不同结果。

## 身份与变量

| 场景 | 地址与变量 | 身份条件 |
| --- | --- | --- |
| 项目文件测试、提交 | `MOI_ENDPOINT`、`MOI_API_KEY`、`MOI_WORKSPACE_ID`、`MOI_RUNTIME_AUTHORIZATION` | 保留当前任务注入的配置。任务授权头原样传递；普通个人令牌不足以提交项目分支。 |
| 接受、拒绝、历史与恢复 | 示例采用公开 `/v5` 地址、`AI_STUDIO_API_KEY` 和 `WORKSPACE_ID` | 具有目标工作区相应工作流操作权限的个人访问令牌；同一环境的任务、提案和产物。 |
| 测试资源准备、观察、重置 | 本组示例采用当前任务环境 | 校验后的任务身份派生范围；普通 Product 身份分支也存在，但需显式提供完整范围并满足资源授权与任务状态条件。 |

`TASK_ID`、`ARTIFACT_ID`、`PROPOSAL_ID` 必须来自同一当前服务端候选。`ACCEPT_KEY` 是用户确认操作的稳定标识。历史使用 `WORKFLOW_CONTEXT_ID`；恢复时保存 `RESTORE_REQUEST_ID`、`RESTORE_TASK_ID` 和 `RESTORE_ARTIFACT_ID`，结果未知时保留原标识与选择，更换来源使用新标识。

## 项目文件映射

将当前任务项目的 `workflow/`、`operators/`、`tests/` 中服务端允许编写的普通文件收集为 JSON 对象：键是项目相对路径，值是字节的 Base64 编码。将此对象文件路径保存为 `PROJECT_FILES_JSON`，供输入示例读取。不要把文件名、目录名或 JSON 对象再次编码为整体 Base64；不要上传平台证据与参考材料。

完整的普通文件收集、目录与符号链接检查沿用开发文档“测试并提交工作流项目”的 Go/Python 示例；本内部工作集没有复制或另造一套路径规则。测试和提交使用相同快照。项目改变后需要重新测试。

## 接受、恢复与版本交接

接受响应包含完整 `candidate_ref`、`accepted_at` 和 `candidate`。候选可以包含工作流图、表单、布局、自定义算子快照、摘要、诊断、来源及内容摘要等服务端字段。保留完整响应，不以重写正文代替原候选。部署时服务端再次按引用取得已接受快照。

候选若已绑定已有工作流，发布会沿用该目标。省略应用 ID 不代表一定新建；显式 ID 不符会冲突。恢复历史保留来源提案的目标绑定，不接受、不发布，也不覆盖已保存应用。

历史 `current` 是最近已接受方案；`saved_workflow` 是可选的已保存工作流及版本引用。两者分别读取：接受后未发布，或其他对话更新同一工作流时，它们可以不对应同一候选。列表按任务分页，`total_tasks` 不能与 `items` 条数混算。

## 测试资源副作用

准备与观察操作都可能创建数据库和输入、输出卷。观察调用不是只读探针；返回的文件与行只是样例，要检查 `truncated`。重置会删除任务跟踪的测试知识库、卷和数据库；已有租约对应的任务必须仍处于 `working`。任务结束后的服务端生命周期清理与此重置动作不同。

## 错误与环境

| 动作 | 已核对的错误边界 | 处理 |
| --- | --- | --- |
| 历史查询与恢复 | 400 `WORKFLOW_HISTORY_INVALID_REQUEST`；404 `WORKFLOW_HISTORY_NOT_FOUND`；409 `WORKFLOW_HISTORY_CONFLICT`；其他服务异常为 503 `WORKFLOW_HISTORY_UNAVAILABLE` | 保留上下文与来源引用；校正分页或查询当前提案状态。认证、授权或参数解码可在此之前失败，不能把所有失败都归入这四种业务码。 |
| 接受 | 原任务未完成、产物无效、提案不匹配、非待确认、过期或确认键冲突 | 回到原任务核对；保留确认键，不改换候选重试。已接受的同键重放与新接受请求不同。 |
| 拒绝 | 仅能拒绝 `pending`；重复拒绝不幂等 | 结果未知时先读历史状态。它不是回滚已接受或已保存应用的接口。 |
| 测试资源 | 范围不一致、Catalog 不可用、租约绑定冲突、任务状态不允许或清理依赖失败 | 保留原任务及错误；不要通过改换用户或任务绕过。 |


Genesis `/v1` 与 Billing 各自独立。不得跨环境复用授权、工作区、任务、提案、候选或幂等键。
