知识库历史虚拟文件夹迁移

状态：archived 类型：feature Owner：backend/package/yuxi/services/knowledge_folder_service.py

问题

历史目录上传把相对路径保存在文件 filename 中，列表据此投影虚拟文件夹。迁移属于知识库级兼容数据治理，不适合作为单个虚拟文件夹的行操作；大知识库也不能在单一 HTTP 事务中递归转换。

决策

知识库详情调用临时检测接口识别仍含路径段的文件。存在历史数据时，文件数统计卡显示 warning 图标和样式；具备管理权限的用户点击后通过弹窗启动知识库级唯一迁移任务。

任务每批扫描最多 500 条文件，每个事务在知识库目录树锁内只剥离一层路径，复用同名真实文件夹或以任务启动者作为 created_by 创建目录，再提交文件的新 parent_id 和剩余名称。SSE 只轮询并发布任务快照，连接断开不取消任务。进程中断或冲突不回滚已经提交的批次，再次启动从仍包含路径段的数据继续。

同名普通文件或重复真实文件夹阻塞对应路径，其他路径继续迁移。任务无进展时结束并在结果中报告剩余文件和冲突数。迁移不改变文件 ID、对象路径、Markdown、Chunk 或向量身份。

替代方案

• 在虚拟文件夹行上逐个转换：无法表达知识库整体迁移进度，拒绝。
• SSE 请求自身执行迁移：连接断开会拥有并取消工作，拒绝。
• 单事务递归转换全部路径：锁持有和失败回滚范围无界，拒绝。

后果

迁移允许部分完成且可重复执行，数据库已提交批次是恢复事实。检测接口和 warning 卡在剩余路径归零后消失。新的目录上传自动实体化仍由路径型目录实体化提案跟踪。

验证

• 真实 HTTP/PostgreSQL integration 在不建立 SSE 的情况下启动任务，回读多层共享父目录、转换者、任务结果和归零后的检测结果；任务不由进度连接拥有。
• 真实 HTTP/PostgreSQL 负向 integration 注入同名普通文件，证明其他路径已提交、冲突路径保留且重跑只处理剩余事实。
• integration 读取终态 SSE 快照，证明进度端点绑定正确知识库任务。
• 前端 API unit、lint 和 build 通过；真实页面截图尚未执行。