docs: 文档重构 — 清理 AI agent 残留，整合 docs/ 目录结构

- 删除 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 - 修复所有过时引用和交叉链接
2026-08-22 11:56:40 +08:00
parent 6e1ac0c46b
commit 6acf938caf
34 changed files with 1191 additions and 3909 deletions
@@ -0,0 +1,148 @@
+# DJAPI — Django API 参考
+
+Django 5.2 项目，提供 A 股金融数据 API 和新闻联播视频处理能力。部署在 Linux 服务器上，通过 uWSGI + nginx 对外服务。
+
+---
+
+## 快速开始
+
+```bash
+# 开发服务器
+python manage.py runserver 0.0.0.0:8000
+
+# uWSGI 管理
+uwsgi --ini uwsgi.ini
+uwsgi --reload uwsgi.pid
+uwsgi --stop uwsgi.pid
+
+# API 文档
+# /api/docs/   - Swagger UI
+# /api/redoc/  - ReDoc
+# /api/schema/ - OpenAPI Schema
+```
+
+## 部署
+
+- 服务器：`simon@doorcome.cn`，路径 `/home/simon/myquant/djapi/`
+- uWSGI 监听 `127.0.0.1:5004`，nginx 反向代理
+- 虚拟环境：`/opt/miniconda/envs/django`（Python 3.10）
+- 域名：`api.doorcome.cn`、`echart.doorcome.cn`
+
+## 架构
+
+```
+djapi/
+├── djapi/                  # 项目配置
+│   ├── settings.py         # Django 设置、CORS、DRF
+│   ├── urls.py             # 根路由 + OpenAPI schema
+│   └── env_loader.py       # .env 加载器
+├── api/                    # 唯一 app
+│   ├── views.py            # 视图层（薄转发）
+│   ├── urls.py             # /api/* 路由
+│   ├── serializers.py      # DRF Serializer（13 个）
+│   ├── stock/              # 股票数据模块
+│   │   ├── data_source.py  # 统一数据入口（全局单例）
+│   │   ├── stock_utils.py  # 通用工具
+│   │   ├── stock_basic.py  # 日线行情、基本信息
+│   │   ├── getStockParam.py    # 个股参数
+│   │   ├── getStockEp.py       # TTM / 季度 EPS
+│   │   ├── getIndexs.py        # 指数行情
+│   │   ├── stockMargin.py      # 融资融券
+│   │   ├── getStockFina.py     # 财务报表分析
+│   │   ├── getStockDiv2.py     # 股息率计算
+│   │   └── xwlbDaily.py        # 新闻联播数据
+│   ├── video/               # 新闻联播视频处理（独立模块）
+│   └── report/              # 日报查询 API
+│       ├── query.py         # 数据库查询
+│       ├── views.py         # 2 个视图
+│       └── serializers.py   # OpenAPI 文档
+└── uwsgi.ini                # uWSGI 配置
+```
+
+## 所有 API 端点（16 个）
+
+基础 URL：`/api/`
+
+| 端点 | 参数 | 说明 |
+|------|------|------|
+| `stockbasic/` | tscode, start_date, end_date | 日线行情 |
+| `stockinfo/` | tscode | 个股基本信息 |
+| `stockparam/` | tscode, start_date, end_date | 个股参数（市值等） |
+| `industrys/` | industry | 按行业查股票列表 |
+| `indexByName/` | index_name | 按名称查指数 |
+| `indexDatas/` | tscode, start_date, end_date | 指数日行情 |
+| `stockep/` | tscode, start_date, end_date | TTM EPS |
+| `quarterlyEps/` | tscode, start_date, end_date | 季度 EPS |
+| `finance/` | tscode, start_date, end_date | 财务报表分析 |
+| `getdiv/` | tscode, start_date, end_date | 股息率（含 TTM） |
+| `dailymargin/` | trade_date, exchange_id | 每日融资融券汇总 |
+| `stockmargin/` | tscode, start_date, end_date | 个股融资融券 |
+| `xwlbNews/` | start_date, end_date | 新闻联播（原始文本） |
+| `xwlbFine/` | start_date, end_date | 新闻联播（AI 分割后） |
+| `news/reports/` | report_type, start_date, end_date, id | 日报查询 |
+| `news/events/` | days, importance, report_type, section, limit | 重要事件聚合 |
+
+### 数据源
+
+所有股票数据端点通过 `api/stock/data_source.py` 统一入口：
+- `get_tushare_pro()` — 全局单例（线程安全）
+- `get_daily()` — 双源 fallback (Tushare → AkShare)
+- `get_mysql_db()` — MySQL 全局单例
+
+## 日报查询 API
+
+### `GET /api/news/reports/`
+
+| 参数 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `report_type` | string | 两者 | `finance`（A 股）/ `intl`（国际） |
+| `start_date` | string | 24h 前 | `YYYY-MM-DD` |
+| `end_date` | string | 今天 | `YYYY-MM-DD` |
+| `id` | int | 无 | 指定 id 返回单份详情（含事件） |
+
+### `GET /api/news/events/`
+
+| 参数 | 类型 | 默认 | 范围 | 说明 |
+| --- | --- | --- | --- | --- |
+| `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 | 返回条数上限 |
+
+详细说明见 [news_report_api.md](news_report_api.md)。
+
+## 新闻联播视频处理
+
+离线批处理流水线：抓取视频 → 下载 → 提取音频 → ASR 转文字 → AI 分割+取标题 → 入库。
+
+```bash
+python api/video/main.py           # 定时任务入口
+python api/video/main_videos.py    # 批量补缺
+```
+
+### 模块文件
+
+| 文件 | 职责 |
+|------|------|
+| `getVideo5.py` | 主流程：抓取→下载→ASR→入库 |
+| `audioRead.py` | 音频转换、分割、ASR 识别、文本纠错 |
+| `deepseek.py` | DeepSeek API 封装 |
+| `newsProcess.py` | AI 新闻分割+标题提取 |
+| `newsRedo.py` | 手动重处理 |
+| `main.py` | 定时任务入口 |
+
+## 部署
+
+详见 [部署说明](deployment.md)。
+
+## 文档索引
+
+| 文档 | 内容 |
+|------|------|
+| [使用指南](usage.md) | 各模块使用方法和代码示例 |
+| [架构说明](architecture.md) | 项目架构、数据流、设计原则 |
+| [开发指南](development.md) | 环境搭建、开发约定 |
+| [部署说明](deployment.md) | 本地环境、服务器、uWSGI、rsync 部署 |
+| [日报查询 API](news_report_api.md) | news/reports + news/events 详细说明 |
+| [日报数据库](db_schema_v1.1.md) | news_report / news_event 表结构 |