fix(txn+security): 仓储改 flush + 启动校验/兜底 + job.error 脱敏 + SSE 异常硬化

P0-1 SqlCredentialStore/save_draft 由自提交改 flush，端点/服务统一 commit
  （新增 CredentialStore.commit() 统一提交点；token 刷新落库显式提交）；
  补多凭据一请求中途失败整体回滚集成测试。
P0-2 启动校验 _fernet(enc_key) 快速失败 + catch-all Exception → ErrorEnvelope；
  credential_enc_key 改 SecretStr。
P0-3 run_job 异常分类：AppError 存 code+message，其余存通用文案不泄 str(exc)。
P0-4 评审/正文 SSE 失败先发 error 事件，尾部 commit 包 try/except。
P1-4 max_version 加 FOR UPDATE 行锁消除 TOCTOU。
P1-5 scan_overdue 谓词下推 + 批量 UPDATE RETURNING。
P1-10 移除 OAuth user_code 日志。
P2 provider_deps 改调网关 build_adapter；accept_service Committable Protocol；
  CORS 白名单收窄；request_id 安全字符集白名单；stdlib 日志接管；读端点 404 校验；
  httpx timeout；测试用合法 Fernet key；类型化响应模型(JobResponse/DimensionEntry/
  ReviewConflictView/selling_points)+路由 ErrorEnvelope responses（供 codegen）。

apps/api/ww_api/services/accept_service.py

@@ -15,6 +15,7 @@ from __future__ import annotations
 
 import uuid
 from dataclasses import dataclass
+from typing import Protocol
 
 import structlog
 from ww_core.domain.chapter_repo import ChapterRepo
@@ -27,6 +28,15 @@ from ww_api.schemas.projects import ConflictDecision
 log = structlog.get_logger(__name__)
 
 
+class Committable(Protocol):
+    """验收事务对 session 的**最小**依赖：仅需 `commit()`（去掉 object + type ignore）。
+
+    真实运行注 `AsyncSession`；测试注 fake session（同形即可）——两者都满足本 Protocol。
+    """
+
+    async def commit(self) -> None: ...
+
+
 @dataclass(frozen=True)
 class AcceptOutcome:
     """验收事务结果（供端点组「本次将更新」清单）。"""
