simonandClaude Opus 4.7
eedead0d41
- 升级 ECharts 到 5.4.2，重构 lib/ 目录结构 - 新增 DataTables 2.x 和 FixedColumns 插件 - 新增 quant/ 宏观研究报告模块 - 重构图表页面：stock_trend、hkholdbycode 等采用 JS fetch API.doorcome.cn 模式 - 新增 CLAUDE.md 补充页面文档和新数据流说明 - 更新 inc/config.php TuShare API 配置 - 更新新闻联播分析模块 news/ 和相关研究报告 research/ - 新增 api_document/ 参考文档 - 清理 .gitignore，排除 uploads/xls/.mcp.json/ source maps 等非代码文件 - 所有 PHP 文件通过 php -l 语法检查 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
184 lines
9.3 KiB
Markdown
184 lines
9.3 KiB
Markdown
# CLAUDE.md
|
||
|
||
本文件为 Claude Code（claude.ai/code）在本仓库中工作提供指引。
|
||
|
||
## 项目概览
|
||
|
||
基于 PHP 的 A 股金融数据可视化和宁波房地产数据分析平台。使用 ECharts 生成交互式图表，后端为 MySQL 数据库和 TuShare API。
|
||
|
||
## 技术栈
|
||
|
||
- **后端**: PHP（无框架），Composer 管理依赖（`phpoffice/phpspreadsheet`、`monolog/monolog`）
|
||
- **前端**: ECharts 4.x、jQuery、Tailwind CSS 3.4（CDN 引入）、DataTables、Font Awesome
|
||
- **数据库**: MySQL，通过 `mysqli` 连接——统一使用 `inc/config.php` 中的 `get_mysqli_connection()` 获取连接
|
||
- **外部 API**: TuShare（`api.tushare.pro` 和 `api.waditu.com`），用于获取财务数据
|
||
- **调试**: XDebug，端口 9000（配置见 `.vscode/launch.json`）
|
||
|
||
## 无构建步骤
|
||
|
||
传统 PHP 应用，没有构建/检查/测试流水线。文件直接部署到 Web 服务器。运行于 `echart.doorcome.cn`。每个 `.php` 文件是独立的入口点，没有路由机制。Composer autoload 在部分文件中使用（引入 `vendor/autoload.php`）。
|
||
|
||
## 架构
|
||
|
||
### 核心 includes（`inc/`）
|
||
|
||
- `config.php` — 数据库连接工厂（`get_mysqli_connection()`），所有 DB 操作统一走此函数。另含 `db_query()` 参数化查询函数和 `jsonResponse()` 统一 JSON 响应函数。
|
||
- `getData.inc.php` — 指数数据、机构持仓（IH）、资金流向（沪深港通南北向）、个股历史查询。
|
||
- `getBasic.inc.php` — PE/PB/PS 历史、股价历史、市值数据、TuShare API 封装、日期工具、数据查询函数。HTML 渲染函数已拆分至 `widgets.inc.php`。
|
||
- `widgets.inc.php` — HTML 组件函数：`tradeStocksList()`、`vendorList()`、`yearList()`、`yearToname()`。
|
||
- `functions.inc.php` — 共享表单组件（districtList、indexList、seList、byDM）和 `callTushareApi()` 辅助函数。
|
||
- `ajax.inc.php` — 所有 AJAX 端点，通过 `$_REQUEST['t']` 分发：股票列表、财务数据（调用 `getFinanceData.class.php`）、房地产成交/挂牌查询。业务函数（`esfTradeDaily`、`esfListDaily`）已迁移至 `getEstate.inc.php`。
|
||
- `getFinanceData.class.php` — `getFinance` 类，调用 TuShare API 获取财务报表数据。
|
||
- `tradeRec.inc.php` — 交易记录查询（`trade_record` / `trade_record_cj` 表）。
|
||
- `excelOperate.inc.php` — 通过 PhpSpreadsheet 读取 Excel/CSV 文件。
|
||
- `postJson.inc.php` — 使用 cURL 发送 JSON HTTP POST 请求。
|
||
- `getEstate.inc.php` — 房地产相关数据查询（`estate_listing` 表）及二手房成交/挂牌数据函数。
|
||
- `upload.php` — 文件上传处理。
|
||
- `plansetup.php` — 用于 Composer autoload 的快捷入口（`__DIR__."/../vendor/autoload.php"`）。
|
||
|
||
### 页面结构
|
||
|
||
根目录及 `charts/` 下的每个 `.php` 文件渲染一个独立的数据视图，存在两种数据获取模式：
|
||
|
||
**模式 A（传统——服务端注入）：**
|
||
1. 引入所需的 `inc/*.php`
|
||
2. 通过 `$_REQUEST` 接收查询参数
|
||
3. PHP 查询数据库，将结果通过 `json_encode()` 注入 `<script>` 标签内的 `window.chartConfig`
|
||
4. 引入对应的 `js/*.js`，JS 读取 `window.chartConfig` 后用 `echarts.init()` 渲染
|
||
5. 引入 `html/head.php` 和 `html/footer.php` 组成页面布局
|
||
|
||
**模式 B（较新——JS fetch 调用外部 API）：**
|
||
1. 页面直接加载 JS，不注入数据
|
||
2. JS 在 `$(document).ready` 中通过 `fetch()` 调用 `https://api.doorcome.cn/api/*` 获取数据
|
||
3. 渲染逻辑与模式 A 相同
|
||
4. 代表页面：`stock_trend.php`、`stockdiv.php`、`stockep.php`、`stockmargin.php`、`hkholdbycode.php`
|
||
|
||
### 页面目录
|
||
|
||
根目录保留入口文件（`index.php`、`index-2.php`、`phpinfo.php`），其余页面文件均位于 `charts/` 子目录。
|
||
|
||
| 文件 | 用途 |
|
||
|------|------|
|
||
| `index.php` | 原导航页，重定向至 `index-2.php` |
|
||
| `index-2.php` | 主导航门户（Tailwind 风格） |
|
||
| `charts/stock_trend.php` | 股价 VS PE/PB/PS 趋势 |
|
||
| `charts/stockep.php` | 股价 VS 盈利能力 |
|
||
| `charts/stockdiv.php` | 股价 VS 股息率 |
|
||
| `charts/stockmargin.php` | 股价 VS 融资融券余额 |
|
||
| `charts/hkholdbycode.php` | 股价 VS 北向资金持股 |
|
||
| `charts/stock_ih.php` | 股价 VS 机构持仓趋势 |
|
||
| `charts/stockkeydata.php` | 个股基本面数据 |
|
||
| `charts/index_trend.php` | 指数 VS PE/PB/PS/市值 |
|
||
| `charts/index_ih.php` | 指数 VS 机构持仓趋势 |
|
||
| `charts/index_mv_all.php` | 指数 VS 两市总市值 |
|
||
| `charts/index_margin.php` | 指数 VS 融资余额 |
|
||
| `charts/moneyflow.php` | 指数 VS 沪深港通资金流向 |
|
||
| `charts/realestate.php` | 房地产挂牌数量趋势（宁波） |
|
||
| `charts/estateNewTradeDaily.php` | 新房每日成交量（宁波） |
|
||
| `charts/estateTradeDaily.php` | 二手房每日成交量（宁波） |
|
||
| `charts/estateListDaily.php` | 二手房每日挂牌量（宁波） |
|
||
| `charts/stockTradeRecord.php` | 个人股票交易记录 |
|
||
| `charts/chartStDetail.php` | 个股详细图表 |
|
||
| `charts/chartSix.php` | 个股 VS 机构持仓（持股数/金额/比例） |
|
||
| `charts/chartThree.php` | 指数 VS 机构持仓（分类型：基金/QFII/社保等） |
|
||
|
||
### JavaScript 约定
|
||
|
||
每个页面加载 `js/` 中对应的 JS 文件（如 `chartStDetail.js`、`renderCharts.js`、`estate.js`）。新版页面通过 `window.chartConfig` 对象传递数据，旧版页面正逐步迁移至此模式。ECharts 库统一使用 `lib/echarts/5.4.2/echarts.js`（v5）。
|
||
|
||
### 子模块
|
||
|
||
- `news/` — 独立的新闻抓取/分析模块，面向 CCTV 新闻联播。包含自己的 PHP、JS 和设计文档。
|
||
- `research/` — 股票研究报告（HTML 和 PDF）、行业分析，含 AI 生成的研究内容。
|
||
- `quant/` — 宏观研究报告模块，基于 PHP + Tailwind CSS，数据存储在 `mac_report` 表中。
|
||
- `api_document/` — Hailo 平台 API 参考文档（TXT 格式，非本项目核心内容）。
|
||
- `deprecated/` — 已废弃的旧版页面和脚本，仅供参考。
|
||
|
||
### 前端库位置
|
||
|
||
- `lib/` — jQuery、DataTables、ECharts 5.4.2
|
||
- `libai/` — Chart.js、anime.js、shader-park-core（AI/研究页面使用）
|
||
- `js/` — 页面专属图表逻辑、Tailwind CSS 3.4.17、ECharts GL、ecStat
|
||
- `css/` — 自定义样式（`style.css`、`css2.css`）、Font Awesome
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
# PHP 语法检查（修改文件后必做）
|
||
php -l inc/ajax.inc.php
|
||
php -l charts/stock_trend.php
|
||
|
||
# Composer 依赖管理
|
||
composer update # 更新依赖
|
||
composer dump-autoload # 更新 autoload
|
||
|
||
# 部署到远程服务器（~/.bashrc 中定义）
|
||
sync-echart -n # 预览（dry-run）
|
||
sync-echart # 执行同步部署到 www.doorcome.cn
|
||
|
||
# 批量 PHP 语法检查（修改多个文件后）
|
||
for f in charts/*.php; do php -l "$f"; done
|
||
for f in inc/*.php; do php -l "$f"; done
|
||
```
|
||
|
||
## 代码风格约定（来自 AGENTS.md）
|
||
|
||
- 缩进使用 Tab
|
||
- SQL 查询使用 heredoc 语法
|
||
- PHP 标签使用 `<?=` 和 `<?php` 短标签
|
||
- 中文注释，简洁为主，解释业务逻辑而非代码本身
|
||
- 不加 docblock
|
||
- 避免使用 PHP 8.1+ 特有特性（enum、readonly 等），需兼容 PHP 7.x
|
||
|
||
## 服务器与部署
|
||
|
||
应用运行于 `echart.doorcome.cn`。所有用户输入通过 `$_REQUEST` 读取——GET 和 POST 统一处理。无认证或 CSRF 防护。数据库凭据在 `inc/config.php` 中。
|
||
|
||
TuShare API Token 统一定义在 `inc/config.php` 的 `TUSHARE_API_TOKEN` 常量中。
|
||
|
||
部署到远程服务器使用 `sync-echart` 命令（定义在 `~/.bashrc` 中），自动排除 `.git`、`.vscode`、`.claude`、`.files`。
|
||
|
||
```bash
|
||
sync-echart -n # 先预览
|
||
sync-echart # 执行部署
|
||
```
|
||
|
||
服务器路径：`simon@www.doorcome.cn:/var/www/html/echart/`
|
||
|
||
## 多文件修改规范
|
||
|
||
修改多个文件前，先输出：
|
||
|
||
- **涉及文件** — 列出所有将被修改的文件
|
||
- **修改原因** — 每个文件为什么需要改
|
||
- **潜在影响** — 可能破坏什么，哪些消费者会受影响
|
||
|
||
修改完成后，输出：
|
||
|
||
- **已完成列表** — 每个文件的具体变更内容
|
||
- **验证步骤** — 确认正确性的步骤（语法检查、页面访问测试等）
|
||
|
||
## 风险意识
|
||
|
||
- 本项目**没有自动化测试**，所有变更需手动验证。
|
||
- 跨层修改（如 AJAX 响应格式、JS 全局变量、PHP 引入路径）属于**高风险操作**——修改前必须追踪所有消费者，并明确说明风险后再动手。
|
||
- 修改 AJAX 响应格式时，需同时检查 PHP 端消费者（服务端数据组装）和 JS 端消费者（`$.ajax` success 回调、`getRows()` 调用、DataTables 配置）。
|
||
- 修改 JS 全局变量名时，需检查所有引用这些变量的 `.js` 文件，而非仅检查注入变量的 PHP 页面。
|
||
- `deprecated/` 目录的文件可更新路径以保持一致性，除此之外不要改动。
|
||
|
||
## 批量脚本注意事项
|
||
|
||
用 Python/sed 对大量文件做机械性修改（路径前缀替换、变量重命名）可以接受，但需：
|
||
|
||
- 运行脚本前先列出将要影响的文件清单
|
||
- 脚本运行后，用 grep 搜索旧模式确认无遗漏
|
||
- 对每个修改过的 PHP 文件执行 `php -l` 语法检查
|
||
|
||
## Checkpoint
|
||
|
||
当用户说 "checkpoint" 时，在项目根目录生成 `continuation.md`，包含：
|
||
|
||
- **当前状态**：刚刚完成了什么、改了哪些文件、结果如何
|
||
- **后续步骤**：具体有序的下一步行动
|
||
- **待解决问题**：未解决的疑问、已知限制或需要决策的事项
|