hmo/MoFin

Fork 0

Files

T

hmo b08bfa5d03 refactor: integrate dashboard into server.py :8899, remove standalone dashboard

2026-07-19 11:06:50 +08:00

7.5 KiB

Raw Blame History

MoFin 开发规范

版本: v1.0 | 更新: 2026-07-19 | 基于 AgentsMeeting 样板重构

📋 样板参考: AgentsMeeting TEMPLATE-GUIDE.md

五条红线

先读/写 Spec，再写代码 — 新增功能先写 spec 再实现；修改已有功能先读对应 spec 了解架构和约束再动手。没有 spec 的模块在 Dashboard 不可见，视为未完成
部署必验 — 部署后不打开 Dashboard F Tab 验证 = 部署未完成
不可见即不存在 — 组件不在 Dashboard 中显示 = 等于没部署。离线不告警 = 监控缺陷
实现后同步 Spec — 每轮开发完毕后，必须将 specs/{module}.json 更新为与实际实现一致的状态。文档过期 = 等于没写
部署目标即验收标准 — 所有代码必须以部署目标环境（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 字段标准

{
  "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）
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/`	架构决策日志

7.5 KiB Raw Blame History Unescape Escape