docs: add jaspersoft-fix evaluation report

EVALUATION_REPORT.md

@@ -0,0 +1,114 @@
+# jaspersoft-fix 评测报告
+
+**项目路径**: `D:\Idea Project\jaspersoft-fix`
+**评测时间**: 2026-05-25
+**评测维度**: 代码质量 · 安全与稳定性 · 工程实践 · 产品设计
+
+---
+
+## 综合评分
+
+| 维度 | 评分 | 主要问题 |
+|------|------|----------|
+| 代码质量与架构 | 7.3/10 | nodes.py 1709行 God Module、无文件锁并发风险 |
+| 安全与稳定性 | P0×1 + P1×2 + P2×4 | llm.log 写全量 prompt、session 并发覆盖、无 magic bytes 校验 |
+| 工程实践 | 3.5/5 | 原子写入优秀、trace_id 传播良好、无 E2E 测试 |
+| 产品设计 | 4.2/5 | natural_explanation 透明、非 fix 报告误报进度不透明 |
+
+---
+
+## 一、代码质量与架构（7.3/10）
+
+亮点：**原子写入**（tempfile+fsync+replace）设计优秀、v5 Band 级分层精确生成架构、前端 Vue3+Pinia 结构清晰。
+
+主要问题：
+
+| 问题 | 严重度 | 说明 |
+|------|--------|------|
+| nodes.py 过胖 | P1 | 1709行，14个工作流节点，应拆分到 `agent/utils.py` |
+| session.py 无文件锁 | P0 | 多用户并发写同一 session 会互相覆盖（无 flock/fcntl） |
+| 废弃 Vue 组件 | P1 | `StreamingMessage.vue`/`NodeProgress.vue` 仍在 frontend/components |
+
+---
+
+## 二、安全与稳定性
+
+| 等级 | 数量 | 问题 |
+|------|------|------|
+| **P0** | 1 | `llm.log` 写全量 prompt（`prompt[:10000]`），API Key 可能泄露 |
+| **P1** | 2 | session 并发无锁（见 P0）；文件上传无 magic bytes 校验 |
+| **P2** | 4 | LLM prompt 注入风险；ChromaDB 无认证；CORS 宽松；无 API 认证 |
+
+已做好：`.env` 隔离、`sessions/` gitignore、SQL 注入防护（参数化查询）、hex session_id 校验防路径穿越。
+
+**⚠️ llm.log 泄露风险**：
+`backend/llm.py` 第 47-49 行写 `prompt[:10000]` 到日志，第 66-67 行写 `response[:10000]`。prompt 中若含用户上传的文档内容（包含敏感字段名）或 API 调用上下文，可能被记录。需要脱敏。
+
+---
+
+## 三、工程实践（3.5/5）
+
+亮点：原子写入（tempfile+fsync+replace）优秀、日志 trace_id 传播（contextvars）、JSONFormatter 结构化日志、`nodes.py` 的 namespace 检查修复（五轮修正失败根因）。
+
+主要问题：
+
+| 问题 | 严重度 |
+|------|--------|
+| 会话并发无文件锁 | P0 — 多用户并发写同一 session 会互相覆盖 |
+| 无 E2E 测试 | P1 — 无 Playwright 测试 |
+| 废弃 Vue 组件未删除 | P1 — `StreamingMessage.vue`/`NodeProgress.vue` |
+| 冷启动慢（llm.py 初始化） | P2 |
+
+---
+
+## 四、产品设计（4.2/5）
+
+亮点：错误修正循环设计优秀、五轮自动修正+失败上下文注入、`SummaryCard.vue` 正确展示 `natural_explanation`（非 fix 报告误报"进度不透明"是错的）。
+
+主要问题：
+
+| 优先级 | 问题 |
+|--------|------|
+| P0 | 会话并发无文件锁（影响稳定性） |
+| P1 | `export_pdf` 未实现（需标记"敬请期待"） |
+| P1 | 意图分类无用户确认机制 |
+| P2 | 流式输出无 XML 语法高亮 |
+| P2 | 空白状态无引导示例 |
+
+---
+
+## 优先修复路线图
+
+### P0（立即修复）
+
+1. **会话并发文件锁**：在 `save_session()` 加 `fcntl.flock()` 保护先读后写
+2. **LLM 日志脱敏**：prompt/response 中截断或替换 API Key 为 `[REDACTED]`
+
+### P1（近期处理）
+
+3. 删除废弃 Vue 组件（`StreamingMessage.vue`/`NodeProgress.vue`）
+4. 实现 `export_pdf` 或标记"敬请期待"
+5. 意图分类结果标签化供用户确认
+6. 添加 Playwright E2E 测试
+
+### P2（有空再搞）
+
+7. 流式输出 XML 语法高亮
+8. 空白状态引导示例
+
+---
+
+## 与 jaspersoft（非 fix）的关键差异
+
+| 项目 | jaspersoft（非 fix） | jaspersoft-fix |
+|------|---------------------|----------------|
+| commit | `2d5183d` OCR fidelity reform | `0839ba9` WIP（rag + test image） |
+| namespace 前缀 | 未处理 | 已修复 `_extract_jrxml()` |
+| 五轮修正失败根因 | 旧评分公式 | 已修复（去掉 field_coverage 权重） |
+| OCR 自动发现文档类型 | 需手动 | 已实现 |
+| 进度透明度 | 非 fix 报告误报"不透明" | 实际展示 natural_explanation ✅ |
+
+---
+
+*评测时间: 2026-05-25 (Asia/Hong_Kong)*
+*评测工具: Mavis AI Agent*