From 06e59f3d9c7eff87c7ce34df0793c081d982cfce Mon Sep 17 00:00:00 2001
From: hmo <staymo7777@gmail.com>
Date: Sun, 19 Jul 2026 11:18:00 +0800
Subject: [PATCH] feat: add prompts and reports module specs (10 specs total)

---
 specs/prompts.json | 60 ++++++++++++++++++++++++++++++++++++++++++++++
 specs/reports.json | 43 +++++++++++++++++++++++++++++++++
 2 files changed, 103 insertions(+)
 create mode 100644 specs/prompts.json
 create mode 100644 specs/reports.json

diff --git a/specs/prompts.json b/specs/prompts.json
new file mode 100644
index 00000000..51830431
--- /dev/null
+++ b/specs/prompts.json
@@ -0,0 +1,60 @@
+{
+  "module": "prompts",
+  "version": "1.0",
+  "purpose": "LLM 提示词版本管理系统。管理知微使用的所有 LLM prompt，支持版本历史、效果追踪和 A/B 测试。",
+
+  "human_help": {
+    "title": "提示词管理",
+    "description": [
+      "集中管理 MoFin 系统中知微 LLM 使用的所有提示词模板。",
+      "每个提示词支持多版本管理，可以激活/回滚/废弃版本。",
+      "内置效果追踪：记录每个提示词版本被调用时的成功率和关联策略数。"
+    ],
+    "usage": [
+      "GET /api/prompts — 获取所有提示词列表（含当前版本和版本数）",
+      "GET /api/prompts/<id> — 获取单个提示词的完整信息（含所有版本和历史）",
+      "POST /api/prompts — 创建新提示词",
+      "POST /api/prompts/<id>/versions — 添加新版本",
+      "POST /api/prompts/<id>/activate — 激活指定版本",
+      "GET /api/prompts/effectiveness — 获取各版本有效性统计",
+      "GET /api/prompts/report — 获取版本有效性报告",
+      "GET /api/prompts/associations/<code> — 获取某股票关联的提示词"
+    ],
+    "troubleshooting": [
+      "提示词列表为空 → 运行 init_registry.py 初始化注册表",
+      "版本激活不生效 → 检查版本号是否存在，确认不是已废弃状态"
+    ]
+  },
+
+  "ai_spec": {
+    "apis": [
+      {"method": "GET", "path": "/api/prompts", "returns": "{prompts[{id, name, category, current_version, versions[]}], categories{}}"},
+      {"method": "GET", "path": "/api/prompts/<id>", "returns": "{prompt{...}, version_history[{version, label, status, created_at, changelog}]}"},
+      {"method": "POST", "path": "/api/prompts", "returns": "{status:'ok', prompt_id}"},
+      {"method": "POST", "path": "/api/prompts/<id>/versions", "returns": "{status:'ok', version}"},
+      {"method": "POST", "path": "/api/prompts/<id>/activate", "returns": "{status:'ok'}"},
+      {"method": "GET", "path": "/api/prompts/stats", "returns": "统计信息"},
+      {"method": "GET", "path": "/api/prompts/effectiveness", "returns": "各版本成功率统计"},
+      {"method": "GET", "path": "/api/prompts/report", "returns": "{report: 版本有效性报告文本}"},
+      {"method": "GET", "path": "/api/prompts/associations/<code>", "returns": "股票关联的提示词列表"}
+    ],
+    "dependencies": [
+      "prompt_manager/init_registry.py — 初始化提示词注册表",
+      "prompt_manager/registry.py — 提示词注册管理",
+      "prompt_manager/models.py — 数据模型",
+      "prompt_manager/tracking.py — 效果追踪",
+      "prompt_manager/analytics.py — 分析统计"
+    ],
+    "constraints": [
+      "提示词内容必须遵守 DEVELOPMENT_STANDARDS.md 中的 LLM Prompt 规范",
+      "不引用 JSON 文件名（S1规则）",
+      "港股价格标注 (HKD)（S2规则）",
+      "不在 prompt 里硬编码路径（S5规则）"
+    ],
+    "related_files": [
+      "prompt_manager/dashboard_views.py — API 路由",
+      "prompt_manager/init_registry.py — 注册表初始化",
+      "docs/DEVELOPMENT_STANDARDS.md — Prompt 规范"
+    ]
+  }
+}
diff --git a/specs/reports.json b/specs/reports.json
new file mode 100644
index 00000000..3e30fdc3
--- /dev/null
+++ b/specs/reports.json
@@ -0,0 +1,43 @@
+{
+  "module": "reports",
+  "version": "1.0",
+  "purpose": "分析报告管理。存储和查询 MoFin 系统生成的各类分析报告（盘中/盘后/周报等）。",
+
+  "human_help": {
+    "title": "报告管理",
+    "description": [
+      "MoFin 系统自动生成的分析报告存档。",
+      "报告存储在 data/reports/ 目录下，每条报告为一个 JSON 文件。",
+      "支持按类型筛选：盘中、盘后、周报等。"
+    ],
+    "usage": [
+      "GET /api/reports — 获取最近 100 条报告列表（含标题、类型、摘要）",
+      "GET /api/report/<id> — 获取单条报告完整内容（支持前缀匹配）",
+      "POST /api/update/report — 上传/更新报告"
+    ],
+    "troubleshooting": [
+      "报告列表为空 → 确认 cron 任务（开盘简报/收盘简报/策略评估）是否正常运行",
+      "报告ID找不到 → 检查 reports/ 目录下的 JSON 文件名"
+    ]
+  },
+
+  "ai_spec": {
+    "apis": [
+      {"method": "GET", "path": "/api/reports", "returns": "[{id, title, type, created_at, summary}] — 最近 100 条报告"},
+      {"method": "GET", "path": "/api/report/<id>", "returns": "报告完整 JSON 内容（支持前缀匹配）"},
+      {"method": "POST", "path": "/api/update/report", "returns": "{status:'ok', id}"}
+    ],
+    "dependencies": [
+      "data/reports/ — 报告 JSON 文件存储目录",
+      "cron: 开盘简报 (9:35) / 收盘简报 (16:10) / 策略评估 (21:00) — LLM Cron"
+    ],
+    "constraints": [
+      "报告 ID 前缀匹配：先精确查找 {id}.json，再按前缀匹配",
+      "报告类型：盘中/盘后/周报/其他"
+    ],
+    "related_files": [
+      "server.py — /api/reports, /api/report/<id>, /api/update/report",
+      "docs/cron-catalog.md — LLM Cron 调度说明"
+    ]
+  }
+}