Files

wjl 1a0ebde95d feat: 初始化 PicAnalysis 项目

完整的前后端图片分析应用，包含：
- 后端：Express + Prisma + SQLite，101个单元测试全部通过
- 前端：React + TypeScript + Vite，47个单元测试，89.73%覆盖率
- E2E测试：Playwright 测试套件
- MCP集成：Playwright MCP配置完成并测试通过

功能模块：
- 用户认证（JWT）
- 文档管理（CRUD）
- 待办管理（三态工作流）
- 图片管理（上传、截图、OCR）

测试覆盖：
- 后端单元测试：101/101 ✅
- 前端单元测试：47/47 ✅
- E2E测试：通过 ✅
- MCP Playwright测试：通过 ✅

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-02-22 20:10:11 +08:00

24 KiB

Raw Permalink Blame History

图片OCR与智能文档管理系统 - 需求文档

1. 项目概述

1.1 项目背景

在数字化办公场景中，用户经常需要从截图中提取文字内容（如截图保存的待办事项、会议记录、资料等），然后手动整理成文档或待办任务。本项目旨在通过OCR和AI技术，自动化这一流程，提升工作效率。

1.2 项目目标

实现图片到文本的自动识别与转换
利用AI智能分析，自动为文档打标签和分类
支持将识别结果一键转化为待办事项或归档文档
提供友好的Web界面，支持多用户协作

1.3 成功标准

OCR识别准确率达到90%以上（清晰印刷体）
AI标签分类准确率达到85%以上
端到端流程（截图→待办）操作步骤不超过5步
系统响应时间 < 2秒（不含OCR处理时间）
支持Docker一键部署

2. 功能需求

2.1 核心功能 (Must Have - P0)

2.1.1 用户认证与授权

描述: 支持多用户注册登录，数据隔离
优先级: P0
验收标准:
- 支持邮箱/用户名注册登录
- 支持密码加密存储（bcrypt）
- 用户只能查看和操作自己的数据
- 提供登出功能
- JWT Token认证机制

2.1.2 图片采集

描述: 支持系统截图和本地图片上传两种方式
优先级: P0
验收标准:
- 支持点击调用系统截图（需浏览器权限）
- 支持拖拽上传图片
- 支持点击选择文件上传
- 支持常见图片格式（JPG、PNG、WEBP）
- 图片预览功能
- 单个图片大小限制 < 10MB

2.1.3 OCR文字识别与智能处理

描述: 将图片中的文字转换为可编辑文本，建立图片-文档关联，支持OCR失败时的降级处理
优先级: P0
验收标准:
- 支持中文、英文识别
- OCR结果可编辑
- 建立图片与识别结果的永久关联
- 显示OCR置信度/处理状态
- 支持重新OCR识别
- OCR失败处理:
  - 当OCR置信度低于阈值（如30%）时，不自动生成文档
  - 图片保存到"待处理"列表，用户可查看所有失败/待处理的图片
  - 用户可从待处理列表手动创建文档（输入文字内容）
  - 提供图片预处理选项（旋转、裁剪、亮度调整）后重试
  - 显示明确的失败原因和建议
- 模糊图片处理:
  - 自动检测图片质量（模糊度、分辨率）
  - 低质量图片发出警告，但仍可继续处理
  - 提供图片增强选项

2.1.4 文档管理

描述: 对OCR结果进行CRUD操作
优先级: P0
验收标准:
- 创建文档（从OCR结果）
- 编辑文档内容
- 删除文档
- 文档列表展示
- 文档搜索（按标题、内容）
- 文档详情查看

2.1.5 待办事项管理

描述: 将文档转化为待办事项并管理，支持三种状态列表
优先级: P0
验收标准:
- 从文档创建待办事项
- 设置优先级（高/中/低）
- 设置截止日期
- 三种状态列表:
  - 未完成列表: 新创建、进行中的待办
  - 已完成列表: 用户标记完成的待办
  - 已确认列表: 完成后经过用户确认归档的待办
