myquant/docs/news_report_api.md

日报查询 API 使用手册（news_report / news_event）

版本：v1.1 | 2026-08-03（已部署至生产 api.doorcome.cn） 数据表定义见 db_schema_v1.1.md。 本文档为前端/调用方对接手册：两个只读查询接口的线上地址、参数、curl 用法与返回结构。

---

0. 快速开始

两个接口均已上线，直接可用：

https://api.doorcome.cn/api/news/reports/   # ① 日报查询
https://api.doorcome.cn/api/news/events/    # ② 重要事件聚合

最快体验（浏览器或 curl 打开）：

# 最近 24 小时有哪些日报（每天每类型一份）
curl 'https://api.doorcome.cn/api/news/reports/'

# 最近 7 天的重要事件（importance≥4）
curl 'https://api.doorcome.cn/api/news/events/'

Swagger 交互式文档（自动生成，含全部参数说明）：https://api.doorcome.cn/api/docs/（展开「日报」tag）。

部署信息（维护用）

• 代码位置：服务器 simon@doorcome.cn:/home/simon/myquant/djapi/api/report/
• 数据库：doorcome 本机 MariaDB myquant 库，表 news_report + news_event（news_ 前缀）
• 连接配置：服务器 djapi/.env 的 NEWS_DB_*（复用 MYSQL_* 同库同用户；密码必填，缺失时接口直接 500）
• 数据量（2026-08-03 实测）：news_report 180 行 / news_event 4372 条

---

1. 日报查询 — GET /api/news/reports/

参数（全部可选）

参数	类型	默认	说明
report_type	string	两者	日报类型：finance（A 股）/ intl（国际）
start_date	string	当前时间往前 24 小时	起始日期 YYYY-MM-DD
end_date	string	今天	结束日期 YYYY-MM-DD
id	int	无	日报 id；指定时返回单份详情（含事件）

返回

未传 id → 日报列表（数组）。每天每类型只返回最新一份（按 generated_at 取 MAX），仅主表字段，不带事件。真实返回（2026-08-03）：

[
  {
    "id": 182,
    "report_date": "2026-08-03",
    "report_type": "finance",
    "file_name": "",
    "generated_at": "2026-08-03T07:00:00",
    "ai_summary": "……（AI 摘要全文，按条目分行）",
    "stats": {
      "pipeline": {
        "raw_total": 116,
        "raw_total_24h": 116,
        "raw_by_source": { "经济观察网": 31, "新浪财经": 27, "证券时报": 28, "财联社": 15, "东方财富": 7, "中证券网": 2, "第一财经": 3, "中国证券网": 3 },
        "raw_by_source_24h": { ... },
        "proc": ..., "deduped": ..., "dups": ..., "emb_count": ..., "qdrant_count": ..., "cninfo_raw": ...
      },
      "news": {
        "total": 643,
        "hi_threshold": 4,
        "sentiments": { "neutral": 470, "positive": 123, "negative": 50 },
        "importances": { "1": 115, "2": 275, "3": 185, "4": 48, "5": 20 },
        "event_types": { "其他": 287, "国际局势": 107, "宏观政策": 62, "行业政策": 49, "财报披露": 29 }
      },
      "cninfo": { "total": 48, "hi_threshold": 2, "by_day": { "2026-08-06": 8, "2026-08-01": 9 }, "announcement": 47, "research": 1, "irm": 0 },
      "xwlb": { "total": 21, "date": "08月05日" }
    },
    "created_at": "2026-08-03T07:01:00"
  },
  {
    "id": 172,
    "report_date": "2026-08-03",
    "report_type": "intl",
    "file_name": "",
    "generated_at": "2026-08-03T07:00:00",
    "ai_summary": "……",
    "stats": {
      "pipeline": { "raw_total": 442, "processed": 442, "deduped": 111, "embedded": 112, "qdrant": 2952 },
      "importance": [
        { "importance": 2, "count": 2 }, { "importance": 3, "count": 31 },
        { "importance": 4, "count": 26 }, { "importance": 5, "count": 5 }
      ],
      "event_types": [
        { "event_type": "宏观经济", "count": 15 }, { "event_type": "地缘政治", "count": 12 },
        { "event_type": "财报披露", "count": 9 }, { "event_type": "央行决议", "count": 7 }
      ],
      "source_dist": [
        { "source": "InvestingLive", "count": 30 }, { "source": "MarketWatch", "count": 3 },
        { "source": "CNBC", "count": 3 }, { "source": "Yahoo Finance", "count": 1 }
      ]
    },
    "created_at": "2026-08-03T07:01:00"
  }
]

