docs: update all project documentation to reflect current codebase

- README.md: complete overhaul — project structure, architecture, env vars, test listing, Java/JDBC pipeline
- CLAUDE.md: fix field count (~28→~40), migrate Streamlit references to Vue 3, update known issues
- frontend/README.md: add missing StreamingMessage.vue and NodeProgress.vue components

README.md

@@ -1,44 +1,60 @@
 # JRXML 生成代理
 
-一个本地桌面应用程序，帮助非技术用户通过多轮自然语言对话创建 JasperReports 模板（JRXML）。
+一个本地桌面应用程序，通过多轮自然语言对话帮助非技术用户创建 JasperReports 模板（JRXML）。
 
 ## 功能
 
-- **多轮聊天**：通过对话优化报表 -- 添加列、更改标题、添加汇总
-- **自动验证**：每次生成或修改后都会验证 JRXML
-- **自动修正**：如果验证失败，代理会分析错误并自动修正（最多 5 次）
-- **模板检索**：使用 Chroma 向量数据库检索相关的 JRXML 示例以获得更好的生成效果
-- **文件上传**：支持图片（OCR识别）、PDF、Word、Excel、文本文件等
-- **聊天粘贴/拖拽**：支持直接在对话框中 Ctrl+V 粘贴或拖拽文件（图片/PDF/Excel/Word）
-- **单据OCR识别**：上传报表单据图片后自动提取所有字段（4策略优先级 + 置信度评分）
-- **批注检测**：识别手写单据上的圈选和箭头标记，自动定位用户要修改的字段
-- **分层精确生成**：A4 报表图片先提取布局 schema，再分 3 阶段（骨架→精调→字段映射）生成，避免 OCR 元素过多导致 prompt 溢出
-- **下载**：导出已验证的、可供 JasperReports 使用的 JRXML 文件
+- **多轮对话**：通过对话优化报表 — 添加列、更改标题、添加汇总
+- **自动验证**：每次生成或修改后验证 JRXML（结构检查 + XSD 校验 + 像素级对比）
+- **自动修正**：验证失败时分析错误并自动修正（最多 5 次）
+- **错误自增长知识库**：修正案例指纹去重入库，避免重复犯错
+- **模板检索**：ChromaDB 语义搜索 JRXML 示例和中文文档
+- **文件上传**：对话框拖拽/粘贴/选择，支持图片、PDF、Word、Excel、文本
+- **单据 OCR 识别**：上传报表图片后自动提取字段（4 策略优先级 + 置信度）
+- **批注检测**：识别手写单据上的圈选和箭头标记
+- **分层精确生成**：3 阶段管线（骨架→精调→字段映射），Band 级窗口化防止内容丢失
+- **多租户知识库**：独立 KB 管理，含字段定义 + JRXML 模板 + ChromaDB 向量检索
+- **Java 渲染管线**：JRXML → PNG 渲染 + SSIM 像素级对比
+- **下载**：导出经过验证的 JRXML 文件，含历史版本追溯
 
 ## 架构
 
 ```
 前端 (Vue 3 + Vite, 端口 5173)
-  │ 聊天界面 + SSE 流式显示 + 文件上传/粘贴/拖拽
-  ▼ HTTP + SSE
+  │ Pinia stores (chat / session / kb)
+  │ 9 components (Sidebar, ChatMessages, ProcessSection, UnifiedInput,
+  │   SummaryCard, KbSelector, KbManager, StreamingMessage, NodeProgress)
+  ▼ HTTP + SSE (Server-Sent Events)
 后端 API (FastAPI, 端口 8000)
-  │ REST 接口 + SSE 流式推送
-  │ 包装 LangGraph Agent ──► agent/
-  │   ├─ retrieve (Chroma/embeddings)
-  │   ├─ generate / generate_skeleton → refine_layout → map_fields (分层生成)
-  │   ├─ validate (FastAPI service)
-  │   ├─ explain + correct (auto-fix loop)
-  │   └─ modify (multi-turn edits)
+  │ REST + SSE 流式推送
+  │ 包装 LangGraph Agent ──► agent/ (18 节点状态机)
+  │   ├─ process_input (文件解析 + OCR + 批注检测)
+  │   ├─ manage_context (token 计数 + 压缩)
+  │   ├─ classify_intent (8 类意图识别)
+  │   ├─ retrieve (RAG + 错误 KB + KB 模板搜索)
+  │   ├─ generate / generate_skeleton → refine_layout → map_fields
+  │   ├─ validate (XSD + 结构 + 像素对比)
+  │   ├─ explain_error + correct_jrxml (自动修正循环, 最多 5 次)
+  │   └─ modify_jrxml / consult / undo / reset / preview / finalize
+  ├── backend/ 服务层
+  │   ├─ llm (Anthropic SDK / OpenAI / Ollama)
+  │   ├─ session (原子 JSON 持久化)
+  │   ├─ validation (验证服务客户端)
+  │   ├─ kb_manager / kb_parser / kb_searcher (多租户知识库)
+  │   ├─ field_matcher (OCR↔KB 字段匹配)
+  │   ├─ ocr_extractor / layout_analyzer / annotation_detector (OCR 管线)
+  │   ├─ rag_adapter / error_kb / embeddings (向量检索)
+  │   └─ file_parser / logger / jrxml_reorder
   ▼
 FastAPI 验证服务 (:8001)
-  └─ Structural checks + XSD schema validation
+  └─ 结构检查 + XSD Schema + 最小内容校验
 ```
 
 ## 前置要求
 
 - Python 3.11+
