worldquant-alpha-system/.scratch/dataset-catalog/spec.md

数据集与数据字段：单数据集研究及 Alpha 模板输入

Status: ready-for-agent

日期：2026-09-07
类型：功能规格
范围：数据集目录、数据字段、详情抽屉、本地研究备注、可靠同步、模板输入交接。
依据：本次对话中确认的流程及 Lark 风格原型。测试边界已由用户确认。

Problem Statement

研究员通常先选定一个数据集，再集中研究该数据集中的字段，并将整集字段提供给 Alpha 模板。以跨数据集搜索、逐个收集字段或命名字段池为主的流程，会增加准备步骤，也容易无意间混入其他数据集。

研究员需要在表格中按研究范围和分类筛选数据集，逐层查看字段和详情，同时保留列表上下文。搜索、筛选、排序或翻页只是帮助查看，不应悄悄缩小模板输入。只有研究员主动取消字段选择时，输入范围才发生变化。

当前系统已有账户连接、Alpha 管理、本地研究记录和持久化同步任务，尚无数据集、字段及模板输入能力。旧项目提供功能参考，不迁移旧库，也不继承字段池和跨数据集组合的默认工作流。

Solution

增加以单数据集为中心的数据目录。研究员设置 Region、Universe、Delay，按分类和子分类筛选，在 Table 中选定一个数据集。默认将该数据集的全部字段作为模板输入。

“查看字段”打开占整个工作区宽度 75% 的右抽屉，抽屉内仍使用 Table。点击字段打开占工作区宽度约 30% 的第二层右抽屉。关闭字段详情后保留第一层抽屉的搜索、筛选、页码和勾选；关闭字段列表后恢复原数据集列表。数据集自身详情也使用右抽屉。

页面和抽屉的功能操作区统一放在顶部，不设置重复的页面或抽屉标题，不在底部再放一组功能按钮。分页属于 Table 交互，可保留在表格下方。用选中数据集、字段数和研究范围表达当前上下文，避免大段功能说明及辅助小字。

界面采用已确认的 Lark 风格：白色主工作区、中性浅色侧栏、蓝色主操作、单行常规字重表格、轻边框及统一间距。正式实现沿用现有应用框架和控件体系，不直接把演示数据或原型脚本接入生产。

User Stories

