feat: 新增路线详情关联管家顾问及相关功能

详细变更如下：
- 更新 .gitignore 文件，添加 pnpm-store 忽略规则
- 新增数据库迁移脚本，为 DetailRecord 添加可空的 conciergeAdvisorId 字段用于关联管家顾问
- 完善 Admin 后台玩法详情编辑器，支持选择关联的管家顾问并校验合法性
- 公共 API 支持返回已启用的管家顾问完整数据，不在详情表中冗余存储管家资料
- 小程序端新增详情页联系管家入口、个人页最近浏览历史功能
- 更新所有相关文档与测试用例，修复下拉选择框的 z-index 样式问题

WonderQ-Admin/alembic/versions/0023_detail_concierge_advisor.py

@@ -0,0 +1,22 @@
+"""Add optional concierge association to route details.
+
+Revision ID: 0023_detail_concierge_advisor
+Revises: 0022_opaque_ids
+"""
+
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = "0023_detail_concierge_advisor"
+down_revision = "0022_opaque_ids"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column("DetailRecord", sa.Column("conciergeAdvisorId", sa.String(), nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column("DetailRecord", "conciergeAdvisorId")

WonderQ-Admin/app/models.py

@@ -206,6 +206,7 @@ class DetailRecord(Base):
     excluded: Mapped[list[str]] = mapped_column(JSONB, default=list, nullable=False)
     notes: Mapped[list[str]] = mapped_column(JSONB, default=list, nullable=False)
     gallery: Mapped[list[str]] = mapped_column(JSONB, default=list, nullable=False)
+    conciergeAdvisorId: Mapped[str | None] = mapped_column(String, nullable=True)
     isActive: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False, index=True)
     sortOrder: Mapped[int] = mapped_column(Integer, default=0, nullable=False, index=True)
     createdAt: Mapped[datetime] = mapped_column(DateTime, default=utc_now, nullable=False)

WonderQ-Admin/app/routers/admin.py

@@ -841,6 +841,18 @@ def detail_key_conflict(db: Session, key: str, current_id: str | None = None) ->
         detail_error(409, "详情 key 已存在", "DETAIL_KEY_EXISTS", {"key": key})
 
 
+def validate_detail_concierge_advisor(db: Session, advisor_id: str | None) -> None:
+    if not advisor_id:
+        return
+    if not db.get(ConciergeAdvisor, advisor_id):
+        detail_error(
+            422,
+            "关联的管家顾问不存在",
+            "DETAIL_CONCIERGE_ADVISOR_INVALID",
+            {"conciergeAdvisorId": advisor_id},
+        )
+
+
 def validate_detail_order(item_ids: list[str], current_ids: list[str]) -> None:
     validate_wanfa_order(item_ids, current_ids, "DETAIL_REORDER_INVALID")
 
@@ -881,6 +893,7 @@ def create_detail(
     db: Session = Depends(get_db),
 ):
     detail_key_conflict(db, body.key)
+    validate_detail_concierge_advisor(db, body.conciergeAdvisorId)
     detail = DetailRecord(
         **body.model_dump(exclude={"sortOrder"}),
         sortOrder=body.sortOrder if body.sortOrder is not None else next_site_sort_order(db, DetailRecord),
@@ -905,6 +918,8 @@ def update_detail(
     before = detail_record_dict(detail)
     if "key" in body.model_fields_set:
         detail_key_conflict(db, body.key or "", detail.id)
+    if "conciergeAdvisorId" in body.model_fields_set:
+        validate_detail_concierge_advisor(db, body.conciergeAdvisorId)
     for field in body.model_fields_set:
         setattr(detail, field, getattr(body, field))
     db.flush()

WonderQ-Admin/app/routers/public.py

@@ -64,7 +64,12 @@ def get_public_detail(detail_key: str, db: Session = Depends(get_db)):
     )
     if not detail:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="详情不存在")
-    return success_response(public_detail_dict(detail))
+    advisor = None
+    if detail.conciergeAdvisorId:
+        candidate = db.get(ConciergeAdvisor, detail.conciergeAdvisorId)
+        if candidate and candidate.isActive:
+            advisor = candidate
+    return success_response(public_detail_dict(detail, advisor))
 
 
 @router.get("/api/public/concierge/advisors")

WonderQ-Admin/app/schemas.py

@@ -193,6 +193,7 @@ class DetailCreate(BaseModel):
     excluded: list[str] = Field(default_factory=list)
     notes: list[str] = Field(default_factory=list)
     gallery: list[str] = Field(default_factory=list)
+    conciergeAdvisorId: str | None = Field(default=None, max_length=120)
     isActive: bool = True
     sortOrder: int | None = Field(default=None, ge=0)
 
@@ -211,6 +212,14 @@ class DetailCreate(BaseModel):
     def validate_detail_gallery(cls, value: list[str]) -> list[str]:
         return normalize_detail_gallery(value)
 
+    @field_validator("conciergeAdvisorId", mode="before")
+    @classmethod
+    def normalize_concierge_advisor_id(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        normalized = str(value).strip()
+        return normalized or None
+
 
 class DetailPatch(BaseModel):
     key: str | None = Field(default=None, min_length=1, max_length=120)
@@ -224,6 +233,7 @@ class DetailPatch(BaseModel):
     excluded: list[str] | None = None
     notes: list[str] | None = None
     gallery: list[str] | None = None
+    conciergeAdvisorId: str | None = Field(default=None, max_length=120)
     isActive: bool | None = None
     sortOrder: int | None = Field(default=None, ge=0)
 
@@ -248,6 +258,14 @@ class DetailPatch(BaseModel):
             raise ValueError("字段不能为空")
         return normalize_detail_gallery(value)
 
+    @field_validator("conciergeAdvisorId", mode="before")
+    @classmethod
+    def normalize_optional_concierge_advisor_id(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        normalized = str(value).strip()
+        return normalized or None
+
 
 class HomeExperienceCreate(BaseModel):
     badge: str = Field(min_length=1, max_length=40)

WonderQ-Admin/app/serializers.py

@@ -50,7 +50,7 @@ def detail_record_dict(detail) -> dict:
     return model_dict(detail)
 
 
-def public_detail_dict(detail) -> dict:
+def public_detail_dict(detail, concierge_advisor=None) -> dict:
     return {
         "key": detail.key,
         "eyebrow": detail.eyebrow,
@@ -63,6 +63,7 @@ def public_detail_dict(detail) -> dict:
         "excluded": detail.excluded or [],
         "notes": detail.notes or [],
         "gallery": detail.gallery or [],
+        "conciergeAdvisor": public_concierge_advisor_dict(concierge_advisor) if concierge_advisor else None,
     }
 
 

WonderQ-Admin/tests/test_details.py

@@ -7,7 +7,7 @@ import pytest
 from app.auth import require_admin
 from app.database import get_db
 from app.main import create_app
-from app.models import AdminUser, DetailRecord
+from app.models import AdminUser, ConciergeAdvisor, DetailRecord
 from app.schemas import DetailCreate
 
 
@@ -79,6 +79,7 @@ def make_detail(**overrides):
         "gallery": ["https://example.test/family-water.jpg"],
         "isActive": True,
         "sortOrder": 0,
+        "conciergeAdvisorId": None,
         "createdAt": datetime(2026, 1, 1),
         "updatedAt": datetime(2026, 1, 2),
     }
@@ -86,6 +87,23 @@ def make_detail(**overrides):
     return DetailRecord(**values)
 
 
+def make_advisor(**overrides):
+    values = {
+        "id": "advisor-amanda",
+        "avatar": "https://example.test/amanda.jpg",
+        "name": "Amanda",
+        "role": "SENIOR TRAVEL ADVISOR",
+        "details": [{"icon": "calendar", "label": "服务经验：8年"}],
+        "qrImage": "https://example.test/amanda-qr.png",
+        "isActive": True,
+        "sortOrder": 0,
+        "createdAt": datetime(2026, 1, 1),
+        "updatedAt": datetime(2026, 1, 2),
+    }
+    values.update(overrides)
+    return ConciergeAdvisor(**values)
+
+
 def authenticated_app(fake_db):
     app = create_app()
     app.dependency_overrides[get_db] = lambda: fake_db
@@ -130,6 +148,20 @@ def test_detail_schema_rejects_invalid_gallery_url():
         )
 
 
+def test_detail_schema_normalizes_empty_concierge_advisor_id_to_null():
+    detail = DetailCreate(
+        key="family-water",
+        eyebrow="玩法推荐",
+        duration="5天4晚",
+        title="亲子玩水",
+        subtitle="贵州路线",
+        intro="介绍",
+        conciergeAdvisorId="   ",
+    )
+
+    assert detail.conciergeAdvisorId is None
+
+
 def test_public_detail_returns_frontend_contract_without_auth():
     fake_db = FakeDb(scalar_values=[make_detail()])
     app = create_app()
@@ -156,10 +188,53 @@ def test_public_detail_returns_frontend_contract_without_auth():
         "excluded": ["往返大交通"],
         "notes": ["请准备轻便雨具。"],
         "gallery": ["https://example.test/family-water.jpg"],
+        "conciergeAdvisor": None,
         },
     }
 
 
