FoXiMao/a-share-analysis
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
21393ef451b1df36b3f26c4dc20cef4de8cfa024
a-share-analysis/docs/superpowers/plans/2026-08-24-index-sector-detail.md
T

12 KiB
Raw Blame History

指数与板块详情分析页实施计划

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 在市场综合概览中实现可点击的指数详情页，并在同一外壳上接入一级行业板块详情；只展示经过 TDX 校验的事实数据和规则计算结果。

Architecture: 后端新增详情业务模块，复用现有 TDX Client 和概览元数据，但不把详情数据拼入首页接口。详情 Controller 负责参数白名单与查询上限，Service 按指数/板块分别读取和映射日 K 线，Web 通过独立 Axios API 和共享详情页面外壳展示状态、K 线与可用视图；分时能力只有在探测报告通过后才启用。

Tech Stack: NestJS 11、TypeScript 5.9、Vue 3、Vue Router 4、Axios、Naive UI、原生 SVG/Canvas（除非依赖评估证明需要新增图表库）、TDX JSON-RPC。

Spec: docs/superpowers/specs/2026-08-24-index-sector-detail-design.md

Global Constraints

  • Node 使用 22.x，MySQL 仅保留 5.7.x 兼容约束，排序规则为 utf8mb4_general_ci。
  • 详情接口只读 TDX，不启用 MySQL、Redis、RocketMQ、AI 或用户体系。
  • TDX 原始地址、请求体、凭据和原始异常不得进入 Web 响应；错误必须分类并脱敏。
  • API 响应 asOf 保持 UTC ISO，Web 统一按 Asia/Shanghai 展示。
  • 每个详情请求最多返回 120 个 K 线点；period 仅接受已验证的 1d。
  • 不提交密钥、密码、.env、生产数据或 .gitnexus/；继续使用项目级 Gitea。
  • 修改代码前完成 GitNexus upstream impact；提交前运行 gitnexus_detect_changes。
  • 中文 Conventional Commit，提交验证通过后立即推送远程。

文件边界

新增

  • server/apps/api/src/market-overview/detail/market-detail.dto.ts：详情响应、报价、K 线点和可用视图 OpenAPI DTO。
  • server/apps/api/src/market-overview/detail/market-detail.mapper.ts：指数/板块 K 线的安全字段映射、日期排序、数量裁剪和状态辅助。
  • server/apps/api/src/market-overview/detail/market-detail.service.ts：详情查询、业务代码白名单、TDX 错误降级和指数/板块口径分流。
  • server/apps/api/src/market-overview/detail/market-detail.controller.ts：两个详情路由、查询参数校验和 Swagger 声明。
  • server/apps/api/src/market-overview/detail/market-detail.service.test.ts、market-detail.mapper.test.ts：服务与映射单元测试。
  • server/apps/api/test/market-detail.e2e-spec.ts：HTTP 参数、响应状态和脱敏测试。
  • web/src/api/market-overview/detail.ts：详情 API Axios 封装。
  • web/src/views/market-overview/detail/MarketDetailPage.vue：共享详情页外壳和加载/错误/延迟状态。
  • web/src/views/market-overview/detail/MarketDetailChart.vue：固定尺寸的轻量 SVG K 线图和不可用边界。
  • web/src/views/market-overview/detail/market-detail.ts：前端详情响应类型适配与展示辅助。
  • web/src/views/market-overview/detail/MarketDetailPage.test.ts、MarketDetailChart.test.ts：路由状态、时区和图表输入测试。
  • docs/features/FEAT-MO-004-index-sector-detail/：PRD、需求、设计、计划、测试、回退、开发总结、GitNexus、Review 和 QA 证据。

修改

  • server/apps/api/src/market-overview/market-overview.module.ts：注册详情 Controller/Service。
  • server/apps/api/src/market-overview/tdx/tdx.types.ts：仅在探测确认后补充分时响应类型；日 K 线已有类型保持兼容。
  • web/src/app/router.ts：新增 /market-overview/indices/:code 与 /market-overview/sectors/:code 路由。
  • web/src/views/market-overview/MarketOverviewPage.vue：把指数/板块选择事件改为真实路由导航。
  • server/openapi/openapi.json、web/src/api/generated/schema.ts：通过既有生成脚本更新契约，不手写漂移。

