<div align="center">

# 📈 A股智能量化工作台（服务端备份/查看版）

**本地完整版的云端伴侣：数据备份 + 基础数据查看**

**面向已部署 `local/` 完整版的用户，提供远程备份与轻量查看能力**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![Python](https://img.shields.io/badge/Python-≥3.11-blue.svg)](https://www.python.org/)
[![React](https://img.shields.io/badge/React-18-61dafb.svg)](https://react.dev/)
[![Deploy: Docker](https://img.shields.io/badge/Deploy-Docker-2496ed.svg)](./Dockerfile)

</div>

<div align="center">

**[快速开始](#-快速开始)** · **[功能范围](#-功能范围)** · **[接收本地同步](#-接收本地同步)** · **[部署说明](#-部署说明)**

</div>

---

## 🎯 项目定位

`serve/` 目录下的版本是 **服务端轻量版**，它不是 `local/` 的替代品，而是其**配套服务端**：

- **数据备份**：接收本地完整版推送的核心数据，防止本地磁盘故障导致历史数据丢失
- **远程查看**：在手机、平板或其他设备上通过浏览器查看基础行情、选股结果、复盘报告等
- **多用户隔离**：支持 admin / viewer 角色，适合家庭或小团队共享查看

**它不是满血版**，不包含实时行情、回测、实时监控、五档盘口、AI 策略生成等需要本地运行或消耗大量计算/Quota 的能力。所有复杂分析和决策功能，请在 `local/` 本地完整版中使用。

---

## ⚡ 快速开始

### 前置依赖

与 `local/` 相同：

| 工具                               | 版本   | 安装                                               |
| :--------------------------------- | :----- | :------------------------------------------------- |
| Python                             | ≥ 3.11 | [python.org](https://www.python.org/)              |
| Node                               | ≥ 20   | [nodejs.org](https://nodejs.org/)                  |
| [`uv`](https://docs.astral.sh/uv/) | latest | `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
| `pnpm`                             | 9      | `npm i -g pnpm`                                    |

### 方式 A：Dev 模式

```bash
cp .env.example .env       # 配置监听端口、同步密钥等
./dev.sh                   # Windows: .\dev.ps1
```

默认：

- 后端 → <http://localhost:3018> · 前端 → <http://localhost:3011>
- 自定义端口：`BACKEND_PORT=8000 FRONTEND_PORT=5173 ./dev.sh`

### 方式 B：Docker（推荐）

```bash
cp .env.example .env
docker compose up --build
# 打开 http://localhost:3018
```

容器名：`stock_panel`。默认端口 `3018`。

> 与 `local/` 不同，`serve/` 的 `data/` 目录**默认被 `.dockerignore` 忽略**，容器重启不会保留容器内的数据。请通过本地 `local/` 主动同步，或将 `data/` 挂载到持久化卷。

---

## 📦 功能范围

| 功能 | serve/ 服务端 | 说明 |
| :--- | :---: | :--- |
| 看板 Dashboard | ✅ | 展示已同步的基础市场概况 |
| 选股结果查看 | ✅ | 查看 local/ 推送的选股结果 |
| 概念 / 行业分析 | ✅ | 查看已同步的概念/行业数据 |
| 复盘报告 | ✅ | 查看 local/ 生成的盘后 AI 复盘 |
| 指数 / 个股基础 K 线 | ✅ | 查看已同步的历史 K 线 |
| 多用户认证（admin/viewer） | ✅ | 支持多用户、角色隔离 |
| 数据同步接收 | ✅ | 接收 local/ 推送的数据 |
| 回测 | ❌ | 请在 local/ 中完成 |
| 实时监控 / SSE 告警 | ❌ | 请在 local/ 中使用 |
| 五档盘口 / 实时行情 | ❌ | 请在 local/ 中使用 |
| 自选实时监控 | ❌ | 请在 local/ 中使用 |
| AI 策略生成 | ❌ | 请在 local/ 中使用 |

### 适用场景

- **异地灾备**：local/ 每天收盘后自动把 enriched 数据、选股结果、复盘报告推送到 serve/
- **移动查看**：出差时用手机浏览器访问 serve/，查看本地已分析好的结果
- **家庭共享**：家人用 viewer 账号查看，admin 账号管理同步密钥

---

## 🔄 接收本地同步

### 1. 服务端配置

在 `serve/.env` 中设置同步密钥（与 local/ 保持一致）：

```ini
SYNC_KEY=your-shared-secret
```

首次启动时建议通过 `AUTH_PASSWORD` 预置管理员密码：

```ini
AUTH_PASSWORD=你的密码
```

### 2. 本地端配置

在 `local/.env` 中填写服务端地址和密钥：

```ini
SYNC_SERVE_URL=https://your-serve.example.com
SYNC_KEY=your-shared-secret
```

### 3. 触发同步

在 local/ 的「设置 → 数据同步」页面手动触发，或等待盘后定时任务自动推送。

### 4. 安全建议

- 务必通过 HTTPS 暴露 serve/
- `SYNC_KEY` 应使用强随机字符串，并定期更换
- 不要对外开放 22 / 数据库等无关端口
- 若暴露在公网，务必先设置 `AUTH_PASSWORD`

---

## 🏗️ 部署说明

### 最小资源

| 资源 | 建议值 |
| :--- | :--- |
| CPU | 1 核 |
| 内存 | 512 MB |
| 磁盘 | 根据数据量，建议 ≥ 10 GB |

### 持久化

serve/ 的数据主要来自 local/ 同步。如果你希望容器重启后保留数据，请在 `docker-compose.yml` 中挂载持久卷：

```yaml
volumes:
  - /your/host/data:/app/data
```

### 反向代理示例（Nginx）

```nginx
server {
    listen 443 ssl;
    server_name your-serve.example.com;

    location / {
        proxy_pass http://127.0.0.1:3018;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}
```

---

## ⚙️ 配置

```ini
# 同步密钥（必须和 local/.env 里的 SYNC_KEY 一致）
SYNC_KEY=your-shared-secret

# 服务端口
HOST=0.0.0.0
PORT=3018

# 首次管理员密码（仅首次启动生效，写入 auth.json 后不再读取）
AUTH_PASSWORD=你的密码

# 日志级别
LOG_LEVEL=INFO

# 数据目录（Docker 中建议挂载到宿主机）
DATA_DIR=./data
```

完整配置项参考 `serve/.env.example`。

---

## 🗺️ 与 local/ 的关系

```
┌─────────────────────────────────────┐
│           local/ 本地完整版          │
│  选股 · 回测 · 实时监控 · AI 分析    │
│           ↓ 定时/手动同步           │
└─────────────────────────────────────┘
                   │
                   ▼ HTTPS + SYNC_KEY
┌─────────────────────────────────────┐
│         serve/ 服务端轻量版          │
│     数据备份 · 基础查看 · 多用户      │
└─────────────────────────────────────┘
```

- **local/**：功能核心，承担所有计算、实时行情、回测、监控
- **serve/**：数据落地与轻量展示，不承担计算，不直接调用 TickFlow 高配额接口
