docs(mvp): organize mvp documentation

2026-07-09 13:40:08 +08:00
parent 9c9a0024d4
commit 841437fa06
57 changed files with 452 additions and 675 deletions
@@ -0,0 +1,49 @@
+# RAG 上传切片参数未真正生效
+
+**状态**：待规划  
+**严重程度**：低  
+**发现时间**：2026-07-04  
+**范围**：文档上传接口、切片配置、API 行为一致性
+
+---
+
+## 现象
+
+上传接口暴露了 `chunkSize` 和 `chunkOverlap` 参数，但实际切片主要使用全局 `DocumentChunkConfig`。这会造成 API 表面能力和真实行为不一致。
+
+---
+
+## 当前实现
+
+- `DocumentController` 的上传接口接收 `chunkSize` 和 `chunkOverlap`。
+- 这些字段会进入 `DocumentUploadRequest`。
+- `DocumentChunkService` 的切片阈值主要来自 `DocumentChunkConfig`。
+- 单次上传请求中的参数没有真正覆盖切片配置。
+
+---
+
+## 影响
+
+- 调用方以为可以控制切片大小，但实际无法影响结果。
+- 测试时容易误判“参数调优无效”的原因。
+- 面试中如果展示 API，会被追问参数是否真实生效。
+
+---
+
+## 建议修复
+
+两个方向二选一：
+
+1. 如果 MVP 不需要请求级切片参数，就从接口中移除或标记为暂不支持。
+2. 如果需要支持，就让 `DocumentChunkService` 接收 per-request chunk options，并记录到文档 metadata 中。
+
+建议面试项目中优先选择第二种，因为它更能体现工程闭环：API、配置、落库、追踪一致。
+
+---
+
+## 相关文件
+
+- `src/main/java/com/superbiz/agent/controller/DocumentController.java`
+- `src/main/java/com/superbiz/agent/service/DocumentManagementService.java`
+- `src/main/java/com/superbiz/agent/service/DocumentChunkService.java`
+- `src/main/java/com/superbiz/agent/config/DocumentChunkConfig.java`