Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

feat: ingestion dataflow-canvas DSL multi-version (sticky snapshot + missing state) (#21261)

xugangqiang9f677f749eec
diff --git a/docs/administrator/upgrade_and_migration/database_change_log.md b/docs/administrator/upgrade_and_migration/database_change_log.md
index 5cc7f4f5c0..9547b21d51 100644
--- a/docs/administrator/upgrade_and_migration/database_change_log.md
+++ b/docs/administrator/upgrade_and_migration/database_change_log.md
@@ -16,7 +16,7 @@ A record of the schema and data changes the Go backend applies to a RAGFlow data
- The marker is a row in `system_settings` with the key `mysql_migration.database.version`.
- For version-gated steps, the marker prevents a migration step from running again after that step has completed successfully.
-- Go defines the versions as constants: `modelMigrationBaseVersion` and `modelMigrationTargetVersion` in [migration_version.go](https://github.com/infiniflow/ragflow/blob/main/internal/dao/migration_version.go), `conversationHistoryTargetVersion` in [conversation_history_migration.go](https://github.com/infiniflow/ragflow/blob/main/internal/dao/conversation_history_migration.go), `knowledgebaseParserConfigTargetVersion` in [migration.go](https://github.com/infiniflow/ragflow/blob/main/internal/dao/migration.go), and `ingestionParserConfigTargetVersion` in [ingestion_parser_config_migration.go](https://github.com/infiniflow/ragflow/blob/main/internal/dao/ingestion_parser_config_migration.go). The two parser-config constants share `v1.0.0-rc2`.
+- Go defines the versions as constants: `modelMigrationBaseVersion` and `modelMigrationTargetVersion` in [migration_version.go](https://github.com/infiniflow/ragflow/blob/main/internal/dao/migration_version.go), `conversationHistoryTargetVersion` in [conversation_history_migration.go](https://github.com/infiniflow/ragflow/blob/main/internal/dao/conversation_history_migration.go), `knowledgebaseParserConfigTargetVersion` in [migration.go](https://github.com/infiniflow/ragflow/blob/main/internal/dao/migration.go), and `ingestionParserConfigTargetVersion` in [ingestion_parser_config_migration.go](https://github.com/infiniflow/ragflow/blob/main/internal/dao/ingestion_parser_config_migration.go). The two parser-config constants share `v1.0.0-rc2`. The DSL multi-version backfill is gated by `dslVersionTargetVersion` (`v1.0.0-rc4`) in [dsl_version_migration.go](https://github.com/infiniflow/ragflow/blob/main/internal/dao/dsl_version_migration.go).
- The current permission migration targets `permissionMigrationTargetVersion` (`v1.0.0-rc3.dev4`) in [permission_migration.go](https://github.com/infiniflow/ragflow/blob/main/internal/dao/permission_migration.go). Tenant default-model migration targets `tenantDefaultModelsTargetVersion` (`v1.0.0-rc3.dev5`) in [tenant_default_models_migration.go](https://github.com/infiniflow/ragflow/blob/main/internal/dao/tenant_default_models_migration.go).
- The compilation queue split records `knowledgeCompileQueueTargetVersion` (`v1.0.0-rc3.dev5`), defined in [knowledge_compile_queue_migration.go](https://github.com/infiniflow/ragflow/blob/main/internal/dao/knowledge_compile_queue_migration.go), after both queues finish. Source-column presence controls the queue copy even when the marker already contains this or a newer version.
- A version-gated step runs when the stored version is lower than the step's version. Versions are compared with Python PEP 440 semantics, where a `dev` prerelease sorts *before* the release it precedes (`v1.0.0-rc1.dev1` < `v1.0.0-rc1`). A missing or unparsable marker never skips a step.
@@ -50,6 +50,7 @@ Startup order in `InitDB` for `ragflow_server --migrate` ([database.go](https://
| `v1.0.0-rc3.dev4` | Normalize legacy tenant invitation roles and statuses | `permissionMigrationTargetVersion` |
| `v1.0.0-rc3.dev5` | Move tenant default-model selections to owner memberships and drop the tenant columns | `tenantDefaultModelsTargetVersion` |
| `v1.0.0-rc3.dev5` | Split compilation queues into `knowledge_compile_docs_backlog` and `knowledge_compile_docs_inflight`, then drop their source columns | `knowledgeCompileQueueTargetVersion`; source-column presence controls copying |
+| `v1.0.0-rc4` | Lock existing dataflow-canvas dataset/document bindings to the canvas latest version (the `pipeline_version_id` columns are added by the version-less step below) | `dslVersionTargetVersion` |
The two tenant model steps are cumulative: a database at `v0.26.0` still runs the `v1.0.0-rc1` step, and a database at or above `v1.0.0-rc1` runs neither.
@@ -256,6 +257,23 @@ This migration requires a coordinated service stop:
Starting a server while either source column remains fails with `knowledge compilation queues need migration`. A database version marker at or above the current release does not bypass this requirement. If migration fails, keep services stopped, resolve the reported error, and rerun `ragflow_server --migrate`.
+## v1.0.0-rc4
+
+Locks every pre-existing dataflow-canvas binding to the latest version of that canvas, so already-configured datasets and documents keep parsing against the version that was current when the upgrade ran (design section 5/B4 sticky snapshot). The `pipeline_version_id` columns it writes are added by the version-less step below; this step only backfills their values and is gated by the `dslVersionTargetVersion` marker.
+
+### Data migration
+
+| Table | Change |
+|-------|--------|
+| `knowledgebase`, `document` | Rows whose `pipeline_id` points at a `dataflow_canvas` are bound to that canvas latest version (`user_canvas_version` ordered by `create_time DESC`). Bindings to a built-in parser id (no backing `user_canvas`), to a non-dataflow canvas, or to a canvas with no versions are left unbound; a dangling version id is never written. |
+
+Execution details:
+
+- Rows are read in id-ordered batches of 256, each batch in its own transaction, so an interrupted run resumes cleanly.
+- The marker advances to `v1.0.0-rc4` only after both tables are processed. Databases already marked `v1.0.0-rc4` or later skip the backfill.
+
+On success the step writes `v1.0.0-rc4` into the version marker.
+
---
## Version-less steps
@@ -277,6 +295,9 @@ These steps are not gated by the version marker. They use schema or data checks
| `ingestion_task_log` | Adds `pipeline_log_id varchar(32) NULL`, `event_type tinyint NOT NULL DEFAULT 4`, and the index `idx_ingestion_task_log_pipeline_id`. |
| `dialog`, `tenant_llm`, `api_token`, `canvas_template`, `system_settings`, `knowledgebase` | Column types converged to the Peewee models, for example `dialog.top_k int NOT NULL DEFAULT 1024`, `tenant_llm.api_key text`, `api_token.dialog_id varchar(32)`, `canvas_template.title` / `description` nullable longtext, `system_settings.value text NOT NULL`, `knowledgebase.raptor_task_finish_at` / `mindmap_task_finish_at` datetime. |
| `conversation`, `api_4_conversation` | Index `idx_<table>_dialog_updated (dialog_id, update_time, id)` for conversation list queries. |
+| `knowledgebase` | Adds `pipeline_version_id varchar(32) NULL` (dataflow canvas version binding; design section 5/B4). |
+| `document` | Adds `pipeline_version_id varchar(32) NULL` (inherits the dataset pinned version at upload; design section 5). |
+| `user_canvas_version` | Adds `alias varchar(255) NULL` (free-text version alias for the version list filter; design A2/F1). |
### Data changes
diff --git a/docs/dsl-multi-version.md b/docs/dsl-multi-version.md
new file mode 100644
index 0000000000..afb5b4c0e6
--- /dev/null
+++ b/docs/dsl-multi-version.md
@@ -0,0 +1,332 @@
+# DSL 多版本设计(Ingestion Pipeline / Dataflow Canvas)
+
+> 状态:v5.4(在 v5.3 基础上追加:§1 C5 / §G3 空版本=红色 Missing + Save 报“版本信息缺失”,dataset/file 两层;仍为锁定设计,TDD 实现中)
+> 约束:单 PR、严格 TDD、迁移为幂等 Go 函数、Missing 运行时校验不加字段、版本归属校验禁止悬空。
+
+---
+
+## 1. 目标与范围
+
+为 ingestion pipeline(画布类别 `dataflow_canvas`)的 DSL 增加**多版本**能力:
+
+- **A1** DSL 变更在数据库增量写入,版本号即时间(`user_canvas_version` 已存在的基础设施)。
+- **A2** 新增版本别名 `alias`(后端仅存储,前端过滤,不涉及后端逻辑)。
+- **B1** 画布可查看多版本;**B2/B2.1** 删除版本需弹窗二次确认(告知可能导致 File 解析不可用);**B3** 手动 Save(用户明确点击保存)→ 生成新版本;自动保存(非手动)→ 仅更新 `user_canvas.dsl` live draft,不生成新版本(v5.2 细化,修正原「改 DSL 即生成版本」);**B4** 画布修改**不向下传播**到已绑定的 dataset/file(粘性快照)。
+- **C1** dataset/file 配置可选版本;**C2** 默认绑定“选择时刻最新具体版本”(锁定非浮动),可手动选;**C3** 切版本 → 参数重置为该版本 default。
+- **C4** 版本删除 → 引用方 Missing,file 不可解析;**D1/D2/D3** 非最新显示 `!`,点击仅提示不引导升级;**E1** 列表新→老;**F1** 别名前端过滤。
+- **C5** 版本信息为空(`pipeline_version_id` 为空 / 未选版本)→ UI 显示红色 `Missing`(缺失)徽标;用户点击 Save 时校验并报错“版本信息缺失”。dataset 与 file 两层均适用(见 G3)。空版本不再自动回填为最新版本。
+- **G1** dataset/file 版本选择 UI:不渲染 `latest` 伪选项,仅列真实版本,选项文案须含 `alias`(如 `alias (title)`);已绑定即存具体版本 ID,无 latest 概念(呼应 C2)。
+- **G2** alias 写入/更新:后端经版本级 `PATCH` 端点(及可选随 manual Save 携带)写入 `user_canvas_version.alias`;前端提供编辑入口(见 §4.4、§8)。
+- **G3** 空版本(`pipeline_version_id` 为空 / 未选版本)处理:UI 显示红色 `Missing`(缺失)徽标,与「版本被删」的 Missing 同一种视觉(见 §3 扩展);用户点击 Save(创建/更新 dataset、或更新 file 绑定)时,后端**拒绝**并校验报错“版本信息缺失”(HTTP 4xx + 文案“版本信息缺失”),不写入、不自动回填为最新版本(呼应 C5)。dataset 与 file 两层均实现此校验(C5 双层要求)。
+
+**不在范围**:agent(画布类别 `agent`)的发布语义、built-in parser(`parse_type=1`)的版本化、Python 端(按 AGENTS.md 正在移除)。
+
+---
+
+## 2. 当前状态核查(已核实,非臆测)
+
+### 2.1 版本化基础设施已存在
+- 表 `user_canvas_version`,实体 `entity.UserCanvasVersion`:`ID, UserCanvasID, Title, Description, Release bool, DSL, BaseModel`。**需加 `Alias *string`**。
+- `internal/dao/user_canvas_version.go`:
+ - `SaveOrReplaceLatestTx`:DSL 变更才建新版本;同 DSL 且 `!latest.Release || opts.Release` 时就地更新最新行(对 dataflow 即同 DSL 重复保存不新建版本)。
+ - `ListByCanvasID`:`ORDER BY create_time DESC` —— 满足 E1(新→老)。
+ - `GetLatest`:`create_time DESC` 取最新版本。
+ - `GetLatestReleased`:仅 `release = true` 的版本。
+ - `DeleteTx` / `DeleteByCanvasIDTx` 已存在。
+
+### 2.2 发布动作的真相(关键修正)
+- `web/.../index.tsx:350` 无条件挂载 `<PublishConfirmDialog>`,但 `publish-confirm-dialog.tsx` 内部有 `if (isPipeline) { return null; }`(`isPipeline` 由 `useIsPipeline()` 判定 URL 分类为 `DataflowCanvas`)。**结论:发布按钮是 agent 专用,ingestion pipeline(dataflow)没有发布动作。**
+- `use-save-graph.ts` 带 `release=true` 的 `saveGraph(...,true)` 仅来自 `onPublish`,而该回调在 pipeline 下永不触发;dataflow 所有保存(含 20s 自动保存)`release` 均为 `undefined`。
+- 后端 `SaveOrReplaceLatestTx` 对 dataflow 写入的版本 `Release` 恒为 `false`。
+- 因此 **`GetLatestReleased` 对 dataflow 永远返回未找到** → dataflow 无 draft/published 双态,**所有版本都是草稿**。
+- **(v5.2 勘误/延伸)** 尽管 dataflow 全部保存 `release` 均为 undefined,但 `SaveOrReplaceLatestTx` 在 DSL 发生变更时会 INSERT 新版本行——即**当前自动保存(20s 去抖)也会生成新版本**。§5.1 将把版本创建收敛到「仅手动 Save」。agent 与 dataflow 共用同一保存入口(`web/src/pages/agent/index.tsx` → `UpdateAgent`),故该修正作用于共享路径。
+
+### 2.3 DSL 加载的两个真相源(版本化要改的核心)
+- API 侧:`internal/service/pipeline_params.go` 的 `loadCanvasDSLJSON(ctx, canvasID)` 读 `user_canvas.dsl`(永远最新),被 `LoadPipelineDSL` 与 `ResolveComponentParamsDefaults` 复用。
+- 运行时:`internal/ingestion/task/pipeline_executor.go` 的 `loadDSLFromCanvas(ctx, canvasID)`(~L1010)读 `user_canvas.dsl`(永远最新),返回 `(dsl, canvasID, err)`。其类型 `loadDSLFunc` 签名仅 `(ctx, canvasID)`,**破坏性变更需加版本**。
+
+### 2.4 绑定落库路径(写入粘性快照的落点)
+- dataset:`internal/service/dataset/crud.go` `CreateDataset`、`internal/service/dataset/update.go` `UpdateDataset`。
+ - `service.FromRequest(parseType, parserID, pipelineID)` 构建 `ParserSelection`;`sel.IsBuiltIn()` 时 `req.PipelineID = nil`(清掉);Pipeline 模式下 `pipelineID` 是 `user_canvas.id`(经 `normalizeDatasetPipelineID` 校验 32 hex)。
+ - `update.go` 中 `service.LoadPipelineDSL(ctx, isPipeline, effParserID, effPipelineID)` 加载 DSL;`pipelineChanged := pipelineID != nil && (lockedKB.PipelineID == nil || *pipelineID != *lockedKB.PipelineID)`。
+- document(文件级):`internal/service/document/file2document.go` 写入 `PipelineID`;`document.go` 有 `PipelineID *string`。单个文件可单独改 pipeline(已确认)。
+
+### 2.5 运行时上下文
+- `internal/ingestion/task/task_context.go` 的 `TaskContext` 仅有 `PipelineID string`;`resolvePipelineID` 需加 `resolvePipelineVersionID`。
+- ad-hoc/调试路径(`pipeline_executor.go` ~L885-916,`input.PipelineID`)也需走版本校验(见 §12 A7)。
+
+---
+
+## 3. 锁定决策
+
+1. **迁移 = 幂等 Go 迁移函数**(`internal/dao/migration.go` 的 `RunMigrations` 集中调用),参考先例 `migrateKnowledgebaseParserConfig`(FindInBatches + 版本标记)。**不**用独立 SQL 脚本。
+2. **Missing = 运行时校验**,不额外增加字段、不查“是否最新”。两种成因都归为 Missing:
+ - **版本被删 / 悬空**:绑定版本 `pipeline_version_id` 指向的 `user_canvas_version` 不存在(或被删、或跨 canvas)→ Missing。
+ - **空版本**:`pipeline_version_id` 为空 / 未选版本(dataset 或 file 创建/更新时未带版本)→ 同样显示红色 `Missing` 徽标(见 G3/C5);保存时后端校验报错“版本信息缺失”,不写入、不自动回填(见 G3)。
+ 空版本与「被删版本」是 Missing 的两种成因,前端视觉统一为红色 `Missing`,区别仅在于成因提示文案(被删=提示重选版本;空版本=提示“版本信息缺失”)。
+3. **版本归属校验**:禁止悬空版本号。`pipeline_version_id` 必须属于绑定 `pipeline_id` 对应的 `user_canvas`(且类别为 `dataflow_canvas`);否则视为无效。
+
+### H12 修订(v4 修正)
+- 因 dataflow 无发布语义,`!`(非最新)基线改用 **`GetLatest`**(按 `create_time DESC`),**不**用 `GetLatestReleased`。
+- `backfillDSLVersionBindings` 对每个绑定了 dataflow-canvas pipeline 的 dataset/file,取 **`GetLatest(canvasID).ID`** 写入 `pipeline_version_id`;`GetLatest` 不存在(脏数据)则跳过 + 日志告警(绝不写悬空 version_id)。
+
+---
+
+## 4. 数据模型变更
+
+### 4.1 `entity.UserCanvasVersion`
+新增字段:
+```go
+Alias *string `gorm:"column:alias" json:"alias,omitempty"`
+```
+
+### 4.2 `entity.Dataset` 与 `entity.Document`
+各新增可空字段:
+```go
+PipelineVersionID *string `gorm:"column:pipeline_version_id;size:32;index" json:"pipeline_version_id,omitempty"`
+```
+(built-in parser 绑定时该字段为 `NULL`,不启用。)
+
+### 4.3 迁移函数(新增 `internal/dao/migration.go`)
+- `migrateDSLVersionColumns`:给 `knowledgebase` 与 `document` 表加 `pipeline_version_id` 列(用 `HasColumn` + ALTER,参考 `migrateIngestionTaskPipelineLogID` 的 `Error1060` 容错)。
+- `backfillDSLVersionBindings`:幂等(用 `system_settings` 版本标记防重跑)。`FindInBatches` 遍历 `knowledgebase`/`document` 中 `pipeline_id IS NOT NULL AND pipeline_id <> ''` 的行;仅当 `user_canvas` 存在且 `canvas_category = dataflow_canvas` 时,写 `pipeline_version_id = GetLatest(canvasID).ID`;built-in / 类别不符 / 无版本 → 跳过。
+
+---
+
+### 4.4 `alias` 写入/更新路径(v5.2 新增)
+
+- **现状(已核实)**:
+ - `entity.UserCanvasVersion.Alias` 已存在(`internal/entity/canvas.go:67`,gorm 列 `alias`)。
+ - DAO `SaveOrReplaceLatestTx` 在新建/就地更新两分支均写 `alias`(`internal/dao/user_canvas_version.go:313-315` 更新分支、`:328` 新建分支);有单测 `TestUserCanvasVersionDAO_SaveOrReplaceLatestTxStoresAlias` 覆盖。
+ - handler `publishAgentRequest.Alias *string`(`internal/handler/agent.go:701`)仅经 `POST /publish` 透传;但 `UpdateAgent` 路径调用 `saveOrReplaceVersionOptions(..., nil, nil, release)` 显式传 `nil` alias,故普通保存**不写** alias。
+ - 前端**无任何 alias 输入控件**:`publish-confirm-dialog.tsx` 对 dataflow 返回 null(无发布入口),agent 发布也不发 alias;所有前端 alias 命中均为只读过滤/显示。结论:**alias 写入路径后端完备但 UI 不可达,实际恒为 NULL**。
+- **写入设计**:
+ - 新增 `PATCH /api/v1/agents/{canvas_id}/versions/{version_id}`:body 含 `alias`/`title`/`description`,经 `versionDAO.UpdateTx` 更新该行元数据;**不**触发新版本、**不**改 DSL;需归属校验(`version.UserCanvasID == canvas_id`)。
+ - `UpdateAgent` 保存请求**可选**携带 `alias`,随 manual Save 创建/刷新版本时一并写入(兜底路径,复用 `SaveOrReplaceLatestTx` 既有 alias 分支)。
+- **前端**:版本历史对话框(`web/src/pages/agent/version-dialog/index.tsx`)增加 alias 编辑输入,提交至上述 PATCH;dataset/file 选择器保持只读过滤(G1/F1)。
+
+## 5. 写入路径:粘性快照(首次默认最新、之后保留)
+
+**语义**:绑定 pipeline 的那一刻,把“当时最新具体版本”的 `ID` 锁进 `pipeline_version_id`,后续画布再改不再影响已绑定方(B4)。
+
+- **dataset**:`crud.go` `CreateDataset` 与 `update.go` `UpdateDataset` 中,当 `sel.IsPipeline()` 且 `pipelineID` 有效时:
+ - 若本次是**新绑定 / pipeline_id 变更**(`pipelineChanged`):`pipeline_version_id = GetLatest(canvasID).ID`(锁定当时最新)。
+ - 若 pipeline_id 未变(仅其它字段变更):**保留**原 `pipeline_version_id`(不随画布漂移)。
+ - 归属校验:确认 `canvas_category = dataflow_canvas`,否则报错(决策 §3-3)。
+- **document**(文件级):`file2document.go` 同理,绑定/变更 pipeline 时写 `pipeline_version_id = GetLatest(canvasID).ID`;未变更则保留。
+- **手动选版本(C2)**:新增请求字段 `pipeline_version_id`(可选)。传入时校验其属于该 `pipeline_id` 的 canvas,写该值(取代“默认最新”)。
+ - **handler 字段白名单(v5.3 补充)**:`internal/handler/dataset.go` 的 `createDatasetAllowedFields` 与 `updateDatasetAllowedFields` 必须放行该字段,否则请求在 handler 层即被拒(code 101 `Extra inputs are not permitted`),service 层永远收不到。该白名单是独立于 service 校验的**第二道闸**,仅显式登记的字段可通过;新增 `pipeline_version_id` 须同时登记到创建与更新两个白名单(PR #21261 已落地,对应 `dataset_allowed_fields_test.go`)。
+- **C3 切版本重置参数**:当 `pipeline_version_id` 被显式改为另一版本时,调用 `ResolveComponentParamsDefaults(ctx, parserID, &canvasID, versionID)` 取得该版本 default,将 dataset/document 的 `parser_config`(component params)重置为该 default(范围见 §12 A3)。
+- **回落契约(v5.1 新增,必读)**:`pipeline_id`(画布容器)与 `pipeline_version_id`(容器内快照)是「容器⊃快照」关系,`pipeline_version_id` 必须在 `pipeline_id` 的上下文里解析。任何解析都必须遵守下面两条回落链,缺一不可,否则会出现「钉被清空 / 误用最新 / 误用 builtin 默认」三类缺陷:
+ - **版本回落链**:`req.PipelineVersionID` → `lockedKB.PipelineVersionID`(已钉版本,不可跳过)→ `GetLatest(canvas)`。请求未带版本时,**必须先回落到已钉版本**,仅当已钉版本也为空才用 latest。绝不允许「请求没带就直接取 latest」——那会让「钉旧版本」的数据集在改配置时被悄悄升级到最新结构。
+ - **canvas 上下文回落链**:解析 `pipeline_version_id` 所需的 canvas = `req.PipelineID` → `lockedKB.PipelineID`(已绑画布)→ nil(builtin)。请求省略 `pipeline_id`(只发 `pipeline_version_id`)时,**必须沿用已绑 `PipelineID`**,不得因省略而让上下文变 nil;否则归属校验失效、`pipeline_version_id` 被误清空、C3 重置误用 builtin 默认。
+ - **parser_config 重建一律基于钉住版本的 DSL**:无论因何触发(请求带 `parser_config`、切版本、pipeline 变更),重建所用 DSL 必须来自 `pipeline_version_id` 指向的版本;仅当 `pipeline_version_id` 为空时才回落 `GetLatest`。「保留版本号」与「用该版本 DSL 重建」是同一语义,不可割裂——只保留列而用 latest DSL 重建属于未完全实现粘性快照(B4)。
+ - **单字段 PATCH 必须沿用已绑值**:update 允许只发 `pipeline_version_id` 省略 `pipeline_id`(或反之)。被省略的字段一律沿用 `lockedKB` 已绑值,不得清空或误判。
+
+---
+
+## 5.1 画布保存语义:手动 Save vs 自动保存(v5.2 新增)
+
+**背景**:agent 与 dataflow 画布共用同一保存入口——`web/src/pages/agent/index.tsx` 的 Save 按钮(`handleSave` → `saveGraph()`)与 `useWatchAgentChange` 的 20s 去抖自动保存,二者皆落到 `service.UpdateAgent` → `SaveOrReplaceLatestTx`。当前只要 DSL 变更即 INSERT 新版本行,故**自动保存也会刷版本**,违背「版本=手动保存里程碑」语义。
+
+**信号**:前端自动保存请求增加 `autosave: true`(手动 Save 不带,或显式 `autosave: false`)。`updateAgent` 请求体(`web/src/services/agent-service.ts`)与 `PUT /api/v1/agents/:canvas_id` 透传该字段;`service.UpdateAgent` 据此分支。
+
+**分支规则(统一作用于 agent 与 dataflow,因共用 `UpdateAgent` 路径)**:
+- `autosave == true`:**仅** `canvasDAO.UpdateFieldsTx` 更新 `user_canvas.dsl`(live draft),**不**调用 `SaveOrReplaceLatestTx`,**不**产生新版本。
+- `autosave == false/缺省`(手动 Save):**必须同时发生两件事**——① `canvasDAO.UpdateFieldsTx` 更新 `user_canvas.dsl`(live draft);② 版本写入 **INSERT 一条新的 `user_canvas_version` 记录**。**v5.2 修正:不再做『同 DSL 就地刷新』去重**——手动 Save 即落一版,即便 DSL 与上一版本完全相同也 INSERT 新行(保证每次手动保存都产生新版本)。实现上 manual Save 应走强制 INSERT 路径(如新增 `SaveNewVersionTx(canvasID, dsl, alias, title, description)` 或给 `SaveOrReplaceLatestVersionOptions` 加 `ForceNew bool`),绕过 `sameDSL` 就地刷新分支;自动保存则不进入该路径。
+
+**agent 发布语义不受影响**:`PublishAgent`(`release=true`)路径独立,仍创建 released 版本,本次不改(与 §1「agent 发布语义不在范围」一致)。
+
+**范围裁定(A9,用户已确认 2026-10-22)**:因 agent/dataflow 共用 `UpdateAgent`,修正必须落在共享路径、对所有画布类别统一生效;**手动 Save 对 agent 与 dataflow 一致:更新 `user_canvas` + INSERT 新 `user_canvas_version`**;agent 的发布语义(Publish)不受影响。agent 手动 Save 仍建版本(行为不变),仅自动保存收敛,属良性改进且不触及 §1 范围。
+
+**粘性快照不受影响**:新建版本只改 `user_canvas_version`,已绑定 dataset/file 的 `pipeline_version_id` 仍为粘性(B4);live draft 领先于最新版本属预期(手动 Save 后方才落成版本)。
+
+## 5.2 版本上限与保留策略(v5.3 新增)
+
+**动机**:用户可经手动 Save(§5.1)反复创建版本,需有一个**可预期、有界**的存储上限,同时**绝不**在写路径上静默删除用户的旧版本(旧设计曾设想「未发布 ≤ 20 自动裁剪」,经评审否决——裁剪会丢失用户可能需要的旧版本,故改为 keep-all)。
+
+### 5.2.1 每画布硬上限 K=64
+
+- 常量 `MaxCanvasVersions = 64`(位于 `internal/dao/user_canvas_version.go`)。计数针对**单个 `user_canvas_id` 下的全部 `user_canvas_version` 行**,不区分 `release` 状态(发布的与未发布的草稿一并计入)。
+- 写版本前 `SaveOrReplaceLatestTx` 先 `COUNT(*)` 该 canvas 现有行数:
+ - 当 `existing < MaxCanvasVersions`:允许写入(新增 INSERT 或就地刷新)。
+ - 当 `existing >= MaxCanvasVersions`:拒绝本次写入,返回 `ErrCanvasVersionLimitExceeded`(文案:**「版本数已达上限(最多 64 个),请删除旧的不再使用的版本」**),由 `mapAgentError` 映射为 `common.CodeDataError` 透传原话给前端弹窗。
+- **计数为「总量」而非「未发布」**:发布版本(agent `PublishAgent` 的 `release=true` 行)同样占名额。达到 64 后,无论手动 Save 新草稿还是发布新版本,都会被上限拦截,必须用户主动删除腾位。
+- **隔离性**:上限按 `user_canvas_id` 维度独立计算,画布 A 写满不影响画布 B(见单测 `TestCanvasVersionLimit_PerCanvasIsolation`)。
+
+### 5.2.2 不消耗名额的写入形态
+
+以下两种写入**不计入 / 不触发上限判定**,是「更新既有版本」而非「新增版本」:
+
+- **就地 DSL 刷新**(`ForceNew=false` 且 `sameDSL` 命中):`SaveOrReplaceLatestTx` 命中同 DSL 分支时只 `UPDATE` 最新一行(如 alias/title/description 元数据),行数不变,不消耗名额(单测 `TestCanvasVersionLimit_RefreshInPlaceAllowedAtCap`)。
+- **元数据 PATCH**:服务层 `PatchVersion`(独立 update 路径)仅改 `alias`/`title`/`description` 等字段,不增行,不消耗名额(单测 `TestCanvasVersionLimit_AliasPatchUnaffected`)。
+
+> 上限只在「实际新增行」时起作用。只要不 INSERT 新行,即便已达到 64 也能继续刷新最新版本或改元数据。
+
+### 5.2.3 keep-all:写路径不做任何自动裁剪
+
+- **彻底删除**原 `deleteAllUnpublishedExcessTx` 及其「未发布 ≤ 20 裁剪」逻辑。写版本路径**不再因总数过高而删除任何既有行**。
+- 版本行的唯一删除入口是用户**显式**操作:
+ - 前端版本历史对话框的删除按钮 → `DeleteVersion`(带归属校验、引用扫描 `CountPipelineVersionReferences`,防止删掉仍被 dataset/file 绑定的版本)。
+ - agent 的版本清理(如适用)走显式接口,非写时隐式裁剪。
+- 因此「手动 Save 越多越占名额」,名额的回收**只能由用户主动删除**完成;K=64 是系统唯一的硬约束,不存在「写满后自动丢旧版」的隐藏行为(单测 `TestCanvasVersionKeepAllRetainsUnpublished`、`TestCanvasVersionKeepAllRetainsBeyondOldTrim`)。
+
+**与上游 PR 的关系**:上游 #21343 曾引入 keep-all 但本 PR 早期版采用「未发布裁剪到 20」,现经评审统一为「keep-all + K=64 上限」——以本 PR 行为为准;上游 #21352 的 `ApplyVersion` 已采纳并保留。
+
+## 6. 读取路径:版本透传 + Missing 校验
+
+### 6.1 API 侧(`pipeline_params.go`)
+- `loadCanvasDSLJSON(ctx, canvasID, versionID *string)`:
+ - `versionID` 非空 → 经 `UserCanvasVersionDAO.GetByID` 取版本;**归属校验**:`version.UserCanvasID == canvasID`(否则视作 Missing)。
+ - `versionID` 空(脏数据/未迁移)→ 回退 `GetLatest(canvasID)`;若仍无 → 返回 Missing 错误。
+ - 读 `version.DSL` 替代 `canvas.DSL`。
+ - 仅 `canvas_category = dataflow_canvas` 进入上述版本化路径;agent 类画布(`agent`/`agent_canvas`)按 §1 不在范围,直接读 `canvas.DSL`(live draft),不走版本化、不触发 Missing。
+- `LoadPipelineDSL` 与 `ResolveComponentParamsDefaults` 透传 `versionID`(从 dataset/document 的 `pipeline_version_id` 取)。
+
+### 6.2 运行时(`pipeline_executor.go`)
+- `TaskContext` 增加 `PipelineVersionID string`;`resolvePipelineID` 增加 `resolvePipelineVersionID`(从 `doc.PipelineID`/`doc.PipelineVersionID` 解析)。
+- `loadDSLFunc` 签名加 `versionID`;`loadDSLFromCanvas(ctx, canvasID, versionID)` 改为读 `user_canvas_version.dsl`(归属校验同上)。
+- ad-hoc `input.PipelineID` 路径同样带 `versionID`(来源见 §12 A7)。
+- **Missing 处理**:版本缺失/不归属 → 解析任务直接 fail(C4),错误信息含“pipeline 版本不存在,请重新选择版本”,file 进入不可解析状态;**不做**“是否最新”判断(决策 §3-2)。
+
+### 6.3 `!` 非最新指示(D1/D2/D3)
+- 列表/详情接口返回 dataset/document 时,附带 `pipeline_version_outdated: bool` =(`pipeline_version_id` 非空 且 ≠ `GetLatest(canvasID).ID`)。
+- 前端显示 `!`;点击仅弹提示(D3:**不**引导升级、不自动改绑定)。
+
+---
+
+## 7. 服务/API 变更
+
+- `agent.go` `UpdateAgent`(agent 与 dataflow 共用,经 `canvas_category` 区分):`patch` 含 `dsl` 时调 `SaveOrReplaceLatestTx`(携 `release`,dataflow 恒 false)——**不改**。
+- **handler 字段白名单放行 `pipeline_version_id`(v5.3 补充)**:`internal/handler/dataset.go` 的 `createDatasetAllowedFields` / `updateDatasetAllowedFields` 已登记 `pipeline_version_id`。这是“绑定具体版本”得以进入 service 层的前置条件——未登记时 create/update dataset 请求携带该字段会被 handler 直接以 `code 101` 拒绝,service 的粘性快照逻辑无从触发(见 §5 C2 注释)。该改动仅“显式放行目标字段”,未知字段仍按白名单拒绝,不退化成“全放行”。
+- `DeleteVersion`:增加引用扫描 —— 查 `knowledgebase`/`document` 中 `pipeline_version_id = 待删版本ID` 的引用数;**允许删除**(B2.1 弹窗已二次确认),引用方因版本缺失自动进入 Missing(§6.2)。仅 dataflow 生效(引用扫描范围见 §12 A4)。
+- 版本列表接口(`ListByCanvasID`,已按 create_time DESC 满足 E1):返回含 `alias` 字段(A2/F1)。
+- 版本详情/下载接口已存在(`version-dialog` 仅查看/下载,无删除/载入编辑入口 —— 前端需补 B2 删除按钮与 C2 选版本入口)。
+
+---
+
+- **保存分支(v5.2)**:`UpdateAgent` 按 `autosave` 字段分支(见 §5.1);自动保存**仅** `UpdateFieldsTx` 更新 live draft、绝不碰 `user_canvas_version`;手动 Save **同时**更新 `user_canvas.dsl` 并 **INSERT 新 `user_canvas_version` 记录**(保证 user_canvas 更新与版本插入两者都发生,不复用就地刷新)。
+- **版本 PATCH 端点(v5.2)**:`PATCH /api/v1/agents/{canvas_id}/versions/{version_id}`,body `{alias?, title?, description?}`,经 `versionDAO.UpdateTx` 更新元数据,不新建版本、不改 DSL;需归属校验(`version.UserCanvasID == canvas_id`);仅对画布本体版本生效。
+
+## 8. 前端变更
+
+- `web/src/pages/agent/index.tsx`:`PublishConfirmDialog` 对 pipeline 返回 null(确认无发布动作,保持现状)。
+- `web/src/components/pipeline-version-select/index.tsx`:**移除 `LATEST_VERSION_VALUE='__latest__'` 伪选项(G1,v5.2)**——删除 `:97-99` 的 `<SelectItem value={LATEST_VERSION_VALUE}>` 与 `:32/:43-49` 的 sentinel 映射(`formValueToSelectValue`/`selectValueToFormValue` 不再用 `__latest__`);选项文案保留并强化 alias 显示(`v.alias ? v.alias + ' (' + v.title + ')' : v.title`)。无预绑定时默认选中最新具体版本(GetLatest),提交发送具体 `pipeline_version_id`,**空值不再表示 latest**。
+- dataset 设置页(`web/src/pages/dataset/setting/index.tsx:294`)与文件对话框(`web/src/components/document-pipeline-dialog/index.tsx:193`)复用上述组件,自动生效;提交体 `pipeline_version_id` 恒为具体版本 ID。
+- `web/src/pages/agent/index.tsx` + `use-save-graph.ts`:自动保存(20s 去抖)请求增加 `autosave: true`;手动 Save(`handleSave`)不带(v5.2,见 §5.1)。
+- `web/src/pages/agent/version-dialog/index.tsx`:增加 alias/title 编辑输入,提交至新 `PATCH` 端点(G2,见 §4.4);保留删除按钮(B2/B2.1)、`!` 提示(D1/D2/D3)、alias 显示与过滤(F1)。
+- dataset 设置页:增加 pipeline 版本选择(C1/C2)与 `!` 指示(D1/D2/D3)。
+
+---
+
+## 9. TDD 测试清单(严格红→绿)
+> **对抗性 fixture 强制规则(v5.1 新增,见 §13):** 本特性的灵魂是 `pipeline_version_id`(钉住)可以 ≠ `GetLatest`(最新)。因此 §9 每一条涉及版本的测试**必须**使用 `pinned != latest` 的 fixture;并且必须为「耦合字段只发其一」的 PATCH 场景各写一条测试。happy-path(pinned==latest 且两字段齐发)**不算覆盖**,因为它永远发现不了 B1/B2 类缺陷。
+
+**后端(unit tier,默认 `bash build.sh --test`)**
+- T1 `migrateDSLVersionColumns`:列不存在时加列、已存在时幂等(Error1060 容错)。
+- T2 `backfillDSLVersionBindings`:dataflow-canvas 绑定 → 写 `GetLatest().ID`;built-in 跳过;agent-canvas 跳过;`GetLatest` 缺失跳过+日志;重跑幂等(system_settings 标记)。
+- T3 `loadCanvasDSLJSON` 带 versionID:取版本 DSL;归属不符 → Missing;空 versionID 回退 GetLatest。
+- T4 `LoadPipelineDSL` 透传 versionID。
+- T5 `ResolveComponentParamsDefaults` 按 version 取 default。
+- T6 dataset `CreateDataset`:Pipeline 模式写 `pipeline_version_id=GetLatest`;BuiltIn 模式字段为 NULL。
+- T7 dataset `UpdateDataset`:pipeline 未变更 → 保留原 versionID(B4);pipeline 变更 → 重写为新 GetLatest;手动 versionID 生效且做归属校验。
+- T7f(B2 对应)`UpdateDataset` **单字段 PATCH**:只发 `pipeline_version_id=v-new`、省略 `pipeline_id`,且数据集已钉 `v-old` → 断言 `pipeline_version_id` 变为 `v-new`(**未被清空**),且 `parser_config` 按 `v-new` 默认整体重置(C3/A3),归属校验以已绑 `PipelineID` 为上下文。
+- T7g(B1 对应)`UpdateDataset` **钉旧版本 + 只改 parser_config**:数据集钉 `v-old`(≠latest),PATCH 只带 `parser_config`、不带 `pipeline_version_id` → 断言重建所用 DSL 来自 `v-old`(**非 latest**),`parser_config` 结构与 `v-old` 默认一致(粘性快照 B4 不被破坏)。
+- T7h(v5.3 白名单)`createDatasetAllowedFields` / `updateDatasetAllowedFields` 含 `pipeline_version_id`:断言 create/update dataset 请求携带该字段不被 handler 白名单以 `code 101` 拒绝(端到端经此闸进入 service);对抗:未知字段 `__bogus_field__` 在两白名单中仍为 false(白名单是“显式放行”而非“全放行”)。对应 `internal/handler/dataset_allowed_fields_test.go`。
+- T8 document 绑定同样写 versionID(粘性)。
+- T9 `DeleteVersion` 引用扫描:引用存在时允许删除、引用方 Missing;无引用正常删。
+- T10 运行时 `loadDSLFromCanvas` 按 versionID 取 `user_canvas_version.dsl`;版本缺失 → 解析 fail(C4)。
+- T11 `TaskContext.resolvePipelineVersionID` 从 doc 解析。
+- T12 ad-hoc 路径带 version 校验。
+- T13 归属校验:悬空/跨 canvas 的 `pipeline_version_id` → 拒绝/ Missing。
+- T14 `!` 指示计算:绑定≠GetLatest → outdated=true;相等 → false。
+- T15 alias 存储/返回(A2)。
+- T16 built-in pipeline 不受任何版本逻辑影响(验收断言)。
+- T17 迁移前存量数据可被 backfill 正确锁定。
+- T18 `normalizeDatasetPipelineID` + 类别校验组合。
+
+**前端**
+- T19 版本列表新→老(E1)。
+- T20 `!` 显示与“仅提示不引导升级”(D3)。
+- T21 删除版本二次确认弹窗文案含“可能导致 File 解析不可用”(B2.1)。
+- T22 选版本表单可选具体版本 + alias 过滤(C2/F1)。
+- T23 dataset/file 版本选择入口与提交体含 `pipeline_version_id`。
+- T28 `!` 点击仅提示。
+- T29 Missing 状态呈现(禁用解析 + 提示重选)。
+
+**集成/边界(按需 integration tier)**
+- T24 删除被引用版本后,相关 file 解析失败且错误可定位。
+- T25 画布改 DSL 生成新版本、已绑定方不受影响(B4 端到端)。
+- T26 切版本后 component params 重置为该版本 default(C3)。
+- T27 迁移在含 built-in + dataflow 混合库上的幂等重跑。
+- T30 并发保存同 canvas 不产生孤儿版本。
+- T31 alias 纯前端过滤不影响后端版本返回集。
+
+---
+
+- T32(v5.2 保存语义)`UpdateAgent` 带 `autosave:true` + DSL 变更 → 断言 `user_canvas_version` 行数**不变**、`user_canvas.dsl` 已更新为最新 DSL(不产生新版本)。
+- T33(v5.2 保存语义)`UpdateAgent` 手动 Save(无 `autosave`)→ 断言**新增一条 `user_canvas_version` 记录且 `user_canvas.dsl` 已更新**(即便 DSL 与上一版本相同也 INSERT 新行,不复用就地刷新;验证 user_canvas 更新与版本插入两者俱发生)。
+- T34(v5.2 统一路径)agent 画布自动保存同样不刷版本(与 dataflow 共用 `UpdateAgent`,断言行数不变)。
+- T35(v5.2 alias 写入)`PATCH /versions/{id}` 带 `alias` → 断言该行 `alias` 更新、未新建版本、DSL 不变;跨 canvas 改 alias → 归属校验拒绝。
+- T36(v5.2 alias 兜底)manual Save 请求携带 `alias` → 断言新建/刷新版本写入该 alias。
+- T37(v5.2 前端 latest 去除)dataset/file 版本选择器选项列表**不含** `__latest__` 伪值,且含 alias 文案;提交 `pipeline_version_id` 为具体 ID(前端/组件断言)。
+- T38(v5.2 对抗)连续 N 次自动保存(不刷版本)+ 仅 1 次手动 Save → 版本数恰为 1(非 N),且 live draft 反映最后一次自动保存内容;手动 Save 前后 `user_canvas_version` 记录数差恰为 1(确认 INSERT 而非 in-place 更新)。
+- T39(v5.4 空版本校验)dataset 创建/更新 Save 时 `pipeline_version_id` 为空(且为 Pipeline 模式)→ 后端**拒绝**并返错误文案“版本信息缺失”(HTTP 4xx),`pipeline_version_id` 不写入、不自动回填为 latest(呼应 C5/G3);对抗:built-in 模式允许空版本(空版本校验仅作用于 Pipeline 模式)。
+- T40(v5.4 空版本校验·file 层)document/file 绑定 Save 时 `pipeline_version_id` 为空(Pipeline 模式)→ 后端同样拒绝并返“版本信息缺失”;dataset 与 file 两层校验行为一致(C5 双层要求)。
+
+## 10. 漏洞审计(v4 状态)
+
+| 编号 | 描述 | 状态 |
+|---|---|---|
+| V1 | 版本未线程化到运行时(loadDSL 永远读最新) | **已修复设计**:§6 改读 `user_canvas_version.dsl` |
+| V2 | 拦截点不全(ad-hoc 路径漏校验) | 设计覆盖,待 T12 落实 |
+| V3 | 别名误建版本 | 设计:alias 仅字段,不改 SaveOrReplaceLatestTx 行为 |
+| V4 | `!` 与 Missing 不可区分 | 设计区分:`!`=outdated(可解析,提示);Missing=版本不存在(不可解析) |
+| V5 | C3 仅在 pipeline 变更触发 | 设计:C3 显式切版本即触发重置(§5 / T26) |
+| V6 | Missing 恢复 | 设计:重新选版本即恢复,无需特殊逻辑 |
+| V7 | 文件级 pipeline 绑定可编辑 | 已确认可编辑,document 级同套逻辑 |
+| H12 | `!` “最新”口径 | **v4 修正**:dataflow 无发布 → 用 `GetLatest`(create_time),非 `GetLatestReleased` |
+
+---
+
+## 11. 验收清单(核心断言)
+
+1. built-in parser 绑定:不受任何版本逻辑影响,`pipeline_version_id` 恒 NULL。
+2. dataflow 绑定默认锁“当时最新具体版本”,画布后续改动不传播到已绑定方(B4)。
+3. 删除被引用版本:引用方进入 Missing、file 不可解析;删除前有二次确认弹窗(B2/B2.1)。
+4. 非最新绑定显示 `!`,点击仅提示,不自动升级(D3)。
+5. 迁移幂等:存量 dataflow 绑定被锁定到 `GetLatest`;重跑安全;built-in/agent 跳过。
+6. 悬空/跨 canvas 的 `pipeline_version_id` 被拒绝或判 Missing(归属校验)。
+7. 别名仅存、仅前端过滤,后端版本返回集不受其影响。
+8. 空版本(Pipeline 模式 `pipeline_version_id` 为空):UI 红色 `Missing` 徽标;Save 时报错“版本信息缺失”且不写入、不自动回填;dataset 与 file 两层一致(C5/G3/T39/T40)。
+
+---
+
+## 12. 决策裁定(v5 已锁定,无未决项)
+
+- **A1 类别边界(已裁定:强制校验)**:绑定/运行时要求 `user_canvas.canvas_category == "dataflow_canvas"`。依据:`canvas_category` 是 `user_canvas` 真实字段(值 `dataflow_canvas`/`agent_canvas`);作为归属校验的强化。
+- **A2 文件级范围(已裁定:覆盖 document)**:`document` 表同样加 `pipeline_version_id` 并复用全套逻辑。依据:C1 原文“dataset/file”。
+- **A3 C3 重置范围(已裁定:整体重置)**:切版本时把 dataset/document 的 `parser_config`(component params)整体重置为该版本 default。依据:用户裁定 + C3 字面“参数重置为该版本 default”。(§5 已按此写)
+- **A4 删除语义(已裁定:允许删除→Missing)**:弹窗二次确认后允许删除,引用方进入 Missing。依据:用户裁定 + B2.1 文案“告知风险”。(§7 已按此写)
+- **A5 alias 约束(已裁定:不约束)**:自由文本、可空、不要求唯一。依据:A2 原文“仅存储、前端过滤”。
+- **A6 Missing 呈现(已裁定:禁用解析+提示重选)**:前端对 Missing(版本被删)禁用解析按钮并提示重新选版本;与 `!`(仍可解析、仅提示)区分。
+- **A7 ad-hoc/调试路径(已裁定:同正式解析带 version)**:`pipeline_executor.go` ad-hoc 路径已 reload `doc`(L888),同法透传 `doc.PipelineVersionID`。
+- **A8 脏数据回填(已裁定:跳过+日志)**:backfill 遇 canvas 无版本时跳过 + 日志告警,绝不写悬空 version_id。
+
+- **A9 保存语义修正范围(已裁定:作用于共享路径、全类别统一;用户确认 2026-10-22)**:手动/自动保存经 `autosave` 信号区分;版本创建仅限手动 Save,且手动 Save **同时**更新 `user_canvas` 并 **INSERT 新 `user_canvas_version` 记录**(agent 与 dataflow 一致);agent 发布语义(Publish)不受影响。依据:agent/dataflow 共用 `UpdateAgent`,修正必须落在共享路径;agent 手动 Save 仍建版本,仅自动保存收敛,属良性改进且不触及 §1 范围。
+
+> 设计已完全锁定,进入 §9 TDD 实现阶段。
+## 13. 对抗性测试强制规则(v5.1 新增)
+
+TDD 保证「代码满足测试」,不保证「测试满足需求」。本特性 review 暴露的 B1/B2 缺陷,根因不是 TDD 机制失效,而是**测试从需求派生的那一环失职**:fixture 全用了 `pinned == latest` 且两字段齐发,导致「钉住≠最新」这一 feature 核心场景从未被锻炼。
+
+**强制规则(每条需求一句对抗性测试):**
+1. **每条需求条款必须对应至少一条对抗性测试**,其 fixture 必须让该条款**可证伪**。若「实现错了测试也绿」,说明 fixture 没打到痛处,该条款未覆盖。
+2. **版本相关测试强制 `pinned != latest`**:凡涉及 `pipeline_version_id` 的测试,fixture 中钉住的版本必须明确不等于 `GetLatest`;并额外构造「钉住版本被后续新建版本挤成过时」的时序。
+3. **耦合字段必须测「只发其一」的 PATCH**:`pipeline_id` / `pipeline_version_id` 是耦合对,必须为「只发 version 省略 pipeline」「只发 pipeline 省略 version」「两者都省略」各写一条,断言省略字段沿用已绑值。
+4. **归属/权限边界必须负向测**:跨 canvas 的 `pipeline_version_id`、悬空 `pipeline_version_id`、agent canvas 误绑 dataflow 版本,必须各自返回 Missing/拒绝,而非静默回落。
+5. **回落链必须逐元素断言**:§5 的版本回落链与 canvas 上下文回落链,必须分别有测试证明「跳过已钉版本直接取 latest」会被拒、「省略 pipeline_id 让上下文变 nil」会被拒。
+
+§9 各 T 条目(T6/T7/T14/T26 等)须按上述规则补对抗性 fixture;新实现的 RED 测试若仅用 happy-path fixture,视为未达 TDD 门禁。
+
+6. **保存语义必须测 `autosave` 正反两例**:必须分别证明「`autosave:true` 不刷版本、仅更新 live draft」与「手动 Save 刷版本」;仅测手动 Save 而漏掉自动保存不刷版本的用例,视为未覆盖(对应 T32/T33/T38)。
diff --git a/internal/dao/database.go b/internal/dao/database.go
index da94c7ea15..56cd6784a3 100644
--- a/internal/dao/database.go
+++ b/internal/dao/database.go
@@ -268,6 +268,17 @@ func InitDB(ctx context.Context, migrateDB bool) error {
if err = migrateKnowledgeCompileQueues(ctx, DB); err != nil {
return fmt.Errorf("failed to split knowledge compilation queues: %w", err)
}
+
+ // Add pipeline_version_id columns and lock existing dataflow bindings to a
+ // version. Runs LAST so the shared migration marker only advances to
+ // v1.0.0-rc3.dev6 after every lower-target migration (notably the
+ // v1.0.0-rc3.dev5 tenant default-model column drop) has already run.
+ if err = MigrateDSLVersionColumns(ctx, DB); err != nil {
+ return fmt.Errorf("failed to add DSL version columns: %w", err)
+ }
+ if err = BackfillDSLVersionBindings(ctx, DB); err != nil {
+ return fmt.Errorf("failed to backfill DSL version bindings: %w", err)
+ }
common.Info("Database schema migrated successfully")
} else {
for _, column := range []string{"backlog_doc_ids", "inflight_doc_ids"} {
diff --git a/internal/dao/dsl_version_migration.go b/internal/dao/dsl_version_migration.go
new file mode 100644
index 0000000000..791e786705
--- /dev/null
+++ b/internal/dao/dsl_version_migration.go
@@ -0,0 +1,176 @@
+package dao
+
+import (
+ "context"
+ "fmt"
+
+ "ragflow/internal/common"
+
+ "go.uber.org/zap"
+ "gorm.io/gorm"
+)
+
+// dslVersionTargetVersion marks the backfill of pipeline_version_id bindings as
+// done. It sorts after every existing migration target version, so the step runs
+// exactly once and is skipped on later starts.
+const dslVersionTargetVersion = "v1.0.0-rc3.dev6"
+
+// migrateDSLVersionColumns adds the pipeline_version_id column to the tables that
+// bind a dataset (knowledgebase) or document to a dataflow canvas version, and
+// ensures user_canvas_version.alias exists (design A2/F1). It is
+// idempotent: an already-present column is left untouched, and a concurrent add
+// that loses the race to a duplicate-column error is tolerated.
+func MigrateDSLVersionColumns(ctx context.Context, db *gorm.DB) error {
+ for _, table := range []string{"knowledgebase", "document"} {
+ if !db.WithContext(ctx).Migrator().HasTable(table) {
+ continue
+ }
+ exists, err := columnExists(ctx, db, table, "pipeline_version_id")
+ if err != nil {
+ return fmt.Errorf("check %s.pipeline_version_id: %w", table, err)
+ }
+ if exists {
+ continue
+ }
+ if err := db.WithContext(ctx).Exec(fmt.Sprintf(
+ "ALTER TABLE %s ADD COLUMN pipeline_version_id varchar(32) NULL", table)).Error; err != nil {
+ if isDuplicateColumnError(err) {
+ continue
+ }
+ return fmt.Errorf("add %s.pipeline_version_id: %w", table, err)
+ }
+ common.Info("Added " + table + ".pipeline_version_id")
+ }
+
+ // The dataflow version table carries a free-text alias (design A2/F1). The
+ // column is defined on the entity and is normally created by AutoMigrate, but
+ // a database whose user_canvas_version table predates the column is missing
+ // it, which makes every version save fail with Error 1054. Add it explicitly
+ // and idempotently, mirroring the pipeline_version_id handling above.
+ if db.WithContext(ctx).Migrator().HasTable("user_canvas_version") {
+ exists, err := columnExists(ctx, db, "user_canvas_version", "alias")
+ if err != nil {
+ return fmt.Errorf("check user_canvas_version.alias: %w", err)
+ }
+ if !exists {
+ if err := db.WithContext(ctx).Exec(
+ "ALTER TABLE user_canvas_version ADD COLUMN alias varchar(255) NULL").Error; err != nil {
+ if !isDuplicateColumnError(err) {
+ return fmt.Errorf("add user_canvas_version.alias: %w", err)
+ }
+ } else {
+ common.Info("Added user_canvas_version.alias")
+ }
+ }
+ }
+ return nil
+}
+
+// backfillDSLVersionBindings locks every pre-existing dataflow-canvas binding to
+// the latest version of that canvas at migration time. It is gated by the shared
+// database migration-version marker so it runs once. Bindings to a built-in
+// parser id (no backing user_canvas), to a non-dataflow canvas, or to a canvas
+// that has no versions yet are left unbound; a dangling version id is never
+// written.
+func BackfillDSLVersionBindings(ctx context.Context, db *gorm.DB) error {
+ currentVersion, err := GetDatabaseMigrationVersion(ctx, db)
+ if err != nil {
+ return fmt.Errorf("read db migration version: %w", err)
+ }
+ if shouldSkipMigration(currentVersion, dslVersionTargetVersion) {
+ common.Info("DSL version bindings already backfilled, skipping",
+ zap.String("current_version", currentVersion),
+ zap.String("target_version", dslVersionTargetVersion))
+ return nil
+ }
+
+ tables := []string{"knowledgebase", "document"}
+ hasAny := false
+ for _, table := range tables {
+ if db.WithContext(ctx).Migrator().HasTable(table) {
+ hasAny = true
+ break
+ }
+ }
+ if !hasAny {
+ return setDatabaseMigrationVersion(ctx, db, dslVersionTargetVersion)
+ }
+
+ for _, table := range tables {
+ if !db.WithContext(ctx).Migrator().HasTable(table) {
+ continue
+ }
+ // Cache per-canvas resolution so a large table with few distinct canvases
+ // does not issue a GetByID + GetLatest round trip per row (N+1 during
+ // RunMigrations). The cached value is one of:
+ // skip=true -> not a dataflow canvas (or no versions): skip the binding
+ // skip=false -> versionID is the version to pin
+ type canvasResolution struct {
+ skip bool
+ versionID string
+ }
+ resolved := map[string]canvasResolution{}
+ resolveCanvas := func(canvasID string) canvasResolution {
+ if r, ok := resolved[canvasID]; ok {
+ return r
+ }
+ r := canvasResolution{skip: true}
+ canvas, cerr := NewUserCanvasDAO().GetByID(ctx, db, canvasID)
+ if cerr != nil || canvas == nil {
+ // Not a user canvas (e.g. a built-in parser id) -> no version binding.
+ resolved[canvasID] = r
+ return r
+ }
+ if canvas.CanvasCategory != "dataflow_canvas" {
+ // Only dataflow canvases carry versions; agent canvases are excluded.
+ resolved[canvasID] = r
+ return r
+ }
+ version, verr := NewUserCanvasVersionDAO().GetLatest(ctx, db, canvasID)
+ if verr != nil {
+ // Canvas has no versions yet -> leave unbound, never write a dangling id.
+ common.Warn("backfill: canvas has no versions, skipping binding",
+ zap.String("canvas_id", canvasID),
+ zap.String("table", table))
+ resolved[canvasID] = r
+ return r
+ }
+ r = canvasResolution{skip: false, versionID: version.ID}
+ resolved[canvasID] = r
+ return r
+ }
+
+ var rows []struct {
+ ID string `gorm:"column:id"`
+ PipelineID *string `gorm:"column:pipeline_id"`
+ }
+ result := db.WithContext(ctx).Table(table).
+ Where("pipeline_id IS NOT NULL AND pipeline_id <> ''").
+ Select("id, pipeline_id").
+ FindInBatches(&rows, 256, func(batchDB *gorm.DB, _ int) error {
+ return batchDB.Transaction(func(tx *gorm.DB) error {
+ for _, row := range rows {
+ if row.PipelineID == nil {
+ continue
+ }
+ res := resolveCanvas(*row.PipelineID)
+ if res.skip {
+ continue
+ }
+ if err := tx.Table(table).Where("id = ?", row.ID).Update("pipeline_version_id", res.versionID).Error; err != nil {
+ return fmt.Errorf("backfill update %s %s: %w", table, row.ID, err)
+ }
+ }
+ return nil
+ })
+ })
+ if result.Error != nil {
+ return fmt.Errorf("backfill %s: %w", table, result.Error)
+ }
+ }
+
+ if err := setDatabaseMigrationVersion(ctx, db, dslVersionTargetVersion); err != nil {
+ return fmt.Errorf("set db migration version %s: %w", dslVersionTargetVersion, err)
+ }
+ return nil
+}
diff --git a/internal/dao/dsl_version_migration_test.go b/internal/dao/dsl_version_migration_test.go
new file mode 100644
index 0000000000..1ab89f7d97
--- /dev/null
+++ b/internal/dao/dsl_version_migration_test.go
@@ -0,0 +1,333 @@
+//go:build integration
+// +build integration
+
+package dao
+
+import (
+ "context"
+ "os"
+ "testing"
+
+ "ragflow/internal/entity"
+
+ "gorm.io/gorm"
+)
+
+// openMigrationTestDB opens the throwaway MySQL database used by the DSL
+// version migration tests. It reuses the same dialect helper as the other
+// migration integration tests so DDL behaviour matches production MySQL.
+// Like them it skips when RAGFLOW_TEST_MYSQL_DSN is unset (the CI
+// integration job does not provision a throwaway MySQL), so the suite
+// stays green there instead of failing on a hardcoded localhost connect.
+func openMigrationTestDB(t *testing.T) *gorm.DB {
+ dsn := os.Getenv("RAGFLOW_TEST_MYSQL_DSN")
+ if dsn == "" {
+ t.Skip("RAGFLOW_TEST_MYSQL_DSN unset: this test needs a throwaway MySQL database")
+ }
+ db, err := gorm.Open(newMigrationAwareDialector(dsn), &gorm.Config{TranslateError: true})
+ if err != nil {
+ t.Fatalf("failed to connect to migration test database: %v", err)
+ }
+ return db
+}
+
+func strPtr(s string) *string { return &s }
+
+// T1: migrateDSLVersionColumns adds pipeline_version_id to knowledgebase and
+// document when the column is absent, and is a no-op (no error) on a second run.
+func TestMigrateDSLVersionColumns_AddsAndIdempotent(t *testing.T) {
+ db := openMigrationTestDB(t)
+ ctx := context.Background()
+
+ if err := db.WithContext(ctx).AutoMigrate(&entity.Knowledgebase{}, &entity.Document{}); err != nil {
+ t.Fatalf("automigrate: %v", err)
+ }
+ // Drop the column so we exercise the add path (AutoMigrate would otherwise
+ // have already created it because the entity now carries the field).
+ _ = db.WithContext(ctx).Exec("ALTER TABLE knowledgebase DROP COLUMN pipeline_version_id").Error
+ _ = db.WithContext(ctx).Exec("ALTER TABLE document DROP COLUMN pipeline_version_id").Error
+
+ if err := MigrateDSLVersionColumns(ctx, db); err != nil {
+ t.Fatalf("MigrateDSLVersionColumns: %v", err)
+ }
+ if !db.WithContext(ctx).Migrator().HasColumn(&entity.Knowledgebase{}, "pipeline_version_id") {
+ t.Fatal("knowledgebase.pipeline_version_id was not added")
+ }
+ if !db.WithContext(ctx).Migrator().HasColumn(&entity.Document{}, "pipeline_version_id") {
+ t.Fatal("document.pipeline_version_id was not added")
+ }
+
+ // Idempotent: column already present must not error (Error 1060 path).
+ if err := MigrateDSLVersionColumns(ctx, db); err != nil {
+ t.Fatalf("MigrateDSLVersionColumns second run: %v", err)
+ }
+}
+
+// seedDSLVersionTables resets the four relevant tables and clears the migration
+// version marker so backfill runs from scratch on every call.
+func seedDSLVersionTables(t *testing.T, db *gorm.DB) {
+ t.Helper()
+ ctx := context.Background()
+ // The shared integration database persists across runs, and another migration
+ // test aborts if knowledgebase (a tenant-model-id table) already exists. Drop
+ // every table we create so the suite stays isolated.
+ t.Cleanup(func() {
+ for _, m := range []interface{}{
+ &entity.UserCanvasVersion{}, &entity.UserCanvas{}, &entity.Document{}, &entity.Knowledgebase{},
+ } {
+ _ = db.WithContext(context.Background()).Migrator().DropTable(m)
+ }
+ })
+ for _, m := range []interface{}{
+ &entity.Knowledgebase{}, &entity.Document{}, &entity.UserCanvas{}, &entity.UserCanvasVersion{},
+ } {
+ _ = db.WithContext(ctx).Migrator().DropTable(m)
+ }
+ if err := db.WithContext(ctx).AutoMigrate(&entity.Knowledgebase{}, &entity.Document{}, &entity.UserCanvas{}, &entity.UserCanvasVersion{}, &entity.SystemSettings{}); err != nil {
+ t.Fatalf("automigrate: %v", err)
+ }
+ if err := db.WithContext(ctx).Exec("DELETE FROM system_settings WHERE name = ?", migrationDBVersionMarker).Error; err != nil {
+ t.Fatalf("clear version marker: %v", err)
+ }
+}
+
+// T2: backfill writes the latest version id for dataflow-canvas bindings and
+// skips agent-canvas and built-in bindings.
+func TestBackfillDSLVersionBindings_BindsDataflowSkipsAgentAndBuiltin(t *testing.T) {
+ db := openMigrationTestDB(t)
+ ctx := context.Background()
+ seedDSLVersionTables(t, db)
+
+ dfCanvas := "df-canvas-1"
+ dfVersion := "df-ver-1"
+ if err := db.WithContext(ctx).Create(&entity.UserCanvas{ID: dfCanvas, CanvasCategory: "dataflow_canvas", Title: strPtr("df")}).Error; err != nil {
+ t.Fatal(err)
+ }
+ if err := db.WithContext(ctx).Create(&entity.UserCanvasVersion{ID: dfVersion, UserCanvasID: dfCanvas, DSL: entity.JSONMap{"k": "v"}}).Error; err != nil {
+ t.Fatal(err)
+ }
+
+ agentCanvas := "agent-canvas-1"
+ agentVersion := "agent-ver-1"
+ db.WithContext(ctx).Create(&entity.UserCanvas{ID: agentCanvas, CanvasCategory: "agent_canvas", Title: strPtr("ag")})
+ db.WithContext(ctx).Create(&entity.UserCanvasVersion{ID: agentVersion, UserCanvasID: agentCanvas, DSL: entity.JSONMap{"k": "v"}})
+
+ builtin := "general"
+
+ db.WithContext(ctx).Create(&entity.Knowledgebase{ID: "kb-df", PipelineID: strPtr(dfCanvas)})
+ db.WithContext(ctx).Create(&entity.Knowledgebase{ID: "kb-agent", PipelineID: strPtr(agentCanvas)})
+ db.WithContext(ctx).Create(&entity.Knowledgebase{ID: "kb-builtin", PipelineID: strPtr(builtin)})
+ db.WithContext(ctx).Create(&entity.Document{ID: "doc-df", KbID: "kb-df", PipelineID: strPtr(dfCanvas), ParserConfig: entity.JSONMap{}})
+ db.WithContext(ctx).Create(&entity.Document{ID: "doc-builtin", KbID: "kb-builtin2", PipelineID: strPtr(builtin), ParserConfig: entity.JSONMap{}})
+
+ if err := BackfillDSLVersionBindings(ctx, db); err != nil {
+ t.Fatalf("BackfillDSLVersionBindings: %v", err)
+ }
+
+ var gotDF, gotAgent, gotBuiltin entity.Knowledgebase
+ db.WithContext(ctx).First(&gotDF, "id = ?", "kb-df")
+ db.WithContext(ctx).First(&gotAgent, "id = ?", "kb-agent")
+ db.WithContext(ctx).First(&gotBuiltin, "id = ?", "kb-builtin")
+ if gotDF.PipelineVersionID == nil || *gotDF.PipelineVersionID != dfVersion {
+ t.Fatalf("kb-df pipeline_version_id = %v, want %s", gotDF.PipelineVersionID, dfVersion)
+ }
+ if gotAgent.PipelineVersionID != nil {
+ t.Fatalf("kb-agent must stay nil (agent canvas), got %v", *gotAgent.PipelineVersionID)
+ }
+ if gotBuiltin.PipelineVersionID != nil {
+ t.Fatalf("kb-builtin must stay nil (built-in), got %v", *gotBuiltin.PipelineVersionID)
+ }
+
+ var gotDocDF, gotDocBuiltin entity.Document
+ db.WithContext(ctx).First(&gotDocDF, "id = ?", "doc-df")
+ db.WithContext(ctx).First(&gotDocBuiltin, "id = ?", "doc-builtin")
+ if gotDocDF.PipelineVersionID == nil || *gotDocDF.PipelineVersionID != dfVersion {
+ t.Fatalf("doc-df pipeline_version_id = %v, want %s", gotDocDF.PipelineVersionID, dfVersion)
+ }
+ if gotDocBuiltin.PipelineVersionID != nil {
+ t.Fatalf("doc-builtin must stay nil (built-in), got %v", *gotDocBuiltin.PipelineVersionID)
+ }
+
+ // Idempotency: a second run must not change or error.
+ if err := BackfillDSLVersionBindings(ctx, db); err != nil {
+ t.Fatalf("BackfillDSLVersionBindings second run: %v", err)
+ }
+ var gotDFAgain entity.Knowledgebase
+ db.WithContext(ctx).First(&gotDFAgain, "id = ?", "kb-df")
+ if *gotDFAgain.PipelineVersionID != dfVersion {
+ t.Fatalf("kb-df changed after second backfill: %v", *gotDFAgain.PipelineVersionID)
+ }
+}
+
+// T17: a pre-existing (存量) dataflow binding is locked to the LATEST version by
+// create_time, even when an older version exists.
+func TestBackfillDSLVersionBindings_LocksLatestVersionByCreateTime(t *testing.T) {
+ db := openMigrationTestDB(t)
+ ctx := context.Background()
+ seedDSLVersionTables(t, db)
+
+ canvas := "df-canvas-order"
+ db.WithContext(ctx).Create(&entity.UserCanvas{ID: canvas, CanvasCategory: "dataflow_canvas", Title: strPtr("df")})
+ // Older version created first (earlier create_time), newer version created
+ // second; GetLatest returns the newer. Explicit create_time makes the order
+ // deterministic (two rows without it can share the same millisecond).
+ oldCT, newCT := int64(100), int64(200)
+ db.WithContext(ctx).Create(&entity.UserCanvasVersion{ID: "ver-old", UserCanvasID: canvas, DSL: entity.JSONMap{"v": 1}, CreateTime: &oldCT})
+ db.WithContext(ctx).Create(&entity.UserCanvasVersion{ID: "ver-new", UserCanvasID: canvas, DSL: entity.JSONMap{"v": 2}, CreateTime: &newCT})
+
+ db.WithContext(ctx).Create(&entity.Knowledgebase{ID: "kb-order", PipelineID: strPtr(canvas)})
+
+ if err := BackfillDSLVersionBindings(ctx, db); err != nil {
+ t.Fatalf("BackfillDSLVersionBindings: %v", err)
+ }
+ var got entity.Knowledgebase
+ db.WithContext(ctx).First(&got, "id = ?", "kb-order")
+ if got.PipelineVersionID == nil || *got.PipelineVersionID != "ver-new" {
+ t.Fatalf("kb-order pipeline_version_id = %v, want ver-new", got.PipelineVersionID)
+ }
+}
+
+// T18: a dataflow canvas bound via pipeline_id but carrying NO versions yet must
+// stay unbound. Writing a dangling version id would break the not-dangling
+// invariant, so the backfill skips it and leaves pipeline_version_id NULL.
+func TestBackfillDSLVersionBindings_NoVersionsStaysNil(t *testing.T) {
+ db := openMigrationTestDB(t)
+ ctx := context.Background()
+ seedDSLVersionTables(t, db)
+
+ canvas := "df-canvas-nover"
+ if err := db.WithContext(ctx).Create(&entity.UserCanvas{ID: canvas, CanvasCategory: "dataflow_canvas", Title: strPtr("df")}).Error; err != nil {
+ t.Fatal(err)
+ }
+ // Intentionally no UserCanvasVersion rows for this canvas.
+ db.WithContext(ctx).Create(&entity.Knowledgebase{ID: "kb-nover", PipelineID: strPtr(canvas)})
+
+ if err := BackfillDSLVersionBindings(ctx, db); err != nil {
+ t.Fatalf("BackfillDSLVersionBindings: %v", err)
+ }
+ var got entity.Knowledgebase
+ db.WithContext(ctx).First(&got, "id = ?", "kb-nover")
+ if got.PipelineVersionID != nil {
+ t.Fatalf("kb-nover must stay nil when canvas has no versions, got %v", *got.PipelineVersionID)
+ }
+}
+
+// T16: built-in pipelines are unaffected by any version logic. A built-in
+// pipeline_id string with no backing user_canvas keeps pipeline_version_id NULL,
+// and a knowledge base with no pipeline at all stays NULL too.
+func TestBackfillDSLVersionBindings_BuiltinUnaffected(t *testing.T) {
+ db := openMigrationTestDB(t)
+ ctx := context.Background()
+ seedDSLVersionTables(t, db)
+
+ builtin := "naive"
+ db.WithContext(ctx).Create(&entity.Knowledgebase{ID: "kb-builtin2", PipelineID: strPtr(builtin)})
+ db.WithContext(ctx).Create(&entity.Knowledgebase{ID: "kb-none", PipelineID: nil})
+
+ if err := BackfillDSLVersionBindings(ctx, db); err != nil {
+ t.Fatalf("BackfillDSLVersionBindings: %v", err)
+ }
+ var gotBuiltin, gotNone entity.Knowledgebase
+ db.WithContext(ctx).First(&gotBuiltin, "id = ?", "kb-builtin2")
+ db.WithContext(ctx).First(&gotNone, "id = ?", "kb-none")
+ if gotBuiltin.PipelineID == nil || *gotBuiltin.PipelineID != builtin {
+ t.Fatalf("built-in pipeline_id must be preserved, got %v", gotBuiltin.PipelineID)
+ }
+ if gotBuiltin.PipelineVersionID != nil {
+ t.Fatalf("built-in must not get a version id, got %v", *gotBuiltin.PipelineVersionID)
+ }
+ if gotNone.PipelineVersionID != nil {
+ t.Fatalf("kb with no pipeline must stay nil, got %v", *gotNone.PipelineVersionID)
+ }
+}
+
+// TestOpenMigrationTestDB_SkipsWhenDSNUnset locks the CI contract: when
+// RAGFLOW_TEST_MYSQL_DSN is unset the migration helper must SKIP (never attempt
+// a hardcoded localhost connection and fail). The ragflow_go_integration job does
+// not provision a throwaway MySQL, so a non-skipping helper turns every DSL
+// version migration test red there (matches migration_integration_test.go).
+func TestOpenMigrationTestDB_SkipsWhenDSNUnset(t *testing.T) {
+ if os.Getenv("RAGFLOW_TEST_MYSQL_DSN") != "" {
+ t.Skip("this probe requires RAGFLOW_TEST_MYSQL_DSN to be unset")
+ }
+ returned := false
+ ok := t.Run("probe", func(st *testing.T) {
+ openMigrationTestDB(st)
+ returned = true // reached only when the helper did NOT skip or fail
+ })
+ if returned {
+ t.Fatalf("openMigrationTestDB returned a DB instead of skipping when RAGFLOW_TEST_MYSQL_DSN is unset")
+ }
+ if !ok {
+ t.Fatalf("probe subtest failed instead of skipping when RAGFLOW_TEST_MYSQL_DSN is unset")
+ }
+}
+
+// T1b: MigrateDSLVersionColumns also adds the user_canvas_version.alias column
+// (design A2/F1) so a version save never fails with Error 1054 on a database
+// whose table predates the column. Idempotent on a second run.
+func TestMigrateDSLVersionColumns_AddsAliasColumnIdempotent(t *testing.T) {
+ db := openMigrationTestDB(t)
+ ctx := context.Background()
+
+ if err := db.WithContext(ctx).AutoMigrate(&entity.UserCanvasVersion{}); err != nil {
+ t.Fatalf("automigrate: %v", err)
+ }
+ // Drop the alias column so we exercise the add path (AutoMigrate would
+ // otherwise have already created it because the entity carries the field).
+ _ = db.WithContext(ctx).Exec("ALTER TABLE user_canvas_version DROP COLUMN alias").Error
+ if db.WithContext(ctx).Migrator().HasColumn(&entity.UserCanvasVersion{}, "alias") {
+ t.Fatal("precondition: alias column should be absent before migration")
+ }
+
+ if err := MigrateDSLVersionColumns(ctx, db); err != nil {
+ t.Fatalf("MigrateDSLVersionColumns: %v", err)
+ }
+ if !db.WithContext(ctx).Migrator().HasColumn(&entity.UserCanvasVersion{}, "alias") {
+ t.Fatal("user_canvas_version.alias was not added")
+ }
+
+ // Idempotent: column already present must not error.
+ if err := MigrateDSLVersionColumns(ctx, db); err != nil {
+ t.Fatalf("MigrateDSLVersionColumns second run: %v", err)
+ }
+}
+
+// T19: many rows sharing the same dataflow canvas must all pin the SAME latest
+// version. This exercises the per-canvas resolution cache: the canvas lookup and
+// GetLatest must be resolved once and reused, so the result is consistent across
+// every row (no row ends up pinned to a stale version due to cached-state reuse).
+func TestBackfillDSLVersionBindings_CachesSharedCanvas(t *testing.T) {
+ db := openMigrationTestDB(t)
+ ctx := context.Background()
+ seedDSLVersionTables(t, db)
+
+ canvas := "df-canvas-shared"
+ if err := db.WithContext(ctx).Create(&entity.UserCanvas{ID: canvas, CanvasCategory: "dataflow_canvas", Title: strPtr("df")}).Error; err != nil {
+ t.Fatal(err)
+ }
+ oldCT, newCT := int64(100), int64(200)
+ db.WithContext(ctx).Create(&entity.UserCanvasVersion{ID: "ver-old", UserCanvasID: canvas, DSL: entity.JSONMap{"v": 1}, CreateTime: &oldCT})
+ db.WithContext(ctx).Create(&entity.UserCanvasVersion{ID: "ver-new", UserCanvasID: canvas, DSL: entity.JSONMap{"v": 2}, CreateTime: &newCT})
+
+ // 5 knowledge bases bound to the same canvas, exercising the cache path.
+ for i := 0; i < 5; i++ {
+ if err := db.WithContext(ctx).Create(&entity.Knowledgebase{ID: "kb-shared-" + string(rune('0'+i)), PipelineID: strPtr(canvas)}).Error; err != nil {
+ t.Fatal(err)
+ }
+ }
+
+ if err := BackfillDSLVersionBindings(ctx, db); err != nil {
+ t.Fatalf("BackfillDSLVersionBindings: %v", err)
+ }
+ var kbs []entity.Knowledgebase
+ db.WithContext(ctx).Where("id LIKE ?", "kb-shared-%").Find(&kbs)
+ if len(kbs) != 5 {
+ t.Fatalf("got %d shared kbs, want 5", len(kbs))
+ }
+ for _, kb := range kbs {
+ if kb.PipelineVersionID == nil || *kb.PipelineVersionID != "ver-new" {
+ t.Fatalf("kb %s pipeline_version_id = %v, want ver-new", kb.ID, kb.PipelineVersionID)
+ }
+ }
+}
diff --git a/internal/dao/kb.go b/internal/dao/kb.go
index 49e2d42396..413591b597 100644
--- a/internal/dao/kb.go
+++ b/internal/dao/kb.go
@@ -265,13 +265,13 @@ func (dao *KnowledgebaseDAO) ListByQuery(ctx context.Context, query *gorm.DB, ow
query = query.WithContext(ctx).
Select(`knowledgebase.id, knowledgebase.avatar, knowledgebase.name,
- knowledgebase.language, knowledgebase.description, knowledgebase.tenant_id,
- knowledgebase.permission, knowledgebase.doc_num, knowledgebase.token_num,
- knowledgebase.chunk_num, knowledgebase.similarity_threshold,
- knowledgebase.vector_similarity_weight, knowledgebase.parser_id, knowledgebase.parser_config,
- knowledgebase.pagerank, knowledgebase.embd_id,
- knowledgebase.tenant_embd_id,
- user.nickname, user.avatar as tenant_avatar, knowledgebase.update_time`).
+ knowledgebase.language, knowledgebase.description, knowledgebase.tenant_id,
+ knowledgebase.permission, knowledgebase.doc_num, knowledgebase.token_num,
+ knowledgebase.chunk_num, knowledgebase.similarity_threshold,
+ knowledgebase.vector_similarity_weight, knowledgebase.parser_id, knowledgebase.parser_config,
+ knowledgebase.pagerank, knowledgebase.embd_id,
+ knowledgebase.tenant_embd_id, knowledgebase.pipeline_id, knowledgebase.pipeline_version_id,
+ user.nickname, user.avatar as tenant_avatar, knowledgebase.update_time`).
Joins("LEFT JOIN user ON knowledgebase.tenant_id = user.id").
Where("knowledgebase.status = ?", string(entity.StatusValid))
diff --git a/internal/dao/migration.go b/internal/dao/migration.go
index aa42293cd8..569014fe25 100644
--- a/internal/dao/migration.go
+++ b/internal/dao/migration.go
@@ -80,10 +80,41 @@ func RunMigrations(ctx context.Context, db *gorm.DB) error {
return fmt.Errorf("failed to migrate tenant model data: %w", err)
}
+ // Drop the unused tenant-level model group tables. Failover is configured
+ // per conversation instead, so nothing reads or writes these any more.
+ if err := dropModelGroupTables(ctx, db); err != nil {
+ return fmt.Errorf("failed to drop tenant model group tables: %w", err)
+ }
+
common.Info("All manual migrations completed successfully")
return nil
}
+// dropModelGroupTables removes tenant_model_group and
+// tenant_model_group_mapping.
+//
+// The tables were created by AutoMigrate for a tenant-scoped failover-group
+// feature that was never shipped: no service read them, and the per-conversation
+// failover path replaced the concept entirely. Their Go definitions are gone, so
+// without this they would linger in every existing database with no way to remove
+// them. AutoMigrate cannot express a drop, hence the explicit migration.
+//
+// Guarded by HasTable so a database that never had them is a no-op, and
+// mapping-first because it references the group table.
+func dropModelGroupTables(ctx context.Context, db *gorm.DB) error {
+ migrator := db.WithContext(ctx).Migrator()
+ for _, table := range []string{"tenant_model_group_mapping", "tenant_model_group"} {
+ if !migrator.HasTable(table) {
+ continue
+ }
+ if err := migrator.DropTable(table); err != nil {
+ return fmt.Errorf("drop %s: %w", table, err)
+ }
+ common.Info("Dropped unused table", zap.String("table", table))
+ }
+ return nil
+}
+
// migrateTenantLLMPrimaryKey migrates tenant_llm from its legacy composite
// primary key (tenant_id, llm_factory, llm_name) to a surrogate auto-increment
// "id" column.
diff --git a/internal/dao/user_canvas_version.go b/internal/dao/user_canvas_version.go
index ec2717488d..2177db6109 100644
--- a/internal/dao/user_canvas_version.go
+++ b/internal/dao/user_canvas_version.go
@@ -18,7 +18,9 @@ package dao
import (
"context"
+ "encoding/json"
"errors"
+ "fmt"
"reflect"
"gorm.io/gorm"
@@ -31,6 +33,85 @@ import (
// canvas id yields no rows. Service and handler layers map this to a 404.
var ErrUserCanvasVersionNotFound = errors.New("user_canvas_version: not found")
+// ErrPipelineVersionMissing indicates the requested pipeline_version_id does
+// not exist or does not belong to the bound canvas. Callers treat this as a
+// Missing state: the file cannot be parsed until a valid version is (re)selected.
+// It is defined once here in the dao layer so that the service and task layers
+// (which re-export it) share a single sentinel and error checks match across
+// all layers (no duplicate errors.New with the same message but different
+// identity).
+var ErrPipelineVersionMissing = errors.New("pipeline version missing or not owned by canvas")
+
+// ErrPipelineVersionEmpty is returned when a dataset or document is saved in
+// Pipeline (dataflow canvas) mode but carries no concrete pinned version
+// (pipeline_version_id is empty / not selected). Per design C5/G3 the empty
+// version is no longer auto-backfilled to the canvas latest; instead the Save is
+// rejected so the UI can surface the red "Missing" badge and the
+// "版本信息缺失" error. BuiltIn mode (no canvas bound) is exempt.
+var ErrPipelineVersionEmpty = errors.New("版本信息缺失")
+
+// userFacingVersionHint is appended to every Missing-state error so the runtime
+// parse path can surface a human-readable instruction (design section 6.2, C4).
+const userFacingVersionHint = "pipeline 版本不存在,请重新选择版本"
+
+// MaxCanvasVersions is the per-canvas cap on the number of DSL versions (K=64,
+// design: limit the number of versions of a DSL). When a canvas already holds
+// this many versions, any write that would create a NEW version row is rejected
+// so the user is forced to delete old unused versions first. The cap counts
+// every version row (published or not); in-place DSL refreshes never consume
+// the budget because they do not insert a row.
+const MaxCanvasVersions = 64
+
+// ErrCanvasVersionLimitExceeded is returned by SaveOrReplaceLatestTx when a new
+// version write would exceed MaxCanvasVersions. The handler surfaces it to the
+// frontend as a data error with this user-facing hint.
+var ErrCanvasVersionLimitExceeded = errors.New("版本数已达上限(最多 64 个),请删除旧的不再使用的版本")
+
+// LoadCanvasVersionDSL resolves the DSL for a dataflow canvas version. When
+// versionID is non-empty it pins that exact version; when empty it resolves the
+// latest published version. A missing, mis-owned, or empty-DSL version returns
+// ErrPipelineVersionMissing so callers can surface a Missing (unparseable) state.
+// Both the service (component-param resolution) and task (runtime parse) layers
+// delegate here, so the resolution logic and its error contract live in one place.
+func LoadCanvasVersionDSL(ctx context.Context, db *gorm.DB, canvasID, versionID string) ([]byte, error) {
+ versionDAO := NewUserCanvasVersionDAO()
+ if versionID != "" {
+ v, err := versionDAO.GetByID(ctx, db, versionID)
+ if err != nil {
+ if errors.Is(err, ErrUserCanvasVersionNotFound) {
+ return nil, fmt.Errorf("%s (version %s): %w", userFacingVersionHint, versionID, ErrPipelineVersionMissing)
+ }
+ return nil, fmt.Errorf("load pipeline version %s: %w", versionID, err)
+ }
+ if v.UserCanvasID != canvasID {
+ return nil, fmt.Errorf("%s (version %s does not belong to canvas %s): %w", userFacingVersionHint, versionID, canvasID, ErrPipelineVersionMissing)
+ }
+ if len(v.DSL) == 0 {
+ return nil, fmt.Errorf("%s (version %s has no DSL): %w", userFacingVersionHint, versionID, ErrPipelineVersionMissing)
+ }
+ return marshalCanvasVersionDSL(versionID, v.DSL)
+ }
+ v, err := versionDAO.GetLatest(ctx, db, canvasID)
+ if err != nil {
+ if errors.Is(err, ErrUserCanvasVersionNotFound) {
+ return nil, fmt.Errorf("%s (canvas %s has no published version): %w", userFacingVersionHint, canvasID, ErrPipelineVersionMissing)
+ }
+ return nil, fmt.Errorf("load latest version for canvas %s: %w", canvasID, err)
+ }
+ if len(v.DSL) == 0 {
+ return nil, fmt.Errorf("%s (latest version %s has no DSL): %w", userFacingVersionHint, v.ID, ErrPipelineVersionMissing)
+ }
+ return marshalCanvasVersionDSL(v.ID, v.DSL)
+}
+
+func marshalCanvasVersionDSL(versionID string, dsl entity.JSONMap) ([]byte, error) {
+ raw, err := json.Marshal(dsl)
+ if err != nil {
+ return nil, fmt.Errorf("marshal canvas version %s DSL: %w", versionID, err)
+ }
+ return raw, nil
+}
+
// UserCanvasVersionDAO persists and queries UserCanvasVersion rows.
type UserCanvasVersionDAO struct{}
@@ -40,9 +121,15 @@ type SaveOrReplaceLatestVersionOptions struct {
UserCanvasID string
Title *string
Description *string
+ Alias *string
DSL entity.JSONMap
Release bool
SameDSL func(entity.JSONMap) bool
+ // ForceNew bypasses the same-DSL in-place refresh so a manual Save always
+ // INSERTs a fresh version row (design §5.1: every manual Save yields a new
+ // version, even when the DSL is byte-identical to the previous one). When
+ // false, an unchanged DSL refreshes the latest row in place as before.
+ ForceNew bool
}
// NewUserCanvasVersionDAO returns a zero-value DAO. The struct is stateless
@@ -92,6 +179,38 @@ func (dao *UserCanvasVersionDAO) GetLatest(ctx context.Context, db *gorm.DB, can
return &v, nil
}
+// LatestIDsByCanvasIDs returns the latest version id (by create_time DESC,
+// matching GetLatest) for each of the given canvas ids in a single query.
+// Canvases with no version rows are absent from the map. List endpoints use it
+// to resolve every row's "is the pinned version still the latest" flag without
+// an N+1 of per-row GetLatest calls.
+func (dao *UserCanvasVersionDAO) LatestIDsByCanvasIDs(ctx context.Context, db *gorm.DB, canvasIDs []string) (map[string]string, error) {
+ out := make(map[string]string, len(canvasIDs))
+ if len(canvasIDs) == 0 {
+ return out, nil
+ }
+ type row struct {
+ UserCanvasID string
+ ID string
+ }
+ var rows []row
+ if err := db.WithContext(ctx).Model(&entity.UserCanvasVersion{}).
+ Select("user_canvas_id, id").
+ Where("user_canvas_id IN ?", canvasIDs).
+ Order("create_time DESC").
+ Find(&rows).Error; err != nil {
+ return nil, err
+ }
+ // Rows arrive newest-first globally, so the first row seen per canvas is its
+ // latest version.
+ for _, r := range rows {
+ if _, ok := out[r.UserCanvasID]; !ok {
+ out[r.UserCanvasID] = r.ID
+ }
+ }
+ return out, nil
+}
+
// GetLatestReleased returns the most recently updated released version of
// canvasID, or ErrUserCanvasVersionNotFound when nothing was ever published.
// Mirrors the released-version lookup in Python's get_agent handler.
@@ -143,6 +262,31 @@ func (dao *UserCanvasVersionDAO) DeleteTx(ctx context.Context, tx *gorm.DB, id s
return tx.WithContext(ctx).Where("id = ?", id).Delete(&entity.UserCanvasVersion{}).Error
}
+// pipelineVersionReferenceTables are the tables that can pin a canvas
+// version through their pipeline_version_id column (design B4 sticky
+// snapshot). The reference scan on delete is scoped to exactly these
+// (design section 12 A4).
+var pipelineVersionReferenceTables = []string{"knowledgebase", "document"}
+
+// CountPipelineVersionReferences returns how many rows across the version
+// reference tables pin the given version. Used by DeleteVersion so callers
+// can warn that deleting the version will leave those bindings in a Missing
+// state (design section 6.2 / A4).
+func (dao *UserCanvasVersionDAO) CountPipelineVersionReferences(ctx context.Context, db *gorm.DB, versionID string) (int64, error) {
+ var total int64
+ for _, table := range pipelineVersionReferenceTables {
+ var n int64
+ if err := db.WithContext(ctx).
+ Table(table).
+ Where("pipeline_version_id = ?", versionID).
+ Count(&n).Error; err != nil {
+ return 0, fmt.Errorf("count %s references for version %s: %w", table, versionID, err)
+ }
+ total += n
+ }
+ return total, nil
+}
+
// DeleteByCanvasIDTx is the transactional variant of DeleteByCanvasID.
// Used by service.AgentService.DeleteAgent so the cascade runs atomically
// with the parent canvas row removal.
@@ -156,6 +300,45 @@ func (dao *UserCanvasVersionDAO) CreateTx(ctx context.Context, tx *gorm.DB, v *e
return tx.WithContext(ctx).Create(v).Error
}
+// UserCanvasVersionPatch carries the mutable metadata fields a version PATCH
+// may change. All fields are optional; only non-nil fields are written, so a
+// caller may update just the alias while leaving title/description untouched.
+type UserCanvasVersionPatch struct {
+ Alias *string
+ Title *string
+ Description *string
+}
+
+// UpdateTx updates mutable metadata fields of an existing version (alias,
+// title, description) without touching its DSL or creating a new version. It
+// is the backing store for the version PATCH endpoint (design G2/§4.4): alias
+// editing must never produce a new version row or alter the pinned DSL. When
+// the patch is empty it is a no-op. Returns ErrUserCanvasVersionNotFound when
+// the target row does not exist.
+func (dao *UserCanvasVersionDAO) UpdateTx(ctx context.Context, tx *gorm.DB, id string, patch UserCanvasVersionPatch) error {
+ updates := map[string]interface{}{}
+ if patch.Alias != nil {
+ updates["alias"] = patch.Alias
+ }
+ if patch.Title != nil {
+ updates["title"] = patch.Title
+ }
+ if patch.Description != nil {
+ updates["description"] = patch.Description
+ }
+ if len(updates) == 0 {
+ return nil
+ }
+ res := tx.WithContext(ctx).Model(&entity.UserCanvasVersion{}).Where("id = ?", id).Updates(updates)
+ if res.Error != nil {
+ return res.Error
+ }
+ if res.RowsAffected == 0 {
+ return ErrUserCanvasVersionNotFound
+ }
+ return nil
+}
+
// SaveOrReplaceLatestTx inserts or refreshes a version using the caller's
// transaction.
func (dao *UserCanvasVersionDAO) SaveOrReplaceLatestTx(ctx context.Context, tx *gorm.DB, opts SaveOrReplaceLatestVersionOptions) (*entity.UserCanvasVersion, error) {
@@ -178,7 +361,7 @@ func (dao *UserCanvasVersionDAO) SaveOrReplaceLatestTx(ctx context.Context, tx *
if !errors.Is(err, gorm.ErrRecordNotFound) {
return nil, err
}
- } else if opts.sameDSL(latest.DSL) {
+ } else if !opts.ForceNew && opts.sameDSL(latest.DSL) {
if !latest.Release || opts.Release {
updates := map[string]interface{}{
"dsl": opts.DSL,
@@ -190,6 +373,9 @@ func (dao *UserCanvasVersionDAO) SaveOrReplaceLatestTx(ctx context.Context, tx *
if opts.Description != nil {
updates["description"] = opts.Description
}
+ if opts.Alias != nil {
+ updates["alias"] = opts.Alias
+ }
if err = tx.WithContext(ctx).Model(&entity.UserCanvasVersion{}).
Where("id = ?", latest.ID).
Updates(updates).Error; err != nil {
@@ -206,11 +392,27 @@ func (dao *UserCanvasVersionDAO) SaveOrReplaceLatestTx(ctx context.Context, tx *
return &latest, nil
}
}
+ // Reaching this point means we are about to INSERT a NEW version row (the
+ // in-place refresh branch above never gets here). Enforce the per-canvas
+ // version cap: reject the write once the canvas already holds MaxCanvasVersions
+ // rows so the user must delete old unused versions first. Counting all rows
+ // (published and unpublished) keeps the budget honest -- the unpublished
+ // excess trim below only ever removes unpublished rows and never frees the cap.
+ var existing int64
+ if err = tx.WithContext(ctx).Model(&entity.UserCanvasVersion{}).
+ Where("user_canvas_id = ?", opts.UserCanvasID).
+ Count(&existing).Error; err != nil {
+ return nil, err
+ }
+ if existing >= MaxCanvasVersions {
+ return nil, ErrCanvasVersionLimitExceeded
+ }
row := &entity.UserCanvasVersion{
ID: opts.NewID,
UserCanvasID: opts.UserCanvasID,
Title: opts.Title,
Description: opts.Description,
+ Alias: opts.Alias,
Release: opts.Release,
DSL: opts.DSL,
}
diff --git a/internal/dao/user_canvas_version_keepall_test.go b/internal/dao/user_canvas_version_keepall_test.go
new file mode 100644
index 0000000000..a9088fe7fd
--- /dev/null
+++ b/internal/dao/user_canvas_version_keepall_test.go
@@ -0,0 +1,87 @@
+package dao
+
+import (
+ "context"
+ "fmt"
+ "testing"
+
+ "github.com/glebarez/sqlite"
+ "gorm.io/gorm"
+
+ "ragflow/internal/entity"
+)
+
+// TestCanvasVersionKeepAllRetainsUnpublished verifies the design decision to keep
+// every version row (published or unpublished) instead of auto-trimming old draft
+// versions. Inserting more draft versions than the old 20-row trim limit must
+// retain them all rather than deleting the oldest.
+func TestCanvasVersionKeepAllRetainsUnpublished(t *testing.T) {
+ db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+ if err != nil {
+ t.Fatalf("open db: %v", err)
+ }
+ if err := db.AutoMigrate(&entity.UserCanvas{}, &entity.UserCanvasVersion{}); err != nil {
+ t.Fatalf("migrate: %v", err)
+ }
+ const canvasID = "keepall"
+ seedCanvasLimit(t, db, canvasID)
+
+ d := NewUserCanvasVersionDAO()
+ const n = 30
+ oldestID := canvasID + "-v-0"
+ for i := 0; i < n; i++ {
+ id := fmt.Sprintf("%s-v-%d", canvasID, i)
+ if _, err := d.SaveOrReplaceLatestTx(context.Background(), db, SaveOrReplaceLatestVersionOptions{
+ NewID: id,
+ UserCanvasID: canvasID,
+ Title: ptrStr("draft"),
+ DSL: entity.JSONMap{"n": i}, // distinct DSL -> create branch
+ Release: false, // unpublished / draft
+ ForceNew: true,
+ }); err != nil {
+ t.Fatalf("save %d: %v", i, err)
+ }
+ }
+
+ got := countVersions(t, db, canvasID)
+ if got != n {
+ t.Fatalf("keep-all: expected all %d unpublished versions retained, got %d (trimming still active?)\n", n, got)
+ }
+ // The oldest draft must still be reachable: keep-all never auto-deletes rows.
+ var oldest entity.UserCanvasVersion
+ if err := db.WithContext(context.Background()).Where("id = ?", oldestID).First(&oldest).Error; err != nil {
+ t.Fatalf("oldest draft %s was auto-deleted: %v", oldestID, err)
+ }
+}
+
+// TestCanvasVersionKeepAllRetainsBeyondOldTrim inserts past the old 20-row trim
+// boundary plus one and confirms growth is unbounded (bounded only by K=64).
+func TestCanvasVersionKeepAllRetainsBeyondOldTrim(t *testing.T) {
+ db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+ if err != nil {
+ t.Fatalf("open db: %v", err)
+ }
+ if err := db.AutoMigrate(&entity.UserCanvas{}, &entity.UserCanvasVersion{}); err != nil {
+ t.Fatalf("migrate: %v", err)
+ }
+ const canvasID = "keepall-extra"
+ seedCanvasLimit(t, db, canvasID)
+
+ d := NewUserCanvasVersionDAO()
+ const n = 21
+ for i := 0; i < n; i++ {
+ if _, err := d.SaveOrReplaceLatestTx(context.Background(), db, SaveOrReplaceLatestVersionOptions{
+ NewID: fmt.Sprintf("%s-v-%d", canvasID, i),
+ UserCanvasID: canvasID,
+ Title: ptrStr("draft"),
+ DSL: entity.JSONMap{"n": i},
+ Release: false,
+ ForceNew: true,
+ }); err != nil {
+ t.Fatalf("save %d: %v", i, err)
+ }
+ }
+ if got := countVersions(t, db, canvasID); got != n {
+ t.Fatalf("keep-all: expected %d retained, got %d (old 20-row trim still active?)\n", n, got)
+ }
+}
diff --git a/internal/dao/user_canvas_version_limit_test.go b/internal/dao/user_canvas_version_limit_test.go
new file mode 100644
index 0000000000..a4d5699312
--- /dev/null
+++ b/internal/dao/user_canvas_version_limit_test.go
@@ -0,0 +1,222 @@
+package dao
+
+import (
+ "context"
+ "errors"
+ "fmt"
+ "strings"
+ "testing"
+
+ "github.com/glebarez/sqlite"
+ "gorm.io/gorm"
+
+ "ragflow/internal/entity"
+)
+
+// seedCanvas creates the parent canvas row that SaveOrReplaceLatestTx locks.
+func seedCanvasLimit(t *testing.T, db *gorm.DB, canvasID string) {
+ t.Helper()
+ if err := db.Create(&entity.UserCanvas{ID: canvasID, UserID: "user-1"}).Error; err != nil {
+ t.Fatalf("seed canvas: %v", err)
+ }
+}
+
+// seedVersions inserts n released version rows directly so the test starts at a
+// known count without going through SaveOrReplaceLatestTx. All versions are kept
+// (keep-all policy): no version row is ever auto-deleted on write, so count
+// assertions stay exact regardless of release state.
+func seedVersions(t *testing.T, db *gorm.DB, canvasID string, n int) {
+ t.Helper()
+ for i := 0; i < n; i++ {
+ v := &entity.UserCanvasVersion{
+ ID: fmt.Sprintf("%s-v-%d", canvasID, i),
+ UserCanvasID: canvasID,
+ Release: true,
+ DSL: entity.JSONMap{"n": i},
+ }
+ if err := db.Create(v).Error; err != nil {
+ t.Fatalf("seed version %d: %v", i, err)
+ }
+ }
+}
+
+func countVersions(t *testing.T, db *gorm.DB, canvasID string) int64 {
+ t.Helper()
+ var n int64
+ if err := db.Model(&entity.UserCanvasVersion{}).Where("user_canvas_id = ?", canvasID).Count(&n).Error; err != nil {
+ t.Fatalf("count versions: %v", err)
+ }
+ return n
+}
+
+// TestCanvasVersionLimit_RejectsAtCap verifies that once a canvas holds the
+// maximum number of versions, a NEW version write (ForceNew) is rejected and NO
+// row is added. This is the core off-by-one: the 64th version is allowed, the
+// 65th is not.
+func TestCanvasVersionLimit_RejectsAtCap(t *testing.T) {
+ db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+ if err != nil {
+ t.Fatalf("open db: %v", err)
+ }
+ if err := db.AutoMigrate(&entity.UserCanvas{}, &entity.UserCanvasVersion{}); err != nil {
+ t.Fatalf("migrate: %v", err)
+ }
+ const canvasID = "cap-full"
+ seedCanvasLimit(t, db, canvasID)
+ seedVersions(t, db, canvasID, MaxCanvasVersions)
+
+ before := countVersions(t, db, canvasID)
+ if before != MaxCanvasVersions {
+ t.Fatalf("seed count = %d, want %d", before, MaxCanvasVersions)
+ }
+
+ d := NewUserCanvasVersionDAO()
+ _, err = d.SaveOrReplaceLatestTx(context.Background(), db, SaveOrReplaceLatestVersionOptions{
+ NewID: canvasID + "-v-new",
+ UserCanvasID: canvasID,
+ Title: ptrStr("new"),
+ DSL: entity.JSONMap{"n": 9999}, // distinct DSL -> create branch
+ Release: true,
+ ForceNew: true,
+ })
+ if err == nil {
+ t.Fatalf("expected rejection when at cap, got nil error")
+ }
+ if !errors.Is(err, ErrCanvasVersionLimitExceeded) {
+ t.Fatalf("cap rejection must return ErrCanvasVersionLimitExceeded, got: %v", err)
+ }
+ if !strings.Contains(err.Error(), "版本数已达上限") {
+ t.Fatalf("cap error must surface the Chinese hint, got: %v", err)
+ }
+ after := countVersions(t, db, canvasID)
+ if after != before {
+ t.Fatalf("rejection must not add a row: before=%d after=%d", before, after)
+ }
+}
+
+// TestCanvasVersionLimit_AllowsBelowCap verifies that one version below the cap
+// still accepts a new write (count becomes exactly the cap).
+func TestCanvasVersionLimit_AllowsBelowCap(t *testing.T) {
+ db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+ if err != nil {
+ t.Fatalf("open db: %v", err)
+ }
+ if err := db.AutoMigrate(&entity.UserCanvas{}, &entity.UserCanvasVersion{}); err != nil {
+ t.Fatalf("migrate: %v", err)
+ }
+ const canvasID = "cap-below"
+ seedCanvasLimit(t, db, canvasID)
+ seedVersions(t, db, canvasID, MaxCanvasVersions-1)
+
+ d := NewUserCanvasVersionDAO()
+ _, err = d.SaveOrReplaceLatestTx(context.Background(), db, SaveOrReplaceLatestVersionOptions{
+ NewID: canvasID + "-v-new",
+ UserCanvasID: canvasID,
+ Title: ptrStr("new"),
+ DSL: entity.JSONMap{"n": 9999},
+ Release: true,
+ ForceNew: true,
+ })
+ if err != nil {
+ t.Fatalf("expected success below cap, got: %v", err)
+ }
+ after := countVersions(t, db, canvasID)
+ if after != MaxCanvasVersions {
+ t.Fatalf("count after allowed write = %d, want %d", after, MaxCanvasVersions)
+ }
+}
+
+// TestCanvasVersionLimit_RefreshInPlaceAllowedAtCap verifies the cap only blocks
+// NEW rows. An in-place DSL refresh (ForceNew=false, same DSL) does not consume
+// the budget and must succeed even at the cap.
+func TestCanvasVersionLimit_RefreshInPlaceAllowedAtCap(t *testing.T) {
+ db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+ if err != nil {
+ t.Fatalf("open db: %v", err)
+ }
+ if err := db.AutoMigrate(&entity.UserCanvas{}, &entity.UserCanvasVersion{}); err != nil {
+ t.Fatalf("migrate: %v", err)
+ }
+ const canvasID = "cap-refresh"
+ seedCanvasLimit(t, db, canvasID)
+ seedVersions(t, db, canvasID, MaxCanvasVersions)
+
+ d := NewUserCanvasVersionDAO()
+ _, err = d.SaveOrReplaceLatestTx(context.Background(), db, SaveOrReplaceLatestVersionOptions{
+ NewID: canvasID + "-v-new",
+ UserCanvasID: canvasID,
+ Title: ptrStr("refreshed"),
+ DSL: entity.JSONMap{"n": 0}, // ignored: SameDSL forces in-place
+ Release: true,
+ ForceNew: false,
+ SameDSL: func(entity.JSONMap) bool { return true },
+ })
+ if err != nil {
+ t.Fatalf("in-place refresh at cap should succeed, got: %v", err)
+ }
+ after := countVersions(t, db, canvasID)
+ if after != MaxCanvasVersions {
+ t.Fatalf("refresh must not add a row: count=%d want %d", after, MaxCanvasVersions)
+ }
+}
+
+// TestCanvasVersionLimit_PerCanvasIsolation verifies the cap is enforced per
+// canvas: a full canvas must not block a different (empty) canvas.
+func TestCanvasVersionLimit_PerCanvasIsolation(t *testing.T) {
+ db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+ if err != nil {
+ t.Fatalf("open db: %v", err)
+ }
+ if err := db.AutoMigrate(&entity.UserCanvas{}, &entity.UserCanvasVersion{}); err != nil {
+ t.Fatalf("migrate: %v", err)
+ }
+ const full = "iso-full"
+ const empty = "iso-empty"
+ seedCanvasLimit(t, db, full)
+ seedCanvasLimit(t, db, empty)
+ seedVersions(t, db, full, MaxCanvasVersions)
+
+ d := NewUserCanvasVersionDAO()
+ _, err = d.SaveOrReplaceLatestTx(context.Background(), db, SaveOrReplaceLatestVersionOptions{
+ NewID: empty + "-v-new",
+ UserCanvasID: empty,
+ Title: ptrStr("new"),
+ DSL: entity.JSONMap{"n": 1},
+ Release: true,
+ ForceNew: true,
+ })
+ if err != nil {
+ t.Fatalf("empty canvas should accept a write despite another canvas being full: %v", err)
+ }
+ if got := countVersions(t, db, empty); got != 1 {
+ t.Fatalf("empty canvas count = %d, want 1", got)
+ }
+ if got := countVersions(t, db, full); got != MaxCanvasVersions {
+ t.Fatalf("full canvas count changed = %d, want %d", got, MaxCanvasVersions)
+ }
+}
+
+// TestCanvasVersionLimit_AliasPatchUnaffected verifies that the cap does not
+// interfere with metadata-only version PATCH (alias edit), which never creates a
+// version row and must succeed even when the canvas is at the cap.
+func TestCanvasVersionLimit_AliasPatchUnaffected(t *testing.T) {
+ db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+ if err != nil {
+ t.Fatalf("open db: %v", err)
+ }
+ if err := db.AutoMigrate(&entity.UserCanvas{}, &entity.UserCanvasVersion{}); err != nil {
+ t.Fatalf("migrate: %v", err)
+ }
+ const canvasID = "cap-patch"
+ seedCanvasLimit(t, db, canvasID)
+ seedVersions(t, db, canvasID, MaxCanvasVersions)
+
+ alias := "pinned"
+ d := NewUserCanvasVersionDAO()
+ if err := d.UpdateTx(context.Background(), db, canvasID+"-v-0", UserCanvasVersionPatch{Alias: &alias}); err != nil {
+ t.Fatalf("alias patch at cap should succeed, got: %v", err)
+ }
+ if got := countVersions(t, db, canvasID); got != MaxCanvasVersions {
+ t.Fatalf("alias patch must not add a row: count=%d want %d", got, MaxCanvasVersions)
+ }
+}
diff --git a/internal/dao/user_canvas_version_test.go b/internal/dao/user_canvas_version_test.go
index a36b799904..d80021844f 100644
--- a/internal/dao/user_canvas_version_test.go
+++ b/internal/dao/user_canvas_version_test.go
@@ -19,12 +19,12 @@ package dao
import (
"context"
"errors"
- "fmt"
"testing"
- "ragflow/internal/entity"
-
+ "github.com/glebarez/sqlite"
"gorm.io/gorm"
+
+ "ragflow/internal/entity"
)
// TestUserCanvasVersionDAO_Constructor verifies the DAO constructor returns
@@ -87,59 +87,104 @@ func TestUserCanvasVersionDAO_InterfaceSatisfied(t *testing.T) {
_ = daoInterface(d)
}
-func TestUserCanvasVersionDAOKeepsAllVersions(t *testing.T) {
- db := setupUserCanvasTestDB(t)
- if err := db.AutoMigrate(&entity.UserCanvasVersion{}); err != nil {
- t.Fatalf("failed to migrate versions: %v", err)
- }
- ctx := t.Context()
- if err := db.WithContext(ctx).Create(&entity.UserCanvas{ID: "canvas-1", UserID: "user-1"}).Error; err != nil {
- t.Fatalf("failed to create canvas: %v", err)
- }
- dao := NewUserCanvasVersionDAO()
- opts := SaveOrReplaceLatestVersionOptions{UserCanvasID: "canvas-1"}
- const versionCount = 35
- for i := 0; i < versionCount; i++ {
- opts.NewID = fmt.Sprintf("version-%02d", i)
- opts.DSL = entity.JSONMap{"revision": fmt.Sprint(i)}
- if err := db.Transaction(func(tx *gorm.DB) error {
- _, err := dao.SaveOrReplaceLatestTx(ctx, tx, opts)
- return err
- }); err != nil {
- t.Fatalf("failed to save version %d: %v", i, err)
+// TestCountPipelineVersionReferences_SumsKBAndDocument verifies the delete-time
+// reference scan sums references across both the knowledgebase and document
+// tables (design section 12 A4).
+func TestCountPipelineVersionReferences_SumsKBAndDocument(t *testing.T) {
+ db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{TranslateError: true})
+ if err != nil {
+ t.Fatalf("open sqlite: %v", err)
+ }
+ if err := db.AutoMigrate(&entity.Knowledgebase{}, &entity.Document{}, &entity.UserCanvasVersion{}); err != nil {
+ t.Fatalf("migrate: %v", err)
+ }
+
+ v1 := "version0000000000000000000000aa"
+ v2 := "version0000000000000000000000bb"
+
+ // One KB + two documents pin v1.
+ if err := db.Create(&entity.Knowledgebase{
+ ID: "kb-1", TenantID: "t1", Name: "kb-1", EmbdID: "e", CreatedBy: "u",
+ Permission: string(entity.TenantPermissionMe), Status: sp("1"),
+ PipelineVersionID: &v1,
+ }).Error; err != nil {
+ t.Fatalf("seed kb v1: %v", err)
+ }
+ for i, id := range []string{"doc-1", "doc-2"} {
+ if err := db.Create(&entity.Document{
+ ID: id, KbID: "kb-1", ParserID: "naive", ParserConfig: entity.JSONMap{},
+ TokenNum: int64(i), ChunkNum: int64(i), Suffix: ".txt", Status: sp("1"),
+ PipelineVersionID: &v1,
+ }).Error; err != nil {
+ t.Fatalf("seed doc %s v1: %v", id, err)
}
}
- for _, stage := range []string{"insert", "refresh", "publish"} {
- t.Run(stage, func(t *testing.T) {
- if stage != "insert" {
- opts.NewID = "unused-version-id"
- opts.Release = stage == "publish"
- if err := db.Transaction(func(tx *gorm.DB) error {
- row, err := dao.SaveOrReplaceLatestTx(ctx, tx, opts)
- if err == nil && (row.ID != "version-34" || row.Release != opts.Release) {
- t.Errorf("unexpected refreshed version: id=%q release=%v", row.ID, row.Release)
- }
- return err
- }); err != nil {
- t.Fatalf("failed to save latest version: %v", err)
- }
- }
- versions, err := dao.ListByCanvasID(ctx, db, opts.UserCanvasID)
- if err != nil {
- t.Fatalf("failed to list versions: %v", err)
- }
- if len(versions) != versionCount {
- t.Fatalf("version count = %d, want %d", len(versions), versionCount)
- }
- ids := make(map[string]bool, len(versions))
- for _, version := range versions {
- ids[version.ID] = true
- }
- for i := 0; i < versionCount; i++ {
- if id := fmt.Sprintf("version-%02d", i); !ids[id] {
- t.Errorf("saved version %q was deleted", id)
- }
- }
- })
+ // One KB pins v2 (must not be counted toward v1).
+ if err := db.Create(&entity.Knowledgebase{
+ ID: "kb-2", TenantID: "t1", Name: "kb-2", EmbdID: "e", CreatedBy: "u",
+ Permission: string(entity.TenantPermissionMe), Status: sp("1"),
+ PipelineVersionID: &v2,
+ }).Error; err != nil {
+ t.Fatalf("seed kb v2: %v", err)
+ }
+
+ d := NewUserCanvasVersionDAO()
+ n1, err := d.CountPipelineVersionReferences(t.Context(), db, v1)
+ if err != nil {
+ t.Fatalf("count v1: %v", err)
+ }
+ if n1 != 3 {
+ t.Fatalf("CountPipelineVersionReferences(v1) = %d, want 3 (1 kb + 2 docs)", n1)
+ }
+ n2, err := d.CountPipelineVersionReferences(t.Context(), db, v2)
+ if err != nil {
+ t.Fatalf("count v2: %v", err)
+ }
+ if n2 != 1 {
+ t.Fatalf("CountPipelineVersionReferences(v2) = %d, want 1", n2)
}
}
+
+// TestUserCanvasVersionDAO_SaveOrReplaceLatestTxStoresAlias verifies the alias
+// field (design A2) is persisted on version save (T15: alias 存储/返回). The
+// alias column was previously write-dead: the DAO never copied it into the row.
+func TestUserCanvasVersionDAO_SaveOrReplaceLatestTxStoresAlias(t *testing.T) {
+ db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+ if err != nil {
+ t.Fatalf("open db: %v", err)
+ }
+ if err := db.AutoMigrate(&entity.UserCanvas{}, &entity.UserCanvasVersion{}); err != nil {
+ t.Fatalf("migrate: %v", err)
+ }
+ // Parent canvas row must exist: SaveOrReplaceLatestTx locks it first.
+ if err := db.Create(&entity.UserCanvas{ID: "canvas-1", UserID: "user-1"}).Error; err != nil {
+ t.Fatalf("seed canvas: %v", err)
+ }
+
+ alias := "release-1.0"
+ d := NewUserCanvasVersionDAO()
+ row, err := d.SaveOrReplaceLatestTx(context.Background(), db, SaveOrReplaceLatestVersionOptions{
+ NewID: "v-1",
+ UserCanvasID: "canvas-1",
+ Title: ptrStr("v1"),
+ Alias: &alias,
+ DSL: entity.JSONMap{"graph": "g"},
+ Release: true,
+ })
+ if err != nil {
+ t.Fatalf("SaveOrReplaceLatestTx: %v", err)
+ }
+ if row.Alias == nil || *row.Alias != alias {
+ t.Fatalf("returned row alias = %v, want %q", row.Alias, alias)
+ }
+ // Reload from the DB to prove the value was persisted, not just in-memory.
+ var got entity.UserCanvasVersion
+ if err := db.Where("id = ?", "v-1").First(&got).Error; err != nil {
+ t.Fatalf("reload: %v", err)
+ }
+ if got.Alias == nil || *got.Alias != alias {
+ t.Fatalf("persisted alias = %v, want %q", got.Alias, alias)
+ }
+}
+
+func ptrStr(v string) *string { return &v }
diff --git a/internal/entity/canvas.go b/internal/entity/canvas.go
index fe333306b9..81752545c3 100644
--- a/internal/entity/canvas.go
+++ b/internal/entity/canvas.go
@@ -81,6 +81,7 @@ type UserCanvasVersion struct {
Description *string `gorm:"column:description;type:longtext" json:"description,omitempty"`
Release bool `gorm:"column:release;not null;default:false;index" json:"release"`
DSL JSONMap `gorm:"column:dsl;type:longtext" json:"dsl,omitempty"`
+ Alias *string `gorm:"column:alias;size:255" json:"alias,omitempty"`
BaseModel
}
diff --git a/internal/entity/dataset.go b/internal/entity/dataset.go
index a07f90faac..73e1fe9f68 100644
--- a/internal/entity/dataset.go
+++ b/internal/entity/dataset.go
@@ -117,6 +117,7 @@ type Knowledgebase struct {
VectorSimilarityWeight float64 `gorm:"column:vector_similarity_weight;default:0.3;index" json:"vector_similarity_weight"`
ParserID string `gorm:"column:parser_id;size:32;not null;default:general;index" json:"parser_id"`
PipelineID *string `gorm:"column:pipeline_id;size:32;index" json:"pipeline_id,omitempty"`
+ PipelineVersionID *string `gorm:"column:pipeline_version_id;size:32;index" json:"pipeline_version_id,omitempty"`
ParserConfig JSONMap `gorm:"column:parser_config;type:json" json:"parser_config"`
Pagerank int64 `gorm:"column:pagerank;default:0" json:"pagerank"`
GraphragTaskID *string `gorm:"column:graphrag_task_id;size:32;index" json:"graphrag_task_id,omitempty"`
@@ -283,6 +284,8 @@ type KnowledgebaseListItem struct {
Nickname string `json:"nickname"`
TenantAvatar *string `json:"tenant_avatar,omitempty"`
UpdateTime *int64 `json:"update_time,omitempty"`
+ PipelineID *string `json:"pipeline_id,omitempty"`
+ PipelineVersionID *string `json:"pipeline_version_id,omitempty"`
}
// DatasetOwnerFilter represents an owner option in dataset filter responses.
diff --git a/internal/entity/document.go b/internal/entity/document.go
index 95bc6a1180..4d26cbaef0 100644
--- a/internal/entity/document.go
+++ b/internal/entity/document.go
@@ -20,61 +20,67 @@ import "time"
// Document document model
type Document struct {
- ID string `gorm:"column:id;primaryKey;size:32" json:"id"`
- Thumbnail *string `gorm:"column:thumbnail;type:longtext" json:"thumbnail,omitempty"`
- KbID string `gorm:"column:kb_id;size:256;not null;index" json:"kb_id"`
- ParserID string `gorm:"column:parser_id;size:32;not null;index" json:"parser_id"`
- PipelineID *string `gorm:"column:pipeline_id;size:32;index" json:"pipeline_id,omitempty"`
- ParserConfig JSONMap `gorm:"column:parser_config;type:longtext;not null" json:"parser_config"`
- SourceType string `gorm:"column:source_type;size:128;not null;default:local;index" json:"source_type"`
- Type string `gorm:"column:type;size:32;not null;index" json:"type"`
- CreatedBy string `gorm:"column:created_by;size:32;not null;index" json:"created_by"`
- Name *string `gorm:"column:name;size:255;index" json:"name,omitempty"`
- Location *string `gorm:"column:location;size:255;index" json:"location,omitempty"`
- Size int64 `gorm:"column:size;default:0;index" json:"size"`
- TokenNum int64 `gorm:"column:token_num;default:0;index" json:"token_num"`
- ChunkNum int64 `gorm:"column:chunk_num;default:0;index" json:"chunk_num"`
- Progress float64 `gorm:"column:progress;default:0;index" json:"progress"`
- ProgressMsg *string `gorm:"column:progress_msg;type:longtext" json:"progress_msg,omitempty"`
- ProcessBeginAt *time.Time `gorm:"column:process_begin_at;index" json:"process_begin_at,omitempty"`
- ProcessDuration float64 `gorm:"column:process_duration;default:0" json:"process_duration"`
- ContentHash *string `gorm:"column:content_hash;size:32;index;default:''" json:"content_hash,omitempty"`
- Suffix string `gorm:"column:suffix;size:32;not null;index" json:"suffix"`
- Status *string `gorm:"column:status;size:1;index;default:'1'" json:"status,omitempty"`
+ ID string `gorm:"column:id;primaryKey;size:32" json:"id"`
+ Thumbnail *string `gorm:"column:thumbnail;type:longtext" json:"thumbnail,omitempty"`
+ KbID string `gorm:"column:kb_id;size:256;not null;index" json:"kb_id"`
+ ParserID string `gorm:"column:parser_id;size:32;not null;index" json:"parser_id"`
+ PipelineID *string `gorm:"column:pipeline_id;size:32;index" json:"pipeline_id,omitempty"`
+ PipelineVersionID *string `gorm:"column:pipeline_version_id;size:32;index" json:"pipeline_version_id,omitempty"`
+ ParserConfig JSONMap `gorm:"column:parser_config;type:longtext;not null" json:"parser_config"`
+ SourceType string `gorm:"column:source_type;size:128;not null;default:local;index" json:"source_type"`
+ Type string `gorm:"column:type;size:32;not null;index" json:"type"`
+ CreatedBy string `gorm:"column:created_by;size:32;not null;index" json:"created_by"`
+ Name *string `gorm:"column:name;size:255;index" json:"name,omitempty"`
+ Location *string `gorm:"column:location;size:255;index" json:"location,omitempty"`
+ Size int64 `gorm:"column:size;default:0;index" json:"size"`
+ TokenNum int64 `gorm:"column:token_num;default:0;index" json:"token_num"`
+ ChunkNum int64 `gorm:"column:chunk_num;default:0;index" json:"chunk_num"`
+ Progress float64 `gorm:"column:progress;default:0;index" json:"progress"`
+ ProgressMsg *string `gorm:"column:progress_msg;type:longtext" json:"progress_msg,omitempty"`
+ ProcessBeginAt *time.Time `gorm:"column:process_begin_at;index" json:"process_begin_at,omitempty"`
+ ProcessDuration float64 `gorm:"column:process_duration;default:0" json:"process_duration"`
+ ContentHash *string `gorm:"column:content_hash;size:32;index;default:''" json:"content_hash,omitempty"`
+ Suffix string `gorm:"column:suffix;size:32;not null;index" json:"suffix"`
+ Status *string `gorm:"column:status;size:1;index;default:'1'" json:"status,omitempty"`
BaseModel
}
// DocumentListItem represents a document list row with joined fields.
type DocumentListItem struct {
- ID string `gorm:"column:id" json:"id"`
- Thumbnail *string `gorm:"column:thumbnail" json:"thumbnail,omitempty"`
- KbID string `gorm:"column:kb_id" json:"kb_id"`
- ParserID string `gorm:"column:parser_id" json:"parser_id"`
- PipelineID *string `gorm:"column:pipeline_id" json:"pipeline_id,omitempty"`
- PipelineName *string `gorm:"column:pipeline_name" json:"pipeline_name,omitempty"`
- ParserConfig string `gorm:"column:parser_config" json:"parser_config"`
- SourceType string `gorm:"column:source_type" json:"source_type"`
- Type string `gorm:"column:type" json:"type"`
- CreatedBy string `gorm:"column:created_by" json:"created_by"`
- Nickname *string `gorm:"column:nickname" json:"nickname,omitempty"`
- Name *string `gorm:"column:name" json:"name,omitempty"`
- Location *string `gorm:"column:location" json:"location,omitempty"`
- Size int64 `gorm:"column:size" json:"size"`
- TokenNum int64 `gorm:"column:token_num" json:"token_num"`
- ChunkNum int64 `gorm:"column:chunk_num" json:"chunk_num"`
- Progress float64 `gorm:"column:progress" json:"progress"`
- ProgressMsg *string `gorm:"column:progress_msg" json:"progress_msg,omitempty"`
- ProcessBeginAt *time.Time `gorm:"column:process_begin_at" json:"process_begin_at,omitempty"`
- ProcessDuration float64 `gorm:"column:process_duration" json:"process_duration"`
- ContentHash *string `gorm:"column:content_hash" json:"content_hash,omitempty"`
- Suffix string `gorm:"column:suffix" json:"suffix"`
- IngestionStatus *string `gorm:"column:ingestion_status" json:"ingestion_status,omitempty"`
- PipelineLogID *string `gorm:"column:pipeline_log_id" json:"-"`
- Status *string `gorm:"column:status" json:"status,omitempty"`
- CreateTime *int64 `gorm:"column:create_time" json:"create_time,omitempty"`
- CreateDate *time.Time `gorm:"column:create_date" json:"create_date,omitempty"`
- UpdateTime *int64 `gorm:"column:update_time" json:"update_time,omitempty"`
- UpdateDate *time.Time `gorm:"column:update_date" json:"update_date,omitempty"`
+ ID string `gorm:"column:id" json:"id"`
+ Thumbnail *string `gorm:"column:thumbnail" json:"thumbnail,omitempty"`
+ KbID string `gorm:"column:kb_id" json:"kb_id"`
+ ParserID string `gorm:"column:parser_id" json:"parser_id"`
+ PipelineID *string `gorm:"column:pipeline_id" json:"pipeline_id,omitempty"`
+ // PipelineVersionID pins the document to a specific dataflow canvas version
+ // (design section 5 sticky snapshot). Returned by the list so the reopened
+ // change-parser dialog can show the saved pin instead of re-adopting the
+ // latest version. Omitted when the document tracks the canvas latest.
+ PipelineVersionID *string `gorm:"column:pipeline_version_id;size:32" json:"pipeline_version_id,omitempty"`
+ PipelineName *string `gorm:"column:pipeline_name" json:"pipeline_name,omitempty"`
+ ParserConfig string `gorm:"column:parser_config" json:"parser_config"`
+ SourceType string `gorm:"column:source_type" json:"source_type"`
+ Type string `gorm:"column:type" json:"type"`
+ CreatedBy string `gorm:"column:created_by" json:"created_by"`
+ Nickname *string `gorm:"column:nickname" json:"nickname,omitempty"`
+ Name *string `gorm:"column:name" json:"name,omitempty"`
+ Location *string `gorm:"column:location" json:"location,omitempty"`
+ Size int64 `gorm:"column:size" json:"size"`
+ TokenNum int64 `gorm:"column:token_num" json:"token_num"`
+ ChunkNum int64 `gorm:"column:chunk_num" json:"chunk_num"`
+ Progress float64 `gorm:"column:progress" json:"progress"`
+ ProgressMsg *string `gorm:"column:progress_msg" json:"progress_msg,omitempty"`
+ ProcessBeginAt *time.Time `gorm:"column:process_begin_at" json:"process_begin_at,omitempty"`
+ ProcessDuration float64 `gorm:"column:process_duration" json:"process_duration"`
+ ContentHash *string `gorm:"column:content_hash" json:"content_hash,omitempty"`
+ Suffix string `gorm:"column:suffix" json:"suffix"`
+ IngestionStatus *string `gorm:"column:ingestion_status" json:"ingestion_status,omitempty"`
+ PipelineLogID *string `gorm:"column:pipeline_log_id" json:"-"`
+ Status *string `gorm:"column:status" json:"status,omitempty"`
+ CreateTime *int64 `gorm:"column:create_time" json:"create_time,omitempty"`
+ CreateDate *time.Time `gorm:"column:create_date" json:"create_date,omitempty"`
+ UpdateTime *int64 `gorm:"column:update_time" json:"update_time,omitempty"`
+ UpdateDate *time.Time `gorm:"column:update_date" json:"update_date,omitempty"`
}
// TableName specify table name
diff --git a/internal/handler/agent.go b/internal/handler/agent.go
index c104fde170..4fd196c2e5 100644
--- a/internal/handler/agent.go
+++ b/internal/handler/agent.go
@@ -697,6 +697,7 @@ func (h *AgentHandler) CancelSessionRun(c *gin.Context) {
type publishAgentRequest struct {
Title *string `json:"title,omitempty"`
Description *string `json:"description,omitempty"`
+ Alias *string `json:"alias,omitempty"`
DSL entity.JSONMap `json:"dsl,omitempty"`
}
@@ -724,6 +725,7 @@ func (h *AgentHandler) PublishAgent(c *gin.Context) {
row, err := h.agentService.PublishAgent(c.Request.Context(), user.ID, canvasID, &service.PublishAgentRequest{
Title: req.Title,
Description: req.Description,
+ Alias: req.Alias,
DSL: req.DSL,
})
if err != nil {
@@ -821,6 +823,44 @@ func (h *AgentHandler) DeleteVersion(c *gin.Context) {
common.SuccessWithData(c, true, "success")
}
+// PatchVersion patches mutable metadata (alias/title/description) of a single
+// version. It does not change the DSL and does not create a new version
+// (design G2/§4.4).
+// @Summary Patch Agent Version
+// @Tags agents
+// @Accept json
+// @Produce json
+// @Param canvas_id path string true "canvas id"
+// @Param version_id path string true "version id"
+// @Param body body object false "patch fields: alias/title/description"
+// @Success 200 {object} map[string]interface{}
+// @Router /api/v1/agents/{canvas_id}/versions/{version_id} [patch]
+func (h *AgentHandler) PatchVersion(c *gin.Context) {
+ user, code, msg := GetUser(c)
+ if code != common.CodeSuccess {
+ common.ResponseWithCodeData(c, code, nil, msg)
+ return
+ }
+ canvasID := c.Param("canvas_id")
+ versionID := c.Param("version_id")
+ var req struct {
+ Alias *string `json:"alias"`
+ Title *string `json:"title"`
+ Description *string `json:"description"`
+ }
+ if err := c.ShouldBindJSON(&req); err != nil {
+ common.ResponseWithCodeData(c, common.CodeArgumentError, nil, err.Error())
+ return
+ }
+ patch := dao.UserCanvasVersionPatch{Alias: req.Alias, Title: req.Title, Description: req.Description}
+ if err := h.agentService.UpdateVersion(c.Request.Context(), user.ID, canvasID, versionID, patch); err != nil {
+ ec, em := mapAgentError(err)
+ common.ResponseWithCodeData(c, ec, nil, em)
+ return
+ }
+ common.SuccessWithData(c, true, "success")
+}
+
// ApplyVersion restores a saved workflow as the current agent draft.
// @Summary Apply Agent Version
// @Tags agents
diff --git a/internal/handler/dataset.go b/internal/handler/dataset.go
index eef9f50033..c022b85058 100644
--- a/internal/handler/dataset.go
+++ b/internal/handler/dataset.go
@@ -390,14 +390,14 @@ var listDatasetsAllowedParams = map[string]bool{
var createDatasetAllowedFields = map[string]bool{
"name": true, "embedding_model": true, "parser_config": true,
"language": true, "permission": true, "parser_id": true,
- "pipeline_id": true, "parse_type": true,
+ "pipeline_id": true, "pipeline_version_id": true, "parse_type": true,
}
// updateDatasetAllowedFields mirrors the field set of Python's UpdateDatasetReq
// (CreateDatasetReq fields + dataset_id/pagerank/language/connectors).
var updateDatasetAllowedFields = map[string]bool{
"name": true, "avatar": true, "description": true, "embedding_model": true,
- "permission": true, "parse_type": true, "pipeline_id": true, "chunk_method": true,
+ "permission": true, "parse_type": true, "pipeline_id": true, "pipeline_version_id": true, "chunk_method": true,
"parser_id": true, "parser_config": true, "auto_metadata_config": true,
"dataset_id": true, "pagerank": true, "language": true, "connectors": true,
}
diff --git a/internal/handler/dataset_allowed_fields_test.go b/internal/handler/dataset_allowed_fields_test.go
new file mode 100644
index 0000000000..48eaa16014
--- /dev/null
+++ b/internal/handler/dataset_allowed_fields_test.go
@@ -0,0 +1,30 @@
+package handler
+
+import "testing"
+
+// RED: dataset create must accept pipeline_version_id so a specific (non-latest)
+// canvas version can be pinned at bind time (design section 5 C2).
+func TestDatasetCreateAllowsPipelineVersionID(t *testing.T) {
+ if !createDatasetAllowedFields["pipeline_version_id"] {
+ t.Fatalf("createDatasetAllowedFields must include pipeline_version_id; otherwise binding a pinned version is rejected as 'extra input'")
+ }
+}
+
+// RED: dataset update must accept pipeline_version_id so an existing dataset can
+// be re-bound to a different version (design section 5 C3 / sticky-snapshot switch).
+func TestDatasetUpdateAllowsPipelineVersionID(t *testing.T) {
+ if !updateDatasetAllowedFields["pipeline_version_id"] {
+ t.Fatalf("updateDatasetAllowedFields must include pipeline_version_id; otherwise version re-bind is rejected as 'extra input'")
+ }
+}
+
+// Adversarial: the whitelist must still reject genuinely unknown fields, proving
+// the fix is a targeted allow-list addition and not a blanket "allow everything".
+func TestDatasetAllowedFieldsRejectUnknownField(t *testing.T) {
+ if createDatasetAllowedFields["__bogus_field__"] {
+ t.Fatalf("createDatasetAllowedFields must not accept unknown fields")
+ }
+ if updateDatasetAllowedFields["__bogus_field__"] {
+ t.Fatalf("updateDatasetAllowedFields must not accept unknown fields")
+ }
+}
diff --git a/internal/handler/document.go b/internal/handler/document.go
index 461cd128b0..85274d36c8 100644
--- a/internal/handler/document.go
+++ b/internal/handler/document.go
@@ -1262,6 +1262,7 @@ func mapDocumentListItem(doc *entity.DocumentListItem, metaFields map[string]int
"parser_id": doc.ParserID,
"chunk_method": doc.ParserID,
"pipeline_id": stringValue(doc.PipelineID),
+ "pipeline_version_id": stringValue(doc.PipelineVersionID),
"pipeline_name": stringValue(doc.PipelineName),
"nickname": stringValue(doc.Nickname),
"parser_config": decodeJSONMap(string(doc.ParserConfig)),
diff --git a/internal/handler/document_test.go b/internal/handler/document_test.go
index 013fbc73c0..e49ded5625 100644
--- a/internal/handler/document_test.go
+++ b/internal/handler/document_test.go
@@ -2334,3 +2334,33 @@ func TestDownloadDocument_ForeignUserRejected(t *testing.T) {
t.Fatalf("unexpected hidden-resource message: %v", resp["message"])
}
}
+
+// TestMapDocumentListItemIncludesPipelineVersionID guards the document list
+// wire format: the reopened change-parser dialog reads record.pipeline_version_id
+// to show the saved pin, so mapDocumentListItem MUST emit it. An earlier fix added
+// the field to the entity struct and asserted on the service-layer struct, but
+// never on this serialization step, so the field was silently dropped from the
+// HTTP response (file-level pin always reverted to latest). This test covers that
+// exact gap.
+func TestMapDocumentListItemIncludesPipelineVersionID(t *testing.T) {
+ pinned := "v-pinned-123"
+ pipelineID := "canvas-1"
+ doc := &entity.DocumentListItem{
+ ID: "doc-1",
+ KbID: "kb-1",
+ PipelineID: &pipelineID,
+ PipelineVersionID: &pinned,
+ }
+ item := mapDocumentListItem(doc, map[string]interface{}{}, nil)
+
+ got, ok := item["pipeline_version_id"]
+ if !ok {
+ t.Fatalf("mapDocumentListItem must emit pipeline_version_id; got keys without it")
+ }
+ if got != pinned {
+ t.Fatalf("pipeline_version_id value mismatch: got %v want %v", got, pinned)
+ }
+ if item["pipeline_id"] != pipelineID {
+ t.Fatalf("pipeline_id mapping regressed: %v", item["pipeline_id"])
+ }
+}
diff --git a/internal/ingestion/task/pipeline_executor.go b/internal/ingestion/task/pipeline_executor.go
index 5d7634eddc..84d02d0d7a 100644
--- a/internal/ingestion/task/pipeline_executor.go
+++ b/internal/ingestion/task/pipeline_executor.go
@@ -842,6 +842,13 @@ type PipelineLogInput struct {
// outcome without the run row that owns it.
var ErrMissingRunIdentity = errors.New("pipeline log id is required")
+// ErrPipelineVersionMissing is the single multi-version Missing sentinel. It is
+// defined once in the dao package (dao.ErrPipelineVersionMissing) and re-exported
+// here so the service and task layers share one identity (review: merge the
+// duplicate service/task sentinels into one implementation). The wrapped message
+// still carries the user-facing hint "pipeline 版本不存在,请重新选择版本".
+var ErrPipelineVersionMissing = dao.ErrPipelineVersionMissing
+
// RecordPipelineLog persists a pipeline operation log without requiring
// executor setup. Callers should pass the status in Status.
//
@@ -1035,6 +1042,24 @@ func (s *PipelineExecutor) loadDSLFromCanvas(ctx context.Context, canvasID strin
}
common.Info(fmt.Sprintf("load canvas %s, name %s", canvasID, canvasTitle))
+ // dataflow canvases are versioned (design section 6.2). An explicit pin
+ // resolves that exact version; an empty pin resolves the latest version.
+ // A missing or mis-owned version maps to ErrPipelineVersionMissing so the
+ // parse task fails and the file enters an unparseable Missing state (C4).
+ if canvas.CanvasCategory == "dataflow_canvas" {
+ // Dataflow canvases are versioned (design section 6.2). An explicit pin
+ // resolves that exact version; an empty pin resolves the latest published
+ // version. A missing or mis-owned version returns ErrPipelineVersionMissing
+ // so the parse task fails and the file enters an unparseable Missing state.
+ raw, verr := dao.LoadCanvasVersionDSL(ctx, s.deps.DB, canvasID, s.taskCtx.PipelineVersionID)
+ if verr != nil {
+ return "", "", verr
+ }
+ return string(raw), canvasID, nil
+ }
+
+ // Agent / non-versioned canvases: read the live draft column (out of scope
+ // for multi-version; mirrors the agent read path in the service layer).
raw, err := json.Marshal(canvas.DSL)
if err != nil {
return "", "", fmt.Errorf("marshal canvas dsl %s: %w", canvasID, err)
diff --git a/internal/ingestion/task/pipeline_version_test.go b/internal/ingestion/task/pipeline_version_test.go
new file mode 100644
index 0000000000..3d115624a8
--- /dev/null
+++ b/internal/ingestion/task/pipeline_version_test.go
@@ -0,0 +1,188 @@
+package task
+
+import (
+ "context"
+ "encoding/json"
+ "errors"
+ "strings"
+ "testing"
+
+ "github.com/glebarez/sqlite"
+ "gorm.io/gorm"
+ "gorm.io/gorm/logger"
+
+ "ragflow/internal/dao"
+ "ragflow/internal/entity"
+)
+
+// setupVersionTestDB stands up an in-memory sqlite with the canvas and version
+// tables, swaps it into dao.DB, and returns a teardown func.
+func setupVersionTestDB(t *testing.T) func() {
+ t.Helper()
+ db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{Logger: logger.Default.LogMode(logger.Silent)})
+ if err != nil {
+ t.Fatalf("open sqlite: %v", err)
+ }
+ if err := db.AutoMigrate(&entity.UserCanvas{}, &entity.UserCanvasVersion{}, &entity.Document{}, &entity.Knowledgebase{}); err != nil {
+ t.Fatalf("auto-migrate: %v", err)
+ }
+ orig := dao.DB
+ dao.DB = db
+ return func() { dao.DB = orig }
+}
+
+func seedCanvas(t *testing.T, db *gorm.DB, canvasID string) {
+ t.Helper()
+ canvas := &entity.UserCanvas{
+ ID: canvasID,
+ CanvasCategory: "dataflow_canvas",
+ Title: strPtr("flow"),
+ DSL: entity.JSONMap{"components": []any{}},
+ }
+ if err := db.Create(canvas).Error; err != nil {
+ t.Fatalf("seed canvas: %v", err)
+ }
+}
+
+func seedVersion(t *testing.T, db *gorm.DB, canvasID, versionID string, dsl entity.JSONMap, createMs ...int64) {
+ t.Helper()
+ v := &entity.UserCanvasVersion{
+ ID: versionID,
+ UserCanvasID: canvasID,
+ DSL: dsl,
+ }
+ // An explicit createMs makes GetLatest ordering deterministic; without it the
+ // two rows can share the same millisecond timestamp and the latest-by-time
+ // order is undefined (flaky test).
+ if len(createMs) > 0 {
+ ct := createMs[0]
+ v.CreateTime = &ct
+ }
+ if err := db.Create(v).Error; err != nil {
+ t.Fatalf("seed version: %v", err)
+ }
+}
+
+// newVersionTaskCtx builds a TaskContext that satisfies executor validation
+// and carries the given pinned version id (empty = latest, design 6.2).
+func newVersionTaskCtx(pin string) *TaskContext {
+ return &TaskContext{
+ Doc: entity.Document{
+ ID: "doc-1",
+ KbID: "kb-1",
+ Name: strPtr("doc.pdf"),
+ },
+ KB: entity.Knowledgebase{ID: "kb-1"},
+ Tenant: entity.Tenant{ID: "tenant-1"},
+ PipelineVersionID: pin,
+ }
+}
+
+// T11: resolvePipelineVersionID maps a document pin to its trimmed version id,
+// and to "" when no pin is set (runtime falls back to latest, design 6.2).
+func TestResolvePipelineVersionID(t *testing.T) {
+ if got := resolvePipelineVersionID(nil); got != "" {
+ t.Fatalf("nil doc = %q, want empty", got)
+ }
+ if got := resolvePipelineVersionID(&entity.Document{}); got != "" {
+ t.Fatalf("no pin = %q, want empty", got)
+ }
+ if got := resolvePipelineVersionID(&entity.Document{PipelineVersionID: strPtr(" v1 ")}); got != "v1" {
+ t.Fatalf("pin = %q, want trimmed v1", got)
+ }
+}
+
+// T10: loadDSLFromCanvas reads a dataflow canvas version by its pinned id.
+func TestLoadDSLFromCanvas_VersionedReadsVersionDSL(t *testing.T) {
+ teardown := setupVersionTestDB(t)
+ defer teardown()
+ db := dao.DB
+ pinnedDSL := entity.JSONMap{"components": []any{map[string]any{"id": "a"}}}
+ seedCanvas(t, db, "flow-1")
+ seedVersion(t, db, "flow-1", "v1", pinnedDSL)
+
+ taskCtx := newVersionTaskCtx("v1")
+ exec := mustNewPipelineExecutor(t, taskCtx, "flow-1", 0)
+ dsl, correctedID, err := exec.loadDSLFromCanvas(context.Background(), "flow-1")
+ if err != nil {
+ t.Fatalf("loadDSLFromCanvas: %v", err)
+ }
+ if correctedID != "flow-1" {
+ t.Fatalf("correctedID = %q", correctedID)
+ }
+ var got map[string]any
+ if err := json.Unmarshal([]byte(dsl), &got); err != nil {
+ t.Fatalf("unmarshal dsl: %v", err)
+ }
+ comps, ok := got["components"].([]any)
+ if !ok || len(comps) != 1 {
+ t.Fatalf("dsl components = %#v", got["components"])
+ }
+}
+
+// TestErrPipelineVersionMissingSingleSentinel proves the task-layer sentinel is
+// the single dao definition, not a second errors.New with the same message. This
+// locks in the review fix that merged the service/task duplicate sentinels into
+// one (design §6.2): a runtime Missing error must match a dao.ErrPipelineVersionMissing
+// check, and must equal the service-layer sentinel identity.
+func TestErrPipelineVersionMissingSingleSentinel(t *testing.T) {
+ if !errors.Is(ErrPipelineVersionMissing, dao.ErrPipelineVersionMissing) {
+ t.Fatalf("task.ErrPipelineVersionMissing must be dao.ErrPipelineVersionMissing, got distinct identity")
+ }
+}
+
+// T12: a pinned-but-missing version (and a mis-owned one) fails with
+// ErrPipelineVersionMissing (C4, design 6.2) carrying the user-facing hint.
+func TestLoadDSLFromCanvas_PinnedMissingVersionFails(t *testing.T) {
+ teardown := setupVersionTestDB(t)
+ defer teardown()
+ db := dao.DB
+ seedCanvas(t, db, "flow-1")
+ seedVersion(t, db, "flow-1", "v1", entity.JSONMap{"components": []any{}})
+ seedCanvas(t, db, "flow-2")
+ seedVersion(t, db, "flow-2", "foreign", entity.JSONMap{"components": []any{}})
+
+ cases := []struct {
+ name string
+ version string
+ }{
+ {"missing", "nope"},
+ {"foreign", "foreign"},
+ }
+ for _, c := range cases {
+ t.Run(c.name, func(t *testing.T) {
+ taskCtx := newVersionTaskCtx(c.version)
+ exec := mustNewPipelineExecutor(t, taskCtx, "flow-1", 0)
+ _, _, err := exec.loadDSLFromCanvas(context.Background(), "flow-1")
+ if err == nil {
+ t.Fatalf("want error for version %q", c.version)
+ }
+ if !errors.Is(err, ErrPipelineVersionMissing) {
+ t.Fatalf("err = %v, want ErrPipelineVersionMissing", err)
+ }
+ if !strings.Contains(err.Error(), "pipeline 版本不存在,请重新选择版本") {
+ t.Fatalf("err message missing user hint: %v", err)
+ }
+ })
+ }
+}
+
+// T12b: no pin falls back to the latest version of the bound canvas.
+func TestLoadDSLFromCanvas_NoPinUsesLatestVersion(t *testing.T) {
+ teardown := setupVersionTestDB(t)
+ defer teardown()
+ db := dao.DB
+ seedCanvas(t, db, "flow-1")
+ seedVersion(t, db, "flow-1", "v-old", entity.JSONMap{"components": []any{map[string]any{"id": "old"}}}, 100)
+ seedVersion(t, db, "flow-1", "v-new", entity.JSONMap{"components": []any{map[string]any{"id": "new"}}}, 200)
+
+ taskCtx := newVersionTaskCtx("")
+ exec := mustNewPipelineExecutor(t, taskCtx, "flow-1", 0)
+ dsl, _, err := exec.loadDSLFromCanvas(context.Background(), "flow-1")
+ if err != nil {
+ t.Fatalf("loadDSLFromCanvas: %v", err)
+ }
+ if !strings.Contains(dsl, "\"id\":\"new\"") {
+ t.Fatalf("expected latest version DSL, got %s", dsl)
+ }
+}
diff --git a/internal/ingestion/task/task_context.go b/internal/ingestion/task/task_context.go
index c418f18eae..01cbcaadc2 100644
--- a/internal/ingestion/task/task_context.go
+++ b/internal/ingestion/task/task_context.go
@@ -57,7 +57,11 @@ type TaskContext struct {
Tenant entity.Tenant
PipelineID string
- File any
+ // PipelineVersionID pins the canvas version to execute (design section 5
+ // sticky snapshot). Empty means the latest version (or legacy canvas DSL)
+ // is used at runtime (design section 6.2).
+ PipelineVersionID string
+ File any
// taskID is the authoritative TaskMessage identity used for admission,
// execution, settlement, and logging. It is unexported so it cannot change
@@ -137,13 +141,14 @@ func LoadFromIngestionTask(ctx context.Context, db *gorm.DB, ingestionTask *enti
pipelineID := resolvePipelineID(doc)
return &TaskContext{
- Ctx: ctx,
- taskID: ingestionTask.ID,
- IngestionTask: ingestionTask,
- PipelineID: pipelineID,
- Doc: *doc,
- KB: *kb,
- Tenant: *tenant,
+ Ctx: ctx,
+ taskID: ingestionTask.ID,
+ IngestionTask: ingestionTask,
+ PipelineID: pipelineID,
+ PipelineVersionID: resolvePipelineVersionID(doc),
+ Doc: *doc,
+ KB: *kb,
+ Tenant: *tenant,
}, nil
}
@@ -154,3 +159,13 @@ func resolvePipelineID(doc *entity.Document) string {
}
return ""
}
+
+// resolvePipelineVersionID resolves the pinned canvas version for a document.
+// Returns "" when the document has no pinned version, so the runtime falls
+// back to the latest version (design section 6.2).
+func resolvePipelineVersionID(doc *entity.Document) string {
+ if doc != nil && doc.PipelineVersionID != nil {
+ return strings.TrimSpace(*doc.PipelineVersionID)
+ }
+ return ""
+}
diff --git a/internal/router/agent_routes.go b/internal/router/agent_routes.go
index 02d06becbf..79206b6218 100644
--- a/internal/router/agent_routes.go
+++ b/internal/router/agent_routes.go
@@ -66,6 +66,7 @@ func RegisterAgentRoutes(g *gin.RouterGroup, h *handler.AgentHandler) {
// Versions.
g.GET("/:canvas_id/versions", h.ListVersions)
g.GET("/:canvas_id/versions/:version_id", h.GetVersion)
+ g.PATCH("/:canvas_id/versions/:version_id", h.PatchVersion)
g.DELETE("/:canvas_id/versions/:version_id", h.DeleteVersion)
g.POST("/:canvas_id/versions/:version_id/apply", h.ApplyVersion)
diff --git a/internal/service/agent.go b/internal/service/agent.go
index 477064ae0b..bcf68f6307 100644
--- a/internal/service/agent.go
+++ b/internal/service/agent.go
@@ -1169,6 +1169,40 @@ func (s *AgentService) UpdateAgent(ctx context.Context, userID, canvasID string,
}
}
updates["release"] = release
+
+ // Autosave signal (design §5.1): the front-end sends autosave:true on its
+ // debounced auto-save. An auto-save refreshes ONLY the live draft
+ // (user_canvas.dsl) and must NOT create a new version. A manual Save (no
+ // autosave flag, or autosave:false) must both update the draft and INSERT a
+ // new version row. v5.2 removes the same-DSL in-place refresh dedup, so
+ // every manual Save produces a version even when the DSL is unchanged.
+ autosave := false
+ if value, ok := patch["autosave"]; ok && value != nil {
+ switch v := value.(type) {
+ case bool:
+ autosave = v
+ case string:
+ autosave = v != "" && v != "false"
+ case float64:
+ autosave = v != 0
+ }
+ }
+
+ // Optional alias carried on a manual Save (design §4.4 carry-on path).
+ var aliasPtr *string
+ if value, ok := patch["alias"]; ok && value != nil {
+ if s, ok := value.(string); ok && strings.TrimSpace(s) != "" {
+ aliasPtr = &s
+ }
+ }
+ // ApplyVersion restore path: re-applying a version whose DSL already matches
+ // the latest draft must reuse that draft instead of minting a duplicate
+ // version row. We signal this with the "apply" flag so the version save can
+ // fall back to the SameDSL reuse branch instead of always inserting.
+ applyVersion := false
+ if value, ok := patch["apply"]; ok && value != nil {
+ applyVersion = true
+ }
if title, ok := updatedAgentTitle(canvasInstance, updates); ok {
canvasCategory := updatedAgentCanvasCategory(canvasInstance, updates)
// Exclude the canvas being updated so keeping or only re-casing its
@@ -1222,8 +1256,17 @@ func (s *AgentService) UpdateAgent(ctx context.Context, userID, canvasID string,
} else if canvasInstance.Title != nil {
title = *canvasInstance.Title
}
- opts := s.saveOrReplaceVersionOptions(ctx, userID, canvasID, dsl, title, nil, release)
- versionOpts = &opts
+ opts := s.saveOrReplaceVersionOptions(ctx, userID, canvasID, dsl, title, nil, aliasPtr, release)
+ // Manual Save (autosave != true) always mints a new version row, even
+ // when the DSL is identical to the previous one (design §5.1). Auto-save
+ // never mints a version at all, so versionOpts stays nil and only the
+ // live draft is refreshed below. ApplyVersion restores a historical DSL
+ // and must reuse the latest draft when the DSL is unchanged, so it does
+ // NOT force a new row (the SameDSL branch governs instead).
+ opts.ForceNew = !autosave && !applyVersion
+ if !autosave {
+ versionOpts = &opts
+ }
}
// The canvas release/DSL update and the version save must commit
@@ -1314,6 +1357,7 @@ func (s *AgentService) DeleteAgent(ctx context.Context, userID, canvasID string)
type PublishAgentRequest struct {
Title *string `json:"title,omitempty"`
Description *string `json:"description,omitempty"`
+ Alias *string `json:"alias,omitempty"`
DSL entity.JSONMap `json:"dsl,omitempty"`
}
@@ -1325,6 +1369,7 @@ func (s *AgentService) PublishAgent(ctx context.Context, userID, canvasID string
dsl := canvasInstance.DSL
title := canvasInstance.Title
description := canvasInstance.Description
+ var alias *string
if req != nil {
if req.DSL != nil {
if err := component.ValidateIntegerParameters(req.DSL); err != nil {
@@ -1339,6 +1384,9 @@ func (s *AgentService) PublishAgent(ctx context.Context, userID, canvasID string
if req.Description != nil {
description = req.Description
}
+ if req.Alias != nil {
+ alias = req.Alias
+ }
}
if err := validateAgentChatModels(ctx, userID, canvasInstance.EffectiveTenantID(), dsl); err != nil {
@@ -1355,7 +1403,7 @@ func (s *AgentService) PublishAgent(ctx context.Context, userID, canvasID string
if title != nil {
titleStr = *title
}
- opts := s.saveOrReplaceVersionOptions(ctx, userID, canvasID, dsl, titleStr, description, true)
+ opts := s.saveOrReplaceVersionOptions(ctx, userID, canvasID, dsl, titleStr, description, alias, true)
var row *entity.UserCanvasVersion
if err = dao.DB.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
if err = s.canvasDAO.UpdateTx(ctx, tx, canvasInstance); err != nil {
@@ -1373,7 +1421,7 @@ func (s *AgentService) PublishAgent(ctx context.Context, userID, canvasID string
return row, nil
}
-func (s *AgentService) saveOrReplaceVersionOptions(ctx context.Context, userID, canvasID string, dsl entity.JSONMap, title string, description *string, release bool) dao.SaveOrReplaceLatestVersionOptions {
+func (s *AgentService) saveOrReplaceVersionOptions(ctx context.Context, userID, canvasID string, dsl entity.JSONMap, title string, description *string, alias *string, release bool) dao.SaveOrReplaceLatestVersionOptions {
nickname, err := s.userDAO.GetNicknameByID(ctx, dao.DB, userID)
if err != nil || strings.TrimSpace(nickname) == "" {
nickname = userID
@@ -1384,6 +1432,7 @@ func (s *AgentService) saveOrReplaceVersionOptions(ctx context.Context, userID,
UserCanvasID: canvasID,
Title: &versionTitle,
Description: description,
+ Alias: alias,
DSL: dsl,
Release: release,
SameDSL: func(latestDSL entity.JSONMap) bool {
@@ -1448,7 +1497,8 @@ func (s *AgentService) DeleteVersion(ctx context.Context, userID, canvasID, vers
if versionID == "" {
return dao.ErrUserCanvasVersionNotFound
}
- if _, err := s.loadCanvasForUser(ctx, userID, canvasID, permission.OperationUpdate); err != nil {
+ canvas, err := s.loadCanvasForUser(ctx, userID, canvasID, permission.OperationUpdate)
+ if err != nil {
return err
}
row, err := s.versionDAO.GetByID(ctx, dao.DB, versionID)
@@ -1458,11 +1508,49 @@ func (s *AgentService) DeleteVersion(ctx context.Context, userID, canvasID, vers
if row.UserCanvasID != canvasID {
return dao.ErrUserCanvasVersionNotFound
}
+ // Design B4 / A4: deleting a version is allowed even when bindings
+ // reference it (the B2.1 dialog already confirmed). Referencing bindings
+ // simply fall into the Missing state (design section 6.2). For dataflow
+ // canvases we scan references so the operator gets a warning about the
+ // affected bindings (design section 12 A4, scan scoped to dataflow only).
+ if canvas.CanvasCategory == "dataflow_canvas" {
+ if refs, rerr := s.versionDAO.CountPipelineVersionReferences(ctx, dao.DB, versionID); rerr == nil && refs > 0 {
+ common.Warn("delete canvas version still referenced by active bindings; referers will enter Missing state",
+ zap.String("canvas_id", canvasID),
+ zap.String("version_id", versionID),
+ zap.Int64("reference_count", refs))
+ }
+ }
return dao.DB.Transaction(func(tx *gorm.DB) error {
return s.versionDAO.DeleteTx(ctx, tx, versionID)
})
}
+// UpdateVersion patches mutable metadata (alias/title/description) of a single
+// version of a canvas the user can update. It never changes the DSL and never
+// creates a new version (design G2/§4.4). Returns
+// dao.ErrUserCanvasVersionNotFound when the row does not exist or belongs to a
+// different canvas, and dao.ErrUserCanvasNotFound when the parent canvas is not
+// updatable by the requesting user.
+func (s *AgentService) UpdateVersion(ctx context.Context, userID, canvasID, versionID string, patch dao.UserCanvasVersionPatch) error {
+ if versionID == "" {
+ return dao.ErrUserCanvasVersionNotFound
+ }
+ if _, err := s.loadCanvasForUser(ctx, userID, canvasID, permission.OperationUpdate); err != nil {
+ return err
+ }
+ row, err := s.versionDAO.GetByID(ctx, dao.DB, versionID)
+ if err != nil {
+ return err
+ }
+ if row.UserCanvasID != canvasID {
+ return dao.ErrUserCanvasVersionNotFound
+ }
+ return dao.DB.Transaction(func(tx *gorm.DB) error {
+ return s.versionDAO.UpdateTx(ctx, tx, versionID, patch)
+ })
+}
+
// ApplyVersion restores a saved version's DSL through the normal draft-save
// path, preserving the agent's metadata and version history.
func (s *AgentService) ApplyVersion(ctx context.Context, userID, canvasID, versionID string) error {
@@ -1476,7 +1564,9 @@ func (s *AgentService) ApplyVersion(ctx context.Context, userID, canvasID, versi
if version.DSL == nil {
return errors.New("agent version has no DSL to apply")
}
- return s.UpdateAgent(ctx, userID, canvasID, map[string]interface{}{"dsl": version.DSL})
+ // The "apply" flag tells UpdateAgent to reuse the latest draft version when
+ // the restored DSL already matches it, instead of minting a duplicate row.
+ return s.UpdateAgent(ctx, userID, canvasID, map[string]interface{}{"dsl": version.DSL, "apply": true})
}
// RunAgent starts a run for the given canvas and returns a channel of
diff --git a/internal/service/agent_message_draft_test.go b/internal/service/agent_message_draft_test.go
index f26f6f3cc6..e7755982a2 100644
--- a/internal/service/agent_message_draft_test.go
+++ b/internal/service/agent_message_draft_test.go
@@ -60,7 +60,11 @@ func TestMessageDraftRoundTripAndExecution(t *testing.T) {
t.Fatalf("params=%#v want %#v", got, tt.params)
}
versions, err := dao.NewUserCanvasVersionDAO().ListByCanvasID(t.Context(), dao.DB, row.ID)
- if err != nil || len(versions) != 1 {
+ // v5.2 §5.1: every manual Save mints a new version row, so repeated
+ // saves of identical DSL accumulate versions rather than reusing one.
+ // We only assert that at least one version exists and carries the
+ // latest DSL; the exact count is owned by the versioning design.
+ if err != nil || len(versions) < 1 {
t.Fatalf("versions=%v err=%v", len(versions), err)
}
if !reflect.DeepEqual(versions[0].DSL["components"].(map[string]any)["message"].(map[string]any)["obj"].(map[string]any)["params"], tt.params) {
diff --git a/internal/service/agent_test.go b/internal/service/agent_test.go
index 55d7febd19..dc6b32bc91 100644
--- a/internal/service/agent_test.go
+++ b/internal/service/agent_test.go
@@ -308,7 +308,7 @@ func TestListVersions_Success(t *testing.T) {
},
})
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
svc := NewAgentService()
versions, err := svc.ListVersions(ctx, "user-1", "canvas-1")
if err != nil {
@@ -353,7 +353,7 @@ func TestListVersions_Empty(t *testing.T) {
Title: sptr("Empty Agent"),
})
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
svc := NewAgentService()
versions, err := svc.ListVersions(ctx, "user-1", "canvas-empty")
if err != nil {
@@ -466,7 +466,7 @@ func TestGetVersion_Success(t *testing.T) {
DSL: entity.JSONMap{"model": "gpt-4"},
})
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
svc := NewAgentService()
v, err := svc.GetVersion(ctx, "user-1", "canvas-1", "v1")
if err != nil {
@@ -500,7 +500,7 @@ func TestGetVersion_WrongCanvas(t *testing.T) {
Title: sptr("version-1"),
})
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
svc := NewAgentService()
_, err := svc.GetVersion(ctx, "user-other", "canvas-other", "v1")
if err == nil {
@@ -525,7 +525,7 @@ func TestGetVersion_NotFound(t *testing.T) {
dao.DB = testDB
t.Cleanup(func() { dao.DB = orig })
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
svc := NewAgentService()
_, err := svc.GetVersion(ctx, "user-1", "canvas-1", "non-existent")
if err == nil {
@@ -580,7 +580,7 @@ func TestRunAgent_VersionBelongsToOtherCanvas(t *testing.T) {
DSL: entity.JSONMap{"components": map[string]any{}},
})
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
svc := NewAgentService()
_, err := svc.RunAgent(
ctx,
@@ -627,7 +627,7 @@ func TestRunAgent_VersionNotFound(t *testing.T) {
Title: sptr("Canvas 1"),
})
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
svc := NewAgentService()
_, err := svc.RunAgent(
ctx,
@@ -685,7 +685,7 @@ func TestRunAgent_NoVersionPublishedPlaceholder(t *testing.T) {
Title: sptr("Canvas With No Version"),
})
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
svc := NewAgentService()
events, err := svc.RunAgent(
WithAgentSessionID(ctx, "test-session"),
@@ -765,7 +765,7 @@ func TestRunAgentRejectsUntrustedSessionContinuation(t *testing.T) {
{name: "valid resume", sessionID: "session-valid", userID: "user-1"},
} {
t.Run(tc.name, func(t *testing.T) {
- events, err := svc.RunAgent(serviceTestContext(t, tc.userID, "user-1"), tc.userID, "canvas-1", tc.sessionID, "", "hello", nil)
+ events, err := svc.RunAgent(t.Context(), tc.userID, "canvas-1", tc.sessionID, "", "hello", nil)
if tc.wantErr {
if !errors.Is(err, dao.ErrUserCanvasNotFound) {
t.Fatalf("RunAgent error = %v, want ErrUserCanvasNotFound", err)
@@ -832,7 +832,7 @@ func TestRunAgent_StorageErrorFromCanvasAccess(t *testing.T) {
t.Fatalf("failed to close sql.DB: %v", cErr)
}
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
svc := NewAgentService()
_, err := svc.RunAgent(
ctx,
@@ -887,7 +887,7 @@ func TestLoadCanvasForUser_StorageErrorWrap(t *testing.T) {
t.Fatalf("failed to close sql.DB: %v", cErr)
}
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
svc := NewAgentService()
_, err := svc.loadCanvasForUser(ctx, "user-1", "canvas-1", permission.OperationRead)
if err == nil {
@@ -972,7 +972,7 @@ func TestListAgentSessionsServiceSuccess(t *testing.T) {
createAgentSessionTestConversation(t, "session-team", "canvas-1", "team-user", 2000)
createAgentSessionTestConversation(t, "session-other-agent", "canvas-other", "user-1", 9999)
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
resp, code, err := NewAgentService().ListAgentSessions(ctx, "user-1", "user-1", "canvas-1", ListAgentSessionsRequest{
Page: 1,
PageSize: 10,
@@ -1012,7 +1012,7 @@ func TestListAgentSessionsServiceDenied(t *testing.T) {
createAgentSessionTestCanvas(t, "canvas-1", "user-2")
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
resp, code, err := NewAgentService().ListAgentSessions(ctx, "user-1", "user-1", "canvas-1", ListAgentSessionsRequest{})
if err == nil {
t.Fatal("expected permission error")
@@ -1031,7 +1031,7 @@ func TestGetAgentSessionServiceSuccess(t *testing.T) {
createAgentSessionTestCanvas(t, "canvas-1", "user-1")
createAgentSessionTestConversation(t, "session-1", "canvas-1", "user-1", 1000)
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
session, code, err := NewAgentService().GetAgentSession(ctx, "user-1", "canvas-1", "session-1")
if err != nil {
t.Fatalf("GetAgentSession failed: %v", err)
@@ -1079,7 +1079,7 @@ func TestCreateAgentSessionWritesLatestVersionTitle(t *testing.T) {
t.Fatalf("failed to create newest version: %v", err)
}
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
svc := NewAgentService()
session, code, err := svc.CreateAgentSession(ctx, &CreateAgentSessionRequest{
UserID: "user-1",
@@ -1132,7 +1132,7 @@ func TestCreateAgentSessionNoVersionLeavesTitleNil(t *testing.T) {
createAgentSessionTestCanvas(t, "canvas-1", "user-1")
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
session, code, err := NewAgentService().CreateAgentSession(ctx, &CreateAgentSessionRequest{
UserID: "user-1",
AgentID: "canvas-1",
@@ -1239,7 +1239,7 @@ func TestCreateAgentSessionVersionLookupErrorReturnsServerError(t *testing.T) {
t.Fatalf("failed to drop user_canvas_version: %v", err)
}
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
session, code, err := NewAgentService().CreateAgentSession(ctx, &CreateAgentSessionRequest{
UserID: "user-1",
AgentID: "canvas-1",
@@ -1261,7 +1261,7 @@ func TestGetAgentSessionServiceNotFoundWhenSessionBelongsToAnotherAgent(t *testi
createAgentSessionTestCanvas(t, "canvas-1", "user-1")
createAgentSessionTestConversation(t, "session-other", "canvas-other", "user-1", 1000)
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
session, code, err := NewAgentService().GetAgentSession(ctx, "user-1", "canvas-1", "session-other")
if err == nil {
t.Fatal("expected not found error")
@@ -1281,7 +1281,7 @@ func TestDeleteAgentSessionItemServiceDeletesMatchingSession(t *testing.T) {
createAgentSessionTestConversation(t, "session-1", "canvas-1", "user-1", 1000)
createAgentSessionTestConversation(t, "session-other", "canvas-other", "user-1", 2000)
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
deleted, code, err := NewAgentService().DeleteAgentSessionItem(ctx, "user-1", "canvas-1", "session-1")
if err != nil {
t.Fatalf("DeleteAgentSessionItem failed: %v", err)
@@ -1315,7 +1315,7 @@ func TestDeleteAgentSessionItemServiceNoopForSessionFromAnotherAgent(t *testing.
createAgentSessionTestCanvas(t, "canvas-1", "user-1")
createAgentSessionTestConversation(t, "session-other", "canvas-other", "user-1", 1000)
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
deleted, code, err := NewAgentService().DeleteAgentSessionItem(ctx, "user-1", "canvas-1", "session-other")
if err != nil {
t.Fatalf("DeleteAgentSessionItem failed: %v", err)
@@ -1344,7 +1344,7 @@ func TestDeleteAgentSessionsServiceDeleteAll(t *testing.T) {
createAgentSessionTestConversation(t, "session-2", "canvas-1", "user-1", 2000)
createAgentSessionTestConversation(t, "session-other", "canvas-other", "user-1", 3000)
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
result, code, err := NewAgentService().DeleteAgentSessions(ctx, "user-1", "canvas-1", nil, true)
if err != nil {
t.Fatalf("DeleteAgentSessions failed: %v", err)
@@ -1382,7 +1382,7 @@ func TestDeleteAgentSessionsServiceDuplicateIDsPartial(t *testing.T) {
createAgentSessionTestCanvas(t, "canvas-1", "user-1")
createAgentSessionTestConversation(t, "session-1", "canvas-1", "user-1", 1000)
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
result, code, err := NewAgentService().DeleteAgentSessions(ctx, "user-1", "canvas-1", []string{"session-1", "session-1"}, false)
if err != nil {
t.Fatalf("DeleteAgentSessions failed: %v", err)
@@ -1414,7 +1414,7 @@ func TestDeleteAgentSessionsServiceMissingSessionError(t *testing.T) {
createAgentSessionTestCanvas(t, "canvas-1", "user-1")
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
result, code, err := NewAgentService().DeleteAgentSessions(ctx, "user-1", "canvas-1", []string{"missing-session"}, false)
if err == nil {
t.Fatal("expected missing session error")
@@ -1436,7 +1436,7 @@ func TestDeleteAgentSessionsServiceRequiresOwner(t *testing.T) {
createAgentSessionTestCanvas(t, "canvas-1", "user-2")
createAgentSessionTestConversation(t, "session-1", "canvas-1", "user-1", 1000)
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
result, code, err := NewAgentService().DeleteAgentSessions(ctx, "user-1", "canvas-1", []string{"session-1"}, false)
if err == nil {
t.Fatal("expected owner error")
@@ -1462,7 +1462,7 @@ func TestUpdateAgentTagsServiceSuccess(t *testing.T) {
createAgentSessionTestCanvas(t, "canvas-1", "user-1")
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
ok, code, err := NewAgentService().UpdateAgentTags(ctx, "user-1", "canvas-1", []interface{}{"alpha", "beta", "alpha", "with,comma"})
if err != nil {
t.Fatalf("UpdateAgentTags failed: %v", err)
@@ -1488,7 +1488,7 @@ func TestUpdateAgentTagsServiceInvalidPayload(t *testing.T) {
createAgentSessionTestCanvas(t, "canvas-1", "user-1")
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
ok, code, err := NewAgentService().UpdateAgentTags(ctx, "user-1", "canvas-1", map[string]string{"tag": "alpha"})
if err == nil {
t.Fatal("expected invalid tags error")
@@ -1514,7 +1514,7 @@ func TestUpdateAgentTagsServiceNoPermission(t *testing.T) {
createAgentSessionTestCanvas(t, "canvas-1", "user-2")
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
ok, code, err := NewAgentService().UpdateAgentTags(ctx, "user-1", "canvas-1", []string{"alpha"})
if err == nil {
t.Fatal("expected permission error")
@@ -1605,7 +1605,7 @@ func TestAssertHostIsSafeAllowsPrivateHostWhenConfigured(t *testing.T) {
}
func TestTestDBConnectionMissingFields(t *testing.T) {
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
code, err := NewAgentService().TestDBConnection(ctx, "user-1", &TestDBConnectionRequest{DBType: "mysql"})
if err == nil {
t.Fatal("expected missing field error")
@@ -1620,7 +1620,7 @@ func TestTestDBConnectionMissingFields(t *testing.T) {
}
func TestTestDBConnectionUnsupportedDatabaseType(t *testing.T) {
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
code, err := NewAgentService().TestDBConnection(ctx, "user-1", &TestDBConnectionRequest{
DBType: "unsupported",
Database: "rag_flow",
@@ -1661,7 +1661,7 @@ func ptr(v int64) *int64 { return &v }
func TestResetAgentServiceClearsPerRunState(t *testing.T) {
setupAgentSessionServiceTest(t)
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
initialDSL := entity.JSONMap{
"graph": map[string]any{
"nodes": []any{map[string]any{"id": "begin"}},
@@ -1766,7 +1766,7 @@ func TestResetAgentServiceClearsPerRunState(t *testing.T) {
func TestResetAgentServiceNotFound(t *testing.T) {
setupAgentSessionServiceTest(t)
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
_, err := NewAgentService().ResetAgent(ctx, "user-1", "missing")
if err == nil {
t.Fatal("expected error for missing canvas")
@@ -1790,7 +1790,7 @@ func TestUpdateAgentSettingsPreservesDSL(t *testing.T) {
},
},
}
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
if err := dao.DB.WithContext(ctx).Create(&entity.UserCanvas{
ID: "canvas-settings",
UserID: "user-1",
@@ -1826,7 +1826,7 @@ func TestUpdateAgentSettingsPreservesDSL(t *testing.T) {
func TestUpdateAgentAllowsExistingTitleForSameCanvas(t *testing.T) {
setupAgentSessionServiceTest(t)
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
if err := dao.DB.WithContext(ctx).Create(&entity.UserCanvas{
ID: "canvas-same-title",
@@ -1850,6 +1850,7 @@ func TestUpdateAgentAllowsExistingTitleForSameCanvas(t *testing.T) {
func TestUpdateAgentTeamMemberCanUpdateButCannotChangePermission(t *testing.T) {
setupAgentSessionServiceTest(t)
+ ctx := t.Context()
status := "1"
for _, row := range []*entity.UserCanvas{
@@ -1870,11 +1871,11 @@ func TestUpdateAgentTeamMemberCanUpdateButCannotChangePermission(t *testing.T) {
DSL: entity.JSONMap{},
},
} {
- if err := dao.DB.WithContext(t.Context()).Create(row).Error; err != nil {
+ if err := dao.DB.WithContext(ctx).Create(row).Error; err != nil {
t.Fatalf("failed to seed canvas %s: %v", row.ID, err)
}
}
- if err := dao.DB.WithContext(t.Context()).Create(&entity.UserTenant{
+ if err := dao.DB.WithContext(ctx).Create(&entity.UserTenant{
ID: "ut-agent-team",
UserID: "member-1",
TenantID: "owner-1",
@@ -1884,8 +1885,6 @@ func TestUpdateAgentTeamMemberCanUpdateButCannotChangePermission(t *testing.T) {
}).Error; err != nil {
t.Fatalf("failed to seed user tenant: %v", err)
}
- ctx := serviceTestContext(t, "member-1", "owner-1", "owner-1")
- grantServiceTestResource(t, "owner-1", "canvas", "canvas-team-edit", "member-1", testResourcePermissionRead|testResourcePermissionWrite)
samePermission := " TEAM "
if err := NewAgentService().UpdateAgent(ctx, "member-1", "canvas-team-edit", map[string]interface{}{
@@ -1914,8 +1913,7 @@ func TestUpdateAgentTeamMemberCanUpdateButCannotChangePermission(t *testing.T) {
if canvas.Permission != string(entity.TenantPermissionTeam) {
t.Fatalf("canvas permission = %q, want unchanged %q", canvas.Permission, entity.TenantPermissionTeam)
}
- ownerCtx := serviceTestContext(t, "owner-1", "owner-1")
- if err := NewAgentService().UpdateAgent(ownerCtx, "owner-1", "canvas-team-edit", map[string]interface{}{
+ if err := NewAgentService().UpdateAgent(ctx, "owner-1", "canvas-team-edit", map[string]interface{}{
"permission": nextPermission,
}); err != nil {
t.Fatalf("canvas owner could not change permission: %v", err)
@@ -1924,7 +1922,7 @@ func TestUpdateAgentTeamMemberCanUpdateButCannotChangePermission(t *testing.T) {
func TestUpdateAgentRejectsDuplicateTitleInDestinationCategory(t *testing.T) {
setupAgentSessionServiceTest(t)
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
if err := dao.DB.WithContext(ctx).Create(&entity.UserCanvas{
ID: "canvas-source-category",
@@ -1976,7 +1974,7 @@ func TestUpdateAgentRejectsCategoryOnlyDuplicateTitleInDestinationCategory(t *te
t.Fatalf("failed to seed duplicate agent: %v", err)
}
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
err := NewAgentService().UpdateAgent(ctx, "user-1", "canvas-category-only-source", map[string]interface{}{
"canvas_category": "dataflow_canvas",
})
@@ -1987,7 +1985,7 @@ func TestUpdateAgentRejectsCategoryOnlyDuplicateTitleInDestinationCategory(t *te
func TestUpdateAgentAllowsCaseOnlyTitleChange(t *testing.T) {
setupAgentSessionServiceTest(t)
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
if err := dao.DB.WithContext(ctx).Create(&entity.UserCanvas{
ID: "canvas-case-only-title",
@@ -2079,7 +2077,7 @@ func seedAgentServiceCreateContext(t *testing.T) context.Context {
t.Fatalf("create Agent permission test table: %v", err)
}
}
- return serviceTestContext(t, "user-1", "tenant-agent")
+ return permission.WithSubject(t.Context(), permission.Subject{UserID: "user-1", TenantID: "tenant-agent"})
}
func TestCreateAgentRequiresAuthenticatedUserID(t *testing.T) {
@@ -2095,7 +2093,7 @@ func TestCreateAgentRequiresAuthenticatedUserID(t *testing.T) {
func TestUpdateAgentPersistsDSLAsJSONMap(t *testing.T) {
setupAgentSessionServiceTest(t)
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
if err := dao.DB.WithContext(ctx).Create(&entity.UserCanvas{
ID: "canvas-dsl-update",
UserID: "user-1",
@@ -2181,18 +2179,27 @@ func TestUpdateAgentDSLCreatesAndReplacesDraftVersion(t *testing.T) {
if err != nil {
t.Fatalf("failed to list versions: %v", err)
}
- if len(versions) != 1 {
- t.Fatalf("expected same DSL to replace latest draft, got %d versions", len(versions))
+ // v5.2 §5.1: a manual Save always INSERTs a new version, even when the DSL
+ // is identical to the previous one (no same-DSL in-place refresh dedup).
+ if len(versions) != 2 {
+ t.Fatalf("expected every manual save to mint a new version, got %d versions", len(versions))
+ }
+ // create_time may tie within the same second, so select the version from the
+ // second ("Renamed Agent") save by its title instead of relying on list order.
+ var latest *entity.UserCanvasVersion
+ for _, v := range versions {
+ if v.Title != nil && strings.HasPrefix(*v.Title, "owner_Renamed Agent_") {
+ latest = v
+ }
}
- title := ""
- if versions[0].Title != nil {
- title = *versions[0].Title
+ if latest == nil {
+ t.Fatalf("could not find the renamed-agent version among %d versions", len(versions))
}
- if !strings.HasPrefix(title, "owner_Renamed Agent_") {
- t.Fatalf("unexpected version title: %q", title)
+ if latest.Title == nil || !strings.HasPrefix(*latest.Title, "owner_Renamed Agent_") {
+ t.Fatalf("unexpected version title: %v", latest.Title)
}
var release bool
- if err = dao.DB.WithContext(ctx).Table("user_canvas_version").Select("release").Where("id = ?", versions[0].ID).Scan(&release).Error; err != nil {
+ if err = dao.DB.WithContext(ctx).Table("user_canvas_version").Select("release").Where("id = ?", latest.ID).Scan(&release).Error; err != nil {
t.Fatalf("failed to read release flag: %v", err)
}
if release {
@@ -2216,7 +2223,7 @@ func TestUpdateAgentReleaseTrueMarksCanvasAndVersionReleased(t *testing.T) {
t.Fatalf("failed to seed agent: %v", err)
}
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
// The front-end publish flow sends release as the string "true".
if err := NewAgentService().UpdateAgent(ctx, "user-1", "canvas-update-release", map[string]interface{}{
"title": "Release Agent",
@@ -2283,7 +2290,7 @@ func TestUpdateAgentWithoutReleaseKeepsCanvasUnreleased(t *testing.T) {
// Python parity: update_agent coerces a missing release to False and
// always writes it back to the canvas row.
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
if err := NewAgentService().UpdateAgent(ctx, "user-1", "canvas-update-draft", map[string]interface{}{
"title": "Draft Agent",
"dsl": map[string]interface{}{
@@ -2334,7 +2341,7 @@ func TestListAgentsIncludesReleaseTime(t *testing.T) {
}).Error; err != nil {
t.Fatalf("failed to seed released version: %v", err)
}
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
resp, code, err := NewAgentService().ListAgents(ctx, "user-1", "", 1, 30, []dao.OrderTerm{{Column: "create_time", Desc: true}}, nil, "", "", nil)
if err != nil || code != common.CodeSuccess {
t.Fatalf("ListAgents failed: code=%v err=%v", code, err)
@@ -2384,7 +2391,7 @@ func TestListAgents_MultiCategoryFilter(t *testing.T) {
}
}
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
resp, code, err := NewAgentService().ListAgents(ctx, "user-1", "", 1, 30, []dao.OrderTerm{{Column: "create_time", Desc: true}}, nil, "dataflow_canvas,agent_canvas", "", nil)
if err != nil || code != common.CodeSuccess {
t.Fatalf("ListAgents failed: code=%v err=%v", code, err)
@@ -2434,7 +2441,7 @@ func TestListAgents_MergesCompilationTemplateGroups(t *testing.T) {
t.Fatalf("failed to seed builtin group: %v", err)
}
- resp, code, err := NewAgentService().ListAgents(serviceTestContext(t, "user-1", "user-1"), "user-1", "", 1, 30, []dao.OrderTerm{{Column: "create_time", Desc: true}}, nil, "", "", nil)
+ resp, code, err := NewAgentService().ListAgents(t.Context(), "user-1", "", 1, 30, []dao.OrderTerm{{Column: "create_time", Desc: true}}, nil, "", "", nil)
if err != nil || code != common.CodeSuccess {
t.Fatalf("ListAgents failed: code=%v err=%v", code, err)
}
@@ -2600,12 +2607,8 @@ func TestPublishAgentUpdatesCanvasAndReleasedVersion(t *testing.T) {
if row.Description == nil || *row.Description != description {
t.Fatalf("published version description = %v", row.Description)
}
- title := ""
- if row.Title != nil {
- title = *row.Title
- }
- if !strings.HasPrefix(title, "owner_Published Agent_") {
- t.Fatalf("unexpected published version title: %q", title)
+ if row.Title == nil || !strings.HasPrefix(*row.Title, "owner_Published Agent_") {
+ t.Fatalf("unexpected published version title: %v", row.Title)
}
persisted, err := dao.NewUserCanvasDAO().GetByID(ctx, dao.DB, "canvas-publish")
@@ -2643,8 +2646,8 @@ func TestPublishAgentUpdatesCanvasAndReleasedVersion(t *testing.T) {
func TestUpdateAgentDSLDoesNotOverwriteLatestReleasedVersion(t *testing.T) {
setupAgentSessionServiceTest(t)
- ctx := serviceTestContext(t, "user-1", "user-1")
- if err := dao.DB.WithContext(ctx).Where("id = ?", "user-1").FirstOrCreate(&entity.User{ID: "user-1", Nickname: "owner", Email: "[email protected]"}).Error; err != nil {
+ ctx := t.Context()
+ if err := dao.DB.WithContext(ctx).Create(&entity.User{ID: "user-1", Nickname: "owner", Email: "[email protected]"}).Error; err != nil {
t.Fatalf("failed to seed user: %v", err)
}
dsl := entity.JSONMap{
@@ -2719,7 +2722,7 @@ func TestResetAgentServiceOtherTenant(t *testing.T) {
setupAgentSessionServiceTest(t)
createAgentSessionTestCanvas(t, "canvas-1", "user-2")
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
_, err := NewAgentService().ResetAgent(ctx, "user-1", "canvas-1")
if !errors.Is(err, dao.ErrUserCanvasNotFound) {
t.Errorf("expected ErrUserCanvasNotFound for cross-tenant access, got %v", err)
@@ -2746,7 +2749,7 @@ func TestGetAgentSession_RejectsIDOR(t *testing.T) {
createAgentSessionTestCanvas(t, "agent-2", "user-1")
createAgentSessionTestConversation(t, "session-1", "agent-1", "user-1", 1000)
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
data, code, err := NewAgentService().GetAgentSession(ctx, "user-1", "agent-2", "session-1")
if err == nil {
t.Fatal("expected non-nil error for cross-agent session access")
@@ -2769,7 +2772,7 @@ func TestGetAgentSession_SuccessWhenAgentMatches(t *testing.T) {
createAgentSessionTestCanvas(t, "agent-1", "user-1")
createAgentSessionTestConversation(t, "session-1", "agent-1", "user-1", 1000)
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
data, code, err := NewAgentService().GetAgentSession(ctx, "user-1", "agent-1", "session-1")
if err != nil {
t.Fatalf("unexpected error: %v", err)
@@ -2799,7 +2802,7 @@ func TestDeleteAgentSessionItem_RejectsIDOR(t *testing.T) {
createAgentSessionTestCanvas(t, "agent-2", "user-1")
createAgentSessionTestConversation(t, "session-1", "agent-1", "user-1", 1000)
- ctx := serviceTestContext(t, "user-1", "user-1")
+ ctx := t.Context()
deleted, code, err := NewAgentService().DeleteAgentSessionItem(ctx, "user-1", "agent-2", "session-1")
if err != nil {
t.Fatalf("unexpected error: %v", err)
@@ -2871,7 +2874,6 @@ func createTeamSharedAgentTestFixtures(t *testing.T, canvasOwner, teammate, sess
if err := dao.DB.Create(&entity.UserCanvas{
ID: "canvas-1",
UserID: canvasOwner,
- TenantID: sptr(canvasOwner),
Title: sptr("Shared Agent"),
CanvasCategory: "agent_canvas",
Permission: string(entity.TenantPermissionTeam),
@@ -2887,7 +2889,6 @@ func createTeamSharedAgentTestFixtures(t *testing.T, canvasOwner, teammate, sess
}).Error; err != nil {
t.Fatalf("failed to create user tenant: %v", err)
}
- grantServiceTestResource(t, canvasOwner, "canvas", "canvas-1", teammate, testResourcePermissionRead)
createAgentSessionTestConversation(t, sessionID, "canvas-1", sessionOwner, 1000)
}
@@ -2895,8 +2896,7 @@ func TestDeleteAgent_SharedCanvasMemberCannotDeleteAgent(t *testing.T) {
setupAgentSessionServiceTest(t)
createTeamSharedAgentTestFixtures(t, "owner-1", "user-1", "session-1", "owner-1")
- ctx := serviceTestContext(t, "user-1", "owner-1", "owner-1")
- err := NewAgentService().DeleteAgent(ctx, "user-1", "canvas-1")
+ err := NewAgentService().DeleteAgent(t.Context(), "user-1", "canvas-1")
if !errors.Is(err, ErrAgentNotOwner) {
t.Fatalf("DeleteAgent error = %v, want ErrAgentNotOwner", err)
}
@@ -2913,8 +2913,7 @@ func TestDeleteAgentSessionItem_SharedCanvasGrantsDeleteAccess(t *testing.T) {
setupAgentSessionServiceTest(t)
createTeamSharedAgentTestFixtures(t, "owner-1", "user-1", "session-1", "owner-1")
- ctx := serviceTestContext(t, "user-1", "owner-1", "owner-1")
- deleted, code, err := NewAgentService().DeleteAgentSessionItem(ctx, "user-1", "canvas-1", "session-1")
+ deleted, code, err := NewAgentService().DeleteAgentSessionItem(t.Context(), "user-1", "canvas-1", "session-1")
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
@@ -2938,8 +2937,7 @@ func TestDeleteAgentSessionItem_SessionCreatorCanDeleteOwnSession(t *testing.T)
setupAgentSessionServiceTest(t)
createTeamSharedAgentTestFixtures(t, "owner-1", "user-1", "session-1", "user-1")
- ctx := serviceTestContext(t, "user-1", "owner-1", "owner-1")
- deleted, code, err := NewAgentService().DeleteAgentSessionItem(ctx, "user-1", "canvas-1", "session-1")
+ deleted, code, err := NewAgentService().DeleteAgentSessionItem(t.Context(), "user-1", "canvas-1", "session-1")
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
@@ -2955,8 +2953,7 @@ func TestDeleteAgentSessionItem_CanvasOwnerCanDeleteAnySession(t *testing.T) {
setupAgentSessionServiceTest(t)
createTeamSharedAgentTestFixtures(t, "owner-1", "user-1", "session-1", "user-1")
- ctx := serviceTestContext(t, "owner-1", "owner-1", "user-1")
- deleted, code, err := NewAgentService().DeleteAgentSessionItem(ctx, "owner-1", "canvas-1", "session-1")
+ deleted, code, err := NewAgentService().DeleteAgentSessionItem(t.Context(), "owner-1", "canvas-1", "session-1")
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
diff --git a/internal/service/dataset/crud.go b/internal/service/dataset/crud.go
index ef732b2b0b..d3f32d486f 100644
--- a/internal/service/dataset/crud.go
+++ b/internal/service/dataset/crud.go
@@ -20,6 +20,35 @@ import (
"gorm.io/gorm"
)
+// resolvePipelineVersionID determines which canvas version to bind for a
+// dataset/document in Pipeline mode (design section 5 sticky snapshot). When a
+// specific version is requested it must belong to the bound pipeline (ownership
+// check, design T13); otherwise the latest version of the bound canvas is used.
+// BuiltIn mode (no pipelineID) yields nil.
+func resolvePipelineVersionID(ctx context.Context, db *gorm.DB, pipelineID *string, requestedVersionID *string) (*string, error) {
+ if pipelineID == nil || strings.TrimSpace(*pipelineID) == "" {
+ return nil, nil
+ }
+ canvasID := strings.TrimSpace(*pipelineID)
+ if requestedVersionID != nil && strings.TrimSpace(*requestedVersionID) != "" {
+ v, err := dao.NewUserCanvasVersionDAO().GetByID(ctx, db, strings.TrimSpace(*requestedVersionID))
+ if err != nil {
+ if errors.Is(err, dao.ErrUserCanvasVersionNotFound) {
+ return nil, fmt.Errorf("pipeline version %s not found: %w", *requestedVersionID, service.ErrPipelineVersionMissing)
+ }
+ return nil, fmt.Errorf("load pipeline version %s: %w", *requestedVersionID, err)
+ }
+ if v.UserCanvasID != canvasID {
+ return nil, fmt.Errorf("pipeline version %s does not belong to canvas %s: %w", *requestedVersionID, canvasID, service.ErrPipelineVersionMissing)
+ }
+ return requestedVersionID, nil
+ }
+ if v, err := dao.NewUserCanvasVersionDAO().GetLatest(ctx, db, canvasID); err == nil && v != nil {
+ return &v.ID, nil
+ }
+ return nil, nil
+}
+
func (d *DatasetService) CreateDataset(ctx context.Context, req *service.CreateDatasetRequest, subject permission.Subject) (map[string]interface{}, common.ErrorCode, error) {
tenantID := strings.TrimSpace(subject.TenantID)
userID := strings.TrimSpace(subject.UserID)
@@ -138,7 +167,18 @@ func (d *DatasetService) CreateDataset(ctx context.Context, req *service.CreateD
}
}
isPipeline := pipelineID != nil && strings.TrimSpace(*pipelineID) != ""
- dslJSON, dslErr := service.LoadPipelineDSL(ctx, isPipeline, parserID, pipelineID)
+ // design C5/G3: an empty version in Pipeline mode is no longer auto-backfilled
+ // to the canvas latest; the Save is rejected so the UI can show the red Missing
+ // badge and surface the "版本信息缺失" error. BuiltIn mode (no canvas bound) is
+ // exempt.
+ if isPipeline && (req.PipelineVersionID == nil || strings.TrimSpace(*req.PipelineVersionID) == "") {
+ return nil, common.CodeBadRequest, service.ErrPipelineVersionEmpty
+ }
+ pipelineVersionID, verr := resolvePipelineVersionID(ctx, dao.DB, pipelineID, req.PipelineVersionID)
+ if verr != nil {
+ return nil, common.CodeBadRequest, verr
+ }
+ dslJSON, dslErr := service.LoadPipelineDSL(ctx, isPipeline, parserID, pipelineID, pipelineVersionID)
parserConfig := entity.JSONMap{}
if dslErr != nil {
common.Warn("failed to load pipeline DSL for building parser_config",
@@ -225,18 +265,19 @@ func (d *DatasetService) CreateDataset(ctx context.Context, req *service.CreateD
parserConfig = service.ApplyComponentScopedParserConfig(parserConfig, llmID)
kb := &entity.Knowledgebase{
- ID: kbID,
- Name: name,
- TenantID: tenantID,
- CreatedBy: userID,
- ParserID: parserID,
- PipelineID: pipelineID,
- ParserConfig: entity.JSONMap(parserConfigMap),
- Permission: visibility,
- Language: language,
- EmbdID: embdID,
- TenantEmbdID: stringPtrIfNotEmpty(tenantEmbdID),
- Status: &status,
+ ID: kbID,
+ PipelineVersionID: pipelineVersionID,
+ Name: name,
+ TenantID: tenantID,
+ CreatedBy: userID,
+ ParserID: parserID,
+ PipelineID: pipelineID,
+ ParserConfig: entity.JSONMap(parserConfigMap),
+ Permission: visibility,
+ Language: language,
+ EmbdID: embdID,
+ TenantEmbdID: stringPtrIfNotEmpty(tenantEmbdID),
+ Status: &status,
}
if err = dao.DB.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
@@ -260,7 +301,7 @@ func (d *DatasetService) CreateDataset(ctx context.Context, req *service.CreateD
return nil, common.CodeServerError, errors.New("dataset created failed")
}
- return datasetToMap(createdKB), common.CodeSuccess, nil
+ return datasetToMap(ctx, createdKB), common.CodeSuccess, nil
}
// dedupeDatasetName returns a non-colliding dataset name within the tenant,
@@ -297,7 +338,7 @@ func (d *DatasetService) GetDataset(ctx context.Context, datasetID, userID strin
return nil, code, permissionErr
}
- data := datasetToMap(kb)
+ data := datasetToMap(ctx, kb)
operatorPermission, err := service.ResolveOperatorPermission(ctx, userID, permission.ResourceRef{
Kind: permission.ResourceKindDataset,
ID: kb.ID,
@@ -670,11 +711,14 @@ func (d *DatasetService) ListDatasets(ctx context.Context, id, name string, page
data := make([]map[string]interface{}, 0, len(kbs))
modelNameCache := make(map[string]string)
+ // Resolve the latest version id per canvas once for the whole page so the
+ // per-row outdated flag does not issue a GetLatest per dataset (N+1).
+ latestVersionByCanvas := latestVersionIDsByCanvas(ctx, kbs)
for _, kb := range kbs {
if kb == nil {
continue
}
- item := datasetListItemToMap(kb)
+ item := datasetListItemToMap(latestVersionByCanvas, kb)
item["operator_permission"] = operatorPermissions[kb.ID]
// Mirror the memory list: surface the concrete model display name
// (modelName@instance@provider) instead of a raw tenant_model ID.
diff --git a/internal/service/dataset/empty_version_test.go b/internal/service/dataset/empty_version_test.go
new file mode 100644
index 0000000000..330017aa07
--- /dev/null
+++ b/internal/service/dataset/empty_version_test.go
@@ -0,0 +1,186 @@
+package dataset
+
+import (
+ "errors"
+ "testing"
+
+ "ragflow/internal/common"
+ "ragflow/internal/entity"
+ "ragflow/internal/service"
+)
+
+// T39 (design C5/G3): creating a dataset in Pipeline (dataflow canvas) mode with
+// no concrete pinned version must be REJECTED with ErrPipelineVersionEmpty. The
+// empty version is no longer auto-backfilled to the canvas latest; the Save fails
+// so the UI can show the red Missing badge and the "版本信息缺失" error. The KB
+// must NOT be persisted.
+func TestCreateDataset_EmptyVersionRejected(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ insertCreateDatasetTenant(t, "tenant-1")
+ ctx := t.Context()
+
+ canvasID := "0123456789abcdef0123456789abcdef"
+ seedDataflowCanvas(t, db, canvasID)
+ seedCanvasVersion(t, db, canvasID, "version0000000000000000000000aa", 0)
+
+ parseType := 2
+ result, code, err := testDatasetCreateService(t).CreateDataset(ctx, &service.CreateDatasetRequest{
+ Name: "ds-empty-version",
+ PipelineID: &canvasID,
+ ParseType: &parseType,
+ // PipelineVersionID omitted on purpose (empty version)
+ }, testDatasetSubject("tenant-1"))
+ if err == nil {
+ t.Fatalf("expected rejection of empty pipeline version, got result=%v code=%d", result, code)
+ }
+ if code != common.CodeBadRequest {
+ t.Fatalf("expected CodeBadRequest, got code=%d err=%v", code, err)
+ }
+ if !errors.Is(err, service.ErrPipelineVersionEmpty) {
+ t.Fatalf("expected ErrPipelineVersionEmpty, got: %v", err)
+ }
+ var count int64
+ if err := db.Model(&entity.Knowledgebase{}).Where("name = ?", "ds-empty-version").Count(&count).Error; err != nil {
+ t.Fatalf("count kb: %v", err)
+ }
+ if count != 0 {
+ t.Fatalf("empty-version create must not persist a KB, got count=%d", count)
+ }
+}
+
+// T39 adversarial: an explicit EMPTY string version (not just omitted) is also
+// rejected in Pipeline mode.
+func TestCreateDataset_ExplicitEmptyVersionStringRejected(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ insertCreateDatasetTenant(t, "tenant-1")
+ ctx := t.Context()
+
+ canvasID := "0123456789abcdef0123456789abcdef"
+ seedDataflowCanvas(t, db, canvasID)
+ seedCanvasVersion(t, db, canvasID, "version0000000000000000000000aa", 0)
+
+ parseType := 2
+ empty := ""
+ _, code, err := testDatasetCreateService(t).CreateDataset(ctx, &service.CreateDatasetRequest{
+ Name: "ds-empty-version-str",
+ PipelineID: &canvasID,
+ PipelineVersionID: &empty,
+ ParseType: &parseType,
+ }, testDatasetSubject("tenant-1"))
+ if err == nil || code == common.CodeSuccess {
+ t.Fatalf("expected rejection of explicit empty version, got code=%d err=%v", code, err)
+ }
+ if !errors.Is(err, service.ErrPipelineVersionEmpty) {
+ t.Fatalf("expected ErrPipelineVersionEmpty, got: %v", err)
+ }
+}
+
+// T39 adversarial (built-in exempt): BuiltIn mode must NOT require a version.
+// An empty version in BuiltIn mode is allowed and the dataset is created.
+func TestCreateDataset_BuiltinEmptyVersionAllowed(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ insertCreateDatasetTenant(t, "tenant-1")
+ ctx := t.Context()
+
+ parseType := 1
+ general := "general"
+ result, code, err := testDatasetCreateService(t).CreateDataset(ctx, &service.CreateDatasetRequest{
+ Name: "ds-builtin-no-version",
+ ParserID: &general,
+ ParseType: &parseType,
+ }, testDatasetSubject("tenant-1"))
+ if err != nil || code != common.CodeSuccess {
+ t.Fatalf("expected BuiltIn create without version to succeed, got code=%d err=%v", code, err)
+ }
+ if result["id"] == nil {
+ t.Fatalf("expected created dataset id, got %v", result)
+ }
+}
+
+// T40 (dataset layer, design C5/G3): updating an existing Pipeline-mode dataset
+// with an explicit empty version is rejected (it must not silently clear the
+// pin). Used to fail with ErrPipelineVersionEmpty.
+func TestUpdateDataset_ExplicitEmptyVersionRejected(t *testing.T) {
+ db := setupDatasetUpdateTestDB(t)
+ pushServiceDB(t, db)
+
+ canvas1 := "0123456789abcdef0123456789abcdef"
+ ver1 := "version0000000000000000000000aa"
+ seedDataflowCanvasWithVersion(t, db, canvas1, ver1)
+ seedBoundKB(t, db, "kb-empty-upd", canvas1, ver1)
+
+ parseType := 2
+ empty := ""
+ _, code, err := testDatasetUpdateService(t).UpdateDataset(t.Context(), "kb-empty-upd", "tenant-1", service.UpdateDatasetRequest{
+ PipelineID: &canvas1,
+ ParseType: &parseType,
+ PipelineVersionID: &empty,
+ })
+ if err == nil || code == common.CodeSuccess {
+ t.Fatalf("expected rejection of explicit empty version on update, got code=%d err=%v", code, err)
+ }
+ if !errors.Is(err, service.ErrPipelineVersionEmpty) {
+ t.Fatalf("expected ErrPipelineVersionEmpty, got: %v", err)
+ }
+ var kb entity.Knowledgebase
+ if err := db.Where("id = ?", "kb-empty-upd").Take(&kb).Error; err != nil {
+ t.Fatalf("load kb: %v", err)
+ }
+ if kb.PipelineVersionID == nil || *kb.PipelineVersionID != ver1 {
+ t.Fatalf("pin must be preserved on rejected update, got %v", kb.PipelineVersionID)
+ }
+}
+
+// T40 adversarial: switching a BuiltIn dataset to a new Pipeline canvas WITHOUT
+// supplying a version is rejected (no GetLatest auto-backfill for empty version).
+func TestUpdateDataset_PipelineChangeWithoutVersionRejected(t *testing.T) {
+ db := setupDatasetUpdateTestDB(t)
+ pushServiceDB(t, db)
+
+ canvas1 := "0123456789abcdef0123456789abcdef"
+ seedDataflowCanvasWithVersion(t, db, canvas1, "version0000000000000000000000aa")
+ insertDatasetUpdateKB(t, "kb-switch", "tenant-1", "Original") // builtin, no pipeline bound
+
+ parseType := 2
+ _, code, err := testDatasetUpdateService(t).UpdateDataset(t.Context(), "kb-switch", "tenant-1", service.UpdateDatasetRequest{
+ PipelineID: &canvas1,
+ ParseType: &parseType,
+ })
+ if err == nil || code == common.CodeSuccess {
+ t.Fatalf("expected rejection of pipeline switch without version, got code=%d err=%v", code, err)
+ }
+ if !errors.Is(err, service.ErrPipelineVersionEmpty) {
+ t.Fatalf("expected ErrPipelineVersionEmpty, got: %v", err)
+ }
+}
+
+// T40 control: a partial update that omits the pipeline selection entirely must
+// PRESERVE the existing pinned version (no error). The empty-version rule only
+// fires when the effective mode is Pipeline with no concrete version.
+func TestUpdateDataset_PreservePinnedVersionOnPartialUpdate(t *testing.T) {
+ db := setupDatasetUpdateTestDB(t)
+ pushServiceDB(t, db)
+
+ canvas1 := "0123456789abcdef0123456789abcdef"
+ ver1 := "version0000000000000000000000aa"
+ seedDataflowCanvasWithVersion(t, db, canvas1, ver1)
+ seedBoundKB(t, db, "kb-preserve", canvas1, ver1)
+
+ name := "renamed-partial"
+ _, code, err := testDatasetUpdateService(t).UpdateDataset(t.Context(), "kb-preserve", "tenant-1", service.UpdateDatasetRequest{
+ Name: &name,
+ })
+ if err != nil || code != common.CodeSuccess {
+ t.Fatalf("expected partial update (preserve pin) to succeed, got code=%d err=%v", code, err)
+ }
+ var kb entity.Knowledgebase
+ if err := db.Where("id = ?", "kb-preserve").Take(&kb).Error; err != nil {
+ t.Fatalf("load kb: %v", err)
+ }
+ if kb.PipelineVersionID == nil || *kb.PipelineVersionID != ver1 {
+ t.Fatalf("pin must be preserved, got %v", kb.PipelineVersionID)
+ }
+}
diff --git a/internal/service/dataset/gap_b1b2_test.go b/internal/service/dataset/gap_b1b2_test.go
new file mode 100644
index 0000000000..d4ad281c68
--- /dev/null
+++ b/internal/service/dataset/gap_b1b2_test.go
@@ -0,0 +1,169 @@
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package dataset
+
+import (
+ "testing"
+
+ "ragflow/internal/common"
+ "ragflow/internal/entity"
+ "ragflow/internal/service"
+
+ "gorm.io/gorm"
+)
+
+// seedGapCanvas creates a dataflow canvas once. Callers seed versions separately.
+func seedGapCanvas(t *testing.T, db *gorm.DB, canvasID string) {
+ t.Helper()
+ if err := db.AutoMigrate(&entity.UserCanvas{}, &entity.UserCanvasVersion{}); err != nil {
+ t.Fatalf("migrate canvas/version: %v", err)
+ }
+ canvas := &entity.UserCanvas{
+ ID: canvasID,
+ UserID: "tenant-1",
+ CanvasCategory: "dataflow_canvas",
+ Permission: "me",
+ DSL: entity.JSONMap{"graph": "legacy"},
+ }
+ if err := db.Create(canvas).Error; err != nil {
+ t.Fatalf("seed canvas: %v", err)
+ }
+}
+
+// seedGapVersion inserts a version whose DSL carries a distinctive component
+// default (source = marker). ComponentParamsDefaults surfaces that marker into
+// parser_config["Parser:Shared"]["source"], which lets a test observe which version's
+// DSL was used to rebuild parser_config.
+func seedGapVersion(t *testing.T, db *gorm.DB, canvasID, versionID, marker string, createMs int64) {
+ t.Helper()
+ dsl := entity.JSONMap{"components": map[string]any{
+ "Parser:Shared": map[string]any{"obj": map[string]any{
+ "component_name": "Parser",
+ "params": map[string]any{"source": marker, "k": "x"},
+ }},
+ }}
+ ct := createMs
+ if err := db.Create(&entity.UserCanvasVersion{
+ ID: versionID,
+ UserCanvasID: canvasID,
+ DSL: dsl,
+ BaseModel: entity.BaseModel{CreateTime: &ct},
+ }).Error; err != nil {
+ t.Fatalf("seed version: %v", err)
+ }
+}
+
+// seedBoundKBWithVersion creates a knowledgebase already bound to a canvas + version.
+func seedBoundKBWithVersion(t *testing.T, db *gorm.DB, kbID, canvasID, versionID string) {
+ t.Helper()
+ kb := &entity.Knowledgebase{
+ ID: kbID,
+ TenantID: "tenant-1",
+ CreatedBy: "tenant-1",
+ Name: kbID,
+ EmbdID: "BAAI/bge-large-zh-v1.5@Builtin",
+ Permission: string(entity.TenantPermissionMe),
+ ParserID: string(entity.ParserTypeNaive),
+ ParserConfig: entity.JSONMap{},
+ Status: sptr(string(entity.StatusValid)),
+ PipelineID: &canvasID,
+ PipelineVersionID: &versionID,
+ }
+ if err := db.Create(kb).Error; err != nil {
+ t.Fatalf("seed kb: %v", err)
+ }
+ ensureDatasetTestMembership(t, "tenant-1", "tenant-1", "owner")
+}
+
+// B1 (design section 5 fallback chain, T7g): editing parser_config on a KB pinned to a
+// non-latest version must rebuild parser_config from the PINNED version DSL, not
+// GetLatest. Uses pinned != latest fixture (adversarial).
+func TestUpdateDataset_ParserConfigRebuildUsesPinnedVersionDSL(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ insertCreateDatasetTenant(t, "tenant-1")
+
+ canvasID := "1234567890abcdef1234567890abcdef"
+ // v-old is the pinned version; v-latest is newer (larger create time) so GetLatest != pinned.
+ seedGapCanvas(t, db, canvasID)
+ seedGapVersion(t, db, canvasID, "v-old", "OLD_MARKER", 100)
+ seedGapVersion(t, db, canvasID, "v-latest", "LATEST_MARKER", 200)
+ seedBoundKBWithVersion(t, db, "kb-1", canvasID, "v-old")
+
+ // Request omits pipeline_id AND pipeline_version_id; only parser_config changes.
+ _, code, err := testDatasetUpdateService(t).UpdateDataset(t.Context(), "kb-1", "tenant-1",
+ service.UpdateDatasetRequest{
+ ParserConfig: map[string]interface{}{"Parser:Shared": map[string]interface{}{"k": "override"}},
+ })
+ if err != nil || code != common.CodeSuccess {
+ t.Fatalf("UpdateDataset err=%v code=%d", err, code)
+ }
+ var kb entity.Knowledgebase
+ if err := db.Where("id = ?", "kb-1").Take(&kb).Error; err != nil {
+ t.Fatalf("load kb: %v", err)
+ }
+ // B4 sticky snapshot: pin must remain the bound version.
+ if kb.PipelineVersionID == nil || *kb.PipelineVersionID != "v-old" {
+ t.Fatalf("pin changed unexpectedly: %v, want v-old", kb.PipelineVersionID)
+ }
+ // B1: parser_config must be rebuilt from the PINNED (v-old) DSL, not v-latest.
+ comp, ok := kb.ParserConfig["Parser:Shared"].(map[string]any)
+ if !ok {
+ t.Fatalf("parser_config missing Parser:Shared: %#v", kb.ParserConfig)
+ }
+ if comp["source"] != "OLD_MARKER" {
+ t.Fatalf("parser_config rebuilt from wrong version: source=%v, want OLD_MARKER (pinned DSL)", comp["source"])
+ }
+}
+
+// B2 (design section 5 canvas-context fallback, T7f): a single-field PATCH that sends ONLY
+// pipeline_version_id (omitting pipeline_id) must NOT clear the pin; it must re-pin to
+// the requested version using the already-bound canvas as context, and C3 must reset
+// parser_config to that version's defaults.
+func TestUpdateDataset_SingleFieldVersionPatchDoesNotClearPin(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ insertCreateDatasetTenant(t, "tenant-1")
+
+ canvasID := "1234567890abcdef1234567890abcdef"
+ seedGapCanvas(t, db, canvasID)
+ seedGapVersion(t, db, canvasID, "v-old", "OLD_MARKER", 100)
+ seedGapVersion(t, db, canvasID, "v-new", "NEW_MARKER", 200)
+ seedBoundKBWithVersion(t, db, "kb-1", canvasID, "v-old")
+
+ // Single-field PATCH: only pipeline_version_id, pipeline_id omitted.
+ _, code, err := testDatasetUpdateService(t).UpdateDataset(t.Context(), "kb-1", "tenant-1",
+ service.UpdateDatasetRequest{
+ PipelineVersionID: sptr("v-new"),
+ })
+ if err != nil || code != common.CodeSuccess {
+ t.Fatalf("UpdateDataset err=%v code=%d", err, code)
+ }
+ var kb entity.Knowledgebase
+ if err := db.Where("id = ?", "kb-1").Take(&kb).Error; err != nil {
+ t.Fatalf("load kb: %v", err)
+ }
+ if kb.PipelineVersionID == nil || *kb.PipelineVersionID != "v-new" {
+ t.Fatalf("pin cleared/incorrect: %v, want v-new", kb.PipelineVersionID)
+ }
+ // C3: version switch must reset parser_config to v-new defaults.
+ comp, ok := kb.ParserConfig["Parser:Shared"].(map[string]any)
+ if !ok {
+ t.Fatalf("parser_config missing Parser:Shared after switch: %#v", kb.ParserConfig)
+ }
+ if comp["source"] != "NEW_MARKER" {
+ t.Fatalf("C3 reset used wrong version: source=%v, want NEW_MARKER", comp["source"])
+ }
+}
diff --git a/internal/service/dataset/pipeline_version_batch_test.go b/internal/service/dataset/pipeline_version_batch_test.go
new file mode 100644
index 0000000000..44c40a805f
--- /dev/null
+++ b/internal/service/dataset/pipeline_version_batch_test.go
@@ -0,0 +1,57 @@
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package dataset
+
+import (
+ "testing"
+
+ "ragflow/internal/dao"
+)
+
+func TestPipelineVersionOutdatedBatch_MatchesSingleRow(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+
+ canvasID := "0123456789abcdef0123456789abcdef"
+ verOld := "version0000000000000000000000aa"
+ verNew := "version0000000000000000000000bb"
+ seedDataflowCanvas(t, db, canvasID)
+ seedCanvasVersion(t, db, canvasID, verOld, 0)
+ seedCanvasVersion(t, db, canvasID, verNew, 1000)
+
+ ctx := t.Context()
+ m, err := dao.NewUserCanvasVersionDAO().LatestIDsByCanvasIDs(ctx, db, []string{canvasID})
+ if err != nil {
+ t.Fatal(err)
+ }
+ if m[canvasID] != verNew {
+ t.Fatalf("LatestIDsByCanvasIDs[%s] = %q, want %q", canvasID, m[canvasID], verNew)
+ }
+ if !pipelineVersionOutdatedBatch(m, &canvasID, &verOld) {
+ t.Fatal("batch: pinned older version should be outdated")
+ }
+ if pipelineVersionOutdatedBatch(m, &canvasID, &verNew) {
+ t.Fatal("batch: pinned latest version should not be outdated")
+ }
+ if got, want := pipelineVersionOutdatedBatch(m, &canvasID, &verOld), pipelineVersionOutdated(ctx, &canvasID, &verOld); got != want {
+ t.Fatalf("batch vs single-row (old) = %v, want %v", got, want)
+ }
+ if got, want := pipelineVersionOutdatedBatch(m, &canvasID, &verNew), pipelineVersionOutdated(ctx, &canvasID, &verNew); got != want {
+ t.Fatalf("batch vs single-row (new) = %v, want %v", got, want)
+ }
+ if pipelineVersionOutdatedBatch(m, &canvasID, nil) {
+ t.Fatal("no pinned version should never be outdated")
+ }
+}
diff --git a/internal/service/dataset/pipeline_version_binding_test.go b/internal/service/dataset/pipeline_version_binding_test.go
new file mode 100644
index 0000000000..c379d48223
--- /dev/null
+++ b/internal/service/dataset/pipeline_version_binding_test.go
@@ -0,0 +1,607 @@
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package dataset
+
+import (
+ "errors"
+ "reflect"
+ "testing"
+ "time"
+
+ "ragflow/internal/common"
+ "ragflow/internal/entity"
+ "ragflow/internal/service"
+
+ "gorm.io/gorm"
+)
+
+func i64ptr(v int64) *int64 { return &v }
+
+// seedDataflowCanvasWithVersion inserts a dataflow canvas owned by tenant-1 with
+// a single version row so GetLatest can resolve it.
+func seedDataflowCanvasWithVersion(t *testing.T, db *gorm.DB, canvasID, versionID string) {
+ t.Helper()
+ if err := db.AutoMigrate(&entity.UserCanvasVersion{}); err != nil {
+ t.Fatalf("migrate version table: %v", err)
+ }
+ canvas := &entity.UserCanvas{
+ ID: canvasID,
+ UserID: "tenant-1",
+ CanvasCategory: "dataflow_canvas",
+ Permission: "me",
+ DSL: entity.JSONMap{"graph": "legacy"},
+ }
+ if err := db.Create(canvas).Error; err != nil {
+ t.Fatalf("seed canvas: %v", err)
+ }
+ ver := &entity.UserCanvasVersion{
+ ID: versionID,
+ UserCanvasID: canvasID,
+ DSL: entity.JSONMap{"graph": "versioned", "components": map[string]any{"Parser:Shared": map[string]any{"obj": map[string]any{"component_name": "Parser", "params": map[string]any{"source": "pinned", "k": "x"}}}}},
+ CreateTime: i64ptr(time.Now().UnixMilli()),
+ }
+ if err := db.Create(ver).Error; err != nil {
+ t.Fatalf("seed version: %v", err)
+ }
+}
+
+// seedBoundKB creates a knowledgebase already bound to a pipeline version.
+func seedBoundKB(t *testing.T, db *gorm.DB, kbID, canvasID, versionID string) {
+ t.Helper()
+ kb := &entity.Knowledgebase{
+ ID: kbID,
+ TenantID: "tenant-1",
+ CreatedBy: "tenant-1",
+ Name: kbID,
+ EmbdID: "BAAI/bge-large-zh-v1.5@Builtin",
+ Permission: string(entity.TenantPermissionMe),
+ ParserID: string(entity.ParserTypeNaive),
+ ParserConfig: entity.JSONMap{},
+ Status: sptr(string(entity.StatusValid)),
+ PipelineID: &canvasID,
+ PipelineVersionID: &versionID,
+ }
+ if err := db.Create(kb).Error; err != nil {
+ t.Fatalf("seed kb: %v", err)
+ }
+ ensureDatasetTestMembership(t, "tenant-1", "tenant-1", "owner")
+}
+
+// T6: creating a dataset in Pipeline mode binds the latest pipeline version.
+func TestCreateDataset_BindsLatestPipelineVersion(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ insertCreateDatasetTenant(t, "tenant-1")
+ ctx := t.Context()
+
+ canvasID := "0123456789abcdef0123456789abcdef"
+ versionID := "version0000000000000000000000aa"
+ seedDataflowCanvasWithVersion(t, db, canvasID, versionID)
+
+ parseType := 2
+ // C5/G3: Pipeline-mode create now requires an explicit version (the empty
+ // version is no longer auto-backfilled to the canvas latest). Supply the seeded
+ // version to verify the create still pins the chosen version.
+ result, code, err := testDatasetCreateService(t).CreateDataset(ctx, &service.CreateDatasetRequest{
+ Name: "ds-bind-version",
+ PipelineID: &canvasID,
+ PipelineVersionID: &versionID,
+ ParseType: &parseType,
+ }, testDatasetSubject("tenant-1"))
+ if err != nil || code != common.CodeSuccess {
+ t.Fatalf("CreateDataset err=%v code=%d", err, code)
+ }
+ var kb entity.Knowledgebase
+ if err := db.Where("id = ?", result["id"]).Take(&kb).Error; err != nil {
+ t.Fatalf("load kb: %v", err)
+ }
+ if kb.PipelineVersionID == nil || *kb.PipelineVersionID != versionID {
+ t.Fatalf("PipelineVersionID = %v, want %s", kb.PipelineVersionID, versionID)
+ }
+}
+
+// T6b: BuiltIn mode never binds a pipeline version.
+func TestCreateDataset_BuiltInHasNoPipelineVersion(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ insertCreateDatasetTenant(t, "tenant-1")
+ ctx := t.Context()
+
+ parseType := 1
+ parserID := "general"
+ result, code, err := testDatasetCreateService(t).CreateDataset(ctx, &service.CreateDatasetRequest{
+ Name: "ds-builtin",
+ ParserID: &parserID,
+ ParseType: &parseType,
+ }, testDatasetSubject("tenant-1"))
+ if err != nil || code != common.CodeSuccess {
+ t.Fatalf("CreateDataset err=%v code=%d", err, code)
+ }
+ var kb entity.Knowledgebase
+ if err := db.Where("id = ?", result["id"]).Take(&kb).Error; err != nil {
+ t.Fatalf("load kb: %v", err)
+ }
+ if kb.PipelineVersionID != nil {
+ t.Fatalf("PipelineVersionID = %v, want nil for builtin", *kb.PipelineVersionID)
+ }
+}
+
+// T7: changing the bound pipeline rewrites pipeline_version_id to the new
+// canvas's latest version (sticky snapshot, design B4).
+func TestUpdateDataset_RewritesVersionOnPipelineChange(t *testing.T) {
+ db := setupDatasetUpdateTestDB(t)
+ pushServiceDB(t, db)
+
+ canvas1 := "0123456789abcdef0123456789abcdef"
+ ver1 := "version0000000000000000000000aa"
+ canvas2 := "fedcba9876543210fedcba9876543210"
+ ver2 := "version0000000000000000000000bb"
+ seedDataflowCanvasWithVersion(t, db, canvas1, ver1)
+ seedDataflowCanvasWithVersion(t, db, canvas2, ver2)
+ seedBoundKB(t, db, "kb-change", canvas1, ver1)
+
+ parseType := 2
+ // C5/G3: switching the bound pipeline now requires an explicit version (the
+ // empty version is no longer auto-backfilled to the new canvas latest). Supply
+ // canvas2's version to verify the rewrite still pins the chosen version.
+ _, code, err := testDatasetUpdateService(t).UpdateDataset(t.Context(), "kb-change", "tenant-1", service.UpdateDatasetRequest{
+ PipelineID: &canvas2,
+ ParseType: &parseType,
+ PipelineVersionID: &ver2,
+ })
+ if err != nil || code != common.CodeSuccess {
+ t.Fatalf("UpdateDataset err=%v code=%d", err, code)
+ }
+ var kb entity.Knowledgebase
+ if err := db.Where("id = ?", "kb-change").Take(&kb).Error; err != nil {
+ t.Fatalf("load kb: %v", err)
+ }
+ if kb.PipelineVersionID == nil || *kb.PipelineVersionID != ver2 {
+ t.Fatalf("PipelineVersionID = %v, want %s after pipeline change", kb.PipelineVersionID, ver2)
+ }
+}
+
+// T7b: leaving the pipeline unchanged preserves the existing pipeline_version_id.
+func TestUpdateDataset_PreservesVersionWhenPipelineUnchanged(t *testing.T) {
+ db := setupDatasetUpdateTestDB(t)
+ pushServiceDB(t, db)
+
+ canvas1 := "0123456789abcdef0123456789abcdef"
+ ver1 := "version0000000000000000000000aa"
+ seedDataflowCanvasWithVersion(t, db, canvas1, ver1)
+ seedBoundKB(t, db, "kb-preserve", canvas1, ver1)
+
+ parseType := 2
+ name := "kb-preserve-renamed"
+ _, code, err := testDatasetUpdateService(t).UpdateDataset(t.Context(), "kb-preserve", "tenant-1", service.UpdateDatasetRequest{
+ Name: &name,
+ PipelineID: &canvas1,
+ ParseType: &parseType,
+ })
+ if err != nil || code != common.CodeSuccess {
+ t.Fatalf("UpdateDataset err=%v code=%d", err, code)
+ }
+ var kb entity.Knowledgebase
+ if err := db.Where("id = ?", "kb-preserve").Take(&kb).Error; err != nil {
+ t.Fatalf("load kb: %v", err)
+ }
+ if kb.PipelineVersionID == nil || *kb.PipelineVersionID != ver1 {
+ t.Fatalf("PipelineVersionID = %v, want preserved %s", kb.PipelineVersionID, ver1)
+ }
+}
+
+// seedDataflowCanvas inserts a dataflow canvas owned by tenant-1 (no versions).
+func seedDataflowCanvas(t *testing.T, db *gorm.DB, canvasID string) {
+ t.Helper()
+ if err := db.AutoMigrate(&entity.UserCanvasVersion{}); err != nil {
+ t.Fatalf("migrate version table: %v", err)
+ }
+ canvas := &entity.UserCanvas{
+ ID: canvasID,
+ UserID: "tenant-1",
+ CanvasCategory: "dataflow_canvas",
+ Permission: "me",
+ DSL: entity.JSONMap{"graph": "legacy"},
+ }
+ if err := db.Create(canvas).Error; err != nil {
+ t.Fatalf("seed canvas: %v", err)
+ }
+}
+
+// seedCanvasVersion inserts a version row with an explicit create-time offset
+// (milliseconds) so GetLatest ordering is deterministic in tests.
+func seedCanvasVersion(t *testing.T, db *gorm.DB, canvasID, versionID string, createOffsetMs int64) {
+ t.Helper()
+ ver := &entity.UserCanvasVersion{
+ ID: versionID,
+ UserCanvasID: canvasID,
+ DSL: entity.JSONMap{"graph": "versioned", "components": map[string]any{"Parser:Shared": map[string]any{"obj": map[string]any{"component_name": "Parser", "params": map[string]any{"source": "pinned", "k": "x"}}}}},
+ CreateTime: i64ptr(time.Now().UnixMilli() + createOffsetMs),
+ }
+ if err := db.Create(ver).Error; err != nil {
+ t.Fatalf("seed version %s: %v", versionID, err)
+ }
+}
+
+// seedCanvasVersionDSL inserts a version row with an explicit DSL that carries
+// real components, so ResolveComponentParamsDefaults can resolve component
+// params defaults for version-reset tests.
+func seedCanvasVersionDSL(t *testing.T, db *gorm.DB, canvasID, versionID string, dsl entity.JSONMap, createOffsetMs int64) {
+ t.Helper()
+ ver := &entity.UserCanvasVersion{
+ ID: versionID,
+ UserCanvasID: canvasID,
+ DSL: dsl,
+ CreateTime: i64ptr(time.Now().UnixMilli() + createOffsetMs),
+ }
+ if err := db.Create(ver).Error; err != nil {
+ t.Fatalf("seed version %s: %v", versionID, err)
+ }
+}
+
+// dslWithResetMarker returns a dataflow DSL whose single Parser component carries
+// a distinctive default param. Two versions seeded with different markers let a
+// test prove that a version switch reset the params to the NEW version defaults
+// (not a merge, not the old version, not empty).
+func dslWithResetMarker(marker string) entity.JSONMap {
+ return entity.JSONMap{
+ "components": map[string]any{
+ "Parser:ResetCpn": map[string]any{
+ "obj": map[string]any{
+ "component_name": "Parser",
+ "params": map[string]any{
+ "c3_reset_marker": marker,
+ },
+ },
+ },
+ },
+ }
+}
+
+// T7c: an explicit PipelineVersionID (not the latest) is bound as-is when it
+// belongs to the bound pipeline (design section 5 + T7 manual pin).
+func TestCreateDataset_BindsExplicitPipelineVersion(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ insertCreateDatasetTenant(t, "tenant-1")
+ ctx := t.Context()
+
+ canvasID := "0123456789abcdef0123456789abcdef"
+ verOld := "version0000000000000000000000aa"
+ verNew := "version0000000000000000000000bb"
+ seedDataflowCanvas(t, db, canvasID)
+ seedCanvasVersion(t, db, canvasID, verOld, 0)
+ seedCanvasVersion(t, db, canvasID, verNew, 1000) // verNew is the latest
+
+ parseType := 2
+ result, code, err := testDatasetCreateService(t).CreateDataset(ctx, &service.CreateDatasetRequest{
+ Name: "ds-explicit-version",
+ PipelineID: &canvasID,
+ PipelineVersionID: &verOld, // explicitly pin the older version
+ ParseType: &parseType,
+ }, testDatasetSubject("tenant-1"))
+ if err != nil || code != common.CodeSuccess {
+ t.Fatalf("CreateDataset err=%v code=%d", err, code)
+ }
+ var kb entity.Knowledgebase
+ if err := db.Where("id = ?", result["id"]).Take(&kb).Error; err != nil {
+ t.Fatalf("load kb: %v", err)
+ }
+ if kb.PipelineVersionID == nil || *kb.PipelineVersionID != verOld {
+ t.Fatalf("PipelineVersionID = %v, want explicit %s (not latest %s)", kb.PipelineVersionID, verOld, verNew)
+ }
+}
+
+// T7d: an explicit PipelineVersionID that belongs to a different canvas is
+// rejected (design T13 ownership check).
+func TestCreateDataset_RejectsForeignPipelineVersion(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ insertCreateDatasetTenant(t, "tenant-1")
+ ctx := t.Context()
+
+ canvas1 := "0123456789abcdef0123456789abcdef"
+ canvas2 := "fedcba9876543210fedcba9876543210"
+ ver1 := "version0000000000000000000000aa"
+ verForeign := "version0000000000000000000000cc"
+ seedDataflowCanvas(t, db, canvas1)
+ seedDataflowCanvas(t, db, canvas2)
+ seedCanvasVersion(t, db, canvas1, ver1, 0)
+ seedCanvasVersion(t, db, canvas2, verForeign, 0)
+
+ parseType := 2
+ _, code, err := testDatasetCreateService(t).CreateDataset(ctx, &service.CreateDatasetRequest{
+ Name: "ds-foreign-version",
+ PipelineID: &canvas1,
+ PipelineVersionID: &verForeign, // belongs to canvas2
+ ParseType: &parseType,
+ }, testDatasetSubject("tenant-1"))
+ if err == nil && code == common.CodeSuccess {
+ t.Fatalf("expected rejection of foreign pipeline version, got success")
+ }
+ if code != common.CodeBadRequest {
+ t.Fatalf("expected CodeBadRequest, got code=%d err=%v", code, err)
+ }
+}
+
+// T7e: updating with an explicit PipelineVersionID re-pins to that version even
+// when the pipeline itself is unchanged (design T7 manual pin).
+func TestUpdateDataset_RebindsExplicitVersion(t *testing.T) {
+ db := setupDatasetUpdateTestDB(t)
+ pushServiceDB(t, db)
+
+ canvas1 := "0123456789abcdef0123456789abcdef"
+ verOld := "version0000000000000000000000aa"
+ verNew := "version0000000000000000000000bb"
+ seedDataflowCanvas(t, db, canvas1)
+ seedCanvasVersion(t, db, canvas1, verOld, 0)
+ seedCanvasVersion(t, db, canvas1, verNew, 1000)
+ seedBoundKB(t, db, "kb-repin", canvas1, verOld)
+
+ parseType := 2
+ _, code, err := testDatasetUpdateService(t).UpdateDataset(t.Context(), "kb-repin", "tenant-1", service.UpdateDatasetRequest{
+ PipelineID: &canvas1,
+ PipelineVersionID: &verNew,
+ ParseType: &parseType,
+ })
+ if err != nil || code != common.CodeSuccess {
+ t.Fatalf("UpdateDataset err=%v code=%d", err, code)
+ }
+ var kb entity.Knowledgebase
+ if err := db.Where("id = ?", "kb-repin").Take(&kb).Error; err != nil {
+ t.Fatalf("load kb: %v", err)
+ }
+ if kb.PipelineVersionID == nil || *kb.PipelineVersionID != verNew {
+ t.Fatalf("PipelineVersionID = %v, want re-pinned %s", kb.PipelineVersionID, verNew)
+ }
+}
+
+// T14: pipelineVersionOutdated (! indicator) is true only when a pinned version
+// is not the latest of its canvas (design section 6.3).
+func TestPipelineVersionOutdated_ComputesFromLatest(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+
+ canvasID := "0123456789abcdef0123456789abcdef"
+ verOld := "version0000000000000000000000aa"
+ verNew := "version0000000000000000000000bb"
+ seedDataflowCanvas(t, db, canvasID)
+ seedCanvasVersion(t, db, canvasID, verOld, 0)
+ seedCanvasVersion(t, db, canvasID, verNew, 1000)
+
+ ctx := t.Context()
+ if pipelineVersionOutdated(ctx, &canvasID, &verNew) {
+ t.Fatalf("pinned latest version should not be outdated")
+ }
+ if !pipelineVersionOutdated(ctx, &canvasID, &verOld) {
+ t.Fatalf("pinned older version should be outdated")
+ }
+ if pipelineVersionOutdated(ctx, nil, &verOld) {
+ t.Fatalf("no pipeline should never be outdated")
+ }
+ if pipelineVersionOutdated(ctx, &canvasID, nil) {
+ t.Fatalf("no pinned version should never be outdated")
+ }
+}
+
+// T7d (updated for C5/G3): an explicit EMPTY PipelineVersionID in Pipeline mode is
+// REJECTED, not silently cleared to track latest. The empty version is no longer
+// auto-backfilled (design section 3); the save must fail with ErrPipelineVersionEmpty
+// and the existing pin must be preserved.
+func TestUpdateDataset_EmptyVersionClearsPin(t *testing.T) {
+ db := setupDatasetUpdateTestDB(t)
+ pushServiceDB(t, db)
+
+ canvas1 := "0123456789abcdef0123456789abcdef"
+ ver1 := "version0000000000000000000000aa"
+ seedDataflowCanvasWithVersion(t, db, canvas1, ver1)
+ seedBoundKB(t, db, "kb-clear", canvas1, ver1)
+
+ parseType := 2
+ empty := ""
+ _, code, err := testDatasetUpdateService(t).UpdateDataset(t.Context(), "kb-clear", "tenant-1", service.UpdateDatasetRequest{
+ PipelineID: &canvas1,
+ ParseType: &parseType,
+ PipelineVersionID: &empty,
+ })
+ if err == nil || code == common.CodeSuccess {
+ t.Fatalf("expected rejection of explicit empty version, got code=%d err=%v", code, err)
+ }
+ if !errors.Is(err, service.ErrPipelineVersionEmpty) {
+ t.Fatalf("err = %v, want ErrPipelineVersionEmpty", err)
+ }
+ var kb entity.Knowledgebase
+ if err := db.Where("id = ?", "kb-clear").Take(&kb).Error; err != nil {
+ t.Fatalf("load kb: %v", err)
+ }
+ if kb.PipelineVersionID == nil || *kb.PipelineVersionID != ver1 {
+ t.Fatalf("PipelineVersionID = %v, want preserved %s after rejected empty version", kb.PipelineVersionID, ver1)
+ }
+}
+
+// T26/C3: switching the pinned version of the SAME pipeline resets parser_config
+// to the new version default (design section 5 + T26). This is the V5 case: C3
+// must trigger on an explicit version change, not only on a pipeline_id change.
+func TestUpdateDataset_VersionChangeResetsParserConfigToNewVersionDefault(t *testing.T) {
+ db := setupDatasetUpdateTestDB(t)
+ pushServiceDB(t, db)
+
+ canvas1 := "0123456789abcdef0123456789abcdef"
+ verOld := "version0000000000000000000000aa"
+ verNew := "version0000000000000000000000bb"
+ seedDataflowCanvas(t, db, canvas1)
+ // Two versions carry DIFFERENT component defaults so the test can prove the
+ // reset loaded the NEW version (not a merge, not the old version, not empty).
+ seedCanvasVersionDSL(t, db, canvas1, verOld, dslWithResetMarker("OLD_VER_DEFAULT"), 0)
+ seedCanvasVersionDSL(t, db, canvas1, verNew, dslWithResetMarker("NEW_VER_DEFAULT"), 1000)
+ seedBoundKB(t, db, "kb-c3", canvas1, verOld)
+
+ // Distinctive parser_config that must NOT survive a version switch.
+ if err := db.Model(&entity.Knowledgebase{}).Where("id = ?", "kb-c3").
+ Update("parser_config", entity.JSONMap{"__c3_marker__": "OLD"}).Error; err != nil {
+ t.Fatalf("seed parser_config: %v", err)
+ }
+
+ ctx := t.Context()
+ parseType := 2
+ _, code, err := testDatasetUpdateService(t).UpdateDataset(ctx, "kb-c3", "tenant-1", service.UpdateDatasetRequest{
+ PipelineID: &canvas1,
+ PipelineVersionID: &verNew,
+ ParseType: &parseType,
+ // No ParserConfig: exercise the reset-to-default path.
+ })
+ if err != nil || code != common.CodeSuccess {
+ t.Fatalf("UpdateDataset err=%v code=%d", err, code)
+ }
+
+ var kb entity.Knowledgebase
+ if err := db.Where("id = ?", "kb-c3").Take(&kb).Error; err != nil {
+ t.Fatalf("load kb: %v", err)
+ }
+ if kb.PipelineVersionID == nil || *kb.PipelineVersionID != verNew {
+ t.Fatalf("PipelineVersionID = %v, want re-pinned %s", kb.PipelineVersionID, verNew)
+ }
+ // C3 (full reset, design A3 整体重置): the pre-switch marker must be gone
+ // (not merged), and the resolved config must come from the NEW version.
+ if v, ok := kb.ParserConfig["__c3_marker__"]; ok && v == "OLD" {
+ t.Fatalf("parser_config still holds pre-switch marker; C3 reset did not run: %v", kb.ParserConfig)
+ }
+ // Compute the expected value the SAME way the implementation does: resolve
+ // the new version defaults, then apply component-scoped scoping (a Parser
+ // node is left untouched, so llmID is irrelevant here).
+ resolved, derr := service.ResolveComponentParamsDefaults(ctx, string(entity.ParserTypeNaive), &canvas1, &verNew)
+ if derr != nil {
+ t.Fatalf("resolve new-version defaults: %v", derr)
+ }
+ expected := service.ApplyComponentScopedParserConfig(resolved, "")
+ if !reflect.DeepEqual(kb.ParserConfig, expected) {
+ t.Fatalf("parser_config = %v, want new-version default %v", kb.ParserConfig, expected)
+ }
+ // The new version's distinctive default must be present, and the old
+ // version's default must NOT be (proves the switch took effect).
+ cpn, ok := expected["Parser:ResetCpn"].(map[string]any)
+ if !ok {
+ t.Fatalf("expected Parser:ResetCpn component missing: %v", expected)
+ }
+ if cpn["c3_reset_marker"] != "NEW_VER_DEFAULT" {
+ t.Fatalf("reset did not load the NEW version default: %v", kb.ParserConfig)
+ }
+}
+
+// T26/C3 regression: a version switch must STILL reset parser_config to the new
+// version DSL defaults when the client echoes the previous (edited) parser_config
+// back. The settings form keeps the user's manual edit (e.g. chunk size 757) until
+// the save, so the request carries the old parser_config. The C3 reset must take
+// precedence over the echoed value (design A3 整体重置).
+func TestUpdateDataset_VersionChangeWithEchoedParserConfigResets(t *testing.T) {
+ db := setupDatasetUpdateTestDB(t)
+ pushServiceDB(t, db)
+
+ canvas1 := "0123456789abcdef0123456789abcdef"
+ verOld := "version0000000000000000000000aa"
+ verNew := "version0000000000000000000000bb"
+ seedDataflowCanvas(t, db, canvas1)
+ seedCanvasVersionDSL(t, db, canvas1, verOld, dslWithResetMarker("OLD_VER_DEFAULT"), 0)
+ seedCanvasVersionDSL(t, db, canvas1, verNew, dslWithResetMarker("NEW_VER_DEFAULT"), 1000)
+ seedBoundKB(t, db, "kb-c3-echo", canvas1, verOld)
+
+ // The form still holds the user's manual edit (e.g. chunk size 757) as a real
+ // component param when the version is switched. Use the version DSL's own
+ // component so the override is recognized and survives BuildParserConfig.
+ echoed := entity.JSONMap{"Parser:ResetCpn": map[string]any{"c3_reset_marker": "ECHOED_757"}}
+ if err := db.Model(&entity.Knowledgebase{}).Where("id = ?", "kb-c3-echo").
+ Update("parser_config", echoed).Error; err != nil {
+ t.Fatalf("seed parser_config: %v", err)
+ }
+
+ ctx := t.Context()
+ parseType := 2
+ _, code, err := testDatasetUpdateService(t).UpdateDataset(ctx, "kb-c3-echo", "tenant-1", service.UpdateDatasetRequest{
+ PipelineID: &canvas1,
+ PipelineVersionID: &verNew,
+ ParseType: &parseType,
+ // Echoed (edited) parser_config — must be discarded on version switch.
+ ParserConfig: echoed,
+ })
+ if err != nil || code != common.CodeSuccess {
+ t.Fatalf("UpdateDataset err=%v code=%d", err, code)
+ }
+
+ var kb entity.Knowledgebase
+ if err := db.Where("id = ?", "kb-c3-echo").Take(&kb).Error; err != nil {
+ t.Fatalf("load kb: %v", err)
+ }
+ if kb.PipelineVersionID == nil || *kb.PipelineVersionID != verNew {
+ t.Fatalf("PipelineVersionID = %v, want re-pinned %s", kb.PipelineVersionID, verNew)
+ }
+ // The echoed component override must NOT survive the version switch.
+ cpn, ok := kb.ParserConfig["Parser:ResetCpn"].(map[string]any)
+ if !ok {
+ t.Fatalf("Parser:ResetCpn missing after switch: %v", kb.ParserConfig)
+ }
+ if cpn["c3_reset_marker"] == "ECHOED_757" {
+ t.Fatalf("parser_config still holds echoed value; C3 reset did not take precedence: %v", kb.ParserConfig)
+ }
+ resolved, derr := service.ResolveComponentParamsDefaults(ctx, string(entity.ParserTypeNaive), &canvas1, &verNew)
+ if derr != nil {
+ t.Fatalf("resolve new-version defaults: %v", derr)
+ }
+ expected := service.ApplyComponentScopedParserConfig(resolved, "")
+ if !reflect.DeepEqual(kb.ParserConfig, expected) {
+ t.Fatalf("parser_config = %v, want new-version default %v", kb.ParserConfig, expected)
+ }
+ if cpn["c3_reset_marker"] != "NEW_VER_DEFAULT" {
+ t.Fatalf("reset did not load the NEW version default: %v", kb.ParserConfig)
+ }
+}
+
+// T26 corner: re-submitting the SAME pinned version must NOT reset parser_config
+// (C3 reset fires only on an actual version change, design section 5 + T26).
+func TestUpdateDataset_SameVersionKeepsParserConfig(t *testing.T) {
+ db := setupDatasetUpdateTestDB(t)
+ pushServiceDB(t, db)
+
+ canvas1 := "0123456789abcdef0123456789abcdef"
+ verOld := "version0000000000000000000000aa"
+ verNew := "version0000000000000000000000bb"
+ seedDataflowCanvas(t, db, canvas1)
+ seedCanvasVersion(t, db, canvas1, verOld, 0)
+ seedCanvasVersion(t, db, canvas1, verNew, 1000)
+ seedBoundKB(t, db, "kb-c3-same", canvas1, verOld)
+
+ if err := db.Model(&entity.Knowledgebase{}).Where("id = ?", "kb-c3-same").
+ Update("parser_config", entity.JSONMap{"__c3_marker__": "OLD"}).Error; err != nil {
+ t.Fatalf("seed parser_config: %v", err)
+ }
+
+ ctx := t.Context()
+ parseType := 2
+ _, code, err := testDatasetUpdateService(t).UpdateDataset(ctx, "kb-c3-same", "tenant-1", service.UpdateDatasetRequest{
+ PipelineID: &canvas1,
+ PipelineVersionID: &verOld, // same version, no change
+ ParseType: &parseType,
+ })
+ if err != nil || code != common.CodeSuccess {
+ t.Fatalf("UpdateDataset err=%v code=%d", err, code)
+ }
+
+ var kb entity.Knowledgebase
+ if err := db.Where("id = ?", "kb-c3-same").Take(&kb).Error; err != nil {
+ t.Fatalf("load kb: %v", err)
+ }
+ if v, ok := kb.ParserConfig["__c3_marker__"]; !ok || v != "OLD" {
+ t.Fatalf("parser_config should be preserved when version unchanged: %v", kb.ParserConfig)
+ }
+}
diff --git a/internal/service/dataset/update.go b/internal/service/dataset/update.go
index 938a1c21f2..6309714553 100644
--- a/internal/service/dataset/update.go
+++ b/internal/service/dataset/update.go
@@ -169,7 +169,7 @@ func (d *DatasetService) UpdateDataset(ctx context.Context, datasetID, userID st
}
requestedAnyUpdate := len(simpleUpdates) > 0 || connectorsProvided || parserIDProvided ||
- pipelineID != nil || embdIDProvided || pagerankRequested || req.ParserConfig != nil || req.ParserConfigProvided
+ pipelineID != nil || embdIDProvided || pagerankRequested || req.ParserConfig != nil || req.ParserConfigProvided || req.PipelineVersionID != nil
if !requestedAnyUpdate {
return nil, common.CodeDataError, errors.New("no properties were modified")
}
@@ -283,6 +283,20 @@ func (d *DatasetService) UpdateDataset(ctx context.Context, datasetID, userID st
updates["tenant_embd_id"] = stringPtrIfNotEmpty(tenantEmbdID)
}
+ // Design §5 fallback chains (v5.1/v5.2): when the request omits a field,
+ // fall back to the persisted (locked) binding rather than resetting to
+ // latest/nil. This is what makes the sticky snapshot (B4), the pinned-DSL
+ // parser_config rebuild (B1), and single-field PATCH (B2) correct.
+ canvasCtx := pipelineID
+ if canvasCtx == nil {
+ canvasCtx = lockedKB.PipelineID
+ }
+ pipelineChanged := pipelineID != nil && (lockedKB.PipelineID == nil || *pipelineID != *lockedKB.PipelineID)
+ requestedVersion := req.PipelineVersionID
+ if requestedVersion == nil && !pipelineChanged {
+ requestedVersion = lockedKB.PipelineVersionID
+ }
+
if req.ParserConfig != nil && len(req.ParserConfig) > 0 {
// Resolve the effective mode/IDs once. sel is the request selection
// (nil when the whole selection block was omitted); current is the
@@ -295,7 +309,14 @@ func (d *DatasetService) UpdateDataset(ctx context.Context, datasetID, userID st
return resolveErr
}
isPipeline, effParserID, effPipelineID := eff.Effective()
- dslJSON, dslErr := service.LoadPipelineDSL(ctx, isPipeline, effParserID, effPipelineID)
+ // Thread the effective pipeline version (design §5): use the §5 fallback
+ // requestedVersion (explicit pin when supplied, else the persisted
+ // pinned version) so a parser_config-only PATCH (B1) rebuilds from the
+ // pinned DSL rather than the canvas latest. The binding block below
+ // re-resolves the same value (and surfaces any ownership error); a load
+ // failure here is best-effort for parser_config rebuild only.
+ effVersionID, _ := resolvePipelineVersionID(ctx, tx, effPipelineID, requestedVersion)
+ dslJSON, dslErr := service.LoadPipelineDSL(ctx, isPipeline, effParserID, effPipelineID, effVersionID)
if dslErr != nil {
common.Warn("failed to load pipeline DSL for building parser_config",
zap.String("parserID", effParserID), zap.Error(dslErr))
@@ -323,7 +344,7 @@ func (d *DatasetService) UpdateDataset(ctx context.Context, datasetID, userID st
}
if parserIDProvided && parserID != lockedKB.ParserID {
if _, ok := updates["parser_config"]; !ok {
- if resolved, cpErr := service.ResolveComponentParamsDefaults(ctx, parserID, nil); cpErr != nil {
+ if resolved, cpErr := service.ResolveComponentParamsDefaults(ctx, parserID, nil, nil); cpErr != nil {
common.Warn("failed to resolve component params defaults on parser_id switch",
zap.String("parserID", parserID), zap.Error(cpErr))
} else if resolved != nil {
@@ -337,17 +358,68 @@ func (d *DatasetService) UpdateDataset(ctx context.Context, datasetID, userID st
}
}
- pipelineChanged := pipelineID != nil && (lockedKB.PipelineID == nil || *pipelineID != *lockedKB.PipelineID)
- if _, ok := updates["parser_config"]; pipelineChanged && !ok {
+ // pipelineChanged already computed in the §5 prep block above.
+ // C3 (T26/V5): an explicit, non-empty version that differs from the
+ // currently pinned version is a version switch even when the pipeline
+ // canvas is unchanged. Such a switch must reset the component params to
+ // the new version defaults (below), not only a pipeline_id change.
+ versionChanged := false
+ if req.PipelineVersionID != nil && strings.TrimSpace(*req.PipelineVersionID) != "" {
+ if lockedKB.PipelineVersionID == nil || strings.TrimSpace(*req.PipelineVersionID) != strings.TrimSpace(*lockedKB.PipelineVersionID) {
+ versionChanged = true
+ }
+ }
+ // Design C5/G3: an empty pipeline_version_id in Pipeline mode is REJECTED
+ // (no longer silently cleared or auto-backfilled to the canvas latest).
+ // The Save fails with ErrPipelineVersionEmpty so the UI can show the red
+ // Missing badge and the "版本信息缺失" error. BuiltIn mode (no canvas
+ // bound) is exempt and may carry an empty version.
+ isEffPipeline := canvasCtx != nil && strings.TrimSpace(*canvasCtx) != ""
+ if req.PipelineVersionID != nil {
+ if strings.TrimSpace(*req.PipelineVersionID) != "" {
+ bound, perr := resolvePipelineVersionID(ctx, tx, canvasCtx, req.PipelineVersionID)
+ if perr != nil {
+ txCode = common.CodeBadRequest
+ return perr
+ }
+ updates["pipeline_version_id"] = bound
+ } else if isEffPipeline {
+ // Explicit empty version in Pipeline mode: reject (do not clear the
+ // pin). Only BuiltIn-mode explicit empties are allowed to clear.
+ txCode = common.CodeBadRequest
+ return service.ErrPipelineVersionEmpty
+ } else {
+ // BuiltIn mode explicit empty: clear the pin (no canvas to pin to).
+ updates["pipeline_version_id"] = nil
+ }
+ } else if pipelineChanged && pipelineID != nil && strings.TrimSpace(*pipelineID) != "" {
+ // Switching to a Pipeline canvas without an explicit version is a
+ // missing-version Save (design C5/G3): reject rather than silently
+ // locking the new canvas's latest version.
+ txCode = common.CodeBadRequest
+ return service.ErrPipelineVersionEmpty
+ }
+ // C3 / A3 整体重置: BOTH a pipeline (canvas) switch and a version switch
+ // force a full parser_config reset to the new DSL defaults, discarding any
+ // echoed/submitted parser_config. When the version or pipeline is switched
+ // the settings form may still hold the previous value (e.g. a manually
+ // edited chunk size), so the reset must take precedence over the submitted
+ // config rather than merging it in.
+ if pipelineChanged || versionChanged {
cfgParserID := lockedKB.ParserID
if parserIDProvided {
cfgParserID = parserID
}
- if cpDefaults, cpErr := service.ResolveComponentParamsDefaults(ctx, cfgParserID, pipelineID); cpErr != nil {
- common.Warn("failed to resolve component params defaults on pipeline change",
+ effVersionID, _ := resolvePipelineVersionID(ctx, tx, canvasCtx, requestedVersion)
+ cpDefaults, cpErr := service.ResolveComponentParamsDefaults(ctx, cfgParserID, canvasCtx, effVersionID)
+ if cpErr != nil {
+ common.Warn("failed to resolve component params defaults on pipeline/version change",
zap.String("parserID", cfgParserID), zap.Error(cpErr))
- } else if cpDefaults != nil {
- updates["parser_config"] = preserveDatasetParserConfigState(cpDefaults, lockedKB.ParserConfig, req.ParserConfig)
+ }
+ // Full reset: replace parser_config with the new DSL defaults. The
+ // previous (echoed) value is intentionally dropped (design A3 整体重置).
+ if cpErr == nil {
+ updates["parser_config"] = cpDefaults
}
}
@@ -423,7 +495,7 @@ func (d *DatasetService) UpdateDataset(ctx context.Context, datasetID, userID st
}
}
- data := datasetToMap(updatedKB)
+ data := datasetToMap(ctx, updatedKB)
data["connectors"] = datasetConnectorsOrEmpty(linkedConnectors)
return data, common.CodeSuccess, nil
}
diff --git a/internal/service/dataset/update_test.go b/internal/service/dataset/update_test.go
index 978211d274..7305f872f6 100644
--- a/internal/service/dataset/update_test.go
+++ b/internal/service/dataset/update_test.go
@@ -295,7 +295,7 @@ func TestUpdateDataset_ParseTypePipelineRejectsParserID(t *testing.T) {
}
}
-func TestUpdateDataset_PipelineSwitchPreservesSubmittedParserConfig(t *testing.T) {
+func TestUpdateDataset_PipelineSwitchResetsParserConfigToDefaults(t *testing.T) {
db := setupDatasetUpdateTestDB(t)
pushServiceDB(t, db)
insertDatasetUpdateKB(t, "kb-1", "tenant-1", "Original")
@@ -318,11 +318,16 @@ func TestUpdateDataset_PipelineSwitchPreservesSubmittedParserConfig(t *testing.T
t.Fatalf("marshal canvas DSL: %v", err)
}
seedDatasetUpdateCanvas(t, pipelineID, "tenant-1", dslJSON)
+ // C5/G3: a Pipeline-mode switch now requires an explicit version (the empty
+ // version is no longer auto-backfilled). Seed one and pass it.
+ verID := "version0000000000000000000000cc"
+ seedCanvasVersion(t, db, pipelineID, verID, 0)
ctx := withDatasetTestContext(t.Context(), "tenant-1", "tenant-1")
_, code, err := testDatasetUpdateService(t).UpdateDataset(ctx, "kb-1", "tenant-1", service.UpdateDatasetRequest{
- PipelineID: &pipelineID,
- ParseType: &parseType,
+ PipelineID: &pipelineID,
+ ParseType: &parseType,
+ PipelineVersionID: &verID,
ParserConfig: map[string]interface{}{
"Parser:CustomP": map[string]interface{}{
"pdf": map[string]interface{}{"remove_toc": true},
@@ -340,6 +345,10 @@ func TestUpdateDataset_PipelineSwitchPreservesSubmittedParserConfig(t *testing.T
if err != nil {
t.Fatalf("get updated kb: %v", err)
}
+ // C3 / A3 整体重置: a pipeline (canvas) switch forces a FULL reset of
+ // parser_config to the new canvas DSL defaults, discarding the submitted
+ // config (design section 5 + A3). The submitted remove_toc=true must NOT
+ // survive; the persisted value must be the new canvas DSL default (false).
parserParams, ok := persisted.ParserConfig["Parser:CustomP"].(map[string]interface{})
if !ok {
t.Fatalf("expected Parser:CustomP in parser_config, got %#v", persisted.ParserConfig)
@@ -348,8 +357,8 @@ func TestUpdateDataset_PipelineSwitchPreservesSubmittedParserConfig(t *testing.T
if !ok {
t.Fatalf("expected pdf parser config, got %#v", parserParams)
}
- if removeTOC, ok := pdfParams["remove_toc"].(bool); !ok || !removeTOC {
- t.Fatalf("remove_toc = %#v, want true", pdfParams["remove_toc"])
+ if removeTOC, ok := pdfParams["remove_toc"].(bool); !ok || removeTOC {
+ t.Fatalf("remove_toc = %#v, want false (submitted value discarded on pipeline switch reset)", pdfParams["remove_toc"])
}
}
@@ -1044,6 +1053,7 @@ func migrateDatasetUpdateTestTables(t *testing.T, db *gorm.DB) {
&entity.TenantModelInstance{},
&entity.TenantModel{},
&entity.UserCanvas{},
+ &entity.UserCanvasVersion{},
); err != nil {
t.Fatalf("failed to migrate dataset update tables: %v", err)
}
diff --git a/internal/service/dataset/utils.go b/internal/service/dataset/utils.go
index 7459d99ee7..db68054cea 100644
--- a/internal/service/dataset/utils.go
+++ b/internal/service/dataset/utils.go
@@ -10,12 +10,77 @@ import (
"strings"
"time"
+ "ragflow/internal/dao"
"ragflow/internal/entity"
modelModule "ragflow/internal/entity/models"
"ragflow/internal/service"
)
-func datasetListItemToMap(kb *entity.KnowledgebaseListItem) map[string]interface{} {
+// pipelineVersionOutdated reports whether a dataset pinned pipeline version is
+// still the latest of its canvas (design section 6.3 D1/D2/D3). It is purely
+// informational: a non-latest version remains fully usable. BuiltIn datasets or
+// datasets without a pinned version are never outdated.
+func pipelineVersionOutdated(ctx context.Context, pipelineID, versionID *string) bool {
+ if pipelineID == nil || strings.TrimSpace(*pipelineID) == "" || versionID == nil {
+ return false
+ }
+ latest, err := dao.NewUserCanvasVersionDAO().GetLatest(ctx, dao.DB, strings.TrimSpace(*pipelineID))
+ if err != nil || latest == nil {
+ return false
+ }
+ return latest.ID != *versionID
+}
+
+// pipelineVersionOutdatedBatch is the list-endpoint variant of
+// pipelineVersionOutdated. It resolves the latest version id from a precomputed
+// {canvasID: latestVersionID} map (one query for the whole page) instead of a
+// GetLatest per row. A canvas absent from the map has no versions, so a pinned
+// version there is treated as not-outdated (matches the single-row fallback,
+// which returns false when GetLatest finds nothing).
+func pipelineVersionOutdatedBatch(latestByCanvas map[string]string, pipelineID, versionID *string) bool {
+ if pipelineID == nil || strings.TrimSpace(*pipelineID) == "" || versionID == nil {
+ return false
+ }
+ latestID, ok := latestByCanvas[strings.TrimSpace(*pipelineID)]
+ if !ok {
+ return false
+ }
+ return latestID != *versionID
+}
+
+// latestVersionIDsByCanvas resolves the latest version id per canvas for the
+// given knowledgebases in one query, so a dataset list page computes every
+// row's outdated flag without an N+1 of GetLatest calls. Returns nil on error
+// or when no dataset pins a pipeline, letting the mapper treat everything as
+// not-outdated.
+func latestVersionIDsByCanvas(ctx context.Context, kbs []*entity.KnowledgebaseListItem) map[string]string {
+ ids := make([]string, 0, len(kbs))
+ seen := make(map[string]struct{}, len(kbs))
+ for _, kb := range kbs {
+ if kb == nil || kb.PipelineID == nil {
+ continue
+ }
+ id := strings.TrimSpace(*kb.PipelineID)
+ if id == "" {
+ continue
+ }
+ if _, dup := seen[id]; dup {
+ continue
+ }
+ seen[id] = struct{}{}
+ ids = append(ids, id)
+ }
+ if len(ids) == 0 {
+ return nil
+ }
+ m, err := dao.NewUserCanvasVersionDAO().LatestIDsByCanvasIDs(ctx, dao.DB, ids)
+ if err != nil {
+ return nil
+ }
+ return m
+}
+
+func datasetListItemToMap(latestByCanvas map[string]string, kb *entity.KnowledgebaseListItem) map[string]interface{} {
// avatar/language/description keys are always present (null when unset),
// matching Python's full-row dict response.
item := map[string]interface{}{
@@ -43,10 +108,19 @@ func datasetListItemToMap(kb *entity.KnowledgebaseListItem) map[string]interface
if kb.UpdateTime != nil {
item["update_time"] = *kb.UpdateTime
}
+ if kb.PipelineID != nil {
+ item["pipeline_id"] = *kb.PipelineID
+ }
+ if kb.PipelineVersionID != nil {
+ item["pipeline_version_id"] = *kb.PipelineVersionID
+ }
+ // Design section 6.3 (! indicator): true when a pinned version is no longer
+ // the latest of its canvas. Purely informational; never blocks parsing.
+ item["pipeline_version_outdated"] = pipelineVersionOutdatedBatch(latestByCanvas, kb.PipelineID, kb.PipelineVersionID)
return item
}
-func datasetToMap(kb *entity.Knowledgebase) map[string]interface{} {
+func datasetToMap(ctx context.Context, kb *entity.Knowledgebase) map[string]interface{} {
item := map[string]interface{}{
"id": kb.ID,
"tenant_id": kb.TenantID,
@@ -76,6 +150,12 @@ func datasetToMap(kb *entity.Knowledgebase) map[string]interface{} {
if kb.PipelineID != nil {
item["pipeline_id"] = *kb.PipelineID
}
+ if kb.PipelineVersionID != nil {
+ item["pipeline_version_id"] = *kb.PipelineVersionID
+ }
+ // Design section 6.3 (! indicator): true when a pinned version is no longer
+ // the latest of its canvas. Purely informational; never blocks parsing.
+ item["pipeline_version_outdated"] = pipelineVersionOutdated(ctx, kb.PipelineID, kb.PipelineVersionID)
if kb.GraphragTaskID != nil {
item["graphrag_task_id"] = *kb.GraphragTaskID
}
diff --git a/internal/service/dataset_types.go b/internal/service/dataset_types.go
index 3d5191f9e6..73af502cef 100644
--- a/internal/service/dataset_types.go
+++ b/internal/service/dataset_types.go
@@ -166,6 +166,10 @@ type CreateDatasetRequest struct {
Permission *string `json:"permission,omitempty"`
ParserID *string `json:"parser_id,omitempty"`
PipelineID *string `json:"pipeline_id,omitempty"`
+ // PipelineVersionID optionally pins a specific canvas version when
+ // ParseType is Pipeline. When empty the latest version is bound (design
+ // section 5 sticky snapshot). Ownership is validated against PipelineID.
+ PipelineVersionID *string `json:"pipeline_version_id,omitempty"`
// ParseType indicates pipeline selection mode: 1 = BuiltIn (parser_id),
// 2 = Pipeline (pipeline_id). nil means unspecified.
ParseType *int `json:"parse_type,omitempty"`
@@ -191,6 +195,10 @@ type UpdateDatasetRequest struct {
Pagerank *int64 `json:"pagerank,omitempty"`
ParserConfig map[string]interface{} `json:"parser_config,omitempty"`
PipelineID *string `json:"pipeline_id,omitempty"`
+ // PipelineVersionID optionally pins a specific canvas version when
+ // ParseType is Pipeline. When empty the latest version is bound (design
+ // section 5 sticky snapshot). Ownership is validated against PipelineID.
+ PipelineVersionID *string `json:"pipeline_version_id,omitempty"`
// ParseType indicates pipeline selection mode: 1 = BuiltIn (parser_id),
// 2 = Pipeline (pipeline_id). nil means unspecified.
ParseType *int `json:"parse_type,omitempty"`
diff --git a/internal/service/delete_version_test.go b/internal/service/delete_version_test.go
new file mode 100644
index 0000000000..d570c6878c
--- /dev/null
+++ b/internal/service/delete_version_test.go
@@ -0,0 +1,136 @@
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package service
+
+import (
+ "errors"
+ "testing"
+
+ "gorm.io/gorm"
+ "ragflow/internal/dao"
+ "ragflow/internal/entity"
+)
+
+// seedVersionedDataflowCanvas inserts a dataflow canvas owned by userID with a
+// single version row and a knowledgebase pinning that version. The canvas is
+// owned by the requesting user so the DeleteVersion permission gate passes.
+func seedVersionedDataflowCanvas(t *testing.T, db *gorm.DB, userID, canvasID, versionID string) {
+ t.Helper()
+ if err := db.AutoMigrate(&entity.UserCanvasVersion{}); err != nil {
+ t.Fatalf("migrate version table: %v", err)
+ }
+ canvas := &entity.UserCanvas{
+ ID: canvasID,
+ UserID: userID,
+ CanvasCategory: "dataflow_canvas",
+ Permission: "me",
+ DSL: entity.JSONMap{"graph": "legacy"},
+ }
+ if err := db.Create(canvas).Error; err != nil {
+ t.Fatalf("seed canvas: %v", err)
+ }
+ ver := &entity.UserCanvasVersion{
+ ID: versionID,
+ UserCanvasID: canvasID,
+ DSL: entity.JSONMap{"graph": "versioned"},
+ }
+ if err := db.Create(ver).Error; err != nil {
+ t.Fatalf("seed version: %v", err)
+ }
+ kb := &entity.Knowledgebase{
+ ID: "kb-" + canvasID,
+ TenantID: "tenant-1",
+ Name: "kb-" + canvasID,
+ EmbdID: "BAAI/bge-large-zh-v1.5@Builtin",
+ CreatedBy: userID,
+ Permission: string(entity.TenantPermissionMe),
+ ParserID: string(entity.ParserTypeNaive),
+ ParserConfig: entity.JSONMap{},
+ Status: sptr(string(entity.StatusValid)),
+ PipelineID: &canvasID,
+ PipelineVersionID: &versionID,
+ }
+ if err := db.Create(kb).Error; err != nil {
+ t.Fatalf("seed kb: %v", err)
+ }
+}
+
+// T9: DeleteVersion reference scan. When a version is referenced by a binding,
+// deletion is still allowed (design A4); the referencing binding enters the
+// Missing state (design section 6.2) because the version row is gone.
+func TestDeleteVersion_ReferencedVersionStillDeleted(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+
+ userID := "user-1"
+ canvasID := "0123456789abcdef0123456789abcdef"
+ versionID := "version0000000000000000000000aa"
+ seedVersionedDataflowCanvas(t, db, userID, canvasID, versionID)
+
+ svc := NewAgentService()
+ if err := svc.DeleteVersion(t.Context(), userID, canvasID, versionID); err != nil {
+ t.Fatalf("DeleteVersion referenced version: %v", err)
+ }
+
+ // The version row must actually be removed.
+ if _, err := dao.NewUserCanvasVersionDAO().GetByID(t.Context(), dao.DB, versionID); !errors.Is(err, dao.ErrUserCanvasVersionNotFound) {
+ t.Fatalf("expected version row removed, got err=%v", err)
+ }
+
+ // The referencing binding now resolves to Missing (design section 6.2).
+ if _, err := loadCanvasDSLJSON(t.Context(), canvasID, &versionID); !errors.Is(err, ErrPipelineVersionMissing) {
+ t.Fatalf("expected Missing after referenced version delete, got err=%v", err)
+ }
+}
+
+// T9b: DeleteVersion with no references deletes normally.
+func TestDeleteVersion_UnreferencedVersionDeleted(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+
+ userID := "user-1"
+ canvasID := "0123456789abcdef0123456789abcdef"
+ versionID := "version0000000000000000000000bb"
+ // Seed canvas + version without any KB pinning it.
+ if err := db.AutoMigrate(&entity.UserCanvasVersion{}); err != nil {
+ t.Fatalf("migrate version table: %v", err)
+ }
+ canvas := &entity.UserCanvas{
+ ID: canvasID,
+ UserID: userID,
+ CanvasCategory: "dataflow_canvas",
+ Permission: "me",
+ DSL: entity.JSONMap{"graph": "legacy"},
+ }
+ if err := db.Create(canvas).Error; err != nil {
+ t.Fatalf("seed canvas: %v", err)
+ }
+ ver := &entity.UserCanvasVersion{
+ ID: versionID,
+ UserCanvasID: canvasID,
+ DSL: entity.JSONMap{"graph": "versioned"},
+ }
+ if err := db.Create(ver).Error; err != nil {
+ t.Fatalf("seed version: %v", err)
+ }
+
+ svc := NewAgentService()
+ if err := svc.DeleteVersion(t.Context(), userID, canvasID, versionID); err != nil {
+ t.Fatalf("DeleteVersion unreferenced version: %v", err)
+ }
+ if _, err := dao.NewUserCanvasVersionDAO().GetByID(t.Context(), dao.DB, versionID); !errors.Is(err, dao.ErrUserCanvasVersionNotFound) {
+ t.Fatalf("expected version row removed, got err=%v", err)
+ }
+}
diff --git a/internal/service/document/document.go b/internal/service/document/document.go
index d2847cde0b..61361adfc5 100644
--- a/internal/service/document/document.go
+++ b/internal/service/document/document.go
@@ -80,28 +80,30 @@ type UpdateDocumentRequest struct {
// DocumentResponse document response
type DocumentResponse struct {
- ID string `json:"id"`
- Name *string `json:"name,omitempty"`
- KbID string `json:"kb_id"`
- ParserID string `json:"parser_id"`
- PipelineID *string `json:"pipeline_id,omitempty"`
- Type string `json:"type"`
- SourceType string `json:"source_type"`
- CreatedBy string `json:"created_by"`
- Location *string `json:"location,omitempty"`
- Size int64 `json:"size"`
- TokenNum int64 `json:"token_num"`
- ChunkNum int64 `json:"chunk_num"`
- Progress float64 `json:"progress"`
- ProgressMsg *string `json:"progress_msg,omitempty"`
- LatestIngestionEvent *service.IngestionEventItem `json:"latest_ingestion_event,omitempty"`
- ProcessBeginAt *time.Time `json:"process_begin_at,omitempty"`
- ProcessDuration float64 `json:"process_duration"`
- Suffix string `json:"suffix"`
- IngestionStatus string `json:"ingestion_status"`
- Status *string `json:"status,omitempty"`
- CreatedAt string `json:"created_at"`
- UpdatedAt string `json:"updated_at"`
+ ID string `json:"id"`
+ Name *string `json:"name,omitempty"`
+ KbID string `json:"kb_id"`
+ ParserID string `json:"parser_id"`
+ PipelineID *string `json:"pipeline_id,omitempty"`
+ PipelineVersionID *string `json:"pipeline_version_id,omitempty"`
+ PipelineVersionOutdated bool `json:"pipeline_version_outdated"`
+ Type string `json:"type"`
+ SourceType string `json:"source_type"`
+ CreatedBy string `json:"created_by"`
+ Location *string `json:"location,omitempty"`
+ Size int64 `json:"size"`
+ TokenNum int64 `json:"token_num"`
+ ChunkNum int64 `json:"chunk_num"`
+ Progress float64 `json:"progress"`
+ ProgressMsg *string `json:"progress_msg,omitempty"`
+ LatestIngestionEvent *service.IngestionEventItem `json:"latest_ingestion_event,omitempty"`
+ ProcessBeginAt *time.Time `json:"process_begin_at,omitempty"`
+ ProcessDuration float64 `json:"process_duration"`
+ Suffix string `json:"suffix"`
+ IngestionStatus string `json:"ingestion_status"`
+ Status *string `json:"status,omitempty"`
+ CreatedAt string `json:"created_at"`
+ UpdatedAt string `json:"updated_at"`
}
type ThumbnailResponse struct {
@@ -131,6 +133,9 @@ type UpdateDatasetDocumentRequest struct {
Progress *float64 `json:"progress"`
ParserConfig map[string]any `json:"parser_config"`
MetaFields map[string]any `json:"meta_fields"`
+ // PipelineVersionID pins the document to a specific dataflow canvas version
+ // (design section 5/C2). Empty/omitted means the latest version is used.
+ PipelineVersionID *string `json:"pipeline_version_id,omitempty"`
// ParseType indicates pipeline selection mode: 1 = BuiltIn (parser_id),
// 2 = Pipeline (pipeline_id). nil means unspecified.
ParseType *int `json:"parse_type,omitempty"`
@@ -142,6 +147,7 @@ type UpdateDatasetDocumentResponse struct {
DatasetID string `json:"dataset_id"`
ParserID string `json:"parser_id"`
PipelineID *string `json:"pipeline_id,omitempty"`
+ PipelineVersionID *string `json:"pipeline_version_id,omitempty"`
ParserConfig map[string]interface{} `json:"parser_config"`
SourceType string `json:"source_type"`
Type string `json:"type"`
diff --git a/internal/service/document/document_dataset_update.go b/internal/service/document/document_dataset_update.go
index 2e59553522..7557e81cbb 100644
--- a/internal/service/document/document_dataset_update.go
+++ b/internal/service/document/document_dataset_update.go
@@ -20,6 +20,8 @@ import (
permissionresponse "ragflow/internal/permission/response"
"ragflow/internal/tokenizer"
"ragflow/internal/utility"
+
+ "go.uber.org/zap"
)
func (s *DocumentService) BatchUpdateDocumentStatus(ctx context.Context, userID, datasetID, status string, documentIDs []string) (map[string]interface{}, common.ErrorCode, error) {
@@ -156,12 +158,10 @@ func (s *DocumentService) UpdateDatasetDocument(ctx context.Context, userID, dat
}
return nil, common.CodeServerError, err
}
- if code, err := s.validateDatasetDocumentUpdate(ctx, doc, req, present); err != nil {
+ if code, err := s.validateDatasetDocumentUpdate(ctx, datasetID, documentID, userID, doc, req, present); err != nil {
return nil, code, err
}
- // Normalize chunk_method into the same selection used to clean and save
- // parser_config. An omitted selection keeps the document's own template.
parseType, parserID := req.ParseType, req.ParserID
hasSelection := parseType != nil ||
(parserID != nil && strings.TrimSpace(*parserID) != "") ||
@@ -190,6 +190,58 @@ func (s *DocumentService) UpdateDatasetDocument(ctx context.Context, userID, dat
selectionChanged = !previousOK || !targetOK || previous.ParserID != target.ParserID
}
hasConfig := present["parser_config"] && req.ParserConfig != nil
+
+ effectiveVersionID := doc.PipelineVersionID
+ repointVersion := false
+ if isPipeline && effPipelineID != nil && strings.TrimSpace(*effPipelineID) != "" && present["pipeline_version_id"] {
+ canvasID := strings.TrimSpace(*effPipelineID)
+ if req.PipelineVersionID != nil && strings.TrimSpace(*req.PipelineVersionID) != "" {
+ requested := strings.TrimSpace(*req.PipelineVersionID)
+ v, verr := dao.NewUserCanvasVersionDAO().GetByID(ctx, dao.DB, requested)
+ if verr != nil {
+ if errors.Is(verr, dao.ErrUserCanvasVersionNotFound) {
+ return nil, common.CodeDataError, fmt.Errorf("pipeline version %s not found: %w", requested, service.ErrPipelineVersionMissing)
+ }
+ return nil, common.CodeServerError, fmt.Errorf("load pipeline version %s: %w", requested, verr)
+ }
+ if v.UserCanvasID != canvasID {
+ return nil, common.CodeDataError, fmt.Errorf("pipeline version %s does not belong to canvas %s: %w", requested, canvasID, service.ErrPipelineVersionMissing)
+ }
+ effectiveVersionID = &requested
+ } else {
+ if isPipeline && effPipelineID != nil && strings.TrimSpace(*effPipelineID) != "" {
+ return nil, common.CodeBadRequest, service.ErrPipelineVersionEmpty
+ }
+ effectiveVersionID = nil
+ }
+ repointVersion = true
+ }
+
+ if !present["pipeline_version_id"] && effPipelineID != nil && strings.TrimSpace(*effPipelineID) != "" {
+ // C5/G3: a canvas-to-canvas switch without supplying a version is a
+ // missing-version Save and is rejected, so the document cannot silently
+ // track the new canvas latest. A builtin-to-canvas switch is allowed: it
+ // tracks the new canvas latest, and any broken-DSL error surfaces below.
+ docOnCanvas := doc.PipelineID != nil && strings.TrimSpace(*doc.PipelineID) != ""
+ pipelineChanged := doc.PipelineID == nil || strings.TrimSpace(*doc.PipelineID) != strings.TrimSpace(*effPipelineID)
+ if docOnCanvas && pipelineChanged {
+ return nil, common.CodeBadRequest, service.ErrPipelineVersionEmpty
+ }
+ }
+
+ versionChanged := false
+ if repointVersion {
+ oldV := ""
+ if doc.PipelineVersionID != nil {
+ oldV = strings.TrimSpace(*doc.PipelineVersionID)
+ }
+ newV := ""
+ if effectiveVersionID != nil {
+ newV = strings.TrimSpace(*effectiveVersionID)
+ }
+ versionChanged = newV != oldV
+ }
+
if (sel != nil || present["parser_config"]) && isPipeline && effPipelineID != nil && strings.TrimSpace(*effPipelineID) != "" {
accessErr := permission.NewDatabaseChecker(dao.DB).CheckDependency(
ctx,
@@ -207,8 +259,7 @@ func (s *DocumentService) UpdateDatasetDocument(ctx context.Context, userID, dat
parserUpdates := map[string]interface{}{}
if sel != nil || hasConfig {
- // Validate the target before any document, file, or metadata writes.
- dslJSON, err := service.LoadPipelineDSL(ctx, isPipeline, effParserID, effPipelineID)
+ dslJSON, err := service.LoadPipelineDSL(ctx, isPipeline, effParserID, effPipelineID, effectiveVersionID)
if err != nil {
return nil, common.CodeDataError, err
}
@@ -220,7 +271,9 @@ func (s *DocumentService) UpdateDatasetDocument(ctx context.Context, userID, dat
if err != nil {
return nil, common.CodeDataError, fmt.Errorf("invalid pipeline DSL: %w", err)
}
- if doc.Name != nil {
+ // File-family compatibility is only declared by builtin parser DSLs. Canvas
+ // pipelines do not declare supported file families, so skip the check there.
+ if !isPipeline && doc.Name != nil {
family := componentpkg.ParserFileFamily(utility.GetFileExtension(*doc.Name))
if family != "" {
if declared, found := configDeclaredFamily(cleaned, family); found && !declared {
@@ -229,8 +282,6 @@ func (s *DocumentService) UpdateDatasetDocument(ctx context.Context, userID, dat
}
}
if selectionChanged || hasConfig {
- // Inherited runtime delimiters are not an explicit override when
- // this request changes parent_child.
parentChildOverrides := maps.Clone(rawConfig)
for componentID, raw := range req.ParserConfig {
if requested, ok := raw.(map[string]any); ok {
@@ -246,6 +297,38 @@ func (s *DocumentService) UpdateDatasetDocument(ctx context.Context, userID, dat
}
}
+ // C3 / A3 整体重置: a pipeline (canvas) switch OR a version switch forces a
+ // full parser_config reset to the new DSL defaults, discarding any
+ // echoed/submitted parser_config. This mirrors the dataset-layer behavior so
+ // the two layers stay consistent (design A3 整体重置): a change to
+ // pipelineID or versionID must reset parser config to the DSL defaults. The
+ // reset overrides the first block's merge, so a stale form value (e.g. a
+ // manually edited chunk size) or a config submitted alongside the switch is
+ // dropped, exactly as the reset-on-switch contract requires.
+ //
+ // pipelineChanged tracks a genuine canvas change (incl. builtin→canvas);
+ // versionChanged tracks a pinned-version change. Builtin→builtin switches are
+ // not pipelineID changes and stay outside this reset (they are handled by the
+ // first block as a normal selection rebuild).
+ pipelineChanged := isPipeline && req.PipelineID != nil &&
+ (doc.PipelineID == nil || strings.TrimSpace(*req.PipelineID) != strings.TrimSpace(*doc.PipelineID))
+ if pipelineChanged || versionChanged {
+ cpDefaults, cpErr := service.ResolveComponentParamsDefaults(ctx, effParserID, effPipelineID, effectiveVersionID)
+ if cpErr != nil {
+ common.Warn("document pipeline/version switch: failed to resolve component params defaults, keeping prior parser_config",
+ zap.String("parserID", effParserID), zap.Error(cpErr))
+ } else {
+ llmID, _, llmErr := service.NewTenantService().GetDefaultModelRefsForUser(ctx, userID, kb.TenantID, entity.ModelTypeChat)
+ if llmErr != nil {
+ common.Warn("document pipeline/version switch: failed to resolve default chat model, falling back to no llm binding",
+ zap.String("tenant_id", kb.TenantID), zap.Error(llmErr))
+ llmID = ""
+ }
+ cleaned := service.ApplyComponentScopedParserConfig(cpDefaults, llmID)
+ parserUpdates["parser_config"] = cleaned
+ }
+ }
+
if sel != nil {
if isPipeline {
parserUpdates["pipeline_id"] = *effPipelineID
@@ -254,6 +337,15 @@ func (s *DocumentService) UpdateDatasetDocument(ctx context.Context, userID, dat
parserUpdates["pipeline_id"] = ""
}
}
+
+ if repointVersion {
+ var colValue interface{}
+ if effectiveVersionID != nil {
+ colValue = *effectiveVersionID
+ }
+ parserUpdates["pipeline_version_id"] = colValue
+ }
+
if present["meta_fields"] {
if err = s.replaceDocumentMetadata(ctx, documentID, req.MetaFields); err != nil {
return nil, common.CodeDataError, err
@@ -264,7 +356,6 @@ func (s *DocumentService) UpdateDatasetDocument(ctx context.Context, userID, dat
return nil, common.CodeDataError, err
}
}
- // Save selection and config together; parsed content changes only on reparse.
if len(parserUpdates) > 0 {
if err = s.documentDAO.UpdateByID(ctx, dao.DB, doc.ID, parserUpdates); err != nil {
return nil, common.CodeDataError, err
@@ -324,15 +415,11 @@ func (s *DocumentService) validateDocumentModifiable(ctx context.Context, doc *e
}
}
-func (s *DocumentService) validateDatasetDocumentUpdate(ctx context.Context, doc *entity.Document, req *UpdateDatasetDocumentRequest, present map[string]bool) (common.ErrorCode, error) {
+func (s *DocumentService) validateDatasetDocumentUpdate(ctx context.Context, datasetID, documentID, userID string, doc *entity.Document, req *UpdateDatasetDocumentRequest, present map[string]bool) (common.ErrorCode, error) {
if req == nil {
return common.CodeDataError, errors.New("invalid request payload")
}
- // Reject any configuration edit while the document is parsing or scheduled.
- // This guard is field-agnostic: every editable field (name, parser_config,
- // chunk_method, pipeline_id, enabled, meta_fields) is blocked so the
- // in-flight parser never reads a config that changed underneath it.
if len(present) > 0 {
if code, err := s.validateDocumentModifiable(ctx, doc); err != nil {
return code, err
@@ -372,8 +459,12 @@ func (s *DocumentService) validateDatasetDocumentUpdate(ctx context.Context, doc
}
}
+ if present["parse_type"] || present["parser_id"] || present["pipeline_id"] {
+ if _, err := service.FromRequest(req.ParseType, req.ParserID, req.PipelineID); err != nil {
+ return common.CodeDataError, err
+ }
+ }
if present["name"] {
- // An explicit null name is a type error, not an unset field.
if req.Name == nil {
return common.CodeDataError, errors.New("Field: <name> - Message: <Input should be a valid string> - Value: <None>")
}
@@ -388,7 +479,6 @@ func (s *DocumentService) validateDatasetDocumentUpdate(ctx context.Context, doc
}
}
if present["parser_config"] && req.ParserConfig != nil {
- // Reject invalid page ranges before any names or metadata are persisted.
if err := pipelinepkg.NormalizeParserConfigPages(req.ParserConfig); err != nil {
return common.CodeDataError, err
}
@@ -396,7 +486,6 @@ func (s *DocumentService) validateDatasetDocumentUpdate(ctx context.Context, doc
return common.CodeSuccess, nil
}
-
func requestField[T any](value *T, present bool) *T {
if !present {
return nil
@@ -433,6 +522,14 @@ func (s *DocumentService) validateDocumentName(ctx context.Context, doc *entity.
return common.CodeSuccess, nil
}
+func isPresentationFile(name *string) bool {
+ if name == nil {
+ return false
+ }
+ ext := strings.ToLower(filepath.Ext(*name))
+ return ext == ".ppt" || ext == ".pptx" || ext == ".pages" || ext == ".dps" || ext == ".dpt"
+}
+
func validateMetaFields(meta map[string]any) error {
if meta == nil {
return nil
@@ -499,6 +596,24 @@ func (s *DocumentService) updateDocumentNameOnly(ctx context.Context, doc *entit
)
}
+func (s *DocumentService) updateDocumentParserConfig(ctx context.Context, documentID string, config map[string]any) error {
+ if len(config) == 0 {
+ return nil
+ }
+
+ doc, err := s.documentDAO.GetByID(ctx, dao.DB, documentID)
+ if err != nil {
+ return fmt.Errorf("document(%s) not found", documentID)
+ }
+
+ merged := common.DeepMergeMaps(doc.ParserConfig, config)
+ pipelinepkg.ApplyParentChildChunkerConfig(merged, config)
+
+ return s.documentDAO.UpdateByID(ctx, dao.DB, documentID, map[string]interface{}{
+ "parser_config": entity.JSONMap(merged),
+ })
+}
+
func (s *DocumentService) toUpdateDatasetDocumentResponse(ctx context.Context, doc *entity.Document, metaFields map[string]interface{}) (*UpdateDatasetDocumentResponse, error) {
if metaFields == nil {
metaFields = map[string]interface{}{}
@@ -526,6 +641,7 @@ func (s *DocumentService) toUpdateDatasetDocumentResponse(ctx context.Context, d
DatasetID: doc.KbID,
ParserID: doc.ParserID,
PipelineID: doc.PipelineID,
+ PipelineVersionID: doc.PipelineVersionID,
ParserConfig: doc.ParserConfig,
SourceType: doc.SourceType,
Type: doc.Type,
@@ -552,6 +668,13 @@ func (s *DocumentService) toUpdateDatasetDocumentResponse(ctx context.Context, d
}, nil
}
+// validDocumentChunkMethods mirrors Python's UpdateDocumentReq chunk_method set.
+var validDocumentChunkMethods = map[string]bool{
+ "naive": true, "manual": true, "qa": true, "table": true, "paper": true,
+ "book": true, "laws": true, "presentation": true, "picture": true,
+ "one": true, "knowledge_graph": true, "email": true, "tag": true,
+}
+
// pythonFloatRepr formats a float the way Python's str()/repr() does:
// integral floats keep a trailing ".0".
func pythonFloatRepr(v float64) string {
diff --git a/internal/service/document/document_list.go b/internal/service/document/document_list.go
index 7f4b719bfd..79ab143731 100644
--- a/internal/service/document/document_list.go
+++ b/internal/service/document/document_list.go
@@ -13,6 +13,78 @@ import (
"ragflow/internal/service"
)
+// documentPipelineVersionOutdated reports whether a document pinned pipeline version
+// is still the latest of its canvas (design section 6.3). Informational only;
+// a non-latest version remains usable. Returns false with no pinned pipeline.
+func documentPipelineVersionOutdated(ctx context.Context, pipelineID, versionID *string) bool {
+ if pipelineID == nil || strings.TrimSpace(*pipelineID) == "" || versionID == nil {
+ return false
+ }
+ latest, err := dao.NewUserCanvasVersionDAO().GetLatest(ctx, dao.DB, strings.TrimSpace(*pipelineID))
+ if err != nil || latest == nil {
+ return false
+ }
+ return latest.ID != *versionID
+}
+
+// documentPipelineVersionOutdatedBatch is the list-endpoint variant of
+// documentPipelineVersionOutdated: it resolves the latest version id from a
+// precomputed {canvasID: latestVersionID} map (one query for the whole page)
+// instead of a GetLatest per row. A canvas absent from the map (no versions)
+// is treated as not-outdated.
+func documentPipelineVersionOutdatedBatch(latestByCanvas map[string]string, pipelineID, versionID *string) bool {
+ if pipelineID == nil || strings.TrimSpace(*pipelineID) == "" || versionID == nil {
+ return false
+ }
+ latestID, ok := latestByCanvas[strings.TrimSpace(*pipelineID)]
+ if !ok {
+ return false
+ }
+ return latestID != *versionID
+}
+
+// documentPipelineVersionOutdatedWith picks the batch resolver when a precomputed
+// map is supplied (list endpoints) and falls back to the per-document GetLatest
+// otherwise (single-document responses).
+func documentPipelineVersionOutdatedWith(ctx context.Context, latestByCanvas map[string]string, pipelineID, versionID *string) bool {
+ if latestByCanvas != nil {
+ return documentPipelineVersionOutdatedBatch(latestByCanvas, pipelineID, versionID)
+ }
+ return documentPipelineVersionOutdated(ctx, pipelineID, versionID)
+}
+
+// latestVersionIDsByCanvasDocs resolves the latest version id per canvas for the
+// given documents in one query, so a document list page computes every row's
+// outdated flag without an N+1 of GetLatest calls. Returns nil when no document
+// pins a pipeline (or on error), letting callers fall back to per-document
+// resolution.
+func latestVersionIDsByCanvasDocs(ctx context.Context, docs []*entity.Document) map[string]string {
+ ids := make([]string, 0, len(docs))
+ seen := make(map[string]struct{}, len(docs))
+ for _, doc := range docs {
+ if doc == nil || doc.PipelineID == nil {
+ continue
+ }
+ id := strings.TrimSpace(*doc.PipelineID)
+ if id == "" {
+ continue
+ }
+ if _, dup := seen[id]; dup {
+ continue
+ }
+ seen[id] = struct{}{}
+ ids = append(ids, id)
+ }
+ if len(ids) == 0 {
+ return nil
+ }
+ m, err := dao.NewUserCanvasVersionDAO().LatestIDsByCanvasIDs(ctx, dao.DB, ids)
+ if err != nil {
+ return nil
+ }
+ return m
+}
+
// escapeSQLLikePattern escapes the SQL LIKE wildcards ('%', '_') and
// the escape character itself ('!') so a literal user-supplied
// filename can be safely interpolated into a `LIKE ? ESCAPE '!'`
@@ -52,6 +124,7 @@ func (s *DocumentService) ListDocuments(ctx context.Context, page, pageSize int)
latestEventsByDocument = make(map[string]*service.IngestionEventItem)
}
+ latestVersionByCanvas := latestVersionIDsByCanvasDocs(ctx, documents)
responses := make([]*DocumentResponse, len(documents))
for i, doc := range documents {
var task *entity.IngestionTask
@@ -60,7 +133,7 @@ func (s *DocumentService) ListDocuments(ctx context.Context, page, pageSize int)
task = taskMap[doc.ID]
latestEvent = latestEventsByDocument[doc.ID]
}
- responses[i] = s.toResponseWithTask(doc, task, latestEvent)
+ responses[i] = s.toResponseWithTask(ctx, doc, task, latestEvent, latestVersionByCanvas)
}
return responses, total, nil
@@ -212,6 +285,7 @@ func (s *DocumentService) GetDocumentsByAuthorID(ctx context.Context, authorID,
latestEventsByDocument = make(map[string]*service.IngestionEventItem)
}
+ latestVersionByCanvas := latestVersionIDsByCanvasDocs(ctx, documents)
responses := make([]*DocumentResponse, len(documents))
for i, doc := range documents {
var task *entity.IngestionTask
@@ -220,7 +294,7 @@ func (s *DocumentService) GetDocumentsByAuthorID(ctx context.Context, authorID,
task = taskMap[doc.ID]
latestEvent = latestEventsByDocument[doc.ID]
}
- responses[i] = s.toResponseWithTask(doc, task, latestEvent)
+ responses[i] = s.toResponseWithTask(ctx, doc, task, latestEvent, latestVersionByCanvas)
}
return responses, total, nil
@@ -229,7 +303,7 @@ func (s *DocumentService) GetDocumentsByAuthorID(ctx context.Context, authorID,
// toResponse convert model.Document to DocumentResponse
func (s *DocumentService) toResponse(ctx context.Context, doc *entity.Document) (*DocumentResponse, error) {
if s.ingestionTaskDAO == nil || doc == nil || doc.ID == "" {
- return s.toResponseWithTask(doc, nil, nil), nil
+ return s.toResponseWithTask(ctx, doc, nil, nil, nil), nil
}
task, err := s.ingestionTaskDAO.GetByDocumentID(ctx, dao.DB, doc.ID)
if err != nil {
@@ -240,7 +314,7 @@ func (s *DocumentService) toResponse(ctx context.Context, doc *entity.Document)
common.Warn(fmt.Sprintf("get latest ingestion event for document %s: %v", doc.ID, err))
latestEventsByDocument = make(map[string]*service.IngestionEventItem)
}
- return s.toResponseWithTask(doc, task, latestEventsByDocument[doc.ID]), nil
+ return s.toResponseWithTask(ctx, doc, task, latestEventsByDocument[doc.ID], nil), nil
}
func (s *DocumentService) latestIngestionEventsByDocument(ctx context.Context, tasksByDocument map[string]*entity.IngestionTask) (map[string]*service.IngestionEventItem, error) {
@@ -294,7 +368,7 @@ func (s *DocumentService) LatestIngestionEventsByPipelineLogIDs(ctx context.Cont
return items, nil
}
-func (s *DocumentService) toResponseWithTask(doc *entity.Document, task *entity.IngestionTask, latestEvent *service.IngestionEventItem) *DocumentResponse {
+func (s *DocumentService) toResponseWithTask(ctx context.Context, doc *entity.Document, task *entity.IngestionTask, latestEvent *service.IngestionEventItem, latestByCanvas map[string]string) *DocumentResponse {
if doc == nil {
return nil
}
@@ -324,27 +398,31 @@ func (s *DocumentService) toResponseWithTask(doc *entity.Document, task *entity.
ingestionStatus = task.Status
}
return &DocumentResponse{
- ID: doc.ID,
- Name: doc.Name,
- KbID: doc.KbID,
- ParserID: doc.ParserID,
- PipelineID: doc.PipelineID,
- Type: doc.Type,
- SourceType: doc.SourceType,
- CreatedBy: doc.CreatedBy,
- Location: doc.Location,
- Size: doc.Size,
- TokenNum: doc.TokenNum,
- ChunkNum: doc.ChunkNum,
- Progress: doc.Progress,
- ProgressMsg: doc.ProgressMsg,
- LatestIngestionEvent: latestEvent,
- ProcessBeginAt: doc.ProcessBeginAt,
- ProcessDuration: doc.ProcessDuration,
- Suffix: doc.Suffix,
- IngestionStatus: ingestionStatus,
- Status: doc.Status,
- CreatedAt: createdAt,
- UpdatedAt: updatedAt,
+ ID: doc.ID,
+ Name: doc.Name,
+ KbID: doc.KbID,
+ ParserID: doc.ParserID,
+ PipelineID: doc.PipelineID,
+ PipelineVersionID: doc.PipelineVersionID,
+ // Design section 6.3 (! indicator): true when the pinned version is no
+ // longer the latest of its canvas. Informational only; never blocks parse.
+ PipelineVersionOutdated: documentPipelineVersionOutdatedWith(ctx, latestByCanvas, doc.PipelineID, doc.PipelineVersionID),
+ Type: doc.Type,
+ SourceType: doc.SourceType,
+ CreatedBy: doc.CreatedBy,
+ Location: doc.Location,
+ Size: doc.Size,
+ TokenNum: doc.TokenNum,
+ ChunkNum: doc.ChunkNum,
+ Progress: doc.Progress,
+ ProgressMsg: doc.ProgressMsg,
+ LatestIngestionEvent: latestEvent,
+ ProcessBeginAt: doc.ProcessBeginAt,
+ ProcessDuration: doc.ProcessDuration,
+ Suffix: doc.Suffix,
+ IngestionStatus: ingestionStatus,
+ Status: doc.Status,
+ CreatedAt: createdAt,
+ UpdatedAt: updatedAt,
}
}
diff --git a/internal/service/document/document_parser_selection.go b/internal/service/document/document_parser_selection.go
index ee4786f543..22cc347112 100644
--- a/internal/service/document/document_parser_selection.go
+++ b/internal/service/document/document_parser_selection.go
@@ -84,7 +84,7 @@ func configDeclaredFamily(config entity.JSONMap, family string) (declared, found
// dataset row storing a historical parser_id is judged by the template it
// actually runs.
func templateDeclaredFamily(ctx context.Context, parserID, family string) (declared, found bool) {
- dslJSON, err := service.LoadPipelineDSL(ctx, false, parserID, nil)
+ dslJSON, err := service.LoadPipelineDSL(ctx, false, parserID, nil, nil)
if err != nil {
return false, false
}
@@ -181,7 +181,7 @@ func resolveDocumentParser(ctx context.Context, kb *entity.Knowledgebase, filena
// the caller keeps the dataset's selection instead of writing a half-switched
// row.
func rebuildParserConfig(ctx context.Context, kb *entity.Knowledgebase, target, filename string, base entity.JSONMap) (entity.JSONMap, bool) {
- dslJSON, err := service.LoadPipelineDSL(ctx, false, target, nil)
+ dslJSON, err := service.LoadPipelineDSL(ctx, false, target, nil, nil)
if err != nil {
common.Warn("document: target pipeline DSL unavailable, keeping dataset selection",
zap.String("parser_id", target), zap.String("filename", filename), zap.Error(err))
diff --git a/internal/service/document/document_test.go b/internal/service/document/document_test.go
index 033ea930bf..e72a56222a 100644
--- a/internal/service/document/document_test.go
+++ b/internal/service/document/document_test.go
@@ -695,7 +695,7 @@ func ensureTestTenantOwner(t *testing.T, userID, tenantID string) {
func insertTestCanvas(t *testing.T, canvasID, ownerID string) {
t.Helper()
tenantID := "tenant-1"
- dslJSON, err := service.LoadPipelineDSL(t.Context(), false, "general", nil)
+ dslJSON, err := service.LoadPipelineDSL(t.Context(), false, "general", nil, nil)
if err != nil {
t.Fatal(err)
}
@@ -3198,11 +3198,14 @@ func TestUpdateDatasetDocumentParserConfigPreservesParseResults(t *testing.T) {
present map[string]bool
wantParser string
wantPipeline string
+ // reset marks a pipeline switch, which (by design A3 整体重置) must reset
+ // parser_config to the canvas DSL defaults, discarding the submitted config.
+ reset bool
}{
{name: "config only", wantParser: "naive"},
{name: "same builtin", request: UpdateDatasetDocumentRequest{ParseType: &builtin, ParserID: sptr("naive")}, present: map[string]bool{"parse_type": true, "parser_id": true}, wantParser: "naive"},
{name: "different builtin", request: UpdateDatasetDocumentRequest{ParseType: &builtin, ParserID: sptr("manual")}, present: map[string]bool{"parse_type": true, "parser_id": true}, wantParser: "manual"},
- {name: "pipeline", request: UpdateDatasetDocumentRequest{ParseType: &pipeline, PipelineID: &pipelineID}, present: map[string]bool{"parse_type": true, "pipeline_id": true}, wantParser: "naive", wantPipeline: pipelineID},
+ {name: "pipeline", request: UpdateDatasetDocumentRequest{ParseType: &pipeline, PipelineID: &pipelineID, PipelineVersionID: sptr("v-doc-pipe-0001")}, present: map[string]bool{"parse_type": true, "pipeline_id": true, "pipeline_version_id": true}, wantParser: "naive", wantPipeline: pipelineID, reset: true},
{name: "chunk method", request: UpdateDatasetDocumentRequest{ChunkMethod: sptr("manual")}, present: map[string]bool{"chunk_method": true}, wantParser: "manual"},
}
for _, tc := range cases {
@@ -3212,6 +3215,7 @@ func TestUpdateDatasetDocumentParserConfigPreservesParseResults(t *testing.T) {
insertTestKB(t, "kb-1", "tenant-1", 1, 10, 5)
insertNamedTestDoc(t, "doc-1", "kb-1", "doc.docx", 10, 5)
insertTestCanvas(t, pipelineID, "user-1")
+ seedDocVersion(t, db, pipelineID, "v-doc-pipe-0001", 0)
insertTestIngestionTaskWithStatus(t, "task-1", "user-1", "doc-1", "kb-1", common.COMPLETED)
if err := db.Model(&entity.Document{}).Where("id = ?", "doc-1").Update("process_duration", 42).Error; err != nil {
t.Fatalf("prepare document: %v", err)
@@ -3247,13 +3251,28 @@ func TestUpdateDatasetDocumentParserConfigPreservesParseResults(t *testing.T) {
if doc.TokenNum != 10 || doc.ChunkNum != 5 || doc.Progress != 0.75 || doc.ProcessDuration != 42 {
t.Fatalf("persisted parse results changed: %+v", doc)
}
- extractor, ok := doc.ParserConfig["Extractor:AutoExtractDefault"].(map[string]interface{})
- if !ok {
- t.Fatalf("extractor config not saved: %#v", doc.ParserConfig)
- }
- keywords, ok := extractor["keywords"].(map[string]interface{})
- if !ok || keywords["top_n"] != float64(5) {
- t.Fatalf("parser config not saved: %#v", doc.ParserConfig)
+ if tc.reset {
+ // A pipeline switch resets parser_config to the canvas DSL
+ // defaults (design A3 整体重置). The submitted
+ // Extractor keywords.top_n=5 must be discarded and replaced by the
+ // DSL default (0), proving the reset took effect.
+ extractor, ok := doc.ParserConfig["Extractor:AutoExtractDefault"].(map[string]interface{})
+ if !ok {
+ t.Fatalf("canvas DSL default parser_config missing Extractor after pipeline switch: %#v", doc.ParserConfig)
+ }
+ keywords, ok := extractor["keywords"].(map[string]interface{})
+ if !ok || keywords["top_n"] != float64(0) {
+ t.Fatalf("submitted keywords.top_n should be reset to DSL default (0), got %#v (config=%#v)", keywords["top_n"], doc.ParserConfig)
+ }
+ } else {
+ extractor, ok := doc.ParserConfig["Extractor:AutoExtractDefault"].(map[string]interface{})
+ if !ok {
+ t.Fatalf("extractor config not saved: %#v", doc.ParserConfig)
+ }
+ keywords, ok := extractor["keywords"].(map[string]interface{})
+ if !ok || keywords["top_n"] != float64(5) {
+ t.Fatalf("parser config not saved: %#v", doc.ParserConfig)
+ }
}
kb, err := dao.NewKnowledgebaseDAO().GetByID(ctx, db, "kb-1")
if err != nil {
@@ -4136,13 +4155,15 @@ func TestUpdateDatasetDocumentPipelineIDTakesPrecedenceOverParserID(t *testing.T
pipelineID := "1234567890abcdef1234567890abcdef"
insertTestCanvas(t, pipelineID, "user-1")
+ seedDocVersion(t, db, pipelineID, "v-pre-0001", 0)
parseType := 2
svc := testDocumentService(t)
ctx := documentTestContext(t.Context())
resp, code, err := svc.UpdateDatasetDocument(ctx, "user-1", "kb-1", "doc-1", &UpdateDatasetDocumentRequest{
- PipelineID: &pipelineID,
- ParseType: &parseType,
- }, map[string]bool{"pipeline_id": true, "parse_type": true})
+ PipelineID: &pipelineID,
+ PipelineVersionID: sptr("v-pre-0001"),
+ ParseType: &parseType,
+ }, map[string]bool{"pipeline_id": true, "pipeline_version_id": true, "parse_type": true})
if err != nil {
t.Fatalf("UpdateDatasetDocument failed: code=%v err=%v", code, err)
}
@@ -4210,10 +4231,12 @@ func TestUpdateDatasetDocumentParseTypePipeline(t *testing.T) {
insertTestCanvas(t, pipelineID, "user-1")
svc := testDocumentService(t)
ctx := documentTestContext(t.Context())
+ seedDocVersion(t, db, pipelineID, "v-ptp-0001", 0)
resp, code, err := svc.UpdateDatasetDocument(ctx, "user-1", "kb-1", "doc-1", &UpdateDatasetDocumentRequest{
- ParseType: &parseType,
- PipelineID: &pipelineID,
- }, map[string]bool{"parser_id": false, "pipeline_id": true, "parse_type": true})
+ ParseType: &parseType,
+ PipelineID: &pipelineID,
+ PipelineVersionID: sptr("v-ptp-0001"),
+ }, map[string]bool{"parser_id": false, "pipeline_id": true, "pipeline_version_id": true, "parse_type": true})
if err != nil {
t.Fatalf("UpdateDatasetDocument failed: code=%v err=%v", code, err)
}
@@ -4261,12 +4284,16 @@ func TestUpdateDatasetDocumentParentChildConfigReachesCanvasChunker(t *testing.T
pushServiceDB(t, db)
insertTestKB(t, "kb-1", "tenant-1", 1, 10, 5)
insertNamedTestDoc(t, "doc-1", "kb-1", "doc.txt", 10, 5)
- parseType := 2
pipelineID := "1234567890abcdef1234567890abcdef"
insertTestCanvas(t, pipelineID, "user-1")
+ seedDocVersion(t, db, pipelineID, "v-pcc-0001", 0)
+ // Bind the document to the pipeline first, so the update below is a plain
+ // parser_config patch on an already-canvas document. A pipeline switch must
+ // reset parser_config to the canvas DSL defaults (design A3 整体重置), so the
+ // submitted parent_child would be dropped on a switch; this test verifies the
+ // config reaches the canvas chunker when no switch occurs.
+ bindDocCanvas(t, db, "kb-1", "doc-1", pipelineID, "v-pcc-0001")
resp, code, err := testDocumentService(t).UpdateDatasetDocument(documentTestContext(t.Context()), "user-1", "kb-1", "doc-1", &UpdateDatasetDocumentRequest{
- ParseType: &parseType,
- PipelineID: &pipelineID,
ParserConfig: map[string]any{
"GeneralChunker:SixApplesFall": map[string]any{
"parent_child": map[string]any{
@@ -4275,7 +4302,7 @@ func TestUpdateDatasetDocumentParentChildConfigReachesCanvasChunker(t *testing.T
},
},
},
- }, map[string]bool{"pipeline_id": true, "parse_type": true, "parser_config": true})
+ }, map[string]bool{"parser_config": true})
if err != nil || code != common.CodeSuccess {
t.Fatalf("UpdateDatasetDocument err=%v code=%d", err, code)
}
diff --git a/internal/service/document/document_upload.go b/internal/service/document/document_upload.go
index c4d87c8fe5..2eb781cb83 100644
--- a/internal/service/document/document_upload.go
+++ b/internal/service/document/document_upload.go
@@ -322,19 +322,20 @@ func (s *DocumentService) newDatasetDocument(kb *entity.Knowledgebase, tenantID,
parserID, pipelineID := parserSelectionColumns(selection)
loc := location
doc := &entity.Document{
- ID: docID,
- KbID: kb.ID,
- ParserID: parserID,
- PipelineID: pipelineID,
- ParserConfig: parserConfig,
- CreatedBy: tenantID,
- Type: filetype,
- SourceType: src,
- Name: &filename,
- Location: &loc,
- Size: size,
- Suffix: suffix,
- Status: &status,
+ ID: docID,
+ KbID: kb.ID,
+ ParserID: parserID,
+ PipelineID: pipelineID,
+ PipelineVersionID: kb.PipelineVersionID,
+ ParserConfig: parserConfig,
+ CreatedBy: tenantID,
+ Type: filetype,
+ SourceType: src,
+ Name: &filename,
+ Location: &loc,
+ Size: size,
+ Suffix: suffix,
+ Status: &status,
}
if blob != nil {
hash := contentHashHex(blob)
diff --git a/internal/service/document/document_version_pin_list_test.go b/internal/service/document/document_version_pin_list_test.go
new file mode 100644
index 0000000000..ddf8dc91bd
--- /dev/null
+++ b/internal/service/document/document_version_pin_list_test.go
@@ -0,0 +1,108 @@
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package document
+
+import (
+ "testing"
+
+ "ragflow/internal/common"
+ "ragflow/internal/dao"
+ "ragflow/internal/entity"
+)
+
+// TestUpdateDatasetDocumentListReturnsPinnedVersion reproduces the file-level
+// bug: a document pinned to a specific canvas version must be reported as pinned
+// when the document list is read back, so the reopened change-parser dialog can
+// show the saved pin instead of re-adopting the latest version. If the list
+// projection drops pipeline_version_id (as DocumentListItem originally did), the
+// returned item's PipelineVersionID is nil and this fails.
+func TestUpdateDatasetDocumentListReturnsPinnedVersion(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ if err := db.AutoMigrate(&entity.UserCanvasVersion{}); err != nil {
+ t.Fatal(err)
+ }
+ insertTestKB(t, "kb-1", "tenant-1", 1, 10, 5)
+ insertNamedTestDoc(t, "doc-1", "kb-1", "doc.txt", 10, 5)
+
+ // The document list JOINs file2document/file, so seed those rows too.
+ if err := db.Create(&entity.File{
+ ID: "file-1", TenantID: "tenant-1", CreatedBy: "user-1",
+ Name: "doc.txt", Type: "doc", SourceType: "local",
+ }).Error; err != nil {
+ t.Fatal(err)
+ }
+ if err := db.Create(&entity.File2Document{
+ ID: "f2d-1", FileID: sptr("file-1"), DocumentID: sptr("doc-1"),
+ }).Error; err != nil {
+ t.Fatal(err)
+ }
+
+ canvasID := "1234567890abcdef1234567890abcdef"
+ insertTestCanvas(t, canvasID, "user-1")
+ if err := db.Model(&entity.UserCanvas{}).Where("id = ?", canvasID).
+ Update("canvas_category", "dataflow_canvas").Error; err != nil {
+ t.Fatal(err)
+ }
+
+ vt := int64(100)
+ if err := db.Create(&entity.UserCanvasVersion{
+ ID: "v-pinned",
+ UserCanvasID: canvasID,
+ DSL: entity.JSONMap{"components": map[string]any{
+ "Parser:Shared": map[string]any{"obj": map[string]any{
+ "component_name": "Parser",
+ "params": map[string]any{"source": "pinned", "k": "x"},
+ }},
+ }},
+ BaseModel: entity.BaseModel{CreateTime: &vt},
+ }).Error; err != nil {
+ t.Fatal(err)
+ }
+
+ if err := db.Model(&entity.Knowledgebase{}).Where("id = ?", "kb-1").
+ Updates(map[string]any{"parser_id": "", "pipeline_id": canvasID}).Error; err != nil {
+ t.Fatal(err)
+ }
+ if err := db.Model(&entity.Document{}).Where("id = ?", "doc-1").
+ Updates(map[string]any{"parser_id": "", "pipeline_id": canvasID}).Error; err != nil {
+ t.Fatal(err)
+ }
+
+ svc := testDocumentService(t)
+ pid := canvasID
+ pv := "v-pinned"
+ pt := 2
+ _, code, err := svc.UpdateDatasetDocument(t.Context(), "user-1", "kb-1", "doc-1", &UpdateDatasetDocumentRequest{
+ ParseType: &pt,
+ PipelineID: &pid,
+ PipelineVersionID: &pv,
+ }, map[string]bool{"pipeline_id": true, "pipeline_version_id": true, "parse_type": true})
+ if err != nil || code != common.CodeSuccess {
+ t.Fatalf("UpdateDatasetDocument err=%v code=%d", err, code)
+ }
+
+ opts := dao.DocumentListOptions{KbID: "kb-1", OrderBy: "create_time", Desc: true, Offset: 0, Limit: 10}
+ docs, _, lerr := svc.ListDocumentsByDatasetIDWithOptions(t.Context(), opts, 1, 10)
+ if lerr != nil {
+ t.Fatal(lerr)
+ }
+ if len(docs) == 0 {
+ t.Fatal("list returned no documents")
+ }
+ if docs[0].PipelineVersionID == nil || *docs[0].PipelineVersionID != "v-pinned" {
+ t.Fatalf("list did not return the pinned version; got %v (want v-pinned)", docs[0].PipelineVersionID)
+ }
+}
diff --git a/internal/service/document/document_version_pin_pipeline_change_test.go b/internal/service/document/document_version_pin_pipeline_change_test.go
new file mode 100644
index 0000000000..37d662951d
--- /dev/null
+++ b/internal/service/document/document_version_pin_pipeline_change_test.go
@@ -0,0 +1,63 @@
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package document
+
+import (
+ "errors"
+ "testing"
+
+ "ragflow/internal/common"
+ "ragflow/internal/service"
+)
+
+// TestUpdateDatasetDocument_PipelineChangeWithoutVersionRejected verifies the C5/G3
+// contract: switching a document to a different dataflow canvas WITHOUT supplying a
+// concrete pipeline_version_id is REJECTED (design section 3: empty version is no
+// longer silently backfilled to the canvas latest). The UI must surface the red
+// Missing badge and the "版本信息缺失" error instead.
+func TestUpdateDatasetDocument_PipelineChangeWithoutVersionRejected(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ insertTestKB(t, "kb-1", "tenant-1", 1, 10, 5)
+ insertNamedTestDoc(t, "doc-1", "kb-1", "doc.txt", 10, 5)
+
+ canvasA := "1234567890abcdef1234567890abcdef"
+ canvasB := "abcdefabcdefabcdefabcdefabcdefabcd"
+ seedDataflowCanvasCat(t, db, canvasA)
+ seedDataflowCanvasCat(t, db, canvasB)
+ seedDocVersion(t, db, canvasA, "v-a", 100)
+ seedDocVersion(t, db, canvasB, "v-b", 100)
+ bindDocCanvas(t, db, "kb-1", "doc-1", canvasA, "v-a")
+
+ // Switch to canvasB, omitting pipeline_version_id entirely.
+ parseType := 2 // Pipeline mode
+ _, code, err := testDocumentService(t).UpdateDatasetDocument(t.Context(), "user-1", "kb-1", "doc-1",
+ &UpdateDatasetDocumentRequest{ParseType: &parseType, PipelineID: sptr(canvasB)},
+ map[string]bool{"pipeline_id": true})
+ if err == nil || code == common.CodeSuccess {
+ t.Fatalf("expected rejection of pipeline switch without version, got code=%d err=%v", code, err)
+ }
+ if !errors.Is(err, service.ErrPipelineVersionEmpty) {
+ t.Fatalf("err = %v, want ErrPipelineVersionEmpty", err)
+ }
+ // The document must be left unchanged (pipeline_id and pin preserved).
+ got := loadDoc(t, db, "doc-1")
+ if got.PipelineID == nil || *got.PipelineID != canvasA {
+ t.Fatalf("pipeline_id = %v, want unchanged %s", got.PipelineID, canvasA)
+ }
+ if got.PipelineVersionID == nil || *got.PipelineVersionID != "v-a" {
+ t.Fatalf("PipelineVersionID = %v, want preserved v-a", got.PipelineVersionID)
+ }
+}
diff --git a/internal/service/document/document_version_pin_test.go b/internal/service/document/document_version_pin_test.go
new file mode 100644
index 0000000000..d5f49c2409
--- /dev/null
+++ b/internal/service/document/document_version_pin_test.go
@@ -0,0 +1,116 @@
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package document
+
+import (
+ "testing"
+
+ "ragflow/internal/common"
+ "ragflow/internal/entity"
+)
+
+// TestUpdateDatasetDocumentUsesPinnedPipelineVersionForParserConfig proves the
+// parser_config cleaning path honors the document's sticky pinned
+// pipeline_version_id (design section 5/B4) instead of silently loading the
+// latest version. The document is pinned to v-pinned, whose DSL exposes a
+// "source" param the request override does NOT touch, so the cleaned config's
+// "source" value reveals which version's DSL was actually loaded:
+// - fixed (pinned): source == "pinned"
+// - buggy loads latest: source == "latest"
+// - buggy fallback (error): source absent
+//
+// Only the fixed behavior satisfies the assertion, so this fails before the fix
+// and passes after (review finding: document_dataset_update.go ignored the
+// pinned version when reloading DSL).
+func TestUpdateDatasetDocumentUsesPinnedPipelineVersionForParserConfig(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ if err := db.AutoMigrate(&entity.UserCanvasVersion{}); err != nil {
+ t.Fatal(err)
+ }
+ insertTestKB(t, "kb-1", "tenant-1", 1, 10, 5)
+ insertNamedTestDoc(t, "doc-1", "kb-1", "doc.txt", 10, 5)
+
+ canvasID := "1234567890abcdef1234567890abcdef"
+ insertTestCanvas(t, canvasID, "user-1")
+ // The dataflow read path is only taken for dataflow_canvas; insertTestCanvas
+ // leaves the category at the agent default, so set it explicitly.
+ if err := db.Model(&entity.UserCanvas{}).Where("id = ?", canvasID).Update("canvas_category", "dataflow_canvas").Error; err != nil {
+ t.Fatal(err)
+ }
+
+ // Same component id, distinct "source" param per version. The request
+ // override only sets "k", so "source" is carried verbatim from the DSL.
+ pinnedDSL := entity.JSONMap{"components": map[string]any{
+ "Parser:Shared": map[string]any{"obj": map[string]any{
+ "component_name": "Parser",
+ "params": map[string]any{"source": "pinned", "k": "x"},
+ }},
+ }}
+ latestDSL := entity.JSONMap{"components": map[string]any{
+ "Parser:Shared": map[string]any{"obj": map[string]any{
+ "component_name": "Parser",
+ "params": map[string]any{"source": "latest", "k": "x"},
+ }},
+ }}
+ pinnedTime := int64(100)
+ latestTime := int64(200)
+ if err := db.Create(&entity.UserCanvasVersion{
+ ID: "v-pinned",
+ UserCanvasID: canvasID,
+ DSL: pinnedDSL,
+ BaseModel: entity.BaseModel{CreateTime: &pinnedTime},
+ }).Error; err != nil {
+ t.Fatal(err)
+ }
+ if err := db.Create(&entity.UserCanvasVersion{
+ ID: "v-latest",
+ UserCanvasID: canvasID,
+ DSL: latestDSL,
+ BaseModel: entity.BaseModel{CreateTime: &latestTime},
+ }).Error; err != nil {
+ t.Fatal(err)
+ }
+
+ // Bind KB + document to the canvas and the pinned (older) version.
+ if err := db.Model(&entity.Knowledgebase{}).Where("id = ?", "kb-1").
+ Updates(map[string]any{"parser_id": "", "pipeline_id": canvasID, "pipeline_version_id": "v-pinned"}).Error; err != nil {
+ t.Fatal(err)
+ }
+ if err := db.Model(&entity.Document{}).Where("id = ?", "doc-1").
+ Updates(map[string]any{"parser_id": "", "pipeline_id": canvasID, "pipeline_version_id": "v-pinned"}).Error; err != nil {
+ t.Fatal(err)
+ }
+
+ svc := testDocumentService(t)
+ _, code, err := svc.UpdateDatasetDocument(t.Context(), "user-1", "kb-1", "doc-1", &UpdateDatasetDocumentRequest{
+ ParserConfig: map[string]any{"Parser:Shared": map[string]any{"k": "override_val"}},
+ }, map[string]bool{"parser_config": true})
+ if err != nil || code != common.CodeSuccess {
+ t.Fatalf("UpdateDatasetDocument err=%v code=%d", err, code)
+ }
+
+ var got entity.Document
+ if err := db.Where("id = ?", "doc-1").First(&got).Error; err != nil {
+ t.Fatal(err)
+ }
+ comp, ok := got.ParserConfig["Parser:Shared"].(map[string]any)
+ if !ok {
+ t.Fatalf("cleaned parser_config missing Parser:Shared component; got: %#v", got.ParserConfig)
+ }
+ if comp["source"] != "pinned" {
+ t.Fatalf("parser_config cleaned from wrong version: source=%v, want pinned; full=%#v", comp["source"], got.ParserConfig)
+ }
+}
diff --git a/internal/service/document/document_version_pin_update_test.go b/internal/service/document/document_version_pin_update_test.go
new file mode 100644
index 0000000000..a5be68f11f
--- /dev/null
+++ b/internal/service/document/document_version_pin_update_test.go
@@ -0,0 +1,333 @@
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package document
+
+import (
+ "errors"
+ "testing"
+
+ "ragflow/internal/common"
+ "ragflow/internal/entity"
+ "ragflow/internal/service"
+
+ "gorm.io/gorm"
+)
+
+func seedDataflowCanvasCat(t *testing.T, db *gorm.DB, canvasID string) {
+ t.Helper()
+ insertTestCanvas(t, canvasID, "user-1")
+ if err := db.Model(&entity.UserCanvas{}).Where("id = ?", canvasID).
+ Update("canvas_category", "dataflow_canvas").Error; err != nil {
+ t.Fatal(err)
+ }
+}
+
+func seedDocVersion(t *testing.T, db *gorm.DB, canvasID, versionID string, createMs int64) {
+ t.Helper()
+ if err := db.AutoMigrate(&entity.UserCanvasVersion{}); err != nil {
+ t.Fatal(err)
+ }
+ ct := createMs
+ dsl := entity.JSONMap{"components": map[string]any{
+ "Parser:Shared": map[string]any{"obj": map[string]any{
+ "component_name": "Parser",
+ "params": map[string]any{"source": versionID, "k": "x"},
+ }},
+ }}
+ if err := db.Create(&entity.UserCanvasVersion{
+ ID: versionID,
+ UserCanvasID: canvasID,
+ DSL: dsl,
+ BaseModel: entity.BaseModel{CreateTime: &ct},
+ }).Error; err != nil {
+ t.Fatal(err)
+ }
+}
+
+func bindDocCanvas(t *testing.T, db *gorm.DB, kbID, docID, canvasID, versionID string) {
+ t.Helper()
+ upd := map[string]any{"parser_id": "", "pipeline_id": canvasID}
+ if versionID != "" {
+ upd["pipeline_version_id"] = versionID
+ }
+ if err := db.Model(&entity.Knowledgebase{}).Where("id = ?", kbID).Updates(upd).Error; err != nil {
+ t.Fatal(err)
+ }
+ if err := db.Model(&entity.Document{}).Where("id = ?", docID).Updates(upd).Error; err != nil {
+ t.Fatal(err)
+ }
+}
+
+func loadDoc(t *testing.T, db *gorm.DB, docID string) entity.Document {
+ t.Helper()
+ var got entity.Document
+ if err := db.Where("id = ?", docID).First(&got).Error; err != nil {
+ t.Fatalf("reload doc %s: %v", docID, err)
+ }
+ return got
+}
+
+func TestUpdateDatasetDocument_PersistsPinnedPipelineVersion(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ insertTestKB(t, "kb-1", "tenant-1", 1, 10, 5)
+ insertNamedTestDoc(t, "doc-1", "kb-1", "doc.txt", 10, 5)
+
+ canvasID := "1234567890abcdef1234567890abcdef"
+ seedDataflowCanvasCat(t, db, canvasID)
+ seedDocVersion(t, db, canvasID, "v-old", 100)
+ seedDocVersion(t, db, canvasID, "v-new", 200)
+ bindDocCanvas(t, db, "kb-1", "doc-1", canvasID, "v-old")
+
+ _, code, err := testDocumentService(t).UpdateDatasetDocument(t.Context(), "user-1", "kb-1", "doc-1",
+ &UpdateDatasetDocumentRequest{PipelineVersionID: sptr("v-new")},
+ map[string]bool{"pipeline_version_id": true})
+ if err != nil || code != common.CodeSuccess {
+ t.Fatalf("UpdateDatasetDocument err=%v code=%d", err, code)
+ }
+ got := loadDoc(t, db, "doc-1")
+ if got.PipelineVersionID == nil || *got.PipelineVersionID != "v-new" {
+ t.Fatalf("PipelineVersionID = %v, want v-new", got.PipelineVersionID)
+ }
+}
+
+func TestUpdateDatasetDocument_RejectsForeignPipelineVersion(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ insertTestKB(t, "kb-1", "tenant-1", 1, 10, 5)
+ insertNamedTestDoc(t, "doc-1", "kb-1", "doc.txt", 10, 5)
+
+ canvasA := "1234567890abcdef1234567890abcdef"
+ canvasB := "abcdefabcdefabcdefabcdefabcdefabcd"
+ seedDataflowCanvasCat(t, db, canvasA)
+ seedDataflowCanvasCat(t, db, canvasB)
+ seedDocVersion(t, db, canvasA, "v-a", 100)
+ seedDocVersion(t, db, canvasB, "v-foreign", 100)
+ bindDocCanvas(t, db, "kb-1", "doc-1", canvasA, "v-a")
+
+ _, code, err := testDocumentService(t).UpdateDatasetDocument(t.Context(), "user-1", "kb-1", "doc-1",
+ &UpdateDatasetDocumentRequest{PipelineVersionID: sptr("v-foreign")},
+ map[string]bool{"pipeline_version_id": true})
+ if err == nil {
+ t.Fatal("expected rejection of foreign pipeline version")
+ }
+ if code != common.CodeDataError {
+ t.Fatalf("code = %d, want CodeDataError", code)
+ }
+ if !errors.Is(err, service.ErrPipelineVersionMissing) {
+ t.Fatalf("err = %v, want ErrPipelineVersionMissing", err)
+ }
+ if got := loadDoc(t, db, "doc-1"); got.PipelineVersionID == nil || *got.PipelineVersionID != "v-a" {
+ t.Fatalf("PipelineVersionID changed on rejected save: %v", got.PipelineVersionID)
+ }
+}
+
+func TestUpdateDatasetDocument_RejectsMissingPipelineVersion(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ insertTestKB(t, "kb-1", "tenant-1", 1, 10, 5)
+ insertNamedTestDoc(t, "doc-1", "kb-1", "doc.txt", 10, 5)
+
+ canvasID := "1234567890abcdef1234567890abcdef"
+ seedDataflowCanvasCat(t, db, canvasID)
+ seedDocVersion(t, db, canvasID, "v-a", 100)
+ bindDocCanvas(t, db, "kb-1", "doc-1", canvasID, "v-a")
+
+ _, code, err := testDocumentService(t).UpdateDatasetDocument(t.Context(), "user-1", "kb-1", "doc-1",
+ &UpdateDatasetDocumentRequest{PipelineVersionID: sptr("does-not-exist")},
+ map[string]bool{"pipeline_version_id": true})
+ if err == nil || code != common.CodeDataError {
+ t.Fatalf("want CodeDataError, got code=%d err=%v", code, err)
+ }
+ if !errors.Is(err, service.ErrPipelineVersionMissing) {
+ t.Fatalf("err = %v, want ErrPipelineVersionMissing", err)
+ }
+}
+
+func TestUpdateDatasetDocument_PreservesPipelineVersionWhenAbsent(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ insertTestKB(t, "kb-1", "tenant-1", 1, 10, 5)
+ insertNamedTestDoc(t, "doc-1", "kb-1", "doc.txt", 10, 5)
+
+ canvasID := "1234567890abcdef1234567890abcdef"
+ seedDataflowCanvasCat(t, db, canvasID)
+ seedDocVersion(t, db, canvasID, "v-old", 100)
+ bindDocCanvas(t, db, "kb-1", "doc-1", canvasID, "v-old")
+
+ _, code, err := testDocumentService(t).UpdateDatasetDocument(t.Context(), "user-1", "kb-1", "doc-1",
+ &UpdateDatasetDocumentRequest{}, map[string]bool{})
+ if err != nil || code != common.CodeSuccess {
+ t.Fatalf("UpdateDatasetDocument err=%v code=%d", err, code)
+ }
+ if got := loadDoc(t, db, "doc-1"); got.PipelineVersionID == nil || *got.PipelineVersionID != "v-old" {
+ t.Fatalf("PipelineVersionID = %v, want preserved v-old", got.PipelineVersionID)
+ }
+}
+
+func TestUpdateDatasetDocument_EmptyPipelineVersionTracksLatest(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ insertTestKB(t, "kb-1", "tenant-1", 1, 10, 5)
+ insertNamedTestDoc(t, "doc-1", "kb-1", "doc.txt", 10, 5)
+
+ canvasID := "1234567890abcdef1234567890abcdef"
+ seedDataflowCanvasCat(t, db, canvasID)
+ seedDocVersion(t, db, canvasID, "v-old", 100)
+ bindDocCanvas(t, db, "kb-1", "doc-1", canvasID, "v-old")
+
+ // C5/G3: an explicit EMPTY version in Pipeline mode is REJECTED (design
+ // section 3: empty version is no longer auto-backfilled to latest). The pin
+ // must be preserved and the save must fail with ErrPipelineVersionEmpty.
+ _, code, err := testDocumentService(t).UpdateDatasetDocument(t.Context(), "user-1", "kb-1", "doc-1",
+ &UpdateDatasetDocumentRequest{PipelineVersionID: sptr("")},
+ map[string]bool{"pipeline_version_id": true})
+ if err == nil || code == common.CodeSuccess {
+ t.Fatalf("expected rejection of empty pipeline version, got code=%d err=%v", code, err)
+ }
+ if !errors.Is(err, service.ErrPipelineVersionEmpty) {
+ t.Fatalf("err = %v, want ErrPipelineVersionEmpty", err)
+ }
+ if got := loadDoc(t, db, "doc-1"); got.PipelineVersionID == nil || *got.PipelineVersionID != "v-old" {
+ t.Fatalf("pin must be preserved on rejected save, got %v", got.PipelineVersionID)
+ }
+}
+
+func TestUpdateDatasetDocument_BuiltinIgnoresPipelineVersion(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ insertTestKB(t, "kb-1", "tenant-1", 1, 10, 5)
+ insertNamedTestDoc(t, "doc-1", "kb-1", "doc.txt", 10, 5)
+
+ _, code, err := testDocumentService(t).UpdateDatasetDocument(t.Context(), "user-1", "kb-1", "doc-1",
+ &UpdateDatasetDocumentRequest{PipelineVersionID: sptr("v-whatever")},
+ map[string]bool{"pipeline_version_id": true})
+ if err != nil || code != common.CodeSuccess {
+ t.Fatalf("UpdateDatasetDocument err=%v code=%d", err, code)
+ }
+ if got := loadDoc(t, db, "doc-1"); got.PipelineVersionID != nil {
+ t.Fatalf("builtin document must not carry pipeline_version_id, got %v", *got.PipelineVersionID)
+ }
+}
+
+func TestUpdateDatasetDocument_CleansParserConfigWithNewVersion(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ insertTestKB(t, "kb-1", "tenant-1", 1, 10, 5)
+ insertNamedTestDoc(t, "doc-1", "kb-1", "doc.txt", 10, 5)
+
+ canvasID := "1234567890abcdef1234567890abcdef"
+ seedDataflowCanvasCat(t, db, canvasID)
+ seedDocVersion(t, db, canvasID, "v-old", 100)
+ seedDocVersion(t, db, canvasID, "v-new", 200)
+ bindDocCanvas(t, db, "kb-1", "doc-1", canvasID, "v-old")
+
+ _, code, err := testDocumentService(t).UpdateDatasetDocument(t.Context(), "user-1", "kb-1", "doc-1",
+ &UpdateDatasetDocumentRequest{
+ PipelineVersionID: sptr("v-new"),
+ ParserConfig: map[string]any{"Parser:Shared": map[string]any{"k": "override"}},
+ },
+ map[string]bool{"pipeline_version_id": true, "parser_config": true})
+ if err != nil || code != common.CodeSuccess {
+ t.Fatalf("UpdateDatasetDocument err=%v code=%d", err, code)
+ }
+ got := loadDoc(t, db, "doc-1")
+ if got.PipelineVersionID == nil || *got.PipelineVersionID != "v-new" {
+ t.Fatalf("PipelineVersionID = %v, want v-new", got.PipelineVersionID)
+ }
+ comp, ok := got.ParserConfig["Parser:Shared"].(map[string]any)
+ if !ok {
+ t.Fatalf("cleaned parser_config missing Parser:Shared: %#v", got.ParserConfig)
+ }
+ if comp["source"] != "v-new" {
+ t.Fatalf("parser_config cleaned from version %v, want v-new (new pin)", comp["source"])
+ }
+}
+
+// T26/C3 (document): switching the pinned version of a pipeline document WITHOUT
+// supplying parser_config resets the document's component params to the new
+// version default (design section 5 + T26/A3 整体重置). The previous config must
+// not be merged in.
+func TestUpdateDatasetDocument_VersionSwitchResetsParserConfigToNewDefault(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ insertTestKB(t, "kb-1", "tenant-1", 1, 10, 5)
+ insertNamedTestDoc(t, "doc-1", "kb-1", "doc.txt", 10, 5)
+
+ canvasID := "1234567890abcdef1234567890abcdef"
+ seedDataflowCanvasCat(t, db, canvasID)
+ seedDocVersion(t, db, canvasID, "v-old", 100)
+ seedDocVersion(t, db, canvasID, "v-new", 200)
+ bindDocCanvas(t, db, "kb-1", "doc-1", canvasID, "v-old")
+
+ // A distinctive parser_config that must NOT survive the version switch.
+ if err := db.Model(&entity.Document{}).Where("id = ?", "doc-1").
+ Update("parser_config", entity.JSONMap{"__c3_marker__": "OLD"}).Error; err != nil {
+ t.Fatalf("seed parser_config: %v", err)
+ }
+
+ _, code, err := testDocumentService(t).UpdateDatasetDocument(t.Context(), "user-1", "kb-1", "doc-1",
+ &UpdateDatasetDocumentRequest{PipelineVersionID: sptr("v-new")},
+ map[string]bool{"pipeline_version_id": true})
+ if err != nil || code != common.CodeSuccess {
+ t.Fatalf("UpdateDatasetDocument err=%v code=%d", err, code)
+ }
+ got := loadDoc(t, db, "doc-1")
+ if got.PipelineVersionID == nil || *got.PipelineVersionID != "v-new" {
+ t.Fatalf("PipelineVersionID = %v, want v-new", got.PipelineVersionID)
+ }
+ // C3 full reset: the pre-switch marker must be gone (not merged).
+ if v, ok := got.ParserConfig["__c3_marker__"]; ok && v == "OLD" {
+ t.Fatalf("parser_config still holds pre-switch marker; C3 reset did not run: %v", got.ParserConfig)
+ }
+ // The reset must load the NEW version's default (source=v-new), not v-old.
+ comp, ok := got.ParserConfig["Parser:Shared"].(map[string]any)
+ if !ok {
+ t.Fatalf("reset parser_config missing Parser:Shared: %#v", got.ParserConfig)
+ }
+ if comp["source"] != "v-new" {
+ t.Fatalf("parser_config reset to version %v, want v-new default", comp["source"])
+ }
+}
+
+// T26 corner (document): re-submitting the SAME pinned version must NOT reset the
+// document's parser_config (C3 fires only on an actual version change).
+func TestUpdateDatasetDocument_SameVersionKeepsParserConfig(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ insertTestKB(t, "kb-1", "tenant-1", 1, 10, 5)
+ insertNamedTestDoc(t, "doc-1", "kb-1", "doc.txt", 10, 5)
+
+ canvasID := "1234567890abcdef1234567890abcdef"
+ seedDataflowCanvasCat(t, db, canvasID)
+ seedDocVersion(t, db, canvasID, "v-old", 100)
+ bindDocCanvas(t, db, "kb-1", "doc-1", canvasID, "v-old")
+
+ if err := db.Model(&entity.Document{}).Where("id = ?", "doc-1").
+ Update("parser_config", entity.JSONMap{"__c3_marker__": "OLD"}).Error; err != nil {
+ t.Fatalf("seed parser_config: %v", err)
+ }
+
+ _, code, err := testDocumentService(t).UpdateDatasetDocument(t.Context(), "user-1", "kb-1", "doc-1",
+ &UpdateDatasetDocumentRequest{PipelineVersionID: sptr("v-old")},
+ map[string]bool{"pipeline_version_id": true})
+ if err != nil || code != common.CodeSuccess {
+ t.Fatalf("UpdateDatasetDocument err=%v code=%d", err, code)
+ }
+ got := loadDoc(t, db, "doc-1")
+ if v, ok := got.ParserConfig["__c3_marker__"]; !ok || v != "OLD" {
+ t.Fatalf("parser_config should be preserved when version unchanged: %v", got.ParserConfig)
+ }
+}
diff --git a/internal/service/document/file2document.go b/internal/service/document/file2document.go
index 0c8e6cc323..c08b1eb1dc 100644
--- a/internal/service/document/file2document.go
+++ b/internal/service/document/file2document.go
@@ -245,16 +245,17 @@ func (s *File2DocumentService) convertFiles(ctx context.Context, fileIDs, kbIDs
parserID, pipelineID := parserSelectionColumns(selection)
suffix := strings.TrimPrefix(filepath.Ext(docName), ".")
doc := &entity.Document{
- ID: common.GenerateUUID(),
- KbID: kb.ID,
- ParserID: parserID,
- PipelineID: pipelineID,
- ParserConfig: parserConfig,
- CreatedBy: userID,
- Type: file.Type,
- Name: &docName,
- Suffix: suffix,
- Size: file.Size,
+ ID: common.GenerateUUID(),
+ KbID: kb.ID,
+ ParserID: parserID,
+ PipelineID: pipelineID,
+ PipelineVersionID: kb.PipelineVersionID,
+ ParserConfig: parserConfig,
+ CreatedBy: userID,
+ Type: file.Type,
+ Name: &docName,
+ Suffix: suffix,
+ Size: file.Size,
}
if file.Location != nil {
doc.Location = file.Location
diff --git a/internal/service/document/pipeline_version_inherit_test.go b/internal/service/document/pipeline_version_inherit_test.go
new file mode 100644
index 0000000000..df6a8e3326
--- /dev/null
+++ b/internal/service/document/pipeline_version_inherit_test.go
@@ -0,0 +1,41 @@
+package document
+
+import (
+ "testing"
+
+ "ragflow/internal/entity"
+ "ragflow/internal/service"
+)
+
+// T8: a document uploaded into a dataflow knowledgebase inherits the KB's
+// pinned pipeline_version_id (sticky snapshot, design section 5/B4). The
+// document locks to the version the KB was bound to at upload time, so later
+// version publishes do not change already-ingested files.
+func TestNewDatasetDocument_InheritsPipelineVersionID(t *testing.T) {
+ pid := "canvas-1"
+ ver := "v1"
+ kb := &entity.Knowledgebase{
+ ID: "kb-1",
+ PipelineID: &pid,
+ PipelineVersionID: &ver,
+ }
+ sel := &service.ParserSelection{Mode: service.ParseModePipeline, PipelineID: pid}
+ doc := (&DocumentService{}).newDatasetDocument(kb, "tenant-1", "f.pdf", "loc", "pdf", sel, entity.JSONMap{}, "local", 10, nil)
+ if doc.PipelineID == nil || *doc.PipelineID != "canvas-1" {
+ t.Fatalf("PipelineID = %v, want canvas-1", doc.PipelineID)
+ }
+ if doc.PipelineVersionID == nil || *doc.PipelineVersionID != "v1" {
+ t.Fatalf("document did not inherit kb pipeline_version_id: %v", doc.PipelineVersionID)
+ }
+}
+
+// T8b: a built-in (non-pipeline) knowledgebase must not carry a
+// pipeline_version_id on its documents (design section 5, built-in unaffected).
+func TestNewDatasetDocument_BuiltinHasNoVersion(t *testing.T) {
+ kb := &entity.Knowledgebase{ID: "kb-2"}
+ sel := &service.ParserSelection{Mode: service.ParseModeBuiltIn, ParserID: "general"}
+ doc := (&DocumentService{}).newDatasetDocument(kb, "tenant-1", "f.pdf", "loc", "pdf", sel, entity.JSONMap{}, "local", 10, nil)
+ if doc.PipelineVersionID != nil {
+ t.Fatalf("built-in document must not carry pipeline_version_id: %v", doc.PipelineVersionID)
+ }
+}
diff --git a/internal/service/pipeline_params.go b/internal/service/pipeline_params.go
index 82b62e66dd..4558e34911 100644
--- a/internal/service/pipeline_params.go
+++ b/internal/service/pipeline_params.go
@@ -15,11 +15,29 @@ import (
"gorm.io/gorm"
)
-// loadCanvasDSLJSON returns the DSL JSON for a custom canvas pipeline. The
-// canvas's dsl column holds the same component-graph structure that built-in
-// templates use, so it can be validated by the same schema extractor. It is a
-// package-level function so both document and knowledge-base updates reuse it.
-func loadCanvasDSLJSON(ctx context.Context, canvasID string) ([]byte, error) {
+// ErrPipelineVersionMissing is the single multi-version Missing sentinel. It is
+// defined once in the dao package (dao.ErrPipelineVersionMissing) and re-exported
+// here so existing callers (e.g. dataset CRUD) keep a stable symbol while the
+// error identity matches across the service and task layers (review: merge the
+// duplicate service/task sentinels into one implementation).
+var ErrPipelineVersionMissing = dao.ErrPipelineVersionMissing
+
+// ErrPipelineVersionEmpty is re-exported from dao so callers (dataset/document
+// CRUD) keep a single stable symbol. It signals a Pipeline-mode Save with no
+// concrete pinned version (design C5/G3: empty version is rejected, not silently
+// backfilled to the canvas latest).
+var ErrPipelineVersionEmpty = dao.ErrPipelineVersionEmpty
+
+// loadCanvasDSLJSON returns the DSL JSON for a custom canvas pipeline.
+//
+// For dataflow canvases (canvas_category = dataflow_canvas) the read is versioned
+// per design §6.1: an explicit versionID resolves that exact version; otherwise
+// the latest version is used, and a canvas with no version rows surfaces
+// ErrPipelineVersionMissing (no fallback to the legacy draft column). Agent
+// canvases are out of the multi-version scope (design §1) and keep reading the
+// live draft column directly. It is a package-level function so both document
+// and knowledge-base updates reuse it.
+func loadCanvasDSLJSON(ctx context.Context, canvasID string, versionID *string) ([]byte, error) {
if strings.TrimSpace(canvasID) == "" {
return nil, fmt.Errorf("empty canvas id")
}
@@ -30,10 +48,28 @@ func loadCanvasDSLJSON(ctx context.Context, canvasID string) ([]byte, error) {
}
return nil, fmt.Errorf("load canvas %s: %w", canvasID, err)
}
- if len(canvas.DSL) == 0 {
- return nil, fmt.Errorf("canvas %s has no DSL", canvasID)
+ if canvas.CanvasCategory != "dataflow_canvas" {
+ // Agent canvases: out of scope for multi-version; read the live draft.
+ if len(canvas.DSL) == 0 {
+ return nil, fmt.Errorf("canvas %s has no DSL", canvasID)
+ }
+ return marshalCanvasDSL(canvasID, canvas.DSL)
+ }
+ // Dataflow canvases are versioned (design section 6.1). An explicit versionID
+ // pins that exact version; an empty versionID resolves the latest published
+ // version. A missing, mis-owned, or empty-DSL version surfaces
+ // ErrPipelineVersionMissing -- there is no legacy-draft fallback for dataflow.
+ // The resolution is delegated to dao.LoadCanvasVersionDSL so the service and
+ // task layers share one implementation (review: merge duplicate resolvers).
+ pin := ""
+ if versionID != nil {
+ pin = strings.TrimSpace(*versionID)
}
- raw, err := json.Marshal(canvas.DSL)
+ return dao.LoadCanvasVersionDSL(ctx, dao.DB, canvasID, pin)
+}
+
+func marshalCanvasDSL(canvasID string, dsl entity.JSONMap) ([]byte, error) {
+ raw, err := json.Marshal(dsl)
if err != nil {
return nil, fmt.Errorf("marshal canvas %s DSL: %w", canvasID, err)
}
@@ -42,10 +78,11 @@ func loadCanvasDSLJSON(ctx context.Context, canvasID string) ([]byte, error) {
// LoadPipelineDSL loads the DSL JSON for a pipeline identified by parserID
// (built-in) or pipelineID (custom canvas). When both are provided, isPipeline
-// selects which one to use.
-func LoadPipelineDSL(ctx context.Context, isPipeline bool, parserID string, pipelineID *string) ([]byte, error) {
+// selects which one to use. versionID selects a specific canvas version; when nil
+// the latest version (or legacy canvas dsl) is used.
+func LoadPipelineDSL(ctx context.Context, isPipeline bool, parserID string, pipelineID *string, versionID *string) ([]byte, error) {
if isPipeline {
- return loadCanvasDSLJSON(ctx, strings.TrimSpace(*pipelineID))
+ return loadCanvasDSLJSON(ctx, strings.TrimSpace(*pipelineID), versionID)
}
registry, err := pipelinepkg.DefaultRegistry()
if err != nil {
@@ -64,13 +101,13 @@ func LoadPipelineDSL(ctx context.Context, isPipeline bool, parserID string, pipe
// ResolveComponentParamsDefaults loads the DSL for the target pipeline and
// returns the component params defaults as an entity.JSONMap {cpnID: {param: value}}.
// For builtin templates the DSL is loaded from the embedded registry; for custom
-// canvas pipelines it is loaded from the canvas row in the database.
-func ResolveComponentParamsDefaults(ctx context.Context, parserID string, pipelineID *string) (entity.JSONMap, error) {
+// canvas pipelines it is loaded from the canvas version (or legacy canvas row).
+func ResolveComponentParamsDefaults(ctx context.Context, parserID string, pipelineID *string, versionID *string) (entity.JSONMap, error) {
isPipeline := pipelineID != nil && strings.TrimSpace(*pipelineID) != ""
var cp map[string]map[string]any
var err error
if isPipeline {
- dslJSON, lerr := loadCanvasDSLJSON(ctx, strings.TrimSpace(*pipelineID))
+ dslJSON, lerr := loadCanvasDSLJSON(ctx, strings.TrimSpace(*pipelineID), versionID)
if lerr != nil {
return nil, fmt.Errorf("load canvas DSL: %w", lerr)
}
diff --git a/internal/service/pipeline_params_version_test.go b/internal/service/pipeline_params_version_test.go
new file mode 100644
index 0000000000..679c27f1f2
--- /dev/null
+++ b/internal/service/pipeline_params_version_test.go
@@ -0,0 +1,238 @@
+package service
+
+import (
+ "context"
+ "errors"
+ "strings"
+ "testing"
+
+ "ragflow/internal/dao"
+ "ragflow/internal/entity"
+)
+
+func assertContains(t *testing.T, haystack, needle string) {
+ t.Helper()
+ if !strings.Contains(haystack, needle) {
+ t.Fatalf("expected output to contain %q, got: %s", needle, haystack)
+ }
+}
+
+func assertMissing(t *testing.T, err error) {
+ t.Helper()
+ if err == nil {
+ t.Fatal("expected ErrPipelineVersionMissing, got nil error")
+ }
+ if !errors.Is(err, ErrPipelineVersionMissing) {
+ t.Fatalf("expected ErrPipelineVersionMissing, got: %v", err)
+ }
+}
+
+func TestLoadCanvasDSLJSON_VersionedReadsVersionDSL(t *testing.T) {
+ db := setupServiceTestDB(t)
+ if err := db.AutoMigrate(&entity.UserCanvasVersion{}); err != nil {
+ t.Fatalf("migrate: %v", err)
+ }
+ orig := dao.DB
+ dao.DB = db
+ t.Cleanup(func() { dao.DB = orig })
+
+ ctx := context.Background()
+ canvasID := "cv-versioned"
+ if err := db.Create(&entity.UserCanvas{ID: canvasID, CanvasCategory: "dataflow_canvas", DSL: entity.JSONMap{"graph": "legacy"}}).Error; err != nil {
+ t.Fatal(err)
+ }
+ if err := db.Create(&entity.UserCanvasVersion{ID: "ver-1", UserCanvasID: canvasID, DSL: entity.JSONMap{"graph": "versioned"}}).Error; err != nil {
+ t.Fatal(err)
+ }
+
+ raw, err := loadCanvasDSLJSON(ctx, canvasID, sptr("ver-1"))
+ if err != nil {
+ t.Fatalf("loadCanvasDSLJSON: %v", err)
+ }
+ assertContains(t, string(raw), "versioned")
+ if strings.Contains(string(raw), "legacy") {
+ t.Fatalf("expected version DSL, got legacy: %s", string(raw))
+ }
+}
+
+func TestLoadCanvasDSLJSON_VersionedMisownedIsMissing(t *testing.T) {
+ db := setupServiceTestDB(t)
+ if err := db.AutoMigrate(&entity.UserCanvasVersion{}); err != nil {
+ t.Fatalf("migrate: %v", err)
+ }
+ orig := dao.DB
+ dao.DB = db
+ t.Cleanup(func() { dao.DB = orig })
+
+ ctx := context.Background()
+ if err := db.Create(&entity.UserCanvas{ID: "cv-a", CanvasCategory: "dataflow_canvas", DSL: entity.JSONMap{"graph": "a"}}).Error; err != nil {
+ t.Fatal(err)
+ }
+ if err := db.Create(&entity.UserCanvas{ID: "cv-b", CanvasCategory: "dataflow_canvas", DSL: entity.JSONMap{"graph": "b"}}).Error; err != nil {
+ t.Fatal(err)
+ }
+ if err := db.Create(&entity.UserCanvasVersion{ID: "ver-b", UserCanvasID: "cv-b", DSL: entity.JSONMap{"graph": "versioned-b"}}).Error; err != nil {
+ t.Fatal(err)
+ }
+
+ // ver-b belongs to cv-b but is requested for cv-a -> Missing.
+ _, err := loadCanvasDSLJSON(ctx, "cv-a", sptr("ver-b"))
+ assertMissing(t, err)
+}
+
+func TestLoadCanvasDSLJSON_VersionedNotFoundIsMissing(t *testing.T) {
+ db := setupServiceTestDB(t)
+ if err := db.AutoMigrate(&entity.UserCanvasVersion{}); err != nil {
+ t.Fatalf("migrate: %v", err)
+ }
+ orig := dao.DB
+ dao.DB = db
+ t.Cleanup(func() { dao.DB = orig })
+
+ ctx := context.Background()
+ if err := db.Create(&entity.UserCanvas{ID: "cv-x", CanvasCategory: "dataflow_canvas", DSL: entity.JSONMap{"graph": "x"}}).Error; err != nil {
+ t.Fatal(err)
+ }
+
+ _, err := loadCanvasDSLJSON(ctx, "cv-x", sptr("no-such-version"))
+ assertMissing(t, err)
+}
+
+func TestLoadCanvasDSLJSON_NilVersionFallsBackToLatestVersion(t *testing.T) {
+ db := setupServiceTestDB(t)
+ if err := db.AutoMigrate(&entity.UserCanvasVersion{}); err != nil {
+ t.Fatalf("migrate: %v", err)
+ }
+ orig := dao.DB
+ dao.DB = db
+ t.Cleanup(func() { dao.DB = orig })
+
+ ctx := context.Background()
+ canvasID := "cv-fallback"
+ if err := db.Create(&entity.UserCanvas{ID: canvasID, CanvasCategory: "dataflow_canvas", DSL: entity.JSONMap{"graph": "legacy"}}).Error; err != nil {
+ t.Fatal(err)
+ }
+ if err := db.Create(&entity.UserCanvasVersion{ID: "ver-fb", UserCanvasID: canvasID, DSL: entity.JSONMap{"graph": "from-version"}}).Error; err != nil {
+ t.Fatal(err)
+ }
+
+ raw, err := loadCanvasDSLJSON(ctx, canvasID, nil)
+ if err != nil {
+ t.Fatalf("loadCanvasDSLJSON: %v", err)
+ }
+ assertContains(t, string(raw), "from-version")
+}
+
+func TestLoadCanvasDSLJSON_AgentCanvasReadsCanvasDSL(t *testing.T) {
+ db := setupServiceTestDB(t)
+ if err := db.AutoMigrate(&entity.UserCanvasVersion{}); err != nil {
+ t.Fatalf("migrate: %v", err)
+ }
+ orig := dao.DB
+ dao.DB = db
+ t.Cleanup(func() { dao.DB = orig })
+
+ ctx := context.Background()
+ // Agent canvases are out of the multi-version scope (design §1): they keep
+ // reading the live draft column, even with no version rows.
+ canvasID := "cv-agent"
+ if err := db.Create(&entity.UserCanvas{ID: canvasID, CanvasCategory: "agent_canvas", DSL: entity.JSONMap{"graph": "agent-only"}}).Error; err != nil {
+ t.Fatal(err)
+ }
+
+ raw, err := loadCanvasDSLJSON(ctx, canvasID, nil)
+ if err != nil {
+ t.Fatalf("loadCanvasDSLJSON: %v", err)
+ }
+ assertContains(t, string(raw), "agent-only")
+}
+
+func TestLoadCanvasDSLJSON_DataflowWithoutVersionIsMissing(t *testing.T) {
+ db := setupServiceTestDB(t)
+ if err := db.AutoMigrate(&entity.UserCanvasVersion{}); err != nil {
+ t.Fatalf("migrate: %v", err)
+ }
+ orig := dao.DB
+ dao.DB = db
+ t.Cleanup(func() { dao.DB = orig })
+
+ ctx := context.Background()
+ // A dataflow canvas with a DSL but NO version rows must surface Missing
+ // (design §6.1): the legacy draft column is not a fallback for dataflow.
+ canvasID := "cv-dataflow-orphan"
+ if err := db.Create(&entity.UserCanvas{ID: canvasID, CanvasCategory: "dataflow_canvas", DSL: entity.JSONMap{"graph": "legacy-only"}}).Error; err != nil {
+ t.Fatal(err)
+ }
+
+ _, err := loadCanvasDSLJSON(ctx, canvasID, nil)
+ assertMissing(t, err)
+}
+
+func TestLoadPipelineDSL_PassthroughVersion(t *testing.T) {
+ db := setupServiceTestDB(t)
+ if err := db.AutoMigrate(&entity.UserCanvasVersion{}); err != nil {
+ t.Fatalf("migrate: %v", err)
+ }
+ orig := dao.DB
+ dao.DB = db
+ t.Cleanup(func() { dao.DB = orig })
+
+ ctx := context.Background()
+ canvasID := "cv-pipe"
+ if err := db.Create(&entity.UserCanvas{ID: canvasID, CanvasCategory: "dataflow_canvas", DSL: entity.JSONMap{"graph": "legacy"}}).Error; err != nil {
+ t.Fatal(err)
+ }
+ if err := db.Create(&entity.UserCanvasVersion{ID: "ver-pipe", UserCanvasID: canvasID, DSL: entity.JSONMap{"graph": "piped-version"}}).Error; err != nil {
+ t.Fatal(err)
+ }
+
+ raw, err := LoadPipelineDSL(ctx, true, "", sptr(canvasID), sptr("ver-pipe"))
+ if err != nil {
+ t.Fatalf("LoadPipelineDSL: %v", err)
+ }
+ assertContains(t, string(raw), "piped-version")
+}
+
+// TestErrPipelineVersionMissingSingleSentinel proves the service-layer sentinel
+// is the single dao definition, not a second errors.New with the same message.
+// This locks in the review fix that merged the service/task duplicate sentinels
+// into one (design §6.2). A caller using errors.Is against the dao sentinel must
+// match service-produced Missing errors.
+func TestErrPipelineVersionMissingSingleSentinel(t *testing.T) {
+ if !errors.Is(ErrPipelineVersionMissing, dao.ErrPipelineVersionMissing) {
+ t.Fatalf("service.ErrPipelineVersionMissing must be dao.ErrPipelineVersionMissing, got distinct identity")
+ }
+}
+
+func TestResolveComponentParamsDefaults_PassthroughVersion(t *testing.T) {
+ db := setupServiceTestDB(t)
+ if err := db.AutoMigrate(&entity.UserCanvasVersion{}); err != nil {
+ t.Fatalf("migrate: %v", err)
+ }
+ orig := dao.DB
+ dao.DB = db
+ t.Cleanup(func() { dao.DB = orig })
+
+ ctx := context.Background()
+ canvasID := "cv-resolve"
+ if err := db.Create(&entity.UserCanvas{ID: canvasID, CanvasCategory: "dataflow_canvas", DSL: entity.JSONMap{"graph": "legacy"}}).Error; err != nil {
+ t.Fatal(err)
+ }
+ if err := db.Create(&entity.UserCanvasVersion{ID: "ver-resolve", UserCanvasID: canvasID, DSL: entity.JSONMap{"graph": "resolved-version"}}).Error; err != nil {
+ t.Fatal(err)
+ }
+ if err := db.Create(&entity.UserCanvasVersion{ID: "ver-empty", UserCanvasID: canvasID, DSL: entity.JSONMap{}}).Error; err != nil {
+ t.Fatal(err)
+ }
+
+ // Threading proof: an empty version DSL surfaces ErrPipelineVersionMissing.
+ if _, err := ResolveComponentParamsDefaults(ctx, "", sptr(canvasID), sptr("ver-empty")); err != nil {
+ assertMissing(t, err)
+ }
+
+ // A non-empty version DSL is loaded and parsed (not rejected as Missing),
+ // even if the stub DSL has no extractable component params.
+ if _, err := ResolveComponentParamsDefaults(ctx, "", sptr(canvasID), sptr("ver-resolve")); errors.Is(err, ErrPipelineVersionMissing) {
+ t.Fatalf("non-empty version should not be Missing, got: %v", err)
+ }
+}
diff --git a/internal/service/update_agent_save_semantics_test.go b/internal/service/update_agent_save_semantics_test.go
new file mode 100644
index 0000000000..3fcafecdcd
--- /dev/null
+++ b/internal/service/update_agent_save_semantics_test.go
@@ -0,0 +1,144 @@
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package service
+
+import (
+ "testing"
+
+ "gorm.io/gorm"
+
+ "ragflow/internal/dao"
+ "ragflow/internal/entity"
+)
+
+func seedSaveCanvas(t *testing.T, db *gorm.DB, userID, canvasID string) {
+ t.Helper()
+ if err := db.AutoMigrate(&entity.UserCanvas{}, &entity.UserCanvasVersion{}); err != nil {
+ t.Fatalf("migrate canvas tables: %v", err)
+ }
+ if err := db.Create(&entity.User{ID: userID, Nickname: "owner", Email: "[email protected]"}).Error; err != nil {
+ t.Fatalf("seed user: %v", err)
+ }
+ if err := db.Create(&entity.UserCanvas{
+ ID: canvasID, UserID: userID, Title: sptr("Save Agent"), CanvasCategory: "agent_canvas", DSL: entity.JSONMap{},
+ }).Error; err != nil {
+ t.Fatalf("seed canvas: %v", err)
+ }
+}
+
+func sampleDSL() map[string]interface{} {
+ return map[string]interface{}{
+ "graph": map[string]interface{}{
+ "nodes": []interface{}{map[string]interface{}{"id": "begin"}},
+ "edges": []interface{}{},
+ },
+ "components": map[string]interface{}{
+ "begin": map[string]interface{}{"obj": map[string]interface{}{"component_name": "Begin"}},
+ },
+ }
+}
+
+// T32 (v5.2 §5.1): autosave updates the live draft (user_canvas.dsl) but does
+// NOT create a new version.
+func TestUpdateAgent_AutosaveUpdatesDraftOnly(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ userID := "user-1"
+ canvasID := "canvas-autosave"
+ seedSaveCanvas(t, db, userID, canvasID)
+ svc := NewAgentService()
+ ctx := t.Context()
+
+ if err := svc.UpdateAgent(ctx, userID, canvasID, map[string]interface{}{"dsl": sampleDSL()}); err != nil {
+ t.Fatalf("manual save: %v", err)
+ }
+ before, err := dao.NewUserCanvasVersionDAO().ListByCanvasID(ctx, dao.DB, canvasID)
+ if err != nil {
+ t.Fatalf("list: %v", err)
+ }
+ if len(before) != 1 {
+ t.Fatalf("want 1 version after manual save, got %d", len(before))
+ }
+
+ autoDSL := sampleDSL()
+ autoDSL["autosave_marker"] = "yes"
+ if err := svc.UpdateAgent(ctx, userID, canvasID, map[string]interface{}{"dsl": autoDSL, "autosave": true}); err != nil {
+ t.Fatalf("autosave: %v", err)
+ }
+ after, err := dao.NewUserCanvasVersionDAO().ListByCanvasID(ctx, dao.DB, canvasID)
+ if err != nil {
+ t.Fatalf("list: %v", err)
+ }
+ if len(after) != 1 {
+ t.Fatalf("autosave must not create a version, got %d", len(after))
+ }
+ reloaded, err := dao.NewUserCanvasDAO().GetByID(ctx, dao.DB, canvasID)
+ if err != nil {
+ t.Fatalf("reload canvas: %v", err)
+ }
+ if _, ok := reloaded.DSL["autosave_marker"]; !ok {
+ t.Fatalf("autosave did not refresh the live draft: %v", reloaded.DSL)
+ }
+}
+
+// T33 (v5.2 §5.1): a manual Save with the SAME DSL as the previous version
+// still INSERTs a new version (no same-DSL in-place dedup).
+func TestUpdateAgent_ManualSaveInsertsNewVersion(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ userID := "user-1"
+ canvasID := "canvas-manual"
+ seedSaveCanvas(t, db, userID, canvasID)
+ svc := NewAgentService()
+ ctx := t.Context()
+
+ if err := svc.UpdateAgent(ctx, userID, canvasID, map[string]interface{}{"dsl": sampleDSL()}); err != nil {
+ t.Fatalf("first save: %v", err)
+ }
+ if err := svc.UpdateAgent(ctx, userID, canvasID, map[string]interface{}{"dsl": sampleDSL()}); err != nil {
+ t.Fatalf("second save: %v", err)
+ }
+ versions, err := dao.NewUserCanvasVersionDAO().ListByCanvasID(ctx, dao.DB, canvasID)
+ if err != nil {
+ t.Fatalf("list: %v", err)
+ }
+ if len(versions) != 2 {
+ t.Fatalf("manual saves must each mint a version, got %d", len(versions))
+ }
+}
+
+// T36 (v5.2 §4.4 carry-on): a manual Save carrying an alias writes it onto the
+// newly created version.
+func TestUpdateAgent_ManualSaveCarriesAlias(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ userID := "user-1"
+ canvasID := "canvas-alias-carry"
+ seedSaveCanvas(t, db, userID, canvasID)
+ svc := NewAgentService()
+ ctx := t.Context()
+
+ alias := "carried-alias"
+ if err := svc.UpdateAgent(ctx, userID, canvasID, map[string]interface{}{"dsl": sampleDSL(), "alias": alias}); err != nil {
+ t.Fatalf("save with alias: %v", err)
+ }
+ latest, err := dao.NewUserCanvasVersionDAO().GetLatest(ctx, dao.DB, canvasID)
+ if err != nil {
+ t.Fatalf("get latest: %v", err)
+ }
+ if latest.Alias == nil || *latest.Alias != alias {
+ t.Fatalf("carry-on alias not written: got %v", latest.Alias)
+ }
+}
diff --git a/internal/service/update_version_test.go b/internal/service/update_version_test.go
new file mode 100644
index 0000000000..5d5b7ebea5
--- /dev/null
+++ b/internal/service/update_version_test.go
@@ -0,0 +1,90 @@
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package service
+
+import (
+ "errors"
+ "testing"
+
+ "ragflow/internal/dao"
+ "ragflow/internal/entity"
+)
+
+// T35 (v5.2 alias write, design G2/§4.4): PATCH /versions/{id} with alias
+// updates that version's alias metadata, does NOT create a new version, and
+// does NOT change the DSL.
+func TestUpdateVersion_PatchesAliasWithoutNewVersion(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+
+ userID := "user-1"
+ canvasID := "0123456789abcdef0123456789abcdef"
+ versionID := "version0000000000000000000000cc"
+ seedVersionedDataflowCanvas(t, db, userID, canvasID, versionID)
+
+ alias := "release-candidate"
+ svc := NewAgentService()
+ patch := dao.UserCanvasVersionPatch{Alias: &alias}
+ if err := svc.UpdateVersion(t.Context(), userID, canvasID, versionID, patch); err != nil {
+ t.Fatalf("UpdateVersion alias: %v", err)
+ }
+
+ updated, err := dao.NewUserCanvasVersionDAO().GetByID(t.Context(), dao.DB, versionID)
+ if err != nil {
+ t.Fatalf("reload version: %v", err)
+ }
+ if updated.Alias == nil || *updated.Alias != alias {
+ t.Fatalf("alias not updated: got %v", updated.Alias)
+ }
+ if g, _ := updated.DSL["graph"].(string); g != "versioned" {
+ t.Fatalf("DSL changed unexpectedly: %v", updated.DSL)
+ }
+ all, err := dao.NewUserCanvasVersionDAO().ListByCanvasID(t.Context(), dao.DB, canvasID)
+ if err != nil {
+ t.Fatalf("list versions: %v", err)
+ }
+ if len(all) != 1 {
+ t.Fatalf("expected exactly 1 version, got %d", len(all))
+ }
+}
+
+// T35 ownership: patching a version that belongs to a different canvas is
+// rejected (cannot cross-canvas edit alias).
+func TestUpdateVersion_CrossCanvasRejected(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+
+ userID := "user-1"
+ canvasID := "0123456789abcdef0123456789abcdef"
+ otherCanvasID := "fedcba9876543210fedcba9876543210"
+ versionID := "version0000000000000000000000dd"
+ seedVersionedDataflowCanvas(t, db, userID, canvasID, versionID)
+
+ if err := db.AutoMigrate(&entity.UserCanvas{}); err != nil {
+ t.Fatalf("migrate canvas: %v", err)
+ }
+ other := &entity.UserCanvas{ID: otherCanvasID, UserID: userID, CanvasCategory: "dataflow_canvas", Permission: "me", DSL: entity.JSONMap{"graph": "legacy"}}
+ if err := db.Create(other).Error; err != nil {
+ t.Fatalf("seed other canvas: %v", err)
+ }
+
+ alias := "hijack"
+ svc := NewAgentService()
+ patch := dao.UserCanvasVersionPatch{Alias: &alias}
+ err := svc.UpdateVersion(t.Context(), userID, otherCanvasID, versionID, patch)
+ if !errors.Is(err, dao.ErrUserCanvasVersionNotFound) {
+ t.Fatalf("expected ErrUserCanvasVersionNotFound, got %v", err)
+ }
+}
diff --git a/web/src/components/document-pipeline-dialog/index.tsx b/web/src/components/document-pipeline-dialog/index.tsx
index 309fae3968..81a9c756f2 100644
--- a/web/src/components/document-pipeline-dialog/index.tsx
+++ b/web/src/components/document-pipeline-dialog/index.tsx
@@ -16,6 +16,7 @@
import { ParserSelect } from '@/components/parser-select';
import PipelineOperatorTabs from '@/components/pipeline-operator-tabs';
+import { PipelineVersionSelect } from '@/components/pipeline-version-select';
import { ButtonLoading } from '@/components/ui/button';
import {
Dialog,
@@ -25,6 +26,7 @@ import {
DialogTitle,
} from '@/components/ui/dialog';
import { Form, FormField, FormItem, FormMessage } from '@/components/ui/form';
+import { RAGFlowTooltip } from '@/components/ui/tooltip';
import { ParseType } from '@/constants/knowledge';
import { IModalProps } from '@/interfaces/common';
import { IChangeParserRequestBody } from '@/interfaces/request/document';
@@ -50,6 +52,7 @@ export function DocumentPipelineDialog({
onOk,
parserId,
pipelineId,
+ pipelineVersionId,
parserConfig,
loading,
}: IProps) {
@@ -66,7 +69,16 @@ export function DocumentPipelineDialog({
operatorValues,
showOperatorTabs,
buildSubmitData,
- } = useDocumentPipelineForm({ parserId, pipelineId, parserConfig });
+ versions,
+ latestVersionId,
+ versionListLoading,
+ versionListError,
+ } = useDocumentPipelineForm({
+ parserId,
+ pipelineId,
+ pipelineVersionId,
+ parserConfig,
+ });
const handleParserSelect = useParserSelectHandler(form);
@@ -78,6 +90,30 @@ export function DocumentPipelineDialog({
control: form.control,
name: 'pipeline_id',
});
+ const selectedVersionId = useWatch({
+ control: form.control,
+ name: 'pipeline_version_id',
+ });
+
+ // versions / latestVersionId / versionListLoading / versionListError come
+ // from the form hook, which fetches the canvas version list reactively.
+ // versions is newest-first, so versions[0] is the latest.
+ // A selected version is only Missing when the list has finished loading and
+ // the id is genuinely absent. While loading (initial mount of a pinned doc,
+ // or after switching pipelines) the list is empty, so treating absence as
+ // Missing would flash the banner and disable save before the fetch resolves.
+ // A fetch error must NOT be treated as Missing either: an errored list is an
+ // unknown state, not proof the version is gone, so we neither warn nor block
+ // the save on it.
+ const versionMissing =
+ !!selectedVersionId &&
+ !versionListLoading &&
+ !versionListError &&
+ !versions.some((v) => v.id === selectedVersionId);
+ const versionOutdated =
+ !!selectedVersionId &&
+ !versionMissing &&
+ selectedVersionId !== latestVersionId;
const onSubmit = useCallback(
async (data: Parameters<typeof buildSubmitData>[0]) => {
@@ -91,7 +127,6 @@ export function DocumentPipelineDialog({
const onInvalid = useCallback(
(errors: FieldErrors) => {
- // Surface the first failing operator tab so its field errors are visible.
const firstOperatorId = Object.keys(errors?.parser_config ?? {})[0];
if (firstOperatorId) {
setActiveTab(firstOperatorId);
@@ -112,6 +147,12 @@ export function DocumentPipelineDialog({
<DialogTitle>{t('knowledgeDetails.parsingMode')}</DialogTitle>
</DialogHeader>
+ {versionMissing && (
+ <div className="rounded-md border border-destructive/40 bg-destructive/10 px-3 py-2 text-sm text-destructive">
+ {t('flow.version.missingContent')}
+ </div>
+ )}
+
<Form {...form}>
<form
onSubmit={form.handleSubmit(onSubmit, onInvalid)}
@@ -137,6 +178,34 @@ export function DocumentPipelineDialog({
</FormItem>
)}
/>
+ {parseType === ParseType.Pipeline && !!selectedPipelineId && (
+ <FormField
+ control={form.control}
+ name="pipeline_version_id"
+ render={({ field }) => (
+ <FormItem>
+ <div className="flex items-center gap-1.5">
+ <span className="text-sm text-text-secondary">
+ {t('flow.version.label')}
+ </span>
+ {versionOutdated && (
+ <RAGFlowTooltip tooltip={t('flow.version.outdated')}>
+ <span className="text-destructive cursor-help font-bold">
+ !
+ </span>
+ </RAGFlowTooltip>
+ )}
+ </div>
+ <PipelineVersionSelect
+ versions={versions}
+ value={field.value ?? ''}
+ onChange={field.onChange}
+ />
+ <FormMessage />
+ </FormItem>
+ )}
+ />
+ )}
{showOperatorTabs && (
<PipelineOperatorTabs
nodes={operatorNodes}
@@ -158,6 +227,7 @@ export function DocumentPipelineDialog({
<ButtonLoading
type="submit"
form={FormId}
+ disabled={versionMissing}
loading={
loading || (operatorNodesLoading && operatorNodes.length === 0)
}
diff --git a/web/src/components/document-pipeline-dialog/use-document-pipeline-form.test.tsx b/web/src/components/document-pipeline-dialog/use-document-pipeline-form.test.tsx
new file mode 100644
index 0000000000..efff96097c
--- /dev/null
+++ b/web/src/components/document-pipeline-dialog/use-document-pipeline-form.test.tsx
@@ -0,0 +1,94 @@
+import { renderHook, act } from '@testing-library/react';
+
+jest.mock('react-i18next', () => ({
+ useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+jest.mock('@/hooks/use-pipeline-operator', () => ({
+ useActiveTab: () => ({ activeTab: '', setActiveTab: jest.fn() }),
+ usePipelineOperatorNodes: () => ({ operatorNodes: [], loading: false }),
+ useResetParserConfigOnPipelineChange: () => {},
+}));
+
+// The hook now fetches the canvas version list itself and derives the latest
+// id reactively, so we mock the fetch and drive it via a mutable array.
+let mockVersions: Array<{ id: string; version?: number; name?: string }> = [];
+jest.mock('@/hooks/use-agent-request', () => ({
+ useFetchCanvasVersionList: () => ({
+ data: mockVersions,
+ loading: false,
+ isError: false,
+ }),
+}));
+
+// Cut the chain parser-config-validation -> compilation-form -> locales/config
+// (which calls i18n.use(initReactI18next) and would crash under the mock).
+jest.mock(
+ '@/components/pipeline-operator-tabs/parser-config-validation',
+ () => ({
+ addParserConfigIssues: jest.fn(),
+ }),
+);
+
+import { useDocumentPipelineForm } from './use-document-pipeline-form';
+
+function renderForm(props: any) {
+ return renderHook((p: any) => useDocumentPipelineForm(p), {
+ initialProps: props,
+ });
+}
+
+describe('useDocumentPipelineForm pipeline_version_id default (design S8: never show Latest version)', () => {
+ beforeEach(() => {
+ mockVersions = [];
+ });
+
+ it('adopts the latest concrete version for an unpinned document (R1a)', () => {
+ mockVersions = [{ id: 'v2', version: 2, name: 'v2' }];
+ const { result } = renderForm({
+ parserId: 'naive',
+ pipelineId: 'canvas-1',
+ pipelineVersionId: undefined,
+ });
+ expect(result.current.form.getValues('pipeline_version_id')).toBe('v2');
+ });
+
+ it('keeps an explicitly pinned version instead of overriding to latest (R1b)', () => {
+ mockVersions = [{ id: 'v2', version: 2, name: 'v2' }];
+ const { result } = renderForm({
+ parserId: 'naive',
+ pipelineId: 'canvas-1',
+ pipelineVersionId: 'v1',
+ });
+ expect(result.current.form.getValues('pipeline_version_id')).toBe('v1');
+ });
+
+ it('stays empty when there is no version list at all (R1c)', () => {
+ mockVersions = [];
+ const { result } = renderForm({
+ parserId: 'naive',
+ pipelineId: undefined,
+ pipelineVersionId: undefined,
+ });
+ expect(result.current.form.getValues('pipeline_version_id')).toBe('');
+ });
+
+ it('adopts the latest version once the list loads after mount (R1d, async)', () => {
+ mockVersions = [];
+ const { result, rerender } = renderForm({
+ parserId: 'naive',
+ pipelineId: 'canvas-1',
+ pipelineVersionId: undefined,
+ });
+ expect(result.current.form.getValues('pipeline_version_id')).toBe('');
+ mockVersions = [{ id: 'v3', version: 3, name: 'v3' }];
+ act(() => {
+ rerender({
+ parserId: 'naive',
+ pipelineId: 'canvas-1',
+ pipelineVersionId: undefined,
+ });
+ });
+ expect(result.current.form.getValues('pipeline_version_id')).toBe('v3');
+ });
+});
diff --git a/web/src/components/document-pipeline-dialog/use-document-pipeline-form.ts b/web/src/components/document-pipeline-dialog/use-document-pipeline-form.ts
index 56b64de6de..8bc8b69fa4 100644
--- a/web/src/components/document-pipeline-dialog/use-document-pipeline-form.ts
+++ b/web/src/components/document-pipeline-dialog/use-document-pipeline-form.ts
@@ -20,6 +20,7 @@ import {
usePipelineOperatorNodes,
useResetParserConfigOnPipelineChange,
} from '@/hooks/use-pipeline-operator';
+import { useFetchCanvasVersionList } from '@/hooks/use-agent-request';
import { IChangeParserRequestBody } from '@/interfaces/request/document';
import {
getOperatorType,
@@ -37,12 +38,16 @@ import { addParserConfigIssues } from '../pipeline-operator-tabs/parser-config-v
export interface IDocumentPipelineDialogProps {
parserId: string;
pipelineId?: string;
+ // Currently pinned canvas version id (design section 5). Empty when the
+ // dataset/document binds the latest version.
+ pipelineVersionId?: string;
parserConfig?: Record<string, any>;
}
export function useDocumentPipelineForm({
parserId,
pipelineId,
+ pipelineVersionId,
parserConfig,
}: IDocumentPipelineDialogProps) {
const { t } = useTranslation();
@@ -57,6 +62,7 @@ export function useDocumentPipelineForm({
// The superRefine below enforces it when BuiltIn is selected.
parser_id: z.string().optional(),
pipeline_id: z.string().optional(),
+ pipeline_version_id: z.string().optional(),
parser_config: z.record(z.string(), z.any()).optional(),
})
.superRefine((data, ctx) => {
@@ -88,6 +94,10 @@ export function useDocumentPipelineForm({
parse_type: pipelineId ? ParseType.Pipeline : ParseType.BuiltIn,
parser_id: parserId || '',
pipeline_id: pipelineId || '',
+ // Design section 8: an unpinned document still pre-selects the latest
+ // concrete version so the UI shows a specific version, never the
+ // "Latest version" placeholder. A pinned value wins when present.
+ pipeline_version_id: pipelineVersionId || '',
parser_config: transformSavedParserConfigToForm(parserConfig),
},
});
@@ -109,6 +119,19 @@ export function useDocumentPipelineForm({
const selectedPipelineId = isPipelineMode
? selectedDataFlowId
: selectedBuiltinId;
+ // The canvas version list drives the selector, the D1/D2/D3 non-latest `!`
+ // indicator and the T29 Missing (unparseable) detection. We fetch it inside
+ // the hook so the latest id is a *reactive* value: it resolves after mount
+ // and the adoption effect below re-fires when it does. (Reading it from a
+ // static prop captured before the fetch would freeze it at undefined.)
+ const {
+ data: versions = [],
+ loading: versionListLoading,
+ isError: versionListError,
+ } = useFetchCanvasVersionList(
+ isPipelineMode ? selectedDataFlowId : undefined,
+ );
+ const latestVersionId = versions[0]?.id;
// The saved parser_config only belongs to the pipeline (and parse type) it
// was saved with — expose its id only while that exact pipeline is selected,
// so that after switching, defaults come purely from the new pipeline's DSL.
@@ -136,6 +159,34 @@ export function useDocumentPipelineForm({
operatorNodes,
);
+ // A pinned version belongs to the canvas it was pinned on (design section 5/B4
+ // sticky snapshot). Switching the dataflow canvas invalidates any previously
+ // pinned version, so clear it; otherwise a version id from the old canvas
+ // would be submitted against the new pipeline. The initial load keeps the
+ // saved version (selected equals saved).
+ useEffect(() => {
+ if (selectedPipelineId !== savedPipelineId) {
+ form.setValue('pipeline_version_id', '');
+ }
+ }, [selectedPipelineId, savedPipelineId, form]);
+
+ // Design section 8 (T37): an unpinned document must never show the "Latest
+ // version" pseudo-value, so adopt the latest concrete version id once the
+ // version list resolves (it loads asynchronously, hence the effect rather
+ // than the form default). `latestVersionId` is reactive (derived from the
+ // fetch above), so this re-fires when the list arrives. We only adopt while
+ // the field is still empty, so a user's manual selection of an older version
+ // is preserved and a stable latest id will not re-fire this effect.
+ useEffect(() => {
+ if (
+ !pipelineVersionId &&
+ latestVersionId &&
+ !form.getValues('pipeline_version_id')
+ ) {
+ form.setValue('pipeline_version_id', latestVersionId);
+ }
+ }, [pipelineVersionId, latestVersionId, form]);
+
const { activeTab, setActiveTab } = useActiveTab(operatorNodes);
useEffect(() => {
@@ -187,6 +238,7 @@ export function useDocumentPipelineForm({
return {
parser_id: isPipeline ? '' : (data.parser_id ?? ''),
pipeline_id: isPipeline ? data.pipeline_id : '',
+ pipeline_version_id: isPipeline ? (data.pipeline_version_id ?? '') : '',
parser_config: transformedConfig,
parse_type: data.parse_type,
};
@@ -205,5 +257,9 @@ export function useDocumentPipelineForm({
operatorValues,
showOperatorTabs,
buildSubmitData,
+ versions,
+ latestVersionId,
+ versionListLoading,
+ versionListError,
};
}
diff --git a/web/src/components/pipeline-version-select/index.test.tsx b/web/src/components/pipeline-version-select/index.test.tsx
new file mode 100644
index 0000000000..9bcbad0291
--- /dev/null
+++ b/web/src/components/pipeline-version-select/index.test.tsx
@@ -0,0 +1,73 @@
+import { render, screen } from '@testing-library/react';
+import React from 'react';
+
+jest.mock('react-i18next', () => ({
+ useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+import { PipelineVersionSelect, filterVersionsByAlias } from './index';
+
+describe('filterVersionsByAlias', () => {
+ const versions = [
+ { id: 'v1', title: 'First', alias: 'prod' },
+ { id: 'v2', title: 'Second', alias: null },
+ { id: 'v3', title: 'Third', alias: 'PROD-2' },
+ ];
+
+ it('returns all versions when the filter is empty or whitespace', () => {
+ expect(filterVersionsByAlias(versions, '')).toHaveLength(3);
+ expect(filterVersionsByAlias(versions, ' ')).toHaveLength(3);
+ });
+
+ it('filters case-insensitively by alias', () => {
+ expect(filterVersionsByAlias(versions, 'prod').map((v) => v.id)).toEqual([
+ 'v1',
+ 'v3',
+ ]);
+ });
+
+ it('treats a null alias as non-matching', () => {
+ expect(filterVersionsByAlias(versions, 'second')).toHaveLength(0);
+ });
+});
+
+describe('PipelineVersionSelect (G1/v5.2: no latest pseudo-option)', () => {
+ it('renders the alias filter input', () => {
+ render(
+ React.createElement(PipelineVersionSelect, {
+ versions: [],
+ value: '',
+ onChange: jest.fn(),
+ }),
+ );
+ expect(
+ screen.getByPlaceholderText('flow.version.filterByAlias'),
+ ).toBeInTheDocument();
+ });
+
+ it('shows the latest placeholder when unbound, with no __latest__ option', () => {
+ render(
+ React.createElement(PipelineVersionSelect, {
+ versions: [{ id: 'v1', title: 'First', alias: null }],
+ value: '',
+ onChange: jest.fn(),
+ }),
+ );
+ // The "latest" label is only a placeholder; there is no selectable
+ // __latest__ sentinel item (design G1 / v5.2).
+ expect(screen.getByText('flow.version.latest')).toBeInTheDocument();
+ expect(screen.queryByText('__latest__')).toBeNull();
+ });
+
+ it('passes the concrete version id through unchanged', () => {
+ const onChange = jest.fn();
+ render(
+ React.createElement(PipelineVersionSelect, {
+ versions: [{ id: 'v1', title: 'First', alias: 'prod' }],
+ value: 'v1',
+ onChange,
+ }),
+ );
+ expect(screen.queryByText('__latest__')).toBeNull();
+ });
+});
diff --git a/web/src/components/pipeline-version-select/index.tsx b/web/src/components/pipeline-version-select/index.tsx
new file mode 100644
index 0000000000..9cea1dac7c
--- /dev/null
+++ b/web/src/components/pipeline-version-select/index.tsx
@@ -0,0 +1,86 @@
+/*
+ * Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { Input } from '@/components/ui/input';
+import {
+ Select,
+ SelectContent,
+ SelectItem,
+ SelectTrigger,
+ SelectValue,
+} from '@/components/ui/select';
+import { useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+export type PipelineVersion = {
+ id: string;
+ title: string;
+ alias?: string | null;
+};
+
+// filterVersionsByAlias applies the free-text alias filter (design A2/F1).
+// An empty or whitespace-only filter keeps every version; matching is
+// case-insensitive; a null alias never matches.
+export function filterVersionsByAlias<V extends PipelineVersion>(
+ versions: V[],
+ aliasFilter: string,
+): V[] {
+ const needle = aliasFilter.trim().toLowerCase();
+ if (!needle) return versions;
+ return versions.filter((v) => (v.alias ?? '').toLowerCase().includes(needle));
+}
+
+// PipelineVersionSelect lets the user pin a specific dataflow canvas version
+// (design section 5/C2) or leave it empty to track the latest version.
+// Versions can be filtered by their free-text alias (design A2/F1). Shared by
+// the document pipeline dialog and the dataset settings page.
+export function PipelineVersionSelect({
+ versions,
+ value,
+ onChange,
+}: {
+ versions: PipelineVersion[];
+ value: string;
+ onChange: (v: string) => void;
+}) {
+ const { t } = useTranslation();
+ const [aliasFilter, setAliasFilter] = useState('');
+
+ const filtered = filterVersionsByAlias(versions, aliasFilter);
+
+ return (
+ <div className="space-y-2">
+ <Input
+ className="h-8"
+ placeholder={t('flow.version.filterByAlias')}
+ value={aliasFilter}
+ onChange={(e) => setAliasFilter(e.target.value)}
+ />
+ <Select value={value} onValueChange={(v) => onChange(v)}>
+ <SelectTrigger>
+ <SelectValue placeholder={t('flow.version.latest')} />
+ </SelectTrigger>
+ <SelectContent>
+ {filtered.map((v) => (
+ <SelectItem key={v.id} value={v.id}>
+ {v.alias ? v.alias + ' (' + v.title + ')' : v.title}
+ </SelectItem>
+ ))}
+ </SelectContent>
+ </Select>
+ </div>
+ );
+}
diff --git a/web/src/hooks/use-agent-request.ts b/web/src/hooks/use-agent-request.ts
index 282d196530..1cf330ca49 100644
--- a/web/src/hooks/use-agent-request.ts
+++ b/web/src/hooks/use-agent-request.ts
@@ -53,6 +53,7 @@ import agentService, {
revokeAgentWebhookCredential,
updateAgent,
updateAgentTags,
+ updateVersion,
uploadAgentFile,
} from '@/services/agent-service';
import { buildMessageListWithUuid } from '@/utils/chat';
@@ -537,6 +538,8 @@ export const useSetAgent = (
release?: string;
description?: string | null;
permission?: string;
+ autosave?: boolean;
+ alias?: string;
}) => {
const agentId = params.id ?? id;
const { data = {} } = agentId
@@ -547,6 +550,8 @@ export const useSetAgent = (
description: params.description,
permission: params.permission,
release: params.release,
+ autosave: params.autosave,
+ alias: params.alias,
})
: await agentService.createAgent(params);
if (data.code === 0) {
@@ -795,7 +800,13 @@ export const useFetchInputForm = (componentId?: string) => {
export const useFetchVersionList = () => {
const { id } = useParams();
const { data, isFetching: loading } = useQuery<
- Array<{ created_at: string; title: string; id: string; release?: boolean }>
+ Array<{
+ created_at: string;
+ title: string;
+ id: string;
+ release?: boolean;
+ alias?: string;
+ }>
>({
queryKey: AgentKeys.versionList(id),
initialData: [],
@@ -810,6 +821,115 @@ export const useFetchVersionList = () => {
return { data, loading };
};
+// useFetchCanvasVersionList lists the published versions of an arbitrary canvas
+// (dataflow or agent) by id. Unlike useFetchVersionList it takes the canvas id
+// explicitly (not from route params) so the document pipeline dialog can load
+// versions for the currently selected dataflow canvas. The backend returns them
+// newest-first (design section 7/E1) and includes the free-text alias (A2/F1).
+export const useFetchCanvasVersionList = (canvasId?: string) => {
+ const {
+ data,
+ isFetching: loading,
+ isError,
+ } = useQuery<
+ Array<{
+ id: string;
+ title: string;
+ created_at: string;
+ release?: boolean;
+ alias?: string;
+ }>
+ >({
+ queryKey: ['canvasVersionList', canvasId],
+ initialData: [],
+ gcTime: 0,
+ enabled: !!canvasId,
+ queryFn: async () => {
+ if (!canvasId) return [];
+ const { data } = await agentService.fetchVersionList(canvasId);
+ return data?.data ?? [];
+ },
+ });
+
+ return { data, loading, isError };
+};
+
+// useDeleteVersion removes a single canvas version (design section 7/B2). The
+// backend still allows deletion when the version is referenced by a dataset or
+// file; the binding then enters a Missing (unparseable) state, so the UI shows a
+// confirmation that warns about breaking bound files (B2.1).
+export const useDeleteVersion = () => {
+ const queryClient = useQueryClient();
+ const {
+ isPending: loading,
+ isError,
+ mutateAsync,
+ } = useMutation({
+ mutationFn: async ({
+ canvasId,
+ versionId,
+ }: {
+ canvasId: string;
+ versionId: string;
+ }) => {
+ const { data } = await agentService.deleteVersion({
+ agentId: canvasId,
+ versionId,
+ });
+ return data?.code === 0;
+ },
+ onSuccess: (_result, variables) => {
+ // Invalidate both version-list caches so the deleted version disappears
+ // without a manual refresh: the version dialog reads
+ // AgentKeys.versionList (canvas id from route params) and the document
+ // pipeline dialog reads the canvasVersionList key.
+ queryClient.invalidateQueries({
+ queryKey: AgentKeys.versionList(variables.canvasId),
+ });
+ queryClient.invalidateQueries({
+ queryKey: ['canvasVersionList', variables.canvasId],
+ });
+ },
+ });
+
+ return { loading, isError, deleteVersion: mutateAsync };
+};
+
+export const useUpdateVersion = () => {
+ const queryClient = useQueryClient();
+ const {
+ isPending: loading,
+ isError,
+ mutateAsync,
+ } = useMutation({
+ mutationFn: async ({
+ canvasId,
+ versionId,
+ alias,
+ }: {
+ canvasId: string;
+ versionId: string;
+ alias: string;
+ }) => {
+ const { data } = await updateVersion(canvasId, versionId, { alias });
+ return data?.code === 0;
+ },
+ onSuccess: (_result, variables) => {
+ // The alias edit does not create a version or change the DSL, but the
+ // version-list cache must reflect the new alias without a manual refresh
+ // (design G2/§4.4).
+ queryClient.invalidateQueries({
+ queryKey: AgentKeys.versionList(variables.canvasId),
+ });
+ queryClient.invalidateQueries({
+ queryKey: ['canvasVersionList', variables.canvasId],
+ });
+ },
+ });
+
+ return { loading, isError, updateVersion: mutateAsync };
+};
+
export const useFetchVersion = (
version_id?: string,
): {
diff --git a/web/src/hooks/use-document-request.ts b/web/src/hooks/use-document-request.ts
index 62ec25974e..0a1f727835 100644
--- a/web/src/hooks/use-document-request.ts
+++ b/web/src/hooks/use-document-request.ts
@@ -657,6 +657,7 @@ export const useSetDocumentPipelineParser = () => {
documentId,
datasetId,
parserConfig,
+ pipelineVersionId,
}: {
parserId: string;
pipelineId: string;
@@ -664,6 +665,7 @@ export const useSetDocumentPipelineParser = () => {
documentId: string;
datasetId: string;
parserConfig?: IChangeParserConfigRequestBody;
+ pipelineVersionId?: string;
}) => {
const updateData: Record<string, unknown> = {
parser_id: parserId,
@@ -674,6 +676,15 @@ export const useSetDocumentPipelineParser = () => {
updateData.parse_type = parse_type;
}
+ // Pin a specific dataflow canvas version (design section 5 sticky
+ // snapshot). An explicit empty string means the user picked
+ // Latest (track the canvas latest), so it must be sent for the
+ // backend to clear the pin; only an omitted value (undefined) keeps
+ // the current pin.
+ if (pipelineVersionId !== undefined) {
+ updateData.pipeline_version_id = pipelineVersionId;
+ }
+
if (parserConfig) {
updateData.parser_config = isPipelineParserConfig(parserConfig)
? parserConfig
diff --git a/web/src/interfaces/database/dataset.ts b/web/src/interfaces/database/dataset.ts
index 5af24bb848..c699be51c5 100644
--- a/web/src/interfaces/database/dataset.ts
+++ b/web/src/interfaces/database/dataset.ts
@@ -38,6 +38,11 @@ export interface IDataset {
parser_id?: string;
permission: string;
pipeline_id: string;
+ // Pinned dataflow canvas version (design section 5/C2). Absent or empty
+ // means the dataset tracks the canvas latest version.
+ pipeline_version_id?: string;
+ // True when the pinned version is not the canvas latest (design D1/D2/D3).
+ pipeline_version_outdated?: boolean;
raptor_task_finish_at: string;
raptor_task_id: string;
similarity_threshold: number;
diff --git a/web/src/interfaces/database/document.ts b/web/src/interfaces/database/document.ts
index 32873234ec..973dcef148 100644
--- a/web/src/interfaces/database/document.ts
+++ b/web/src/interfaces/database/document.ts
@@ -15,6 +15,11 @@ export interface IDocumentInfo {
// parser_id: string;
pipeline_id: string;
pipeline_name: string;
+ // Pinned dataflow canvas version; empty when the latest version is used
+ // (design section 5 sticky snapshot). Outdated/Missing flags come from the
+ // dataset/document read path (design section 6.2/6.3).
+ pipeline_version_id?: string;
+ pipeline_version_outdated?: boolean;
process_begin_at?: string;
process_duration: number;
progress: number;
diff --git a/web/src/interfaces/request/document.ts b/web/src/interfaces/request/document.ts
index 803db4aa25..ab7ffcaeae 100644
--- a/web/src/interfaces/request/document.ts
+++ b/web/src/interfaces/request/document.ts
@@ -39,6 +39,9 @@ export interface IChangeParserConfigRequestBody {
export interface IChangeParserRequestBody {
parser_id: string;
pipeline_id?: string;
+ // Pins a specific dataflow canvas version (design section 5 sticky snapshot).
+ // Empty/omitted means the latest published version is used at runtime.
+ pipeline_version_id?: string;
// 1 = BuiltIn (parser_id), 2 = Pipeline (pipeline_id); omitted = unspecified.
parse_type?: number;
doc_id?: string;
diff --git a/web/src/locales/en.ts b/web/src/locales/en.ts
index 8247c02f48..e873306261 100644
--- a/web/src/locales/en.ts
+++ b/web/src/locales/en.ts
@@ -3438,6 +3438,24 @@ This delimiter is used to split the input text into several text pieces echo of
loadFailed: 'Failed to load the version; it may have been deleted',
version: 'Version',
select: 'No version selected',
+ label: 'Pipeline version',
+ latest: 'Latest version',
+ filterByAlias: 'Filter by alias',
+ alias: 'Alias',
+ pinnedTooltip:
+ 'This dataset is pinned to a specific version. New versions published on the canvas will not affect it.',
+ outdated:
+ 'The pinned version is not the latest. Click to learn more; we will not upgrade it automatically.',
+ delete: 'Delete version',
+ deleteConfirmTitle: 'Delete this version?',
+ deleteConfirmContent:
+ 'Deleting a version that a dataset or file is bound to will make that file unparseable. This cannot be undone.',
+ restore: 'Restore as current',
+ restoreConfirmTitle: 'Restore this version as the current canvas?',
+ restoreConfirmContent:
+ 'The current canvas DSL will be replaced by this version. Publish again to save it as a new version.',
+ missingContent:
+ 'The pinned pipeline version no longer exists, so this file cannot be parsed. Please choose a version (or the latest) to continue.',
},
setting: 'Settings',
settings: {
diff --git a/web/src/locales/zh.ts b/web/src/locales/zh.ts
index e03d689f4d..b28b7a5407 100644
--- a/web/src/locales/zh.ts
+++ b/web/src/locales/zh.ts
@@ -2474,6 +2474,22 @@ NER:使用 spaCy NER 和基于规则的关键词提取来抽取 Entities 和 R
download: '下载',
loadFailed: '版本加载失败,该版本可能已被删除',
version: '版本',
+ label: '流水线版本',
+ latest: '最新版本',
+ filterByAlias: '按别名筛选',
+ alias: '别名',
+ pinnedTooltip: '该数据集已固定到特定版本。画布新发布的版本不会影响它。',
+ outdated: '固定的版本不是最新版本。点击了解详情;我们不会自动升级它。',
+ delete: '删除版本',
+ deleteConfirmTitle: '删除该版本?',
+ deleteConfirmContent:
+ '若数据集或文件正绑定此版本,删除后将导致对应文件无法解析。此操作不可撤销。',
+ restore: '恢复为当前版本',
+ restoreConfirmTitle: '恢复此版本为当前画布?',
+ restoreConfirmContent:
+ '当前画布 DSL 将被此版本替换。再次发布会将其保存为新版本。',
+ missingContent:
+ '所固定的流水线版本已不存在,该文件无法解析。请重新选择版本(或选择最新版本)后继续。',
},
cite: '显示引文',
citeTip: '引用',
diff --git a/web/src/pages/agent/hooks/use-save-graph.ts b/web/src/pages/agent/hooks/use-save-graph.ts
index 2443ce67ca..635af9e0e1 100644
--- a/web/src/pages/agent/hooks/use-save-graph.ts
+++ b/web/src/pages/agent/hooks/use-save-graph.ts
@@ -37,6 +37,7 @@ export const useSaveGraph = (
globalVariables: Record<string, GlobalVariableType>;
},
release?: boolean,
+ autosave?: boolean,
) => {
if (!id) {
return;
@@ -51,6 +52,12 @@ export const useSaveGraph = (
if (release) {
params.release = 'true';
}
+ // Design §5.1: the debounced auto-save path passes autosave:true so the
+ // backend refreshes only the live draft and never mints a new version.
+ // An explicit (manual) Save omits this flag.
+ if (autosave) {
+ params.autosave = true;
+ }
return setAgent(params);
},
@@ -170,7 +177,7 @@ export const useWatchAgentChange = (chatDrawerVisible: boolean) => {
) {
return;
}
- const ret = await saveGraph();
+ const ret = await saveGraph(undefined, undefined, undefined, true);
if (ret?.data?.update_time) {
setSaveTime(ret.data.update_time);
}
diff --git a/web/src/pages/agent/version-dialog/index.test.tsx b/web/src/pages/agent/version-dialog/index.test.tsx
new file mode 100644
index 0000000000..a513dbcab6
--- /dev/null
+++ b/web/src/pages/agent/version-dialog/index.test.tsx
@@ -0,0 +1,160 @@
+/*
+ * Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { fireEvent, render, screen } from '@testing-library/react';
+import React from 'react';
+
+jest.mock('react-i18next', () => {
+ const actual = jest.requireActual('react-i18next');
+ return {
+ ...actual,
+ useTranslation: () => ({ t: (key: string) => key }),
+ };
+});
+
+jest.mock('react-router', () => ({
+ useParams: () => ({ id: 'canvas-1' }),
+}));
+
+// The component imports nodeTypes from the canvas graph, which transitively loads
+// the chat/i18n machinery. Mock it so the heavy canvas module is never imported.
+jest.mock('../canvas', () => ({ nodeTypes: {} }));
+
+// ReactFlow is heavy and irrelevant to the version-list assertions; render it as a
+// null node so the right-panel canvas does not mount during the test.
+jest.mock('@xyflow/react', () => ({
+ ReactFlow: () => null,
+ ReactFlowProvider: ({ children }: { children?: any }) => children,
+ ConnectionMode: { Loose: 'loose' },
+}));
+
+const mockUpdateVersion = jest.fn();
+
+const mockVersions = [
+ {
+ id: 'v-latest',
+ title: 'Latest',
+ created_at: '2024-01-02',
+ release: true,
+ alias: 'prod',
+ },
+ {
+ id: 'v-old',
+ title: 'Old Snapshot',
+ created_at: '2024-01-01',
+ release: false,
+ alias: 'old',
+ },
+];
+
+jest.mock('@/hooks/use-agent-request', () => ({
+ useFetchVersionList: () => ({ data: mockVersions, loading: false }),
+ useFetchVersion: () => ({ data: undefined, loading: false, isError: false }),
+ useDeleteVersion: () => ({
+ deleteVersion: jest.fn(),
+ loading: false,
+ isError: false,
+ }),
+ useSetAgent: () => ({ setAgent: jest.fn(), loading: false }),
+ useUpdateVersion: () => ({
+ updateVersion: mockUpdateVersion,
+ loading: false,
+ isError: false,
+ }),
+}));
+
+import { VersionDialog } from './index';
+
+describe('VersionDialog outdated marker (D1/D2/D3, T21)', () => {
+ it('marks non-latest versions with the ! outdated indicator but not the latest', () => {
+ render(<VersionDialog hideModal={jest.fn()} />);
+
+ expect(screen.getByText('Latest')).toBeInTheDocument();
+ expect(screen.getByText('Old Snapshot')).toBeInTheDocument();
+ // Exactly one ! marker: the non-latest list entry. The latest is selected by
+ // default, so the detail panel shows no marker.
+ expect(screen.getAllByText('!')).toHaveLength(1);
+ });
+});
+
+describe('VersionDialog editable alias input (G2/section 4.4, T35)', () => {
+ it('renders an editable alias input for every version', () => {
+ render(<VersionDialog hideModal={jest.fn()} />);
+ // Two mock versions => two alias inputs (design G2/section 4.4).
+ expect(screen.getAllByPlaceholderText('flow.version.alias')).toHaveLength(
+ 2,
+ );
+ });
+});
+
+describe('VersionDialog alias filter (A2/F1, T19)', () => {
+ it('narrows the list to aliases matching the query', () => {
+ render(<VersionDialog hideModal={jest.fn()} />);
+
+ const filter = screen.getByPlaceholderText('flow.version.filterByAlias');
+ fireEvent.change(filter, { target: { value: 'prod' } });
+
+ expect(screen.queryByText('Old Snapshot')).not.toBeInTheDocument();
+ expect(screen.getByText('Latest')).toBeInTheDocument();
+ expect(screen.queryByText('!')).not.toBeInTheDocument();
+ });
+
+ it('shows every version when the alias filter is cleared', () => {
+ render(<VersionDialog hideModal={jest.fn()} />);
+
+ const filter = screen.getByPlaceholderText('flow.version.filterByAlias');
+ fireEvent.change(filter, { target: { value: 'prod' } });
+ fireEvent.change(filter, { target: { value: '' } });
+
+ expect(screen.getByText('Latest')).toBeInTheDocument();
+ expect(screen.getByText('Old Snapshot')).toBeInTheDocument();
+ expect(screen.getAllByText('!')).toHaveLength(1);
+ });
+});
+
+describe('VersionDialog alias edit commits on blur (G2/section 4.4, T35)', () => {
+ it('PATCHes the trimmed new alias when the input loses focus', () => {
+ mockUpdateVersion.mockClear();
+ render(<VersionDialog hideModal={jest.fn()} />);
+
+ // mockVersions order: [v-latest (alias prod), v-old (alias old)].
+ const inputs = screen.getAllByPlaceholderText('flow.version.alias');
+ const oldInput = inputs[1];
+
+ fireEvent.change(oldInput, { target: { value: ' renamed ' } });
+ fireEvent.blur(oldInput);
+
+ expect(mockUpdateVersion).toHaveBeenCalledTimes(1);
+ expect(mockUpdateVersion).toHaveBeenCalledWith({
+ canvasId: 'canvas-1',
+ versionId: 'v-old',
+ alias: 'renamed',
+ });
+ });
+
+ it('does not PATCH when the alias is unchanged', () => {
+ mockUpdateVersion.mockClear();
+ render(<VersionDialog hideModal={jest.fn()} />);
+
+ const inputs = screen.getAllByPlaceholderText('flow.version.alias');
+ const oldInput = inputs[1]; // alias old
+
+ fireEvent.change(oldInput, { target: { value: 'old' } });
+ fireEvent.blur(oldInput);
+
+ expect(mockUpdateVersion).not.toHaveBeenCalled();
+ });
+});
diff --git a/web/src/pages/agent/version-dialog/index.tsx b/web/src/pages/agent/version-dialog/index.tsx
index d3a86da828..413fce12da 100644
--- a/web/src/pages/agent/version-dialog/index.tsx
+++ b/web/src/pages/agent/version-dialog/index.tsx
@@ -8,21 +8,36 @@ import {
DialogHeader,
DialogTitle,
} from '@/components/ui/dialog';
+import { Input } from '@/components/ui/input';
+import {
+ AlertDialog,
+ AlertDialogAction,
+ AlertDialogCancel,
+ AlertDialogContent,
+ AlertDialogDescription,
+ AlertDialogFooter,
+ AlertDialogHeader,
+ AlertDialogTitle,
+} from '@/components/ui/alert-dialog';
import { RAGFlowPagination } from '@/components/ui/ragflow-pagination';
import { Spin } from '@/components/ui/spin';
-import { RAGFlowTooltip } from '@/components/ui/tooltip';
+import { AntToolTip, RAGFlowTooltip } from '@/components/ui/tooltip';
import { useClientPagination } from '@/hooks/logic-hooks/use-pagination';
import {
+ useDeleteVersion,
useFetchVersion,
useFetchVersionList,
+ useSetAgent,
+ useUpdateVersion,
} from '@/hooks/use-agent-request';
import { IModalProps } from '@/interfaces/common';
import { cn } from '@/lib/utils';
import { formatDate } from '@/utils/date';
import { ConnectionMode, ReactFlow, ReactFlowProvider } from '@xyflow/react';
-import { ArrowDownToLine } from 'lucide-react';
-import { ReactNode, useCallback, useEffect, useState } from 'react';
+import { ArrowDownToLine, RotateCcw, Trash2 } from 'lucide-react';
+import { ReactNode, useCallback, useEffect, useMemo, useState } from 'react';
import { useTranslation } from 'react-i18next';
+import { useParams } from 'react-router';
import { nodeTypes } from '../canvas';
import { downloadDsl } from '../utils/download-dsl';
@@ -32,10 +47,51 @@ function Dot() {
);
}
+type PendingAction =
+ | { kind: 'delete'; versionId: string; title: string }
+ | { kind: 'restore'; versionId: string; title: string }
+ | null;
+
+// AliasInput is a controlled input for a single canvas version's free-text alias
+// (design G2/section 4.4). It keeps the value in local state and is keyed by
+// version id, so parent re-renders (including version-list refetches triggered by
+// focus changes or row selection) never unmount the field and wipe in-progress
+// keystrokes the way an uncontrolled defaultValue input with a volatile key could.
+const AliasInput = ({
+ placeholder,
+ versionId,
+ canvasId,
+ initialAlias,
+ onCommit,
+}: {
+ placeholder: string;
+ versionId: string;
+ canvasId: string;
+ initialAlias: string;
+ onCommit: (alias: string) => void;
+}) => {
+ const [val, setVal] = useState(initialAlias);
+ return (
+ <Input
+ className="h-7 text-xs"
+ placeholder={placeholder}
+ value={val}
+ onChange={(e) => setVal(e.target.value)}
+ onClick={(e) => e.stopPropagation()}
+ onBlur={() => {
+ const v = val.trim();
+ if (v === initialAlias) return;
+ onCommit(v);
+ }}
+ />
+ );
+};
+
export function VersionDialog({
hideModal,
}: IModalProps<any> & { initialName?: string; title?: ReactNode }) {
const { t } = useTranslation();
+ const { id: canvasId } = useParams();
const { data, loading } = useFetchVersionList();
const [selectedId, setSelectedId] = useState<string>('');
const {
@@ -43,9 +99,27 @@ export function VersionDialog({
loading: versionLoading,
isError: versionLoadFailed,
} = useFetchVersion(selectedId);
+ const [aliasFilter, setAliasFilter] = useState('');
+ const [pending, setPending] = useState<PendingAction>(null);
+
+ const { deleteVersion, loading: deleting } = useDeleteVersion();
+ const { setAgent, loading: restoring } = useSetAgent(false);
+ const { updateVersion } = useUpdateVersion();
+
+ // Backend returns the list newest-first (design section 7/E1); the first
+ // entry is therefore the latest version and every other entry is an older
+ // snapshot. Non-latest versions get a D1/D2/D3 `!` marker.
+ const latestId = data[0]?.id;
+
+ // A2/F1: alias filtering is a pure front-end filter over the returned set.
+ const filtered = useMemo(() => {
+ const q = aliasFilter.trim().toLowerCase();
+ if (!q) return data;
+ return data.filter((x) => (x.alias ?? '').toLowerCase().includes(q));
+ }, [data, aliasFilter]);
const { page, pageSize, onPaginationChange, pagedList } =
- useClientPagination(data);
+ useClientPagination(filtered);
const handleClick = useCallback(
(id: string) => () => {
@@ -60,6 +134,35 @@ export function VersionDialog({
}
}, [agent?.dsl, agent?.title]);
+ const runPending = useCallback(async () => {
+ if (!pending || !canvasId) return;
+ if (pending.kind === 'delete') {
+ // deleteVersion resolves to a success boolean (code === 0). Only drop the
+ // selection on success, so a failed delete keeps the current version
+ // selected for retry instead of silently clearing the preview.
+ const ok = await deleteVersion({
+ canvasId,
+ versionId: pending.versionId,
+ });
+ if (ok && selectedId === pending.versionId) setSelectedId('');
+ } else if (pending.kind === 'restore') {
+ await setAgent({
+ id: canvasId,
+ dsl: agent?.dsl,
+ title: agent?.title,
+ });
+ }
+ setPending(null);
+ }, [
+ pending,
+ canvasId,
+ deleteVersion,
+ selectedId,
+ setAgent,
+ agent?.dsl,
+ agent?.title,
+ ]);
+
// Keep the current selection across list refreshes; only fall back to the
// newest version when the selected one was pruned server-side.
useEffect(() => {
@@ -78,24 +181,62 @@ export function VersionDialog({
</DialogHeader>
<section className="flex gap-8 relative min-w-0">
<div className="w-72 shrink-0 max-h-[60vh] overflow-auto min-h-[40vh]">
+ <Input
+ className="mb-3"
+ placeholder={t('flow.version.filterByAlias')}
+ value={aliasFilter}
+ onChange={(e) => setAliasFilter(e.target.value)}
+ />
{loading ? (
<Spin className="top-1/2"></Spin>
) : (
<ul className="space-y-4 text-sm">
- {pagedList.map((x) => (
- <li
- key={x.id}
- className={cn('cursor-pointer p-2', {
- 'bg-card rounded-md ': x.id === selectedId,
- })}
- onClick={handleClick(x.id)}
- >
- <div className="flex items-center gap-2">
- <span className="truncate min-w-0">{x.title}</span>
- {x.release && <Dot></Dot>}
- </div>
- </li>
- ))}
+ {pagedList.map((x) => {
+ const isLatest = x.id === latestId;
+ return (
+ <li
+ key={x.id}
+ className={cn('cursor-pointer p-2', {
+ 'bg-card rounded-md ': x.id === selectedId,
+ })}
+ onClick={handleClick(x.id)}
+ >
+ <div className="flex items-center gap-2">
+ <span className="truncate min-w-0">{x.title}</span>
+ {x.release && <Dot></Dot>}
+ {!isLatest && (
+ <AntToolTip
+ title={t('flow.version.outdated')}
+ trigger="click"
+ >
+ <span className="text-destructive font-bold">
+ !
+ </span>
+ </AntToolTip>
+ )}
+ </div>
+ <div className="mt-1">
+ {/* Editable alias (design G2, section 4.4): PATCHes the
+ version metadata without creating a new version or touching the DSL.
+ Clicking the input must not also select the row. Controlled via AliasInput
+ so re-renders never wipe in-progress keystrokes. */}
+ <AliasInput
+ placeholder={t('flow.version.alias')}
+ versionId={x.id}
+ canvasId={canvasId ?? ''}
+ initialAlias={x.alias ?? ''}
+ onCommit={(alias) =>
+ updateVersion({
+ canvasId: canvasId ?? '',
+ versionId: x.id,
+ alias,
+ })
+ }
+ />
+ </div>
+ </li>
+ );
+ })}
</ul>
)}
</div>
@@ -111,7 +252,7 @@ export function VersionDialog({
<CardContent className="h-full p-5 flex flex-col">
<section className="flex justify-between gap-2 pb-2">
<div className="min-w-0">
- <div className="flex min-w-0">
+ <div className="flex min-w-0 items-center">
<span className="pb-1 truncate">{agent?.title}</span>
{agent?.release && (
<RAGFlowTooltip tooltip={t('flow.productionTooltip')}>
@@ -123,6 +264,16 @@ export function VersionDialog({
</Button>
</RAGFlowTooltip>
)}
+ {selectedId !== latestId && (
+ <AntToolTip
+ title={t('flow.version.outdated')}
+ trigger="click"
+ >
+ <span className="ml-2 text-destructive font-bold cursor-help">
+ !
+ </span>
+ </AntToolTip>
+ )}
</div>
<p className="text-text-secondary text-xs">
{t('flow.version.created')}:{' '}
@@ -130,17 +281,54 @@ export function VersionDialog({
</p>
</div>
- <Button variant={'ghost'} onClick={downloadFile}>
- <ArrowDownToLine />
- </Button>
+ <div className="flex items-center gap-2">
+ <Button
+ variant={'ghost'}
+ onClick={downloadFile}
+ title={t('flow.version.download')}
+ >
+ <ArrowDownToLine />
+ </Button>
+ <Button
+ variant={'ghost'}
+ onClick={() =>
+ setPending({
+ kind: 'restore',
+ versionId: selectedId,
+ title: agent?.title ?? '',
+ })
+ }
+ title={t('flow.version.restore')}
+ disabled={
+ selectedId === latestId || !selectedId || restoring
+ }
+ >
+ <RotateCcw />
+ </Button>
+ <Button
+ variant={'ghost'}
+ className="text-destructive"
+ onClick={() =>
+ setPending({
+ kind: 'delete',
+ versionId: selectedId,
+ title: agent?.title ?? '',
+ })
+ }
+ title={t('flow.version.delete')}
+ disabled={!selectedId || deleting}
+ >
+ <Trash2 />
+ </Button>
+ </div>
</section>
<section className="relative flex-1">
- <ReactFlowProvider key={`flow-${selectedId}`}>
+ <ReactFlowProvider key={'flow-' + selectedId}>
<ReactFlow
connectionMode={ConnectionMode.Loose}
- nodes={agent?.dsl.graph?.nodes || []}
+ nodes={agent?.dsl?.graph?.nodes || []}
edges={
- agent?.dsl.graph?.edges.flatMap((x) => ({
+ agent?.dsl?.graph?.edges?.flatMap((x) => ({
...x,
type: 'default',
})) || []
@@ -168,12 +356,49 @@ export function VersionDialog({
</div>
</section>
<RAGFlowPagination
- total={data.length}
+ total={filtered.length}
current={page}
pageSize={pageSize}
onChange={onPaginationChange}
></RAGFlowPagination>
</DialogContent>
+
+ <AlertDialog
+ open={!!pending}
+ onOpenChange={(open) => {
+ if (!open) setPending(null);
+ }}
+ >
+ <AlertDialogContent>
+ <AlertDialogHeader>
+ <AlertDialogTitle>
+ {pending?.kind === 'delete'
+ ? t('flow.version.deleteConfirmTitle')
+ : t('flow.version.restoreConfirmTitle')}
+ </AlertDialogTitle>
+ <AlertDialogDescription>
+ {pending?.kind === 'delete'
+ ? t('flow.version.deleteConfirmContent')
+ : t('flow.version.restoreConfirmContent')}
+ </AlertDialogDescription>
+ </AlertDialogHeader>
+ <AlertDialogFooter>
+ <AlertDialogCancel>{t('common.cancel')}</AlertDialogCancel>
+ <AlertDialogAction
+ onClick={runPending}
+ className={
+ pending?.kind === 'delete'
+ ? 'bg-destructive hover:bg-destructive'
+ : ''
+ }
+ >
+ {pending?.kind === 'delete'
+ ? t('flow.version.delete')
+ : t('flow.version.restore')}
+ </AlertDialogAction>
+ </AlertDialogFooter>
+ </AlertDialogContent>
+ </AlertDialog>
</Dialog>
);
}
diff --git a/web/src/pages/dataset/dataset/change-parser-dialog.test.tsx b/web/src/pages/dataset/dataset/change-parser-dialog.test.tsx
index d5767e42d0..1854c82f7f 100644
--- a/web/src/pages/dataset/dataset/change-parser-dialog.test.tsx
+++ b/web/src/pages/dataset/dataset/change-parser-dialog.test.tsx
@@ -39,6 +39,12 @@ jest.mock('@/hooks/use-agent-request', () => ({
dsl: isBuiltin ? mockBuiltinDsl : mockCustomDsl,
loading: false,
}),
+ // The version selector in DocumentPipelineDialog lists canvas versions;
+ // these tests do not exercise version pinning, so an empty list suffices.
+ useFetchCanvasVersionList: (_id?: string) => ({
+ data: [],
+ loading: false,
+ }),
}));
jest.mock('@/hooks/use-document-request', () => ({
useRunDocument: () => ({ runDocumentByIds: mockRun, loading: false }),
diff --git a/web/src/pages/dataset/dataset/change-parser-dialog.tsx b/web/src/pages/dataset/dataset/change-parser-dialog.tsx
index ac056d8dff..1021c6bef5 100644
--- a/web/src/pages/dataset/dataset/change-parser-dialog.tsx
+++ b/web/src/pages/dataset/dataset/change-parser-dialog.tsx
@@ -20,6 +20,7 @@ export function ChangeParserDialog({
<DocumentPipelineDialog
parserId={record.chunk_method}
pipelineId={record.pipeline_id}
+ pipelineVersionId={record.pipeline_version_id}
parserConfig={record.parser_config}
onOk={onOk}
hideModal={hideModal}
diff --git a/web/src/pages/dataset/dataset/parsing-status-cell.test.tsx b/web/src/pages/dataset/dataset/parsing-status-cell.test.tsx
index 863a5c775d..0f2722ab0e 100644
--- a/web/src/pages/dataset/dataset/parsing-status-cell.test.tsx
+++ b/web/src/pages/dataset/dataset/parsing-status-cell.test.tsx
@@ -22,7 +22,8 @@ jest.mock('./use-run-document', () => ({
}));
import { IngestionTaskStatus } from './constant';
-import { ParsingStatusCell } from './parsing-status-cell';
+import { ParseDropdownButton, ParsingStatusCell } from './parsing-status-cell';
+import { TooltipProvider } from '@/components/ui/tooltip';
const baseRecord = {
id: 'doc-1',
@@ -217,4 +218,42 @@ describe('ParsingStatusCell', () => {
expect(mockShowReparseDialog).toHaveBeenCalledTimes(1);
expect(mockRunDocumentByIds).not.toHaveBeenCalled();
});
+
+ // The outdated bang (design D1/D2/D3) lives in the parser dropdown button,
+ // so it is covered here against ParseDropdownButton.
+ function renderDropdown(overrides: Record<string, any> = {}) {
+ const record = { ...baseRecord, ...overrides } as any;
+ return render(
+ React.createElement(
+ TooltipProvider,
+ null,
+ React.createElement(ParseDropdownButton, {
+ record,
+ showChangeParserModal: jest.fn(),
+ }),
+ ),
+ { wrapper: StrictMode },
+ );
+ }
+
+ it('shows the outdated bang when the pinned pipeline version is not the latest', () => {
+ renderDropdown({
+ pipeline_id: 'canvas-1',
+ pipeline_version_outdated: true,
+ });
+ const bang = screen.getByText('!');
+ expect(bang).toBeInTheDocument();
+ expect(bang).toHaveClass('text-destructive');
+ });
+
+ it('hides the outdated bang for up-to-date or unpinned documents', () => {
+ renderDropdown({
+ pipeline_id: 'canvas-1',
+ pipeline_version_outdated: false,
+ });
+ expect(screen.queryByText('!')).not.toBeInTheDocument();
+
+ renderDropdown({ pipeline_id: '', pipeline_version_outdated: false });
+ expect(screen.queryByText('!')).not.toBeInTheDocument();
+ });
});
diff --git a/web/src/pages/dataset/dataset/parsing-status-cell.tsx b/web/src/pages/dataset/dataset/parsing-status-cell.tsx
index 7974b4c3a6..e38fd8aa2d 100644
--- a/web/src/pages/dataset/dataset/parsing-status-cell.tsx
+++ b/web/src/pages/dataset/dataset/parsing-status-cell.tsx
@@ -13,6 +13,7 @@ import {
TooltipContent,
TooltipTrigger,
} from '@/components/ui/tooltip';
+import { RAGFlowTooltip } from '@/components/ui/tooltip';
import { IDocumentInfo } from '@/interfaces/database/document';
import { cn } from '@/lib/utils';
import { CircleQuestionMark, CircleX, Clock3, Loader2 } from 'lucide-react';
@@ -82,7 +83,7 @@ export function ParseDropdownButton({
return (
<DropdownMenu>
<DropdownMenuTrigger asChild>
- <div>
+ <div className="flex items-center gap-1">
<Tooltip>
<TooltipTrigger asChild>
<Button variant="static" size="auto">
@@ -93,6 +94,11 @@ export function ParseDropdownButton({
<p>{parserLabel}</p>
</TooltipContent>
</Tooltip>
+ {record.pipeline_version_outdated ? (
+ <RAGFlowTooltip tooltip={t('flow.version.outdated')}>
+ <span className="text-destructive cursor-help font-bold">!</span>
+ </RAGFlowTooltip>
+ ) : null}
</div>
</DropdownMenuTrigger>
<DropdownMenuContent>
diff --git a/web/src/pages/dataset/dataset/use-change-document-parser.test.tsx b/web/src/pages/dataset/dataset/use-change-document-parser.test.tsx
new file mode 100644
index 0000000000..3670f45e30
--- /dev/null
+++ b/web/src/pages/dataset/dataset/use-change-document-parser.test.tsx
@@ -0,0 +1,58 @@
+import { renderHook, act } from '@testing-library/react';
+import React from 'react';
+
+jest.mock('react-i18next', () => ({
+ useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+const mockInvalidate = jest.fn();
+const mockSet = jest.fn().mockResolvedValue(0);
+const mockRun = jest.fn().mockResolvedValue(undefined);
+
+jest.mock('@tanstack/react-query', () => ({
+ useQueryClient: () => ({ invalidateQueries: mockInvalidate }),
+}));
+
+jest.mock('@/hooks/use-document-request', () => ({
+ useSetDocumentPipelineParser: () => ({
+ setDocumentPipelineParser: mockSet,
+ loading: false,
+ }),
+ useRunDocument: () => ({ runDocumentByIds: mockRun }),
+ DocumentKeys: { all: () => ['fetchDocumentList'] },
+}));
+
+import { DocumentKeys } from '@/hooks/use-document-request';
+import { useChangeDocumentParser } from './use-change-document-parser';
+
+const record = {
+ id: 'doc-1',
+ dataset_id: 'dataset-1',
+ name: 'doc.pdf',
+ chunk_count: 0,
+ pipeline_id: 'canvas-1',
+ pipeline_version_id: '',
+} as any;
+
+const saveBody = {
+ parser_id: '',
+ pipeline_id: 'canvas-1',
+ pipeline_version_id: 'v1',
+ parser_config: {},
+ parse_type: 'pipeline',
+} as any;
+
+describe('useChangeDocumentParser invalidates the document list after save (R2)', () => {
+ it('refetches the document list so the reopened dialog shows the pinned version', async () => {
+ const { result } = renderHook(() => useChangeDocumentParser());
+ act(() => {
+ result.current.showChangeParserModal(record);
+ });
+ await act(async () => {
+ await result.current.onChangeParserOk(saveBody);
+ });
+ expect(mockInvalidate).toHaveBeenCalledWith({
+ queryKey: DocumentKeys.all(),
+ });
+ });
+});
diff --git a/web/src/pages/dataset/dataset/use-change-document-parser.ts b/web/src/pages/dataset/dataset/use-change-document-parser.ts
index 267a43e475..55ca8804ca 100644
--- a/web/src/pages/dataset/dataset/use-change-document-parser.ts
+++ b/web/src/pages/dataset/dataset/use-change-document-parser.ts
@@ -3,7 +3,9 @@ import { useSetModalState } from '@/hooks/common-hooks';
import {
useRunDocument,
useSetDocumentPipelineParser,
+ DocumentKeys,
} from '@/hooks/use-document-request';
+import { useQueryClient } from '@tanstack/react-query';
import { IDocumentInfo } from '@/interfaces/database/document';
import { IChangeParserRequestBody } from '@/interfaces/request/document';
import { useCallback, useState } from 'react';
@@ -11,6 +13,7 @@ import { useTranslation } from 'react-i18next';
export const useChangeDocumentParser = () => {
const { t } = useTranslation();
+ const queryClient = useQueryClient();
const { setDocumentPipelineParser, loading } = useSetDocumentPipelineParser();
const { runDocumentByIds } = useRunDocument();
const [record, setRecord] = useState<IDocumentInfo>({} as IDocumentInfo);
@@ -29,12 +32,16 @@ export const useChangeDocumentParser = () => {
const ret = await setDocumentPipelineParser({
parserId: parserConfigInfo.parser_id,
pipelineId: parserConfigInfo.pipeline_id || '',
+ pipelineVersionId: parserConfigInfo.pipeline_version_id || '',
documentId: record?.id,
datasetId: record?.dataset_id,
parserConfig: parserConfigInfo.parser_config,
parse_type: parserConfigInfo.parse_type,
});
if (ret === 0) {
+ // Refresh the document list so the reopened dialog reflects the newly
+ // pinned version instead of the stale record (design section 8).
+ queryClient.invalidateQueries({ queryKey: DocumentKeys.all() });
hideChangeParserModal();
if (record.chunk_count > 0) {
Modal.confirm({
diff --git a/web/src/pages/dataset/setting/form-schema.ts b/web/src/pages/dataset/setting/form-schema.ts
index 0cdc21046a..238a55953a 100644
--- a/web/src/pages/dataset/setting/form-schema.ts
+++ b/web/src/pages/dataset/setting/form-schema.ts
@@ -8,6 +8,9 @@ export const formSchema = z
.object({
parse_type: z.nativeEnum(ParseType).optional(),
pipeline_id: z.string().optional(),
+ // Pinned dataflow canvas version (design section 5/C2). Empty means
+ // track the canvas latest version.
+ pipeline_version_id: z.string().optional(),
name: z.string().min(1, {
message: 'Username must be at least 2 characters.',
}),
diff --git a/web/src/pages/dataset/setting/hooks.test.tsx b/web/src/pages/dataset/setting/hooks.test.tsx
index c174217752..87db0369ff 100644
--- a/web/src/pages/dataset/setting/hooks.test.tsx
+++ b/web/src/pages/dataset/setting/hooks.test.tsx
@@ -90,3 +90,61 @@ describe('useSaveDatasetSetting parser_config metadata scoping', () => {
});
});
});
+
+describe('useSaveDatasetSetting pipeline_version_id passthrough', () => {
+ beforeEach(() => {
+ mockUseUpdateKnowledge.mockReset();
+ });
+
+ function setup() {
+ const saveKnowledgeConfiguration = jest.fn();
+ mockUseUpdateKnowledge.mockReturnValue({
+ saveKnowledgeConfiguration,
+ loading: false,
+ } as never);
+ const {
+ result: { current },
+ } = renderHook(() => useSaveDatasetSetting());
+ return { handleSave: current.handleSave, saveKnowledgeConfiguration };
+ }
+
+ it('passes a pinned pipeline_version_id through in pipeline mode', async () => {
+ const { handleSave, saveKnowledgeConfiguration } = setup();
+
+ await handleSave({
+ parse_type: 2,
+ pipeline_id: 'canvas-1',
+ pipeline_version_id: 'v-1',
+ } as never);
+
+ const payload = saveKnowledgeConfiguration.mock.calls[0][0];
+ expect(payload.pipeline_version_id).toBe('v-1');
+ });
+
+ it('keeps an explicit empty pipeline_version_id (track latest)', async () => {
+ const { handleSave, saveKnowledgeConfiguration } = setup();
+
+ await handleSave({
+ parse_type: 2,
+ pipeline_id: 'canvas-1',
+ pipeline_version_id: '',
+ } as never);
+
+ const payload = saveKnowledgeConfiguration.mock.calls[0][0];
+ expect(payload.pipeline_version_id).toBe('');
+ });
+
+ it('drops pipeline_version_id in built-in mode', async () => {
+ const { handleSave, saveKnowledgeConfiguration } = setup();
+
+ await handleSave({
+ parse_type: 1,
+ parser_id: 'naive',
+ pipeline_version_id: 'v-1',
+ } as never);
+
+ const payload = saveKnowledgeConfiguration.mock.calls[0][0];
+ expect(payload.pipeline_version_id).toBeUndefined();
+ expect(payload.pipeline_id).toBeUndefined();
+ });
+});
diff --git a/web/src/pages/dataset/setting/hooks.ts b/web/src/pages/dataset/setting/hooks.ts
index 827a00ad76..ccbeb51050 100644
--- a/web/src/pages/dataset/setting/hooks.ts
+++ b/web/src/pages/dataset/setting/hooks.ts
@@ -62,6 +62,7 @@ export const useFetchDatasetSettingOnMount = (
'pagerank',
'avatar',
'pipeline_id',
+ 'pipeline_version_id',
'parser_id',
]),
embedding_model: knowledgeDetails.embedding_model,
@@ -69,6 +70,9 @@ export const useFetchDatasetSettingOnMount = (
parse_type: knowledgeDetails.pipeline_id
? ParseType.Pipeline
: ParseType.BuiltIn,
+ // Backfill the pinned version (design section 5/C2); an absent pin
+ // renders as the empty (track latest) form value.
+ pipeline_version_id: knowledgeDetails.pipeline_version_id ?? '',
parser_config: formParserConfig,
} as z.infer<typeof formSchema>;
form.reset(formValues);
@@ -108,6 +112,9 @@ export const useSaveDatasetSetting = () => {
if (payload.parse_type === ParseType.BuiltIn) {
payload.pipeline_id = undefined;
+ // A version pin only exists for a dataflow pipeline; drop it in
+ // built-in mode so no stale canvas version is submitted.
+ payload.pipeline_version_id = undefined;
} else {
payload.parser_id = undefined;
}
diff --git a/web/src/pages/dataset/setting/index.tsx b/web/src/pages/dataset/setting/index.tsx
index 1d5c4fc68c..ac0c02fa1e 100644
--- a/web/src/pages/dataset/setting/index.tsx
+++ b/web/src/pages/dataset/setting/index.tsx
@@ -45,6 +45,9 @@ import {
useSaveDatasetSetting,
} from './hooks';
import { normalizeParserConfigForComparison } from './parser-config';
+import { PipelineVersionSelect } from '@/components/pipeline-version-select';
+import { RAGFlowTooltip } from '@/components/ui/tooltip';
+import { useFetchCanvasVersionList } from '@/hooks/use-agent-request';
import { useRevealSubmitErrors } from './use-reveal-submit-errors';
export default function DatasetSetting() {
@@ -94,6 +97,11 @@ export default function DatasetSetting() {
name: 'pipeline_id',
defaultValue: '',
});
+ const pipelineVersionId = useWatch({
+ control: form.control,
+ name: 'pipeline_version_id',
+ defaultValue: '',
+ });
const builtinPipelineId = useWatch({
control: form.control,
@@ -120,6 +128,33 @@ export default function DatasetSetting() {
: knowledgeDetails?.parser_id
: undefined;
+ // Published versions of the selected dataflow canvas (design C1/C2).
+ const { data: canvasVersions } = useFetchCanvasVersionList(
+ parseType === ParseType.Pipeline && pipelineId ? pipelineId : undefined,
+ );
+ // Show the outdated bang only while the form still holds the SAVED pin:
+ // once the user picks a different (unsaved) version the bang would be
+ // misleading (design D3: hint only, never auto-upgrade).
+ const savedVersionOutdated =
+ !!knowledgeDetails?.pipeline_version_outdated &&
+ (pipelineVersionId ?? '') === (knowledgeDetails?.pipeline_version_id ?? '');
+
+ // Design section 8 (T37): an unpinned dataset must still pre-select the latest
+ // concrete canvas version instead of the "Latest version" placeholder. We only
+ // fill an empty field, so a saved pin or a user selection wins. This effect
+ // runs after the on-mount form.reset (which sets an unpinned dataset to ''),
+ // so the latest concrete id wins once the version list resolves.
+ useEffect(() => {
+ const savedPin = knowledgeDetails?.pipeline_version_id;
+ if (
+ !savedPin &&
+ canvasVersions?.length &&
+ !form.getValues('pipeline_version_id')
+ ) {
+ form.setValue('pipeline_version_id', canvasVersions[0].id);
+ }
+ }, [knowledgeDetails, canvasVersions, form]);
+
const { operatorNodes, loading: operatorNodesLoading } =
usePipelineOperatorNodes(
selectedPipelineId,
@@ -136,6 +171,17 @@ export default function DatasetSetting() {
operatorNodes,
);
+ // A pinned version belongs to the canvas it was pinned on (design section
+ // 5/B4 sticky snapshot). Switching the dataflow canvas invalidates any
+ // previously pinned version, so clear it; otherwise a version id from the
+ // old canvas would be submitted against the new pipeline. The initial load
+ // keeps the saved version (selected equals saved).
+ useEffect(() => {
+ if (selectedPipelineId !== savedPipelineId) {
+ form.setValue('pipeline_version_id', '');
+ }
+ }, [selectedPipelineId, savedPipelineId, form]);
+
const { activeTab, setActiveTab } = useActiveTab(operatorNodes);
const { scrollContainerRef, handleInvalidSubmit } =
@@ -285,6 +331,42 @@ export default function DatasetSetting() {
</div>
</div>
</FormItem>
+ {parseType === ParseType.Pipeline && !!pipelineId && (
+ <FormItem className="items-center space-y-0">
+ <div className="flex items-center gap-1">
+ <FormLabel className="text-sm text-text-secondary whitespace-wrap w-1/4">
+ {t('flow.version.label')}
+ </FormLabel>
+ <div className="text-muted-foreground w-3/4">
+ <FormField
+ control={form.control}
+ name="pipeline_version_id"
+ render={({ field }) => (
+ <FormItem className="space-y-1">
+ <div className="flex items-center gap-2">
+ <PipelineVersionSelect
+ versions={canvasVersions}
+ value={field.value ?? ''}
+ onChange={field.onChange}
+ />
+ {savedVersionOutdated && (
+ <RAGFlowTooltip
+ tooltip={t('flow.version.outdated')}
+ >
+ <span className="text-destructive cursor-help font-bold">
+ !
+ </span>
+ </RAGFlowTooltip>
+ )}
+ </div>
+ <FormMessage />
+ </FormItem>
+ )}
+ />
+ </div>
+ </div>
+ </FormItem>
+ )}
{showOperatorTabs && (
<PipelineOperatorTabs
nodes={operatorNodes}
diff --git a/web/src/services/agent-service.ts b/web/src/services/agent-service.ts
index 4a129dfee6..d4606ef19f 100644
--- a/web/src/services/agent-service.ts
+++ b/web/src/services/agent-service.ts
@@ -37,6 +37,8 @@ const {
trace,
fetchVersionList,
fetchVersion,
+ deleteVersion,
+ updateVersion: updateVersionApi,
getAgent,
fetchAgentSessions,
fetchExternalAgentInputs,
@@ -65,6 +67,15 @@ const methods = {
fetchVersion(config.agentId, config.versionId),
method: 'get',
},
+ deleteVersion: {
+ url: deleteVersion,
+ method: 'delete',
+ },
+ updateVersion: {
+ url: (config: { agentId: string; versionId: string }) =>
+ updateVersionApi(config.agentId, config.versionId),
+ method: 'put',
+ },
listAgents: {
url: listAgents,
method: 'get',
@@ -161,11 +172,24 @@ export const updateAgent = (
description?: string | null;
permission?: string;
release?: string;
+ autosave?: boolean;
+ alias?: string;
},
) => {
return request(updateAgentApi(agentId), { method: 'put', data: params });
};
+export const updateVersion = (
+ agentId: string,
+ versionId: string,
+ params: { alias?: string; title?: string; description?: string },
+) => {
+ return request(updateVersionApi(agentId, versionId), {
+ method: 'patch',
+ data: params,
+ });
+};
+
export const updateAgentTags = (agentId: string, tags: string[]) => {
return request(api.updateAgentTags(agentId), {
method: 'put',
diff --git a/web/src/utils/api.ts b/web/src/utils/api.ts
index 6c41060c56..76566ca43c 100644
--- a/web/src/utils/api.ts
+++ b/web/src/utils/api.ts
@@ -366,6 +366,10 @@ export default {
fetchVersionList: (id: string) => `${restAPIv1}/agents/${id}/versions`,
fetchVersion: (agentId: string, versionId: string) =>
`${restAPIv1}/agents/${agentId}/versions/${versionId}`,
+ deleteVersion: (agentId: string, versionId: string) =>
+ `${restAPIv1}/agents/${agentId}/versions/${versionId}`,
+ updateVersion: (agentId: string, versionId: string) =>
+ `${restAPIv1}/agents/${agentId}/versions/${versionId}`,
getAgent: (id: string) => `${restAPIv1}/agents/${id}`,
uploadAgentFile: (id?: string) => `${restAPIv1}/agents/${id}/upload`,
createAgentSession: (agentId: string) =>