From 50b6318d253a91b32ca757a43a3222b6cc2cef5f Mon Sep 17 00:00:00 2001 From: Citrons <909229731@qq.com> Date: Tue, 25 Aug 2026 00:24:11 +0800 Subject: [PATCH] =?UTF-8?q?docs(FEAT-MO-004):=20=E5=AE=8C=E6=88=90?= =?UTF-8?q?=E8=AF=A6=E6=83=85=E9=A1=B5=E6=B2=BB=E7=90=86=E8=BF=BD=E6=BA=AF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 2 +- .../FEAT-MO-004-index-sector-detail/design.md | 7 +++- .../development-summary.md | 34 ++++++++++++++++ .../gitnexus/after.md | 40 +++++++++++++++++++ .../gitnexus/comparison.md | 11 +++++ .../gitnexus/detected-changes.md | 18 +++++++++ .../manifest.yaml | 3 +- .../qa/test-results.md | 14 +++++++ .../qa/visual-qa.md | 14 +++++++ .../release-notes.md | 16 ++++++++ .../review/code-review.md | 20 ++++++++++ .../review/standards-review.md | 16 ++++++++ .../test-plan.md | 25 ++++++++++++ .../detail/market-detail.mapper.ts | 4 +- .../detail/market-detail.service.ts | 1 - 15 files changed, 219 insertions(+), 6 deletions(-) create mode 100644 docs/features/FEAT-MO-004-index-sector-detail/development-summary.md create mode 100644 docs/features/FEAT-MO-004-index-sector-detail/gitnexus/after.md create mode 100644 docs/features/FEAT-MO-004-index-sector-detail/gitnexus/comparison.md create mode 100644 docs/features/FEAT-MO-004-index-sector-detail/gitnexus/detected-changes.md create mode 100644 docs/features/FEAT-MO-004-index-sector-detail/qa/test-results.md create mode 100644 docs/features/FEAT-MO-004-index-sector-detail/qa/visual-qa.md create mode 100644 docs/features/FEAT-MO-004-index-sector-detail/release-notes.md create mode 100644 docs/features/FEAT-MO-004-index-sector-detail/review/code-review.md create mode 100644 docs/features/FEAT-MO-004-index-sector-detail/review/standards-review.md create mode 100644 docs/features/FEAT-MO-004-index-sector-detail/test-plan.md diff --git a/AGENTS.md b/AGENTS.md index 3b7db3e..4cb273b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,7 +29,7 @@ # GitNexus — Code Intelligence -This project is indexed by GitNexus as **a-share-analysis** (3730 symbols, 5410 relationships, 115 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely. +This project is indexed by GitNexus as **a-share-analysis** (3786 symbols, 5466 relationships, 115 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely. > If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first. diff --git a/docs/features/FEAT-MO-004-index-sector-detail/design.md b/docs/features/FEAT-MO-004-index-sector-detail/design.md index 87ce93c..66ea3b5 100644 --- a/docs/features/FEAT-MO-004-index-sector-detail/design.md +++ b/docs/features/FEAT-MO-004-index-sector-detail/design.md @@ -6,5 +6,10 @@ 详情数据失败采用模块级降级，页面仍保留标题、来源、更新时间和 warning。分时能力不通过探测时不返回假数据，UI 只展示明确的不可用边界。 -安全策略：Controller/Service 双层参数校验、代码白名单、固定周期、数量上限、响应字段白名单和错误脱敏。性能策略：单次最多 120 点、固定图表尺寸、页面卸载释放图表状态，不新增数据库和缓存热点。 +## 安全策略与评估 +Controller/Service 双层参数校验、代码白名单、固定周期、数量上限、响应字段白名单和错误脱敏。详情不接受任意 TDX 方法名或地址，分时未验证时不伪造数据。测试覆盖非法代码、越界数量、TDX 超时和原始字段不泄漏；残余风险是 TDX 本身依赖本机隧道，公网部署前必须另立采集架构评估。 + +## 性能目标与评估 + +单次最多 120 点、固定图表尺寸、页面卸载释放图表状态，不新增数据库和缓存热点。本地真实 TDX 详情请求观测约 47-56ms，浏览器首屏在开发机可交互；P95 小于 2 秒是本地开发目标，不代表生产容量证明。 diff --git a/docs/features/FEAT-MO-004-index-sector-detail/development-summary.md b/docs/features/FEAT-MO-004-index-sector-detail/development-summary.md new file mode 100644 index 0000000..d906e36 --- /dev/null +++ b/docs/features/FEAT-MO-004-index-sector-detail/development-summary.md @@ -0,0 +1,34 @@ +# FEAT-MO-004 指数与板块详情分析页开发总结 + +- 功能编号：FEAT-MO-004 +- 状态：in_review +- 发布状态：unreleased + +## 原始开发需求 + +市场综合概览中的指数、板块点击后进入详细分析页，使用 TDX 真实数据展示行情和 K 线，支持后续复盘查看。 + +## 需求与范围变化 + +已确认首版同时覆盖指数和一级行业板块，但拆成共享外壳下的两个数据切片。TDX 能力探测发现三个分时候选方法均返回协议错误，因此首版只发布日 K 线，分时明确标记不可用。未扩大到成分股、资金流、新闻、AI、用户体系或交易操作。 + +## 实际完成需求 + +新增指数和板块详情 API、DTO、TDX 日 K 线映射、代码/参数白名单、统一数据状态和错误脱敏；新增 Vue 详情路由、Axios API、事实摘要、轻量 SVG K 线和响应式布局；概览指数与板块入口已接通真实导航；OpenAPI 和前端生成契约已同步。 + +## 修复缺陷 + +实现期间修复了板块目录记录字段与内部定义字段名不一致导致详情不可用的问题；修复了前端详情页在接口异步完成前测试读取旧加载状态的问题；修复了 Web 严格类型下可空涨跌幅的显示类型错误；补充了详情模块注册到 OpenAPI 导出入口，避免契约遗漏。 + +## 未完成与延期项 + +分时数据延期，等待 TDX 提供可验证协议；成分股排名、资金净流入、盘中新闻、AI 结论、数据库/Redis/RocketMQ 持久化和公网采集代理另立功能。当前详情页仍依赖开发机 TDX 隧道，不作为公网生产采集方案。 + +## 关键提交 + +`0131f86 feat(FEAT-MO-004): 实现指数板块详情分析页`，已推送项目 Gitea 分支 `codex/feat-mo-004-index-sector-detail`。 + +## 验证证据 + +TDX 脱敏能力报告记录日 K 线和一级行业目录通过、分时候选失败；GitNexus 开发前风险为 MEDIUM，开发后检测到预期 API 模块注册、OpenAPI、路由和概览导航影响；自动化、构建、视觉和移动端证据见 `test-plan.md`、`qa/test-results.md`、`qa/visual-qa.md`。 + diff --git a/docs/features/FEAT-MO-004-index-sector-detail/gitnexus/after.md b/docs/features/FEAT-MO-004-index-sector-detail/gitnexus/after.md new file mode 100644 index 0000000..8804946 --- /dev/null +++ b/docs/features/FEAT-MO-004-index-sector-detail/gitnexus/after.md @@ -0,0 +1,40 @@ +# GitNexus 开发后基线 + +## GitNexus 状态 + +```text +Repository: /Users/citrons/Documents/Codex/2026-08-12/wo-x/a-share-analysis +Indexed: 8/25/2026, 12:22:30 AM +Indexed commit: 0131f86 +Current commit: 0131f86 +Status: ✅ up-to-date +``` + +## Git 已跟踪变更摘要 + +```text +AGENTS.md | 2 +- + docs/features/FEAT-MO-004-index-sector-detail/design.md | 7 ++++++- + docs/features/FEAT-MO-004-index-sector-detail/manifest.yaml | 3 +-- + server/apps/api/src/market-overview/detail/market-detail.mapper.ts | 4 +++- + .../apps/api/src/market-overview/detail/market-detail.service.ts | 1 - + 5 files changed, 11 insertions(+), 6 deletions(-) +``` + +## Git 工作区摘要 + +```text +M AGENTS.md + M docs/features/FEAT-MO-004-index-sector-detail/design.md + M docs/features/FEAT-MO-004-index-sector-detail/manifest.yaml + M server/apps/api/src/market-overview/detail/market-detail.mapper.ts + M server/apps/api/src/market-overview/detail/market-detail.service.ts +?? "SRMS3.6.0\345\270\270\350\247\201\351\227\256\351\242\230\346\265\213\350\257\204\351\242\230.2csv" +?? docs/features/FEAT-MO-004-index-sector-detail/development-summary.md +?? docs/features/FEAT-MO-004-index-sector-detail/gitnexus/comparison.md +?? docs/features/FEAT-MO-004-index-sector-detail/gitnexus/detected-changes.md +?? docs/features/FEAT-MO-004-index-sector-detail/qa/ +?? docs/features/FEAT-MO-004-index-sector-detail/release-notes.md +?? docs/features/FEAT-MO-004-index-sector-detail/review/ +?? docs/features/FEAT-MO-004-index-sector-detail/test-plan.md +``` diff --git a/docs/features/FEAT-MO-004-index-sector-detail/gitnexus/comparison.md b/docs/features/FEAT-MO-004-index-sector-detail/gitnexus/comparison.md new file mode 100644 index 0000000..acd701f --- /dev/null +++ b/docs/features/FEAT-MO-004-index-sector-detail/gitnexus/comparison.md @@ -0,0 +1,11 @@ +# GitNexus 前后对比 + +| 指标 | 开发前 | 开发后 | +| --- | ---: | ---: | +| 索引提交 | `f8f4da9` | `0131f86`及收尾文档提交 | +| 节点 | 3506 | 3786 | +| 关系 | 4983 | 5466 | +| 执行流 | 104 | 115 | +| 变更风险 | 开发前 `MarketOverviewService` MEDIUM，其余 LOW | `detect_changes` MEDIUM，影响为预期模块注册/路由/契约 | + +执行流数量变化来自详情 Controller/Service、Mapper、页面和测试被 GitNexus 纳入索引；收尾后的 3 个 mapper 流程是 lint 修复后的预期细化，没有发现跨基础设施的意外扩散。完整状态保存在 `before.md` 与 `after.md`。 diff --git a/docs/features/FEAT-MO-004-index-sector-detail/gitnexus/detected-changes.md b/docs/features/FEAT-MO-004-index-sector-detail/gitnexus/detected-changes.md new file mode 100644 index 0000000..b429436 --- /dev/null +++ b/docs/features/FEAT-MO-004-index-sector-detail/gitnexus/detected-changes.md @@ -0,0 +1,18 @@ +# GitNexus 开发后变更检测 + +- 执行：`gitnexus_detect_changes(scope=all)`（实现提交前与文档收尾后各执行一次） +- 实现提交前结果：`risk_level=medium`，实现变更落在 API 模块注册、OpenAPI 导出、路由和概览导航，受影响执行流 2 个。 +- 收尾后结果：`risk_level=medium`，5 个收尾变更文件、3 个 `mapDetailQuote` 相关执行流，均为预期的注释/文档和 lint 修复。 + +## 预期变更 + +- API：`MarketOverviewModule.register` 注册详情 Controller/Service；OpenAPI 导出接入详情 Controller/Service。 +- Web：新增详情路由；概览页指数/板块入口改为真实导航。 +- 文档：功能档案和 GitNexus 统计更新。 + +## 受影响执行流 + +- `RunApi → CreateTdxClient`：模块注册步骤变化，已有 API 启动和详情 E2E 已覆盖。 +- `RunApi → CreateAktoolsClient`：模块注册步骤变化，已有短线和进程烟测已覆盖。 + +未发现数据库、Redis、RocketMQ、Scheduler、Worker 或部署文件的非预期变更；两次检测均未出现 HIGH/CRITICAL。 diff --git a/docs/features/FEAT-MO-004-index-sector-detail/manifest.yaml b/docs/features/FEAT-MO-004-index-sector-detail/manifest.yaml index a114454..7bbf1d6 100644 --- a/docs/features/FEAT-MO-004-index-sector-detail/manifest.yaml +++ b/docs/features/FEAT-MO-004-index-sector-detail/manifest.yaml @@ -1,9 +1,8 @@ featureId: FEAT-MO-004 slug: index-sector-detail name: 指数与板块详情分析页 -status: in_progress +status: in_review release: unreleased source: tdx scope: internal_lan_only createdAt: 2026-08-24 - diff --git a/docs/features/FEAT-MO-004-index-sector-detail/qa/test-results.md b/docs/features/FEAT-MO-004-index-sector-detail/qa/test-results.md new file mode 100644 index 0000000..4b6f5c4 --- /dev/null +++ b/docs/features/FEAT-MO-004-index-sector-detail/qa/test-results.md @@ -0,0 +1,14 @@ +# FEAT-MO-004 QA 测试结果 + +## 1. 自动化门禁 + +`pnpm verify` 已通过运行时、契约、边界、部署、Schema、Web 34 测试、Server 94 测试、typecheck、构建和格式检查。Lint 仅保留仓库既有 Vue 规则 warning，无 error。 + +## 2. API 与真实 TDX + +真实开发 API 已加载新详情路由；指数详情返回 TDX 真实收盘价、交易日期和 120 个 K 线点，板块详情先读一级行业目录再读取 K 线。历史交易日被标记为 `delayed`，不被当作当日实时。 + +## 3. 残余风险 + +TDX 分时协议仍不可用；当前测试未证明公网网络、生产容量或长时间隧道稳定性。详情功能保持内网开发范围。 + diff --git a/docs/features/FEAT-MO-004-index-sector-detail/qa/visual-qa.md b/docs/features/FEAT-MO-004-index-sector-detail/qa/visual-qa.md new file mode 100644 index 0000000..2fa9149 --- /dev/null +++ b/docs/features/FEAT-MO-004-index-sector-detail/qa/visual-qa.md @@ -0,0 +1,14 @@ +# FEAT-MO-004 视觉 QA + +## 1. 桌面视口 + +在 1440x900 浏览器中，详情页标题、来源、更新时间、交易日、状态、核心行情、K 线、分时边界和事实摘要均可见；SVG 图表有真实非空路径，详情内容宽度 1400px，文档宽度等于视口 1440px。 + +## 2. 移动视口 + +在 390x844 浏览器中，详情页折叠为单列核心行情，图表容器保持稳定，`innerWidth=390`、`scrollWidth=390`、`body.scrollWidth=390`，无横向溢出；标题和状态文字未互相遮挡。 + +## 3. 交互验收 + +概览页指数按钮导航到 `/market-overview/indices/000001.SH`，板块按钮导航到 `/market-overview/sectors/881001.SH`；返回概览按钮可用；TDX 不可用和分时不可用状态均展示明确文案，不显示伪造图表。 + diff --git a/docs/features/FEAT-MO-004-index-sector-detail/release-notes.md b/docs/features/FEAT-MO-004-index-sector-detail/release-notes.md new file mode 100644 index 0000000..45241bb --- /dev/null +++ b/docs/features/FEAT-MO-004-index-sector-detail/release-notes.md @@ -0,0 +1,16 @@ +# FEAT-MO-004 发布说明 + +## 当前状态 + +未发布，功能分支已完成实现和 Review，等待合并决策。 + +## 用户可见变化 + +- 综合概览的核心指数和一级行业按钮可进入详情页。 +- 详情页展示 TDX 来源、上海时间、交易日期、状态、最新收盘价、涨跌幅和 K 线。 +- TDX 分时能力未验证时显示明确不可用边界。 + +## 部署边界 + +仅适用于当前内网开发隧道；不改变数据库结构，不启用 Redis/RocketMQ，不暴露 TDX 到公网。 + diff --git a/docs/features/FEAT-MO-004-index-sector-detail/review/code-review.md b/docs/features/FEAT-MO-004-index-sector-detail/review/code-review.md new file mode 100644 index 0000000..e03d9d4 --- /dev/null +++ b/docs/features/FEAT-MO-004-index-sector-detail/review/code-review.md @@ -0,0 +1,20 @@ +# FEAT-MO-004 代码 Review + +## 安全与残余风险 + +通过。Controller 和 Service 双层限制代码、周期和数量；TDX 方法名、地址、原始错误和业务字段不直接暴露给 Web；响应体点数固定不超过 120。残余风险为 TDX 隧道依赖和分时能力缺失，已在 API 状态和文档中显式呈现。 + +## 性能与资源影响 + +通过。详情按单代码读取，不引入数据库、Redis、RocketMQ 或异步任务；K 线数量和 SVG viewBox 固定，页面无定时刷新和大对象缓存。真实开发探测耗时约 47-56ms；生产容量仍未证明。 + +## GitNexus 与同步修改 + +通过。开发前 `MarketOverviewService` 影响为 MEDIUM，其余入口 LOW；开发后 `detect_changes` 仅报告 API 模块注册、OpenAPI 导出、前端路由和概览导航的预期变更，RunApi 两条启动流程已回归测试。HTTP/OpenAPI、Web API、测试和文档同步；消息、数据库、Redis、Scheduler、Worker、部署无需同步。 + +## 发现与处置 + +未发现阻断问题。已修复板块目录字段映射、前端异步状态测试和可空涨跌幅类型问题。 + +最终结论：passed + diff --git a/docs/features/FEAT-MO-004-index-sector-detail/review/standards-review.md b/docs/features/FEAT-MO-004-index-sector-detail/review/standards-review.md new file mode 100644 index 0000000..a8e2854 --- /dev/null +++ b/docs/features/FEAT-MO-004-index-sector-detail/review/standards-review.md @@ -0,0 +1,16 @@ +# FEAT-MO-004 开发规范符合性 Review + +## 安全、性能与架构检查 + +通过。后端按市场概览业务模块内的 detail 职责组织 DTO、Mapper、Service、Controller；前端 API 独立文件并统一经过 Axios request；关键边界有中文注释；未过度抽取工具类；未新增不必要依赖；没有密钥、密码、生产数据或 Docker 变更。 + +## GitNexus 与开发总结检查 + +通过。功能开发前执行 Schema baseline/verify、governance:start、GitNexus impact 和 TDX 脱敏探测；开发后刷新 GitNexus、执行 detect_changes、保存前后报告；开发总结明确原始需求、范围变化、实际完成、修复缺陷、延期项、关键提交和验证证据。 + +## 版本控制与发布检查 + +通过。提交使用中文 Conventional Commit `feat(FEAT-MO-004): 实现指数板块详情分析页`，已推送项目级 Gitea 功能分支；未修改全局 Git 配置；回退无需数据库数据回滚。 + +最终结论：passed + diff --git a/docs/features/FEAT-MO-004-index-sector-detail/test-plan.md b/docs/features/FEAT-MO-004-index-sector-detail/test-plan.md new file mode 100644 index 0000000..f1659ad --- /dev/null +++ b/docs/features/FEAT-MO-004-index-sector-detail/test-plan.md @@ -0,0 +1,25 @@ +# FEAT-MO-004 测试计划与结果 + +## 测试范围 + +- Mapper：日期排序、非法行过滤、数量上限、缺失成交字段和涨跌幅计算。 +- Service：指数/板块成功、目录校验、延迟、部分数据、不可用和超时脱敏。 +- HTTP：两个详情路由、代码格式、周期和数量参数、OpenAPI 响应结构。 +- Web：Axios API 路径、路由加载、上海时间、空/错误/延迟状态、K 线 SVG 和移动端布局。 + +## 安全验证 + +已验证非法代码不会触发 TDX；`count` 只接受 1-120；页面和 HTTP 响应不包含 `ErrorId`、TDX 地址或原始异常；分时协议未通过时 `intraday=false`。未执行交易、账户、自选或写入接口。 + +## 性能验证 + +详情服务固定最多 120 个 K 线点，真实开发 TDX 日 K 线请求观测约 47-56ms；SVG 图表固定 `viewBox=0 0 720 260`，390px 视口 `documentElement.scrollWidth=390`，无横向溢出。该证据仅代表本机开发环境，不代表生产容量。 + +## 自动化结果 + +- Web：12 个测试文件、34 个测试通过。 +- Server：18 个测试文件、94 个测试通过。 +- 根级治理、契约、边界、部署和 Schema 测试全部通过。 +- Playwright：桌面/移动应用冒烟和 API 健康契约共 4 个测试通过。 +- Web/Server typecheck、生产构建和 Prettier 检查通过；lint 无 error，保留既有 Vue 格式 warning。 + diff --git a/server/apps/api/src/market-overview/detail/market-detail.mapper.ts b/server/apps/api/src/market-overview/detail/market-detail.mapper.ts index 122ed2e..29562ab 100644 --- a/server/apps/api/src/market-overview/detail/market-detail.mapper.ts +++ b/server/apps/api/src/market-overview/detail/market-detail.mapper.ts @@ -92,8 +92,10 @@ function mapDirection(changePercent: number | null): QuoteDirection { /** 报价使用最后两个有效交易日；上一收盘为零时不计算涨跌幅，避免无意义的无穷值。 */ export function mapDetailQuote( series: TdxKlineSeries, - _definition: DetailInstrumentDefinition, + definition: DetailInstrumentDefinition, ): DetailQuoteDto | null { + // 保留 definition 参数作为指数/板块共享映射边界；两类报价当前采用相同的收盘口径。 + void definition; const points = mapDetailSeries(series, MAX_DETAIL_POINTS); const latest = points.at(-1); if (!latest) return null; diff --git a/server/apps/api/src/market-overview/detail/market-detail.service.ts b/server/apps/api/src/market-overview/detail/market-detail.service.ts index 75647b5..8adb6df 100644 --- a/server/apps/api/src/market-overview/detail/market-detail.service.ts +++ b/server/apps/api/src/market-overview/detail/market-detail.service.ts @@ -4,7 +4,6 @@ import type { TdxClient } from '../tdx/tdx.client'; import { TdxClientError } from '../tdx/tdx.client'; import { CORE_INDEXES, - type IndexDefinition, type TdxKlineSeries, type TdxMarketDataResult, type TdxStockListResult,