myquant/djapi/CLAUDE.md

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 对外服务。

常用命令

# 开发服务器
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/ 是独立功能模块，默认不修改该目录下任何文件。仅当用户明确要求时才操作此目录。

注意事项

• config.py 中的 TS_TOKEN 和 deepseek.py/ai.py/audioRead.py 中的 API key、mysqlHandle.py 中的数据库密码均为硬编码 —— 生产环境应迁移到环境变量
• api/stock/ 下的模块支持两种导入方式（相对导入和绝对导入），这是为了兼容「作为 Django app 被调用」和「直接命令行运行脚本」两种场景
• api/video/ 模块设计为独立命令行运行，不依赖 Django 框架
• db.sqlite3 已提交到代码库，包含 Django admin 的用户数据