lzf_0626
eded5896cd
## 问题
`agent_reply_template.scene` 有数据库 CHECK 约束 `chk_template_scene`，只允许
`disclaimer` / `low_confidence` / `compliance_block` / `transfer` / `model_failure` /
`system_busy` / `clarification` 七个值。
而 `ReplyPayload.scene` 只校验长度（`min_length=1, max_length=32`）——
传一个不在列内的场景会**穿过接口校验、撞上数据库约束**，最终以
`500` 冒出：
(3819, "Check constraint 'chk_template_scene' is violated.")
那本该是一次 `422` 参数校验失败。**500 与 422 的差别不只是状态码**：
前者会让调用方以为服务端故障、触发重试与告警，而实际是自己参数错了。
## 改动
`ReplyPayload.scene` 改为 `Literal[...]`（新增 `ReplyScene` 类型别名），
取值与 `chk_template_scene` **逐字对齐**，并在注释里写明这个对齐关系与本次事故。
实测：非法 scene → `422 AGENT_INPUT_INVALID`（不再是 500）；合法 scene → `201`。
## 发现方式
这一处是**按接口逐条调用、逐个核对返回**时暴露的 —— 只看代码很难注意到
"schema 的宽松校验"与"数据库的严格约束"之间那道缝。同类风险仍存在：
凡是**表上有 CHECK 而 schema 只做长度校验**的字段，都有同样的 500 风险。
验证：unit+contract 1397 passed；integration 110 passed；ruff 通过；
mypy 251 文件 0 错；e2e 冒烟 40/40。
126 lines
5.0 KiB
Python
126 lines
5.0 KiB
Python
from typing import Any, Literal
|
|
|
|
from pydantic import BaseModel, ConfigDict, Field, HttpUrl
|
|
|
|
|
|
class StrictPayload(BaseModel):
|
|
model_config = ConfigDict(extra="forbid")
|
|
|
|
|
|
class ReleasePayload(StrictPayload):
|
|
release_no: str = Field(min_length=1, max_length=64)
|
|
title: str = Field(min_length=1, max_length=128)
|
|
change_summary: str = Field(min_length=1, max_length=1000)
|
|
|
|
|
|
class ItemPayload(StrictPayload):
|
|
# `fund_market` 必须在列内：`admin_service` 有专门的 `FUND_MARKET_FIELDS` 校验与
|
|
# `namespace=fund_market / config_key=default` 读取路径，缺了它会让行情配置
|
|
# 走 API 一律 422、只能靠工具内默认值运行（曾因此被回退过一次）。
|
|
namespace: Literal["agent_tools", "memory", "relationship", "runtime", "fund_market"]
|
|
item_key: str = Field(min_length=1, max_length=128)
|
|
value_json: dict[str, Any]
|
|
schema_version: Literal["1"] = "1"
|
|
|
|
|
|
class EndpointPayload(StrictPayload):
|
|
endpoint_code: str = Field(min_length=1, max_length=64)
|
|
provider: str = Field(min_length=1, max_length=32)
|
|
model_name: str = Field(min_length=1, max_length=128)
|
|
base_url: HttpUrl
|
|
secret_ref: str = Field(pattern=r"^env:[A-Z][A-Z0-9_]{0,100}$")
|
|
capabilities: list[str] = Field(min_length=1, max_length=20)
|
|
allowed_data_levels: list[str] = Field(min_length=1, max_length=20)
|
|
context_window: int = Field(gt=0)
|
|
timeout_ms: int = Field(default=15000, ge=100, le=120000)
|
|
|
|
|
|
class FallbackPayload(StrictPayload):
|
|
endpoint_id: int = Field(gt=0)
|
|
fallback_order: int = Field(ge=1, le=2)
|
|
retryable_error_codes: list[str] = Field(default_factory=list)
|
|
|
|
|
|
class RoutingPayload(StrictPayload):
|
|
rule_code: str = Field(min_length=1, max_length=64)
|
|
agent_type: str = Field(min_length=2, max_length=32)
|
|
task_type: str = Field(min_length=1, max_length=48)
|
|
model_policy: str = Field(min_length=1, max_length=32)
|
|
primary_endpoint_id: int = Field(gt=0)
|
|
fallbacks: list[FallbackPayload] = Field(default_factory=list, max_length=2)
|
|
max_attempts: int = Field(default=2, ge=1, le=3)
|
|
latency_budget_ms: int = Field(default=15000, ge=100, le=120000)
|
|
priority: int = Field(default=100, ge=0)
|
|
|
|
|
|
class PromptPayload(StrictPayload):
|
|
release_id: int = Field(gt=0)
|
|
prompt_code: str = Field(min_length=1, max_length=64)
|
|
task_type: str = Field(min_length=1, max_length=48)
|
|
agent_type: str | None = Field(default=None, max_length=32)
|
|
version: int = Field(ge=1)
|
|
system_prompt: str = Field(min_length=1, max_length=32000)
|
|
user_prompt_template: str = Field(min_length=1, max_length=32000)
|
|
input_schema: dict[str, Any] | None = None
|
|
output_schema: dict[str, Any] | None = None
|
|
|
|
|
|
class IntentPayload(StrictPayload):
|
|
agent_type: str = Field(min_length=2, max_length=32)
|
|
intent_code: str = Field(min_length=1, max_length=64)
|
|
intent_name: str = Field(min_length=1, max_length=128)
|
|
description: str | None = Field(default=None, max_length=500)
|
|
examples: list[str]
|
|
classifier_instruction: str | None = None
|
|
confidence_threshold: str = Field(default="0.6000", pattern=r"^(0(\.\d{1,4})?|1(\.0{1,4})?)$")
|
|
max_clarification_rounds: int = Field(default=2, ge=0, le=10)
|
|
transfer_on_failure: bool = True
|
|
allowed_tools: list[str] = Field(default_factory=list)
|
|
priority: int = Field(default=100, ge=0)
|
|
version: int = Field(default=1, ge=1)
|
|
|
|
|
|
#: `agent_reply_template.chk_template_scene` 允许的取值。**必须逐字对齐**：
|
|
#: 此前 `ReplyPayload.scene` 只校验长度（`min_length=1, max_length=32`），
|
|
#: 于是传一个不在列内的场景会**穿过接口校验、撞上数据库 CHECK 约束**，
|
|
#: 最终以 `500` 冒出（`(3819, "Check constraint 'chk_template_scene' is violated.")`）——
|
|
#: 那本该是一次 `422` 参数校验失败。2026-09-13 由接口逐条测试发现。
|
|
ReplyScene = Literal[
|
|
"disclaimer",
|
|
"low_confidence",
|
|
"compliance_block",
|
|
"transfer",
|
|
"model_failure",
|
|
"system_busy",
|
|
"clarification",
|
|
]
|
|
|
|
|
|
class ReplyPayload(StrictPayload):
|
|
template_code: str = Field(min_length=1, max_length=64)
|
|
scene: ReplyScene
|
|
title: str = Field(min_length=1, max_length=128)
|
|
content_text: str = Field(min_length=1, max_length=32000)
|
|
variables: list[str] = Field(default_factory=list)
|
|
locale: str = Field(default="zh-CN", max_length=16)
|
|
version: int = Field(default=1, ge=1)
|
|
|
|
|
|
class NegativePayload(StrictPayload):
|
|
rule_code: str = Field(min_length=1, max_length=64)
|
|
word_pattern: str = Field(min_length=1, max_length=256)
|
|
match_type: Literal["contains", "exact"] = "contains"
|
|
category: str = Field(min_length=1, max_length=32)
|
|
severity: Literal["block", "replace", "warn"] = "block"
|
|
applicable_agents: list[str] | None = None
|
|
safe_reply_template_code: str | None = Field(default=None, max_length=64)
|
|
|
|
|
|
class ReviewPayload(StrictPayload):
|
|
decision: Literal["approved", "rejected"]
|
|
comment: str = Field(default="", max_length=1000)
|
|
|
|
|
|
class EmptyPayload(StrictPayload):
|
|
pass
|