1. 作为研究员，我希望从工作空间进入数据集目录，以便围绕一个数据集开展研究。
2. 作为研究员，我希望按 Region 选择研究地区，以便看到该地区可用的数据集。
3. 作为研究员，我希望 Universe 与 Region 联动，以便避免组合不兼容的研究范围。
4. 作为研究员，我希望设置 Delay，以便目录、字段和模板输入使用一致的研究条件。
5. 作为研究员，我希望搜索数据集名称或 ID，以便快速定位已知数据集。
6. 作为研究员，我希望按分类筛选，以便集中查看基本面、分析师、新闻或价量等类型的数据。
7. 作为研究员，我希望子分类随分类联动，以便进一步缩小范围而不产生无效条件。
8. 作为研究员，我希望重置目录筛选时保留明确设置的研究范围，以便重新浏览同一研究环境。
9. 作为研究员，我希望在可排序、可分页的 Table 中查看数据集，以便高效比较名称、分类、字段数和同步状态。
10. 作为研究员，我希望一次只选中一个数据集，以便默认构建单数据集 Alpha。
11. 作为研究员，我希望选中数据集后默认包含整集字段，以便省去逐个勾选的步骤。
12. 作为研究员，我希望直接从数据集使用全部字段，以便无需先打开字段列表才能准备模板输入。
13. 作为研究员，我希望在右抽屉查看数据集说明、ID、分类、子分类和研究范围，以便了解数据含义且不离开列表。
14. 作为研究员，我希望在 75% 宽的右抽屉查看数据字段，以便获得足够的表格空间并保留数据集背景。
15. 作为研究员，我希望搜索当前数据集内的字段名称或 ID，以便定位关注的字段。
16. 作为研究员，我希望按字段类型和覆盖率筛选，以便比较符合当前研究条件的字段。
17. 作为研究员，我希望字段表格支持排序和分页，以便浏览较大的数据集。
18. 作为研究员，我希望筛选和翻页不改变模板输入，以便“全部字段”始终指当前数据集的完整字段集合。
19. 作为研究员，我希望通过取消勾选排除个别字段，以便保留整集为主的研究方式并处理例外。
20. 作为研究员，我希望表头全选操作作用于整个数据集，以便不会把当前页或当前搜索结果误当成全集。
21. 作为研究员，我希望顶部展示全部字段数或已选数/总数，以便随时确认模板输入范围。
22. 作为研究员，我希望能恢复全选，以便快速撤销排除并回到整集研究。
23. 作为研究员，我希望排除全部字段后无法提交输入，以便避免创建空的研究任务。
24. 作为研究员，我希望在约 30% 宽的第二层抽屉查看字段详情，以便对照当前字段列表理解含义。
25. 作为研究员，我希望字段详情显示 ID、所属数据集、类型、说明及平台实际提供的指标，以便判断字段是否适合研究。
26. 作为研究员，我希望缺失指标和单位显示为未提供，以便不把未知值误认为零或确定事实。
27. 作为研究员，我希望能在字段详情中排除或重新加入字段，以便判断后直接更新模板输入。
28. 作为研究员，我希望逐层关闭抽屉时保留搜索、页码和勾选，以便继续刚才的研究。
29. 作为研究员，我希望按钮统一放在顶部且界面少说明文字，以便把注意力留给数据。
30. 作为研究员，我希望能用键盘操作列表和抽屉，以便完成选择、查看和逐层返回。
31. 作为研究员，我希望窄屏下抽屉和顶部操作仍可用，以便在较小窗口中继续查看。
32. 作为研究员，我希望查看同步进度、失败原因、重试与取消，以便知道字段是否已经完整取得。
33. 作为研究员，我希望同步失败或重启后能继续，以便不必反复从头下载大数据集。
34. 作为研究员，我希望不完整同步不会被当成全部字段，以便模板不会遗漏尚未获取的数据。
35. 作为研究员，我希望为数据集和字段保存本地研究备注，以便记录理解与研究假设。
36. 作为研究员，我希望平台同步不会覆盖本地备注，以便长期积累研究记录。
37. 作为研究员，我希望模板输入明确记录数据集、研究范围和字段集合，以便后续模板消费时不靠猜测恢复条件。
38. 作为研究员，我希望已保存的输入不随后台同步自动变化，以便能复现一次研究准备结果。
39. 作为研究员，我希望模板尚未接入时能明确保存输入草稿，以便先完成准备且不会误以为已经开始回测。
40. 作为研究员，我希望已有账户、Alpha 和 AI 助手功能继续正常工作，以便新增数据目录不破坏现有研究流程。

Implementation Decisions

已确认的交互约束

• 入口以数据集为中心，不以跨数据集字段检索为默认入口。数据集单选，不提供多数据集输入篮子。
• 数据集和字段列表均采用 Table，包含筛选、稳定排序、分页和明确的选中状态。
• 数据集列表默认列为选择、数据集名称、分类、字段数、同步状态、查看字段。字段列表默认列为选择、字段名称、类型、覆盖率、用户数、Alpha 数。字段指标仅在上游确实提供时展示。
• 单元格保持单行、14px/22px/400；较长名称省略并可进入详情查看。ID 放在详情和可选的悬停提示中，子分类保留在筛选和详情中，不重新堆叠成双行小字。
• 字段抽屉宽度为完整工作区的 75%，字段详情抽屉宽度为完整工作区的 30%，不是父抽屉宽度的 30%。工作区指应用整体承载区域，包含侧栏；不按剩余表格宽度计算。
• 字段详情覆盖字段抽屉右部，不推动父抽屉或重建父列表。普通数据集详情、模板输入面板沿用常规右抽屉，不强行套用字段详情的 30%。
• 所有主要功能操作均在各自页面或抽屉顶部。保留关闭入口和无障碍名称，不恢复重复标题。详情正文中的对象名称是业务内容，不属于重复面板标题。
• Esc、关闭按钮及遮罩点击逐层关闭；背景不可交互，焦点限制在当前最上层抽屉。关闭时优先返回原触发控件，原控件不存在时回到有效的列表入口。
• 查看字段、打开详情、逐层返回不丢失父列表状态。重新打开一个已完全关闭的字段列表可重置浏览条件，但显式字段排除应按当前研究会话和范围保留。
• 与现有 AI 助手共享遮罩与焦点管理：不能同时出现两个可操作的模态层。窄屏沿用现有聊天展开时暂时隐藏业务详情、收起后恢复的规则；不得修改 75%/30% 的计算基准来挤出聊天空间。

视觉与组件