- 状态流转：未完成 → 已完成 → 已确认
- 支持批量操作（批量完成、批量确认）
- 待办列表按状态/优先级/截止日期排序
- 待办归类（支持分类文件夹）
- 已确认列表支持归档和导出

2.1.6 AI智能分析

描述: 对OCR结果进行AI分析，自动打标签和分类，支持动态类型和标签扩展
优先级: P0
验收标准:
- 支持GLM（智谱AI）接口
- 支持MiniMax接口
- 支持DeepSeek接口
- 智能标签生成:
  - 自动生成3-5个标签
  - AI可根据内容创建新标签（非预定义标签）
  - 新标签自动添加到用户标签库
  - 标签使用频率统计，常用标签优先展示
- 智能分类与类型:
  - AI可自动识别文档/待办类型
  - 支持AI创建新分类（如"会议记录"、"发票"、"学习笔记"等）
  - 新分类自动添加到用户分类体系
  - 分类图标和颜色自动生成（可手动修改）
- 动态展示优化:
  - 根据用户保存的内容，自动调整标签/分类展示顺序
  - 常用组合（标签+分类）智能推荐
  - 相似内容自动归集建议
- 标签和分类可手动修改
- AI分析失败时降级处理

2.2 重要功能 (Should Have - P1)

2.2.1 标签与分类系统

描述: 完善的标签分类管理体系
优先级: P1
验收标准:
- 创建自定义分类
- 创建自定义标签
- 标签颜色自定义
- 按标签/分类筛选
- 标签统计展示

2.2.2 配置管理

描述: 可配置的服务提供商设置
优先级: P1
验收标准:
- OCR提供商配置（本地/云端）
- AI提供商配置（API Key等）
- 模型参数配置（温度、top_p等）
- 配置测试功能
- 配置导入/导出

2.2.3 批量操作

描述: 提高批量处理效率
优先级: P1
验收标准:
- 批量上传图片
- 批量OCR识别
- 批量AI分析
- 批量删除
- 批量打标签

2.3 可选功能 (Could Have - P2)

2.3.1 数据导出

描述: 支持将数据导出为各种格式
优先级: P2
功能:
- 导出为Markdown
- 导出为PDF
- 导出为JSON

2.3.2 数据统计

描述: 展示使用统计
优先级: P2
功能:
- OCR次数统计
- 文档数量趋势
- 待办完成率

2.3.3 模板系统

描述: 预设文档/待办模板
优先级: P2
功能:
- 创建模板
- 应用模板
- 模板市场

3. 非功能需求

3.1 性能要求

页面首屏加载时间: < 2秒
API响应时间: < 500ms（不含OCR处理）
OCR处理时间: < 5秒（单张常规图片）
并发用户: 5-10人同时使用
数据容量: 单用户最多1000个文档

3.2 安全要求

密码使用bcrypt加密
JWT Token有效期24小时
API Key加密存储
文件上传类型验证
SQL注入防护
XSS防护
CORS配置
HTTPS部署支持

3.3 可用性要求

系统可用性: 99%
故障恢复时间: < 1小时
数据备份频率: 每日自动备份

3.4 可维护性要求

代码结构清晰，模块化
完善的日志系统
Docker容器化部署
环境变量配置
API文档完整

4. 技术栈

4.1 前端技术栈

框架: React 18
构建工具: Vite
UI组件库: Ant Design 5
状态管理: Zustand / React Query
路由: React Router v6
HTTP客户端: Axios
截图功能: html2canvas 或 MediaDevices API
拖拽上传: react-dropzone

4.2 后端技术栈

运行时: Node.js 18+
框架: Express.js / Fastify
ORM: Prisma
数据库: SQLite（开发） / PostgreSQL（生产）
认证: JWT
文件存储: 本地存储 / 可选OSS

4.3 OCR方案

本地: PaddleOCR (Python微服务) / Tesseract.js
云端API:
- 百度OCR
- 腾讯云OCR
- 阿里云OCR

