# 业务数据存储优化与指标报告

> 状态：已完成第一阶段可审计代码改造；未执行破坏性清理。
> 目标：减少无效任务文件、把任务元数据从“内存 + 散落目录 JSON”提升为“可恢复元数据存储”，并为后续 PostgreSQL 迁移留出接口。

## 1. 优化前现状

### 任务存储

- 任务状态 / 事件只存在于 `JobManager._jobs` 内存中，服务重启即丢失。
- `POST /api/jobs` 每次提交都会立刻创建 `service_workspace/{job_id}/input`、`output` 和配置文件。
- 任务完成后没有 TTL / 引用检查清理逻辑；历史任务目录会一直留在磁盘。
- `service_workspace` 中大量任务目录只是“曾经跑过一次”的产物，没有被任何素材或模板引用。

### 素材存储

- 素材文件保留在 `service_assets/{asset_id}/asset.*`，元数据写在目录内 `meta.json`。
- 普通的 `POST /api/assets` 没有写入 `sha256`，只有 `.wcd` 导入路径开始做内容去重。
- 前端贴纸 `tint` 仍放在 localStorage，没有回到服务端统一维护。

### 当前实际磁盘基线（2026-08-06 扫描）

| 项 | 数量 / 大小 |
|---|---|
| `service_workspace` 任务目录 | 193 个 |
| `service_workspace` 总大小 | 2.44 GiB / 2,618,726,669 bytes |
| 被素材 `job_id` 引用的任务目录 | 6 个 |
| 未被任何素材引用的任务目录 | 187 个 |
| 未引用任务目录总大小 | 2.38 GiB / 2,556,506,642 bytes |
| 素材文件 | 40 个，合计约 95.6 MiB |
| 素材中重复内容多占空间 | 6 个额外文件，约 2.34 MiB |
| 设计模板 JSON | 4 个 |

## 2. 优化方案与已落地改动

### 1) 新增业务元数据存储层

新增 `backend/service/metadata_store.py`：

- SQLite 单文件 `backend/service_metadata/app.db`。
- 建 `jobs` 和 `job_events` 两张表。
- 任务创建、状态更新、产物路径、SSE 事件都会落库。
- `JobManager` 启动时可以从数据库恢复任务，不再完全依赖内存。
- 表结构有意保持“一行元数据 + JSONB/JSON 字段”风格，后续迁移到 PostgreSQL 时主体字段不变。

### 2) 任务目录可审计与可清理

扩展 `backend/service/storage.py`：

- `job_dir_size()` / `job_dir_info()`：按任务统计占用。
- `stale_job_dirs()`：按“未被素材引用、不在元数据库、可选按年龄”筛选遗留目录。
- `remove_job_dir()`：提供精确清理，只清理 `service_workspace` 下的任务目录。

新增 `backend/service/storage_metrics.py`：

- 默认 `dry-run`，只扫描并输出可回收空间。
- 只有显式 `--apply` 才会删除遗留任务目录。
- 示例：

```bash
cd backend
.venv/bin/python -m service.storage_metrics --max-age-days 0
.venv/bin/python -m service.storage_metrics --max-age-days 0 --json ../docs/storage-metrics.json
# 确认后执行
.venv/bin/python -m service.storage_metrics --max-age-days 0 --apply
```

### 3) 素材去重基础

- `.wcd` 导入路径已按 `sha256` 去重素材。
- `service_assets/{id}/meta.json` 中新增 `sha256` 字段。
- 后续 `POST /api/assets` 也可以统一补充哈希，形成服务级去重。

### 4) 可实时查询指标

新增只读接口：

```text
GET /api/maintenance/storage-summary
```

返回指标包括：

- `job_dir_count`：当前任务目录数。
- `referenced_job_ids`：被素材引用的任务数。
- `stale_job_count`：可回收任务数。
- `reclaimable_bytes`：可回收字节数。
- `jobs_in_db` / `events_in_db`：当前元数据分录数。
- `dry_run_only`: `true`，明确该接口不做删除。

## 3. 优化后指标

### 空间收益（只做审计，未执行删除）

| 指标 | 优化前 | 优化后可清理 | 优化后保留 |
|---|---:|---:|---:|
| 任务目录 | 193 | 187 | 6（被素材引用） |
| 任务文件占用 | 2.44 GiB | 2.38 GiB | ~59.3 MiB |
| 任务空间占用 | 100% | 可回收 97.6% | 首个保护区约 2.4% |

换算：

- 2,556,506,642 bytes ≈ 2.38 GiB。
- 若执行清理，仅任务目录可释放约 **2.38 GiB**。
- 清理后任务目录可降到约 **59.3 MiB**，即保留的部分仍是当前贴纸真正引用的任务产物。

### 素材去重收益

当前 40 个素材文件中有 6 个属于重复内容，去重后：

- 少存 6 个文件。
- 可节省 2,455,630 bytes，约 **2.34 MiB**。
- 素材文件数量从 40 → 34 个唯一内容。

这个数字目前不大，因为很多重复不到 100KB；真正大头仍是任务目录。

### 效能与可维护性收益

1. **任务可恢复**
   - 原来重启服务后任务状态、进度、事件全部丢失。
   - 现在 `jobs` / `job_events` 落库，启动时可恢复。

2. **查询由全盘扫描变为索引查询**
   - 原来 `list_jobs` 只读内存；任务详情依赖内存里的事件列表。
   - 现在有持久化事件表和 `job_id` 索引，可追溯历史。

3. **清理依据可计算**
   - 原来“哪个目录能删”靠人工判断。
   - 现在可统计“是否被素材引用、是否在元数据库、目录多老”，避免误删正在使用的任务。

4. **存储成本上限可控**
   - 配合 TTL 清理，后续每新增任务产生的产物会在保留期后被回收。
   - 不会继续无限制累积。

## 4. 建议后续执行步骤

1. 确认当前项目不再需要 187 个旧任务产物后，执行：

```bash
cd backend
.venv/bin/python -m service.storage_metrics --max-age-days 0 --apply
```

2. 把 `metadata_store.py` 从 SQLite 迁移到 PostgreSQL：

   - 安装 SQLAlchemy / asyncpg。
   - `docker-compose.yml` 增加 PostgreSQL 服务。
   - 将 `jobs` / `job_events` / `assets` / `design_documents` 迁到 PG。

3. 把贴纸 `tint` 从 localStorage 迁到 `assets` 元数据，并由后端 `PATCH /api/assets/{id}` 维护。

4. `POST /api/assets` 统一补 `sha256`，实现服务级素材去重。

5. 增加后台定时清理任务，例如保留 7 天、30 天两档。

## 5. 相关文件

- `backend/service/metadata_store.py`
- `backend/service/job_manager.py`
- `backend/service/storage.py`
- `backend/service/storage_metrics.py`
- `backend/service/app.py`
- `docs/DESIGN_DATA_STORAGE_PLAN.md`