• 正式界面沿用现有 React、TypeScript、Semi Design 控件体系，实现 Lark/UD 风格的 Table、Button、Input、Select、Drawer、Tag 和反馈状态。原型的原生 HTML 控件是演示实现，不是正式组件选型。
• 主工作区白色或近白；侧栏直接使用 #f9f9f9，选中侧栏背景直接使用 #1f23290d，选中文字字重 500。蓝色用于主操作、链接、焦点和当前状态，不用作普通分类装饰。
• 间距以 4px 为基准，统一页面留白；控件圆角约 6px，表格容器约 8px。无渐变、普通内容无阴影。详情及表格正文以常规字重为主。
• 保留列表、研究范围、操作区这几个主要内容组，不增加 KPI 墙、Hero、推荐区或解释性侧栏。
• 原型每页 5 条用于展示，不作为产品分页上限；正式分页复用现有 25/50/100 条偏好。完整字段输入不得受分页上限影响。
• 宽度不足时工具栏换行或折叠筛选；字段抽屉在紧凑视口铺满可用工作区。表格可局部横向滚动，不能导致整页横向溢出。列表表体滚动、操作区可达，分页保持在列表可用区域内。
• 图标按指定 skill 的目录语义选择；正式资源可用时使用同组一致的图标。原型因图标资源不可用采用文字按钮，这是允许的降级，不要求复制字符图标或引入额外图标库。

领域边界与模块职责

• 沿用“平台快照、本地研究记录、同步任务”的既有分离原则，新增数据目录业务能力，统一由共用业务层提供查询、备注修改、同步控制和输入准备。
• WorldQuant 集成负责真实平台协议、认证、分页、退避和数据归一化；业务层负责研究范围、快照完整性、字段归属和输入约束；页面只处理交互状态并消费业务契约。
• 研究范围包含 instrument type、Region、Universe、Delay。首版页面以 EQUITY 为基础，不新增只有一个选项的品种选择器；契约显式保留该维度。
• 数据集/字段的可用性和指标按研究范围隔离。不能仅以字段 ID 建立跨范围唯一性，也不能从某个字段或模板表达式猜测 Region、Universe、Delay。
• 分类及子分类来自平台实际数据或已同步元数据；原型中的分类名称和示例 ID 不硬编码为完整生产枚举。未知分类仍可展示，缺失分类有明确空值处理。
• 平台字段类型按原值保留，已知 MATRIX/VECTOR 可筛选；未知类型不强制映射为已有类型。覆盖率的原始单位在集成层核对，显示与筛选使用同一归一化口径。
• 本地数据集备注与字段备注独立于平台原始响应保存，并按对象和研究范围建立身份关联。沿用本地研究记录版本检查，冲突时提示而不覆盖较新的内容；后台刷新不能覆盖未保存草稿。

同步和持久化

• 数据集目录按研究范围同步，字段按选定数据集与研究范围同步。读取页面不隐式触发全平台下载，不预先下载所有数据集的字段。
• 首次无目录数据时提供明确同步入口；已有缓存时可查看缓存及最后同步时间。未取得字段全集时，“用于 Alpha 模板”先转为同步动作，不允许用部分数据完成输入准备。
• 扩展现有持久化任务执行器与任务面板，继续使用任务 ID、查询进度、取消、失败重试和检查点恢复。保持单管理员、单平台账户、单后端进程约束，不引入第二套队列。
• 现有任务明细以 Alpha ID 为目标，新任务应使用明确的数据集/研究范围目标契约；不能将数据集 ID 伪装为 Alpha ID。保持旧任务 API 与历史记录可读。
• 每页字段与检查点同事务落库；重试幂等去重，并遵守上游 Retry-After。断开连接、人工验证和重启沿用已有任务状态语义。
• 字段集合记录同步批次、完成状态、实际去重数量与来源时间。只有一次成功完成的完整枚举才可用于“全部字段”；上游总数不可靠或分页异常时不得仅凭当前页数量宣称完整。
• 后续刷新在完成前不替换上一版可用字段集合。失败或取消保留上一版及本次进度；首次同步未完成时保持不可绑定。
• 单次未出现的字段不直接删除其历史快照或本地研究记录。一次成功刷新可形成新的字段集合版本，旧输入仍指向旧版本；这不意味着平台提供了严格的时间点一致性快照。
• 新增持久化结构覆盖范围化数据集、字段快照/集合版本、研究备注及模板输入记录。使用增量迁移，不改写已发布迁移，不清空 Alpha、账户、AI 数据或现有研究记录。

选择模型与模板输入交接

