DH-WP-002 KOL总控室工程化方案文档

1. 工程目标

Release 1 交付一条基于当前生产数据可运行的链路：

Release 1 使用现有静态画像和原始消息覆盖，不等待完整实时动态画像链路。页面需要真实显示当前数据状态，并为后续实时观点、实盘信号、证据链和 Trading Matrix 反馈保留接口字段。

2. Release 切分

Release	目标	主要能力
R1	静态画像驱动的 KOL总控室	画像摘要读模型、Dashboard、KOL工作台、画像详情、观察清单、基础状态设计。
R2	动态观点和证据链	信号事件抽取、动态状态、证据列表、Dashboard 实时模块。
R3	可注册情报模块	模块 registry、Widget snapshot、用户布局和持续扩展机制。
R4	TM 协同闭环	回测、模拟、实盘反馈回流，进入 KOL 质量和策略验证视图。

3. R1 范围

R1 交付：

dn_kol_profile_summary 读模型。
dn_kol_watchlist 观察清单表。
Profile parser 和 summary rebuild 能力。
Dashboard 聚合接口。
Workbench list / facets / profile-detail 接口。
Evidence placeholder 接口。
Watchlist list / add / remove 接口。
前端 KOL总控室 路由。
Dashboard 页面。
KOL工作台页面。
Profile detail modal。
Dashboard 到 Workbench 的 URL-backed FilterContext。
light / dark 和状态矩阵。

4. 后端工程方案

4.1 API 文件

新增：

server/api/kol_control_room.api

并在现有 openservice API 聚合文件中引入。

R1 Endpoint：

POST /v1/kol/control-room/dashboard
POST /v1/kol/control-room/workbench/list
POST /v1/kol/control-room/workbench/facets
POST /v1/kol/control-room/workbench/profile-detail
POST /v1/kol/control-room/evidence/list
POST /v1/kol/control-room/watchlist/list
POST /v1/kol/control-room/watchlist/add
POST /v1/kol/control-room/watchlist/remove

4.2 SQL 与模型

新增 SQL：

文件	用途
`docs/sql/dn_kol_profile_summary.sql`	KOL 画像摘要读模型。
`docs/sql/dn_kol_watchlist.sql`	用户观察清单。

新增或生成模型：

server/internal/model/mysql/kol_profile_summary_model*.go
server/internal/model/mysql/kol_watchlist_model*.go

修改模型聚合管理器，让 service context 可以注入新模型。

4.3 Domain service

新增目录：

server/internal/domain/kolcontrolroom/

职责拆分：

文件	职责
`profile_summary.go`	解析 `profile_json/report_md`，构建摘要读模型。
`filter_context.go`	校验、归一化、序列化 Dashboard 来源上下文。
`dashboard.go`	构建覆盖率、分布、优先 KOL 和模块聚合。
`workbench.go`	工作台查询条件、分页、排序、行投影。
`evidence.go`	R1 画像证据摘要与后续事件证据契约。
`widgets.go`	Dashboard 模块定义与数据状态。

4.4 错误与边界

后端逻辑需要返回结构化错误，不在 logic 中动态创建错误字符串。JSON 解析失败、筛选参数非法、分页越界、KOL 不存在、画像缺失和观察清单重复等情况应有明确返回。

列表类接口需要限制 pageSize 上限。筛选数组、搜索关键字、备注和 source context 需要长度限制。

5. 前端工程方案

5.1 文件结构

新增：

web/src/api/datahorizon/kol-control-room.ts
web/src/views/datahorizon/kol-control-room/index.vue
web/src/views/datahorizon/kol-control-room/dashboard.vue
web/src/views/datahorizon/kol-control-room/workbench.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

修改：

web/src/router/routes/modules/datahorizon.ts
web/src/locales/langs/zh-CN/datahorizon.json
web/src/locales/langs/en-US/datahorizon.json
web/src/api/datahorizon/index.ts

5.2 页面状态

URL query 保存：

tab
page
pageSize
sortField
sortOrder
sourceModuleKey
sourceLabel
kolName
role
rating
activityLevel
holdingPeriod
assetClasses
tradingMarkets
symbols
direction
selectedKolId

页面初始化时先从 URL 还原状态，再请求 Dashboard、Workbench、Facets 和 Watchlist。

5.3 接口容错

接口请求按区域隔离：

Dashboard 失败只影响 Dashboard。
Workbench 失败只影响列表。
Facets 失败保留基础筛选。
Watchlist 失败不阻断页面主流程。
Profile detail 失败只影响详情弹窗。

页面显示局部错误和重试入口，不让单个接口失败导致整个页面 mounted hook 抛未处理异常。

