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 — 返回各阶段数量

{
"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 — 按来源类型和关键词统计

{
"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

{
"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 可用

2026-04-14-mature-product-features-design.md 7.9 KB Bezpośredni odnośnik Historia Czysty

Spider 成熟产品功能扩展设计

概述

Phase 1：运营效率

1.1 商户分配机制

1.2 批量操作

1.3 数据导入

1.4 商户详情页

Phase 2：可观测性与安全

2.1 操作审计日志

2.2 通知系统

2.3 系统健康监控

2.4 数据归档

Phase 3：数据洞察

3.1 转化漏斗分析

3.2 来源效率分析

3.3 趋势报表

技术约束

2026-04-14-mature-product-features-design.md 7.9 KB

Bezpośredni odnośnik Historia Czysty