# 小白复盘

面向 A 股盘后复盘的本地 Web 工作台。收盘后把涨停、炸板、连板梯队、板块轮动、集合竞价、龙虎榜等数据整理成可浏览的复盘界面；不接券商、不代为下单，也不提供个股推荐。

本目录是唯一正式源码。模块边界见 [ARCHITECTURE.md](ARCHITECTURE.md)，产品与维护文档见 [docs/README.md](docs/README.md)。

## 主要功能

登录后左侧共 16 个页面，另有一个内嵌页「策略持续跟踪」。交易日快照保存在本地 SQLite 数据库 `data/review.db`。

- **情绪周期**：0–100 情绪温度与阶段判定（默认首页）
- **涨停池 / 炸板池 / 跌停板 / 昨日涨停 / 涨停表现**：封板结构、炸板、跌停与昨日反馈
- **市场天梯**：按连板高度排列的市场梯队
- **板块轮动**：近若干交易日板块热力与成分下钻
- **集合竞价**：盘前生命周期；9:30 后停止更新并冻结为复盘归档。当前数据源提供 9:25 最终竞价快照，不是动态虚拟撮合行情
- **题材库 / 人气热榜 / 龙虎榜**：题材成分、双榜人气、席位与游资档案
- **智能选股**（会员）：六阶段策略、精选策略库、自然语言编译为受控公式后的确定性筛选与滚动回测；候选需手动加入后才进入五交易日跟踪
- **问师**（会员）：按选定的游资思维 Skill 单师对话；新增公开角色时在 `游资skills` 下增加含 `SKILL.md` 的目录，并在 `游资skills/mentor_catalog.json` 登记。管理员私有角色放在 `data/private-mentor-skills`（不进 Git / 镜像）
- **问天**（会员，冻结区，勿改代码）：观势 / 观气 / 观心。卦象、干支、节气与气机由本地程序确定性计算，大模型只负责文字解释
- **我的复盘**：手工交易日志、每日复盘、提醒中心与复盘助手；不接券商、不自动下单

全局能力：日间 / 夜间主题、股票代码悬停预览日 K 与分时、`Ctrl + K` 全局搜索。图表数据不写入主行情，也不参与情绪、选股或问天计算。

## 技术栈

| 层面 | 说明 |
| --- | --- |
| 运行时 | Python 3.12；标准库 `ThreadingHTTPServer`，无独立 Web 框架 |
| 依赖 | `requirements.txt` 仅含 `cryptography`；问天历法使用仓库内 `vendor/lunar_python` |
| 数据库 | SQLite（WAL），默认文件 `data/review.db` |
| 前端 | 原生 HTML / CSS / JavaScript，无打包、无构建步骤 |
| 部署 | Docker / Docker Compose，或本机直接运行 `server.py` |
| 安全 | 账号密码 scrypt 哈希；行情 Token 与模型密钥用 `APP_ENCRYPTION_KEY` 加密后存库 |

## 环境要求

- Python 3.12（与 `Dockerfile` 一致）
- 本机启动：能执行 `python` / `pip`
- Docker 部署：Docker Engine 24+，Compose v2（`docker compose`）
- 行情：部署者自行申请并配置 Tushare Pro Token；部分分时优先使用同花顺 iFinD（可选）
- 问师、问天解释、复盘助手、自然语言编译公式：需配置 OpenAI 兼容接口；未配置时市场数据页仍可用

## 安装与启动

仓库根目录即为运行目录（`server.py`、`requirements.txt` 都在根目录）。

```bash
python -m pip install -r requirements.txt
python server.py
```

默认监听 `127.0.0.1:8765`（仅本机可访问）。浏览器打开该地址，首次使用先注册账号；第一个账号自动成为管理员，之后注册的默认为普通用户。

主行情不再回退演示数据：盘前、非交易日或临时取数失败时沿用最近真实收盘快照；没有任何真实快照时，页面会提示等待管理员完成首次同步。

可选参数：

```bash
python server.py --host 127.0.0.1 --port 8765
```

