# Spider 成熟产品功能扩展设计

## 概述

Spider 当前已具备完整的商户采集、清洗、分级、跟进核心流程。本设计覆盖 11 个功能点，分三个阶段实现，目标是将 Spider 从工具升级为成熟的运营平台。

---

## Phase 1：运营效率

### 1.1 商户分配机制

**数据模型：** `merchants_clean` 新增 `assigned_to VARCHAR(50) INDEX` 字段。

**后端 API：**
- `PUT /api/v1/merchants/clean/:id/assign` — body: `{assigned_to: "username"}`，admin/operator 可用
- `PUT /api/v1/merchants/clean/batch-assign` — body: `{ids: [1,2,3], assigned_to: "username"}`
- `GET /api/v1/merchants/clean` 增加 `assigned_to` query 参数筛选

**前端：**
- 商户列表新增"负责人"列
- 筛选栏新增"负责人"下拉（包含"我的商户"快捷项，自动填充当前用户名）
- 行操作增加分配按钮，弹出用户选择下拉

### 1.2 批量操作

**后端 API：**
- `PUT /api/v1/merchants/clean/batch-follow-status` — body: `{ids: [], follow_status: "contacted"}`
- `PUT /api/v1/merchants/clean/batch-level` — body: `{ids: [], level: "Hot"}`
- 复用已有 `batch-assign` 和 `batch-delete`

**前端：**
- 表格增加 checkbox 行选择
- 选中后顶部显示批量操作栏："已选 N 项" + 批量跟进状态 / 批量等级 / 批量分配 / 批量删除
- 操作完成后刷新列表、清空选择

### 1.3 数据导入

**后端 API：**
- `POST /api/v1/merchants/clean/import` — multipart/form-data 上传 CSV
- CSV 必须包含 `tg_username` 列，可选列：merchant_name, website, email, phone, industry_tag, level
- 去重逻辑：tg_username 已存在则跳过
- 响应：`{imported: 10, skipped: 3, failed: 1, errors: ["row 5: invalid level"]}`

**前端：**
- 导出按钮旁增加"导入"按钮
- 弹出 Modal：Dragger 上传 CSV → 显示导入结果统计

### 1.4 商户详情页

**路由：** `/merchants/:id`，独立页面

**布局：**
- 顶部：TG 用户名 + 商户名 + 等级 Tag + 跟进状态 Badge + 负责人 + 操作按钮（编辑/分配）
- 左列（65%）：基本信息 Descriptions + 来源记录卡片列表 + 所属群组列表
- 右列（35%）：跟进备注 Timeline 组件（含添加输入框）
- 底部：TG 预览 iframe

**列表页联动：** 商户名列和查看按钮都链接到详情页

---

## Phase 2：可观测性与安全

### 2.1 操作审计日志

**数据模型：**
```
audit_logs:
  id          BIGINT PK AUTO_INCREMENT
  username    VARCHAR(50) INDEX      -- 操作人
  action      VARCHAR(50) INDEX      -- create/update/delete/assign/import/login/export
  target_type VARCHAR(50) INDEX      -- merchant/user/keyword/schedule/setting/task
  target_id   VARCHAR(100)           -- 目标 ID 或标识
  detail      JSON                   -- 变更前后的字段差异 {field: {old: x, new: y}}
  ip          VARCHAR(45)
  created_at  DATETIME INDEX
```

**后端：**
- 审计中间件：在关键 handler 中记录操作（商户编辑/删除/分配/导入、用户管理、设置变更、任务启停）
- `GET /api/v1/audit-logs` — 分页查询，支持 username/action/target_type/date_range 筛选（admin only）
- 辅助函数 `logAudit(c *gin.Context, action, targetType, targetID string, detail interface{})` 供各 handler 调用

**前端：**
- 新增"审计日志"页面（admin 菜单），表格展示操作记录
- 商户详情页右侧时间线增加"操作历史"Tab，展示该商户的审计记录

### 2.2 通知系统

**数据模型：**
```
notification_configs:
  id          INT PK AUTO_INCREMENT
  name        VARCHAR(100)
  event_type  VARCHAR(50)   -- task_completed/task_failed/new_hot_merchant/schedule_run
  channel     VARCHAR(20)   -- webhook/tg_bot
  config      JSON          -- {url: "..."} 或 {bot_token: "...", chat_id: "..."}
  enabled     BOOL DEFAULT true
  created_at  DATETIME
  updated_at  DATETIME
```