• 选择状态由单个数据集、研究范围和显式排除集合决定，浏览筛选独立保存。默认排除集合为空；搜索、类型筛选、覆盖率筛选、排序和翻页不得修改排除集合。
• 表头勾选作用于整个已完成字段集合；部分排除时显示半选。取消全选后为零选择，绑定不可用；“恢复全选”清空排除集合。
• 切换数据集或研究范围不沿用另一对象的排除集合。切换范围后重新读取该范围目录及字段同步状态，清理当前不适用的选中目标。
• 来自原型的核心不变量为：有效字段等于当前完整字段集合减去显式排除；与列表当前匹配结果和当前页无关。正文不要求保留原型内部状态变量或组件结构。
• 输入准备由服务端解析全部字段，不依赖浏览器已加载页数。服务端检查字段归属、范围、集合版本与非空约束，拒绝跨数据集字段、未知字段或不完整集合。
• 输入记录至少包含数据集 ID、研究范围、完整字段集合版本、选择意图（全部/显式子集）、实际字段 ID 集合、创建时间；接入真实模板后关联模板标识及必要版本。
• 即使选择意图为“全部”，保存时也固定实际字段集合及来源版本。后续同步新增或移除字段，不静默改变已保存输入；再次准备输入才消费新的完整版本。
• 页面显示总数与输入记录中的实际字段数一致。准备过程中集合版本变化时返回冲突，要求重新读取范围，不在后台悄悄改变结果。
• 本期交付可持久化的模板输入准备/交接能力，不扩展完整模板编辑器。模板消费方尚未接入时，只显示“保存输入草稿”及真实草稿状态，不展示虚构可用模板，也不提示已绑定真实模板。原型中的两个模板名称是演示数据。
• 消费方必须使用显式研究范围及字段类型，不猜测默认 Region/Delay，不在数据目录中静默加入 winsorize、backfill 或 VECTOR 聚合。具体表达式生成、参数规则与类型处理由后续模板规格定义。

对外契约和错误行为

• 数据集查询接受研究范围、查询词、分类、子分类、排序及分页，返回 items、total、分页参数和同步元数据。分类变化清空旧子分类；无匹配结果正常返回空列表。
• 字段查询还接受所属数据集、类型与最低覆盖率；返回列表匹配数量、完整集合总数和集合版本，明确区分“匹配数”与“本集总数”。
• 数据集详情和字段详情返回身份、范围、来源时间、平台描述、可用指标及独立的本地研究记录；未知指标保留 null，不伪装成零。字段 ID 不直接拼接成未经校验的上游请求。
• 备注更新包含读取时的记录版本；输入准备包含数据集、范围、集合版本与选择意图。写入成功才更新保存状态，异常不显示成功反馈。
• 同步创建异步返回任务 ID；查询和重试沿用已有任务契约。具体 URL 和任务 kind 名称在实现时与现有 API 命名保持一致，并通过 OpenAPI 描述，不在规格中绑定文件组织。
• 所有业务接口复用系统会话、写请求来源校验和账户隔离。沿用既有 401/403/404/409/422 等错误语义，冲突或无效范围不能造成部分写入。
• WorldQuant 只读边界保持，认证除外；数据集同步不回测、不检查、不提交、不修改平台属性。公开错误不得包含凭据、认证正文或 Cookie。

Testing Decisions

用户已确认：以“筛选数据集 → 查看字段与详情 → 整集字段绑定到模板”的完整流程为主，只在 WorldQuant 外部接口边界使用模拟数据，并补充同步失败、断点恢复等接口测试。

