tick-stock-panel/CONTRIBUTING.md

# Tick Stock Panel 贡献、AI 开发与复审指南

本文档适用于整个仓库，供贡献者、AI 编码代理和 PR 审查者共同使用。目标是让改动落在正确的模块，保持数据口径、插件化和兼容性一致，并通过可复现的验证减少返工。

`CONTRIBUTING.md` 是项目贡献与审查规范，不替代 `README.md`、`docs/` 中的用户文档和领域文档。所有贡献者和 AI 编码代理在修改代码、提交或审查 PR 前都应阅读本文档。

涉及代码二次开发时，同时遵循 [`docs/secondary-development.md`](docs/secondary-development.md)。前端优先使用真实存在的受控插槽或注册入口，后端优先使用小粒度策略接口和依赖注入；现有扩展点无法表达核心行为变化时允许直接修改源码，但必须保持改动聚焦并补足兼容性验证。

## 1. 基本原则

### 1.1 修改前先理解

- 先定位真实调用链、数据来源、缓存层和现有测试，不根据文件名或界面现象猜测实现。
- 明确用户问题、输入、输出、资产类型、时间周期和兼容边界后再修改。
- 存在多种解释时必须说明假设；会改变业务口径的歧义必须先确认。
- 优先复用现有接口、服务、类型和组件，不平行实现第二套逻辑。

### 1.2 保持简单

- 只实现当前需求，不增加未被要求的配置、兼容层或通用框架。
- 单次使用的简单逻辑不提前抽象；出现真实重复或明确模块边界时再复用。
- 能在现有模块内完成的改动，不新增跨层依赖或新目录。
- 注释解释“为什么”，不复述代码行为。

### 1.3 最小范围修改

- 每一处变更都应能追溯到当前问题。
- 不顺手重构、重命名、格式化或删除无关代码。
- 保留用户和其他贡献者尚未提交的改动，不覆盖、不回滚。
- 只清理由本次修改产生的无用导入、变量、文件和调试输出。

### 1.4 以验证结果作为完成标准

- 修复 bug 时，优先编写能复现问题的测试，再修到测试通过。
- 新功能至少覆盖正常路径、关键边界和失败路径。
- “代码已写完”“页面能打开”或“GitHub 没有红灯”都不代表完成。
- 无法执行必要验证时，必须在 PR 中说明原因和剩余风险。

## 2. 项目架构

### 2.1 技术栈

- 后端：Python 3.11+、FastAPI、Pydantic v2、Polars、DuckDB、PyArrow。
- 回测边界允许使用 pandas；业务数据计算优先使用 Polars。`vectorbt` 是可选依赖，不得让未安装它的主流程失效。
- 前端：React 18、TypeScript、Vite、TanStack Query、Tailwind CSS、ECharts、lightweight-charts。
- 包管理和验证命令：后端使用 `uv`，前端使用 `pnpm`。

### 2.2 主数据流

```text
数据源或数据插件
  -> services 同步、校验与标准化
  -> DataStore / KlineRepository / Parquet
  -> indicators pipeline 生成 enriched 数据
  -> 策略 / 监控 / 回测 / 分析服务
  -> FastAPI API / SSE
  -> frontend API 类型 + TanStack Query
  -> 页面和共享组件
```

改动前应沿这条链路检查上下游。禁止通过页面或 API 层绕过标准化、仓库、业务服务而直接读取某个数据源或本地文件。

### 2.3 模块边界

