hw-web/doc/PORTAL_SEARCH_ANALYTICS_API_FRONTEND_GUIDE.md

Portal 搜索与访问监控接口前端接入指南

1. 基本说明

• 接口前缀：/prod-api（按当前前端 request.js 约定）
• 统一返回结构：{ code, msg, data }
• code = 200 表示成功，其他值表示失败

说明：

• 搜索结果当前覆盖：menu/web/web1/document/configType
• 已弃用表（不再纳入搜索）：hw_about_us_info、hw_product_case_info、hw_product_info、hw_product_info_detail

2. 搜索接口（展示端）

2.1 请求

• Method: GET
• URL: /prod-api/portal/search
• Query:
  • keyword 必填，1~50 字符
  • pageNum 可选，默认 1
  • pageSize 可选，默认 20，最大 50

示例：

GET /prod-api/portal/search?keyword=工业交换机&pageNum=1&pageSize=10

2.2 成功返回示例

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "total": 2,
    "rows": [
      {
        "sourceType": "web1",
        "title": "详情#7-1-1001",
        "snippet": "...<em class=\"search-hit\">工业交换机</em>用于工业现场网络互联...",
        "score": 120,
        "route": "/productCenter/detail",
        "routeQuery": {
          "webCode": "7",
          "typeId": "1",
          "deviceId": "1001"
        },
        "editRoute": null
      },
      {
        "sourceType": "menu",
        "title": "工业物联",
        "snippet": "<em class=\"search-hit\">工业物联</em>",
        "score": 110,
        "route": "/test",
        "routeQuery": {
          "id": "23"
        },
        "editRoute": null
      }
    ]
  }
}

2.3 失败返回示例

{
  "code": 500,
  "msg": "关键词不能为空"
}

3. 搜索接口（编辑端）

3.1 请求

• Method: GET
• URL: /prod-api/portal/search/edit
• Query 与展示端一致

示例：

GET /prod-api/portal/search/edit?keyword=RFID&pageNum=1&pageSize=20

3.2 返回差异

• rows[].editRoute 会返回编辑页路由，可直接 router.push(editRoute)

示例字段：

{
  "sourceType": "web1",
  "editRoute": "/editor?type=2&id=7,1,1001"
}

4. 匿名访问采集接口

4.1 请求

• Method: POST
• URL: /prod-api/portal/analytics/collect
• Content-Type 支持：
  • application/json
  • text/plain（兼容 navigator.sendBeacon）

请求体字段（常用）：

• visitorId 必填，访客匿名 ID
• sessionId 必填，会话 ID
• eventType 必填：page_view / page_leave / search_submit / download_click / contact_submit
• path 必填，当前页面路径
• eventTime 可选，毫秒时间戳
• stayMs 可选（page_leave 时建议传）
• keyword 可选（search_submit 时建议传）
• utmSource / utmMedium / utmCampaign 可选

示例：

{
  "visitorId": "b7b2b53f-9f0b-4d90-9a4b-1f53c0f0a911",
  "sessionId": "77c4d72a-75f8-46f1-a5f2-e7f72f6f9de0",
  "eventType": "page_view",
  "path": "/productCenter/detail?webCode=7&typeId=1&deviceId=1001",
  "referrer": "/productCenter",
  "eventTime": 1772438400000
}

成功返回：

{
  "code": 200,
  "msg": "操作成功"
}

失败返回（示例）：

{
  "code": 500,
  "msg": "采集失败: 不支持的事件类型"
}

5. 访问监控看板接口

5.1 请求

• Method: GET
• URL: /prod-api/portal/analytics/dashboard
• Query:
  • statDate 可选，格式 yyyy-MM-dd，默认当天
  • top 可选，排行数量，默认 10，最大 50

示例：

GET /prod-api/portal/analytics/dashboard?statDate=2026-03-02&top=10

5.2 返回示例

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "statDate": "2026-03-02",
    "pv": 1250,
    "uv": 420,
    "ipUv": 390,
    "avgStayMs": 18342,
    "bounceRate": 41.25,
    "searchCount": 86,
    "downloadCount": 29,
    "entryPages": [
      { "name": "/index", "value": 230 }
    ],
    "hotPages": [
      { "name": "/productCenter", "value": 402 }
    ],
    "hotKeywords": [
      { "name": "工业交换机", "value": 21 }
    ]
  }
}

6. 前端接入建议

• 搜索页渲染时直接使用：
  • 跳转：router.push({ path: item.route, query: item.routeQuery })
  • 高亮摘要：v-html="item.snippet"（仅渲染后端已生成片段）
• 编辑端定位：
  • if (item.editRoute) router.push(item.editRoute)
• 采集埋点：
  • page_view：路由切换后上报
  • page_leave：离开页面时通过 sendBeacon 上报 stayMs
  • search_submit：提交搜索时同步上报 keyword