-- 完整的编译验证需要：JDK 21 + JasperReports 7.0.6
-- OpenAI 兼容的 API 密钥（或本地 Ollama）
+- JDK 21+（Java JRXML→PNG 渲染管线使用）
+- Anthropic 兼容 API 密钥（MiniMax M2.7 等）
 
 ## 快速开始
 
@@ -54,12 +70,12 @@ pip install -r requirements.txt
 cp .env.example .env
 ```
 
-编辑 `.env` 配置您的 API 密钥和偏好设置。
+编辑 `.env` 配置 API 密钥和偏好设置。
 
 ### 3. 初始化知识库
 
 ```bash
-python scripts/init_kb.py
+python scripts/init_default_kb.py
 ```
 
 ### 4. 启动服务
@@ -79,7 +95,7 @@ python -m uvicorn api_server:app --port 8000 --host 0.0.0.0
 cd frontend && npm install && npm run dev
 ```
 
-在浏览器中打开 http://localhost:5173。
+浏览器打开 `http://localhost:5173`。
 
 ## 使用示例
 
@@ -92,98 +108,132 @@ cd frontend && npm install && npm run dev
 第三轮 - 修改：
 > "将标题改为 '2024 员工目录' 并加粗"
 
-每一轮都会自动验证和修正 JRXML。
-
-## 验证服务（当前限制）
-
-由于完整的 JasperReports 7.0.6 编译需要 JDK 21，当前的验证执行以下检查：
-
-1. 结构检查：字段声明一致性、SQL 查询存在性、页面尺寸、报表名称
-2. XSD schema 验证：如果 `validation_service/schemas/jasperreport_7_0_6.xsd` 可用
-
-要进行完整的编译验证，请将 `jasper-validator.jar` 放在 `validation_service/` 目录并更新 `main.py`。
-
-## 测试
-
-```bash
-pytest tests/test_validation.py -v
-pytest tests/test_agent.py -v
-pytest tests/ -v
-```
+每一轮自动验证和修正 JRXML。上传报表图片后自动触发 OCR 识别 + 分层精确生成。
 
 ## 项目结构
 
 ```
-jrxml-agent/
-  api_server.py              FastAPI SSE 后端（REST + 流式推送）
-  start.bat                  一键启动脚本
-  stop.bat                   一键停止脚本
-  frontend/                  Vue 3 + Vite 前端（聊天 UI）
+jaspersoft/
+  api_server.py                 FastAPI SSE 后端（REST + 流式推送）
+  start.bat / stop.bat          一键启停脚本
+  start.py                      Python 启动器
+
+  agent/                        LangGraph 工作流引擎
+    state.py                    AgentState 类型定义（~40 字段）
+    nodes.py                    18 个工作流节点实现
+    graph.py                    状态图编译 + 9 个路由函数
+    datasource.py               数据源模式解析（参数 vs JDBC）
+    jrxml_windower.py           Band 级拆解/切分/重组引擎
+
+  backend/                      后端服务层
+    llm.py                      LLM 工厂（Anthropic SDK / OpenAI / Ollama）
+    logger.py                   结构化 JSON 日志（trace_id + UTC+8）
+    validation.py               验证服务 HTTP 客户端
+    session.py                  会话 JSON 原子持久化 CRUD
+    embeddings.py               嵌入模型工厂（HuggingFace / OpenAI）
+    rag_adapter.py              RAG 语义搜索适配器
+    error_kb.py                 错误自增长知识库（指纹去重 + ChromaDB）
+    file_parser.py              多格式文件解析（PDF/DOCX/XLSX/XLS/DOC/图片/文本）
+    layout_analyzer.py          A4 模板布局分析（布局 schema 提取 + 列聚类）
+    ocr_extractor.py            OCR 字段精确提取（4 策略 + 置信度）
+    annotation_detector.py      批注检测（圈选 + 箭头 + OCR 关联）
+    kb_manager.py               多租户知识库 CRUD（用户 + KB）
+    kb_parser.py                KB 解析管道（解析→chunk→embed）
+    kb_searcher.py              Per-KB ChromaDB 搜索适配器
+    field_matcher.py            OCR↔KB 字段匹配（Embedding + LLM 两阶段）
+    jrxml_reorder.py            JRXML 元素重排序（XSD sequence 合规）
+
+  prompts/                      LLM Prompt 模板（热重载）
+    loader.py                   Prompt 加载器
+    *.md                        10 个 Prompt 模板文件
+
+  frontend/                     Vue 3 + Vite 前端
     src/
-      api/client.ts           SSE 客户端 + fetch 封装
-      stores/                 Pinia 状态管理（chat + session）
-      components/             聊天界面组件（6 个）
-  agent/
-    state.py                 AgentState 定义（28 字段）
-    nodes.py                图节点（generate, generate_skeleton, refine_layout 等，18 节点）
-    graph.py                LangGraph 状态机（含分层生成路由）
-  backend/
-    llm.py                  LLM 工厂（Anthropic SDK / OpenAI / Ollama）
-    logger.py               集中日志模块（JSON + trace_id）
-    embeddings.py           嵌入模型工厂
-    validation.py           验证服务客户端
-    rag_adapter.py          RAG 语义搜索适配器
-    error_kb.py             错误自增长知识库
-    file_parser.py          文件解析器（PDF/DOCX/XLSX/XLS/DOC/图片/文本）
-    layout_analyzer.py      A4 模板布局分析（含布局 schema 提取）
-    ocr_extractor.py        OCR 字段精确提取（4 策略 + 置信度）
-    annotation_detector.py  批注检测（圈选 + 箭头 + OCR 关联）
-    session.py              会话持久化 CRUD
-  prompts/
-    loader.py               Prompt 加载器（热重载）
-    *.md                    10 个 Prompt 模板文件
-  validation_service/
-    main.py                 FastAPI 验证服务器
+      api/client.ts             SSE 客户端 + fetch 封装
+      stores/
+        chat.ts                 Pinia: 消息/流式/节点进度
+        session.ts              Pinia: 会话管理
+        kb.ts                   Pinia: 知识库状态
+      components/
+        Sidebar.vue             会话列表 + 下载 + 历史版本
+        ChatMessages.vue        消息列表渲染
+        ProcessSection.vue      过程折叠区（<details>/<summary>）
+        StreamingMessage.vue    流式消息显示
+        NodeProgress.vue        节点进度指示器
+        UnifiedInput.vue        统一输入框（文本 + 文件拖拽/粘贴/芯片）
+        SummaryCard.vue         结果摘要卡片（含耗时）
+        KbSelector.vue          KB 下拉选择器
+        KbManager.vue           KB 管理面板（上传/构建/删除）
+
+  validation_service/           独立验证服务（端口 8001）
+    main.py                     FastAPI 验证端点
+    schemas/
+      jasperreport_7_0_6.xsd   JasperReports XSD Schema
+
+  lib/java/                     Java JRXML 渲染管线
+    JrxmlRenderer.java          JRXML → PNG 渲染器
+    JrxmlDebug.java             诊断工具
+    JrxmlGen.java               参考：程序化 JasperDesign
+    jasperreports-6.21.0.jar   核心 JasperReports 库
+
+  tests/                        Python 测试（19 文件, ~385 测试）
+    test_session.py             会话 CRUD（27）
+    test_ocr_extraction.py      OCR 字段提取（49）
+    test_jrxml_windower.py      Band 窗口化（28）
+    test_api_integration.py     API 集成（25）
+    test_error_kb.py            错误 KB（24）
+    test_programmatic_map_fields.py  字段映射（20）
+    test_layered_generation.py  分层生成（19）
+    test_annotation_detector.py 批注检测（7）
+    test_validation.py          验证服务（6）
+    test_file_parser_formats.py 文件解析（4）
+    test_e2e_ocr.py             OCR E2E（3）
+    test_agent.py / test_kb_*.py /
+
   data/
-    sample_templates/       知识库的 JRXML 模板
-    corrections/            错误修正案例
-  logs/
-    app.log                 应用日志（节点流转、路由、用户交互）
-    llm.log                 LLM 调用日志（完整 prompt / response）
+    sample_templates/           JRXML 样本模板
+    corrections/                错误修正案例
+
   scripts/
-    init_default_kb.py      多租户默认知识库初始化脚本
-  tests/
-    test_validation.py      验证服务测试
-    test_agent.py           代理集成测试
-    test_e2e_ocr.py         OCR 端到端测试
-    test_ocr_extraction.py  OCR 字段提取单元测试
-    test_annotation_detector.py 批注检测测试
-    test_file_parser_formats.py 多格式解析测试
-    test_layered_generation.py 分层生成测试
-  requirements.txt
-  .env.example
-  README.md
+    init_default_kb.py          多租户默认知识库初始化
 ```
 
 ## 环境变量
 
 | 变量 | 描述 | 默认值 |