@@ -82,7 +92,7 @@ def _serialize_decisions(
 
 async def run_accept_transaction(
     *,
-    session: object,
+    session: Committable,
     chapter_repo: ChapterRepo,
     digest_repo: DigestAppendRepo,
     review_repo: ReviewRepo,
@@ -97,7 +107,8 @@ async def run_accept_transaction(
 
     `digest_facts` 已在事务外提炼好（R2）。各 repo 写方法只 flush；本函数统一在末尾
     `await session.commit()`，任一步抛错由调用方/上下文回滚（不显式半提交）。
-    `session` 类型用 object 以免绑定 SQLAlchemy（测试注入 fake session 亦可）。
+    `session` 用最小 `Committable` Protocol（只需 `commit()`）以免绑定 SQLAlchemy，
+    测试注入 fake session 亦满足（去掉了 `object` + `type: ignore`）。
     """
     # 步骤 1：终稿晋升 accepted 新 version（max+1，草稿行保留，R4）。
     chapter = await chapter_repo.promote_to_accepted(project_id, chapter_no, content=final_text)
@@ -120,7 +131,7 @@ async def run_accept_transaction(
     # 的副作用、且自建独立 session（请求 session 此时已关闭）。
     # 人物 latest_state 更新仍留后续（M4+）：本事务只落晋升 + digest + 裁决留痕。
 
-    await session.commit()  # type: ignore[attr-defined]  # AsyncSession.commit()（fake 同形）
+    await session.commit()
 
     log.info(
         "chapter_accepted",

apps/api/ww_api/services/credentials.py

@@ -49,7 +49,12 @@ class StoredRouting:
 
 
 class CredentialStore(Protocol):
-    """凭据 + 档位路由的读写接口（按 owner_id 隔离）。"""
+    """凭据 + 档位路由的读写接口（按 owner_id 隔离）。
+
+    写方法（upsert/delete）**只 flush 不 commit**——提交交调用方（端点/服务）经
+    `commit()` 统一一次，保证「多凭据一请求」的原子性（任一步失败整体回滚，不留半更新）。
+    无 session 句柄的服务侧调用方（如 token 刷新落库）则直接调 `commit()`。
+    """
 
     async def list_credentials(self, owner_id: uuid.UUID) -> list[StoredCredential]: ...
 
@@ -71,6 +76,8 @@ class CredentialStore(Protocol):
 
     async def upsert_routing(self, routing: StoredRouting) -> None: ...
 
+    async def commit(self) -> None: ...
+
 
 class ProviderProbe(Protocol):
     """最小连通探测：验证 Key + 返回能力矩阵。测试注入假探测，绝不联网。"""
@@ -156,7 +163,8 @@ class SqlCredentialStore:
             existing.api_key_enc = api_key_enc
             existing.auth_type = AUTH_TYPE_API_KEY
             existing.oauth_enc = None
-        await self._session.commit()
+        # 仓储只 flush，提交交调用方（端点/服务）统一一次——保证多凭据一请求的原子性。
+        await self._session.flush()
 
     async def upsert_oauth_credential(
         self, owner_id: uuid.UUID, provider: str, oauth_enc: bytes
@@ -191,7 +199,8 @@ class SqlCredentialStore:
             existing.api_key_enc = None
             existing.auth_type = AUTH_TYPE_OAUTH
             existing.oauth_enc = oauth_enc
-        await self._session.commit()
+        # 仓储只 flush，提交交调用方统一一次。
+        await self._session.flush()
 
     async def delete_credential(self, owner_id: uuid.UUID, provider: str) -> bool:
         """删除凭据行（OAuth disconnect / 撤销）。返回是否删到行。"""
@@ -207,7 +216,8 @@ class SqlCredentialStore:
         if existing is None:
             return False
         await self._session.delete(existing)
-        await self._session.commit()
+        # 仓储只 flush，提交交调用方统一一次。
+        await self._session.flush()
         return True
 
     async def upsert_routing(self, routing: StoredRouting) -> None:
@@ -233,4 +243,9 @@ class SqlCredentialStore:
             existing.provider = routing.provider
             existing.model = routing.model
             existing.fallback = routing.fallback
+        # 仓储只 flush，提交交调用方统一一次。
+        await self._session.flush()
+
+    async def commit(self) -> None:
+        """统一提交点：端点/服务侧在一组 flush 后调一次，落库所有挂起写入。"""
         await self._session.commit()

apps/api/ww_api/services/job_runner.py

@@ -25,9 +25,13 @@ from typing import Any, Protocol
 import structlog
 from sqlalchemy.ext.asyncio import AsyncSession
 from ww_core.domain.job_repo import JobView, SqlJobRepo
+from ww_shared import AppError
 
 from ww_api.services.foreshadow_scan import SessionFactory
 
+# 非 AppError 异常落库的通用文案（绝不回传 str(exc)，避免泄露内部细节，P0-3）。
+_GENERIC_JOB_ERROR = "任务执行失败"
+
 log = structlog.get_logger(__name__)
 
 # 业务工作缝：拿 session 跑真正的长任务，返回写回 job.result 的摘要 dict。
@@ -63,7 +67,8 @@ async def run_job(
     """跑一个长任务：新建独立 session → set_running → await work → complete/fail → commit。
 
     成功：`complete(job_id, result)`（status=done, progress=100, result=work 返回值）后 commit。
-    异常：回滚 work 的部分写 → 新 session 里 `fail(job_id, str(exc))` → commit（job 失败可见）。
+    异常分类落库（P0-3）：`AppError` 存其 `code: message`（已是面向用户的安全文案）；其余
+    `Exception` 存通用「任务执行失败」——**绝不**把 `str(exc)` 落库/回传前端（防泄露内部细节）。
     任何异常都被吞（后台任务边界，不冒泡崩进程）；失败置态本身再炸只记日志。
     `session_factory`/`repo_factory` 是可注入缝：测试直接 await、注 fake，绝不联网/起线程。
     """
@@ -76,8 +81,21 @@ async def run_job(
             await session.commit()
         log.info("job_done", job_id=str(job_id), request_id=request_id)
     except Exception as exc:  # noqa: BLE001 — 后台任务边界：记错误 + 置 job failed，不冒泡。
+        # 服务端日志记完整错误（含原始异常）；落库的 job.error 经分类脱敏。
         log.error("job_failed", job_id=str(job_id), request_id=request_id, error=str(exc))
-        await _mark_failed(session_factory, job_id, str(exc), repo_factory, request_id)
+        stored_error = _classify_job_error(exc)
+        await _mark_failed(session_factory, job_id, stored_error, repo_factory, request_id)
+
+
+def _classify_job_error(exc: Exception) -> str:
+    """把异常映射为可安全落库/回传前端的错误文案（P0-3）。
+
+    `AppError` 的 `message` 是设计为面向用户的安全文案，连同 `code` 一起呈现；其余异常一律
+    用通用文案，**绝不**回传 `str(exc)`（可能含解密失败提示/内部路径等敏感信息）。
+    """
+    if isinstance(exc, AppError):
+        return f"{exc.code}: {exc.message}"
+    return _GENERIC_JOB_ERROR
 
 
 async def _mark_failed(

apps/api/ww_api/services/project_deps.py

@@ -264,7 +264,9 @@ async def _build_provider_adapter(store: CredentialStore, provider: str) -> Prov
     if cred.auth_type == AUTH_TYPE_OAUTH or provider == KIMI_CODE_PROVIDER:
         # OAuth 凭据（Kimi Code）：解密 token 包 → 临近过期则刷新并持久化 → access token
         # 当 api_key 喂工厂（工厂为 kimi-code 构建带伪造头 + coding base 的客户端）。
-        access_token = await _resolve_kimi_code_token(store, cred, settings.credential_enc_key)
+        access_token = await _resolve_kimi_code_token(
+            store, cred, settings.credential_enc_key.get_secret_value()
+        )
         return build_adapter(
             provider, api_key=access_token, base_url=_PROVIDER_BASE_URLS.get(provider)
         )
@@ -273,7 +275,9 @@ async def _build_provider_adapter(store: CredentialStore, provider: str) -> Prov
         # api_key 凭据但密文缺失（数据不一致）——视作未配置，回退链跳过。
         return None
     try:
-        api_key = decrypt_api_key(cred.api_key_enc, key=settings.credential_enc_key)
+        api_key = decrypt_api_key(
+            cred.api_key_enc, key=settings.credential_enc_key.get_secret_value()
+        )
     except CredentialKeyError as exc:
         raise AppError(ErrorCode.INTERNAL, str(exc)) from exc
     # OpenAI 兼容 provider 需 base_url；Anthropic/Gemini 走原生 SDK（base_url=None）。
@@ -305,10 +309,12 @@ async def _resolve_kimi_code_token(
         return token.access_token
 
     # 临近过期 → 刷新并持久化新包。
-    async with httpx.AsyncClient() as http:
+    async with httpx.AsyncClient(timeout=30.0) as http:
         refreshed = await kimi_refresh(http, token.refresh_token)
     new_blob = encrypt_oauth_bundle(refreshed, key=enc_key)
     await store.upsert_oauth_credential(STUB_OWNER_ID, KIMI_CODE_PROVIDER, new_blob)
+    # token 刷新是独立可持久的副作用（下次建网关复用），须立即提交，不依赖请求后续是否提交。
+    await store.commit()
     return refreshed.access_token
 
 

apps/api/ww_api/services/provider_deps.py

@@ -10,12 +10,11 @@ import uuid
 from typing import Annotated
 
 from fastapi import Depends
-from openai import AsyncOpenAI
 from sqlalchemy.ext.asyncio import AsyncSession
 from ww_config import get_settings
 from ww_db import get_session
 from ww_llm_gateway.adapters.base import Capabilities
-from ww_llm_gateway.adapters.openai_compat import OpenAICompatAdapter
+from ww_llm_gateway.factory import build_adapter
 from ww_shared import AppError, ErrorCode
 
 from ww_api.security.credentials import (
@@ -84,11 +83,12 @@ class GatewayProviderProbe:
         except CredentialKeyError as exc:
             raise AppError(ErrorCode.INTERNAL, str(exc)) from exc
 
-        client = AsyncOpenAI(api_key=api_key, base_url=base_url)
-        adapter = OpenAICompatAdapter(provider=provider, client=client)
+        # 经网关工厂构造适配器（base_url 单点归网关 build_adapter，不在此本地构造 AsyncOpenAI）。
+        adapter = build_adapter(provider, api_key=api_key, base_url=base_url)
         try:
-            # 最小探测：列模型即可验证 Key 有效（不消耗生成额度）。
-            await client.models.list()
+            # 最小探测：列模型即可验证 Key 有效（不消耗生成额度）。底层 AsyncOpenAI 由适配器持有
+            # （已知 provider 为 OpenAI 兼容，见 _PROVIDER_BASE_URLS）；读私有客户端属同仓既有约定。
+            await adapter._client.models.list()  # type: ignore[attr-defined]  # noqa: SLF001
         except Exception as exc:  # noqa: BLE001 — 任一失败都映射为 LLM 不可用
             raise AppError(
                 ErrorCode.LLM_UNAVAILABLE,
@@ -101,4 +101,4 @@ class GatewayProviderProbe:
 def get_provider_probe(
     store: Annotated[CredentialStore, Depends(get_credential_store)],
 ) -> GatewayProviderProbe:
-    return GatewayProviderProbe(store, get_settings().credential_enc_key)
+    return GatewayProviderProbe(store, get_settings().credential_enc_key.get_secret_value())