echart/CLAUDE.md

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

常用命令

# 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。

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，包含：

• 当前状态：刚刚完成了什么、改了哪些文件、结果如何
• 后续步骤：具体有序的下一步行动
• 待解决问题：未解决的疑问、已知限制或需要决策的事项