明确错误报告单实例与详情错误边界

补充单实例文件锁和内存 ZIP 生命周期注释

区分管理员详情 404 与归档存储 500

同步错误报告技术方案与项目决策记录

docs/technical/【技术方案】AGC错误报告与诊断上传-2026-08-31.md

@@ -18,9 +18,11 @@ 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<u8>`，随后立即写入私有本地归档；不把 ZIP 长期留在内存。这样既控制峰值，又支持进程重启后后台查看/下载和 OSS 上传失败后的本地取证。
 - 归档对象使用固定私有 OSS key：`agc/error-reports/v1/{yyyy}/{mm}/{dd}/{batchId}.zip`；api-server 先写 `uploading` 元数据，上传成功后记录 `ossObjectKey`、SHA-256、大小和 `ready` 状态。完整事件、说明和日志不进入元数据记录。
 - `agc` 是服务端专用私有前缀；公共直传票据、通用 object-key 规范化和 legacy 公开路径均拒绝该前缀。归档内同名日志会自动加数字后缀，读取本机诊断日志时拒绝符号链接/非普通文件。
 - 后台接口：`GET/PATCH /admin/api/error-reports/{batchId}`、`GET /admin/api/error-reports` 和受保护的 `/download`。
+- 这些是 api-server 内部登录/管理员路由，不属于 `/api/external/v1`，不纳入 External OpenAPI；管理员详情对不存在返回 404，对归档/元数据损坏返回 500。
 - admin viewer 仅接受 error-reports Tab 权限，支持列表筛选、详情、状态 `new/in-progress/resolved`、处理备注和受控下载。
 - 当前兼容实现仍在 api-server 配置目录旁保留元数据与本地归档副本，便于无 OSS 配置的开发环境运行；生产配置启用 OSS 后以 OSS 对象为完整内容来源。SpacetimeDB `error_report` 私有表接入及 30 天 OSS/元数据清理 worker 为后续门禁，HTTP DTO 与管理员权限保持不变。