docs: add strategy manual, office report, workflow design doc

docs/gitea_workflow_design.md

@@ -0,0 +1,397 @@
+# Beast Trader — Gitea 仓库结构与自动化工作流设计
+
+> 版本：v1.0 | 日期：2026-06-11 | 作者：FXY
+
+---
+
+## 一、背景
+
+Gitea 1.24.2 已部署于东京服务器（43.163.225.30:3000），库存为空，数据库为 SQLite。现有量化交易系统（freqtrade + Binance Futures）的后端基础设施已就位，需建立完整的版本管理、研发工作流和自动化运维体系。
+
+---
+
+## 二、仓库结构
+
+### （一）总体方案：单仓库（Monorepo）
+
+理由：单人使用场景下多仓库增加管理成本，且策略、回测、文档之间存在强耦合关系。
+
+### （二）目录结构
+
+```
+beast-trader/                         # 根仓库
+│
+├── strategies/                       # ── 策略代码 ──
+│   ├── current/                      #   当前活跃策略（软链指向具体版本）
+│   ├── v1.6/                         #   历史版本（从 versions/ 迁移）
+│   ├── v2.1/
+│   ├── v2.2b/
+│   ├── v2.2c/
+│   ├── v2.2d/                        #   🔥 当前最优基线
+│   └── swing/                        #   波段策略系列
+│       ├── v3.0/
+│       └── v3.1/
+│
+├── backtests/                        # ── 回测结果 ──
+│   ├── full/                         #   全周期回测（2021-2026）
+│   │   ├── v2_2c_full.txt
+│   │   ├── v2_2c_full.meta.json
+│   │   └── v2_2d_full.txt
+│   ├── yearly/                       #   逐年回测
+│   │   ├── v2_2d_2021.txt
+│   │   ├── v2_2d_2022.txt
+│   │   └── ...
+│   └── swing/                        #   波段策略回测
+│
+├── trades/                           # ── 实盘交易记录（自动生成）──
+│   ├── 2026/
+│   │   ├── 06/
+│   │   │   ├── trades_2026-06-11.md
+│   │   │   ├── trades_2026-06-12.md
+│   │   │   └── ...
+│   │   └── ...
+│   ├── monthly/                      #   月度汇总（自动生成）
+│   │   ├── 2026-06.md
+│   │   └── ...
+│   └── INDEX.md                      #   交易记录索引（自动维护）
+│
+├── daily_briefs/                     # ── 日报 ──
+│   ├── 2026/
+│   │   ├── 06/
+│   │   │   ├── brief_2026-06-11.md
+│   │   │   └── ...
+│   │   └── ...
+│   └── INDEX.md
+│
+├── docs/                             # ── 文档 ──
+│   ├── manual/                       #   策略说明书
+│   │   ├── v2_2d_manual.pdf
+│   │   └── v2_2d_manual.html
+│   ├── reports/                      #   阶段性报告
+│   │   ├── today_report_2026-06-11.md
+│   │   └── ...
+│   └── guides/                       #   操作指南
+│       ├── api_deployment.md
+│       └── workflow_reference.md
+│
+├── config/                           # ── 配置文件 ──
+│   ├── freqtrade/
+│   │   ├── config.json               #   Docker内配置（去掉密钥占位）
+│   │   ├── config.pairlist.json
+│   │   └── config.backtest.json
+│   ├── docker/
+│   │   ├── docker-compose.yml
+│   │   └── Dockerfile
+│   └── dashboard/
+│       ├── nginx.conf
+│       └── dashboard.env
+│
+├── scripts/                          # ── 自动化脚本（服务器可执行）──
+│   ├── export_trades.sh              #   实盘交易导出 → git push
+│   ├── generate_brief.sh             #   日报生成 → git push
+│   ├── deploy_strategy.sh            #   策略部署到 Docker
+│   ├── archive_backtest.py           #   回测结果自动归档
+│   └── init_gitea_repo.sh            #   首次初始化脚本
+│
+├── .gitea/workflows/                 # ── Gitea Actions 工作流 ──
+│   ├── deploy-on-tag.yml             #   tag 推送时自动部署
+│   └── daily-backup.yml              #   每日自动备份
+│
+├── .gitignore
+└── README.md
+```
+
+### （三）设计原则
+
+1. **按时间组织**：trades/、daily_briefs/ 按年/月两级目录自然归档
+2. **按版本归档**：strategies/ 每个版本独立子目录（延续现有原则）
+3. **自动写入，人工阅读**：实盘记录和日报是程序自动写入的，格式要规范可读
+4. **一台服务器，一套体系**：开发者 = 用户，不需要分支策略，master/main 即可
+5. **紧耦合不分离**：策略代码和它的回测结果放在不同目录但同一仓库，禁止拆分
+
+---
+
+## 三、完整工作流设计
+
+### （一）生命周期总览
+
+```
+┌────────────────────────────────────────────────────────────────────────┐
+│                                                                        │
+│   [研发] ──→ [回测] ──→ [评估] ──→ [发布] ──→ [实盘] ──→ [复盘]     │
+│     ↑                                                    │             │
+│     └──────────────────── 迭代 ──────────────────────────┘             │
+│                                                                        │
+└────────────────────────────────────────────────────────────────────────┘
+```
+
+### （二）各阶段详细流程
+
+#### Phase 1：策略研发
+
+| 步骤 | 操作 | 自动化 |
+|:---|:---|:---|
+| 1.1 | 在 WorkBuddy 中编写/修改策略代码 | — |
+| 1.2 | `git add strategies/current/ && git commit -m "v2.3: XXXX"` | — |
+| 1.3 | `git push` 到 Gitea | ✅ 触发 Gitea Webhook 通知 |
+
+#### Phase 2：回测验证
+
+| 步骤 | 操作 | 自动化 |
+|:---|:---|:---|
+| 2.1 | Docker 内回测：`freqtrade backtesting ...` | ✅ 可脚本化 |
+| 2.2 | 回测结果保存到 `backtests/full/` | ✅ 脚本自动写入 |
+| 2.3 | 回测结果推送到 Gitea | ✅ git push |
+
+*标准回测命令（固化）：*
+```
+# 策略层 full 测试
+freqtrade backtesting --strategy StructureFlowStrategyV2_2d \
+  --timerange 20210101-20260601 \
+  --config /freqtrade/user_data/config.backtest.json \
+  --export trades
+```
+
+#### Phase 3：评估决策
+
+| 步骤 | 操作 | 自动化 |
+|:---|:---|:---|
+| 3.1 | 查看回测结果（对比 v2.2d 基线） | — |
+| 3.2 | 决定是否部署 | — |
+| 3.3 | 如优化，回到 Phase 1；如发布，进入 Phase 4 | — |
+
+#### Phase 4：代码发布（Release）
+
+| 步骤 | 操作 | 自动化 |
+|:---|:---|:---|
+| 4.1 | 更新 `strategies/current/` 指向新版本 | — |
+| 4.2 | `git tag v2.3.0 && git push --tags` | ✅ 触发 Actions 自动部署 |
+| 4.3 | 服务器拉取 → 复制策略到 `user_data/strategies/` | ✅ Shell 脚本 |
+| 4.4 | 重启 freqtrade Docker 容器 | ✅ `docker-compose down && up -d` |
+
+#### Phase 5：实盘运行
+
+| 步骤 | 操作 | 自动化 |
+|:---|:---|:---|
+| 5.1 | freqtrade 启动 live/dry-run | — |
+| 5.2 | 每笔成交 → 自动记录到 `trades/` | ✅ 每小时 cron 导出 |
+| 5.3 | 每日日报 → Server酱推送微信 | ✅ daily_brief.py + cron |
+| 5.4 | 日报 → 推送至 Gitea | ✅ cron + git push |
+
+#### Phase 6：复盘优化
+
+| 步骤 | 操作 | 自动化 |
+|:---|:---|:---|
+| 6.1 | 查看 `trades/` 实盘记录 | — |
+| 6.2 | 分析盈亏分布、胜率、出场原因 | — |
+| 6.3 | 提出新思路 → 回到 Phase 1 | — |
+
+---
+
+## 四、自动化架构
+
+### （一）总体架构图
+
+```
+┌───────────────────────────────────────────────────┐
+│              WorkBuddy（智能调度层）                 │
+│  ┌──────────────┐    ┌───────────────────────┐    │
+│  │ 每日08:00读取 │    │  Webhook 接收通知      │    │
+│  │ Gitea 最新日报│    │  → 触发回测/分析       │    │
+│  └──────────────┘    └───────────────────────┘    │
+└───────────────────────────────────────────────────┘
+                        │
+                        ▼
+┌───────────────────────────────────────────────────┐
+│              东京服务器（执行层）                    │
+│                                                    │
+│  ┌─────────┐  ┌──────────┐  ┌──────────────────┐  │
+│  │  Cron   │  │  Gitea   │  │  Gitea Actions   │  │
+│  │ (系统级)│  │ Webhooks │  │ （CI/CD 可选）   │  │
+│  └────┬────┘  └────┬─────┘  └───────┬──────────┘  │
+│       │            │                │              │
+│       ▼            ▼                ▼              │
+│  ┌─────────────────────────────────────────────┐   │
+│  │              Shell 脚本层                     │   │
+│  │  export_trades.sh  │  generate_brief.sh     │   │
+│  │  deploy.sh         │  archive_results.sh    │   │
+│  └────────────────────┼────────────────────────┘   │
+│                       │                            │
+│                       ▼                            │
+│  ┌─────────────────────────────────────────────┐   │
+│  │              Docker/Freqtrade                │   │
+│  │         实盘执行 / 回测引擎                   │   │
+│  └─────────────────────────────────────────────┘   │
+└───────────────────────────────────────────────────┘
+```
+
+### （二）Cron 任务表
+
+| 任务 | 调度 | 脚本 | 功能 |
+|:---|:---|:---|:---|
+| 实盘导出 | **每小时** | `export_trades.sh` | 查 Freqtrade DB → 写入 trades/ → git commit+push |
+| 日报生成 | 每日 **23:55 UTC** | `daily_brief.py`（已有） | 现行系统，扩充写入 Gitea |
+| 日报推送 | 日报生成后 | `generate_brief.sh` | 日报文件 → git push |
+| 仓库备份 | 每日 **03:00** | `backup_repo.sh` | Gitea 内 git bundle → 备份到独立存储 |
+
+### （三）实盘交易记录自动导出机制
+
+这是本次设计的核心创新点。方案如下：
+
+```
+Freqtrade SQLite DB
+    │  tradesv3.sqlite（Docker内 /freqtrade/user_data/）
+    │
+    ▼
+export_trades.sh（每小时 cron 执行）
+    │
+    ├── 1. 拉取最新成交记录（自上次导出时间戳之后）
+    ├── 2. 格式化为 Markdown 表格
+    ├── 3. 写入 trades/2026/06/trades_2026-06-11.md
+    ├── 4. 更新 INDEX.md（追加本日记录入口）
+    ├── 5. git add + git commit + git push
+    │
+    ▼
+Gitea 仓库自动更新
+```
+
+**每条记录的字段：**
+
+| 字段 | 说明 | 来源 |
+|:---|:---|:---|
+| 序号 | #001, #002... | 自动递增 |
+| 时间 | 入场/出场时间戳 | Freqtrade DB |
+| 方向 | 做多/做空 | Freqtrade DB |
+| 入场价 | | Freqtrade DB |
+| 出场价 | | Freqtrade DB |
+| 数量 | ETH 数量 | Freqtrade DB |
+| 盈亏 | 绝对金额（USDT） | Freqtrade DB |
+| 收益率 | % | 计算 |
+| 出场原因 | take_profit / stop_loss / trailing_stop / signal | Freqtrade DB |
+| 冷却期 | 交易后冷却剩余 | 策略上下文 |
+| 备注 | 人工填写 | 手动 |
+
+**查询 SQL：**
+```sql
+SELECT id, pair, open_time, close_time, open_rate, close_rate,
+       amount, close_profit, close_profit_abs, exit_reason
+FROM trades
+WHERE close_time > {last_export_timestamp}
+ORDER BY close_time ASC;
+```
+
+### （四）首次初始化脚本
+
+首次搭建时，需要将服务器上现有的所有文件推送到 Gitea。这需要一个一次性脚本：
+
+```bash
+#!/bin/bash
+# init_gitea_repo.sh — 首次初始化
+
+# 1. 在 Gitea 创建仓库
+# 2. git init + 建立目录结构
+# 3. 复制现有策略文件到 strategies/
+# 4. 复制回测结果到 backtests/
+# 5. 复制文档到 docs/
+# 6. 复制配置文件到 config/
+# 7. 复制 Dashboard 代码到 dashboard/
+# 8. 首次 commit + push
+```
+
+### （五）关键自动化脚本设计
+
+#### 5.1 `export_trades.sh` — 实盘交易记录导出
+
+```bash
+#!/bin/bash
+# 每小时执行，从 Freqtrade DB 导出新成交记录到 Gitea 仓库
+
+LAST_EXPORT_FILE="/var/lib/gitea/export_timestamp.txt"
+TRADES_DB="/home/ubuntu/freqtrade/user_data/tradesv3.sqlite"
+REPO_DIR="/home/ubuntu/beast-trader"
+TRADES_DIR="$REPO_DIR/trades/$(date +%Y/%m)"
+
+# 1. 读取上次导出时间
+if [ -f "$LAST_EXPORT_FILE" ]; then
+    LAST_TS=$(cat "$LAST_EXPORT_FILE")
+else
+    LAST_TS=0
+fi
+
+# 2. 查询新成交记录（需在 Docker 内或直接读 SQLite）
+# 注意：tradesv3.sqlite 在 Docker volume 内，需从宿主机访问
+# 如果 Docker 挂载了目录，可直接读取
+
+# 3. 格式化写入 Markdown
+# ...
+
+# 4. 更新 INDEX.md
+# ...
+
+# 5. git push
+cd "$REPO_DIR" && git add . && git commit -m "trades: auto export $(date +%Y-%m-%d %H:%M)" && git push
+```
+
+#### 5.2 `deploy_strategy.sh` — 策略自动部署
+
+```bash
+#!/bin/bash
+# 在 git tag push 后触发
+
+TAG=$1  # 例如 v2.3.0
+
+# 1. 从 Gitea 拉取最新代码
+cd /home/ubuntu/beast-trader && git pull
+
+# 2. 将策略复制到 freqtrade 目录
+cp strategies/current/*.py /home/ubuntu/freqtrade/user_data/strategies/
+
+# 3. 重启 freqtrade Docker
+cd /home/ubuntu/freqtrade && docker-compose down && docker-compose up -d
+
+# 4. 记录部署版本
+echo "Deployed: $TAG at $(date)" >> deploy_history.log
+```
+
+---
+
+## 五、实现优先级建议
+
+建议分三个阶段推进：
+
+### 第一阶段：数据入仓（1-2天）
+
+| 优先级 | 任务 | 产出 |
+|:---|:---|:---|
+| P0 | 写好 `init_gitea_repo.sh`，将现有全部文件推送到 Gitea | Gitea 仓库完整初始化 |
+| P0 | 建立目录结构 | 目录框架 |
+| P1 | 迁移 strategies/ 下所有版本 | 版本历史完整 |
+| P1 | 迁移 backtest_results/ 下的结果 | 回测历史完整 |
+| P2 | 迁移 docs/ 说明书和报告 | 文档完整 |
+
+### 第二阶段：自动化搭建（2-3天）
+
+| 优先级 | 任务 | 产出 |
+|:---|:---|:---|
+| P0 | 编写 `export_trades.sh` + 配置 cron | 实盘记录每小时自动归档 |
+| P0 | 日报增加 git push 步骤 → Gitea | 日报自动入仓 |
+| P1 | 编写 `deploy_strategy.sh` | 一键部署 |
+| P1 | 实现 `scripts/archive_backtest.py` | 回测结果自动归档 |
+
+### 第三阶段：工作流闭环（持续）
+
+| 优先级 | 任务 | 产出 |
+|:---|:---|:---|
+| P1 | Gitea Webhook → WorkBuddy 通知 | 变更即感知 |
+| P2 | 月度交易报告自动生成 | 复盘辅助 |
+| P2 | Gitea Actions 搭建 | CI/CD 能力 |
+| P3 | 策略对比看板（Gitea Pages） | 可视化演进 |
+
+---
+
+## 六、附则
+
+1. **密钥不入库**：Exchange API key/secret、Server酱 SendKey 等敏感信息禁止提交到 Gitea
+2. **回测数字仅供参考**：回测结果说明"过去表现好"，不代表未来收益
+3. **只增不删**：trades/ 和 daily_briefs/ 是单向录入，禁止手动删除
+4. **日志即文档**：Gitea 的 commit log 本身就是研发日志，commit message 写清楚改动内容

