Simon
6acf938caf
- 删除 11 个残留文件: continuation.md, init_plan.md, reasonix.toml, djapi/continuation.md, djapi/.serena/, djapi/.claude/, djapi/.mcp.json, .claude/skills/, docs/usage.html, docs/db_schema.md, docs/report_db_design.md - 7 个 CLAUDE-*.md 移入 docs/ 并重命名去 CLAUDE- 前缀 - 新增 4 个文档: architecture.md, development.md, api.md, deployment.md - 重写 usage.md, README.md - 修复所有过时引用和交叉链接
248 lines
9.0 KiB
Markdown
248 lines
9.0 KiB
Markdown
# 日报查询 API 使用手册（news_report / news_event）
|
||
|
||
> 版本：v1.1 | 2026-08-03（已部署至生产 `api.doorcome.cn`）
|
||
> 数据表定义见 [db_schema_v1.1.md](db_schema_v1.1.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": {
|
||
"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 条事件）：
|
||
|
||
```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",
|
||
"sources": ["InvestingLive"],
|
||
"url": "https://www.investing.com/..."
|
||
}
|
||
]
|
||
```
|
||
|
||
> `sources` 为该新闻的**全部来源**（JSON 数组，字符串列表）；`source` 为主来源（单值）。多源事件（如同一新闻被多家媒体转载）时 `sources` 含多个元素；历史事件可能为 `null`。
|
||
|
||
### 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§ion=intl&limit=50'
|
||
|
||
# 最近 30 天 A 股日报的新闻联播板块重要事件
|
||
curl 'https://api.doorcome.cn/api/news/events/?days=30&report_type=finance§ion=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` 过滤展示。
|