feat: introduce spec system + dashboard + health pipeline (AgentsMeeting template)

2026-07-19 10:50:34 +08:00
parent 81c6dd2314
commit 747fdfe467
19 changed files with 1826 additions and 0 deletions
@@ -0,0 +1,214 @@
+# MoFin 开发规范
+
+> 版本: v1.0 | 更新: 2026-07-19 | 基于 AgentsMeeting 样板重构
+>
+> 📋 样板参考: [AgentsMeeting TEMPLATE-GUIDE.md](../AgentsMeeting/docs/TEMPLATE-GUIDE.md)
+
+---
+
+## 五条红线
+
+1. **先读/写 Spec，再写代码** — 新增功能先写 spec 再实现；修改已有功能先读对应 spec 了解架构和约束再动手。没有 spec 的模块在 Dashboard 不可见，视为未完成
+2. **部署必验** — 部署后不打开 Dashboard F Tab 验证 = 部署未完成
+3. **不可见即不存在** — 组件不在 Dashboard 中显示 = 等于没部署。离线不告警 = 监控缺陷
+4. **实现后同步 Spec** — 每轮开发完毕后，必须将 `specs/{module}.json` 更新为与实际实现一致的状态。文档过期 = 等于没写
+5. **部署目标即验收标准** — 所有代码必须以部署目标环境（Linux 246）为基准编写和测试。禁止使用 Windows 专属 API（`tasklist`、`netstat`、`schtasks`、`wmic`）在 246 部署的代码中
+
+---
+
+## 一、双轨同源规范体系
+
+每新增/修改一个独立功能模块，必须先写 `specs/{module}.json`。
+一个来源同时产出两套文档：
+
+```
+specs/{module}.json
+├── human_help  → ? 按钮（人类看说明/排错）
+└── ai_spec     → § 按钮（AI 看接口/约束/依赖）
+```
+
+### 什么算一个模块
+
+满足以下任一条件即视为独立模块，必须写 spec：
+
+- 暴露独立的 HTTP API 端点
+- 在 Dashboard 上有独立 UI 面板（`?` + `§` 按钮）
+- 有独立的配置文件 / 数据文件
+- 可独立部署（如定时任务、数据采集脚本）
+
+### Spec 字段标准
+
+```json
+{
+  "module": "模块名（与 Dashboard 引用名一致）",
+  "version": "1.0",
+  "purpose": "一句话说明这个模块干什么",
+
+  "human_help": {
+    "title": "面向人类的标题",
+    "description": ["说明段落数组"],
+    "usage": ["使用步骤数组"],
+    "troubleshooting": ["常见问题数组"]
+  },
+
+  "ai_spec": {
+    "apis": [
+      {"method": "GET", "path": "/api/xxx", "returns": "返回值说明"}
+    ],
+    "dependencies": ["依赖的服务或文件"],
+    "constraints": ["AI 必须遵守的约束"],
+    "must_not": ["AI 绝对不能做的事"],
+    "tests": [{"id": "T1", "name": "测试用例名"}],
+    "related_files": ["实现文件路径"]
+  }
+}
+```
+
+### 当前模块清单
+
+| 模块 | spec 路径 | 说明 | 状态 |
+|------|----------|------|------|
+| portfolio | `specs/portfolio.json` | 持仓数据 + 总览 | ✅ |
+| watchlist | `specs/watchlist.json` | 自选股管理 | ✅ |
+| decisions | `specs/decisions.json` | 策略决策库 | ✅ |
+| market | `specs/market.json` | 市场观察数据 | ✅ |
+| signals | `specs/signals.json` | 信号 + 小果扫描 | ✅ |
+| evaluation | `specs/evaluation.json` | 策略评估 | ✅ |
+| dashboard | `specs/dashboard.json` | Dashboard 自身 | ✅ |
+| health | `specs/health.json` | 健康监控管线 | ✅ |
+| price_monitor | `specs/price_monitor.json` | 价格监控 cron | 📋 |
+| strategy_lifecycle | `specs/strategy_lifecycle.json` | 策略生命周期 | 📋 |
+
+> 状态: ✅ = spec 已完成 | 📋 = 待编写
+
+---
+
+## 二、验证闭环
+
+```
+┌────────────┐     ┌──────────┐     ┌──────────┐
+│ G: 规范体系 │────→│ K: 测试  │────→│ F: 健康  │
+│ 定义期望    │     │ 验证实现  │     │ 持续监控  │
+└────────────┘     └──────────┘     └──────────┘
+       ↑                ↑                │
+       └────────────────┼────────────────┘
+                        │
+               ┌────────┴────────┐
+               │ F 异常 → 触发 K  │
+               │ K 失败 → 更新 G │
+               └─────────────────┘
+```
+
+### 核心反馈链路
+
+| 方向 | 触发条件 | 动作 |
+|------|---------|------|
+| G → K | 新增/修改 spec | 对应测试 ID 必须新增/更新 |
+| K → F | 测试全部通过 | F Tab 组件标记为已验证 |
+| **F → K** | **F Tab 发现异常** | 触发对应测试重跑，确认是服务故障还是测试过期 |
+| **F → G** | **F Tab 持续异常但测试通过** | 期望矩阵或 spec 过时，应更新 G 和对应 spec |
+
+### F — 系统健康度（Dashboard F Tab）
+
+- **期望矩阵**：应该运行的服务 vs 实际状态
+- **监控数据**：Tier1（5min）/ Tier2（日报）作为实时状态输入
+- **服务拓扑**：所有服务的健康、端口状态
+- **?§ 覆盖**：F Tab 中的每条服务必须有对应的 ?（human_help）和 §（ai_spec）按钮
+
+---
+
+## 三、开发流程
+
+### 新增功能流程
+
+```
+确定模块边界
+  │
+  ├─ 1. 创建 specs/{module}.json
+  │      human_help + ai_spec
+  │
+  ├─ 2. 实现功能代码
+  │      包含 /health 端点 + PID 锁（proc_guard）
+  │
+  ├─ 3. 注册到系统
+  │      - 端口注册
+  │      - 添加到期望矩阵（F Tab 自动检测）
+  │
+  ├─ 4. 编写测试
+  │      - ai_spec.tests 添加对应测试标识
+  │
+  ├─ 5. 同步更新 Spec
+  │      - 将 specs/{module}.json 更新为与实际实现一致
+  │
+  └─ 6. 提交 → 部署 → 验证
+```
+
+### 修改已有功能流程
+
+```
+识别要修改的模块（查看模块清单确定 module 名）
+  │
+  ├─ 1. 读 specs/{module}.json
+  │      重点读 ai_spec：apis / constraints / dependencies / must_not
+  │
+  ├─ 2. 确认理解
+  │      - 如果 spec 描述与代码实际行为不一致，优先怀疑 spec 过期
+  │
+  ├─ 3. 修改功能代码
+  │      只改动需求直接涉及的部分，不顺手优化无关代码
+  │
+  ├─ 4. 同步更新 Spec
+  │
+  └─ 5. 提交 → 部署 → 验证
+```
+
+### Git 操作规范
+
+| # | 规则 | 说明 |
+|---|------|------|
+| 1 | 开工前必 pull | `git pull --rebase` |
+| 2 | 改完即 commit | 一个逻辑单元一次提交。禁止含密钥 |
+| 3 | 推前必拉 + 配代理 | push 前 `git pull --rebase`。远程操作前配 `:15000` 代理 |
+| 4 | trunk-based | 日常在 main。仅长周期大改开分支 |
+
+### 已有编码规范
+
+MoFin 已有的编码规范见 `docs/DEVELOPMENT_STANDARDS.md`，包含：
+- 代码结构（mo_models → mo_data → mofin_db 三层）
+- 数据规范（币种、汇率、数据源）
+- DB 规范（表设计、迁移）
+- LLM Prompt 规范
+- Cron 规范（独立运行、幂等性）
+- 测试要求（`run_all_tests.py`）
+
+以上规范与本文件互补，不冲突。本文件侧重"先 spec 后代码"和"通过 Dashboard 保证可见性"。
+
+---
+
+## 四、部署环境
+
+| 项目 | 值 |
+|------|-----|
+| **生产环境** | Linux 192.168.1.246 |
+| **代码目录** | `/home/hmo/MoFin/` |
+| **数据库** | `/home/hmo/web-dashboard/data/mofin.db`（SQLite） |
+| **Flask API** | `server.py` → `:8899` |
+| **Dashboard** | `dashboard.py` → `:5804`（新增） |
+| **Python** | 系统 Python 3 |
+
+---
+
+## 五、文档索引
+
+| 文档 | 用途 |
+|------|------|
+| `docs/dev-spec.md` | 本文件 — 开发规范（含五条红线） |
+| `docs/DEVELOPMENT_STANDARDS.md` | 编码规范（已有） |
+| `SYSTEM_ARCHITECTURE.md` | 系统架构（已有） |
+| `docs/cron-catalog.md` | Cron 任务清单（已有） |
+| `docs/DEPLOY.md` | 部署指南 |
+| `docs/QUICKSTART.md` | 快速操作 |
+| `docs/DASHBOARD.md` | Dashboard API 参考 |
+| `docs/HEALTH-PIPELINE.md` | 健康管线文档 |
+| `docs/learned.md` | 经验教训记录 |
+| `docs/decisions/` | 架构决策日志 |