实施任务

Task 1：建立功能档案、基线与影响分析

Files:

  • Create: docs/features/FEAT-MO-004-index-sector-detail/manifest.yaml

  • Create: docs/features/FEAT-MO-004-index-sector-detail/prd.md

  • Create: docs/features/FEAT-MO-004-index-sector-detail/requirements.md

  • Create: docs/features/FEAT-MO-004-index-sector-detail/design.md

  • Create: docs/features/FEAT-MO-004-index-sector-detail/rollback.md

  • Create: docs/features/FEAT-MO-004-index-sector-detail/gitnexus/impact-plan.md

  • 运行 npm run schema:baseline、npm run schema:verify；如果开发库为空，记录 captured_empty，不得伪造 SQL。

  • 运行 npm run governance:start -- FEAT-MO-004 index-sector-detail，确认基线已提交、已推送且 GitNexus up-to-date。

  • 对 MarketOverviewController、MarketOverviewService、createTdxClient、createAppRouter 和 MarketOverviewPage 执行 upstream impact，记录直接调用方、执行流、模块影响和风险。

  • 将 HTTP/OpenAPI、Web API、消息、数据库、Redis、Scheduler、Worker、部署、测试和文档的同步判断写入 gitnexus/impact-plan.md。

Task 2：TDX 能力探测和脱敏证据

Files:

  • Create: docs/features/FEAT-MO-004-index-sector-detail/tdx-capability-probe.md

  • Test: server/apps/api/src/market-overview/tdx/tdx.client.test.ts（只补充固定方法/参数边界测试，如确有必要）

  • 使用当前开发环境 TDX 隧道探测 get_market_data 的日 K 线、候选分时方法、时间字段、响应上限和一级行业代码历史 K 线。

  • 记录方法名、参数形状、返回字段、耗时、是否可重复和脱敏失败原因；禁止把地址、请求体凭据或原始异常写入文档。

  • 若分时协议或字段完整性未通过，只登记 intraday=false，不改造协议、不生成假数据。

Task 3：先写详情 Mapper 失败测试并实现安全 K 线映射

Files:

  • Create: server/apps/api/src/market-overview/detail/market-detail.mapper.test.ts
  • Create: server/apps/api/src/market-overview/detail/market-detail.mapper.ts
  • Create: server/apps/api/src/market-overview/detail/market-detail.dto.ts

Interfaces:

  • mapDetailSeries(series: TdxKlineSeries, count: number): DetailSeriesPoint[]

  • mapDetailQuote(series: TdxKlineSeries, definition: DetailInstrumentDefinition): DetailQuoteDto | null

  • trimAndSortSeries(points: DetailSeriesPoint[], count: number): DetailSeriesPoint[]

  • 为空序列、日期非法、字段长度不一致、倒序日期、缺少金额/成交量、超过 120 条和相邻收盘价为零编写失败测试。

  • 实现只读取 Date/Open/High/Low/Close/Amount/Volume，按合法交易日期升序排序，单点字段缺失时返回 null 或降级状态，不抛出原始数据。

  • 实现价格、涨跌幅和方向计算；板块报价只暴露设计中确认的强弱字段。

  • 运行 mapper 定向测试并确认通过。

Task 4：实现详情 Service、Controller 和 OpenAPI DTO

Files:

  • Create: server/apps/api/src/market-overview/detail/market-detail.service.ts
  • Create: server/apps/api/src/market-overview/detail/market-detail.controller.ts
  • Create: server/apps/api/src/market-overview/detail/market-detail.service.test.ts
  • Modify: server/apps/api/src/market-overview/market-overview.module.ts

Interfaces:

  • MarketDetailService.getIndexDetail(code: string, period: DetailPeriod, count: number): Promise<IndexDetailResponseDto>

  • MarketDetailService.getSectorDetail(code: string, period: DetailPeriod, count: number): Promise<SectorDetailResponseDto>

  • GET /api/v1/market-overview/indices/:code/detail?period=1d&count=120

  • GET /api/v1/market-overview/sectors/:code/detail?period=1d&count=120

  • 先写成功、非法代码、非法 period/count、TDX 超时、协议错误、空序列、部分字段缺失和延迟交易日测试。

  • Controller 只接受白名单指数/一级行业代码、period=1d 和 1..120 的整数 count；非法参数由 Nest 标准 400 返回。

  • Service 调用固定 get_market_data，不把方法名或原始 params 从 HTTP 传入；指数和板块使用独立定义表和 warning 文案。

  • 以 fresh/delayed/partial/unavailable 生成元数据；详情失败只影响本次请求，不影响首页接口。

  • 注册模块并生成 OpenAPI；运行 API 单元测试和 E2E 定向测试。

