'增加中转站链接接口'

code/api/audit/point_sale/routes_url_link.py

+"""读取 fortune-hub.transfer_url 默认第一行的 url_link。"""
+
+from __future__ import annotations
+
+import mysql.connector
+from mysql.connector import errors as mysql_errors
+
+from fastapi import APIRouter, HTTPException
+
+from api.response import ApiEnvelope, ok
+from api.settings import get_settings
+
+url_link_router = APIRouter(prefix="/api")
+
+
+def _fortune_hub_connect():
+    connect_kwargs = get_settings().mysql_connect_kwargs().copy()
+    connect_kwargs["database"] = "fortune-hub"
+    try:
+        return mysql.connector.connect(**connect_kwargs)
+    except mysql_errors.Error as e:
+        raise HTTPException(
+            status_code=502,
+            detail={"ok": False, "error": f"数据库连接失败: {e}"},
+        ) from e
+
+
+@url_link_router.get("/v1/url-link", response_model=ApiEnvelope)
+def get_url_link() -> ApiEnvelope:
+    conn = _fortune_hub_connect()
+    try:
+        cur = conn.cursor(dictionary=True)
+        cur.execute("SELECT url_link FROM transfer_url LIMIT 1")
+        row = cur.fetchone()
+    except mysql_errors.Error as e:
+        raise HTTPException(
+            status_code=502,
+            detail={"ok": False, "error": f"查询 transfer_url 失败: {e}"},
+        ) from e
+    finally:
+        conn.close()
+
+    if not row:
+        raise HTTPException(
+            status_code=404,
+            detail={"ok": False, "error": "transfer_url 没有可用数据"},
+        )
+
+    return ok(data={"url_link": row["url_link"]}, msg="成功")

code/index.py

@@ -3,6 +3,7 @@ from fastapi.exceptions import HTTPException, RequestValidationError
 
 from api.audit.point_sale.routes_clean import api_router
 from api.audit.point_sale.routes_risk_audit_visit import risk_audit_visit_router
+from api.audit.point_sale.routes_url_link import url_link_router
 from api.exception_handlers import http_exception_handler, validation_exception_handler
 from api.settings import get_settings
 
@@ -13,3 +14,4 @@ app.add_exception_handler(HTTPException, http_exception_handler)
 app.add_exception_handler(RequestValidationError, validation_exception_handler)
 app.include_router(api_router)
 app.include_router(risk_audit_visit_router)
+app.include_router(url_link_router)

docs/api.md

@@ -2,13 +2,14 @@
 
 ## 应用装配
 
-- **`code/index.py`**：`FastAPI` 实例 `app`，注册 `HTTPException` / `RequestValidationError` 处理器，挂载 `api_router` 与 `risk_audit_visit_router`（二者均来自 `api/audit/point_sale/`）。
+- **`code/index.py`**：`FastAPI` 实例 `app`，注册 `HTTPException` / `RequestValidationError` 处理器，挂载 `api_router`、`risk_audit_visit_router`、`url_link_router`（均来自 `api/audit/point_sale/`）。
 
 ## 路由
 
 - **前缀**：`/api`
 - **清洗**：`POST /api/v1/clean`（`api/audit/point_sale/routes_clean.py`）
 - **稽查走访表 CRUD**：`api/audit/point_sale/routes_risk_audit_visit.py`（`GET/PUT/DELETE /api/v1/risk-audit-visit...`，库表见 `code/sql_/risk_audit_visit.sql`）
+- **链接读取**：`GET /api/v1/url-link`（`api/audit/point_sale/routes_url_link.py`，单独查 `fortune-hub.transfer_url`）
 
 ### POST /api/v1/clean
 
@@ -32,6 +33,14 @@
 - **PUT `/api/v1/risk-audit-visit/{rav_id}`**：按主键**整行覆盖**更新。请求体为 **`RiskAuditVisitReplaceBody`**（与表业务列一致，**不含** `rav_id`；须提交全部字段键，值为 JSON `null` 表示写入 NULL）。`price`、`low_price_diff` 若前端传空字符串 `""`，与 `null` 同等视为写入 NULL。不存在 → **404**；违反唯一键 `uk_biz` → **409**；库连接等失败 → **502**。
 - **DELETE `/api/v1/risk-audit-visit/{rav_id}`**：按主键删除。不存在 → **404**。
 
+### GET /api/v1/url-link
+
+- 无请求参数。
+- 连接信息仍取 `Settings.mysql_connect_kwargs()` 对应的主机、端口、账号、密码；**仅此接口**在发起连接前把 `database` 改为 **`fortune-hub`**，不影响其它接口仍使用 `DB_NAME`。
+- 查询表 **`transfer_url`**，直接取 **默认第一行**：`SELECT url_link FROM transfer_url LIMIT 1`，不额外排序。
+- 成功时返回：`data = {"url_link": "<第一行的 url_link>"}`。
+- 表为空时 → **404**；数据库连接/查询失败 → **502**。
+
 连接参数同清洗写库：`Settings.mysql_connect_kwargs()`（见 [database.md](database.md)）。
 
 **成功时 `data` 形态**：仅返回与本次合并入库相关的统计（无成功落盘需合并时 `data` 为 `{}`）：
@@ -55,6 +64,6 @@
 
 ## 相关文件
 
-- **售点稽查**：`api/audit/point_sale/` 下 `routes_clean.py`、`routes_risk_audit_visit.py`、`schemas.py`、`team_conversion_loader.py`、`chengyu_puling_loader.py`、`low_price_loader.py`
+- **售点稽查**：`api/audit/point_sale/` 下 `routes_clean.py`、`routes_risk_audit_visit.py`、`routes_url_link.py`、`schemas.py`、`team_conversion_loader.py`、`chengyu_puling_loader.py`、`low_price_loader.py`
 - **通用**：`response.py`、`exception_handlers.py`、`settings.py`
 - 数据库环境变量说明见 [database.md](database.md)

docs/database.md

@@ -25,3 +25,4 @@
 
 - **`bi_price_xx`**：价盘，低价稽查只读。
 - **`risk_audit_visit`**：`POST /api/v1/clean` 在写出 `low_price_*.xlsx` 后，将合并结果全量 upsert；唯一键 **`uk_biz`** 为 `audit_date, source, store_name, channel_type, series, taste, weight, dealer_name`。
+- **`fortune-hub.transfer_url`**：仅 **`GET /api/v1/url-link`** 使用。该接口仍复用 `.env` 的 `DB_HOST`、`DB_PORT`、`DB_USER`、`DB_PASSWORD`，但会在接口内部把连接库名临时切到 **`fortune-hub`**，再读取 `transfer_url` 表默认第一行的 `url_link`；**不会改动** 其它接口使用的 `DB_NAME`。