| 目录 | 职责 | 放置要求 |
| --- | --- | --- |
| `backend/app/api/` | HTTP、SSE、参数校验和响应映射 | 保持薄层，不放重计算、全量扫描或数据源专属业务 |
| `backend/app/services/` | 同步、实时行情、通知等业务编排 | 组合领域能力，不复制仓库或 provider 的实现 |
| `backend/app/tickflow/` | 数据存储、仓库、能力检测和 TickFlow 接入 | 对外通过既有抽象暴露能力，避免上层依赖存储细节 |
| `backend/app/data_providers/` | 数据源接口、标准化模型和自定义数据源 | 新数据能力先定义数据集契约，再由 provider 实现 |
| `backend/app/plugins/` | 插件发现、加载和插件协议 | 插件失败不得破坏未启用插件的主流程 |
| `backend/app/indicators/` | 指标计算和 enriched 流水线 | 保持向量化，明确原始价、复权价和输出单位 |
| `backend/app/strategy/` | 策略注册、执行、监控和 AI 策略 | 内置与自定义策略尽量共享执行契约，不能各自形成不同口径 |
| `backend/app/backtest/` | 回测、优化、步进优化和 worker | 严格隔离信号生成与成交模拟，防止未来函数 |
| `frontend/src/lib/api.ts` | 前端 API 请求和类型契约 | 后端契约变化必须同步更新类型与调用方 |
| `frontend/src/lib/queryKeys.ts` | TanStack Query 查询键 | 查询键集中维护，不在组件内拼出平行键 |
| `frontend/src/lib/useSharedQueries.ts` 等 | 跨页面共享查询 | 相同数据优先共享缓存，避免每张卡片重复请求 |
| `frontend/src/pages/` | 页面级编排 | 复杂领域逻辑下沉到 hook、组件或后端服务 |
| `frontend/src/components/` | 可复用交互组件 | 保持 props 契约稳定，不把页面专属状态塞进公共组件 |
| `data/` | 用户运行时数据 | 不提交到 Git，不把本地样本、账号信息或绝对路径写入 PR |

## 3. 不可混用的数据契约

金融数据错误经常不会报异常，但会生成看似合理的错误结果。涉及下列字段时，必须在变量名、边界转换或测试中证明口径正确。

### 3.1 比例和百分比

| 字段/场景 | 当前口径 | 示例 |
| --- | --- | --- |
| 自定义实时数据源入口的 `change_pct` | 小数制 | `0.0366` 表示 `3.66%` |
| enriched 和股票监控内部的 `change_pct` | 通常为小数制 | 阈值比较前确认调用链，不凭字段名推断 |
| 指数实时展示缓存的涨跌幅 | 存在百分数口径 | 使用前必须显式转换，不得直接复用到股票监控 |
| 实时数据源入口的 `turnover_rate` | 小数制 | `0.05` 表示 `5%` |
| enriched 的 `turnover_rate` | 百分数值 | `5` 表示 `5%` |

新增跨边界映射时必须增加单位测试。禁止用“数值小于 1 就乘 100”一类启发式转换，这会掩盖真实数据错误。

### 3.2 价格与复权

- enriched 的 `open/high/low/close` 为前复权价格。
- `raw_close/raw_high/raw_low` 为不复权原始价格。
- 涨停、跌停、一字板、炸板和交易所价格限制必须基于原始价及对应交易日规则判断。
- 技术指标和收益序列使用哪种价格，必须与现有指标定义一致，不得在同一公式中混用。

### 3.3 日期、交易日和时区

- 窗口、前 N 日和批次回算均按实际交易日，不得用自然日直接替代。
- A 股交易时段统一按北京时间处理；服务器时区不能成为业务逻辑的隐式输入。
- 日线、分钟线和实时快照必须明确交易日期归属，尤其注意午休、收盘后和跨日重启。
- 分钟 K 的股票、ETF、指数分开存储和路由，不得仅凭代码格式猜测资产类型。

### 3.4 历史股本与换手率

- 历史换手率优先使用公告日不晚于目标交易日的历史股本。
- 缺少可用历史股本时，才允许降级到最新维表股本。
- 当日维表、财务公告日和报表期是不同概念，不能用报表期提前泄露尚未公告的数据。
- 修改股本补全或 enriched 重算时，必须覆盖“有历史股本”和“无历史股本降级”两条路径。

## 4. 数据源插件化要求

数据源已经插件化。任何通用功能都必须通过 provider 能力和标准化数据集访问数据，不能把 TickFlow SDK 调用硬编码到策略、监控、回测、API 或前端流程中。