1. 优先使用现有浏览器验收环境，将真实页面、API、业务层、数据库和任务执行器串起来。外部平台 HTTP 是主测试替换点，不再逐层 mock 查询服务、选择状态或组件内部函数。
2. 好的测试断言用户可见结果与公开契约，例如字段数、绑定集合、备注保留、错误状态和恢复后的结果；不锁定组件树、内部变量、SQL 调用次数或 CSS 类名。
3. 复用现有工作空间端到端测试先例：登录、连接模拟平台、多页同步、保存研究记录、重同步后记录保留、轮询任务完成和浏览器无运行异常。数据目录新增同层级流程，不独立搭建另一套浏览器服务。
4. 复用现有 API 测试的隔离数据库、ASGI 客户端和上游 HTTP 模拟方式，覆盖查询、范围校验、输入准备及备注版本冲突。复用现有同步测试的检查点、重试、取消和重启恢复用例设计；涉及新协议的测试尽量仍在 HTTP 边界替换。
5. 主路径：同步目录，按分类/子分类筛选，选择数据集，取得多页字段，确认默认全选；搜索到两个字段并打开第二层详情；关闭后保留筛选；准备输入仍包含整集所有字段。模板未接入时，以真实持久化输入草稿与同一交接契约为验收终点，不伪造一个成功的模板消费者。
6. 选择例外：在非第一页排除字段，筛选与排序后排除仍生效；恢复全选还原全集；表头取消全选使主操作禁用；切换数据集及研究范围不串选。
7. 完整性：使用超过单页大小且包含重复 ID 的合成字段。验证多页去重、失败不标记完成、重试不丢进度、刷新失败保留旧版本、缺失总数按实际完整枚举处理；不将已下载页当成全部字段。
8. 固定输入：绑定后刷新字段集合，原输入 ID 集合保持不变；新准备使用新版本；准备时版本冲突返回明确错误。跨数据集、跨范围、空集合、未知字段不能产生输入记录。
9. 备注：数据集和字段备注保存后经重新同步及页面刷新仍存在；并发版本冲突不覆盖新内容；后台更新不清空未保存草稿。
10. 数据质量：缺失分类、说明、覆盖率、单位及未知字段类型有可理解的展示；覆盖率筛选与显示口径一致，null 不作为零参与数值条件。
11. 交互验收：75% / 30% 宽度按同一工作区测量；顶部操作可见、底部无重复功能区、表格单行常规字重；Esc/遮罩逐层关闭、背景隔离和焦点恢复正确。
12. 响应式：覆盖桌面、窄窗口和手机宽度；只允许表格容器局部横向滚动，操作按钮、筛选和关闭入口不被遮挡。验证与现有 AI 助手开合时的状态恢复，不新增数据集 AI 工具。
13. 无匹配、无缓存、同步中、失败、取消、登录失效、等待连接及人工验证均有反馈。已有账户和 Alpha 的主要验收流程继续通过。
14. 生产存储使用 PostgreSQL；涉及集合版本和事务迁移时，应在隔离 PostgreSQL 验证升级与数据保留。SQLite 测试不能替代生产数据库迁移验收。
15. 自动化禁止使用真实凭据、正式数据库、付费模型或真实平台写操作。真实 WorldQuant 数据集 schema、分类选项及权限仍需后续只读联调，模拟测试通过不等于真实平台兼容性已证实。

Out of Scope

• 跨数据集组合、跨目录字段购物篮、默认逐字段收集、命名字段池和自定义数据集编辑器。
• 完整 Alpha 模板管理、模板编辑、表达式生成、AST 校验、参数搜索、批次队列、实验去重与回测执行。
• 数据集/字段的 AI 查询工具、AI 自动选字段、自动解释数据、自动生成研究假设和自动向模型发送字段信息。
• 平台回写、运行检查、提交 Alpha、修改属性或任何真实交易操作。
• 旧数据库迁移、旧 API 兼容、多用户/多平台账户、分布式队列、Redis、额外服务与大规模架构重构。
• 本次文档交付不实施业务代码、不执行数据库迁移、不部署、不提交 Git，不触发真实平台同步。
• 原型样例数据量、虚构模板名称、显示宽度中的固定像素和降级文字按钮不成为生产业务数据或不可调整的技术实现。

Further Notes

• 交互原型是本次已评审样式与交互的留档，使用明确标识的合成数据。原型中的同步、备注和绑定均为浏览器内演示，不能当作已实现的后端能力。
• 用户明确确认的核心约束：数据集优先、单数据集 Alpha、默认整集字段、Table、分类联动、75%/30% 双层抽屉、功能区在顶部、顶部无重复标题、少描述小字及 Lark 风格。
• 本规格中的快照版本、服务端完整性校验、输入草稿交接及既有 AI 面板兼容属于为实现上述流程作出的工程约定；不代表本轮已经实现或验证生产行为。
• 原型历史核验已覆盖分类联动、筛选后仍保持整集输入、字段排除/恢复全选、逐层返回、宽度比例和顶部按钮；Lark 静态检查通过，浏览器未发现运行错误。正式实现仍须执行本规格的验收，不能沿用原型结果宣称功能完成。
• 图标目录已检索，但当时资源服务连接失败，原型按 skill 允许的文字方案降级。实现时可重新接入可用官方目录资源，不要求绕过网络或证书校验。
• 项目依据：总体方案、现有验证记录、本地任务规范。
• 测试确认记录：用户答复“符合，按这个边界”。规格标记 ready-for-agent 表示可供后续实现，不表示用户本轮要求开始开发。