requirements.md 9.4 KB
DataDownload 产品需求
文档类型：稳定需求。本文描述系统应该提供的产品行为，不描述某个函数或数据库的当前实现。当前落地情况见 implementation-status.md。
1. 目标与边界
DataDownload 用于按站点、设备、日期和数据类型请求、复用、查看及下载诊断数据。新模块独立于旧 BatchDownload；不修改、不迁移旧任务和旧文件。
核心目标：
- 用户创建数据请求任务后，可以持续查看进度、失败原因和已成功数据；
- 相同逻辑数据可跨任务复用，不因任务删除而删除共享文件；
- AI 在新会话中可按数据条件重新查询状态，不依赖记住旧 taskID；
- Mutable 数据可刷新，Frozen 数据稳定复用；
- 部分文件失败时，成功文件仍立即可用。
2. 支持的数据类型
| 类型 | 请求维度 | 固化策略 | 主要输出 |
|---|---|---|---|
| PowerFlow | SiteSN + 本地日期 + 时区 | D+2 | HTML/JSON |
| MQTT Log | SiteSN + 本地日期 + SubType + 时区 | D+2 | XLSX/CSV/JSON |
| EventAlarm | SiteSN + 本地日期 + 时区 | D+2 | XLSX/CSV/JSON |
| AlarmSnapshot | SiteSN + 本地日期 + 时区 | D+2 | 原始 XLSX |
| EMS Log | SiteSN + 日期 + SubType | D+2 | 原始文件 |
| FaultRecord | DeviceSN + DevType + 本地日期 + 时区 | D+2 | 零到多个原始录波文件 |
| UpdateLog | SiteSN | 永不固化 | XLSX/JSON |
用户日期表示站点本地日历日期。任何依赖本地日期边界的类型都必须保留实际时区，不能只保存 UTC 偏移后丢失夏令时语义。
3. 任务需求
3.1 创建
- 至少提供一个有效 SN 和一个数据类型；
- SN 支持文本输入和 UTF-8 TXT 文件导入；
- SN 去空、去重，但不静默改写其内容；
- 日期型数据必须提供开始、结束日期，包含首尾；
- 不允许请求站点当地的未来日期；
- 单任务日期范围最多 600 天；
- UpdateLog 单独请求时不要求日期范围；
- 任务描述不参与数据身份和复用判断。
3.2 状态
任务状态包括：
pending -> running -> complete | partial_success | failed | error | cancelled
\-> cancelling -> cancelled
- 全部工作单元成功或为空：
complete； - 至少有可用结果，同时有失败、取消或 partial item：
partial_success； - 所有需要执行的工作单元均失败：
failed； - 无法规划或启动：
error； - 等待相同数据请求时仍表现为 pending，不占用 worker 长时间等待。
任务完成表示所需数据已经成功缓存，不要求提前生成所有预览格式。
3.3 重试、取消和删除
- 后台对失败请求执行有上限的自动重试；
- 人工“一键重试”处理全部失败 item；FaultRecord 内部只重试未成功文件；
- 首版不提供 FaultRecord 单文件人工重试按钮；
- 已成功 item 不重复执行；
- cancelled 任务不能恢复；
- active 任务必须先取消，才能删除；
- 删除任务只删除 Task、Item、FileAttempt 和 TaskDocument，不删除共享 Document 或文件；
- 任务记录不自动过期，管理员可手动删除。
4. 文档复用与数据新鲜度
4.1 Document 与 Task 的关系
Task 是请求和执行历史；Document 是可复用的数据。多个任务可以引用同一 Document。
- 普通用户只能通过自己的 TaskDocument 入口访问文件；
- 删除任务后用户失去入口，但共享数据继续保留；
- 用户再次请求同一数据时，可以重新关联已有 Document；
- 历史任务不保证永久读取“任务创建时的旧版本”，Mutable 数据成功刷新后可切换为新内容。
4.2 Mutable、Frozen、Dynamic
Mutable：尚未到固化边界，新请求可以刷新当前内容；Frozen：固化边界后完成过一次成功的完整查询，后续直接复用；Dynamic：永不固化，每个独立新请求都允许刷新；当前只有 UpdateLog。
D 日数据的固化边界是业务时区 D+2 00:00:00。D+2 到达后不能只修改状态；必须在边界之后重新成功查询一次，才能 Frozen。
空结果也是有效查询结果。D+2 后完整查询为空可以 Frozen，并保存 Empty 元数据，不创建虚假文件。
5. FaultRecord 专项需求
FaultRecord 的 Frozen 单元是 DeviceSN + DevType + DataDate，不是站点、整个任务或单个物理文件。
当前站点任务只处理 DevType=0（aPower）和 DevType=1（aGate）。DevType=2（MPPT）和 DevType=3（aHub）暂不纳入规划；未来启用时需先确定其设备 SN 来源。
获取流程先查询设备的可召唤目录，按 failureTime 选出目标日期的条目。查询已召唤列表后，必须读取子记录，以子记录的 failureTime 和故障码匹配目录条目；子记录数还必须等于列表中的 faultRecordsCount。仅对未匹配的目录条目发起召唤。新召唤任务按设备 SN、DevType、召唤数量、TriggerType 和 cellTime（请求 UTC 时间 ±1 分钟）定位，并记录任务 ID；每 60 秒查询一次状态，最多等待 2 小时。成功后按该 ID 查已召唤列表，验证子记录数量等于召唤数量，再下载所有有效新旧子文件。超时需保留最后一次观测的召唤状态。
“faultRecordingLst 无记录”指接口成功返回 result: []，可继续召唤目录中的目标项；“lstSubFaultWave 子项为空”指某条已召唤记录的子列表为空，需要与该记录的 faultRecordsCount 比较。数量不一致时该记录无效，不得作为已完成召唤复用。
- 当前已知 DevType 为
0-aPower、1-aGate、2-MPPT、3-aHub，未来允许新增； - 未知类型必须明确失败，不能错误回退为 SiteSN；
- 每日文档关联零到多个独立原始对象，不生成每日 ZIP；
- 稳定文件身份使用上游 FaultID/SubRecordID 等标识，不能依赖可能重复的文件名；
- 一个文件失败不阻止其他文件发布；成功文件立即可用；
- 文件级失败必须记录阶段、原因和尝试次数；
- 刷新已有文件失败时继续保留旧 current file，不能用失败结果覆盖它；
- 旧任务仍可读取旧 current file；新任务必须记录本轮失败，不能把旧文件算作本轮成功；
- 上游后续未再返回某个历史文件时，不自动删除该文件；
- 到达 D+2、完整清单查询成功、所有要求文件成功且无待重试失败时，文档才能 Frozen；
- 某设备/日期 Frozen 不等待同任务的其他设备或日期。
6. 权限与可见性
| 操作 | Owner | 管理员 | 其他用户 |
|---|---|---|---|
| 查看任务和任务文件 | 是 | 是 | 否 |
| 修改描述、取消、重试、删除 | 是 | 是 | 否 |
| 打包本任务文件 | 是 | 是 | 否 |
| 浏览/删除全局共享文档 | 否 | 是 | 否 |
| 修改 owner | 否 | 否 | 否 |
- 普通用户即使传入全局 scope，也只能查询自己的任务；
- 管理员可以查看所有任务和全局 Document Catalog；
- 文件 API 必须校验 TaskID、owner/admin 和 TaskDocument 关联，不能凭 DocumentID 绕过入口；
- 强制删除被引用的共享 Document 仅管理员可执行，并必须明确提示引用影响。
7. 查看、下载与打包
- 任务只要存在可读取的成功文件，就允许查看和下载，不受总体 partial/failed 状态阻断；
- 空文档不出现在普通文件目录中，但管理员可查看其元数据；
- 未知二进制和
.dat允许下载，不要求预览； - FaultRecord 在任务目录中按设备、日期和原始文件展示；
- 多任务 ZIP 按 TaskID 分目录；
partial_success允许打包成功文件；ZIP 根目录包含DataDownloadReport.json；- 报告至少包含任务状态、成功/失败数量，以及失败文件的设备、日期、文件名、阶段、原因和尝试次数；
- 已选中的可用文件在实际读取时失败，则整个 PackageJob 失败，不提供半成品 ZIP；
- ZIP 成功后保留 7 天；任务删除不自动删除已生成 ZIP，PackageJob 按自身生命周期管理。
8. AI / MCP 需求
MCP 使用固定的非管理员特殊用户 USER_AI。
- AI 以数据条件为中心，不要求跨会话记住 taskID；
Frozen + complete数据可直接使用；- Mutable 数据必须向用户说明数据日期和
SourceFetchedAt，由用户选择立即使用或刷新； - partial 数据可以使用成功部分，但必须说明失败/缺失数量；
- 刷新失败而旧版本存在时，AI必须说明“刷新失败、旧版本仍存在”，再由用户确认是否使用；
- 数据缺失时，先检查
USER_AI是否已有覆盖该数据单元的活跃请求，避免重复创建； - 新任务 owner 固定为
USER_AI；普通用户看不到 AI 任务，只有管理员可管理； - MCP 不得查看普通用户任务元数据，也不得获得管理员文档删除权限；
- MCP 不得直接 Put、覆盖或删除共享文件。
9. 核心验收标准
- 相同内容条件产生相同文档身份，任务字段不会破坏复用；
- D+2、时区和空结果行为可测试；
- FaultRecord 每个文件独立发布、失败和重试；
- partial 任务的成功文件可立即下载及打包，并附准确报告；
- 刷新失败不会破坏当前可用旧文件；
- 删除任务立即移除用户入口，但共享文件仍存在；
- 普通用户不能读取其他 owner 或全局 Document；
- AI 新会话能按数据条件查询可用性或请求状态。