simon
8ea9b48a9a
- 新增 charts/news_reports.php 报告查询导航页（列表+详情一体，fetch API 渲染） - 新增 js/newsReports.js：AI 摘要/新闻联播/财经新闻/公告调研/数据总览固定模块，stats 归一化兼容多种格式 - index-2.php 研究报告卡片改为导航链接，移除 PHP 目录下拉框 - 更新 AGENTS.md/CLAUDE.md（路径、页面清单、数据模式等核实修正） - 同步服务器拉取的文档：quant 使用手册、podcast-docs - 生成 continuation.md 会话检查点
190 lines
11 KiB
Markdown
190 lines
11 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_json`、`estate_json_ext`、`estate_listing` 表）及二手房成交/挂牌数据函数（`esfTradeDaily`、`esfListDaily`）。
|
||
- `upload.php` — 文件上传处理。
|
||
- `plansetup.php` — 用于 Composer autoload 的快捷入口（`__DIR__."/../vendor/autoload.php"`）。
|
||
|
||
> 数据库表全量清单（16 张表、在用/未用/已由 API 替代状态）见根目录 `DB_REFERENCE.md`。
|
||
|
||
### 页面结构
|
||
|
||
根目录及 `charts/` 下的每个 `.php` 文件渲染一个独立的数据视图，存在三种数据获取模式：
|
||
|
||
**模式 A（服务端注入）：**
|
||
1. 引入所需的 `inc/*.php`，通过 `$_REQUEST` 接收查询参数
|
||
2. PHP 查询数据库，将结果通过 `json_encode()` 注入 `<script>` 标签内的 JS 变量
|
||
3. 引入对应的 `js/*.js` 渲染
|
||
4. 注意：`window.chartConfig` 全局变量**仅剩 `deprecated/` 在用**；活跃页面中 `charts/chartStDetail.php` 是变体（注入命名变量 `data1`…`data5`）
|
||
|
||
**模式 B（较新——JS fetch 调用外部 API）：**
|
||
1. 页面直接加载 JS，不注入数据
|
||
2. JS 在 `$(document).ready` 中通过 `fetch()` 调用 `https://api.doorcome.cn/api/*`（如 `stockparam`、`indexDatas`、`stockinfo`、`getdiv`、`stockep`、`stockmargin`、`stockbasic`）获取数据
|
||
3. 代表页面：`stock_trend.php`、`stockdiv.php`、`stockep.php`、`stockmargin.php`、`hkholdbycode.php`、`index_trend.php`、`index_mv_all.php`、`index_margin.php`
|
||
|
||
**模式 C（AJAX → `inc/ajax.inc.php`）：**
|
||
1. 页面 JS 用 `$.ajax` 调 `../inc/ajax.inc.php`，通过 `$_REQUEST['t']` 路由（if 链）：`stockList`、`financeData`、`esfTBD`、`esfListDaily`、`newTBD`、`moneyflowData`、`estateData`
|
||
2. 代表页面：`moneyflow.php`、`realestate.php`、`estateTradeDaily.php`、`estateListDaily.php`、`estateNewTradeDaily.php`、`stockkeydata.php`、`stockTradeRecord.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/stockkeydata.php` | 个股基本面数据 |
|
||
| `charts/index_trend.php` | 指数 VS PE/PB/PS/市值 |
|
||
| `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/myexcel.php` | 交易记录 Excel/CSV 导入处理（配合上传流程） |
|
||
| `charts/chartStDetail.php` | 个股详细图表（服务端注入命名变量 data1…data5） |
|
||
|
||
> 注：`stock_ih.php`、`index_ih.php`、`chartSix.php`、`chartThree.php` 及旧版 `stock_trend.php`/`index_trend.php`/`index_mv_all.php` 已移入 `deprecated/`，勿引用。
|
||
|
||
### JavaScript 约定
|
||
|
||
每个页面加载 `js/` 中对应的 JS 文件（如 `chartStDetail.js`、`renderCharts.js`、`pubfunc.js`、`adj.ajax.js`）。新式图表页面复用 `js/renderCharts.js`（`doubleLineChart()` 等）和 `js/pubfunc.js`（`getRows()`、`hideSwitch()` 等）。ECharts 库统一从 `/lib/js/echarts-5.4.2.js`（v5）引用。`window.chartConfig` 传递模式仅存于 `deprecated/`。
|
||
|
||
### 子模块
|
||
|
||
- `news/` — 独立的新闻抓取/分析模块，面向 CCTV 新闻联播。包含自己的 PHP、JS 和设计文档。
|
||
- `research/` — 股票研究报告（HTML 和 PDF）、行业分析，含 AI 生成的研究内容。
|
||
- `quant/` — 宏观研究报告模块，基于 PHP + Tailwind CSS，数据存储在 `mac_report` 表中。
|
||
- `api_document/` — Hailo 平台 API 参考文档（TXT 格式，非本项目核心内容）。
|
||
- `deprecated/` — 已废弃的旧版页面和脚本，仅供参考。
|
||
|
||
### 前端库位置
|
||
|
||
- `lib/js/` — jQuery 3.6.0、DataTables 1.13.4、ECharts 5.4.2（`echarts-5.4.2.js`）、ECharts GL、ecStat、Tailwind CSS 3.4.17（`tailwindcss-3.4.17.js`）、Chart.js、anime.js、marked、mermaid 等第三方库
|
||
- `lib/css/`、`lib/webfonts/` — 第三方 CSS 与字体
|
||
- `libai/` — shader-park-core（AI/研究页面使用）
|
||
- `js/` — 页面专属图表逻辑（不含第三方库）
|
||
- `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
|
||
|
||
# 部署到远程服务器（脚本位于 ~/bin/sync-echart，rsync 单向推送本地 → 服务器）
|
||
sync-echart -n # 预览（dry-run）
|
||
sync-echart # 执行部署到 simon@www.doorcome.cn:/var/www/html/echart/
|
||
# 排除项: .git/.vscode/.claude/.serena/.mcp.json/reasonix.toml
|
||
# 以及数据/产物目录 uploads/xls/files/research/podcast/podcast-docs（服务器为权威，不覆盖）
|
||
|
||
# 批量 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`，包含：
|
||
|
||
- **当前状态**：刚刚完成了什么、改了哪些文件、结果如何
|
||
- **后续步骤**：具体有序的下一步行动
|
||
- **待解决问题**：未解决的疑问、已知限制或需要决策的事项
|