257 lines
9.0 KiB
Markdown
257 lines
9.0 KiB
Markdown
# 日志系统 + 任务历史 + 文件管理 设计文档
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:writing-plans to create an implementation plan from this spec.
|
||
|
||
**Goal:** 为益选 OCR Web 系统添加持久化日志、任务历史和增强文件管理，提升生产环境可观测性和用户体验。
|
||
|
||
**Architecture:** 单一 SQLite 数据库 (`data/web_data.db`) 存储三类数据，FastAPI 中间件自动采集 HTTP 日志，TaskManager 改造为写入 DB，前端新增两个独立页面。
|
||
|
||
**Tech Stack:** FastAPI middleware, SQLite (via existing DBPool), Vue 3 + Element Plus, Pinia
|
||
|
||
---
|
||
|
||
## 1. 数据库设计
|
||
|
||
数据库文件: `data/web_data.db`，通过现有 `DBPool` 管理。
|
||
|
||
### 1.1 `http_logs` 表
|
||
|
||
```sql
|
||
CREATE TABLE IF NOT EXISTS http_logs (
|
||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||
timestamp TEXT NOT NULL, -- ISO 8601
|
||
method TEXT NOT NULL, -- GET/POST/PUT/DELETE
|
||
path TEXT NOT NULL, -- /api/memory
|
||
status_code INTEGER, -- 200, 404, 500
|
||
duration_ms REAL, -- 请求耗时(ms)
|
||
user TEXT, -- 当前用户名
|
||
ip TEXT, -- 客户端 IP
|
||
detail TEXT -- 错误详情/备注
|
||
);
|
||
CREATE INDEX IF NOT EXISTS idx_http_logs_timestamp ON http_logs(timestamp);
|
||
CREATE INDEX IF NOT EXISTS idx_http_logs_status ON http_logs(status_code);
|
||
```
|
||
|
||
### 1.2 `task_history` 表
|
||
|
||
```sql
|
||
CREATE TABLE IF NOT EXISTS task_history (
|
||
id TEXT PRIMARY KEY, -- 8-char UUID
|
||
name TEXT NOT NULL, -- pipeline/ocr-batch/excel/merge/sync-push/sync-pull
|
||
status TEXT NOT NULL, -- pending/running/completed/failed
|
||
progress INTEGER DEFAULT 0,
|
||
message TEXT,
|
||
result_files TEXT, -- JSON array of filenames
|
||
error TEXT,
|
||
log_lines TEXT, -- JSON array of log strings
|
||
created_at TEXT NOT NULL, -- ISO 8601
|
||
updated_at TEXT NOT NULL, -- ISO 8601
|
||
completed_at TEXT -- ISO 8601, null if not done
|
||
);
|
||
CREATE INDEX IF NOT EXISTS idx_task_history_status ON task_history(status);
|
||
CREATE INDEX IF NOT EXISTS idx_task_history_created ON task_history(created_at);
|
||
```
|
||
|
||
### 1.3 `file_metadata` 表
|
||
|
||
```sql
|
||
CREATE TABLE IF NOT EXISTS file_metadata (
|
||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||
filename TEXT NOT NULL,
|
||
directory TEXT NOT NULL, -- input/output/result
|
||
size INTEGER,
|
||
action TEXT NOT NULL, -- upload/delete/clear
|
||
user TEXT,
|
||
timestamp TEXT NOT NULL, -- ISO 8601
|
||
task_id TEXT -- 关联的任务 ID (可选)
|
||
);
|
||
CREATE INDEX IF NOT EXISTS idx_file_metadata_timestamp ON file_metadata(timestamp);
|
||
```
|
||
|
||
### 1.4 自动清理
|
||
|
||
30 天过期清理，在服务器启动时执行，之后每天通过 `asyncio` 定时任务执行一次：
|
||
|
||
```python
|
||
async def cleanup_old_records():
|
||
cutoff = (datetime.now() - timedelta(days=30)).isoformat()
|
||
await db_pool.execute_write("DELETE FROM http_logs WHERE timestamp < ?", cutoff)
|
||
await db_pool.execute_write("DELETE FROM task_history WHERE created_at < ?", cutoff)
|
||
await db_pool.execute_write("DELETE FROM file_metadata WHERE timestamp < ?", cutoff)
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 后端架构
|
||
|
||
### 2.1 新增文件
|
||
|
||
| 文件 | 职责 |
|
||
|------|------|
|
||
| `web/backend/services/db_schema.py` | 建表 SQL + `init_db()` + `cleanup_old_records()` |
|
||
| `web/backend/middleware/logging.py` | HTTP 请求日志中间件 |
|
||
| `web/backend/routers/logs.py` | 日志查询 API |
|
||
| `web/backend/routers/tasks.py` | 任务历史 API |
|
||
|
||
### 2.2 修改文件
|
||
|
||
| 文件 | 改动 |
|
||
|------|------|
|
||
| `web/backend/main.py` | lifespan 中调用 `init_db()`，挂载 logging 中间件，注册 logs/tasks 路由 |
|
||
| `web/backend/services/task_manager.py` | `update_progress()` 和 `_finish()` 写入 task_history 表 |
|
||
| `web/backend/routers/files.py` | upload/delete/clear 操作写入 file_metadata 表 |
|
||
|
||
### 2.3 API 端点
|
||
|
||
**日志 (`/api/logs`)**
|
||
- `GET /api/logs` — 分页查询
|
||
- 参数: `page`, `page_size`, `method`, `status_code`, `path`(搜索), `start_date`, `end_date`
|
||
- 返回: `{ items: [...], total: number }`
|
||
- `GET /api/logs/stats` — 统计概览
|
||
- 返回: `{ today_count, error_count, avg_duration_ms, error_rate }`
|
||
|
||
**任务历史 (`/api/tasks`)**
|
||
- `GET /api/tasks` — 分页查询
|
||
- 参数: `page`, `page_size`, `status`, `name`(类型筛选), `search`
|
||
- 返回: `{ items: [...], total: number }`
|
||
- `GET /api/tasks/{task_id}` — 任务详情（含完整 log_lines）
|
||
- `POST /api/tasks/{task_id}/retry` — 重试失败任务
|
||
- 根据 `name` 字段重新调用对应处理端点
|
||
|
||
**文件历史 (`/api/files`)**
|
||
- `GET /api/files/history` — 文件操作记录
|
||
- 参数: `page`, `page_size`, `directory`, `action`
|
||
- 返回: `{ items: [...], total: number }`
|
||
- `GET /api/files/stats` — 存储统计
|
||
- 返回: `{ directories: [{ name, file_count, total_size }] }`
|
||
|
||
### 2.4 中间件设计
|
||
|
||
```python
|
||
async def logging_middleware(request: Request, call_next):
|
||
# 跳过静态资源和 WebSocket
|
||
if request.url.path.startswith("/assets") or request.url.path.startswith("/ws"):
|
||
return await call_next(request)
|
||
|
||
start = time.time()
|
||
response = await call_next(request)
|
||
duration_ms = (time.time() - start) * 1000
|
||
|
||
# 异步写入日志（不阻塞响应）
|
||
asyncio.create_task(write_log(
|
||
method=request.method,
|
||
path=request.url.path,
|
||
status_code=response.status_code,
|
||
duration_ms=duration_ms,
|
||
user=get_current_user_from_request(request),
|
||
ip=request.client.host,
|
||
))
|
||
return response
|
||
```
|
||
|
||
### 2.5 TaskManager 改造
|
||
|
||
现有 `TaskManager.update_progress()` 和 `_finish()` 方法中增加 DB 写入：
|
||
|
||
```python
|
||
async def update_progress(self, task_id: str, progress: int, message: str):
|
||
task = self._tasks[task_id]
|
||
task.progress = progress
|
||
task.message = message
|
||
task.log_lines.append(message)
|
||
# 新增：写入 DB
|
||
await self._db.execute_write(
|
||
"UPDATE task_history SET progress=?, message=?, log_lines=?, updated_at=? WHERE id=?",
|
||
progress, message, json.dumps(task.log_lines), datetime.now().isoformat(), task_id
|
||
)
|
||
await self._broadcast(task)
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 前端设计
|
||
|
||
### 3.1 新增页面
|
||
|
||
**侧边栏导航新增 2 项：**
|
||
|
||
| 页面 | 路由 | 图标 | 标签 |
|
||
|------|------|------|------|
|
||
| 任务历史 | `/tasks` | `Timer` | - |
|
||
| 日志中心 | `/logs` | `Notebook` | - |
|
||
|
||
### 3.2 任务历史页面 (`Tasks.vue`)
|
||
|
||
**布局：**
|
||
- 顶部统计卡片行（4 卡片）：总任务数 / 成功 / 失败 / 运行中
|
||
- 筛选栏：状态下拉（全部/成功/失败/运行中）+ 类型下拉（全部/pipeline/ocr/excel/merge）+ 搜索框
|
||
- 表格列：任务ID、类型、状态（彩色标签）、进度条、耗时、创建时间、操作
|
||
- 操作：查看详情（弹窗显示完整日志流）、重试（仅失败任务）
|
||
|
||
**详情弹窗：**
|
||
- 任务基本信息（类型/状态/耗时/结果文件）
|
||
- 终端风格日志流（复用 Dashboard 的 log-box 样式）
|
||
- 结果文件列表（可下载）
|
||
|
||
### 3.3 日志中心页面 (`Logs.vue`)
|
||
|
||
**布局：**
|
||
- 顶部统计卡片行（4 卡片）：今日请求 / 错误数 / 平均耗时 / 错误率
|
||
- 筛选栏：时间范围选择器（今天/7天/30天）+ 方法筛选（GET/POST/PUT/DELETE）+ 状态码筛选（2xx/4xx/5xx）+ 路径搜索
|
||
- 表格列：时间、方法（彩色标签）、路径、状态码（颜色区分）、耗时、用户
|
||
- 点击行展开详情面板（IP 地址、错误信息）
|
||
|
||
### 3.4 Dashboard 增强
|
||
|
||
- stats-row 第三列从硬编码 "记忆库 5591" 改为动态存储统计（磁盘用量）
|
||
- 文件列表区新增「操作历史」按钮，弹窗显示该目录的 file_metadata 记录
|
||
|
||
### 3.5 新增文件
|
||
|
||
| 文件 | 职责 |
|
||
|------|------|
|
||
| `web/frontend/src/views/Tasks.vue` | 任务历史页面 |
|
||
| `web/frontend/src/views/Logs.vue` | 日志中心页面 |
|
||
| `web/frontend/src/stores/tasks.ts` | 任务历史状态管理（可选，可用 api 直接调用） |
|
||
|
||
### 3.6 修改文件
|
||
|
||
| 文件 | 改动 |
|
||
|------|------|
|
||
| `web/frontend/src/views/Layout.vue` | navItems 新增 2 项 |
|
||
| `web/frontend/src/router/index.ts` | 新增 2 个路由 |
|
||
| `web/frontend/src/views/Dashboard.vue` | stats-row 动态化 + 文件历史弹窗 |
|
||
|
||
---
|
||
|
||
## 4. 安全与性能
|
||
|
||
- 日志查询 API 仅限认证用户
|
||
- HTTP 日志不记录请求体（避免泄露敏感数据）
|
||
- 中间件使用 `asyncio.create_task()` 异步写入，不阻塞响应
|
||
- 日志表索引：`timestamp`、`status_code`、`path`
|
||
- 任务表索引：`status`、`created_at`
|
||
- 自动清理 30 天前的记录，防止数据库无限增长
|
||
- 分页查询默认 page_size=50，最大 200
|
||
|
||
---
|
||
|
||
## 5. 实施顺序
|
||
|
||
1. **Phase 1: 数据库 + 后端**
|
||
- db_schema.py（建表 + 清理）
|
||
- logging 中间件
|
||
- task_manager 改造
|
||
- files.py 改造
|
||
- logs.py + tasks.py 路由
|
||
|
||
2. **Phase 2: 前端页面**
|
||
- Tasks.vue
|
||
- Logs.vue
|
||
- Layout.vue 路由注册
|
||
- Dashboard.vue 增强
|
||
|
||
3. **Phase 3: 集成测试**
|
||
- npm run build
|
||
- 端到端验证：操作 → 日志记录 → 任务历史 → 文件历史
|