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

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