diff --git a/app/llm.py b/app/llm.py
new file mode 100644
index 0000000..c18a6db
--- /dev/null
+++ b/app/llm.py
@@ -0,0 +1,175 @@
+"""LLM client module — all network egress is concentrated here.
+
+Uses ``httpx`` (already in requirements) to call OpenAI-compatible endpoints.
+No ``openai`` SDK dependency. Sync functions are fine: FastAPI runs sync
+handlers in a threadpool.
+
+Public API:
+- ``is_configured(cfg)`` — returns True when the client can make calls.
+- ``test_connection(cfg)`` — minimal request to verify credentials.
+- ``expand_query(cfg, query)`` — query-term expansion (step 3 consumer).
+- ``analyze_image(...)`` — **reserved stub, not implemented**.
+
+All calls go through ``_call_chat_completion()`` so tests can mock a single
+boundary.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from app.settings_store import LLMConfig
+
+# Sensible defaults
+_TIMEOUT_SECONDS = 30
+
+
+@dataclass
+class LLMResult:
+ """Uniform result wrapper for LLM calls."""
+
+ success: bool
+ message: str
+ data: Any = None
+
+
+def is_configured(cfg: LLMConfig) -> bool:
+ """Return True only when the LLM is enabled AND has required fields."""
+ return bool(cfg.enabled and cfg.model and cfg.api_key)
+
+
+def test_connection(cfg: LLMConfig) -> LLMResult:
+ """Send a minimal chat-completion request to verify the config.
+
+ Uses a tiny prompt to minimise cost. Returns an ``LLMResult`` indicating
+ success or failure with a human-readable message.
+ """
+ if not is_configured(cfg):
+ return LLMResult(
+ success=False,
+ message="LLM 未配置或未启用（缺少 model 或 api_key）。",
+ )
+
+ try:
+ response = _call_chat_completion(
+ cfg,
+ messages=[{"role": "user", "content": "Hi"}],
+ max_tokens=1,
+ )
+ return LLMResult(
+ success=True,
+ message=f"连接成功（模型：{cfg.model}）。",
+ data=response,
+ )
+ except httpx.HTTPStatusError as exc:
+ status = exc.response.status_code
+ return LLMResult(
+ success=False,
+ message=f"连接失败（HTTP {status}）。请检查 base_url、model 和 api_key。",
+ )
+ except httpx.ConnectError:
+ return LLMResult(
+ success=False,
+ message="无法连接到服务器。请检查 base_url 是否正确。",
+ )
+ except httpx.TimeoutException:
+ return LLMResult(
+ success=False,
+ message="连接超时。请检查网络或 base_url 是否可达。",
+ )
+ except Exception as exc: # noqa: BLE001 — graceful degradation
+ return LLMResult(
+ success=False,
+ message=f"未知错误：{exc}",
+ )
+
+
+def expand_query(cfg: LLMConfig, query: str) -> list[str]:
+ """Expand a search query into multiple synonymous terms via LLM.
+
+ **Step 3 will consume this.** Returns a list including the original query.
+ If the LLM call fails or is not configured, returns ``[query]`` as a
+ fallback (graceful degradation).
+ """
+ if not is_configured(cfg):
+ return [query]
+
+ try:
+ response = _call_chat_completion(
+ cfg,
+ messages=[
+ {
+ "role": "system",
+ "content": (
+ "你是一个搜索词扩展助手。用户给你一个搜索词，"
+ "你返回 3-5 个同义词或相关词，每行一个。"
+ "不要编号、不要解释、不要标点。"
+ ),
+ },
+ {"role": "user", "content": query},
+ ],
+ max_tokens=100,
+ )
+ choices = response.get("choices", [])
+ if choices:
+ content = choices[0].get("message", {}).get("content", "")
+ expanded = [
+ line.strip() for line in content.strip().splitlines() if line.strip()
+ ]
+ if expanded:
+ # Always include the original query
+ return [query] + [t for t in expanded if t != query]
+ return [query]
+ except Exception: # noqa: BLE001 — graceful degradation
+ return [query]
+
+
+def analyze_image(cfg: LLMConfig, image_data: bytes, prompt: str) -> LLMResult:
+ """Analyze an image via LLM vision API.
+
+ .. note:: **Reserved stub — not implemented.** Will be filled in a future
+ round for image analysis. The signature is fixed so callers can
+ depend on it.
+ """
+ # TODO: Implement in future round for image analysis.
+ return LLMResult(
+ success=False,
+ message="图片分析功能尚未实现。",
+ )
+
+
+# ------------------------------------------------------------------
+# Internal boundary — all network calls go through this single function
+# ------------------------------------------------------------------
+
+
+def _call_chat_completion(
+ cfg: LLMConfig,
+ *,
+ messages: list[dict[str, str]],
+ max_tokens: int = 1,
+) -> dict:
+ """Call the OpenAI-compatible ``/chat/completions`` endpoint.
+
+ Returns the parsed JSON response body on success (status 2xx).
+ Raises ``httpx.HTTPStatusError`` on non-2xx, or other ``httpx`` exceptions
+ on network failures — callers handle these for graceful degradation.
+ """
+ url = cfg.base_url.rstrip("/") + "/chat/completions"
+ payload: dict[str, Any] = {
+ "model": cfg.model,
+ "messages": messages,
+ "max_tokens": max_tokens,
+ }
+ headers = {
+ "Authorization": f"Bearer {cfg.api_key}",
+ "Content-Type": "application/json",
+ }
+
+ with httpx.Client(timeout=_TIMEOUT_SECONDS) as client:
+ response = client.post(url, json=payload, headers=headers)
+ response.raise_for_status()
+ return response.json()
diff --git a/app/main.py b/app/main.py
index 0226481..ff40328 100644
--- a/app/main.py
+++ b/app/main.py
@@ -10,7 +10,10 @@ from sqlalchemy.orm import Session
from app.db import get_db, init_db
from app.images import process_upload
+from app.llm import test_connection
+from app.llm import LLMResult
from app.models import Box, Item, SubItem
+from app.settings_store import LLMConfig, get_app_settings, save_app_settings
templates = Jinja2Templates(directory="app/templates")
STATIC_DIR = Path("app/static")
@@ -88,6 +91,46 @@ def _wants_add_next(submit_action: str | None) -> bool:
return submit_action == "save_and_add_next"
+def _validate_settings_origin(request: Request) -> str | None:
+ """Check Origin/Referer for same-host browser requests.
+
+ Returns an error message if validation fails, or None if OK.
+ Missing both headers (e.g. curl, API call) is allowed for now.
+ """
+ origin = request.headers.get("origin")
+ referer = request.headers.get("referer")
+
+ if origin:
+ host = request.headers.get("host", "")
+ # origin includes scheme, host only has host:port
+ from urllib.parse import urlparse
+
+ parsed = urlparse(origin)
+ origin_host = parsed.netloc
+ if origin_host != host:
+ return "请求来源与当前站点不一致，操作被拒绝。"
+ elif referer:
+ host = request.headers.get("host", "")
+ from urllib.parse import urlparse
+
+ parsed = urlparse(referer)
+ referer_host = parsed.netloc
+ if referer_host != host:
+ return "请求来源与当前站点不一致，操作被拒绝。"
+
+ return None
+
+
+def _validate_base_url_scheme(base_url: str) -> str | None:
+ """Return an error message if base_url scheme is not allowed, else None."""
+ from urllib.parse import urlparse
+
+ parsed = urlparse(base_url)
+ if parsed.scheme not in ("https", "http"):
+ return "Base URL 必须以 http:// 或 https:// 开头。"
+ return None
+
+
def _format_average(total: int, divisor: int) -> str:
if divisor == 0:
return "0.0"
@@ -267,6 +310,161 @@ def create_app() -> FastAPI:
context={"page_title": "箱子", "boxes": boxes, "summary": summary},
)
+ # ------------------------------------------------------------------
+ # Settings
+ # ------------------------------------------------------------------
+
+ @app.get("/settings")
+ def settings_page(request: Request, db: Session = Depends(get_db)):
+ cfg = get_app_settings(db)
+ return templates.TemplateResponse(
+ request=request,
+ name="settings/form.html",
+ context={
+ "page_title": "设置",
+ "config": cfg,
+ "api_key_configured": bool(cfg.api_key),
+ "test_result": None,
+ },
+ )
+
+ @app.post("/settings")
+ def save_settings(
+ request: Request,
+ enabled: str | None = Form(default=None),
+ base_url: str | None = Form(default=None),
+ model: str | None = Form(default=None),
+ api_key: str | None = Form(default=None),
+ db: Session = Depends(get_db),
+ ) -> Response:
+ # Origin/Referer check for browser requests
+ origin_error = _validate_settings_origin(request)
+ if origin_error:
+ raise HTTPException(status_code=403, detail=origin_error)
+
+ resolved_base_url = _clean_text(base_url) or "https://api.openai.com/v1"
+
+ # Validate base_url scheme
+ scheme_error = _validate_base_url_scheme(resolved_base_url)
+ if scheme_error:
+ raise HTTPException(status_code=400, detail=scheme_error)
+
+ resolved_model = _clean_text(model) or ""
+
+ # Only base_url change counts as an endpoint change — model switches
+ # under the same base_url do not require a new key.
+ existing_cfg = get_app_settings(db)
+ submitted_key = _clean_text(api_key)
+ base_url_changed = resolved_base_url != existing_cfg.base_url
+
+ if base_url_changed and submitted_key is None:
+ # base_url changed but no new key provided — refuse to save,
+ # return to settings page with a clear error message.
+ return templates.TemplateResponse(
+ request=request,
+ name="settings/form.html",
+ context={
+ "page_title": "设置",
+ "config": LLMConfig(
+ enabled=enabled == "on",
+ base_url=resolved_base_url,
+ model=resolved_model,
+ api_key=existing_cfg.api_key,
+ ),
+ "api_key_configured": bool(existing_cfg.api_key),
+ "test_result": LLMResult(
+ success=False,
+ message="Base URL 已变更，请重新输入 API Key 后保存。",
+ ),
+ },
+ )
+
+ # submitted_key is None → keep old key; str (including "") → use new value
+ resolved_api_key = submitted_key
+
+ save_app_settings(
+ db,
+ enabled=enabled == "on",
+ base_url=resolved_base_url,
+ model=resolved_model,
+ api_key=resolved_api_key,
+ )
+ return RedirectResponse(url="/settings", status_code=status.HTTP_303_SEE_OTHER)
+
+ @app.post("/settings/test")
+ def test_settings_connection(
+ request: Request,
+ enabled: str | None = Form(default=None),
+ base_url: str | None = Form(default=None),
+ model: str | None = Form(default=None),
+ api_key: str | None = Form(default=None),
+ db: Session = Depends(get_db),
+ ):
+ # Origin/Referer check for browser requests
+ origin_error = _validate_settings_origin(request)
+ if origin_error:
+ raise HTTPException(status_code=403, detail=origin_error)
+
+ resolved_base_url = _clean_text(base_url) or "https://api.openai.com/v1"
+
+ # Validate base_url scheme
+ scheme_error = _validate_base_url_scheme(resolved_base_url)
+ if scheme_error:
+ raise HTTPException(status_code=400, detail=scheme_error)
+
+ resolved_model = _clean_text(model) or ""
+
+ # Only reuse stored key if base_url matches saved config. Model switches
+ # under the same base_url can use the same key; a base_url change cannot.
+ existing_cfg = get_app_settings(db)
+ submitted_key = _clean_text(api_key)
+ base_url_matches = resolved_base_url == existing_cfg.base_url
+ if base_url_matches and submitted_key is None:
+ resolved_api_key = existing_cfg.api_key
+ elif submitted_key is not None:
+ resolved_api_key = submitted_key
+ else:
+ # base_url changed but no key provided — refuse to test
+
+ return templates.TemplateResponse(
+ request=request,
+ name="settings/form.html",
+ context={
+ "page_title": "设置",
+ "config": LLMConfig(
+ enabled=enabled == "on",
+ base_url=resolved_base_url,
+ model=resolved_model,
+ api_key="",
+ ),
+ "api_key_configured": bool(existing_cfg.api_key),
+ "test_result": LLMResult(
+ success=False,
+ message="Base URL 已变更，请重新输入 API Key 后再测试。",
+ ),
+ },
+ )
+
+ test_cfg = LLMConfig(
+ enabled=enabled == "on",
+ base_url=resolved_base_url,
+ model=resolved_model,
+ api_key=resolved_api_key or "",
+ )
+
+ result = test_connection(test_cfg)
+
+ return templates.TemplateResponse(
+ request=request,
+ name="settings/form.html",
+ context={
+ "page_title": "设置",
+ "config": test_cfg,
+ "api_key_configured": bool(test_cfg.api_key),
+ "test_result": result,
+ },
+ )
+
@app.get("/boxes/new")
def new_box_page(request: Request):
return templates.TemplateResponse(
diff --git a/app/models.py b/app/models.py
index 2e76460..d034011 100644
--- a/app/models.py
+++ b/app/models.py
@@ -90,3 +90,10 @@ class SubItem(Base):
)
parent_item: Mapped[Item] = relationship(back_populates="subitems")
+
+
+class AppSetting(Base):
+ __tablename__ = "app_settings"
+
+ key: Mapped[str] = mapped_column(Text, primary_key=True)
+ value: Mapped[str | None] = mapped_column(Text, nullable=True)
diff --git a/app/settings_store.py b/app/settings_store.py
new file mode 100644
index 0000000..8ee84a4
--- /dev/null
+++ b/app/settings_store.py
@@ -0,0 +1,88 @@
+"""Settings read/write helpers for the ``app_settings`` KV table.
+
+Provides a typed ``LLMConfig`` dataclass and two helpers:
+
+- ``get_app_settings(db) -> LLMConfig`` — reads KV rows (or returns defaults).
+- ``save_app_settings(db, ...) -> None`` — writes KV rows; API key left blank
+ means "keep the old value".
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from sqlalchemy.orm import Session
+
+from app.models import AppSetting
+
+
+@dataclass
+class LLMConfig:
+ """All settings consumed by the LLM client and settings UI."""
+
+ enabled: bool = False
+ base_url: str = "https://api.openai.com/v1"
+ model: str = ""
+ api_key: str = ""
+ ai_search_enabled: bool = False
+
+
+def _get_value(rows: dict[str, str], key: str, default: str) -> str:
+ return rows.get(key, default)
+
+
+def _get_bool(rows: dict[str, str], key: str, default: bool) -> bool:
+ return rows.get(key, str(default).lower()) == "true"
+
+
+def get_app_settings(db: Session) -> LLMConfig:
+ """Read all settings from ``app_settings`` and return an ``LLMConfig``."""
+ rows: dict[str, str] = {}
+ for row in db.query(AppSetting).all():
+ if row.value is not None:
+ rows[row.key] = row.value
+
+ return LLMConfig(
+ enabled=_get_bool(rows, "llm_enabled", False),
+ base_url=_get_value(rows, "llm_base_url", "https://api.openai.com/v1"),
+ model=_get_value(rows, "llm_model", ""),
+ api_key=_get_value(rows, "llm_api_key", ""),
+ ai_search_enabled=_get_bool(rows, "ai_search_enabled", False),
+ )
+
+
+def save_app_settings(
+ db: Session,
+ *,
+ enabled: bool | None = None,
+ base_url: str | None = None,
+ model: str | None = None,
+ api_key: str | None = None,
+ ai_search_enabled: bool | None = None,
+) -> None:
+ """Write settings to ``app_settings``.
+
+ If ``api_key`` is ``None`` (form field left blank), the existing key is
+ preserved. All other fields are written as-is.
+ """
+ updates: dict[str, str | None] = {}
+
+ if enabled is not None:
+ updates["llm_enabled"] = str(enabled).lower()
+ if base_url is not None:
+ updates["llm_base_url"] = base_url
+ if model is not None:
+ updates["llm_model"] = model
+ if api_key is not None:
+ updates["llm_api_key"] = api_key
+ if ai_search_enabled is not None:
+ updates["ai_search_enabled"] = str(ai_search_enabled).lower()
+
+ for key, value in updates.items():
+ existing = db.get(AppSetting, key)
+ if existing is not None:
+ existing.value = value
+ else:
+ db.add(AppSetting(key=key, value=value))
+
+ db.commit()
diff --git a/app/templates/base.html b/app/templates/base.html
index 72325e8..4a379ba 100644
--- a/app/templates/base.html
+++ b/app/templates/base.html
@@ -19,6 +19,7 @@
{% block content %}{% endblock %}
diff --git a/app/templates/settings/form.html b/app/templates/settings/form.html
new file mode 100644
index 0000000..31f69da
--- /dev/null
+++ b/app/templates/settings/form.html
@@ -0,0 +1,55 @@
+{% extends "base.html" %}
+
+{% block content %}
+
+
+
+{% if test_result %}
+
+
+ {{ "✓ " if test_result.success else "✗ " }}{{ test_result.message }}
+
+
+{% endif %}
+
+
+{% endblock %}
diff --git a/docs/design/llm-integration-design.md b/docs/design/llm-integration-design.md
index d220b69..4137268 100644
--- a/docs/design/llm-integration-design.md
+++ b/docs/design/llm-integration-design.md
@@ -199,6 +199,7 @@ More settings are coming; adding columns to an *existing* table costs a migratio
| `llm_model` | 模型名 / model name | （空 / empty） |
| `llm_api_key` | API Key（明文 / plaintext，见 §7） | （空 / empty） |
| `ai_search_enabled` | AI 搜索功能开关 / AI-search feature toggle | `false` |
+| `ai_search_extra_hints` | AI 搜索：可选「额外领域提示」，追加到默认系统提示词（step 3 引入）/ optional extra domain hints appended to the default prompt | （空 / empty） |
> 读写封装 / Access helpers：`get_app_settings(db) -> LLMConfig`（dataclass 视图）与 `save_app_settings(db, ...)`，供路由与 `app/llm.py` 复用。
> Helpers `get_app_settings(db) -> LLMConfig` and `save_app_settings(db, ...)`, reused by routes and `app/llm.py`.
@@ -209,7 +210,7 @@ OpenAI 兼容的薄客户端，基于 `httpx`，**无新依赖** / A thin OpenAI
- `is_configured(cfg) -> bool`：开关开启且 `model`/`api_key` 齐全。
- `test_connection(cfg) -> Result`：发一个最小请求验证 `base_url`/`model`/`api_key`，供配置页"测试连接"用。
-- `expand_query(cfg, query) -> list[str]`：把查询词扩成一批近义/相关词（本轮 AI 搜索用，见 §5）。
+- `expand_query(cfg, query) -> list[str]`：把查询词扩成一批近义/相关词（提示词与输出契约见 §5.2）。
- `analyze_image(...)`：**本轮不实现**，仅在文档中预留为未来接口（图片分析轮次）。Reserved for a future round, not implemented now.
要点 / Notes：
@@ -251,7 +252,22 @@ When disabled/unconfigured: the settings page still works; the AI-search button
- **只把查询词发出去 / Only the query leaves**，不外泄物品清单；token 恒定、不随上千件物品增长。
Only the query is sent; the inventory is not. Token cost is constant and does not grow with thousands of items.
-### 5.2 实现接口 / Implementation seam
+### 5.2 提示词与输出契约 / Prompt & Output Contract
+
+`expand_query` 的**质量**取决于提示词，**集成稳定性**取决于输出契约——两者都在代码侧掌控（决策 C）。
+Quality hinges on the prompt; integration stability hinges on the output contract — both are code-controlled (decision C).
+
+- **基础系统提示词写死在 `app/llm.py`（用户改不坏）/ Base system prompt hardcoded：** 框定搬家/家居场景，要求"列出用户可能用来命名同一物品的相关词（近义、别称、上位类别、具体品类）"；语言跟随查询；最多约 8 个；不解释、不造无关词。
+ Frames the moving/household domain, asks for related naming terms, follows the query's language, caps the count, no prose.
+- **可选「额外领域提示」/ Optional extra hints：** KV `ai_search_extra_hints`（设置页一个多行输入，默认空）。非空时**追加**到基础提示词之后，供业主微调倾向（如"厨房用品多，偏向厨具类"）。**它只能补充，不能改写输出格式。**
+ An optional free-text setting appended to the base prompt; it can only add guidance, never alter the output format.
+- **输出契约（代码强制，与提示词解耦）/ Output contract (code-enforced)：** 要求模型只返回 **JSON 字符串数组**；解析时去掉 ` ```json ` 围栏 → `json.loads` → 失败按行/逗号兜底 → 再不行返回 `[]`。`expand_query` 只返回扩展词；**原词由 `ai_search` 并入并去重**，数量在代码侧再封顶一次。
+ Require a JSON string array; tolerant parse with fallbacks to `[]`. `ai_search` adds the original term and dedupes; the count is capped in code.
+- **客户端参数 / Client params：** 低 temperature、较小 max_tokens、设超时。Low temperature, small max_tokens, a timeout.
+- **措辞留松 / Wording left loose：** 默认提示词的具体字句可在 step-3 实测中迭代，不在文档里冻死。
+ Exact default wording can be iterated during step-3 testing.
+
+### 5.3 实现接口 / Implementation seam
- 路由层扩展现有 `GET /search`：增加 `ai=1` 触发位（如 `GET /search?q=锅&ai=1`），保持单页、可收藏、SSR 友好。
Extend the existing `GET /search` with an `ai=1` trigger (e.g. `/search?q=…&ai=1`), staying single-page and bookmarkable.
@@ -263,7 +279,7 @@ When disabled/unconfigured: the settings page still works; the AI-search button
- 本轮检索范围＝`name` + `note`（`image_description` 本轮不存在）。
Search scope this round = `name` + `note` (no `image_description` yet).
-### 5.3 降级 / Degradation
+### 5.4 降级 / Degradation
AI 关闭/未配置 → 不显示按钮（或提示去 `/settings`）；调用失败 → 友好提示并回退到普通结果。
AI off/unconfigured → no button (or a hint to `/settings`); on failure → a friendly message, fall back to normal results.
@@ -334,3 +350,4 @@ AI off/unconfigured → no button (or a hint to `/settings`); on failure → a f
| D8 | AI 搜索 v1＝查询词扩展 / query-term expansion | 上千件物品下可扩展、不外泄清单、token 恒定。 |
| D9 | 检索做成可替换 seam / pluggable retrieval | 未来换嵌入式语义搜索时上层不动。 |
| D10 | 图片分析不在本轮 / image analysis deferred | 业主本轮三件事不含它；架构预留接口。 |
+| D11 | AI 搜索提示词：默认写死 + 可选「额外领域提示」；输出契约由代码强制 / hardcoded default prompt + optional extra-hints, code-enforced JSON contract | 保证解析稳定（用户改不坏），又给业主一点不改代码即可微调的空间。 |
diff --git a/docs/design/step-3-ai-search.md b/docs/design/step-3-ai-search.md
index 1cbb75b..f1e6a9f 100644
--- a/docs/design/step-3-ai-search.md
+++ b/docs/design/step-3-ai-search.md
@@ -17,7 +17,9 @@ A **persistent** "AI search" action on the search page that broadens results via
- 现有搜索：`app/main.py::_build_search_results(db, query)` 对 `Box`/`Item`/`SubItem` 的 `name` 与 `note` 做大小写不敏感 `LIKE`，返回结果列表；路由 `GET /search`（函数 `search_page`，参数 `q`）渲染 `app/templates/search/index.html`。
Existing search: `_build_search_results(db, query)` does case-insensitive `LIKE` over name/note; route `GET /search` renders `search/index.html`.
-- 步骤 2 已提供：`app/llm.py::expand_query(cfg, query) -> list[str]`、配置读取 `get_app_settings(db)`、开关 `ai_search_enabled` 与 `is_configured(cfg)`。
+- 步骤 2 已提供：`app/llm.py::expand_query(cfg, query) -> list[str]`、配置读取 `get_app_settings(db)`、开关 `ai_search_enabled` 与 `is_configured(cfg)`、设置页 `app/templates/settings/form.html`。
+- 本步**新增**配置项 `ai_search_extra_hints`（可选「额外领域提示」）并在设置页加一个多行输入——这是本步**唯一**触及设置页之处。
+ This step adds the `ai_search_extra_hints` setting + a textarea on the settings page (the only settings-page change here).
- 本轮检索范围＝`name` + `note`（`image_description` 本轮不存在，属未来图片分析轮次）。
Search scope = `name` + `note` (no `image_description` this round).
@@ -29,12 +31,20 @@ A **persistent** "AI search" action on the search page that broadens results via
Trigger → expand → OR-`LIKE` over the original + expanded terms → render with a banner of the expansion. Only the query leaves.
- **可替换的检索 seam。** 把 AI 检索抽成一个函数（如 `ai_search(db, query) -> (expanded_terms, results)`），本轮内部＝查询词扩展 + 本地 `LIKE`；**未来换成向量嵌入 + 相似度时，路由与模板不变**。
Wrap AI retrieval behind a swappable seam so embeddings can replace it later without touching route/template.
+- **提示词（决策 C，详见设计 §5.2）。** 基础系统提示词**写死在 `app/llm.py`**；设置页可选的 `ai_search_extra_hints` 非空时**追加**到其后；**输出契约由代码强制**（要求 JSON 字符串数组 → 容忍性解析 → 失败返回 `[]`），用户改 hints 也改不坏解析。
+ Base prompt hardcoded; optional extra hints appended; output contract (JSON array → tolerant parse → `[]`) enforced in code.
- **优雅降级。** AI 关闭/未配置 → 不显示按钮（或提示去 `/settings`）；调用失败 → 友好提示 + 回退普通结果。
---
## 任务 / Tasks
+- [ ] **落地/校准 `expand_query` 的提示词（按设计 §5.2）**：
+ - 基础系统提示词写死在 `app/llm.py`（搬家/家居场景、列相关命名词、跟随查询语言、≤ ~8 个、不解释、不造无关词）。默认提示词起点（**可迭代** / a starting point, tune during testing）：
+ > 你是搬家物品搜索助手。用户在搜索自己打包的箱子与物品（家居/搬家场景）。给定一个搜索词，列出用户可能用来命名同一类物品的相关词：近义词、常见别称、上位类别、具体品类。规则：用与查询相同的语言；只给与该物品紧密相关、有助于在清单里找到它的词；不要解释、不要造无关词；最多 8 个；只输出一个 JSON 字符串数组，例如 `["炒锅","平底锅","汤锅","厨具"]`。
+ - 读取 `ai_search_extra_hints`，非空则**追加**到基础提示词之后（只补充，不改格式）。
+ - **输出契约**：要求模型只回 JSON 字符串数组；解析去 ` ```json ` 围栏 → `json.loads` → 失败按行/逗号兜底 → 再不行返回 `[]`；任何异常/超时都返回 `[]`（不抛错）。
+- [ ] **新增配置项 `ai_search_extra_hints`**：KV 默认空；纳入 `get_app_settings` / `save_app_settings`；设置页 `app/templates/settings/form.html` 加一个多行输入（沿用 step 2 风格）。
- [ ] 实现检索 seam：在 `app/main.py`（或抽一个小搜索模块 `app/search.py`）加 `ai_search(db, query) -> (expanded_terms, results)`：
- 调 `expand_query(cfg, query)` 得到扩展词；
- 用「原词 + 扩展词」对 `name`/`note` 做 OR `LIKE`（**复用现有 `_build_search_results` 的匹配逻辑**，避免重复实现），去重。
@@ -53,12 +63,16 @@ A **persistent** "AI search" action on the search page that broadens results via
- [ ] 已有结果时点 AI 仍可用，且结果集被扩大（含原结果）。
- [ ] 按钮可见性随 `ai_search_enabled` + `is_configured()` 门控。
- [ ] 调用失败 → 回退普通结果、页面不报错。
+ - [ ] `expand_query` 输出解析：模型回合法 JSON 数组 → 正确解析；回散文/坏 JSON/超时 → 返回 `[]`、不抛错。
+ Output parsing: valid JSON array → parsed; prose/bad JSON/timeout → `[]`, no raise.
+ - [ ] `ai_search_extra_hints` 非空时确被追加进请求（可对构造的请求体断言）。
+ Extra hints, when set, are appended to the request.
---
## 涉及文件 / Files
-`app/main.py`、（可选 `app/search.py`）、`app/templates/search/index.html`、`tests/`。
+`app/llm.py`、`app/main.py`、（可选 `app/search.py`）、`app/templates/search/index.html`、`app/templates/settings/form.html`、配置读写 helper（step 2 的 settings store）、`tests/`。
---
diff --git a/migrations/versions/a1b2c3d4e5f6_v2_app_settings.py b/migrations/versions/a1b2c3d4e5f6_v2_app_settings.py
new file mode 100644
index 0000000..a70c793
--- /dev/null
+++ b/migrations/versions/a1b2c3d4e5f6_v2_app_settings.py
@@ -0,0 +1,32 @@
+"""V2 app_settings
+
+Revision ID: a1b2c3d4e5f6
+Revises: 57af90893f55
+Create Date: 2026-06-01 14:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'a1b2c3d4e5f6'
+down_revision: Union[str, Sequence[str], None] = '57af90893f55'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+ """Upgrade schema."""
+ op.create_table('app_settings',
+ sa.Column('key', sa.Text(), nullable=False),
+ sa.Column('value', sa.Text(), nullable=True),
+ sa.PrimaryKeyConstraint('key')
+ )
+
+
+def downgrade() -> None:
+ """Downgrade schema."""
+ op.drop_table('app_settings')
diff --git a/pytest.ini b/pytest.ini
index 0e7730c..1a5b62a 100644
--- a/pytest.ini
+++ b/pytest.ini
@@ -1,4 +1,6 @@
[pytest]
pythonpath = .
+testpaths = tests
+norecursedirs = app .venv
filterwarnings =
ignore:'asyncio\.iscoroutinefunction' is deprecated and slated for removal in Python 3\.16; use inspect\.iscoroutinefunction\(\) instead:DeprecationWarning:fastapi\.routing
diff --git a/tests/test_migrate.py b/tests/test_migrate.py
index 4a60960..acc81cd 100644
--- a/tests/test_migrate.py
+++ b/tests/test_migrate.py
@@ -28,6 +28,7 @@ from app.db import Base, SessionLocal, configure_database
from app.migrate import (
V1_REVISION,
_detect_db_state,
+ _make_alembic_config,
run_migrations,
verify_schema_is_current,
)
@@ -35,6 +36,18 @@ from app.main import create_app
from fastapi.testclient import TestClient
+def _get_head_revision() -> str:
+ """Resolve the current Alembic head revision from migration scripts."""
+ from alembic.script import ScriptDirectory
+
+ cfg = _make_alembic_config("sqlite:///") # URL is unused for script lookup
+ script = ScriptDirectory.from_config(cfg)
+ return script.get_current_head()
+
+
+HEAD_REVISION = _get_head_revision()
+
+
@pytest.fixture()
def tmp_db_path(tmp_path):
"""Provide a temporary SQLite database path."""
@@ -55,7 +68,7 @@ def tmp_db_url(tmp_db_path):
class TestFreshDBMigration:
"""Empty database gets all tables created by migration."""
- def test_creates_all_three_tables(self, tmp_db_url):
+ def test_creates_all_tables(self, tmp_db_url):
run_migrations(tmp_db_url)
eng = create_engine(tmp_db_url)
tables = set(inspect(eng).get_table_names())
@@ -63,6 +76,7 @@ class TestFreshDBMigration:
assert "boxes" in tables
assert "items" in tables
assert "subitems" in tables
+ assert "app_settings" in tables
def test_creates_alembic_version_table(self, tmp_db_url):
run_migrations(tmp_db_url)
@@ -77,7 +91,7 @@ class TestFreshDBMigration:
with eng.begin() as conn:
version = conn.execute(text("SELECT version_num FROM alembic_version")).scalar()
eng.dispose()
- assert version == V1_REVISION
+ assert version == HEAD_REVISION
def test_boxes_table_has_all_columns(self, tmp_db_url):
run_migrations(tmp_db_url)
@@ -147,9 +161,11 @@ class TestUnmanagedDBAdoption2a:
"""Database with existing tables matching baseline gets adopted."""
def _create_old_db(self, db_url: str) -> None:
- """Simulate a pre-Alembic DB: create_all + insert data."""
+ """Simulate a pre-Alembic DB: create V1 tables only + insert data."""
eng = create_engine(db_url)
- Base.metadata.create_all(bind=eng)
+ # Only create V1 tables (boxes, items, subitems) — not app_settings
+ for table_name in ("boxes", "items", "subitems"):
+ Base.metadata.tables[table_name].create(bind=eng)
with eng.begin() as conn:
conn.execute(text(
"INSERT INTO boxes (name, room, status, created_at, updated_at) "
@@ -170,7 +186,7 @@ class TestUnmanagedDBAdoption2a:
with eng.begin() as conn:
version = conn.execute(text("SELECT version_num FROM alembic_version")).scalar()
eng.dispose()
- assert version == V1_REVISION
+ assert version == HEAD_REVISION
def test_data_preserved_after_adoption(self, tmp_db_url):
self._create_old_db(tmp_db_url)
@@ -187,14 +203,14 @@ class TestUnmanagedDBAdoption2a:
assert item_count == 1
assert box_name == "Kitchen Box"
- def test_no_extra_tables_created(self, tmp_db_url):
+ def test_no_extra_tables_beyond_migrations(self, tmp_db_url):
self._create_old_db(tmp_db_url)
run_migrations(tmp_db_url)
eng = create_engine(tmp_db_url)
tables = set(inspect(eng).get_table_names())
eng.dispose()
- assert tables == {"alembic_version", "boxes", "items", "subitems"}
+ assert tables == {"alembic_version", "boxes", "items", "subitems", "app_settings"}
def test_adoption_is_idempotent(self, tmp_db_url):
"""Running run_migrations twice does not error or duplicate data."""
@@ -209,7 +225,7 @@ class TestUnmanagedDBAdoption2a:
eng.dispose()
assert box_count == 1
- assert version == V1_REVISION
+ assert version == HEAD_REVISION
# ---------------------------------------------------------------------------
@@ -396,7 +412,7 @@ class TestManagedDBMigration:
with eng.begin() as conn:
version = conn.execute(text("SELECT version_num FROM alembic_version")).scalar()
eng.dispose()
- assert version == V1_REVISION
+ assert version == HEAD_REVISION
# ---------------------------------------------------------------------------
@@ -639,7 +655,7 @@ class TestProdDBCopyAdoption:
subitems_after = conn.execute(text("SELECT COUNT(*) FROM subitems")).scalar()
eng.dispose()
- assert version == V1_REVISION
+ assert version == HEAD_REVISION
assert boxes_after == boxes_before
assert items_after == items_before
assert subitems_after == subitems_before
diff --git a/tests/test_settings.py b/tests/test_settings.py
new file mode 100644
index 0000000..b67735b
--- /dev/null
+++ b/tests/test_settings.py
@@ -0,0 +1,634 @@
+"""Tests for the settings store, LLM client, and settings routes.
+
+All LLM calls are mocked — CI never touches the network.
+"""
+
+from unittest.mock import patch
+
+import pytest
+
+import app.llm as llm_module
+from app.llm import LLMResult, expand_query, is_configured
+from app.models import AppSetting
+from app.settings_store import LLMConfig, get_app_settings, save_app_settings
+
+# Alias to avoid pytest collecting it as a test function
+_test_connection = llm_module.test_connection
+
+
+# ---------------------------------------------------------------------------
+# LLMConfig dataclass defaults
+# ---------------------------------------------------------------------------
+
+
+class TestLLMConfigDefaults:
+ def test_default_values(self):
+ cfg = LLMConfig()
+ assert cfg.enabled is False
+ assert cfg.base_url == "https://api.openai.com/v1"
+ assert cfg.model == ""
+ assert cfg.api_key == ""
+ assert cfg.ai_search_enabled is False
+
+
+# ---------------------------------------------------------------------------
+# settings_store: get_app_settings
+# ---------------------------------------------------------------------------
+
+
+class TestGetAppSettings:
+ def test_returns_defaults_when_no_rows(self, db_session):
+ cfg = get_app_settings(db_session)
+ assert cfg.enabled is False
+ assert cfg.base_url == "https://api.openai.com/v1"
+ assert cfg.model == ""
+ assert cfg.api_key == ""
+ assert cfg.ai_search_enabled is False
+
+ def test_reads_stored_values(self, db_session):
+ db_session.add(AppSetting(key="llm_enabled", value="true"))
+ db_session.add(AppSetting(key="llm_base_url", value="https://custom.api/v1"))
+ db_session.add(AppSetting(key="llm_model", value="gpt-4o"))
+ db_session.add(AppSetting(key="llm_api_key", value="sk-test-key"))
+ db_session.add(AppSetting(key="ai_search_enabled", value="true"))
+ db_session.commit()
+
+ cfg = get_app_settings(db_session)
+ assert cfg.enabled is True
+ assert cfg.base_url == "https://custom.api/v1"
+ assert cfg.model == "gpt-4o"
+ assert cfg.api_key == "sk-test-key"
+ assert cfg.ai_search_enabled is True
+
+ def test_handles_null_value_as_default(self, db_session):
+ db_session.add(AppSetting(key="llm_model", value=None))
+ db_session.commit()
+
+ cfg = get_app_settings(db_session)
+ assert cfg.model == ""
+
+
+# ---------------------------------------------------------------------------
+# settings_store: save_app_settings
+# ---------------------------------------------------------------------------
+
+
+class TestSaveAppSettings:
+ def test_saves_new_settings(self, db_session):
+ save_app_settings(
+ db_session,
+ enabled=True,
+ base_url="https://my-api.com/v1",
+ model="gpt-4o-mini",
+ api_key="sk-new-key",
+ )
+
+ cfg = get_app_settings(db_session)
+ assert cfg.enabled is True
+ assert cfg.base_url == "https://my-api.com/v1"
+ assert cfg.model == "gpt-4o-mini"
+ assert cfg.api_key == "sk-new-key"
+
+ def test_updates_existing_settings(self, db_session):
+ save_app_settings(db_session, enabled=True, model="old-model", api_key="key1")
+ save_app_settings(db_session, model="new-model")
+
+ cfg = get_app_settings(db_session)
+ assert cfg.model == "new-model"
+ # enabled was not passed in second save, so it stays unchanged
+ assert cfg.enabled is True
+
+ def test_api_key_none_preserves_old_key(self, db_session):
+ save_app_settings(db_session, api_key="sk-original")
+ save_app_settings(db_session, model="gpt-4o", api_key=None)
+
+ cfg = get_app_settings(db_session)
+ assert cfg.api_key == "sk-original"
+ assert cfg.model == "gpt-4o"
+
+ def test_api_key_empty_string_overwrites(self, db_session):
+ save_app_settings(db_session, api_key="sk-original")
+ save_app_settings(db_session, api_key="")
+
+ cfg = get_app_settings(db_session)
+ assert cfg.api_key == ""
+
+ def test_partial_save_only_updates_specified_fields(self, db_session):
+ save_app_settings(db_session, enabled=True, model="gpt-4o")
+ save_app_settings(db_session, base_url="https://new.url/v1")
+
+ cfg = get_app_settings(db_session)
+ assert cfg.enabled is True
+ assert cfg.model == "gpt-4o"
+ assert cfg.base_url == "https://new.url/v1"
+
+
+# ---------------------------------------------------------------------------
+# is_configured
+# ---------------------------------------------------------------------------
+
+
+class TestIsConfigured:
+ def test_false_when_disabled(self):
+ cfg = LLMConfig(enabled=False, model="gpt-4o", api_key="sk-key")
+ assert is_configured(cfg) is False
+
+ def test_false_when_no_model(self):
+ cfg = LLMConfig(enabled=True, model="", api_key="sk-key")
+ assert is_configured(cfg) is False
+
+ def test_false_when_no_api_key(self):
+ cfg = LLMConfig(enabled=True, model="gpt-4o", api_key="")
+ assert is_configured(cfg) is False
+
+ def test_true_when_all_set(self):
+ cfg = LLMConfig(enabled=True, model="gpt-4o", api_key="sk-key")
+ assert is_configured(cfg) is True
+
+
+# ---------------------------------------------------------------------------
+# test_connection (mocked)
+# ---------------------------------------------------------------------------
+
+
+class TestTestConnection:
+ def test_returns_failure_when_not_configured(self):
+ cfg = LLMConfig(enabled=False)
+ result = _test_connection(cfg)
+ assert result.success is False
+ assert "未配置" in result.message
+
+ @patch("app.llm._call_chat_completion")
+ def test_success_when_configured(self, mock_call):
+ mock_call.return_value = {"choices": [{"message": {"content": "Hi"}}]}
+ cfg = LLMConfig(enabled=True, model="gpt-4o", api_key="sk-key")
+ result = _test_connection(cfg)
+ assert result.success is True
+ assert "连接成功" in result.message
+ assert "gpt-4o" in result.message
+
+ @patch("app.llm._call_chat_completion")
+ def test_handles_http_error(self, mock_call):
+ import httpx
+
+ mock_call.side_effect = httpx.HTTPStatusError(
+ "401",
+ request=httpx.Request("POST", "http://x"),
+ response=httpx.Response(401),
+ )
+ cfg = LLMConfig(enabled=True, model="gpt-4o", api_key="sk-bad")
+ result = _test_connection(cfg)
+ assert result.success is False
+ assert "401" in result.message
+
+ @patch("app.llm._call_chat_completion")
+ def test_handles_connect_error(self, mock_call):
+ import httpx
+
+ mock_call.side_effect = httpx.ConnectError("refused")
+ cfg = LLMConfig(enabled=True, model="gpt-4o", api_key="sk-key")
+ result = _test_connection(cfg)
+ assert result.success is False
+ assert "无法连接" in result.message
+
+ @patch("app.llm._call_chat_completion")
+ def test_handles_timeout(self, mock_call):
+ import httpx
+
+ mock_call.side_effect = httpx.TimeoutException("timeout")
+ cfg = LLMConfig(enabled=True, model="gpt-4o", api_key="sk-key")
+ result = _test_connection(cfg)
+ assert result.success is False
+ assert "超时" in result.message
+
+
+# ---------------------------------------------------------------------------
+# expand_query (mocked)
+# ---------------------------------------------------------------------------
+
+
+class TestExpandQuery:
+ def test_returns_original_when_not_configured(self):
+ cfg = LLMConfig(enabled=False)
+ result = expand_query(cfg, "锅")
+ assert result == ["锅"]
+
+ @patch("app.llm._call_chat_completion")
+ def test_expands_query_successfully(self, mock_call):
+ mock_call.return_value = {
+ "choices": [
+ {"message": {"content": "平底锅\n炒锅\n锅具\n厨房锅"}}
+ ]
+ }
+ cfg = LLMConfig(enabled=True, model="gpt-4o", api_key="sk-key")
+ result = expand_query(cfg, "锅")
+ assert "锅" in result
+ assert "平底锅" in result
+ assert len(result) >= 4
+
+ @patch("app.llm._call_chat_completion")
+ def test_fallback_on_api_failure(self, mock_call):
+ mock_call.side_effect = Exception("network down")
+ cfg = LLMConfig(enabled=True, model="gpt-4o", api_key="sk-key")
+ result = expand_query(cfg, "锅")
+ assert result == ["锅"]
+
+ @patch("app.llm._call_chat_completion")
+ def test_fallback_on_empty_response(self, mock_call):
+ mock_call.return_value = {"choices": [{"message": {"content": ""}}]}
+ cfg = LLMConfig(enabled=True, model="gpt-4o", api_key="sk-key")
+ result = expand_query(cfg, "锅")
+ assert result == ["锅"]
+
+
+# ---------------------------------------------------------------------------
+# Routes: GET /settings
+# ---------------------------------------------------------------------------
+
+
+class TestSettingsPage:
+ def test_settings_page_returns_200(self, client):
+ response = client.get("/settings")
+ assert response.status_code == 200
+
+ def test_settings_page_has_form_elements(self, client):
+ response = client.get("/settings")
+ assert "设置" in response.text
+ assert 'name="enabled"' in response.text
+ assert 'name="base_url"' in response.text
+ assert 'name="model"' in response.text
+ assert 'name="api_key"' in response.text
+ assert "保存设置" in response.text
+ assert "测试连接" in response.text
+
+ def test_settings_page_shows_nav_link(self, client):
+ response = client.get("/boxes")
+ assert "设置" in response.text
+ assert 'href="/settings"' in response.text
+
+ def test_settings_page_no_api_key_echoed(self, client, db_session):
+ save_app_settings(db_session, api_key="sk-super-secret-key-12345")
+ response = client.get("/settings")
+ assert "sk-super-secret-key-12345" not in response.text
+ assert "已配置" in response.text
+
+ def test_settings_page_shows_placeholder_when_no_key(self, client):
+ response = client.get("/settings")
+ assert "输入 API Key" in response.text
+
+ def test_settings_page_shows_default_base_url(self, client):
+ response = client.get("/settings")
+ assert "https://api.openai.com/v1" in response.text
+
+
+# ---------------------------------------------------------------------------
+# Routes: POST /settings
+# ---------------------------------------------------------------------------
+
+
+class TestSaveSettingsRoute:
+ def test_save_settings_redirects(self, client):
+ response = client.post(
+ "/settings",
+ data={
+ "enabled": "on",
+ "base_url": "https://my-api.com/v1",
+ "model": "gpt-4o-mini",
+ "api_key": "sk-test-key",
+ },
+ follow_redirects=False,
+ )
+ assert response.status_code == 303
+ assert response.headers["location"] == "/settings"
+
+ def test_saved_settings_persist(self, client, db_session):
+ client.post(
+ "/settings",
+ data={
+ "enabled": "on",
+ "base_url": "https://my-api.com/v1",
+ "model": "gpt-4o-mini",
+ "api_key": "sk-test-key",
+ },
+ follow_redirects=False,
+ )
+ cfg = get_app_settings(db_session)
+ assert cfg.enabled is True
+ assert cfg.base_url == "https://my-api.com/v1"
+ assert cfg.model == "gpt-4o-mini"
+ assert cfg.api_key == "sk-test-key"
+
+ def test_save_with_blank_api_key_preserves_old(self, client, db_session):
+ # First save with a key
+ client.post(
+ "/settings",
+ data={"enabled": "on", "model": "gpt-4o", "api_key": "sk-original"},
+ follow_redirects=False,
+ )
+ # Second save without key (blank)
+ client.post(
+ "/settings",
+ data={"enabled": "on", "model": "gpt-4o", "api_key": ""},
+ follow_redirects=False,
+ )
+ cfg = get_app_settings(db_session)
+ assert cfg.api_key == "sk-original"
+
+ def test_save_disabled_state(self, client, db_session):
+ # First enable
+ client.post(
+ "/settings",
+ data={"enabled": "on", "model": "gpt-4o", "api_key": "sk-key"},
+ follow_redirects=False,
+ )
+ # Then disable (no 'enabled' checkbox)
+ client.post(
+ "/settings",
+ data={"model": "gpt-4o", "api_key": ""},
+ follow_redirects=False,
+ )
+ cfg = get_app_settings(db_session)
+ assert cfg.enabled is False
+
+ def test_save_settings_no_api_key_in_redirect_page(self, client):
+ client.post(
+ "/settings",
+ data={"enabled": "on", "model": "gpt-4o", "api_key": "sk-secret-key"},
+ follow_redirects=False,
+ )
+ response = client.get("/settings")
+ assert "sk-secret-key" not in response.text
+
+ def test_save_refuses_when_base_url_changes_and_key_blank(self, client, db_session):
+ """P1 fix: if base_url changes and api_key is blank, refuse save with error."""
+ client.post(
+ "/settings",
+ data={
+ "enabled": "on",
+ "base_url": "https://old-api.com/v1",
+ "model": "gpt-4o",
+ "api_key": "sk-old-key",
+ },
+ follow_redirects=False,
+ )
+ # Try saving with different base_url, no key
+ response = client.post(
+ "/settings",
+ data={
+ "enabled": "on",
+ "base_url": "https://new-api.com/v1",
+ "model": "gpt-4o",
+ "api_key": "", # blank + base_url changed → refuse
+ },
+ )
+ assert response.status_code == 200
+ assert "请重新输入 API Key 后保存" in response.text
+ # Old config should be unchanged — nothing was saved
+ cfg = get_app_settings(db_session)
+ assert cfg.base_url == "https://old-api.com/v1"
+ assert cfg.api_key == "sk-old-key"
+
+ def test_save_preserves_key_when_endpoint_unchanged_and_key_blank(self, client, db_session):
+ """P1 fix: if endpoint is unchanged and api_key is blank, keep old key."""
+ client.post(
+ "/settings",
+ data={
+ "enabled": "on",
+ "base_url": "https://api.openai.com/v1",
+ "model": "gpt-4o",
+ "api_key": "sk-original",
+ },
+ follow_redirects=False,
+ )
+ # Re-save same endpoint, blank key
+ client.post(
+ "/settings",
+ data={
+ "enabled": "on",
+ "base_url": "https://api.openai.com/v1",
+ "model": "gpt-4o",
+ "api_key": "",
+ },
+ follow_redirects=False,
+ )
+ cfg = get_app_settings(db_session)
+ assert cfg.api_key == "sk-original"
+
+ def test_save_preserves_key_when_only_model_changes_and_key_blank(self, client, db_session):
+ """Model change alone should not clear the key — same base_url, different model."""
+ client.post(
+ "/settings",
+ data={
+ "enabled": "on",
+ "base_url": "https://api.openai.com/v1",
+ "model": "gpt-4o",
+ "api_key": "sk-original",
+ },
+ follow_redirects=False,
+ )
+ # Change only model, leave api_key blank
+ client.post(
+ "/settings",
+ data={
+ "enabled": "on",
+ "base_url": "https://api.openai.com/v1",
+ "model": "gpt-4o-mini",
+ "api_key": "",
+ },
+ follow_redirects=False,
+ )
+ cfg = get_app_settings(db_session)
+ assert cfg.model == "gpt-4o-mini"
+ assert cfg.api_key == "sk-original"
+
+ def test_save_does_not_touch_ai_search_enabled(self, client, db_session):
+ """P2 fix: saving LLM settings must not reset ai_search_enabled."""
+ db_session.add(AppSetting(key="ai_search_enabled", value="true"))
+ db_session.commit()
+ client.post(
+ "/settings",
+ data={"enabled": "on", "model": "gpt-4o", "api_key": "sk-key"},
+ follow_redirects=False,
+ )
+ cfg = get_app_settings(db_session)
+ assert cfg.ai_search_enabled is True
+
+
+# ---------------------------------------------------------------------------
+# Routes: POST /settings/test
+# ---------------------------------------------------------------------------
+
+
+class TestTestConnectionRoute:
+ @patch("app.llm._call_chat_completion")
+ def test_test_connection_success(self, mock_call, client):
+ mock_call.return_value = {"choices": [{"message": {"content": "Hi"}}]}
+ response = client.post(
+ "/settings/test",
+ data={
+ "enabled": "on",
+ "base_url": "https://api.openai.com/v1",
+ "model": "gpt-4o",
+ "api_key": "sk-test",
+ },
+ )
+ assert response.status_code == 200
+ assert "连接成功" in response.text
+ assert "gpt-4o" in response.text
+
+ @patch("app.llm._call_chat_completion")
+ def test_test_connection_failure(self, mock_call, client):
+ import httpx
+
+ mock_call.side_effect = httpx.HTTPStatusError(
+ "401",
+ request=httpx.Request("POST", "http://x"),
+ response=httpx.Response(401),
+ )
+ response = client.post(
+ "/settings/test",
+ data={
+ "enabled": "on",
+ "base_url": "https://api.openai.com/v1",
+ "model": "gpt-4o",
+ "api_key": "sk-bad",
+ },
+ )
+ assert response.status_code == 200
+ assert "连接失败" in response.text
+ assert "401" in response.text
+
+ def test_test_connection_not_configured(self, client):
+ response = client.post(
+ "/settings/test",
+ data={
+ "enabled": "", # not checked
+ "base_url": "https://api.openai.com/v1",
+ "model": "",
+ "api_key": "",
+ },
+ )
+ assert response.status_code == 200
+ assert "未配置" in response.text
+
+ @patch("app.llm._call_chat_completion")
+ def test_test_connection_uses_stored_key_when_endpoint_matches(self, mock_call, client, db_session):
+ """When api_key is blank but base_url and model match saved config, the stored key should be used."""
+ mock_call.return_value = {"choices": [{"message": {"content": "Hi"}}]}
+ # Store a config first
+ save_app_settings(
+ db_session,
+ enabled=True,
+ base_url="https://api.openai.com/v1",
+ model="gpt-4o",
+ api_key="sk-stored-key",
+ )
+ response = client.post(
+ "/settings/test",
+ data={
+ "enabled": "on",
+ "base_url": "https://api.openai.com/v1",
+ "model": "gpt-4o",
+ "api_key": "", # blank → use stored key (endpoint matches)
+ },
+ )
+ assert response.status_code == 200
+ assert "连接成功" in response.text
+
+ @patch("app.llm._call_chat_completion")
+ def test_test_connection_uses_stored_key_when_only_model_changes(self, mock_call, client, db_session):
+ """Model changes under the same base_url can reuse the stored key."""
+ captured = {}
+
+ def fake_call(cfg, **kwargs):
+ captured["base_url"] = cfg.base_url
+ captured["model"] = cfg.model
+ captured["api_key"] = cfg.api_key
+ return {"choices": [{"message": {"content": "Hi"}}]}
+
+ mock_call.side_effect = fake_call
+ save_app_settings(
+ db_session,
+ enabled=True,
+ base_url="https://api.openai.com/v1",
+ model="gpt-4o",
+ api_key="sk-stored-key",
+ )
+ response = client.post(
+ "/settings/test",
+ data={
+ "enabled": "on",
+ "base_url": "https://api.openai.com/v1",
+ "model": "gpt-4o-mini",
+ "api_key": "",
+ },
+ )
+ assert response.status_code == 200
+ assert "连接成功" in response.text
+ assert captured == {
+ "base_url": "https://api.openai.com/v1",
+ "model": "gpt-4o-mini",
+ "api_key": "sk-stored-key",
+ }
+
+ def test_test_connection_refuses_stored_key_when_endpoint_changed(self, client, db_session):
+ """When base_url changed and api_key is blank, refuse to test."""
+ save_app_settings(
+ db_session,
+ enabled=True,
+ base_url="https://api.openai.com/v1",
+ model="gpt-4o",
+ api_key="sk-stored-key",
+ )
+ response = client.post(
+ "/settings/test",
+ data={
+ "enabled": "on",
+ "base_url": "https://attacker.example/v1", # different endpoint
+ "model": "gpt-4o",
+ "api_key": "", # blank → refuse
+ },
+ )
+ assert response.status_code == 200
+ assert "请重新输入 API Key" in response.text
+
+ def test_test_connection_result_shows_on_settings_page(self, client):
+ """Test result is rendered on the same settings page."""
+ response = client.post(
+ "/settings/test",
+ data={
+ "enabled": "",
+ "base_url": "https://api.openai.com/v1",
+ "model": "",
+ "api_key": "",
+ },
+ )
+ assert response.status_code == 200
+ assert "设置" in response.text
+ assert "保存设置" in response.text
+
+
+# ---------------------------------------------------------------------------
+# Graceful degradation: unconfigured LLM does not affect existing features
+# ---------------------------------------------------------------------------
+
+
+class TestGracefulDegradation:
+ def test_boxes_page_works_without_llm_config(self, client):
+ response = client.get("/boxes")
+ assert response.status_code == 200
+
+ def test_search_page_works_without_llm_config(self, client):
+ response = client.get("/search?q=test")
+ assert response.status_code == 200
+
+ def test_crud_works_without_llm_config(self, client, db_session):
+ from app.models import Box
+
+ response = client.post(
+ "/boxes",
+ data={"name": "No LLM Box"},
+ follow_redirects=False,
+ )
+ assert response.status_code == 303
+ assert db_session.query(Box).count() == 1