- 使用现有的 `get_provider()`、`provider_has_dataset()` 和 preferences 路由能力。
- 支持的数据集包括但不限于 `daily`、`adj_factor`、`minute`、`realtime`、`financial`；新增数据集应先定义清晰的输入输出契约。
- provider 负责把供应商字段、单位、日期和代码格式转换为内部标准格式。
- 上层服务依赖标准字段和能力声明，不依赖供应商响应结构。
- 只有明确标注为 TickFlow 专属的功能才可以直接依赖 TickFlow，并且不得影响其他 provider。
- provider 缺少某项能力时，应明确提示、跳过该功能或 fail-closed；禁止静默换用错误数据或错误口径。
- 插件加载失败、字段缺失和空数据必须有隔离测试，不能导致应用启动失败或其他数据源不可用。
- 新增数据源适配应同步更新 `docs/custom-data-source.md` 或 `docs/plugin-development.md` 中对应契约。

## 5. 领域专项要求

### 5.1 策略

- 内置策略和自定义策略的基础参数、策略参数、过滤、评分和结果结构应走统一契约。
- 参数修改后要检查：持久化内容、运行时实例、策略结果缓存、监控实例和前端查询是否全部更新。
- 创建策略的表单状态必须在每次打开时初始化；编辑态数据不得泄漏到新建态，关闭或创建成功后不能残留上一个策略 ID。
- 策略 ID 是稳定标识。重命名、复制、导入和删除必须分别处理 ID 冲突，不能靠覆盖文件解决。
- AI 生成策略的 META 必须经过结构化解析和规范化；兼容历史格式时保留旧格式读取能力，但新输出使用当前规范。
- 评分字段必须有确定的数据来源或临时计算路径。缺少输入时应返回明确的不可计算状态，不能把空值伪装成零分。
- 删除策略涉及用户文件，必须校验目标范围并 fail-closed；不得允许路径穿越或删除策略目录之外的文件。

### 5.2 监控与通知

- 监控计算应复用标准化实时行情和统一规则，不为页面、语音、飞书、企业微信分别计算。
- 涨跌幅、涨跌停和均价穿越必须明确数据口径、交易时段、资产类型和阈值方向。
- 分钟信号只有在 provider 声明分钟数据能力且标的进入订阅池后才启用；无权限时给出明确状态。
- 行情回调线程中不得执行全量历史重算、同步 Webhook、慢磁盘扫描等长耗时任务。
- 通知文案使用用户可理解的中文名称，不泄漏内部枚举名、模块名或调试字段。
- 同一事件的去重、冷却和恢复状态必须可测试，重启后的行为要与持久化设计一致。

### 5.3 回测、优化与步进优化

- 信号生成和成交模拟是两个阶段。必须明确区分信号时间、可成交时间和使用的价格。
- 严禁未来函数：交易日只能使用当时已经公开且可获得的数据。
- 股票规则需保持 T+1、手续费、滑点、涨跌停不可成交等约束；新成交选项不得绕过这些规则。
- 日线回测不能声称“信号触发瞬间成交”。分钟精确成交只有在分钟数据完整覆盖目标窗口时才能启用。
- 卖出信号的“当日收盘”“次日开盘”“次分钟开盘”等选项必须分别测试时间对齐和边界数据缺失。
- 优化和步进优化共享矩阵时，矩阵必须覆盖每个 fold 的完整窗口；缓存键必须包含会改变矩阵结果的输入。
- 修改选股、评分或排序逻辑时，同时核对历史策略结果、回测交易记录和 UI 展示是否使用同一候选集和排序方向。

## 6. 缓存、并发与性能

项目同时存在仓库缓存、enriched 历史缓存、实时聚合、筛选缓存、策略结果缓存、回测矩阵缓存、mtime 缓存、SSE 和前端 TanStack Query。修改读写路径时必须列出受影响的缓存层。

### 6.1 缓存一致性

