[已完成]新增 OpenAI Responses 兼容映射入口

[JAVA-LW]

Issue Metadata

• Title: [讨论]新增 OpenAI Responses 兼容映射入口
• Level: L3 Execution Task
• Grade: G3 Cross-Domain / Contract Decision
• Labels: type:feature, area:api, area:backend, level:l3, grade:g3, priority:p1, risk:high, size:m, phase:discussion, contract, needs-backend, needs-qa, child-issue
• Parent issue: [已完成]OpenAI Responses 与 Chat Completions 兼容入口工作流 #370
• Child issues: None.

Observed Facts

• api/apps/api-server/src/routes/application_public_api/mod.rs:25-38 currently mounts OpenAI Chat Completions compatible routes such as /chat/completions, /v1/chat/completions, model-list aliases, and Anthropic /v1/messages.
• api/crates/control-plane/src/application_public_api/compat/openai.rs:41-120 maps Chat Completions request shape into NativeRunRequest with query, model, history, conversation, response_mode, metadata, and compatibility_mode.
• api/crates/control-plane/src/application_public_api/run_service.rs:326-356 binds native public conversations from native request fields; external protocols must not own a second conversation truth layer.
• api/apps/api-server/src/application_public_docs.rs:1504-1522 currently documents /v1/chat/completions, /v1/models, and /v1/messages, but no /v1/responses operation.

Suspected Problems

• Chat Completions compatible clients do not get a protocol-native continuation cursor that maps cleanly to the next call, so callers may manually maintain 1flowbase conversation identifiers.
• Adding OpenAI Responses naively could accidentally make previous_response_id or OpenAI response state a second source of truth.

Non-negotiable Invariants

• 1flowbase Native API, native run records, native runtime events, and native conversation semantics are the only truth layer.
• OpenAI Chat Completions, OpenAI Responses, and Anthropic protocols are adapter projections only.
• Existing Chat Completions-compatible endpoints must keep working.
• previous_response_id is an external protocol cursor only; it must resolve back to 1flowbase native run/conversation/history semantics and must not introduce an OpenAI-owned conversation store.
• stream: true must use native streaming as the event source and only translate the outer SSE event shape.

Draft Hypotheses

• /v1/responses can be implemented as a new OpenAI-compatible route and mapping module that creates native public runs with compatibility_mode = openai-responses-v1.
• The Responses id can safely be derived from the 1flowbase native run id, then accepted later as previous_response_id after validating it belongs to the same API key/application through native public run lookup.
• If the native layer lacks enough previous-run context for continuation, the smallest acceptable fix is to add native-first continuation support, then project it through the Responses adapter.

Open Decisions

• Keep /v1/responses as the only new Responses endpoint in this task. Do not add /openai/v1/responses unless the issue is updated.
• Add /openai/v1/chat/completions as the requested prefixed Chat Completions alias while preserving existing Chat Completions routes. Do not remove old aliases.
• /openai/v1/models is not in this task unless implementation evidence shows the prefixed Chat Completions route is unusable for common clients without the matching model-list alias.

Bad Solutions

• Creating a separate OpenAI conversation/session table.
• Treating previous_response_id as internal truth instead of resolving it to native run state.
• Translating Chat Completions chunks directly as Responses SSE without checking native event semantics.
• Changing model-provider runtime protocol or LLM node behavior to satisfy only the OpenAI adapter.

Acceptance Evidence

• Existing /v1/chat/completions, /chat/completions, and /v1/models compatible route tests still pass.
• POST /openai/v1/chat/completions accepts the same body and auth behavior as existing Chat Completions and returns the same compatible response shape.
• POST /v1/responses supports blocking text input mapped through native run creation and returns an OpenAI Responses-shaped object whose id is derived from the native run id.
• POST /v1/responses with previous_response_id can continue from a prior Responses call without the caller manually sending a 1flowbase conversation id, while still using native run/history/conversation semantics.
• POST /v1/responses with stream: true emits Responses-shaped SSE events projected from native streaming events.
• API docs list the new Responses operation and the prefixed Chat Completions alias if docs are expected to expose aliases.
• Tests cover request mapping, previous response validation, blocking response projection, streaming projection, auth failure, and docs catalog/spec output.

Execution Boundary

• Main files / modules:
  • api/apps/api-server/src/routes/application_public_api/mod.rs
  • api/apps/api-server/src/routes/application_public_api/openai.rs or a new sibling Responses route module
  • api/crates/control-plane/src/application_public_api/compat/openai.rs or a new Responses mapping module
  • api/apps/api-server/src/routes/application_public_api/compat_sse.rs / native SSE projection code if streaming output needs a Responses event shape
  • api/apps/api-server/src/application_public_docs.rs
  • api/apps/api-server/src/_tests/application_public_api/compat_routes.rs
  • api/apps/api-server/src/_tests/application/application_api_docs_routes.rs
• Verification:
  • Targeted Rust tests for application_public_api::compat_routes
  • Targeted Rust tests for OpenAI-compatible mapping in control-plane
  • Targeted API docs route tests for the OpenAI-compatible category
• Stop / escalate if:
  • Previous response continuation requires a durable schema migration or a new canonical conversation model.
  • Native runtime events do not expose enough information to faithfully project Responses streaming events.
  • The task starts requiring frontend workflow changes beyond API docs exposure.
  • Compatibility requirements conflict with the invariant that native API is the only truth layer.

Lifecycle

• Current phase: phase:discussion
• Next gate: user confirms issue content, then update to phase:ready before implementation.
• Close condition: implementation and targeted QA evidence pass, then user accepts the behavior and contract.