6. API 契约摘要

6.1 Dashboard

Request：

{
  "timeWindow": "profile_batch"
}

Response 核心结构：

{
  "overview": {
    "totalKol": 80,
    "profiledKol": 59,
    "profileCoverageRate": 0.7375,
    "profileBatchStart": "2026-06-10 08:00:00",
    "profileBatchEnd": "2026-06-11 03:00:00",
    "latestRawMessageAt": "2026-06-13 01:18:31"
  },
  "modules": [],
  "priorityKols": []
}

6.2 Workbench list

Request 包含分页、排序、filterContext 和筛选条件。

Response 行包含：

kolId
kolName
role
rating
activityLevel
holdingPeriod
assetClasses
tradingMarkets
riskPreference
oneLineProfile
currentViewSummary
focusSymbols
profileStatus
dynamicStatus
qualitySummary
matchContext

6.3 Profile detail

Response 包含：

KOL 基础信息。
profile status。
match context。
static profile。
dynamic state。
evidence。
full report markdown。

7. 实施顺序

核验 dn_kol_profile.profile_json schema 变体。
实现 profile parser 和 fixture 测试。
新增 dn_kol_profile_summary 与 dn_kol_watchlist SQL。
生成模型并接入 service context。
新增 control-room API 契约并生成 handler / logic。
实现 Dashboard、Workbench、Facets、ProfileDetail、Evidence、Watchlist logic。
新增前端 API wrapper。
新增路由和页面 shell。
实现 Dashboard。
实现 KOL工作台和 URL query 状态。
实现画像详情弹窗。
完成 light / dark、状态矩阵和浏览器 smoke。
调度独立 Review / Audit。

8. 验证策略

8.1 后端

profile parser 单元测试。
summary rebuild 测试。
dashboard aggregate 测试。
workbench list 筛选、排序、分页测试。
facets count 测试。
profile detail 三种场景测试：有画像、无画像、带来源上下文。
watchlist list / add / remove 测试。
API 参数边界测试。

8.2 前端

路由加载测试。
Dashboard static profile mode 渲染测试。
Workbench 100+ 行分页视觉 smoke。
URL query 刷新恢复测试。
Dashboard 点击进入 Workbench 的来源上下文测试。
Profile detail tab 切换测试。
light / dark 截图 smoke。
空、加载、错误、过期、样本不足状态测试。

8.3 本地与测试环境

本地验证需要满足：

前端 dev server 可进入 /datahorizon/kol-control-room。
后端测试环境提供 /v1/kol/control-room/* 接口。
登录态可用。
页面没有未处理 mounted hook 异常。
Dashboard 与 KOL工作台可以获取真实或测试数据。

测试环境验收需要记录接口返回、页面截图、浏览器 console 和构建结果。

9. Review / Audit 门禁

工程落地完成后，进行独立 Review / Audit。

角色：

角色	审查重点
backend reviewer	go-zero API、logic、domain service、model 查询、错误处理和权限边界。
frontend reviewer	路由、API wrapper、URL 状态、表格、画像详情、light / dark。
data contract reviewer	读模型、FilterContext、Dashboard aggregate、Workbench row 和 profile detail 字段语义。
security reviewer	后台权限、watchlist 用户边界、输入长度、JSON 解析和越权风险。
product / UX reviewer	是否满足一屏看全局、下钻到 KOL 子集、保留画像信息密度。

审计产物：

audit/<date>-kol-control-room-engineering-audit.md
Findings 按 blocker、high、medium、low 分级。
每条 finding 包含位置、影响、修复建议和验收标准。
blocker 和 high 修复后复审。
结论输出 ready、ready with follow-up 或 not ready。

10. 交付清单

后端：

API 契约和生成代码。
SQL 和模型。
profile parser。
Dashboard / Workbench / Facets / ProfileDetail / Evidence / Watchlist logic。
单元测试。

前端：

路由和菜单。
API wrapper。
Dashboard。
KOL工作台。
画像详情。
URL query 状态。
light / dark 和状态矩阵。

知识治理：

1. 工程目标​

2. Release 切分​

3. R1 范围​

4. 后端工程方案​

4.1 API 文件​

4.2 SQL 与模型​

4.3 Domain service​

4.4 错误与边界​

5. 前端工程方案​

5.1 文件结构​

5.2 页面状态​

5.3 接口容错​

6. API 契约摘要​

6.1 Dashboard​

6.2 Workbench list​

6.3 Profile detail​

7. 实施顺序​

8. 验证策略​

8.1 后端​

8.2 前端​

8.3 本地与测试环境​

9. Review / Audit 门禁​

10. 交付清单​