DH-WP-002 KOL总控室设计文档

1. 设计目标

KOL总控室 的设计目标是把 KOL 群体级情报、个体级画像和团队观察动作组织成一个连续工作台。

设计从三个层面展开：

层面	目标
产品与交互	团队先看全局，再下钻到 KOL 子集，最后阅读单个 KOL 的画像和证据。
后端与架构	后端提供读模型、聚合结果、筛选上下文和证据契约；前端渲染结构化结果。
UI / UX	页面符合 Data Horizon 后台风格，高密度、可扫描、支持 light / dark、适合日常重复使用。

2. 总体架构

Release 1 使用 dn_kol、dn_kol_profile、dn_raw_news 和 dn_kol_profile_summary 形成可上线的静态画像工作台。后续 Release 把实时消息抽取、动态状态、证据链和 Trading Matrix 反馈接入同一架构。

3. 领域对象

对象	说明	当前落地
KOL	KOL 基础资料和来源关系。	dn_kol
RawMessage	原始消息、新闻、社交内容和信号来源。	dn_raw_news
StaticProfile	第一阶段 KOL 静态画像产物。	dn_kol_profile
ProfileSummary	面向查询和聚合的结构化画像摘要。	dn_kol_profile_summary
DashboardAggregate	Dashboard 上的群体级聚合结果。	API 读投影
WorkbenchRow	KOL工作台表格行。	API 读投影
FilterContext	Dashboard 到工作台的筛选上下文。	API DTO + URL query
EvidenceView	可读证据片段。	Release 1 为画像证据摘要，后续接事件证据。
WatchlistItem	用户观察清单。	dn_kol_watchlist
SignalEvent	观点、策略、操作、情绪、持仓事件。	后续动态表
DynamicState	KOL 当前动态状态。	后续动态表
TMFeedback	TM 回测、模拟、实盘反馈。	后续反馈表

4. 后端设计

4.1 模块边界

新增 KOL control-room 读侧能力，保持与既有 KOL 管理能力分离：

模块	职责
既有 KOL 管理	KOL 配置、编辑、source 绑定、已有画像管理。
KOL总控室	面向运营和研究的聚合查看、筛选、画像阅读和观察清单。

建议后端目录：

server/api/kol_control_room.api
server/internal/domain/kolcontrolroom/
  dashboard.go
  evidence.go
  filter_context.go
  profile_summary.go
  widgets.go
  workbench.go

4.2 读模型

dn_kol_profile_summary 是 Release 1 的核心读模型。它从 dn_kol_profile.profile_json 和 report_md 重建，服务 Dashboard 聚合、工作台筛选、排序、facet 和表格摘要。

关键字段：

字段组	字段
标识	kol_id、kol_name
分类	role、rating、activity_level、holding_period
市场	asset_classes、symbols、trading_markets、strategy_styles
方法	risk_preference、decision_driver、trade_method、specialties
表达	expression_style、structure_completeness、one_line_profile
报告	brief_report_json、sample_count、profile_analyzed_at
维护	summary_version、created_at、updated_at

dn_kol_watchlist 保存用户观察清单，记录 user_id、kol_id、来源上下文和备注。

4.3 API

API prefix：

/v1/kol/control-room

Endpoint	作用
POST /dashboard	返回 Dashboard 覆盖率、群体摘要、模块数据和优先 KOL。
POST /workbench/list	返回 KOL工作台分页列表。
POST /workbench/facets	返回当前筛选条件下的筛选项计数。
POST /workbench/profile-detail	返回 KOL 画像详情、命中原因、简介报告和完整报告。
POST /evidence/list	返回画像证据摘要；后续返回事件证据。
POST /watchlist/list	返回用户观察清单。
POST /watchlist/add	加入观察清单。
POST /watchlist/remove	移出观察清单。

4.4 FilterContext

Dashboard 的每个可点击聚合项都返回 FilterContext。前端将其序列化到 URL query，工作台按该上下文请求列表和 facets。

{
  "sourcePage": "dashboard",
  "sourceModuleKey": "kol.profile.asset_distribution",
  "sourceLabel": "擅长标的 / BTC",
  "timeWindow": "profile_batch",
  "filters": {
    "profileStatus": ["profiled"],
    "symbols": ["BTC"]
  }
}

FilterContext 同时服务三个目标：

• 让 Dashboard 到 KOL工作台的跳转可复现。
• 让工作台顶部显示业务可读来源。
• 让画像详情可以展示本次命中原因。

4.5 可注册情报模块

KOL总控室 先采用固定核心模块交付 Release 1，再向可注册情报模块演进。后端通过模块 manifest 告诉前端有哪些可展示数据类别，前端以 Widget 容器渲染。

模块 manifest 建议包含：

字段	说明
moduleKey	稳定模块标识。
title	业务可读标题。
widgetType	前端渲染类型。
dataStatus	ready、pending、insufficient、error、stale。
summary	业务摘要。
payload	Widget 数据。
filterContext	点击后进入工作台的筛选上下文。
freshness	新鲜度。
confidence	置信度或数据充分度。

这套模型可扩展到 Data Horizon 其他金融信息感知模块。

5. 前端架构设计

5.1 路由

新增路由：

/datahorizon/kol-control-room

页面内部使用 Tab 或子路由承载：

• dashboard
• workbench

URL query 保存页面状态：

• 当前 tab
• 分页
• 排序
• Dashboard 来源上下文
• KOL 名称
• 角色、评级、活跃度、周期、资产类别、交易市场、标的、方向
• 当前选中 KOL

5.2 文件结构

