feat(wiki): 知识库扫描源实体化 wiki_kb_source —— 路径别名分组、单路径扫描与按源定时增量同步

[ncw1992120]

背景与动机

Wiki 知识库目前的文件接入方式是单一的 sourceDirectory（已支持多行路径/glob）+ KB 级 watcher。在实际运营场景中（例如：多个爬虫定时落盘到不同服务器目录，分别对应不同业务来源），暴露出三个缺口：

1. 路径没有身份 —— 多条路径混在一个换行分隔的文本字段里，无法命名（业务别名）、无法单独启停、无法单独触发扫描；
2. 材料没有归属 —— wiki_raw_material 不记录文件来自哪条路径，前端无法按来源分组展示、无法按来源批量运维（重扫/清理某一来源）；
3. 定时粒度太粗 —— watcher 只有 KB 级开关和全局间隔，无法为不同路径配置不同的同步计划（例如处罚公告每日 02:00、系统文档每周一次）。

我们团队已完成这一功能的完整前端交互设计（原型 + 需求文档，见 fork 分支 feat/wiki-raw-material-panel 的 wiki-improve/ 目录，含搜索/筛选/分组折叠/批量操作/异常分区/在线预览），前端部分将按单一关注点拆成独立 PR 提交。本 issue 提议补齐对应的后端实体，达成一致后我们来实现。

方案：扫描源实体化 wiki_kb_source

表结构

列	类型	说明
id	BIGINT（雪花）
kb_id	BIGINT	所属知识库
alias	VARCHAR(128)	业务别名，同 KB 内唯一
path	VARCHAR(1024)	单条路径或 glob（多路径 = 多条 source 记录）
file_filter	VARCHAR(256)	可空；逗号分隔 glob（*.pdf, *.txt）
cron	VARCHAR(64)	可空；空 = 不定时
enabled	TINYINT/SMALLINT	定时开关
create_time / update_time / deleted		通用约定

wiki_raw_material 增加两列：

• source_id（可空，不可变）：文件的客观出处；手动上传/粘贴文本为 NULL；
• group_override_id（可空）：用户手动"迁移分组"改这一列，展示分组 = COALESCE(group_override_id, source_id)。

为什么两列而不是一列：如果迁移分组直接改 source_id，出处信息被销毁，且与增量扫描的按路径去重产生歧义（迁走的文件下次扫描是否重新归入原组？）。出处与组织方式分离后，迁移不影响去重判断。

两条设计约束

1. 定时任务只做增量扫描，不提供"定时全量"。全量重扫 = 手动动作（扫描 + 对该 source 下已有材料批量 reprocess）。理由：全量意味着对目录下所有文件重跑 LLM 消化，放进 cron 是纯粹的 token 燃烧器。因此表中不设 scan_mode 列，模式仅作为手动扫描接口的参数。
2. 路径校验复用 WikiSourcePathValidator（符号链接逃逸检查等），扫描复用 WikiDirectoryScanService 的既有去重（按解析后绝对路径跳过已存在文件，即天然增量）。

API

GET    /api/v1/wiki/knowledge-bases/{kbId}/sources           列表（含每 source 文件数统计）
POST   /api/v1/wiki/knowledge-bases/{kbId}/sources           创建
PUT    /api/v1/wiki/knowledge-bases/{kbId}/sources/{sid}     更新
DELETE /api/v1/wiki/knowledge-bases/{kbId}/sources/{sid}     删除（材料保留，source_id 置空）
POST   /api/v1/wiki/knowledge-bases/{kbId}/sources/{sid}/scan?mode=incr|full   单路径扫描
PUT    /api/v1/wiki/knowledge-bases/{kbId}/raws/group        批量迁移分组 {rawIds, targetSourceId}

• 权限：全部 manage:wiki，与现有扫描一致
• 定时：扩展 WikiSourceWatcherService（ShedLock，锁粒度按 source），全局 watcher 开关继续作为总闸

兼容性

• 存量 sourceDirectory 保持可用；迁移脚本将非空的 sourceDirectory 按行拆为 source 记录（alias 默认"默认扫描路径 N"），字段标记废弃但不删除
• 迁移脚本按方言目录同版本号同步新增
• 有状态逻辑配测试（source CRUD、扫描归属写入、去重 × group_override 交互、定时增量）

分步计划

1. PR-1（前端，不依赖本 issue）：材料列表增强 — 搜索/筛选/排序/批量操作/在线预览/异常文件分区
2. PR-2（后端，本 issue）：wiki_kb_source + 归属列 + API + 定时
3. PR-3（前端接线）：路径分组配置、单路径扫描、迁移分组，按原型完整落地

如方案方向认可，PR-2/PR-3 由我们团队实现提交。

[ncw1992120]

as-built 更新：实现已落地，两处与原规格的差异（以实现为准）

实现见 fork 分支 8d0ac970（表名 mate_wiki_source_group），由我们团队的前端设计者本人完成后端。与本 issue 原方案有两处偏离，均为实现阶段发现的更优解，请按 as-built 评审：

1. 单列 group_id + 粘性规则，替代 source_id / group_override_id 两列

原方案用两列分离"出处（不可变）"与"展示分组（可迁移）"，以避免手动迁移与扫描去重的冲突。实现改为单列 group_id 配一条打标规则：

分组扫描只在 group_id 为 null 时补写归属，永不覆盖已有值（包括手动改挂的）。

手动迁移因此是"粘性"的——文件迁到 B 组后，A 组的重扫不会把它拉回去。该规则由测试 incrementalScan_skipHitAlreadyGroupedNotRetagged 锁定。代价是不保留"文件最初来自哪条路径"的出处记录，v1 可接受；如后续需要出处审计，再加只读的 origin_group_id 即可，不影响本方案。

2. 历史材料回填：不做一次性匹配脚本，靠下一次正常扫描自然补写

原方案设想迁移脚本回填归属。实现只回填分组定义（启动时幂等地把存量 sourceDirectory 按行拆成 group 记录），历史 raw 的 group_id 留给该分组下一次正常扫描时按 source_path 命中补写——避免一次性路径匹配出错的风险，且天然幂等。

其余与原方案对齐的确认

• scan_mode 不落列，仅作为手动扫描接口的 ?mode= 参数（与"定时触发只允许增量"的约束一致；当前列存在但将移除）
• 路径校验复用 WikiSourcePathValidator，去重复用既有 ingest 逻辑
• cron 调度本轮只落库不接调度器，接入时执行"cron 仅增量"约束
• 迁移版本号（V166/V167）与 upstream 现有 V166 冲突，PR 提交前将随 upstream 同步重编

分步计划不变：PR-1（前端列表增强）与 PR-2（本实现）无依赖、并行推进，PR-3 接线收尾。