4.4 AI提供商

智谱AI (GLM): GLM-4 / GLM-4-Flash
MiniMax: MiniMax-Pro
DeepSeek: DeepSeek-Chat / DeepSeek-Coder

4.5 部署方案

容器化: Docker + Docker Compose
反向代理: Nginx
进程管理: PM2 (开发环境)

5. 数据模型

5.1 实体关系图

erDiagram
    USER ||--o{ DOCUMENT : owns
    USER ||--o{ TODO : owns
    USER ||--o{ CATEGORY : owns
    USER ||--o{ TAG : owns
    USER ||--o{ IMAGE : owns

    DOCUMENT ||--o| IMAGE : has
    DOCUMENT ||--o{ DOCUMENT_TAG : has
    DOCUMENT }|--|| CATEGORY : belongs_to

    TODO }|--o| DOCUMENT : derived_from
    TODO }|--|| CATEGORY : belongs_to
    TODO ||--o{ TODO_TAG : has

    TAG ||--o{ DOCUMENT_TAG : associated
    TAG ||--o{ TODO_TAG : associated

    DOCUMENT }|--|| AI_ANALYSIS : has

    NOTE: IMAGE.document_id 可为空，支持待处理图片独立存在

5.2 核心实体

User (用户)

字段	类型	说明	约束
id	UUID	主键	PK
username	String	用户名	UNIQUE, NOT NULL
email	String	邮箱	UNIQUE
password_hash	String	密码哈希	NOT NULL
created_at	DateTime	创建时间
updated_at	DateTime	更新时间

Document (文档)

字段	类型	说明	约束
id	UUID	主键	PK
user_id	UUID	所属用户	FK, NOT NULL
title	String	标题
content	Text	OCR内容/编辑后内容	NOT NULL
category_id	UUID	所属分类	FK
created_at	DateTime	创建时间
updated_at	DateTime	更新时间

Image (图片)

字段	类型	说明	约束
id	UUID	主键	PK
user_id	UUID	所属用户	FK, NOT NULL
document_id	UUID	关联文档	FK (可为空)
file_path	String	存储路径	NOT NULL
file_size	Integer	文件大小
mime_type	String	MIME类型
ocr_result	Text	OCR原始结果
ocr_confidence	Float	置信度
processing_status	Enum	处理状态	pending/processing/success/failed
quality_score	Float	图片质量分数
error_message	Text	失败原因
created_at	DateTime	创建时间
updated_at	DateTime	更新时间

Todo (待办事项)

字段	类型	说明	约束
id	UUID	主键	PK
user_id	UUID	所属用户	FK, NOT NULL
document_id	UUID	来源文档	FK
title	String	标题	NOT NULL
description	Text	描述
priority	Enum	优先级	high/medium/low
status	Enum	状态	pending(未完成)/completed(已完成)/confirmed(已确认)
due_date	DateTime	截止日期
category_id	UUID	所属分类	FK
completed_at	DateTime	完成时间
confirmed_at	DateTime	确认时间
created_at	DateTime	创建时间
updated_at	DateTime	更新时间

Category (分类)

字段	类型	说明	约束
id	UUID	主键	PK
user_id	UUID	所属用户	FK, NOT NULL
name	String	分类名	NOT NULL
type	Enum	类型	document/todo
color	String	颜色
icon	String	图标
parent_id	UUID	父分类	FK
sort_order	Integer	排序
usage_count	Integer	使用次数	默认0
is_ai_created	Boolean	AI创建	默认false
created_at	DateTime	创建时间

Tag (标签)

字段	类型	说明	约束
id	UUID	主键	PK
user_id	UUID	所属用户	FK, NOT NULL
name	String	标签名	NOT NULL
color	String	颜色
usage_count	Integer	使用次数	默认0
is_ai_created	Boolean	AI创建	默认false
created_at	DateTime	创建时间

AIAnalysis (AI分析结果)

字段	类型	说明	约束
id	UUID	主键	PK
document_id	UUID	关联文档	FK, NOT NULL
provider	String	AI提供商
model	String	模型名
suggested_tags	JSON	推荐标签
suggested_category	String	推荐分类
summary	Text	摘要
raw_response	JSON	原始响应
created_at	DateTime	创建时间

Config (配置)

字段	类型	说明	约束
id	UUID	主键	PK
user_id	UUID	所属用户	FK, NOT NULL
key	String	配置键	NOT NULL
value	JSON	配置值
created_at	DateTime	创建时间
updated_at	DateTime	更新时间

5.3 待处理图片列表

概念说明

当OCR失败或置信度过低时，图片不会被删除，而是保存到"待处理图片列表"中，用户可以：

查看所有待处理的图片
手动输入文字创建文档
调整图片后重新OCR
删除无用的图片

查询逻辑

-- 待处理图片列表
SELECT * FROM images
WHERE user_id = ? AND (document_id IS NULL OR processing_status = 'failed')
ORDER BY created_at DESC

状态流转

图片上传 → OCR处理 → 成功(创建文档) / 失败(进入待处理列表)
待处理列表 → 手动创建文档 / 删除 / 重新OCR

6. 用户界面

6.1 页面结构

页面	路由	权限	描述
登录/注册	`/auth`	公开	用户登录和注册
工作台	`/`	需登录	主页面，包含快速操作和统计
文档列表	`/documents`	需登录	文档管理页面
文档详情	`/documents/:id`	需登录	文档编辑/查看
待办列表	`/todos`	需登录	待办事项管理（三种状态）
待处理图片	`/pending-images`	需登录	OCR失败的待处理图片列表
设置	`/settings`	需登录	系统配置
标签管理	`/tags`	需登录	标签和分类管理
统计	`/stats`	需登录	数据统计

6.2 核心交互流程

flowchart TD
    A[用户登录] --> B[工作台]
    B --> C{选择操作}

    C -->|截图/上传| D[图片上传]
    D --> E[OCR处理]
    E --> F{OCR结果}

    F -->|成功且置信度高| G[显示OCR结果]
    F -->|失败/置信度低| H[保存到待处理列表]

    G --> I{满意结果?}
    I -->|是| J[保存文档]
    I -->|需编辑| K[编辑OCR结果]
    K --> J

    H --> L[待处理图片页]
    L --> M{处理方式}
    M -->|手动输入| N[创建文档]
    M -->|图片增强+重试| D
    M -->|删除| O[移除图片]

    J --> P[AI智能分析]
    P --> Q{AI分析}
    Q -->|自动创建| R[新标签/新分类]
    Q -->|推荐已有| S[现有标签/分类]

    R --> T[用户确认/修改]
    S --> T

    T --> U{文档用途}
    U -->|待办事项| V[创建待办]
    U -->|存档| W[归档文档]

    V --> X[设置优先级/截止日期]
    X --> Y[保存到未完成列表]

    Y --> Z{状态流转}
    Z -->|完成| AA[移动到已完成列表]
    Z -->|确认| AB[移动到已确认列表]

    W --> AC[选择分类]
    AC --> AD[保存完成]

6.3 界面原型要点

工作台首页

顶部：快速截图按钮（突出显示）
中部：最近文档 + 待办事项
底部：快捷操作入口

文档编辑页

左侧：图片预览 + OCR原始结果
右侧：可编辑文本区域
底部：AI分析按钮 + 标签选择 + 操作按钮

待办管理页（三种状态列表）

顶部: Tab切换（未完成 / 已完成 / 已确认）
筛选器: 优先级、分类、标签、截止日期
未完成列表:
- 待办卡片显示：标题、描述、优先级标签、截止日期
- 操作：编辑、标记完成、删除
- 支持拖拽排序
已完成列表:
- 已完成的待办，显示完成时间
- 操作：撤销（回到未完成）、确认归档、删除
- 批量确认操作
已确认列表:
- 归档的待办，只读查看
- 支持导出、批量删除
- 显示确认时间

待处理图片页

顶部: 统计信息（待处理数量、本周新增）
图片网格: 显示所有待处理图片
图片卡片操作:
- 预览图片
- 手动创建文档（打开编辑对话框）
- 图片增强（旋转、裁剪、亮度）后重新OCR
- 删除图片
批量操作: 全选后批量删除

文档详情页

左侧: 图片预览 + OCR原始结果
右侧: 可编辑文本区域
底部/侧边:
- AI分析按钮
- 动态标签展示（常用标签优先）
- 动态分类展示（AI推荐分类置顶）
- 转为待办按钮

7. API设计

7.1 认证相关

POST   /api/auth/register     # 用户注册
POST   /api/auth/login        # 用户登录
POST   /api/auth/logout       # 用户登出
GET    /api/auth/me           # 获取当前用户信息

7.2 文档相关

GET    /api/documents         # 获取文档列表
POST   /api/documents         # 创建文档
GET    /api/documents/:id     # 获取文档详情
PUT    /api/documents/:id     # 更新文档
DELETE /api/documents/:id     # 删除文档
GET    /api/documents/:id/image # 获取关联图片

7.3 OCR相关

POST   /api/ocr/upload        # 上传图片并OCR
POST   /api/ocr/analyze       # 对已有图片重新OCR
GET    /api/ocr/status/:taskId # 查询OCR任务状态
POST   /api/ocr/enhance       # 图片增强后重新OCR
GET    /api/ocr/pending       # 获取待处理图片列表
DELETE /api/ocr/pending/:id   # 删除待处理图片
POST   /api/ocr/pending/:id/manual-create # 手动创建文档

7.4 待办相关

GET    /api/todos             # 获取待办列表（支持状态筛选）
POST   /api/todos             # 创建待办
GET    /api/todos/:id         # 获取待办详情
PUT    /api/todos/:id         # 更新待办
DELETE /api/todos/:id         # 删除待办
PATCH  /api/todos/:id/complete # 标记完成
PATCH  /api/todos/:id/confirm # 标记确认
PATCH  /api/todos/:id/reopen  # 撤销到未完成
POST   /api/todos/batch-complete # 批量完成
POST   /api/todos/batch-confirm  # 批量确认

7.5 AI分析相关

POST   /api/ai/analyze        # AI分析文档（标签+分类）
POST   /api/ai/suggest-tags   # 获取标签建议（可创建新标签）
POST   /api/ai/suggest-category # 获取分类建议（可创建新分类）
POST   /api/ai/detect-type    # AI检测文档类型
GET    /api/ai/smart-suggestions # 获取智能推荐（基于历史）

7.6 分类与标签

GET    /api/categories        # 获取分类列表
POST   /api/categories        # 创建分类
PUT    /api/categories/:id    # 更新分类
DELETE /api/categories/:id    # 删除分类

GET    /api/tags              # 获取标签列表
POST   /api/tags              # 创建标签
PUT    /api/tags/:id          # 更新标签
DELETE /api/tags/:id          # 删除标签

7.7 配置相关

GET    /api/config            # 获取配置
PUT    /api/config            # 更新配置
POST   /api/config/test       # 测试配置

8. 开发计划

8.1 里程碑

里程碑	预计完成	交付物
M1: 基础框架搭建	第1周	项目脚手架、数据库设计、基础API
M2: 核心功能开发	第2-3周	OCR识别、文档CRUD、用户认证
M3: AI集成	第4周	AI分析功能、标签分类
M4: 待办管理	第5周	待办CRUD、优先级截止日期
M5: 完善与优化	第6周	UI优化、测试、文档

8.2 任务分解

Sprint 1: 基础架构

搭建React + Vite项目
搭建Express后端项目
设计数据库Schema (Prisma)
实现JWT认证
Docker配置文件编写
估算: 3-5天

Sprint 2: 图片与OCR

实现图片上传功能
集成本地OCR (PaddleOCR)
集成云端OCR API
建立图片-文档关联
OCR结果编辑功能
估算: 5-7天
依赖: Sprint 1

Sprint 3: 文档管理

文档CRUD API
文档列表UI
文档详情/编辑页
搜索功能
估算: 3-4天
依赖: Sprint 2

Sprint 4: AI集成

AI提供商抽象层设计
集成GLM API
集成MiniMax API
集成DeepSeek API
标签分类生成逻辑
估算: 5-7天
依赖: Sprint 3

Sprint 5: 待办管理

待办数据模型
待办CRUD API和UI
优先级和截止日期
状态管理
待办分类
估算: 4-5天
依赖: Sprint 3

Sprint 6: 配置与优化

配置管理页面
OCR/AI提供商配置
UI/UX优化
性能优化
错误处理完善
估算: 3-4天

9. 风险评估

风险	可能性	影响	缓解措施
OCR准确率不达标	中	高	同时支持多个OCR提供商，允许用户选择
AI API成本过高	中	中	提供本地模型选项，优化prompt减少token
浏览器截图权限限制	高	中	提供本地文件上传作为替代方案
本地OCR性能问题	中	中	使用GPU加速，或默认使用云端API
多用户数据隔离问题	低	高	严格的中间件验证，充分的测试
AI提供商API变更	中	中	抽象层设计，便于切换提供商

10. Docker部署方案

10.1 服务架构

┌─────────────────────────────────────────┐
│              Nginx (80/443)              │
├─────────────────────────────────────────┤
│                                         │
│  ┌─────────────┐  ┌─────────────────┐  │
│  │   React     │  │   Express API   │  │
│  │   Frontend  │  │   Backend       │  │
│  └─────────────┘  └─────────────────┘  │
│                          │              │
│  ┌─────────────┐  ┌──────▼──────┐      │
│  │  PaddleOCR  │  │  Database   │      │
│  │  (Optional) │  │  (SQLite/   │      │
│  │             │  │   PG)       │      │
│  └─────────────┘  └─────────────┘      │
└─────────────────────────────────────────┘

10.2 Docker Compose 配置

services:
  frontend:
    build: ./frontend
    ports:
      - "3000:3000"
    depends_on:
      - backend

  backend:
    build: ./backend
    ports:
      - "4000:4000"
    environment:
      - DATABASE_URL=file:./dev.db
      - JWT_SECRET=${JWT_SECRET}
    volumes:
      - ./uploads:/app/uploads
      - ./data:/app/data

  ocr-service:
    build: ./ocr-service
    ports:
      - "5000:5000"
    profiles:
      - local-ocr

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
    depends_on:
      - frontend
      - backend

11. 后续扩展方向

移动端适配: 响应式设计或PWA
协作功能: 分享文档、多人协作编辑
语音输入: 支持语音转文字后处理
智能提醒: 基于待办的智能提醒
知识图谱: 构建文档间的关联关系
版本控制: 文档修改历史和版本回溯
插件系统: 支持自定义扩展
API开放: 提供开放API供第三方集成

12. 附录

12.1 参考资料

12.2 术语表

OCR: Optical Character Recognition，光学字符识别
GLM: General Language Model，智谱AI的大语言模型
JWT: JSON Web Token，用于身份验证的令牌
CRUD: Create, Read, Update, Delete，增删改查
Docker: 容器化部署技术

需求确认

我已经整理了完整的需求文档。请确认：

功能完整性 - 是否有遗漏的功能？
优先级 - P0/P1/P2 的划分是否合理？
可行性 - 技术方案和时间估算是否可行？
其他 - 还有其他需要补充的吗？

如果确认无误，请回复 "确认"，我将进入开发规划阶段。如果需要修改，请告诉我具体需要调整的地方。

24 KiB Raw Permalink Blame History Unescape Escape