- 写数据后同步检查：持久化文件、内存缓存、generation/version、SSE 事件和前端 query invalidation。
- 不能只保证“文件已写入”，却继续返回旧内存对象。
- 多步刷新优先构建新快照后原子替换，避免 UI 在刷新期间短暂变成空列表或零结果。
- 缓存键必须覆盖资产类型、周期、日期、策略参数和其他会改变结果的维度。
- 失效范围应精确；不能为了修复单条数据而无条件清空所有历史缓存。

### 6.2 并发安全

- API、后台 worker 和实时行情线程共享字典或缓存时，使用锁、不可变快照或原子替换。
- 不在持锁期间执行网络请求、磁盘全量扫描或重计算。
- 取消、超时和应用关闭路径必须释放资源，后台线程不得阻止进程退出。

### 6.3 性能约束

- 列表页避免 N+1 API、每卡片独立请求和重复全量策略计算，优先批量接口及共享查询。
- Polars 计算优先表达式和批处理，避免逐行 Python 循环。
- 实时热路径不得随历史数据量线性增长；需要历史窗口时只读取必要范围。
- 无规则、无订阅者或 provider 无能力时，不执行对应实时计算。
- 声称“提升性能”的 PR 必须给出同一数据规模、同一环境下的修改前后数据，至少包括耗时或请求数。

## 7. 前端改动要求

- 复用 `frontend/src/lib/api.ts` 中的请求封装和类型，禁止组件直接散落请求地址。
- TanStack Query 查询键使用集中定义；资产类型、日期、周期等影响结果的参数必须进入查询键。
- 切换股票、ETF、日期或策略后，不得把上一上下文的缓存结果当作当前结果。
- 实时刷新保留上一份有效数据直到新数据就绪，避免列、计数和列表闪烁消失。
- 弹窗打开和关闭必须正确重置临时表单状态；新建态与编辑态分离。
- 公共标签、个股详情、成分股等跨页面行为使用共享组件，不在多个页面复制交互。
- 新增交互必须覆盖加载、空数据、错误、禁用和无权限状态。
- 改动应在常用桌面和窄屏尺寸下检查文字截断、遮挡、滚动区域和弹窗可操作性。
- 不用前端补丁掩盖后端单位或契约错误；契约问题应在数据边界修正。

## 8. 安全、兼容与用户数据

- 不提交 `data/`、密钥、Token、Webhook、用户策略、日志、数据库、Parquet 样本和机器绝对路径。
- 日志和异常响应不得包含授权信息、完整配置或用户敏感数据。
- 文件删除、覆盖、迁移和批量回算属于高风险操作：限制目标目录、验证路径、提供清晰失败原因，并保持 fail-closed。
- 不用不安全的字符串拼接执行 SQL、Shell 或动态 Python。
- 配置、策略 JSON、Parquet schema 和 API 字段变化默认需要向后兼容。新增字段优先提供默认值，读取历史数据时允许字段缺失。
- 必须改变既有行为时，在 PR 中列出迁移方式、降级行为和影响范围。
- Windows、macOS、Linux 和 Docker 的路径、编码、回收站及权限行为不同；涉及文件系统时至少审查跨平台失败路径。

## 9. 验证矩阵

根据改动范围执行最小但充分的验证。以下是最低要求，不是上限。

| 改动类型 | 最低验证 |
| --- | --- |
| 后端纯函数、规则或 bug 修复 | 对应定向 `pytest`，包含复现用例和边界用例 |
| API 契约 | service 测试 + API 测试；检查成功、无数据和错误响应 |
| 数据源或插件 | provider 契约测试、缺少能力、空数据、字段/单位标准化测试 |
| 指标、复权、换手率、涨跌停 | 固定样本数值断言，覆盖历史边界和降级路径 |
| 策略或监控 | 参数变更、缓存失效、资产切换、重启/并发相关路径 |
| 回测 | 信号日与成交日、T+1、费用、滑点、不可成交、数据缺口 |
| 缓存或性能 | 命中/失效测试、并发快照测试；必要时提供前后基准 |
| 前端组件或页面 | `pnpm build`，并手工检查加载、空、错、切换和实时刷新状态 |
| 前后端契约同时变化 | 后端定向测试 + 前端构建 + 对应页面联调 |
| 文件、Docker 或跨平台逻辑 | 正常路径、权限/能力缺失和目标不可用的失败路径 |