stats 为 JSON 快照（示例为 2026-08-06 真实数据）：finance 含 pipeline/news/cninfo/xwlb，intl 含 pipeline/importance/event_types/source_dist（另有 sentiment）。finance 与 intl 的 pipeline 内部 key 集不同（finance: raw_total/raw_by_source/proc/dups/...；intl: raw_total/processed/deduped/embedded/qdrant），前端按 key 防御性读取；各数字口径（raw_total ≠ news.total 等）见 db_schema_v1.1.md §3.1。

传 id → 单份详情（对象），增加 events 数组（按 section, rank 排序）。真实返回（id=182，58 条事件）：

{
  "id": 182,
  "report_date": "2026-08-03",
  "report_type": "finance",
  "file_name": "",
  "generated_at": "2026-08-03T07:00:00",
  "ai_summary": "……",
  "stats": { ... },
  "created_at": "2026-08-03T07:01:00",
  "events": [
    {
      "id": 3001,
      "section": "cninfo",
      "rank": 1,
      "importance": 3,
      "event_type": "公告",
      "title": "汇川技术：投资者关系活动记录表（2026年6月26日-7月24日）",
      "summary": "……",
      "sentiment": "neutral",
      "source": "cninfo",
      "url": "http://www.cninfo.com.cn/..."
    },
    {
      "id": 3002,
      "section": "xwlb",
      "rank": 1,
      "importance": 4,
      "event_type": "新闻联播",
      "title": "……",
      "summary": null,
      "sentiment": "positive",
      "source": null,
      "url": null
    }
  ]
}

section 取值：xwlb=新闻联播 / news=财经新闻 / cninfo=公告调研（finance 日报）；intl 日报只有 intl 板块。

curl 示例

# 默认：最近 24 小时内的日报列表
curl 'https://api.doorcome.cn/api/news/reports/'

# 指定类型 + 日期范围
curl 'https://api.doorcome.cn/api/news/reports/?report_type=finance&start_date=2026-08-01&end_date=2026-08-03'

# 单份详情（含全部事件）
curl 'https://api.doorcome.cn/api/news/reports/?id=182'

---

2. 重要事件聚合 — GET /api/news/events/

跨日报检索最近 N 天的重要事件（importance 达到阈值），按重要度、日期降序。

参数（全部可选）

参数	类型	默认	范围	说明
days	int	7	1~365	最近 N 天
importance	int	4	1~5	最低重要度
report_type	string	两者	finance/intl	日报类型过滤
section	string	全部	xwlb/news/cninfo/intl	板块过滤
limit	int	100	1~500	返回条数上限

返回

事件数组，每条含所属日报信息。真实返回（intl 过滤后）：

[
  {
    "report_date": "2026-08-03",
    "report_type": "intl",
    "id": 7501,
    "section": "intl",
    "rank": 1,
    "importance": 5,
    "event_type": "地缘政治",
    "title": "特朗普称已取消对伊朗的袭击计划，因双方就协议框架达成一致",
    "summary": "……",
    "sentiment": "neutral",
    "source": "InvestingLive",
    "sources": ["InvestingLive"],
    "url": "https://www.investing.com/..."
  }
]

sources 为该新闻的全部来源（JSON 数组，字符串列表）；source 为主来源（单值）。多源事件（如同一新闻被多家媒体转载）时 sources 含多个元素；历史事件可能为 null。

curl 示例

# 最近 7 天的重要事件（默认 importance≥4）
curl 'https://api.doorcome.cn/api/news/events/'

# 最近 3 天、只看国际日报、最高重要度、最多 50 条
curl 'https://api.doorcome.cn/api/news/events/?days=3&report_type=intl&section=intl&limit=50'

# 最近 30 天 A 股日报的新闻联播板块重要事件
curl 'https://api.doorcome.cn/api/news/events/?days=30&report_type=finance&section=xwlb&importance=4'

---

3. 错误处理

场景	HTTP 状态	响应体
参数校验失败（非法 report_type/section/日期格式/数值越界）	400	{"error": "说明"}
id 指定的日报不存在	404	{"error": "日报 id=xxx 不存在"}
数据库不可达 / NEWS_DB_PASSWORD 缺失 / 查询异常	500	{"error": "查询失败: ..."}

# 验证错误处理
curl -i 'https://api.doorcome.cn/api/news/reports/?id=999999'   # → 404
curl -i 'https://api.doorcome.cn/api/news/events/?section=foo'  # → 400

---

4. 接口约定

• 只读：无任何写操作；SQL 全部参数化，无拼接注入面。
• 日期：统一 YYYY-MM-DD；时间字段为 ISO 字符串。
• 幂等：同一份日报重复生成会覆盖（file_name='' 每天每类型仅一行），列表按 generated_at 取最新，前端无需去重。
• 默认窗口：日报列表默认返回"当前时间往前 24 小时"；事件聚合默认最近 7 天。
• 板块差异：finance 日报含 xwlb+news+cninfo；intl 日报仅 intl。按 section 过滤展示。