diff --git a/docs/technical/【技术方案】AGC错误报告与诊断上传-2026-08-31.md b/docs/technical/【技术方案】AGC错误报告与诊断上传-2026-08-31.md index 50d6effb2..caae7986a 100644 --- a/docs/technical/【技术方案】AGC错误报告与诊断上传-2026-08-31.md +++ b/docs/technical/【技术方案】AGC错误报告与诊断上传-2026-08-31.md @@ -19,11 +19,12 @@ AI Game Creator Shell 采用 IDEA 风格的当前进程错误报告：错误事 - 登录态客户端使用 `POST /api/error-reports`，请求 DTO 位于 `shared-contracts::error_reports`。 - api-server 对请求体设置 24 MiB 上限，并校验 schemaVersion、submissionId、事件/日志数量和 20 MiB 压缩包上限；事件字段、用户说明和日志名/内容均做长度限制与基础脱敏，归档使用 `events.jsonl`（每行一个事件）。结构化事件只保存在当前进程内，用户提交时才生成 `events.jsonl`，不在磁盘单独持久化。submissionId 提供重放幂等。 - 归档构建会短暂使用一个受 20 MiB 上限约束的内存 `Vec`，随后立即写入私有本地归档；不把 ZIP 长期留在内存。这样既控制峰值，又支持进程重启后后台查看/下载和 OSS 上传失败后的本地取证。 -- 归档对象使用固定私有 OSS key：`agc/error-reports/v1/{yyyy}/{mm}/{dd}/{batchId}.zip`；api-server 先写 `uploading` 元数据，上传成功后记录 `ossObjectKey`、SHA-256、大小和 `ready` 状态。完整事件、说明和日志不进入元数据记录。 +- 本地 `error-reports/index.json` 保存元数据索引；创建时用索引完成 submission 幂等查找，管理员列表从索引读取并分页。索引缺失时会从现有元数据文件一次性重建。 +- 归档对象使用固定私有 OSS key：`agc/error-reports/v1/{batchId}.zip`；key 只由报告 UUID 决定，不包含时间戳。api-server 先写 `uploading` 元数据，上传成功后记录 `ossObjectKey`、SHA-256、大小和 `ready` 状态；相同 submission 重放对已 `ready` 报告直接返回，不重复上传。完整事件、说明和日志不进入元数据记录。 - `agc` 是服务端专用私有前缀；公共直传票据、通用 object-key 规范化和 legacy 公开路径均拒绝该前缀。归档内同名日志会自动加数字后缀，读取本机诊断日志时拒绝符号链接/非普通文件。 -- 后台接口：`GET/PATCH /admin/api/error-reports/{batchId}`、`GET /admin/api/error-reports` 和受保护的 `/download`。 +- 后台接口：`GET/PATCH /admin/api/error-reports/{batchId}`、`GET /admin/api/error-reports` 和受保护的 `/download`。列表支持 `limit`/`offset` 分页并返回 `total`、`hasMore`。 - 这些是 api-server 内部登录/管理员路由，不属于 `/api/external/v1`，不纳入 External OpenAPI；管理员详情对不存在返回 404，对归档/元数据损坏返回 500。 -- admin viewer 仅接受 error-reports Tab 权限，支持列表筛选、详情、状态 `new/in-progress/resolved`、处理备注和受控下载；列表行支持键盘 Enter/Space 打开详情，详情事件预览最多显示 20 条，完整内容通过诊断包下载获取。 +- admin viewer 仅接受 error-reports Tab 权限，支持列表筛选、分页、详情、状态 `new/in-progress/resolved`、处理备注和受控下载；不存在的更新目标返回 404，存储损坏返回 500。列表行支持键盘 Enter/Space 打开详情，详情事件预览最多显示 20 条，完整内容通过诊断包下载获取。 - 当前兼容实现仍在 api-server 配置目录旁保留元数据与本地归档副本，便于无 OSS 配置的开发环境运行；生产配置启用 OSS 后以 OSS 对象为完整内容来源。SpacetimeDB `error_report` 私有表接入及 30 天 OSS/元数据清理 worker 为后续门禁，HTTP DTO 与管理员权限保持不变。 ## 验收 diff --git a/review.txt b/review.txt index 418394e11..e8e5ba575 100644 --- a/review.txt +++ b/review.txt @@ -8,36 +8,12 @@ 当前仅限制单次请求体（24 MiB），没有按用户限流、存储配额或全局容量上限。单个账号可以持续触发 ZIP/SHA-256/OSS 写入并使本地磁盘和对象存储增长。需要确定：按用户还是按 IP 限流、窗口与返回状态（通常 429）、配额维度、超额时是否拒绝或清理旧报告，以及生产配置和监控指标。 -## 2. 管理员错误报告列表需要分页契约（中风险） - -位置：`apps/admin-web/src/pages/AdminErrorReportsPage.tsx` 及 admin API。 - -列表目前最多读取服务端默认 100 条，没有 offset/cursor 和 total；超过 100 条后旧报告不可达。需要确定采用 offset 还是 cursor、是否返回 total/hasMore、默认页大小、筛选与排序保持方式，并同步 shared-contracts、前后端测试和 UI。 - ## 3. 并发文件 I/O 与归档解析迁移到 `spawn_blocking`（中风险） 位置：`server-rs/crates/api-server/src/error_reports.rs`。 create/list/get/read_archive/mark_* 在 async handler 中持有 Tokio mutex 并执行同步文件 I/O、ZIP 解析和权限操作，会阻塞 worker 且串行化请求。迁移需要重新划分锁的临界区、处理取消语义和错误映射，并验证并发下幂等与清理行为。 -## 4. 元数据全目录扫描改为索引（中风险） - -位置：`ErrorReportStore::create/list`。 - -每次创建和列表都扫描并反序列化所有元数据，成本随 30 天保留量线性增长。可选方案包括把 `user_id + submission_id` 哈希进文件名、维护内存索引或引入持久索引；需要评估进程重启恢复、历史文件兼容和清理一致性。 - -## 5. 幂等重放对已 ready 报告短路（中风险） - -位置：`ErrorReportStore::create`/上传流程。 - -相同 `submission_id` 重放时当前会再次读取、哈希和上传归档，可能在跨日时生成新 OSS key、遗留旧对象，或把原本 ready 的报告降级为 failed。修复会改变重放响应和存储状态迁移，需要确定 ready/failed/uploading 各状态的权威行为、并发重放锁和 OSS 清理策略。 - -## 6. 归档缺少 `events.jsonl` 时应视为损坏（中风险） - -位置：`parse_archive`。 - -当前缺少 `events.jsonl` 会静默返回空事件，管理员可能把损坏包当成有效报告。改为报错会改变现有损坏归档的读取结果和 HTTP 状态，需要确定是否仅在 `event_count > 0` 时拒绝、错误码/提示和历史归档处理方式。 - ## 7. 日志脱敏从整段替换改为局部掩码（中风险） 位置：`sanitize_report_text_with_limit`。 @@ -50,12 +26,6 @@ create/list/get/read_archive/mark_* 在 async handler 中持有 Tokio mutex 并 当前每次 console 调用都同步打开/追加/flush 文件，读取命令也在主线程执行。迁移到 `spawn_blocking` 或队列批量写入会改变调用时序、失败可见性、退出时刷盘和测试方式，需要确定丢日志容忍度、队列上限、关闭 flush 和 Tauri command 返回语义。 -## 9. 管理员更新缺失报告的错误契约（低但涉及 HTTP 语义） - -位置：`admin_update_error_report` 与 `ErrorReportStore::update`。 - -当前所有 update 错误都映射为 400 并可能泄露底层文件系统文本；合法但不存在的 `batch_id` 应为 404，损坏/内部错误应为 500。需要引入 typed error、统一错误消息和对应契约测试，属于管理员 API 状态码语义调整。 - ## 10. 诊断日志读取的安全打开实现（中风险） 位置：`apps/ai-game-creator-shell/src-tauri/src/main.rs::read_diagnostic_logs`。