**后端：**
- `internal/notification/` 包：Notifier 接口 + WebhookNotifier + TgBotNotifier 实现
- 事件触发点：task manager 完成/失败时、processor 发现 Hot 商户时、scheduler 执行后
- `GET/POST/PUT/DELETE /api/v1/notification-configs` — CRUD 通知配置（admin）
- `POST /api/v1/notification-configs/:id/test` — 发送测试通知

**前端：**
- 设置页面新增"通知管理"Tab
- 配置表格：事件类型、通知渠道、目标地址、启用开关
- 支持测试发送

### 2.3 系统健康监控

**后端 API：**
- `GET /api/v1/system/health` — 返回各组件状态
  - MySQL 连接状态 + 连接池使用率
  - Redis 连接状态
  - TG 账号状态汇总（idle/online/cooling 各几个）
  - 最近 24h 任务统计（成功/失败/运行中）
  - 磁盘/数据量（merchants_raw 行数、merchants_clean 行数、task_details 行数）

**前端：**
- Dashboard 页面顶部增加系统状态卡片区域
- 各组件用绿/黄/红指示灯显示状态
- TG 账号状态一目了然

### 2.4 数据归档

**后端：**
- `POST /api/v1/merchants/archive` — 将满足条件的商户移入归档表 `merchants_archived`
  - 条件：status=invalid/bot + 超过 90 天未更新，或 follow_status=rejected + 超过 180 天
  - 可配置天数阈值
- `GET /api/v1/merchants/archived` — 查看归档数据（只读，分页）
- `POST /api/v1/merchants/archived/:id/restore` — 恢复单条数据
- 可配合定时任务自动归档

**数据模型：** `merchants_archived` 与 `merchants_clean` 结构一致，增加 `archived_at DATETIME` 和 `archive_reason VARCHAR(100)`

**前端：**
- 原始数据页面增加"归档数据"Tab
- 归档操作按钮在商户列表批量操作栏中

---

## Phase 3：数据洞察

### 3.1 转化漏斗分析

**后端 API：**
- `GET /api/v1/analytics/funnel` — 返回各阶段数量
  ```json
  {
    "raw_total": 5000,
    "clean_total": 1200,
    "valid_total": 980,
    "contacted": 320,
    "cooperating": 85,
    "rejected": 45,
    "conversion_rates": {
      "raw_to_clean": 0.24,
      "clean_to_valid": 0.817,
      "valid_to_contacted": 0.327,
      "contacted_to_cooperating": 0.266
    }
  }
  ```

**前端：**
- Dashboard 新增漏斗图卡片（使用 antd 进度条或简单 div 渐变实现，不引入重型图表库）
- 每级显示数量和转化率百分比

### 3.2 来源效率分析

**后端 API：**
- `GET /api/v1/analytics/source-efficiency` — 按来源类型和关键词统计
  ```json
  {
    "by_source_type": [
      {"source_type": "tg_channel", "raw_count": 3000, "clean_count": 800, "hot_count": 120, "efficiency": 0.04},
      {"source_type": "web", "raw_count": 1500, "clean_count": 300, "hot_count": 50, "efficiency": 0.033}
    ],
    "top_keywords": [
      {"keyword": "担保", "merchants_found": 230, "hot_count": 45},
      {"keyword": "支付", "merchants_found": 180, "hot_count": 30}
    ],
    "top_groups": [
      {"group_username": "xxx", "members_found": 150, "valid_count": 80}
    ]
  }
  ```

**前端：**
- 新增"数据分析"页面
- 来源效率对比表格 + 柱状图（纯 CSS/div 实现）
- Top 关键词和 Top 群组排行榜

### 3.3 趋势报表

**后端 API：**
- `GET /api/v1/analytics/trends` — query: `period=week|month`, `range=30|90|180`
  ```json
  {
    "period": "week",
    "data": [
      {"period_label": "2026-W14", "raw_added": 500, "clean_added": 120, "contacted": 30, "cooperating": 5},
      {"period_label": "2026-W15", "raw_added": 600, "clean_added": 150, "contacted": 45, "cooperating": 8}
    ]
  }
  ```

**前端：**
- 数据分析页面增加趋势区域
- 按周/月切换，表格 + 简单折线/柱状图
- 支持导出报表 CSV

---

## 技术约束

- 不引入新的重型依赖（图表用 antd + CSS 实现，不加 echarts/recharts）
- 所有新 API 遵循现有 RESTful 风格和 response 格式
- 新表自动通过 GORM AutoMigrate 创建
- 审计日志不影响主流程性能（异步写入或 goroutine）
- 前端新页面加入现有路由和侧边栏菜单
- 权限控制：分析和审计页面 admin 可见，商户操作 admin/operator 可用