From 2e7b941b04de9495d5c136e783e8656c0a1f508b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=8B=E5=BE=B7=E5=AE=87?= Date: Wed, 2 Sep 2026 19:18:34 +0800 Subject: [PATCH] =?UTF-8?q?=E5=90=8C=E6=AD=A5=E9=94=99=E8=AF=AF=E6=8A=A5?= =?UTF-8?q?=E5=91=8A=E5=A5=91=E7=BA=A6=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 记录开发期用户归属、身份限流与元数据校验 同步管理员更新响应、备注编辑器和列表索引行为 --- docs/project-memory/shared-memory/decision-log.md | 1 + .../technical/【技术方案】AGC错误报告与诊断上传-2026-08-31.md | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index 5c061ec3b..5d4cd4cc9 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -7908,3 +7908,4 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在 - 2026-09-01 review minor 修复：错误报告每日清理改为完整分页扫描，DB 删除失败显式返回以便下周期重试；OSS 读取按 `Content-Length` 与流式累计执行大小上限；管理员归档解析限制解压后 `events.jsonl` 为 24 MiB / 100 条事件。 - 2026-09-02 review breaking 项落地：错误报告 create/update procedure 删除 `user_id`、`now_micros` 输入字段，分别改用 `ctx.sender()`、`ctx.timestamp`；首个 fingerprint/source 强制 512 字符上限，备注超过 2,000 字显式拒绝；内部 OSS 对象键收紧为 `agc/error-reports/v1/`，凭据脱敏覆盖空白/分隔符变体。发布需同步 module、spacetime-client bindings 与 api-server。 - 2026-09-02 客户端错误报告提交成功与本地队列 ack 解耦：POST 成功即显示提交成功并关闭，ack 使用有限重试且失败只记录日志；同一批 eventId 在进程内复用稳定 submissionId，避免 ack 失败后重新提交产生重复报告。 +- 2026-09-02 review 后续收口：错误报告创建增加服务 identity 门禁与单 identity 每小时 100 次配额；开发期将已验证登录用户 `user_id` 由 api-server 注入 procedure 并由 module 校验；module 收紧固定 OSS key、SHA-256、归档大小和计数；管理员 PATCH 返回轻量元数据并在详情弹窗提供备注编辑器；列表无过滤查询使用 `created_at` BTree 索引。 diff --git a/docs/technical/【技术方案】AGC错误报告与诊断上传-2026-08-31.md b/docs/technical/【技术方案】AGC错误报告与诊断上传-2026-08-31.md index 2f9a3fc52..9b6b9d2dc 100644 --- a/docs/technical/【技术方案】AGC错误报告与诊断上传-2026-08-31.md +++ b/docs/technical/【技术方案】AGC错误报告与诊断上传-2026-08-31.md @@ -19,14 +19,14 @@ AI Game Creator Shell 采用 IDEA 风格的当前进程错误报告：错误事 ## HTTP 与存储 - 登录态客户端使用 `POST /api/error-reports`，请求 DTO 位于 `shared-contracts::error_reports`。 -- api-server 对请求体设置 24 MiB 上限，并校验 schemaVersion、submissionId、事件/日志数量和 20 MiB 压缩包上限；事件字段、用户说明和日志名/内容均做长度限制与凭据脱敏，归档使用 `events.jsonl`（每行一个事件）。结构化事件只保存在当前进程内，用户提交时才生成 `events.jsonl`，不在磁盘单独持久化。submissionId 提供重放幂等；客户端对同一批事件复用稳定 submissionId，服务端提交成功后立即反馈成功，本地事件 ack 独立重试，不因 ack 失败误报提交失败；SpacetimeDB procedure 不接受调用方 `user_id` 或 `now_micros`，分别使用 `ctx.sender()` 与 `ctx.timestamp`。 +- api-server 对请求体设置 24 MiB 上限，并校验 schemaVersion、submissionId、事件/日志数量和 20 MiB 压缩包上限；事件字段、用户说明和日志名/内容均做长度限制与凭据脱敏，归档使用 `events.jsonl`（每行一个事件）。结构化事件只保存在当前进程内，用户提交时才生成 `events.jsonl`，不在磁盘单独持久化。submissionId 提供重放幂等；客户端对同一批事件复用稳定 submissionId，服务端提交成功后立即反馈成功，本地事件 ack 独立重试，不因 ack 失败误报提交失败；SpacetimeDB procedure 使用服务 identity 门禁，`user_id` 由 api-server 注入并在 module 校验，时间戳仍使用 `ctx.timestamp`。创建 procedure 额外限制单 identity 每小时 100 次提交。 - 归档构建只在请求生命周期内使用受 20 MiB 上限约束的内存 `Vec`，随后直接 PUT 到私有 OSS；服务端不写本地报告文件，也不保留本地索引。OSS 上传失败不写入数据库，调用方可稍后重新提交。 - 归档对象使用固定私有 OSS key：`agc/error-reports/v1/{batchId}.zip`；key 只由报告 UUID 决定，不包含时间戳。上传成功后才写入 SpacetimeDB `error_report` 元数据表；`userId + submissionId` 由唯一幂等键保证重放返回已有记录。完整事件、说明和日志只存在 OSS ZIP。 - `agc` 是服务端专用私有前缀；公共直传票据、通用 object-key 规范化和 legacy 公开路径均拒绝该前缀。归档内同名日志会自动加数字后缀，读取本机诊断日志时拒绝符号链接/非普通文件。 - 后台接口：`GET/PATCH /admin/api/error-reports/{batchId}`、`GET /admin/api/error-reports` 和受保护的 `/download`。列表支持 `limit`/`offset` 分页并返回 `total`、`hasMore`；OSS 读取先检查 `Content-Length` 并在流式累计超过上限时立即中止，不把超限对象完整缓存在内存中。 - 这些是 api-server 内部登录/管理员路由，不属于 `/api/external/v1`，不纳入 External OpenAPI；管理员详情对不存在返回 404，对归档/元数据损坏返回 500。 - admin viewer 仅接受 error-reports Tab 权限，支持列表筛选、分页、详情、状态 `new/in-progress/resolved`、处理备注和受控下载；不存在的更新目标返回 404，存储损坏返回 500。列表行支持键盘 Enter/Space 打开详情，详情事件预览最多显示 20 条，完整内容通过诊断包下载获取。 -- 管理员列表、筛选、状态和备注全部读取/更新 SpacetimeDB；错误报告的 list/get/update procedure 要求 `require_editor_generation_runtime_service_identity`，详情先读表再从 OSS 下载并解析 ZIP，下载接口直接从 OSS 返回 ZIP。无需新增管理员 DELETE HTTP 接口。每日清理任务按分页扫描全部报告，删除过期 OSS 对象后再删 DB；任一 DB 删除失败会保留错误并在后续周期重试。详情解析对解压后的 `events.jsonl` 设置 24 MiB（与请求体上限一致）与 100 条事件上限。管理员备注超过 2,000 字会被明确拒绝；内部 OSS 读写只允许 `agc/error-reports/v1/`。旧本地报告不迁移。 +- 管理员列表、筛选、状态和备注全部读取/更新 SpacetimeDB；错误报告的 list/get/update procedure 要求 `require_editor_generation_runtime_service_identity`，详情先读表再从 OSS 下载并解析 ZIP，下载接口直接从 OSS 返回 ZIP。PATCH 更新直接返回元数据，不重新下载归档；详情弹窗提供备注编辑器。无需新增管理员 DELETE HTTP 接口。每日清理任务按分页扫描全部报告，删除过期 OSS 对象后再删 DB；任一 DB 删除失败会保留错误并在后续周期重试。详情解析对解压后的 `events.jsonl` 设置 24 MiB（与请求体上限一致）与 100 条事件上限。管理员备注超过 2,000 字会被明确拒绝；module 同时校验固定 OSS key、SHA-256、归档大小和事件/日志计数上限；OSS 读取仅将明确不存在映射为 404，其余错误按请求无效或上游故障返回。内部 OSS 读写只允许 `agc/error-reports/v1/`。旧本地报告不迁移。 SpacetimeDB `error_report` 表字段：`batch_id` 主键、`user_id`、`submission_id`、`idempotency_key` 唯一键、`object_key`、`archive_sha256`、`archive_size_bytes`、`event_count`、`log_count`、首个 fingerprint/source、`review_status`、`admin_note`、`created_at`、`updated_at`；索引为 `(user_id, submission_id)`、`created_at`、`review_status`。