# ashare-view

同一来源下的个股支持多个产业链产品归属。升级已有数据库前，需依次执行兄弟项目 `ashare-data/scripts/migrations/20260925_stock_industry_multiple.sql` 和 `20260925_stock_industry_active.sql`，将唯一键改为 `(source, stock_code, industry_code)` 并增加有效标记及索引。两个脚本各执行一次；已完成第一个迁移的数据库只执行第二个。启动建表不会修改已有字段或索引。行业树仅读取 `active = 1` 的归属，每个产品节点显示该股票，共同父节点按股票去重统计数量、成交额及涨停次数；失效归属保留原记录。

ashare-view 是一个面向 A 股市场数据的可视化看板，前端使用 React + Vite + Ant Design，后端使用 Go + Gin + GORM 连接 MySQL。项目将市场概览、指数行情、个股 K 线叠加、阶段新高、连板高度和每日趋势整合到一个单页应用中。

## 功能概览

- 市场概览：展示上涨、下跌、平盘数量，总成交额，平均涨跌幅，涨停、跌停和阶段新高列表。
- 指数行情：查看上证指数、深证成指、沪深 300、中证 500、中证 1000、创业板指等指数 K 线。
- K 线叠加：输入股票代码后叠加多只个股走势，便于横向比较。
- 情绪导图：按涨停梯队、焦点股和研报产业链树整理市场情绪。
- 阶段新高：查看当前交易日创 150 日新高的股票列表。
- 连板高度：统计当日涨停股的连续涨停天数，并按高度分组。
- 每日趋势：查看近 7、30、90、180 天的市场宽度、涨跌停和连板趋势。
- 历史日期查询：概览、阶段新高、连板高度和每日趋势支持选择历史日期；非交易日会自动映射到不晚于该日期的最近交易日。

## 技术栈

- 前端：React 19、TypeScript、Vite、Ant Design、ECharts、Axios、React Router。
- 后端：Go、Gin、GORM、MySQL、YAML 配置。
- 部署：Docker 多阶段构建，前端静态资源内嵌到 Go 服务镜像。

## 目录结构

```text
.
├── Dockerfile
├── docker-compose.yml
├── server
│   ├── config          # 配置加载
│   ├── database        # MySQL 连接和索引初始化
│   ├── handler         # HTTP handler
│   ├── model           # 数据模型
│   ├── repository      # SQL 查询
│   ├── router          # API 和静态资源路由
│   ├── service         # 业务逻辑和缓存
│   └── sql             # 示例初始化脚本
└── web
    ├── src
    │   ├── api         # 前端 API 封装和类型
    │   ├── components  # 图表、表格列、通用组件
    │   ├── constants   # 导航和市场常量
    │   ├── hooks       # 通用 React hooks
    │   └── pages       # 页面组件
    └── vite.config.ts
```

## Windows 双击启动

配置好 `server/config.yaml` 后，双击根目录 `start.cmd`。脚本使用已安装的 Node.js、npm 和 Go 构建前后端，由系统分配空闲端口，等待服务就绪后自动打开浏览器。前后端共用同一个地址，无需单独启动 Vite。

需要已安装前端依赖、已缓存 Go 依赖且 MySQL 可连接；脚本不会安装缺失的环境。支持查找 fnm 中已安装的兼容 Node.js。重复双击会打开已有服务；修改代码后先双击 `stop.cmd`，再启动以重新构建。停止脚本只关闭该启动脚本记录的服务。

实际访问地址和进程信息记录在 `.runtime/server.json`。启动失败时窗口会保留错误信息。命令行验证可运行 `powershell -NoProfile -ExecutionPolicy Bypass -File .\start.ps1 -NoBrowser`。

## 本地开发

### 1. 准备环境

- Node.js 20.19+ 或 22.12+（Vite 要求）
- npm
- Go 1.25+，或开启 Go toolchain 自动下载
- MySQL 8.x，且已有行情数据表

后端当前依赖以下核心表：

- `stock_daily`：个股日线行情，至少包含 `code`、`date`、`open`、`close`、`high`、`low`、`volume`、`turnover`、`pct_change`。
- `stock_info`：股票基础信息，至少包含 `code`、`name`。
- `index_daily`：指数日线行情，至少包含 `code`、`date`、`open`、`close`、`high`、`low`、`volume`、`amount`、`pct_change`。

