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 - 修复所有过时引用和交叉链接
106 lines
5.5 KiB
Markdown
106 lines
5.5 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## 项目概述
|
||
|
||
djapi 是一个 Django 5.2 项目，提供金融数据 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 # 停止
|
||
|
||
# 数据库操作（Django ORM 主要用于 admin，业务数据走 MySQL）
|
||
python manage.py makemigrations
|
||
python manage.py migrate
|
||
python manage.py createsuperuser
|
||
|
||
# API 文档地址
|
||
# /api/docs/ - Swagger UI
|
||
# /api/redoc/ - ReDoc
|
||
# /api/schema/ - OpenAPI Schema
|
||
|
||
# 视频处理脚本（独立运行，非 Django 管理）
|
||
python api/video/main.py
|
||
```
|
||
|
||
## 架构
|
||
|
||
### Django 层（薄）
|
||
|
||
- 项目只有一个 app：`api`
|
||
- views.py 仅做路由转发，每个 view 函数接收请求参数后直接调用 `api/stock/` 下的业务函数
|
||
- Django ORM 基本未使用（sqlite3 仅用于 admin），所有业务数据走 MySQL（通过 `mysqlHandle.py` 直连）
|
||
- DRF + drf_spectacular 已配置但 API 视图仍沿用原生 `JsonResponse`，未使用 DRF ViewSet/Serializer
|
||
|
||
### 子模块一：`api/stock/` — 股票数据
|
||
|
||
核心依赖 **Tushare** 获取 A 股数据，数据流是「Tushare API → pandas DataFrame → Django JsonResponse」。
|
||
|
||
- **`config.py`**：全局配置，包括 TS_TOKEN、默认日期范围、行业列表、扫描阈值等
|
||
- **`stock_utils.py`**：通用工具集，包含 tscodeCheck（股票代码格式校验/补全后缀）、dataCorrect（NaN 填充）、dataMerge（按 ts_code+trade_date 合并 DataFrame）、viewFunc_tsCodeAndDate（通用 view 包装器：从 request 提取参数→调用 data_func→返回 JsonResponse）
|
||
- **`stock_basic.py`**：日线行情（daily）、个股基本信息（stock_basic）、按行业查股票列表
|
||
- **`getStockParam.py`**：个股技术参数（市值等）
|
||
- **`getStockEp.py`**：TTM EPS 和季度 EPS
|
||
- **`getIndexs.py`**：指数行情，支持按名称模糊查询指数代码
|
||
- **`stockMargin.py`**：融资融券数据
|
||
- **`getStockFina.py`**：`FinanceData` 类，按财报日期获取资产负债表+利润表+现金流量表，计算运营/资产/负债/回报率等指标
|
||
- **`getStockDiv2.py`**：`analyze_stock_dividend_and_price()` — 核心股息率计算。查分红记录→生成 TTM 分红序列→合并日线行情→计算 div_yield = cash_div_year/close，含毛刺平滑处理
|
||
- **`smoothBrush.py`**：滑动窗口中位数法检测并平滑毛刺数据
|
||
- **`divSearch.py`**：批量扫描全市场股息率，输出 CSV
|
||
- **`xwlbDaily.py`**：从 MySQL 查询新闻联播数据（`xwlb_daily` 和 `xwlb_daily_ext` 表）
|
||
- **`mysqlHandle.py`**：`MySQLDB` 类封装 mysql-connector，提供 insert/query/update 方法
|
||
|
||
### 子模块二：`api/video/` — 新闻联播视频处理
|
||
|
||
离线批处理流水线：**抓取视频 → 下载 → 提取音频 → ASR 转文字 → AI 分割+取标题 → 入库**。
|
||
|
||
- **`getVideo5.py`**：主流程。生成 CCTV 节目页 URL → 解析完整版视频链接 → yt-dlp 下载视频 → ffmpeg 提取 MP3 → 调用音频识别 → 写入 MySQL
|
||
- **`audioRead.py`**：音频处理。MP3→WAV 转换、智能静音分割、DashScope Paraformer ASR 识别、Qwen 文本纠错
|
||
- **`deepseek.py`**：`DeepSeekAPI` 类，带重试/降级机制的 DeepSeek API 封装
|
||
- **`ai.py`**：遗留的独立 AI 调用函数（deepseek_text, qwen_text），被 video 模块直接调用
|
||
- **`newsProcess.py`**：post-processing —— 从 MySQL 取出当天原始识别文本，调用 DeepSeek 分割为独立新闻+生成标题，写入 `xwlb_daily_ext` 表
|
||
- **`main.py`**：定时任务入口，每天执行 `process_videos(today, today)`
|
||
- **`wasted/`**：废弃的旧版视频抓取脚本
|
||
- **`xwlb_video/`**：下载的视频和音频文件（服务器上）
|
||
- **`mysqlHandle.py`**（video 子目录）：与 stock 子目录功能相同的数据库连接类
|
||
|
||
### URL 路由
|
||
|
||
所有 API 端点挂载在 `/api/` 下，由 `api/urls.py` 定义，共约 20 个端点，按功能分为：
|
||
- 股票基础：`stockbasic/`, `stockinfo/`, `stockparam/`, `industrys/`
|
||
- 财务数据：`finance/`, `stockep/`, `quarterlyEps/`
|
||
- 行情+指数：`indexByName/`, `indexDatas/`
|
||
- 融资融券：`dailymargin/`, `stockmargin/`
|
||
- 分红：`getdiv/`
|
||
- 新闻联播：`xwlbNews/`, `xwlbFine/`
|
||
|
||
大多数 API 接受 ts_code、start_date、end_date 三个通用参数，经由 `viewFunc_tsCodeAndDate()` 统一处理。
|
||
|
||
### 部署
|
||
|
||
- 服务器用户 `simon`，项目路径 `/home/simon/myquant/djapi/`
|
||
- uWSGI 监听 127.0.0.1:5004，通过 socket 与 nginx 通信
|
||
- 虚拟环境：`/opt/miniconda/envs/django`
|
||
- 静态文件已 collect 到 `static/`，由 nginx 直接服务
|
||
- 生产域名：`api.doorcome.cn`、`echart.doorcome.cn`
|
||
- CORS 已配置，允许跨域 cookie（SameSite=None）
|
||
|
||
## 开发约束
|
||
|
||
- `api/video/` 是独立功能模块，默认不修改该目录下任何文件。仅当用户明确要求时才操作此目录。
|
||
|
||
## 注意事项
|
||
|
||
- 所有密钥已迁移到环境变量，通过 `.env` 统一管理
|
||
- `api/stock/` 下的模块支持两种导入方式（相对导入和绝对导入），这是为了兼容「作为 Django app 被调用」和「直接命令行运行脚本」两种场景
|
||
- `api/video/` 模块设计为独立命令行运行，不依赖 Django 框架
|
||
- `db.sqlite3` 已提交到代码库，包含 Django admin 的用户数据
|