xiaobai-review/README.md

小白复盘

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

本目录是唯一正式源码。模块边界见 ARCHITECTURE.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 都在根目录）。

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

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

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

可选参数：

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

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

powershell -ExecutionPolicy Bypass -File tools/start_local.ps1

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

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 提交号，避免打出无版本标签的镜像：

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. 检查健康接口：

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

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

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

目录与配置

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 — 模块边界
• docs/README.md — 交接手册入口
• DOCKER_DEPLOY.md — Docker 部署、备份与恢复
• THIRD_PARTY_NOTICES.md — 第三方授权（含问天历法库）
• AGENTS.md — 维护约束

注意事项与免责声明

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