simonandClaude Code
7e57cae242
安全性: - 所有SQL查询改用参数化查询(db_query)，防止SQL注入 - TUSHARE_API_TOKEN集中到config.php常量，移除硬编码和多份拷贝 - getBasic.inc.php中$_REQUEST输出到JS时添加htmlspecialchars转义 代码组织: - 21个页面文件移至charts/子目录，根目录仅保留入口文件 - ajax.inc.php拆分：esfTradeDaily/esfListDaily迁至getEstate.inc.php - getBasic.inc.php拆分：HTML组件函数迁至新建的widgets.inc.php - 前端依赖去重：移除lib/echarts.min.js、libai/3.4.16.js、research/js/3.4.16.js 规范化: - AJAX响应格式统一为jsonResponse()标准封装 - 前端全局变量统一为window.chartConfig对象模式 - 修复PHP 8.4 Deprecated警告(getEstateData、getStockHistoryDataByTS参数顺序) - html/head.php中jQuery/CSS路径改为绝对路径，修复charts/子目录加载问题 Co-Authored-By: Claude Code <noreply@anthropic.com>
142 lines
7.4 KiB
Markdown
142 lines
7.4 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` 文件是独立的入口点，没有路由机制。
|
||
|
||
## 架构
|
||
|
||
### 核心 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` 表）及二手房成交/挂牌数据函数。
|
||
|
||
### 页面结构
|
||
|
||
根目录及 `charts/` 下的每个 `.php` 文件渲染一个独立的数据视图，遵循统一模式：
|
||
|
||
1. 引入所需的 `inc/*.php`
|
||
2. 通过 `$_REQUEST` 接收查询参数
|
||
3. 查询数据库，将结果通过 `json_encode()` 注入 `<script>` 标签
|
||
4. 加载对应的 `js/*.js`，由 JS 调用 `echarts.init()` 渲染图表
|
||
5. 引入 `html/head.php` 和 `html/footer.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` | 个股详细图表 |
|
||
|
||
### 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 生成的研究内容。
|
||
- `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
|
||
|
||
## 服务器与部署
|
||
|
||
应用运行于 `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`，包含：
|
||
|
||
- **当前状态**：刚刚完成了什么、改了哪些文件、结果如何
|
||
- **后续步骤**：具体有序的下一步行动
|
||
- **待解决问题**：未解决的疑问、已知限制或需要决策的事项
|