-|----------|-------------|---------|
-| LLM_BACKEND | cloud 或 local | cloud |
-| LLM_PROVIDER | openai 或 anthropic | openai |
-| OPENAI_API_KEY | API 密钥（OpenAI 或 MiniMax） | - |
-| OPENAI_BASE_URL | API 基础 URL | https://api.openai.com/v1 |
-| ANTHROPIC_API_KEY | Anthropic 兼容 API 密钥（优先） | - |
-| ANTHROPIC_BASE_URL | Anthropic 兼容 Base URL | https://api.minimaxi.com/anthropic |
-| LLM_MODEL | 模型名称 | MiniMax-M2.7 |
-| LLM_MAX_TOKENS | 默认 max_tokens（各节点可覆盖） | 8192 |
-| LOCAL_LLM_MODEL | Ollama 模型 | qwen2.5-coder:7b |
-| EMBED_BACKEND | local 或 cloud | local |
-| LOCAL_EMBED_MODEL | 嵌入模型 | Qwen/Qwen3-Embedding-0.6B |
-| VALIDATION_SERVICE_URL | 验证端点 | http://localhost:8001/validate |
-| CHROMA_PERSIST_DIR | Chroma 存储位置 | ./db/chroma |
-| MAX_RETRY | 自动修正尝试次数 | 5 |
-| CONTEXT_MAX_TOKENS | 上下文压缩阈值 | 6000 |
-| LOG_DIR | 日志目录 | ./logs |
-| LOG_LEVEL | 日志级别 | DEBUG |
-| SESSIONS_DIR | 会话持久化目录 | ./sessions |
+|------|------|--------|
+| `LLM_BACKEND` | LLM 后端: cloud / local | cloud |
+| `LLM_PROVIDER` | 云端提供商: anthropic / openai | anthropic |
+| `ANTHROPIC_API_KEY` | Anthropic 兼容 API 密钥（优先） | - |
+| `ANTHROPIC_BASE_URL` | Anthropic 兼容 Base URL | https://api.minimaxi.com/anthropic |
+| `OPENAI_API_KEY` | OpenAI 兼容 API 密钥（fallback） | - |
+| `OPENAI_BASE_URL` | OpenAI 兼容 Base URL | https://api.openai.com/v1 |
+| `LLM_MODEL` | 模型名称 | MiniMax-M2.7 |
+| `LLM_MAX_TOKENS` | 默认 max_tokens（各节点可覆盖） | 8192 |
+| `LOCAL_LLM_MODEL` | Ollama 模型 | qwen2.5-coder:7b |
+| `EMBED_BACKEND` | 嵌入模型后端: local / cloud | local |
+| `LOCAL_EMBED_MODEL` | 本地嵌入模型 | Qwen/Qwen3-Embedding-0.6B |
+| `VALIDATION_SERVICE_URL` | 验证服务端点 | http://localhost:8001/validate |
+| `CHROMA_PERSIST_DIR` | ChromaDB 持久化目录 | ./db/chroma |
+| `MAX_RETRY` | 自动修正最大尝试次数 | 5 |
+| `CONTEXT_MAX_TOKENS` | 上下文压缩阈值 | 6000 |
+| `CONTEXT_KEEP_RECENT` | 保留最近 N 轮对话 | 4 |
+| `SESSIONS_DIR` | 会话持久化目录 | ./sessions |
+| `LOG_DIR` | 日志目录 | ./logs |
+| `LOG_LEVEL` | 日志级别 | DEBUG |
+| `HISTORY_MAX_SNAPSHOTS` | 状态快照保留数 | 10 |
+| `OCR_USE_GPU` | OCR GPU 加速 | false |
+| `OCR_CONFIDENCE_THRESHOLD` | OCR 置信度最低阈值 | 0.5 |
+| `RAG_EMBED_MODEL` | RAG 嵌入模型 | paraphrase-multilingual-MiniLM-L12-v2 |
+| `RAG_JRXML_SOURCE` | JRXML 模板源目录 | ./rag/jrxml_source |
+| `RAG_COLLECTION_NAME` | ChromaDB 集合名 | jrxml_chunks |
+
+## 测试
+
+```bash
+# 全部单元 + 集成测试
+cd D:\Idea Project\jaspersoft && python -m pytest tests/ -v
+
+# 仅 E2E 测试（需要前端 dev server 运行）
+cd frontend && npx playwright test
+```