Windows 下若需要后台启动，并把日志、进程号和 Python 缓存写入 `runtime/`（不在源码根目录产生运行文件）：

```powershell
powershell -ExecutionPolicy Bypass -File tools/start_local.ps1
```

该脚本默认端口为 `8797`。统一验收：

```bash
python tools/verify_baseline.py
```

涉及运行时或前端时再加 `--e2e`（Playwright）。

## Docker 使用

局域网或服务器部署使用仓库根目录的 `Dockerfile` 与 `compose.yaml`。容器监听 `8765`，默认以非 root 用户运行，并把宿主机 `./data` 挂到容器内 `/app/data`。

1. 复制 `.env.example` 为 `.env`，填入 `APP_ENCRYPTION_KEY` 以及行情 / 模型等初始化配置。密钥不会返回到浏览器。
2. `compose.yaml` 构建时要求带上当前 Git 提交号，避免打出无版本标签的镜像：

```bash
export XIAOBAI_GIT_REV="$(git rev-parse HEAD)"
export XIAOBAI_GIT_SHORT="$(git rev-parse --short=7 HEAD)"
docker compose build
docker compose up -d
```

3. 检查健康接口：

```bash
docker compose ps
curl http://127.0.0.1:8765/api/health
```

健康响应类似 `{"ok": true, "storage": "sqlite", "account_required": true}`。

完整的迁移、持久化、防火墙、备份、恢复与正式线构建入口见 [DOCKER_DEPLOY.md](DOCKER_DEPLOY.md)。`.env` 必须与数据库成对备份；丢失 `APP_ENCRYPTION_KEY` 后无法恢复加密资料。

## 目录与配置

```text
server.py            进程入口
backend/            服务、路由、数据、任务、LLM
frontend/            无构建前端（shared + pages）
config/              页面 / API / 任务等注册表
data/                SQLite 与私有数据（数据库文件不进 Git）
runtime/             本地日志、PID、缓存（不进 Git）
tools/               启动、验收与构建辅助脚本
游资skills/          公开问师角色
vendor/              本地第三方库（含 lunar-python）
Dockerfile
compose.yaml
.env.example         环境变量模板（复制为 .env 后填写）
```

管理员通过页面右上角「系统管理」保存公共 Tushare Token、平台主/辅助模型、会员每日额度和后台刷新开关。所有用户读取同一份 SQLite 行情快照。`.env` 中的 Tushare 和平台 LLM 配置只用于初始化系统配置。

普通用户在「账号设置」中维护个人资料、查看会员状态和修改密码，不配置个人 LLM。有效会员使用平台模型；管理员可开通、续期、停用会员。平台模型受每日调用次数限制，管理员账号始终可用。

相关文档：

- [ARCHITECTURE.md](ARCHITECTURE.md) — 模块边界
- [docs/README.md](docs/README.md) — 交接手册入口
- [DOCKER_DEPLOY.md](DOCKER_DEPLOY.md) — Docker 部署、备份与恢复
- [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) — 第三方授权（含问天历法库）
- [AGENTS.md](AGENTS.md) — 维护约束

## 注意事项与免责声明

- 本项目是个人研究与复盘工具，全部数据、指标、候选与文字分析均不构成投资建议、证券推荐或买卖要约。
- 不接券商、不代为下单。交易日志只做手工记录与统计，不代表实际成交。
- 情绪温度、阶段判定、连板梯队、策略筛选等均为基于公开数据的统计与规则计算，不预测走势，不保证收益。
- 「问天」属于传统文化视角的观察工具，不具备预测功能，不得作为投资依据；该模块为冻结区，不要改其代码。
- 行情来自第三方接口，可能延迟、缺失或口径调整；不可用时页面会明确提示，请以交易所与券商正式披露为准。
- 不要把服务端口直接暴露到公网。不要把 Token、密码、密钥、数据库或 `.env` 提交进 Git。
- 股市有风险，入市需谨慎。投资决策及其后果由使用者本人承担。