`server/sql/init.sql` 是早期示例初始化脚本，可作为演示数据参考；生产或完整开发环境应以当前后端查询所需的表结构为准。

### 2. 配置后端

服务启动时会读取当前工作目录下的 `config.yaml`。也可以通过环境变量覆盖配置文件中的值。

```yaml
mysql:
  host: "127.0.0.1"
  port: "3306"
  user: "root"
  password: "your-password"
  database: "ashare"
  charset: "utf8mb4"

server:
  port: "0"
```

可覆盖的环境变量：

- `DB_HOST`
- `DB_PORT`
- `DB_USER`
- `DB_PASSWORD`
- `DB_NAME`
- `SERVER_PORT`

### 3. 启动后端

```powershell
cd server
go mod download
go run .
```

默认端口为 `0`，由系统分配空闲端口。访问启动日志中 `Server running on` 后的实际地址；每次重启地址可能变化。

### 4. 启动前端

```powershell
cd web
npm ci
$env:ASHARE_API_TARGET = '粘贴后端日志中的实际 HTTP 地址'
npm run dev
```

Vite 使用随机端口，将 `/api` 代理到 `ASHARE_API_TARGET`。如果使用根目录启动脚本启动后端，可省略该环境变量，Vite 会读取 `.runtime/server.json` 中的实际地址。启动后访问 Vite 终端输出的地址；后端端口变化后需重新启动 Vite。

## 构建与部署

### 前端构建

```powershell
cd web
npm run build
```

构建产物输出到 `web/dist`。

### 后端构建

```powershell
cd server
go build -o ashare-view .
```

生产镜像通过根目录 `Dockerfile` 完成前后端一起构建：

```powershell
docker build -t ashare-view:local .
```

`docker-compose.yml` 构建当前源码，挂载 `server/config.yaml`，通过 host 网络使用系统分配的随机端口。需要 Linux Docker Engine，或 Docker Desktop 4.34+ 并启用 host networking（Linux 容器）。不支持 host 网络的环境请使用本地启动脚本。

```powershell
docker compose up -d --build
docker compose logs ashare-view
```

部署后访问日志中 `Server running on` 后的实际地址。远程部署时将地址中的 `127.0.0.1` 替换为服务器 IP，并按实际端口配置防火墙。随机端口会在服务重启后变化，不配置固定端口映射。

## API 概览

所有接口返回格式均为：

```json
{
  "data": {}
}
```

| 方法 | 路径 | 参数 | 说明 |
| --- | --- | --- | --- |
| GET | `/api/dashboard/summary` | `date?` | 市场概览，未传日期时返回最新交易日 |
| GET | `/api/dashboard/daily` | `days?`、`end_date?` | 近 N 天每日统计，`days` 范围为 1-365 |
| GET | `/api/dashboard/sentiment-map` | `date?` | 市场情绪导图，包含涨停梯队、焦点股和研报产业链树 |
| GET | `/api/dashboard/consecutive` | `date?` | 指定日期或最新交易日的连板列表 |
| GET | `/api/dashboard/high100` | `date?` | 指定日期或最新交易日的 150 日新高列表 |
| GET | `/api/dashboard/index-kline` | `code?`、`days?` | 指数 K 线，默认 `000001` |
| GET | `/api/dashboard/stock-kline` | `code` | 个股全历史 K 线 |

## 开发注意事项

- 后端查询层按职责拆分在 `server/repository/`：市场、分钟行情、概念管理、情绪分类和行业树各自维护，`stock_repo.go` 保留仓储入口和日期工具。
- 后端 `server/service/cache.go` 统一缓存有效期、容量上限和同键并发请求合并，失败结果不缓存；具体查询的缓存键和期限由 service 指定。
- 启动时会异步为 `stock_daily` 创建常用索引：`date`、`code/date`、`date/pct_change`。
- 前端路由由 `web/src/App.tsx` 管理，菜单项在 `web/src/constants/navigation.tsx`。
- 前端 API 类型集中在 `web/src/api/types.ts`，接口封装在 `web/src/api/dashboard.ts`。
- `web/src/hooks/useEChart.ts` 统一图表初始化、尺寸监听和销毁；`useAsyncData.ts` 隔离不同参数的请求结果，防止旧响应覆盖新选择。