整理错误报告 Breaking Change 待决项

覆盖评审文件并记录十项需要产品或架构决策的问题

review.txt

@@ -0,0 +1,72 @@
+# 待决 Breaking Change 评审项
+
+以下问题没有在本轮实现，因为它们会改变公开接口、持久化/归档语义、资源保护策略或运行时并发模型。请你逐项决定是否进入后续变更；本轮已完成的 minor 修复已从此文件移除。
+
+## 1. 错误报告提交缺少限流与配额（高风险）
+
+位置：`server-rs/crates/api-server/src/error_reports.rs` 的 `POST /api/error-reports`。
+
+当前仅限制单次请求体（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`。
+
+当前日志中出现 `bearer `、`token=` 等 marker 时可能把整段（最多 2 MiB）替换成 `[REDACTED]`，诊断信息损失较大。改为按值或按行掩码需要定义凭据语法、边界、误报策略和兼容测试，且必须与客户端脱敏规则保持一致。
+
+## 8. Tauri 日志写入改为异步/批量（中风险）
+
+位置：`append_application_log`、`read_diagnostic_logs` 和 WebView console bridge。
+
+当前每次 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`。
+
+当前先 `symlink_metadata` 再按路径读取，存在 TOCTOU；安全修复应复用 `open_secure_diagnostic_log` 的 O_NOFOLLOW/普通文件校验并从同一 handle 读取。需要补充跨平台实现和 symlink/hardlink 测试，确认缺失文件是否创建以及权限失败的处理。
+
+## 决策后实施要求
+
+确认要做的项目后，请按项目拆分提交，并同步：
+
+- 相关 `shared-contracts`/HTTP 或 Tauri 契约、实现和契约测试；
+- `docs/technical/【技术方案】AGC错误报告与诊断上传-2026-08-31.md` 及必要的共享记忆；
+- 定向前端/Rust 测试、`npm run check:encoding`、`git diff --check`；
+- 若修改公开 API，更新对应 OpenAPI（本轮项目均不属于 `/api/external/v1`）。