常用命令：

```bash
cd backend
uv run pytest tests/path/to/test_x.py -q
uv run ruff check app/path.py tests/path.py

cd frontend
pnpm build

git diff --check
```

- 后端至少运行受影响模块的测试，不应只运行新加的单个测试。
- 新增文件和本次改动不得引入 Ruff 告警。不要为清理历史告警而在功能 PR 中全仓格式化。
- 前端任何 TypeScript、组件、样式或 API 类型改动至少执行一次 `pnpm build`。
- 提交前必须运行 `git diff --check`，并检查最终 diff 不含调试代码和无关文件。

## 10. PR 提交要求

一个可审查的 PR 应聚焦一个问题。功能、无关重构、批量格式化和依赖升级不得混在一起。

PR 描述必须包含：

1. **问题与复现**：原行为、复现条件和影响用户。
2. **根因**：具体到调用链、数据契约或状态生命周期，不能只写“修复 bug”。
3. **解决方案**：改动模块、关键取舍，以及为什么没有破坏插件化或现有口径。
4. **兼容性**：对历史配置、策略、缓存、Parquet、API、数据源和不同资产类型的影响。
5. **性能**：是否进入实时或列表热路径；有性能主张时附前后数据。
6. **验证结果**：列出实际执行的命令和结果，不写计划执行的测试。
7. **界面证据**：有可见变化时提供修改前后截图或短视频，并覆盖浅色/深色或窄屏中相关场景。
8. **风险与回滚**：剩余风险、降级行为和可行的回滚方式。

提交前作者自检：

- [ ] 改动只解决 PR 描述的问题，没有夹带无关整理。
- [ ] 已检查完整调用链和所有受影响缓存。
- [ ] 已核对单位、复权、交易日、时区和资产类型。
- [ ] 未绕过 provider abstraction，缺少能力时行为明确。
- [ ] 历史配置和旧数据仍可读取，或已说明迁移方案。
- [ ] 实时线程、列表请求和批处理没有明显性能退化。
- [ ] 错误路径 fail-closed，不会静默返回错误金融结果。
- [ ] 测试能在未修复代码上失败，并在修复后通过。
- [ ] 已执行适用的测试、构建、Ruff 和 `git diff --check`。
- [ ] 最终 diff 不含敏感数据、本地路径、调试输出和生成文件。

## 11. PR 复审流程

作者自审和维护者复审均按以下顺序进行，避免只看页面效果或新增代码：

1. **确认问题**：根据描述和测试复现旧行为，确认 PR 解决的是同一个问题。
2. **检查边界**：确认代码位于正确模块，没有反向依赖、平行实现或 API 层重计算。
3. **核对数据契约**：检查单位、复权、日期、时区、资产类型、空值和排序方向。
4. **核对插件化**：检查是否依赖 provider 能力，非 TickFlow 数据源能否工作或明确降级。
5. **跟踪状态变化**：从写入一路检查持久化、缓存、generation、SSE 和前端查询失效。
6. **检查兼容性**：使用历史配置、旧策略 JSON、旧 Parquet schema 和缺字段数据验证。
7. **检查性能和并发**：定位是否进入实时、列表或全量扫描热路径，检查锁和原子替换。
8. **检查失败路径**：网络失败、无权限、空数据、能力缺失和部分写入时不得产生错误状态。
9. **评估测试质量**：测试必须断言业务结果，覆盖负例和边界，不能只断言接口返回 200。
10. **检查最终 diff**：按文件逐项确认必要性，排除无关格式化、敏感信息和临时文件。
11. **给出结论**：明确写出“可合并”“修改后合并”或“不建议合并”，区分阻断项和建议项。

问题严重级别：