docs/today_report_2026-06-11.md

@@ -0,0 +1,98 @@
+# 关于v2.2d量化交易策略研发进度及实盘部署准备情况的报告
+
+根据近期工作部署，现将2026年6月11日策略研发工作推进情况报告如下：
+
+## 一、基本情况
+
+本日围绕v2.2d策略开展了基线确认、回测验证、文档编撰、实盘环境搭建等系列工作，阶段性成果显著。核心进展如下：
+
+| 工作事项 | 完成情况 | 备注 |
+|:---|:---|:---|
+| v2.2d全周期回测 | 已完成 | 2021.01-2026.06，2057倍收益 |
+| v2.2d逐年回测 | 已完成 | 按年独立测算，5年正收益 |
+| v2.2d策略说明书 | 已完成 | A4优化版PDF，32页 |
+| BinanceAPI部署 | 已完成 | 交易权限+I锁定东京 |
+| Dashboard升级 | 已完成 | 实时价格+逐年数据 |
+| 博客哲学分析 | 已完成 | 10章深度点评 |
+| 非入场诊断 | 已完成 | resistance_alive到期 |
+
+## 二、主要做法
+
+### （一）策略基线更替——v2.2d确立为新最优
+
+1. **问题溯源**。v2.2c冷却期逻辑存在缺陷：`short_base.rolling(6).max()==0`基于条件满足而非实际入场计时，市场持续满足条件时可永久阻止下单。
+
+2. **修复方案**。将冷却期改为`_apply_cooldown`基于实际入场事件触发，彻底消除自锁死风险。
+
+3. **回测验证**。全周期回测（2021.01.01—2026.06.01）结果如下：
+
+| 指标 | v2.2c（旧基线） | v2.2d（新基线） | 变化 |
+|:---|:---|:---|:---|
+| 最终资金 | $11,983,254.68 | $20,578,435.93 | +71.7% |
+| 收益率 | +119,732.55% | +205,684.36% | — |
+| 交易笔数 | 1,056 | 1,375 | +30.2% |
+| 胜率 | 29.7% | 28.9% | — |
+| CAGR | 270.15% | 309.01% | +14.4% |
+| Sharpe | 0.82 | 1.03 | +25.6% |
+| 利润因子 | 1.97 | 1.92 | — |
+| 最大回撤 | 17.96% | 20.58% | — |
+
+4. **结论**。v2.2d在交易频率、最终收益、夏普比率三项核心指标上全面优于v2.2c，冷却期修复逻辑自洽。即日起v2.2d为新最优基线，此前所有引用以v2.2d为准。
+
+### （二）逐年回测验证
+
+对v2.2d进行逐年独立回测（每年$10,000起算），结果如下：
+
+| 年份 | 交易数 | 收益率 | 终值 | 同期市场 | 胜率 | 最大回撤 |
+|:---|:---|:---|:---|:---|:---|:---|
+| 2021 | 172 | +251.16% | $35,116 | +407% | 27.3% | 11.28% |
+| 2022 | 204 | +110.91% | $21,091 | -68% | 30.9% | 11.69% |
+| 2023 | 182 | +49.35% | $14,935 | +92% | 26.9% | 10.04% |
+| 2024 | 232 | +185.84% | $28,584 | +46% | 28.4% | 6.87% |
+| 2025 | 221 | +608.24% | $70,824 | -11% | 27.6% | 13.92% |
+| 2026 | 54 | -11.87% | $8,813 | -45% | 22.2% | 14.89% |
+
+主要发现：一是策略在熊市和震荡市中表现突出（2022市场-68%时策略+111%），牛市相对逊色但保持正收益。二是胜率稳定在22%—31%区间，回撤控制在7%—15%范围，逐年表现一致性较好。
+
+### （三）策略说明书编撰
+
+完成v2.2d策略说明书编撰及PDF转换，共12章、32页。内容覆盖策略逻辑、参数说明、风险管理、部署运维等全部环节。PDF经A4尺寸优化排版，作者署名FXY，可直接打印使用。
+
+### （四）Binance API部署及实盘环境就绪
+
+1. **密钥安全管理**。新旧密钥已完成更替，新密钥仅保留Futures + Trade权限，未开通提币，IP锁定东京服务器（43.163.225.30）。密钥存储路径：`~/freqtrade/.keys/binance_readonly`（chmod 600）。
+
+2. **Freqtrade桥接**。将密钥转换为JSON配置（`user_data/secrets.json`，chmod 600），通过docker-compose配置链`config.json → config.pairlist.json → secrets.json`自动加载覆盖。
+
+3. **连通验证**。三项测试全部通过：服务器时间正常、账户状态可交易（canTrade=True）、合约下单接口可达（返回价格过低提示，非权限拒绝）。
+
+4. **结论**。实盘环境已具备部署条件，无需额外配置或重新上传密钥。
+
+### （五）非入场原因诊断
+
+用户发现14:00（北京时间）应有交易信号但未触发。诊断确认原因为`resistance_alive`到期：11:00的1661阻力位于三根K线后（14:00）失效，策略正确拒绝了在已过期阻力位上做空。经评估，当前3根K线有效期设置合理，维持不变。
+
+## 三、存在的问题
+
+（一）**冷却期逻辑的隐患**。v2.2c的冷却期缺陷虽然已在v2.2d修复，但`_apply_cooldown`新逻辑仍需在实盘环境中持续观察，确保不存在新的边界条件问题。
+
+（二）**牛市相对表现偏弱**。逐年数据表明策略在趋势性牛市中跑输市场（如2021年+251% vs 市场+407%），这是价格行为学策略的固有特征，暂时不作为缺陷对待，但需关注。
+
+（三）**2026年当前负收益**。今年前半年策略-11.87%（市场-45%），绝对收益为负。虽然相对表现尚可，但提醒策略在极端行情下仍有持续亏损周期可能。
+
+（四）**夏普比率仍属中等偏优**。1.03的夏普比率在加密货币策略中属"良好偏优"，距离优秀（1.5+）仍有提升空间。
+
+## 四、下一步工作打算
+
+（一）**启动v2.2d实盘（dry-run）**。当前部署条件已全部就绪，建议择机启动dry-run，以真实市场环境检验策略执行稳定性。
+
+（二）**策略说明书完善**。根据实际运行反馈，补充实盘操作章节和常见问题排查手册。
+
+（三）**波段策略研发**。v3.1在熊市/震荡市表现优异（2025年+65.47%，70%胜率），继续探索与趋势策略v2.2d的互补机制，考虑多策略并行架构。
+
+（四）**监控日报自动化**。现有daily_brief.py已运行稳定，后续可增强为异常行情自动预警。
+
+特此报告。
+
+FXY
+2026年6月11日