yuxuanhui
61 lines
5.5 KiB
Markdown
61 lines
5.5 KiB
Markdown
# Home 市场数据概览
|
||
|
||
## Goal
|
||
|
||
让量化研究者进入系统后，在一个稳定的管理后台 Home 页面立即了解当前目标股票池和最近一次市场数据同步状态，并能定位失败股票。
|
||
|
||
## Background and confirmed facts
|
||
|
||
- 当前根路由展示的是后端连通性 smoke 页面，前端只有 `system` feature。
|
||
- `market_data` bounded context 已有 `market_stock`、`market_daily_bar`、`market_daily_basic`、`market_sync_batch` 和 `market_sync_item` 表及同步写入逻辑。
|
||
- PostgreSQL 是运行时市场数据事实源；CSV 仅是同步快照和恢复介质。
|
||
- 当前目标股票池由 active 的沪深非 ST A 股组成，历史 inactive 主数据不能计入当前目标数。
|
||
- 一只股票只有在目标交易日同时存在日线行情和估值快照时才是有效股票。
|
||
- 同一交易日的重试批次以最近一次已完成结果为展示结果；该交易日仍有 running 批次时优先展示“更新中”。
|
||
- 浏览器通过同源 `/api/v1` 路径访问后端。
|
||
- 侧边栏采用确认过的最小结构：`首页` 可用，`行情数据`、`同步任务`、`选股策略` 可见但禁用。
|
||
- 前端项目已配置 shadcn/ui（`base-nova`、Tailwind CSS 4、Lucide 图标和 `@/shared/ui` 别名）；本任务必须优先复用现有 shadcn primitives，并按需补齐标准 primitive。
|
||
|
||
## Requirements
|
||
|
||
### Backend overview contract
|
||
|
||
- 新增只读 `GET /api/v1/home/overview` 聚合接口。
|
||
- 响应提供当前目标股票池数、最近更新交易日、同步完成时间、更新状态、目标数、成功数、失败数、有效数、覆盖率，以及失败股票详情和批次级错误。
|
||
- 状态稳定表示为 `updating`、`success`、`partial_success`、`failed`、`no_data`；无任何批次时必须能与 HTTP/服务错误区分。
|
||
- 目标交易日按最近开市日语义展示；接口不得用旧成功批次冒充更新了更晚交易日。
|
||
- 日期和完成时间在展示边界按 `Asia/Shanghai` 表达；交易日与完成时间必须是独立字段。
|
||
- 目标数只计算 active 当前目标股票池；成功数只计算目标日同时存在 daily bar 和 daily basic 的股票；覆盖率为成功数 / 目标数。
|
||
- 失败股票包含代码、名称、失败类型、可读原因和目标交易日。缺失 daily bar、缺失 valuation snapshot、已记录的股票级失败应能区分；批次级错误不得伪造成股票失败。
|
||
- PostgreSQL 读取失败沿用现有 HTTP 错误边界，不返回伪造的空成功数据。
|
||
|
||
### Frontend Home
|
||
|
||
- 根路由替换为 Home 页面，同时保留现有 provider、router、query client 和主题行为。
|
||
- Home 使用 feature 垂直切片，包含 overview API adapter、响应类型、query hook、页面和失败详情对话框。
|
||
- 页面包含管理后台 shell：侧边栏、顶部搜索视觉占位、头像视觉区域和主内容区；未实现的导航入口可见但禁用。
|
||
- 管理后台 shell、概览卡片、状态反馈和失败详情优先由 `shared/ui` 中的 shadcn primitives 组合实现；按需补齐并使用 `Avatar`、`Dialog`、`Input`、`Progress`、`ScrollArea`、`Separator`、`Skeleton` 等标准组件，不在 feature 中复制同类基础交互。
|
||
- 主内容使用一个“市场数据概览”组合卡片，展示最近更新交易日、同步完成时间、状态、目标/成功/失败数量、覆盖率和当前目标股票池数量。
|
||
- 分别渲染加载占位、暂无数据、请求异常及重试、更新中、已更新、部分更新和未更新状态；请求异常提供 retry 操作。
|
||
- 点击失败汇总打开可滚动、可关闭、支持键盘交互的失败详情对话框；对话框展示代码、名称、失败类型、原因和目标交易日。
|
||
- 桌面和平板保持可读；窄屏将内容纵向堆叠，不影响失败详情访问。
|
||
- 搜索和头像只做视觉展示，不实现搜索、认证、账户菜单或权限行为。
|
||
|
||
## Acceptance Criteria
|
||
|
||
- [ ] `GET /api/v1/home/overview` 的 HTTP 契约可测试覆盖：active 股票计数、完整成功、部分成功、失败批次、running 批次、无批次、同日 retry 选择、覆盖率、股票级失败详情和批次级错误。
|
||
- [ ] 接口对完整成功、部分成功、失败、更新中和无数据返回正确稳定状态；批次级错误不会出现在股票失败列表中。
|
||
- [ ] Home 根路由可见管理后台 shell 和“市场数据概览”卡片；既有 system HTTP/frontend 测试继续通过。
|
||
- [ ] 侧边栏显示 `首页`、`行情数据`、`同步任务`、`选股策略`，只有首页可操作，其余入口明确禁用；搜索和头像保持视觉占位。
|
||
- [ ] Home 的卡片、状态反馈和失败弹窗使用项目 `@/shared/ui` 的 shadcn primitives，新增 primitive 保持 `components.json` 的 `base-nova` / Tailwind 约定。
|
||
- [ ] Home 前端测试覆盖正常、加载、无数据、请求错误与重试、全部更新状态、数量/覆盖率、打开失败对话框、详情字段和关闭行为，并包含对话框可访问名称断言。
|
||
- [ ] 后端 Ruff、Pyright、pytest 以及前端格式检查、lint、typecheck、Vitest、build 通过；根级检查按环境可用性执行并如实记录。
|
||
|
||
## Out of scope
|
||
|
||
- 从 Home 触发同步、重试失败股票、修复数据或执行选股。
|
||
- 股票搜索、股票详情、同步历史、策略/选股页面、实时或分钟行情。
|
||
- 认证、用户资料、账户菜单和权限管理。
|
||
- 修改六年保留策略、Tushare 同步流程、市场数据写入语义或 PostgreSQL 事实源。
|
||
- 独立交易日历产品和超出可用堆叠布局的移动端视觉打磨。
|