+def test_public_detail_includes_active_concierge_advisor():
+    advisor = make_advisor()
+    fake_db = FakeDb(
+        scalar_values=[make_detail(conciergeAdvisorId=advisor.id)],
+        get_results={(ConciergeAdvisor, advisor.id): advisor},
+    )
+    app = create_app()
+    app.dependency_overrides[get_db] = lambda: fake_db
+
+    try:
+        response = TestClient(app).get("/api/public/details/family-water")
+    finally:
+        app.dependency_overrides.clear()
+
+    assert response.status_code == 200
+    assert response.json()["data"]["conciergeAdvisor"] == {
+        "avatar": advisor.avatar,
+        "name": advisor.name,
+        "role": advisor.role,
+        "details": advisor.details,
+        "qrImage": advisor.qrImage,
+    }
+
+
+def test_public_detail_hides_inactive_concierge_advisor():
+    advisor = make_advisor(isActive=False)
+    fake_db = FakeDb(
+        scalar_values=[make_detail(conciergeAdvisorId=advisor.id)],
+        get_results={(ConciergeAdvisor, advisor.id): advisor},
+    )
+    app = create_app()
+    app.dependency_overrides[get_db] = lambda: fake_db
+
+    try:
+        response = TestClient(app).get("/api/public/details/family-water")
+    finally:
+        app.dependency_overrides.clear()
+
+    assert response.status_code == 200
+    assert response.json()["data"]["conciergeAdvisor"] is None
+
+
 def test_public_detail_returns_not_found_for_missing_key():
     fake_db = FakeDb(scalar_values=[None])
     app = create_app()
@@ -227,3 +302,27 @@ def test_admin_detail_create_normalizes_key_and_appends():
     assert response.status_code == 201
     assert response.json()["data"]["key"] == "family-water"
     assert fake_db.added[0].sortOrder == 3
+
+
+def test_admin_detail_create_rejects_unknown_concierge_advisor():
+    fake_db = FakeDb(scalar_values=[None, 2])
+    app = authenticated_app(fake_db)
+
+    try:
+        response = TestClient(app).post(
+            "/api/admin/details",
+            json={
+                "key": "family-water",
+                "eyebrow": "玩法推荐",
+                "duration": "5天4晚",
+                "title": "亲子玩水",
+                "subtitle": "贵州路线",
+                "intro": "沿着山地深入探索。",
+                "conciergeAdvisorId": "missing-advisor",
+            },
+        )
+    finally:
+        app.dependency_overrides.clear()
+
+    assert response.status_code == 422
+    assert response.json()["errorCode"] == "DETAIL_CONCIERGE_ADVISOR_INVALID"