yuxuanhui
154 lines
5.8 KiB
Markdown
154 lines
5.8 KiB
Markdown
# 知行 B1 选股策略实施计划
|
||
|
||
## 实施原则
|
||
|
||
- 只修改 `zhixing-system`；旧项目只读，不回写、不重命名、不提交旧项目数据。
|
||
- 先写行为测试，再补最小实现；每一步保持 `uv run pytest` 可定位失败范围。
|
||
- `zhixing_b1` 是新策略身份；不要把 `xg_composite` 作为新模块的对外名称。
|
||
- 公式语义优先于旧 Python 的偶然行为；每个有意差异都要在 fixture 或测试名中
|
||
留下证据。
|
||
- 不启动 HTTP、前端、信号持久化或全市场批次编排；它们属于后续任务。
|
||
|
||
## 1. 依赖与模块骨架
|
||
|
||
- 在 `zhixing-server/pyproject.toml` 声明直接依赖 `pandas` 和 `numpy`，执行
|
||
`uv lock`，确认锁文件与 Python 3.12 环境一致。
|
||
- 创建 `modules/selection/{domain,application,infrastructure,presentation}`
|
||
包和上下文 README，保持 domain 不导入 FastAPI/Psycopg。
|
||
- 先新增领域模型、端口和评估状态类型，再接入基础设施。
|
||
|
||
验证：
|
||
|
||
```bash
|
||
cd zhixing-server
|
||
uv lock --check
|
||
uv run python -c "import numpy, pandas; print(numpy.__version__, pandas.__version__)"
|
||
```
|
||
|
||
回滚点：依赖或包骨架若无法通过 Ruff/Pyright，先撤销骨架，不触碰
|
||
`modules/market_data`。
|
||
|
||
## 2. 迁移公式原语
|
||
|
||
- 从旧项目 `shared/indicators.py`、`kdj.py`、`rsi.py`、`zhixing.py` 和
|
||
`market_type.py` 提取必要实现到 `selection/domain/indicators.py`。
|
||
- 先覆盖 `MA/EMA/LLV/HHV/SMA/REF/EXIST/EVERY/COUNT/HHVBARS/BARSLAST/CROSS`，
|
||
再实现 KDJ、RSI、知行线和板块幅度参数。
|
||
- 每个公共函数增加完整类型、参数/返回值/边界说明；NaN、除零和不足窗口行为
|
||
用测试锁定。
|
||
- 不引入 Numba、SciPy 或其他旧项目专用依赖；首期 Pandas/NumPy 足够保持公式
|
||
计算的向量化和数值接近。
|
||
|
||
验证：
|
||
|
||
```bash
|
||
cd zhixing-server
|
||
uv run pytest tests/unit/selection/test_indicators.py
|
||
```
|
||
|
||
## 3. 实现 `ZhixingB1Strategy`
|
||
|
||
- 将旧 `prepare_xg_indicators()` 拆成可读的领域计算步骤：基础线、振幅、KDJ/RSI、
|
||
缩量、大绿棒、异动、趋势、距离/回踩、7 个子信号。
|
||
- 策略类固定 `name = "zhixing_b1"`，公开入口显式接收 `StockHistory` 和
|
||
`target_trade_date`。
|
||
- 对目标交易日定位使用日期索引，不使用 DataFrame 最后一行猜测目标日期。
|
||
- 保留 7 个 mask 的全部命中，按公式顺序产生多个 `SelectionSignal`，不可使用
|
||
旧代码中的 `break`。
|
||
- 详情只写可序列化、与目标行相关的关键指标；不要保存整张 DataFrame。
|
||
- 对目标日缺失、历史不足、无信号分别返回评估状态；公式计算异常向上暴露，
|
||
不静默转换为空结果。
|
||
|
||
验证：
|
||
|
||
```bash
|
||
cd zhixing-server
|
||
uv run pytest tests/unit/selection/test_zhixing_b1.py
|
||
```
|
||
|
||
回滚点：若结果数量明显偏离 golden，保留公式原语测试和差异报告，回滚策略
|
||
编排层，不回退到旧 `xg_composite` 命名。
|
||
|
||
## 4. 建立市场数据读取端口与 PostgreSQL 适配器
|
||
|
||
- 在 `selection/domain/ports.py` 定义只读 `MarketDataReader`。
|
||
- 在 `selection/infrastructure/postgres_reader.py` 实现参数化查询，读取 qfq
|
||
`market_daily_bar`，左连接同日 `market_daily_basic`，按日期升序映射为
|
||
`StockHistory`。
|
||
- 从 `Settings` 注入连接串；不直接读取环境变量，不调用 Tushare，不回退 CSV。
|
||
- 使用数据库事实表的 `source_adj = 'qfq'` 过滤，拒绝目标日之后的行。
|
||
- 连接失败转换为带股票和目标日上下文的基础设施错误；目标日无 bar 属于可识别
|
||
的业务状态。
|
||
|
||
验证：
|
||
|
||
```bash
|
||
cd zhixing-server
|
||
uv run pytest tests/unit/selection/test_postgres_reader.py
|
||
```
|
||
|
||
若增加 PostgreSQL 集成覆盖：
|
||
|
||
```bash
|
||
cd zhixing-server
|
||
uv run pytest -m integration tests/integration/test_selection_reader.py
|
||
```
|
||
|
||
回滚点：只读适配器失败时删除 selection 适配器即可；不得修改已有市场数据表、
|
||
同步事务或 Alembic migration。
|
||
|
||
## 5. 应用用例与 Fake reader
|
||
|
||
- 实现 `EvaluateZhixingB1`，输入 `ts_code`、`target_trade_date` 和 reader，输出
|
||
`SelectionEvaluation`。
|
||
- 用例只负责读取、调用领域策略和映射错误；不负责全市场循环、保存信号或 HTTP
|
||
响应。
|
||
- 提供 Fake reader 测试目标日期截断、缺失目标行、历史不足、无信号、选中多分类
|
||
和基础设施错误。
|
||
|
||
验证：
|
||
|
||
```bash
|
||
cd zhixing-server
|
||
uv run pytest tests/unit/selection/test_evaluate.py
|
||
```
|
||
|
||
## 6. 固定 fixture 与 golden 对比
|
||
|
||
- 从旧项目现有 `data/raw` 中选取少量股票和目标日期，抽取最小 OHLCV CSV，放入
|
||
`zhixing-server/tests/fixtures/selection/zhixing_b1/`。
|
||
- 将旧实现或人工确认结果固化为 JSON，包含目标日期、命中分类集合和关键详情的
|
||
容差范围；测试运行时不导入旧项目。
|
||
- 至少包含普通代码和宽幅代码，并加入一个人工构造的同日多信号样本。
|
||
- 明确记录旧实现“只保留第一个分类”与新实现“保留全部分类”的差异。
|
||
|
||
验证：
|
||
|
||
```bash
|
||
cd zhixing-server
|
||
uv run pytest tests/integration/test_zhixing_b1_golden.py
|
||
```
|
||
|
||
## 7. 完整质量检查与规划复核
|
||
|
||
实现结束后运行：
|
||
|
||
```bash
|
||
cd zhixing-server
|
||
uv run ruff format --check .
|
||
uv run ruff check .
|
||
uv run pyright
|
||
uv run pytest
|
||
```
|
||
|
||
并检查：
|
||
|
||
- `rg -n "xg_composite|zgnb\." src/zhixing_server/modules/selection tests` 只在
|
||
迁移说明或兼容性测试中出现，不成为新领域运行时依赖；
|
||
- 旧项目工作区没有被修改；
|
||
- 没有新增 HTTP 路由、前端文件、信号表 migration 或调度入口；
|
||
- golden、单元测试和端口测试都能在无网络、无生产数据库条件下运行。
|
||
|
||
完成 planning 后，先向用户展示 `prd.md`、`design.md` 和本文件摘要；只有用户
|
||
明确批准最新 planning summary，才能执行 `task.py start` 并进入实现阶段。
|