| 级别 | 定义 | 合并要求 |
| --- | --- | --- |
| `P0` | 数据破坏、安全漏洞、可能导致严重错误交易结果 | 禁止合并，修复并完整复审 |
| `P1` | 核心流程不可用、错误金融口径、未来函数、广泛回归 | 禁止合并，修复并补回归测试 |
| `P2` | 明确功能错误、兼容性问题或明显性能退化 | 修改后合并 |
| `P3` | 维护性、局部体验、文档或测试补强建议 | 可不阻断，但应记录后续处理方式 |

复审意见应包含文件和行号、触发条件、实际影响及建议修改方向。不要只写“这里可能有问题”或直接给出没有证据的结论。

### 11.1 追加提交后的复审

- 先逐项核对上轮每个阻断问题是否在代码和测试中真正解决，不以提交者回复“已修改”为依据。
- 查看新增 commit 便于理解修复意图，但最终必须重新审查 PR 相对目标分支的完整 diff，不能只看最后一次提交。
- 重新执行受影响测试，并检查修复是否引入新的单位、缓存、兼容性、性能或插件化问题。
- 已解决的问题明确标记为已验证；仍存在的问题引用当前最新行号并说明缺失内容。
- 原阻断项全部解决且没有新增阻断项后，才能把结论改为“可合并”。

### 11.2 推荐的复审输出格式

```text
结论：可合并 / 修改后合并 / 不建议合并

阻断问题：
- [P1/P2] 文件:行号 - 触发条件、实际影响、修改要求

非阻断建议：
- [P3] 文件:行号 - 建议及理由

已验证：
- 执行的测试或构建命令及结果
- 上轮问题的逐项复核结果

剩余风险：
- 未覆盖的平台、数据源、数据规模或场景
```

没有发现问题时也应明确写“未发现阻断问题”，并说明尚未验证的范围，不能用“看起来没问题”代替结论。

## 12. 不得合并的情况

出现以下任一情况，PR 不应合并：

- 无法说明根因，修改只是增加延时、重试、强制刷新或吞掉异常来掩盖现象。
- 混用百分比、复权价、自然日和交易日，或无法证明金融计算口径。
- 通用功能直接绑定单一数据源，且没有能力检测或明确降级。
- 写入后存在已知缓存不一致，需用户重启或手动清数据才能正确显示。
- 回测引入未来数据、绕过成交约束，或历史结果和交易记录使用不同选股逻辑。
- 实时线程增加阻塞网络请求、全量历史计算或无界任务。
- 破坏历史策略、配置、数据文件或 API，且没有兼容或迁移方案。
- 文件操作可能越界删除、默认覆盖用户数据，或失败后继续执行。
- 测试没有复现问题、只覆盖正常路径，或必要测试/前端构建失败。
- PR 包含密钥、用户数据、本地数据目录、机器绝对路径或大量无关改动。
- 对评审提出的 `P0`、`P1`、`P2` 问题尚未处理或验证。

## 13. AI 编码代理额外规则

- 开始前先读取本文件、目标模块、相邻实现、调用方和相关测试。
- 修改前用简短计划写明每一步及验证方式；简单改动可只写一句。
- 不把猜测当成事实。无法从代码、测试或文档确认的业务口径，应明确询问。
- 不因用户要求“直接修复”就跳过复现、根因分析和回归验证。
- 不自动执行提交、推送、合并、删除文件、数据库迁移或批量数据覆盖；需要时按当前会话权限规则取得明确确认。
- 不覆盖工作区已有改动。遇到同文件并行修改时先读取最新内容并保留双方逻辑。
- 不虚构测试结果、性能数据、GitHub 状态或线上行为。未运行的验证必须明确标注。
- 审查 PR 时先报告问题，按严重级别排序并引用文件行号；最后再给合并建议和简短总结。
- 完成后检查 `git diff` 和 `git status`，准确说明改了什么、验证了什么、仍有什么风险。

遵循本指南的衡量标准不是文档写得多，而是：改动范围更小、金融口径有证据、插件边界不被绕过、测试能真实复现问题、复审结论可执行，且相同问题不再反复返工。