# DataDownload 当前实现状态

> 更新时间：2026-09-23。本文是代码导航和差异摘要，不替代源码。动态问题状态见 [问题台账](../issues/data-download-open-issues.md)。

## 1. 已实现

- 独立 DataDownload 路由、MongoDB collections、PostgreSQL 当前正文、Asynq 队列和 MinIO 前缀；
- Task、Item、TaskDocument、Document、FileAttempt、FaultRecordEntry、RenderSlot、Artifact、PackageJob 分离；
- 600 天日期范围、站点时区未来日期判断、D+2 和 Dynamic 状态；
- 按数据类型构造 RequestKey，ItemKey 与 Document 身份分离；
- Redis FileRequest token 租约、续租、deferred 等待和 completed marker；
- PostgreSQL 事务替换当前正文并递增 Generation；
- Renderer Artifact、72 小时过期、正文更新断开 Slot；
- PackageJob 创建、下载、取消、重试、删除及 7 天有效期；
- FaultRecord 设备级每日文档、独立文件对象、文件级 Attempt、partial、D+2 Frozen；
- FaultRecord `v2` 先查可召唤目录、验证已召唤子记录，再召唤缺失项；召唤任务按字段与 UTC 时间窗口定位，按 ID 分页查询，每轮延迟约 60 秒重入队并释放 worker，最长 2 小时；
- partial ZIP 成功文件及 `DataDownloadReport.json`；
- owner/admin 任务隔离和 task-scoped 文件入口；
- 管理员 FaultRecord 文件清单、单文件下载和物理删除；
- MCP 固定非管理员 owner `USER_AI`，其任务查询限制为自身。

## 2. 主要代码入口

| 领域 | 文件 |
|---|---|
| Domain | `service/domain/dataDownloadDomain.go` |
| Task planning / structured execution | `service/services/dataDownloadService.go` |
| RequestKey | `service/services/dataDownloadRequestKey.go` |
| Request lease | `service/services/dataDownloadFileRequestService.go` |
| Binary execution | `service/services/dataDownloadBinaryService.go` |
| FaultRecord execution | `service/services/dataDownloadFaultRecordService.go` |
| Renderer | `service/services/dataDownloadRenderService.go` |
| Package | `service/services/dataDownloadPackageService.go` |
| Admin deletion | `service/services/dataDownloadAdminService.go` |
| Mongo repository | `service/repositories/mongo/dataDownloadRepo.go` |
| PostgreSQL repository | `service/repositories/pgsql/dataDownloadRepo.go` |
| MinIO repository | `service/repositories/minio/dataDownloadRepo.go` |
| Queue | `service/task/queue/dataDownloadQueue/dataDownloadQueue.go` |
| HTTP controller/routes | `service/controllers/dataDownloadControllers.go`、`service/routes/dataDownloadRoutes.go` |
| MCP | `service/cmd/mcp/tools/service/data_download.go` |
| Frontend | `src/views/data-download/`、`src/service/dataDownload/` |

## 3. 已知设计差异

| 领域 | 当前实现 | 尚缺 |
|---|---|---|
| content lock | Redis 排他锁；流式读取可续租 | writer-preference 读写锁、统一 fencing |
| Generation | Mongo Document/Slot 比较 | 每次命中校验 PostgreSQL 权威 Generation |
| RenderSlot | DocumentID、format、Generation、ArtifactID | RendererVersion、CacheKey、发布 token/CAS、状态机 |
| PostgreSQL migration | 自制 migration 表和 GORM SQL | goose/embed 或 migration advisory lock |
| PostgreSQL schema | 强类型列仍保留 payload jsonb | 完整类型化及 UpdateLog 细分 |
| Renderer | MQTT/EventAlarm 固定列，PowerFlow 基础 HTML | PowerFlow ECharts、UpdateLog 双 Sheet、JSON envelope |
| 前端预览 | 下载为主 | HTML/CSV/XLSX/JSON/TXT 真实预览、tar 浏览 |
| 批量操作 | 后端支持多 Task 打包，页面单任务整包 | 多选、部分文件选择、批量删除 |
| MCP | 自身任务列表、创建、全局文档分页 | 条件过滤、详情/读取、存在性判断、覆盖检查与幂等创建 |
| 大对象 | HTTP 读取流式；上游与 ZIP 多处 `[]byte` | 流式生成/上传或临时文件 |
| FaultRecord 召唤轮询 | 每轮查询一次并延迟约 60 秒重入队，释放 worker；持久化任务信息和召唤占用，最长 2 小时 | 实际轮询间隔受队列调度影响 |
| FaultRecord 设备发现 | 站点和设备基本信息只规划 aGate/aPower | MPPT/aHub 本阶段不处理；未来启用前确定设备 SN 来源 |

## 4. 当前高风险项

以问题台账为准，当前主要风险包括：

- 普通 content/render 临界区的 TTL、续租和 fencing 不完整；
- PostgreSQL、Mongo Document 和 RenderSlot 不是原子提交；
- Artifact 发布缺少 generation/token CAS；
- 上游大文件和 ZIP 构建存在内存放大；
- migration 多实例并发不安全；
- 二进制 Mongo 发布失败可能产生孤儿对象；
- Task 跨 collection 删除不具备事务性；
- MinIO 底层 helper 尚未真正传播 context。

## 5. DD-005 / DD-006 落地状态

### DD-005 RequestKey

已解决。每个 Kind 只采用影响正文身份的字段；DocumentID、请求租约和 Mongo Document 使用同一规范化 RequestKey。各 Kind 通过独立 `content_version` 管理内容语义升级。

### DD-006 FaultRecord

已解决。规划按 DeviceSN/DevType/Date 拆分；执行保存多个 Entry 和每任务 FileAttempt；成功文件立即发布，失败不覆盖旧 current file；partial 可重试和打包；完整无失败且到达 D+2 才 Frozen。

## 6. 验证

当前相关验证命令：

```bash
cd service
GOCACHE=/tmp/fwh-toolbox-go-cache go test ./services ./cmd/mcp/tools/service ./controllers ./routes ./task/queue/dataDownloadQueue ./repositories/mongo ./repositories/pgsql

cd ..
pnpm exec vue-tsc --build
pnpm exec eslint src/service/dataDownload/index.ts src/service/dataDownload/interface.ts src/views/data-download/index.vue src/views/data-download/documents.vue
```

上述 DataDownload 相关测试与前端类型检查已通过。全仓 `go test ./...` 仍被与 DataDownload 无关的旧程序阻断，包括：

- `models/model_pgsql/siteOriginalData.go` 语法错误；
- 部分 `cmd/gen` 使用已不存在的配置字段；
- 多个旧测试仍调用旧版 `logger.Init`；
- 若干历史测试使用已经变化的函数签名。

## 7. 接续开发读取顺序

1. 先读 [README.md](README.md)；
2. 按任务读取 [requirements.md](requirements.md) 的相关需求；
3. 读取 [technical-design.md](technical-design.md) 的相关设计；
4. 阅读本文对应差异与源码入口；
5. 只读取问题台账中的目标 DD 项；
6. 仅在缺少决策依据时查阅 `archive/`。