web/src/api/datahorizon/kol-control-room.ts
web/src/views/datahorizon/kol-control-room/index.vue
web/src/views/datahorizon/kol-control-room/types.ts
web/src/views/datahorizon/kol-control-room/components/dashboard-module-card.vue
web/src/views/datahorizon/kol-control-room/components/filter-context-bar.vue
web/src/views/datahorizon/kol-control-room/components/profile-detail-modal.vue
web/src/views/datahorizon/kol-control-room/composables/use-filter-context.ts

5.3 状态管理

URL query 是筛选、分页、排序和来源上下文的真相源。Pinia 或本地状态只缓存字典、模块定义、用户布局和临时 UI 状态。

接口失败时，页面保留已加载区域并显示局部错误状态。Dashboard、Workbench、Facets、Watchlist 互不阻塞，避免单个接口失败导致 mounted hook 抛未处理异常。

6. UI / UX 交互设计

6.1 视觉方向

视觉语言延续 Data Horizon 后台：克制、清晰、高密度、适合金融信息扫描。科技金融感来自数据层级、状态语义、精确排版和证据可追溯，而不是装饰性渐变、玻璃卡片或营销式大图。

设计参数：

参数	取值
信息密度	高，支持 100+ KOL 浏览和多维筛选。
动效强度	低，只用于加载、刷新、筛选、弹窗切换和状态反馈。
主题	light / dark 同等支持。
组件	Ant Design Vue、Vben Admin、VxeGrid、ECharts 和现有主题 token。

6.2 Dashboard

Dashboard 首屏从上到下：

1. 覆盖与新鲜度条。
2. 群体摘要。
3. 方向、标的、市场、策略、周期分布。
4. 情绪和质量状态。
5. 优先查看 KOL 队列。

Widget 需要回答明确情报问题，例如：

• 当前整体偏多还是偏空？
• 哪些标的正在升温？
• 哪些市场分歧最大？
• 哪些策略风格正在集中出现？
• 哪些 KOL 观点新鲜且可用？
• 哪些数据质量不足，需要补采或延迟判断？

每个 Widget 至少包含标题、摘要、核心指标、贡献 KOL 数、证据数、新鲜度、置信度和点击后的筛选条件说明。

6.3 KOL工作台

KOL工作台布局：

区域	设计
来源上下文	从 Dashboard 进入时显示 chip，可清除。
常用筛选	两行内完成，优先 KOL 名称、角色、评级、周期、资产、标的、方向和画像状态。
高级筛选	折叠展示风险偏好、策略风格、语言区域、来源类型、新鲜度和证据质量。
表格	VxeGrid 高密度表格，左侧固定 KOL，右侧固定操作。
详情	点击 KOL 名称或画像按钮打开宽弹窗。

操作只保留业务必要动作：

• 画像
• 加入观察清单

6.4 画像详情

画像详情使用宽弹窗，建议 960px 以上宽度，适配 1366px 屏幕。内容结构：

• 简介报告
• 完整报告
• 证据片段

简介报告包含概要高亮、标签与元信息、画像维度表和决策心智。完整报告渲染 Markdown 正文。证据片段在 Release 1 显示画像证据摘要，后续接入消息级证据。

6.5 状态设计

所有状态都需要业务可读文案：

状态	显示方式
加载中	Skeleton + 局部 loading。
空结果	展示当前筛选条件和恢复建议。
接入中	标明动态状态或证据事件正在接入。
数据过期	展示最新更新时间和刷新入口。
样本不足	展示样本量和可用字段。
错误	局部错误提示 + 重试，不影响其他区域。

语义色必须搭配文字或数字，不只依赖颜色。

7. UI / UX 设计稿

最终设计稿已经固化为可浏览 HTML 原型，作为工程落地前端实现的界面基准：

• 打开 KOL总控室 UI / UX 交互原型
• 产物来源：Open Design data-horizon-kol-control-room-v9-taste-impeccable-redesign-2026-06-13
• 设计语言：中文界面、Data Horizon 后台式信息架构、高密度数据扫描、light / dark 主题、金融信息工作台风格。

7.1 原型覆盖页面

页面 / 状态	设计内容
KOL情报中心 Dashboard	覆盖数量、新鲜度、群体摘要、聚合情报 Widget、优先查看 KOL 队列。
KOL工作台	100+ KOL 的高密度列表、筛选、排序、分页、从 Dashboard 聚合项带条件进入。
画像详情	点击 KOL 名称或 画像 按钮后展示简介报告、完整报告和证据片段。
Widget 状态	正常、分歧、风险、回升、样本不足等状态，用标签、数字、文案共同表达。
主题状态	支持浅色 / 深色切换，保持 Data Horizon 后台统一视觉语言。

7.2 原型交互说明

• Dashboard 中的聚合情报 Widget 是主要阅读对象，点击后把对应筛选条件带入 KOL工作台。
• KOL工作台保留列表信息密度，画像内容通过右侧 / 弹窗详情承载，不把完整画像塞入表格。
• 画像详情沿用 Data Horizon 现有 KOL画像 的简介报告和完整报告结构，并为后续动态证据链预留证据片段区。
• 顶部搜索用于 KOL、标的、策略和市场的跨字段查找。
• 主题切换用于验证 light / dark 两种后台模式下的信息层级和状态色可读性。

8. 设计验收

• Dashboard 一屏可读，聚合情报优先，跳转能力自然存在。
• KOL工作台能真实容纳 100+ KOL 的浏览、筛选、排序和分页。
• 画像详情保留现有 KOL画像 中简介报告和完整报告的信息密度。
• Dashboard 聚合项到 KOL工作台筛选结果的路径清晰。
• light / dark 模式均完整。
• 状态矩阵完整，接入中、空状态、错误状态、样本不足和数据过期有不同表达。
• UI 语言与 Data Horizon 后台一致，适合日常运营、研究和交易协同使用。