Task 5：接入 Web 路由、Axios API 和共享详情页面

Files:

  • Create: web/src/api/market-overview/detail.ts
  • Create: web/src/views/market-overview/detail/market-detail.ts
  • Create: web/src/views/market-overview/detail/MarketDetailPage.vue
  • Create: web/src/views/market-overview/detail/MarketDetailChart.vue
  • Create: web/src/views/market-overview/detail/MarketDetailPage.test.ts
  • Create: web/src/views/market-overview/detail/MarketDetailChart.test.ts
  • Modify: web/src/app/router.ts
  • Modify: web/src/views/market-overview/MarketOverviewPage.vue
  • Modify: web/src/styles/index.scss

Interfaces:

  • createMarketDetailApi(requestClient): { getIndexDetail(code, params), getSectorDetail(code, params) }

  • MarketDetailPage consumes route type/code, calls only the Axios API wrapper, and renders instrument/quote/series/availableViews.

  • 先写路由参数、加载、空、错误、延迟、上海时区和 390px 视口测试。

  • 实现页面固定结构：返回概览、名称/代码/来源/更新时间、核心行情、K 线、数据质量和事实型复盘摘要。

  • 实现轻量 SVG 图表，固定容器尺寸，点数多于 120 时不额外扩张；intraday=false 只显示边界说明。

  • 修改概览点击事件使用 router.push，不在页面直接调用 Axios 或 TDX。

  • 运行 Web 定向测试、typecheck 和生产构建；确认移动端无横向溢出。

Task 6：契约、全量验证与 Review

Files:

  • Modify: server/openapi/openapi.json

  • Modify: web/src/api/generated/schema.ts

  • Create: docs/features/FEAT-MO-004-index-sector-detail/test-plan.md

  • Create: docs/features/FEAT-MO-004-index-sector-detail/implementation-plan.md

  • Create: docs/features/FEAT-MO-004-index-sector-detail/development-summary.md

  • Create: docs/features/FEAT-MO-004-index-sector-detail/review/code-review.md

  • Create: docs/features/FEAT-MO-004-index-sector-detail/review/standards-review.md

  • Create: docs/features/FEAT-MO-004-index-sector-detail/qa/test-results.md

  • Create: docs/features/FEAT-MO-004-index-sector-detail/qa/visual-qa.md

  • Create: docs/features/FEAT-MO-004-index-sector-detail/gitnexus/after.md

  • Create: docs/features/FEAT-MO-004-index-sector-detail/gitnexus/detected-changes.md

  • Create: docs/features/FEAT-MO-004-index-sector-detail/gitnexus/comparison.md

  • 运行 npm run check:contracts，确认后端 DTO、OpenAPI 和 Web 类型一致。

  • 运行定向测试、npm run verify、开发服务器 Playwright 桌面/390px 截图和非空图表检查。

  • 执行代码 Review、开发规范符合性 Review，记录发现、处置和残余风险。

  • 运行 npm run governance:finish -- FEAT-MO-004 index-sector-detail，刷新 GitNexus 并保存前后对比。

  • 运行 gitnexus_detect_changes，确认只影响详情模块、路由、契约和预期文档。

  • 使用中文 Conventional Commit 提交并立即推送项目 Gitea；推送失败不得标记完成。

计划自检

  • 设计覆盖：指数/板块双切片、TDX 能力门、状态降级、路由、契约、时区、安全、性能、测试、回退均有对应任务。
  • 占位检查：没有以 TBD/TODO 或“适当处理”代替具体行为；分时未验证时明确返回 intraday=false。
  • 类型一致性：Service 参数、DTO 字段、Web API 方法和页面消费字段与设计文档一致。
Reference in New Issue View Git Blame Copy Permalink