GenarrativeAI/Genarrative
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: enrich image failure audit metadata

Browse Source
This commit is contained in:
kdletters
2026-05-28 14:50:13 +08:00
parent c8b36cf799
commit 771b0411a3
18 changed files with 234 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
.hermes/shared-memory/pitfalls.md
View File

@@ -23,6 +23,14 @@
- 验证：触发任一平台级异步失败时，页面应出现包含“错误来源”和“错误内容”的弹窗；复制内容应包含来源和错误正文；旧页面内错误 banner 不再重复出现。
- 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/platform-entry/PlatformErrorDialog.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
## VectorEngine 图片生成 SendRequest 超时要按传输失败排查
- 现象：`external_api_call_failure` 里看到 `failureStage=request_send`、`timeout=true`、`statusCode=null`、`errorSource=client error (SendRequest)`，前端只知道图片生成失败。
- 原因：`timeout=true` 来自 `reqwest::Error::is_timeout()`，不是业务代码固定写死；`SendRequest` 是 Hyper 发送请求阶段的错误来源标签，只说明请求未拿到可归类的 HTTP 响应，不会包含上游 JSON 错误体。
- 处理：先按 `provider/failureStage/statusClass` 聚合，再用 `user_id` / `profile_id` 和 `metadata_json.userId/profileId` 定位触发者与草稿 / 作品；`request_send + timeout=true` 优先查请求体大小、参考图数量、出口网络、代理/Nginx、VectorEngine 当时可用性和同一 request_id 日志。若记录有 `502` 或 `429 moderation_blocked`，按上游网关或审核失败另行处理，不要归到传输超时。
- 验证：`cargo check -p api-server --manifest-path server-rs/Cargo.toml`；查询 `tracking_event` 时失败记录应能看到触发者 `user_id` 和可用的 `profile_id`。
- 关联：`server-rs/crates/api-server/src/external_api_audit.rs`、`server-rs/crates/api-server/src/openai_image_generation.rs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
## “我的”页每日任务卡不要硬编码进度
- 现象：用户完成或领取每日任务后，任务中心弹窗里的任务状态已经变化，但“我的”页卡片仍显示 `0 / 1` 和“去完成”。

2
docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
View File

@@ -167,7 +167,7 @@ npm run check:server-rs-ddd
- Hyper3D / Rodin：只保留后端安全代理和旧数据兼容；Rodin 提交、状态、下载和响应解析归属 `platform-hyper3d`，`api-server/src/hyper3d_generation.rs` 只做路由、配置和错误 envelope 映射；新 Match3D 草稿和批量新增不再生成 GLB。
- 音频：视觉小说专用音频路由保留；VectorEngine Suno/Vidu provider 协议、任务提交/查询、音频 URL 提取、下载、MIME/extension 归一和 OSS put 请求准备归属 `platform-audio`。`api-server/src/vector_engine_audio_generation.rs` 只做路由、配置、计费、asset object confirm、entity binding 和错误 envelope 映射；拼图、抓大鹅和敲木鱼提示词生成音效入口暂时关闭，通用 `/api/creation/audio/*` 对这些目标返回 `410 Gone`。敲木鱼创作只接收上传 / 录音音频资产；未提供时由 `api-server` 写回内置默认木鱼音 `/wooden-fish/default-hit-sound.mp3`。
- OSS：私有 generated legacy path 进入浏览器前必须通过 `/api/assets/read-url` 换签；不要裸请求 `/generated-*`。
- 外部 API 失败审计：外部供应商调用未成功时，`api-server` 必须发送 OTLP 失败事件并写入 `tracking_event`。VectorEngine 图片 provider 在 `platform-image` 内输出结构化日志和 `PlatformImageFailureAudit`，覆盖 `request_send`、`response_body`、`upstream_status`、`response_parse`、`missing_image` 和 `image_download` 阶段；`api-server` 只把该 audit 映射成 `external_api_call_failure`，`scope_kind = module`、`scope_id = provider`、`module_key = external-api`。metadata 固定包含 provider、endpoint、operation、failureStage、statusCode、statusClass、timeout、retryable、errorMessage、latencyMs、promptChars、referenceImageCount、imageModel 和 rawExcerpt。入库优先复用 tracking outbox，outbox 不可写或保护阈值拒绝时回退同步写 SpacetimeDB；不得新增前端兜底或在 SpacetimeDB reducer 内做外部 I/O。
- 外部 API 失败审计：外部供应商调用未成功时，`api-server` 必须发送 OTLP 失败事件并写入 `tracking_event`。VectorEngine 图片 provider 在 `platform-image` 内输出结构化日志和 `PlatformImageFailureAudit`，覆盖 `request_send`、`response_body`、`upstream_status`、`response_parse`、`missing_image` 和 `image_download` 阶段；`api-server` 只把该 audit 映射成 `external_api_call_failure`，`scope_kind = module`、`scope_id = provider`、`module_key = external-api`。metadata 固定包含 provider、endpoint、operation、failureStage、statusCode、statusClass、timeout、retryable、errorMessage、latencyMs、promptChars、referenceImageCount、imageModel、rawExcerpt，以及在调用方可获得上下文时补充的 `userId`（触发者）和 `profileId`（草稿 / 作品 / 场景作用域）。图片生成入口应优先把 owner user id 和 profile id 透传到失败审计，不要只保留 provider 级聚合，否则很难按“谁触发、哪个作品触发”定位问题。入库优先复用 tracking outbox，outbox 不可写或保护阈值拒绝时回退同步写 SpacetimeDB；不得新增前端兜底或在 SpacetimeDB reducer 内做外部 I/O。
- 外部生成运行记录：所有外部生成编排的完成态统一写入 `tracking_event`，`event_key = external_generation_run`，`scope_kind = module`，`scope_id = provider`，`module_key = external-generation`。metadata 固定包含 `runId`、`provider`、`operation`、`requestLabel`、`requestPayload`、`status`、`success`、`failureReason`、`providerRequestId`、`resultPayload`、`startedAtMicros`、`completedAtMicros` 和 `durationMs`。这类记录只用于运行审计和排障，不再走 `ai_task` 旧表。
## SpacetimeDB 表目录

23
docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
View File

@@ -281,7 +281,7 @@ OpenTelemetry 现阶段默认开启 OTLP traces / metrics / logs，但本地日
- debug exporter / Rider 转发都会同时接收 traces、metrics 和 logs。
- api-server 会随 metrics 发送进程级指标：`process.memory.usage`、`process.memory.virtual`、`process.cpu.time`、`genarrative.process.cpu.usage_percent`、`process.thread.count`、`genarrative.process.memory.private`；Windows 额外发送 `process.windows.handle.count`，Linux 额外发送 `process.unix.file_descriptor.count`。这些指标只描述当前进程，不携带请求、用户或作品 label。
- HTTP 运行态补充发送 `genarrative.http.server.response_bodies.in_flight` 与 `genarrative.http.server.request_permits.available`，后者带低基数 `pool=default|gallery|detail|admin` label，用于区分业务 handler / 背压 permit 是否仍被占用；拼图广场热点缓存补充发送 `genarrative.puzzle_gallery.cache.*` 指标，记录 fresh hit、stale hit、未命中、后台刷新开始 / 失败、重建耗时和预序列化 data JSON 字节数。
- 外部 API 失败统一发送 OTLP 并落库。当前 VectorEngine `gpt-image-2` 图片生成 / 编辑失败由 `platform-image` provider 输出低基数字段结构化日志，字段包括 provider、endpoint、failure_stage、status、status_class、timeout、retryable、latency_ms、prompt_chars、reference_image_count、image_model 和 raw_excerpt；`api-server` 再记录指标 `genarrative.external_api.failures{provider,failure_stage,status_class,retryable}`，并写入 `tracking_event`，`event_key = external_api_call_failure`、`module_key = external-api`、`scope_kind = module`、`scope_id = provider`。排障时先按 provider / failureStage 聚合，再结合 request 日志和上游响应 excerpt 判断是限流、超时、解析失败还是未返回图片。
- 外部 API 失败统一发送 OTLP 并落库。当前 VectorEngine `gpt-image-2` 图片生成 / 编辑失败由 `platform-image` provider 输出低基数字段结构化日志，字段包括 provider、endpoint、failure_stage、status、status_class、timeout、retryable、latency_ms、prompt_chars、reference_image_count、image_model 和 raw_excerpt；`api-server` 再记录指标 `genarrative.external_api.failures{provider,failure_stage,status_class,retryable}`，并写入 `tracking_event`，`event_key = external_api_call_failure`、`module_key = external-api`、`scope_kind = module`、`scope_id = provider`。调用方能拿到身份上下文时，失败事件还会在行级 `user_id` / `owner_user_id` / `profile_id` 和 `metadata_json.userId` / `metadata_json.profileId` 中记录触发者与草稿 / 作品作用域。排障时先按 provider / failureStage 聚合，再下钻 userId / profileId，最后结合 request 日志和上游响应 excerpt 判断是限流、超时、解析失败还是未返回图片。
- SpacetimeDB 观测分为两类：procedure / reducer 调用继续用 `genarrative.spacetime.procedure.*`，订阅本地 cache 读使用 `genarrative.spacetime.read.*`。`read=list_puzzle_gallery` 表示拼图广场当前从 `puzzle_gallery_card_view` 本地 cache 读取，不再每个 HTTP 请求调用 `list_puzzle_gallery` procedure。
- 本地 Windows 直连压测的内存高水位要结合 K6 VU / 连接数解释。250 RPS 下过高 `PREALLOCATED_VUS` 可能让 300 个本地 Established 连接把 `api-server` private memory 瞬时推到 GB 级，且 `/healthz` 小响应也能复现；若压测结束后回落、`response_bodies.in_flight` 和背压 permit 未显示业务积压，应优先按连接 / 发送链路高水位处理，而不是判断为 SpacetimeDB 或 JSON 缓存泄漏。
- Rider 的 Logs 面板只展示 log event 自身字段，不会自动展开父 span 的全部 attributes；请求完成日志会直接带 `request_id`、`http.request.method`、`http.route`、`url.scheme`、`url.path`、`http.response.status_code`、`status_class`、`latency_ms` 和 `slow_request`，完整链路继续到 Traces 面板按 trace/span 查看。
@@ -340,7 +340,7 @@ cargo test -p platform-auth --manifest-path server-rs/Cargo.toml aliyun_send_sms
个人任务首版 scope 仅支持 `user`。后台、RPG、大鱼吃小鱼、Visual Novel、Story、Combat 等特定链路按 tracking 中间件排除规则处理；作品游玩统一使用 `work_play_start`。
外部 API 失败审计复用 `tracking_event`，不新增表。失败事件优先写入本机 tracking outbox，再由后台 worker 批量落库；如果 outbox 因权限、磁盘或保护阈值不可写，会回退同步直写 SpacetimeDB。`metadata_json` 包含 endpoint、operation、failureStage、statusCode、statusClass、timeout、retryable、errorMessage、latencyMs、promptChars、referenceImageCount、imageModel 和 rawExcerpt。常用查询：
外部 API 失败审计复用 `tracking_event`，不新增表。失败事件优先写入本机 tracking outbox，再由后台 worker 批量落库；如果 outbox 因权限、磁盘或保护阈值不可写，会回退同步直写 SpacetimeDB。`metadata_json` 包含 endpoint、operation、failureStage、statusCode、statusClass、timeout、retryable、errorMessage、latencyMs、promptChars、referenceImageCount、imageModel、rawExcerpt、userId 和 profileId；其中 `userId` 是触发生成的用户，`profileId` 是调用方传入的草稿 / 作品 / 场景作用域，入口拿不到上下文时允许为空。常用查询：
```sql
SELECT event_id, scope_id AS provider, metadata_json, occurred_at
@@ -350,6 +350,25 @@ ORDER BY occurred_at DESC
LIMIT 50;
```
按失败阶段、触发者和作品作用域聚合时：
```sql
SELECT
json_extract(metadata_json, '$.failureStage') AS failure_stage,
user_id,
profile_id,
COUNT(*) AS failures,
MIN(occurred_at) AS first_seen,
MAX(occurred_at) AS last_seen
FROM tracking_event
WHERE event_key = 'external_api_call_failure'
GROUP BY failure_stage, user_id, profile_id
ORDER BY failures DESC, last_seen DESC
LIMIT 100;
```
VectorEngine `request_send` 且 `timeout = true` 的记录表示 `reqwest::Error::is_timeout()` 判定为超时，常见于连接、发送请求体、等待上游首包或上游长时间无响应；`errorSource = client error (SendRequest)` 是 Hyper 发送请求阶段的错误来源标签，不等于最终根因。若 `statusCode` 为空，应优先查同一时间窗口的 `api-server` request 日志、Nginx / 出口网络、VectorEngine 可用性和请求体大小；若已有 `502`、`429 moderation_blocked` 等状态码，则按上游网关或内容审核失败单独处理，不要和传输超时混为一类。
tracking outbox 默认配置：
```env

5
server-rs/crates/api-server/src/bark_battle.rs
View File

@@ -1204,7 +1204,10 @@ async fn generate_and_persist_bark_battle_image_asset(
prompt: &str,
size: &str,
) -> Result<BarkBattleGeneratedImageAsset, AppError> {
let settings = require_openai_image_settings(state)?;
let settings = require_openai_image_settings(state)?.with_external_api_audit_context(
Some(owner_user_id.to_string()),
Some(draft_id.unwrap_or(asset_id).to_string()),
);
let http_client = build_openai_image_http_client(&settings)?;
let generated = create_openai_image_generation(
&http_client,

9
server-rs/crates/api-server/src/character_visual_assets.rs
View File

@@ -94,7 +94,9 @@ pub async fn generate_character_visual(
.map_err(|error| character_visual_error_response(&request_context, error))?;
let result = async {
let settings = require_openai_image_settings(&state)?;
let settings = require_openai_image_settings(&state)?
.with_external_api_audit_context(Some(owner_user_id.clone()), Some(character_id.clone()))
.with_external_api_audit_request_id(Some(request_context.request_id().to_string()));
let http_client = build_openai_image_http_client(&settings)?;
state
@@ -318,7 +320,10 @@ pub(crate) async fn generate_character_primary_visual_for_profile(
&model,
&prompt,
)?;
let settings = require_openai_image_settings(state)?;
let settings = require_openai_image_settings(state)?.with_external_api_audit_context(
Some(owner_user_id.to_string()),
Some(character_id.clone()),
);
let http_client = build_openai_image_http_client(&settings)?;
state
.ai_task_service()

19
server-rs/crates/api-server/src/custom_world_ai.rs
View File

@@ -553,7 +553,12 @@ pub async fn generate_custom_world_scene_image(
"scene_image",
asset_id.as_str(),
async {
let settings = require_openai_image_settings(&state)?;
let settings = require_openai_image_settings(&state)?
.with_external_api_audit_context(
Some(owner_user_id.to_string()),
normalized.profile_id.clone(),
)
.with_external_api_audit_request_id(Some(request_context.request_id().to_string()));
let http_client = build_openai_image_http_client(&settings)?;
let reference_image =
if let Some(reference_image_src) = normalized.reference_image_src.as_deref() {
@@ -675,7 +680,10 @@ pub(crate) async fn generate_custom_world_scene_image_for_profile(
}),
};
let normalized = normalize_scene_image_request(payload)?;
let settings = require_openai_image_settings(state)?;
let settings = require_openai_image_settings(state)?.with_external_api_audit_context(
Some(owner_user_id.to_string()),
normalized.profile_id.clone(),
);
let http_client = build_openai_image_http_client(&settings)?;
let generated = create_openai_image_generation(
&http_client,
@@ -1011,7 +1019,12 @@ pub async fn generate_custom_world_opening_cg(
opening_cg_id.as_str(),
OPENING_CG_POINTS_COST,
async {
let image_settings = require_openai_image_settings(&state)?;
let image_settings = require_openai_image_settings(&state)?
.with_external_api_audit_context(
Some(owner_user_id.clone()),
normalized.profile_id.clone(),
)
.with_external_api_audit_request_id(Some(request_context.request_id().to_string()));
let image_http_client = build_openai_image_http_client(&image_settings)?;
let video_settings = require_ark_video_settings(&state)?;
let video_http_client = build_upstream_http_client(video_settings.request_timeout_ms)?;

6
server-rs/crates/api-server/src/custom_world_ai/opening_cg.rs
View File

@@ -8,9 +8,13 @@ pub(super) async fn generate_opening_cg_storyboard(
normalized: &NormalizedOpeningCgRequest,
reference_images: &[String],
) -> Result<GeneratedOpeningCgStoryboard, AppError> {
let audit_settings = settings.clone().with_external_api_audit_context(
Some(owner_user_id.to_string()),
normalized.profile_id.clone(),
);
let generated = create_openai_image_generation(
http_client,
settings,
&audit_settings,
normalized.storyboard_prompt.as_str(),
None,
OPENING_CG_STORYBOARD_IMAGE_SIZE,

2
server-rs/crates/api-server/src/edutainment_baby_object.rs
View File

@@ -1050,6 +1050,8 @@ mod tests {
api_key: "secret".to_string(),
request_timeout_ms: 180_000,
external_api_audit_state: None,
external_api_audit_user_id: None,
external_api_audit_profile_id: None,
});
assert_eq!(

36
server-rs/crates/api-server/src/external_api_audit.rs
View File

@@ -27,6 +27,9 @@ pub(crate) struct ExternalApiFailureDraft {
pub(crate) prompt_chars: Option<usize>,
pub(crate) reference_image_count: Option<usize>,
pub(crate) image_model: Option<&'static str>,
pub(crate) user_id: Option<String>,
pub(crate) profile_id: Option<String>,
pub(crate) request_id: Option<String>,
}
impl ExternalApiFailureDraft {
@@ -53,6 +56,9 @@ impl ExternalApiFailureDraft {
prompt_chars: None,
reference_image_count: None,
image_model: None,
user_id: None,
profile_id: None,
request_id: None,
}
}
@@ -108,6 +114,21 @@ impl ExternalApiFailureDraft {
self.image_model = image_model;
self
}
pub(crate) fn with_user_id(mut self, user_id: Option<String>) -> Self {
self.user_id = user_id;
self
}
pub(crate) fn with_profile_id(mut self, profile_id: Option<String>) -> Self {
self.profile_id = profile_id;
self
}
pub(crate) fn with_request_id(mut self, request_id: Option<String>) -> Self {
self.request_id = request_id;
self
}
}
pub(crate) fn build_external_api_failure_draft_from_platform_image_audit(
@@ -130,6 +151,9 @@ pub(crate) fn build_external_api_failure_draft_from_platform_image_audit(
.with_prompt_chars(audit.prompt_chars)
.with_reference_image_count(audit.reference_image_count)
.with_image_model(audit.image_model)
.with_user_id(None)
.with_profile_id(None)
.with_request_id(None)
}
/// 中文注释：下载图片、OSS 读写等非标准 HTTP 状态统一显式归类，避免 OTLP 低基数 label 误落到 `transport`。
@@ -203,6 +227,9 @@ pub(crate) fn build_external_api_failure_tracking_draft(
);
draft.scope_kind = RuntimeTrackingScopeKind::Module;
draft.scope_id = failure.provider.to_string();
draft.user_id = failure.user_id.clone();
draft.owner_user_id = failure.user_id.clone();
draft.profile_id = failure.profile_id.clone();
draft.metadata = build_external_api_failure_metadata(failure);
draft
}
@@ -233,6 +260,15 @@ fn build_external_api_failure_metadata(failure: &ExternalApiFailureDraft) -> Val
if let Some(image_model) = failure.image_model {
metadata["imageModel"] = json!(image_model);
}
if let Some(user_id) = failure.user_id.as_deref().map(str::trim).filter(|value| !value.is_empty()) {
metadata["userId"] = json!(truncate_field(user_id, 1_000));
}
if let Some(profile_id) = failure.profile_id.as_deref().map(str::trim).filter(|value| !value.is_empty()) {
metadata["profileId"] = json!(truncate_field(profile_id, 1_000));
}
if let Some(request_id) = failure.request_id.as_deref().map(str::trim).filter(|value| !value.is_empty()) {
metadata["requestId"] = json!(truncate_field(request_id, 1_000));
}
if let Some(source) = failure
.error_source
.as_deref()

11
server-rs/crates/api-server/src/jump_hop.rs
View File

@@ -412,7 +412,16 @@ async fn maybe_generate_jump_hop_assets(
.unwrap_or_else(|| build_prefixed_uuid_id("jump-hop-profile-"));
payload.profile_id = Some(profile_id.clone());
let settings = require_openai_image_settings(state).map_err(|error| {
let settings = require_openai_image_settings(state)
.map(|settings| {
settings
.with_external_api_audit_context(
Some(owner_user_id.to_string()),
Some(profile_id.clone()),
)
.with_external_api_audit_request_id(Some(request_context.request_id().to_string()))
})
.map_err(|error| {
jump_hop_error_response(request_context, JUMP_HOP_CREATION_PROVIDER, error)
})?;
let http_client = build_openai_image_http_client(&settings).map_err(|error| {

5
server-rs/crates/api-server/src/match3d/item_assets.rs
View File

@@ -753,7 +753,10 @@ async fn generate_match3d_material_sheet_from_level_scene(
config: &Match3DConfigJson,
background_asset: Option<&Match3DGeneratedBackgroundAsset>,
) -> Result<Match3DMaterialSheet, AppError> {
let settings = require_openai_image_settings(state)?;
let settings = require_openai_image_settings(state)?.with_external_api_audit_context(
Some(owner_user_id.to_string()),
Some(profile_id.to_string()),
);
let http_client = build_openai_image_http_client(&settings)?;
let prompt = build_match3d_item_spritesheet_prompt();
let reference = load_match3d_level_scene_reference_image(state, background_asset).await?;

15
server-rs/crates/api-server/src/match3d/works.rs
View File

@@ -301,7 +301,10 @@ pub(super) async fn generate_match3d_cover_image_asset(
reference_image_srcs: Vec<String>,
) -> Result<Match3DAssetUpload, AppError> {
require_match3d_oss_client(state)?;
let settings = require_openai_image_settings(state)?;
let settings = require_openai_image_settings(state)?.with_external_api_audit_context(
Some(owner_user_id.to_string()),
Some(profile_id.to_string()),
);
let http_client = build_openai_image_http_client(&settings)?;
let cover_prompt = build_match3d_cover_generation_prompt(config, prompt);
let generated = if let Some(uploaded_image) = resolve_match3d_reference_image_for_edit(
@@ -448,7 +451,10 @@ pub(super) async fn generate_match3d_level_asset_bundle(
prompt: &str,
) -> Result<Match3DGeneratedBackgroundAsset, AppError> {
require_match3d_oss_client(state)?;
let settings = require_openai_image_settings(state)?;
let settings = require_openai_image_settings(state)?.with_external_api_audit_context(
Some(owner_user_id.to_string()),
Some(profile_id.to_string()),
);
let http_client = build_openai_image_http_client(&settings)?;
let level_scene_prompt = build_match3d_level_scene_generation_prompt(config);
@@ -590,7 +596,10 @@ pub(super) async fn generate_match3d_container_image(
prompt: &str,
) -> Result<Match3DGeneratedBackgroundAsset, AppError> {
require_match3d_oss_client(state)?;
let settings = require_openai_image_settings(state)?;
let settings = require_openai_image_settings(state)?.with_external_api_audit_context(
Some(owner_user_id.to_string()),
Some(profile_id.to_string()),
);
let http_client = build_openai_image_http_client(&settings)?;
let reference_image = load_match3d_container_reference_image()?;
let container_prompt = build_match3d_container_generation_prompt(config, prompt);

52
server-rs/crates/api-server/src/openai_image_generation.rs
View File

@@ -34,6 +34,9 @@ pub(crate) struct OpenAiImageSettings {
pub api_key: String,
pub request_timeout_ms: u64,
pub external_api_audit_state: Option<AppState>,
pub external_api_audit_user_id: Option<String>,
pub external_api_audit_profile_id: Option<String>,
pub external_api_audit_request_id: Option<String>,
}
impl std::fmt::Debug for OpenAiImageSettings {
@@ -47,6 +50,18 @@ impl std::fmt::Debug for OpenAiImageSettings {
"external_api_audit_enabled",
&self.external_api_audit_state.is_some(),
)
.field(
"external_api_audit_user_id",
&self.external_api_audit_user_id,
)
.field(
"external_api_audit_profile_id",
&self.external_api_audit_profile_id,
)
.field(
"external_api_audit_request_id",
&self.external_api_audit_request_id,
)
.finish()
}
}
@@ -87,6 +102,9 @@ pub(crate) fn require_openai_image_settings(
api_key: api_key.to_string(),
request_timeout_ms: state.config.vector_engine_image_request_timeout_ms.max(1),
external_api_audit_state: Some(state.clone()),
external_api_audit_user_id: None,
external_api_audit_profile_id: None,
external_api_audit_request_id: None,
})
}
@@ -240,6 +258,21 @@ pub(crate) fn build_openai_image_request_body(
}
impl OpenAiImageSettings {
pub(crate) fn with_external_api_audit_context(
mut self,
user_id: Option<String>,
profile_id: Option<String>,
) -> Self {
self.external_api_audit_user_id = user_id;
self.external_api_audit_profile_id = profile_id;
self
}
pub(crate) fn with_external_api_audit_request_id(mut self, request_id: Option<String>) -> Self {
self.external_api_audit_request_id = request_id;
self
}
fn provider_settings(&self) -> VectorEngineImageSettings {
VectorEngineImageSettings {
base_url: self.base_url.clone(),
@@ -310,6 +343,10 @@ pub(crate) async fn record_openai_image_failure_if_configured(
let Some(draft) = build_openai_image_failure_audit_draft(error) else {
return;
};
let draft = draft
.with_user_id(settings.external_api_audit_user_id.clone())
.with_profile_id(settings.external_api_audit_profile_id.clone())
.with_request_id(settings.external_api_audit_request_id.clone());
record_external_api_failure(state, draft).await;
}
@@ -422,12 +459,18 @@ mod tests {
api_key: "test-key".to_string(),
request_timeout_ms: 1_000_000,
external_api_audit_state: None,
external_api_audit_user_id: None,
external_api_audit_profile_id: None,
external_api_audit_request_id: None,
};
let v1_settings = OpenAiImageSettings {
base_url: "https://vector.example/v1".to_string(),
api_key: "test-key".to_string(),
request_timeout_ms: 1_000_000,
external_api_audit_state: None,
external_api_audit_user_id: None,
external_api_audit_profile_id: None,
external_api_audit_request_id: None,
};
assert_eq!(
@@ -447,12 +490,18 @@ mod tests {
api_key: "test-key".to_string(),
request_timeout_ms: 1_000_000,
external_api_audit_state: None,
external_api_audit_user_id: None,
external_api_audit_profile_id: None,
external_api_audit_request_id: None,
};
let v1_settings = OpenAiImageSettings {
base_url: "https://vector.example/v1".to_string(),
api_key: "test-key".to_string(),
request_timeout_ms: 1_000_000,
external_api_audit_state: None,
external_api_audit_user_id: None,
external_api_audit_profile_id: None,
external_api_audit_request_id: None,
};
assert_eq!(
@@ -472,6 +521,9 @@ mod tests {
api_key: "test-key".to_string(),
request_timeout_ms: 1_000_000,
external_api_audit_state: None,
external_api_audit_user_id: None,
external_api_audit_profile_id: None,
external_api_audit_request_id: None,
};
let http_client = reqwest::Client::new();

11
server-rs/crates/api-server/src/puzzle/draft.rs
View File

@@ -1085,6 +1085,7 @@ pub(crate) fn attach_puzzle_level_asset_bundle(
pub(crate) async fn generate_puzzle_initial_ui_background_required(
state: &PuzzleApiState,
request_context: &RequestContext,
owner_user_id: &str,
session_id: &str,
draft: &PuzzleResultDraftRecord,
@@ -1093,6 +1094,7 @@ pub(crate) async fn generate_puzzle_initial_ui_background_required(
let prompt = resolve_puzzle_initial_ui_background_prompt(draft, target_level);
let generated = generate_puzzle_ui_background_image(
state,
request_context,
owner_user_id,
session_id,
target_level.level_name.as_str(),
@@ -1104,6 +1106,7 @@ pub(crate) async fn generate_puzzle_initial_ui_background_required(
pub(crate) async fn generate_puzzle_level_asset_bundle_required(
state: &PuzzleApiState,
request_context: &RequestContext,
owner_user_id: &str,
session_id: &str,
target_level: &PuzzleDraftLevelRecord,
@@ -1111,6 +1114,7 @@ pub(crate) async fn generate_puzzle_level_asset_bundle_required(
) -> Result<GeneratedPuzzleLevelAssetBundle, AppError> {
generate_puzzle_level_asset_bundle(
state,
request_context,
owner_user_id,
session_id,
target_level.level_name.as_str(),
@@ -1175,6 +1179,7 @@ pub(crate) fn find_puzzle_level_for_initial_asset_check<'a>(
pub(crate) async fn compile_puzzle_draft_with_initial_cover(
state: &PuzzleApiState,
request_context: &RequestContext,
session_id: String,
owner_user_id: String,
prompt_text: Option<&str>,
@@ -1195,6 +1200,7 @@ pub(crate) async fn compile_puzzle_draft_with_initial_cover(
})?;
let mut target_level = select_puzzle_level_for_api(&draft, None)?;
let fallback_level_name = target_level.level_name.clone();
let (_, profile_id) = build_stable_puzzle_work_ids(&compiled_session.session_id);
let image_prompt = resolve_puzzle_draft_cover_prompt(
prompt_text,
&target_level.picture_description,
@@ -1209,6 +1215,7 @@ pub(crate) async fn compile_puzzle_draft_with_initial_cover(
let mut candidates = generate_puzzle_image_candidates(
state,
owner_user_id.as_str(),
Some(profile_id.as_str()),
&compiled_session.session_id,
&target_level.level_name,
&image_prompt,
@@ -1262,6 +1269,7 @@ pub(crate) async fn compile_puzzle_draft_with_initial_cover(
{
let asset_bundle = generate_puzzle_level_asset_bundle_required(
state,
request_context,
owner_user_id.as_str(),
compiled_session.session_id.as_str(),
&target_level,
@@ -1369,7 +1377,6 @@ pub(crate) async fn compile_puzzle_draft_with_initial_cover(
Err(error)
}
})?;
let (_, profile_id) = build_stable_puzzle_work_ids(&compiled_session.session_id);
match state
.spacetime_client()
.update_puzzle_work(PuzzleWorkUpsertRecordInput {
@@ -1441,6 +1448,7 @@ pub(crate) async fn compile_puzzle_draft_with_initial_cover(
pub(crate) async fn compile_puzzle_draft_with_uploaded_cover(
state: &PuzzleApiState,
request_context: &RequestContext,
session_id: String,
owner_user_id: String,
prompt_text: Option<&str>,
@@ -1544,6 +1552,7 @@ pub(crate) async fn compile_puzzle_draft_with_uploaded_cover(
.await?;
let asset_bundle = generate_puzzle_level_asset_bundle_required(
state,
request_context,
owner_user_id.as_str(),
compiled_session.session_id.as_str(),
&target_level,

18
server-rs/crates/api-server/src/puzzle/generation.rs
View File

@@ -78,6 +78,7 @@ pub(crate) async fn create_uploaded_puzzle_image_candidate(
pub(crate) async fn generate_puzzle_image_candidates(
state: &PuzzleApiState,
owner_user_id: &str,
profile_id: Option<&str>,
session_id: &str,
level_name: &str,
prompt: &str,
@@ -150,6 +151,11 @@ pub(crate) async fn generate_puzzle_image_candidates(
// 中文注释：SpacetimeDB reducer 不能做外部 I/O，参考图读取与外部生图都必须停留在 api-server。
// 中文注释：拼图作品资产统一按 1:1 正方形生成，前端运行时也按正方形棋盘切块承载。
let settings = require_puzzle_vector_engine_settings(state)?;
let settings = PuzzleVectorEngineSettings {
external_api_audit_user_id: Some(owner_user_id.to_string()),
external_api_audit_profile_id: profile_id.map(ToOwned::to_owned),
..settings
};
let vector_engine_started_at = Instant::now();
let generated = if should_use_reference_image_generation {
let reference_image = reference_image.as_ref().ok_or_else(|| {
@@ -255,12 +261,18 @@ pub(crate) async fn generate_puzzle_image_candidates(
pub(crate) async fn generate_puzzle_ui_background_image(
state: &PuzzleApiState,
request_context: &RequestContext,
owner_user_id: &str,
session_id: &str,
level_name: &str,
prompt: &str,
) -> Result<GeneratedPuzzleUiBackgroundResponse, AppError> {
let settings = require_openai_image_settings(state.root_state())?;
let settings = require_openai_image_settings(state.root_state())?
.with_external_api_audit_context(
Some(owner_user_id.to_string()),
Some(session_id.to_string()),
)
.with_external_api_audit_request_id(Some(request_context.request_id().to_string()));
let http_client = build_openai_image_http_client(&settings)?;
let generated = create_openai_image_generation(
&http_client,
@@ -292,12 +304,14 @@ pub(crate) async fn generate_puzzle_ui_background_image(
pub(crate) async fn generate_puzzle_level_asset_bundle(
state: &PuzzleApiState,
request_context: &RequestContext,
owner_user_id: &str,
session_id: &str,
level_name: &str,
puzzle_image: &PuzzleDownloadedImage,
) -> Result<GeneratedPuzzleLevelAssetBundle, AppError> {
let settings = require_puzzle_vector_engine_settings(state)?;
let settings = require_puzzle_vector_engine_settings(state)?
.with_external_api_audit_request_id(Some(request_context.request_id().to_string()));
let http_client = build_puzzle_image_http_client(state, PuzzleImageModel::GptImage2)?;
let puzzle_reference = build_puzzle_downloaded_image_reference(puzzle_image);
let scene_generated = create_puzzle_vector_engine_image_generation(

10
server-rs/crates/api-server/src/puzzle/handlers.rs
View File

@@ -71,12 +71,14 @@ pub async fn generate_puzzle_onboarding_work(
let now = current_utc_micros();
let session_id = build_prefixed_uuid_id("puzzle-onboarding-");
let onboarding_profile_id = format!("onboarding-profile-{now}");
let naming = generate_puzzle_first_level_name(&state, prompt_text.as_str()).await;
let tags =
generate_puzzle_work_tags(&state, naming.level_name.as_str(), prompt_text.as_str()).await;
let candidates = generate_puzzle_image_candidates(
&state,
"onboarding-guest",
Some(onboarding_profile_id.as_str()),
session_id.as_str(),
naming.level_name.as_str(),
prompt_text.as_str(),
@@ -132,7 +134,7 @@ pub async fn generate_puzzle_onboarding_work(
));
let item = PuzzleWorkProfileRecord {
work_id: format!("onboarding-work-{now}"),
profile_id: format!("onboarding-profile-{now}"),
profile_id: onboarding_profile_id,
owner_user_id: "onboarding-guest".to_string(),
source_session_id: None,
author_display_name: "陶泥儿主".to_string(),
@@ -675,6 +677,7 @@ pub async fn execute_puzzle_agent_action(
async {
compile_puzzle_draft_with_initial_cover(
&state,
&request_context,
compile_session_id.clone(),
owner_user_id.clone(),
prompt_text,
@@ -689,6 +692,7 @@ pub async fn execute_puzzle_agent_action(
} else {
compile_puzzle_draft_with_uploaded_cover(
&state,
&request_context,
compile_session_id.clone(),
owner_user_id.clone(),
prompt_text,
@@ -861,9 +865,11 @@ pub async fn execute_puzzle_agent_action(
.await?,
]
} else {
let (_, profile_id) = build_stable_puzzle_work_ids(&session.session_id);
generate_puzzle_image_candidates(
&state,
owner_user_id.as_str(),
Some(profile_id.as_str()),
&session.session_id,
&target_level.level_name,
&prompt,
@@ -920,6 +926,7 @@ pub async fn execute_puzzle_agent_action(
})?;
let asset_bundle = generate_puzzle_level_asset_bundle_required(
&state,
&request_context,
owner_user_id.as_str(),
&session.session_id,
&target_level,
@@ -1079,6 +1086,7 @@ pub async fn execute_puzzle_agent_action(
);
let generated = generate_puzzle_ui_background_image(
&state,
&request_context,
owner_user_id.as_str(),
&session.session_id,
&target_level.level_name,

17
server-rs/crates/api-server/src/puzzle/vector_engine.rs
View File

@@ -31,6 +31,9 @@ pub(crate) struct PuzzleVectorEngineSettings {
pub(crate) api_key: String,
pub(crate) request_timeout_ms: u64,
pub(crate) external_api_audit_state: Option<AppState>,
pub(crate) external_api_audit_user_id: Option<String>,
pub(crate) external_api_audit_profile_id: Option<String>,
pub(crate) external_api_audit_request_id: Option<String>,
}
pub(crate) struct PuzzleGeneratedImages {
@@ -100,8 +103,19 @@ impl PuzzleVectorEngineSettings {
api_key: self.api_key.clone(),
request_timeout_ms: self.request_timeout_ms,
external_api_audit_state: self.external_api_audit_state.clone(),
external_api_audit_user_id: self.external_api_audit_user_id.clone(),
external_api_audit_profile_id: self.external_api_audit_profile_id.clone(),
external_api_audit_request_id: self.external_api_audit_request_id.clone(),
}
}
pub(crate) fn with_external_api_audit_request_id(
mut self,
request_id: Option<String>,
) -> Self {
self.external_api_audit_request_id = request_id;
self
}
}
pub(crate) struct ParsedPuzzleImageDataUrl {
@@ -177,6 +191,9 @@ pub(crate) fn require_puzzle_vector_engine_settings(
api_key: api_key.to_string(),
request_timeout_ms: state.vector_engine_image_request_timeout_ms().max(1),
external_api_audit_state: Some(state.root_state().clone()),
external_api_audit_user_id: None,
external_api_audit_profile_id: None,
external_api_audit_request_id: None,
})
}

5
server-rs/crates/api-server/src/square_hole/visual_assets.rs
View File

@@ -389,7 +389,10 @@ async fn generate_square_hole_image_data_url(
size: &str,
failure_context: &str,
) -> Result<String, AppError> {
let settings = require_openai_image_settings(state)?;
let settings = require_openai_image_settings(state)?.with_external_api_audit_context(
Some(owner_user_id.to_string()),
Some(profile_id.to_string()),
);
let http_client = build_openai_image_http_client(&settings)?;
let generated = create_openai_image_generation(
&http_client,