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

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

---

## 0. 快速开始

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

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

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

```bash
# 最近 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）：

```json
[
  {
    "id": 182,
    "report_date": "2026-08-03",
    "report_type": "finance",
    "file_name": "",
    "generated_at": "2026-08-03T07:00:00",
    "ai_summary": "……（AI 摘要全文，按条目分行）",
    "stats": {
      "pipeline": { "M1": 210, "M2": 205, "M3": 198, "M4": 190, "M5": 188, "M6": 180 },
      "sources": { "cls": 95, "eastmoney": 60, "other": 25 },
      "news": { "total": 180, "hi_threshold": 18, "sentiments": {...}, "importances": [...], "event_types": [...] },
      "cninfo": { "total": 58, "hi_threshold": 4, "by_day": {...}, "announcement": 40, "research": 15, "irm": 3 },
      "xwlb": { "total": 28, "date": "2026-08-03" }
    },
    "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": { "M1": 150, "M2": 145, "M3": 140, "M4": 135, "M5": 130, "M6": 125 },
      "sentiment": [...],
      "importance": [{ "重要度": 5, "数量": 3 }, { "重要度": 4, "数量": 12 }],
      "event_types": [{ "事件类型": "地缘政治", "数量": 8 }],
      "source_dist": [{ "来源": "investinglive.com", "文章数": 45 }]
    },
    "created_at": "2026-08-03T07:01:00"
  }
]
```

> `stats` 为 JSON 快照：finance 含 `pipeline/sources/news/cninfo/xwlb`，intl 含 `pipeline/sentiment/importance/event_types/source_dist`。前端按 key 防御性读取（见 db_schema.md §3）。

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

```json
{
  "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 示例

```bash
# 默认：最近 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 过滤后）：

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

### curl 示例

```bash
# 最近 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": "查询失败: ..."}` |

```bash
# 验证错误处理
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` 过滤展示。