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>
85 lines
3.9 KiB
Markdown
85 lines
3.9 KiB
Markdown
# AGENTS.md
|
||
|
||
本文件为 AI 编码助手提供在本仓库中工作的指引与约定。
|
||
|
||
## 项目背景
|
||
|
||
这是一个 A 股基本面数据可视化和宁波房地产数据分析平台，面向个人投资者使用。项目没有框架，是原生 PHP 写的传统 Web 应用。
|
||
|
||
## 技术约束
|
||
|
||
- **不要引入框架或构建工具** —— 项目是纯 PHP + jQuery + ECharts，没有 webpack、vite、composer autoload 之外的依赖管理。新增功能沿用现有模式即可。
|
||
- **不要动 `inc/config.php`** —— 该文件包含数据库连接逻辑且部分编码加密，手工修改可能破坏现有功能。
|
||
- **PHP 版本** —— 代码兼容 PHP 7.x/8.x，使用了 `mysqli`、cURL、Composer autoload。不要使用 PHP 8.1+ 独有的特性（如枚举、readonly 等）。
|
||
- **所有用户输入走 `$_REQUEST`** —— GET 和 POST 统一处理，不需要区分。
|
||
- **图表数据传递模式** —— 后端 PHP 查库 → `json_encode()` 注入 `<script>` 标签作为 JS 全局变量 → 页面专属的 JS 文件读取全局变量并用 `echarts.init()` 渲染。
|
||
|
||
## 代码风格约定
|
||
|
||
- 缩进：使用 Tab 缩进（现有代码风格）。
|
||
- SQL 查询：使用 heredoc 语法，保持可读性。
|
||
- PHP 标签：使用 `<?=` 和 `<?php` 短标签。
|
||
- 注释：中文注释，简洁为主，解释业务逻辑而非代码本身（如指数的 ts_code 映射、机构类型 LX 含义等）。
|
||
- 不需要加 docblock —— 现有代码基本没有，新代码也不加。
|
||
|
||
## 新增页面流程
|
||
|
||
如果要新增一个数据可视化页面，按以下步骤：
|
||
|
||
1. 在 `inc/` 中写数据获取函数（如果数据源有复用价值），或在页面内直接写查询
|
||
2. 在根目录创建 `newpage.php`，include 需要的 `inc/*.php`
|
||
3. 通过 `$_REQUEST` 接收参数（如 `ts_code`、`t_start`、`t_end`）
|
||
4. 查询数据库，`json_encode` 结果注入到页面
|
||
5. 在 `js/` 中创建对应的 JS 文件，负责 ECharts 初始化和图表渲染
|
||
6. 对于样式较新的页面，使用 `js/tailwindcss_3.4.17.js` 并参考 `index-2.php` 的布局风格
|
||
7. 在 `index-2.php` 中添加导航入口
|
||
|
||
## 常用代码片段
|
||
|
||
### 获取数据库连接
|
||
```php
|
||
include_once __DIR__."/inc/config.php";
|
||
$mysqli = get_mysqli_connection();
|
||
```
|
||
|
||
### 标准查询返回 echarts 数据格式
|
||
```php
|
||
$tDate = $idx = $data = array();
|
||
while ($row = $result->fetch_assoc()) {
|
||
array_push($tDate, $row['trade_date']);
|
||
array_push($idx, $row['close']);
|
||
array_push($data, array("value" => array($row['trade_date'], round($row['close'], 2))));
|
||
}
|
||
$result->free();
|
||
$mysqli->close();
|
||
return array('tDate' => $tDate, 'idx' => $idx, 'data' => $data);
|
||
```
|
||
|
||
### 调用 TuShare API
|
||
```php
|
||
include_once __DIR__."/inc/functions.inc.php";
|
||
$data = callTushareApi('daily_basic', $params);
|
||
```
|
||
|
||
### 前端 AJAX 调用模式
|
||
```php
|
||
// 请求参数中必须包含 t 字段，用于路由
|
||
$_REQUEST['t'] = 'stockList'; // ajax.inc.php 中的 case
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
- **TuShare API token 硬编码在代码中** —— 不要提交到公开仓库。
|
||
- **没有鉴权机制** —— 这是内网或个人使用的系统，不需要添加登录/权限功能。
|
||
- **数据库表名约定** —— 指数数据在 `index_hist_pro`，个股历史在 `stock_his_pro`，基本面在 `stock_his_basic_pro`，机构持仓在 `ih_by_ts_code_ext`，房地产数据在 `estate_json` 系列，交易记录在 `trade_record`。
|
||
- **`deprecated/` 目录** —— 存放已废弃的旧版页面，直接忽略，不要修改或引用。
|
||
- **`news/` 和 `research/`** —— 独立的子模块，有自己的 JS/CSS 和设计文档，修改前先看对应的 `design.md` 和 `outline.md`。
|
||
|
||
## Checkpoint
|
||
|
||
当用户说 "checkpoint" 时，在项目根目录生成 `continuation.md`，包含：
|
||
|
||
- **当前状态**：刚刚完成了什么、改了哪些文件、结果如何
|
||
- **后续步骤**：具体的、有序的下一步行动
|
||
- **待解决问题**：未解决的疑问、已知限制或需要决策的事项
|