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`

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

### 2.2 成功返回示例
```json
{
  "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 失败返回示例
```json
{
  "code": 500,
  "msg": "关键词不能为空"
}
```

## 3. 搜索接口（编辑端）
### 3.1 请求
- Method: `GET`
- URL: `/prod-api/portal/search/edit`
- Query 与展示端一致

示例：
```http
GET /prod-api/portal/search/edit?keyword=RFID&pageNum=1&pageSize=20
```

### 3.2 返回差异
- `rows[].editRoute` 会返回编辑页路由，可直接 `router.push(editRoute)`

示例字段：
```json
{
  "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` 可选

示例：
```json
{
  "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
}
```

成功返回：
```json
{
  "code": 200,
  "msg": "操作成功"
}
```

失败返回（示例）：
```json
{
  "code": 500,
  "msg": "采集失败: 不支持的事件类型"
}
```

## 5. 访问监控看板接口
### 5.1 请求
- Method: `GET`
- URL: `/prod-api/portal/analytics/dashboard`
- Query:
  - `statDate` 可选，格式 `yyyy-MM-dd`，默认当天
  - `top` 可选，排行数量，默认 `10`，最大 `50`

示例：
```http
GET /prod-api/portal/analytics/dashboard?statDate=2026-03-02&top=10
```

### 5.2 返回示例
```json
{
  "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`