xiaobaifupan/app/docs/HANDOFF.md

小白复盘项目交接说明

核实日期：2026-08-06（Asia/Shanghai） 正式源码边界：webapp/app/ 产品行为基准：docs/product/小白复盘-完整产品规格说明书.md

本文件不是聊天摘要。内容以当前仓库、配置注册表、测试、Git 状态和产品规格交叉核实为准。后续维护者应先阅读根目录 AGENTS.md、ARCHITECTURE.md、本文件和产品规格，再修改代码。

0. 状态口径与证据

本文使用四种状态，不能混用：

• 已实现：当前正式源码中存在对应实现。
• 自动验证通过：有测试或注册表检查证明，不等同于人工视觉验收。
• 人工已验收：用户已经确认迁移后的正式 app/ 在功能和视觉上与迁移前等价；该结论只覆盖当时基线。
• 待验收/待实现：代码尚未完成，或虽已写入工作区但尚未取得本轮人工确认和 Git 回档点。

0.1 Git 与运行快照

• 分支：main。
• 当前提交：bd97ba1 feat: unify trading workspace visual system。
• HEAD 与 origin/main 一致；远端为内部 Gitea 仓库。
• 生成本文前工作区已有 37 个修改文件，约 2490 行新增、2958 行删除，主要是全站视觉调整和最新问师改造；这些改动不是本文创建的，禁止丢弃。
• 生成本文时 8797 端口没有监听进程，因此实时数据源和 LLM 的运行可用性没有通过在线健康检查确认。
• 当前正式数据库为 data/review.db，使用 SQLite WAL；数据库、.env、Token、私有 Skill、日志和运行产物不进入 Git。
• 本轮文档生成后的自动验证结果见本文末尾“验证记录”。

1. 项目目标和当前状态

1.1 项目目标

小白复盘是面向 A 股盘后复盘和盘前观察的本地/局域网 Web 工作台。目标不是自动交易，而是把真实行情、市场情绪、涨跌停结构、集合竞价、板块题材、选股、思维模型问答、传统文化观察和个人复盘放在一套可追溯、可复现、账号隔离的系统中。

产品必须坚持以下底线：

1. 不使用演示行情冒充真实数据，不静默混用日期、单位、复权或数据源。
2. 计算型数据缺失时失败关闭；公开网页源只允许作为已登记的展示兜底。
3. 阶段、策略筛选、情绪、观势取象和六爻排盘由确定性程序完成；LLM 只编译自然语言条件或解释确定性结果。
4. 用户自选、复盘、交易日志、问师/问天历史等私有数据必须按账号隔离。
5. PC 端优先达到稳定、精致、可长期维护；移动端必须独立设计，不能把 PC 页面简单压缩。

1.2 当前状态

正式版本已经从历史混乱目录保真迁入 webapp/app/，用户已人工确认迁移本身在功能和视觉上成功。项目已经完成模块化单体边界、页面碎片化、数据网关、LLM 网关、后台任务、数据库迁移、注册表和统一验收工具等结构治理。

当前不是“从零重写”状态，也不应再次从旧根目录或失败的 next/ 复制实现。现阶段属于：

• 核心 PC 产品可用，16 个主工作区均有正式实现。
• 当前工作区正在进行全站 PC 视觉一致性调整，以及问师经典 QQ 式三栏界面和动态追问能力；自动化测试已覆盖，尚待本轮人工视觉验收和提交。
• 移动端明确暂停，当前存在样式但不能据此宣称可用。
• 完整 IC 动态加权、稳定宏观/政策/隔夜消息、分析师一致预期、Level-2 等依赖数据与算法的能力尚未完成。
• 局域网单实例是当前部署边界；公网多实例能力不属于当前完成范围。

2. 技术架构与主要目录

2.1 总体架构

项目采用模块化单体：一个 Python 进程、一个 SQLite WAL 数据库、无构建工具的 HTML/CSS/JavaScript 前端。

Browser
  -> frontend/shared/api.js
  -> backend/http + backend/features/<feature>/routes.py
  -> feature service
  -> Repository / DataGateway / LLMGateway
  -> SQLite / Tushare / iFinD / display-only providers / LLM provider

Scheduler
  -> backend/jobs
  -> 同一套 feature service / repository / gateway

该结构适合当前局域网单实例产品：部署简单、数据本地、回档直接，同时通过领域边界避免再次退化成单文件应用。除非进入公网多实例阶段，不要提前引入微服务、消息队列或前端构建框架。

2.2 主要目录

路径	唯一职责
server.py	稳定启动/导入门面
backend/bootstrap/	配置、依赖组装、启动与组合根
backend/http/	鉴权、请求 ID、JSON/NDJSON、静态文件、流式连接和统一异常
backend/features/	按账户、市场、选股、问师、问天、复盘等领域组织业务、路由和 Repository
backend/data/	DataGateway、数据源策略、来源/日期/单位/新鲜度/覆盖率质量门
backend/data/providers/	Tushare、iFinD 等供应商适配；不得由业务模块直接调用
backend/database/	SQLite 连接、顺序迁移和 Repository 组合
backend/jobs/	行情刷新、盘后选股、事件补充的锁、状态、幂等和重试
backend/llm/	模型选择、会员/额度、主辅回退、流式协议、取消和审计
frontend/index.html	登录层、全站 Shell、摘要条、状态栏、全局弹窗和唯一页面挂载点
frontend/shared/	唯一 API 出口、状态、Shell、会话、主题和公共组件
frontend/pages/	页面局部 page.html、page.js、foundation.css
config/	页面、功能、API、数据字段、质量和任务注册表
data/	正式数据库与私有数据，不入 Git
runtime/	日志、PID、缓存、测试结果，不入 Git
tests/	Python 单元/边界/契约测试与 Playwright 浏览器回归
tools/	启动、注册表生成、架构清单和统一验收工具
docs/	产品规格、维护、治理、历史迁移和当前交接/Issue

2.3 注册表和运行事实

• config/pages.config.json：16 个主页面，默认页为情绪周期。
• config/features.config.json：20 个功能及 public/authenticated/member/admin 权限。
• config/api.config.json：当前 53 个精确 API 路径和 11 个正则路径，由工具生成并校验。
• config/jobs.config.json：行情刷新、15:10 后盘后选股、iFinD 事件补充三类任务。
• config/data-fields.config.json：数据源与字段用途；Tushare/iFinD 可进入已登记计算，东方财富/腾讯只允许展示，未解决数据集显式阻塞。
• config/data-quality.config.json：单位、覆盖率、新鲜度和失败关闭规则。
• config/architecture-inventory.json：生成的架构清单和代码热点，不应手工编造。

2.4 数据源边界

数据源	当前角色	约束
Tushare	交易日、股票主数据、日线、估值、财务、资金、申万行业、涨跌停、最终竞价、热榜、龙虎榜等主要计算数据	按接口权限和质量门使用
iFinD	动态竞价、展示型日 K/分时和盘后事件补充	凭据/授权到期时必须显式不可用，不得伪造
东方财富/腾讯	分时或实时指数的展示观察兜底	不得静默进入情绪、选股或问天计算
Local	情绪等确定性派生结果	保存算法/输入版本，保证可复现
unresolved	分析师一致预期、Level-2	当前阻塞，不能用名称或空字段冒充实现

3. 已完成功能

以下表示当前正式源码存在实现；人工视觉结论仅继承用户对迁移基线的确认，不覆盖本轮未提交视觉改动。

3.1 全局与账户

• 注册、登录、退出、首账号管理员、普通/会员/管理员权限。
• 个人资料、生辰资料、修改密码、会员状态、系统管理与公共凭据配置。
• 顶栏日期、默认最近真实交易日、情绪摘要条、日间/夜间、全局搜索、提醒中心。
• 股票、题材、板块、指数详情；日 K/分时与代码/题材悬浮预览。
• 统一 Toast、弹窗、空态、加载、错误转换和页面生命周期基础设施。

3.2 市场复盘页面

• 情绪周期：温度、阶段、方向、置信度、构成、趋势和交易日明细。
• 涨停池、炸板池、跌停池、昨日涨停、涨停表现。
• 市场天梯、板块轮动与成分股联动。
• 集合竞价：盘前状态、9:25 最终筛选、普通异动/一字板、成交额对比和自选。
• 题材库、人气热榜、龙虎榜和游资名录/详情基础能力。

3.3 智能选股

• 六阶段盘后候选、29 套精选策略、策略适用说明和确定性候选结果。
• 自定义公式 DSL、自然语言编译公式、因子与权重手动配置。
• 候选按策略/日期隔离，盘后自动发布最近完整交易日结果。
• 用户手动加入五交易日策略跟踪，T+1/T+3/T+5 反馈和幂等提醒。
• 数据缺失、无符合条件、任务失败等状态区分。
• 当前多因子为基础动态版；完整 IC 版不在“已完成”范围内。

3.4 问师与 LLM

• 公共/管理员私有思维模型 Skill 注册、证据等级、关注维度和排序偏好。
• 按账号、模型、交易日隔离对话；最多带入最近 10 条历史。
• 按模型类型提供不同市场上下文，识别个股时追加有限标的数据。
• 统一 LLM 会员/额度、主辅回退、流式去重、停止生成、审计和安全错误。
• 当前工作区已经实现经典 QQ 式联系人/会话/资料三栏和同次调用动态追问；状态为“自动验证通过、待人工验收和提交”，详见 Issue 001。

3.5 问天

• 观势：真实行情安全门、三才六爻、势值、本卦/之卦、客观数据补录与恢复自动数据。
• 观气：历法、节气、中运/司天在泉/主客气、个人合参、五行行业取象和每日解运持久化。
• 观心：交易/心境/无题预设、呼吸流程、六次铜钱起卦、第一念、京房纳甲/八宫世应/六亲/六神/旬空等确定性排盘。
• 本地知识检索、答案一致性校验和 LLM 解释；LLM 不起卦、不修改程序结果。

3.6 个人复盘

• 账号私有自选追踪、个股笔记、三个独立输入框的每日复盘及历史。
• 结构化交易日志、编辑删除、胜率/盈亏/仓位统计。
• 复盘助手流式对话，读取共享市场和当前用户记录，不执行交易。
• 手工提醒、已读状态、策略跟踪 T+1/T+5 自动提醒和幂等去重。

3.7 工程治理

• 正式源码独立于父目录旧程序和失败 next/。
• 页面结构、行为和样式已按领域拆分；浏览器请求统一经过 frontend/shared/api.js。
• Tushare 大客户端、智能选股、问天、市场洞察和 HTTP 层已拆成职责明确的模块门面。
• 有正式数据库 migration、数据/LLM/job 网关、API/功能/页面/数据注册表。
• 统一验收工具覆盖 Python、注册表、JS 语法、Git 空白、SQLite 完整性和可选 Playwright。

4. 尚未完成的功能

每项均有独立 Issue，Issue 状态优先于历史聊天中的阶段编号。

Issue	状态	优先级	未完成内容
ISSUE-001	待人工验收/提交	P0	问师三栏界面、停止生成和动态追问收口
ISSUE-002	待审查/提交	P0	当前全站 PC 视觉改动的逐页验收、拆分和回档点
ISSUE-003	明确延期	P2	独立移动 Shell、逐页信息架构和触控交互
ISSUE-004	未实现	P1	12 个月 Rank IC、季度重算、中性化和前 5% 输出
ISSUE-005	数据源未定	P1	稳定政策/宏观/隔夜消息序列与竞价量化
ISSUE-006	数据阻塞	P2	一致预期、预测修正、评级/目标价等字段
ISSUE-007	授权阻塞	P2	Level-2 委托队列、逐笔和动态竞价深度
ISSUE-008	低优先级	P3	游资档案的更完整历史画像和归类质量
ISSUE-009	待整理	P1	活跃文档/注册表中移动端、端口和验收状态漂移
ISSUE-010	待运行核验	P0	启动正式服务并验证数据源、iFinD、LLM 与任务健康
ISSUE-011	未来范围	P3	公网多实例、TLS、PostgreSQL、队列、缓存和集中监控

明确不是待办：问师自主联网取数当前已因风险高于收益而延期；全能金融爬虫 Skill 已放弃；旧 next/ 已冻结失败；不要把这些内容重新加入实现。

5. 已知问题与风险

5.1 用户可见问题

1. 移动端整体不可用或交互较差。 当前存在大量媒体查询和 mobile_layout: dedicated 注册值，但这只证明代码存在，不证明通过人工可用性验收。
2. 当前问师与全站视觉改动未完成交付闭环。 自动化已通过，但工作区未提交，且用户尚未对本轮 QQ 式问师界面进行视觉确认。
3. 实时数据和 LLM 当前在线状态未知。 生成本文时 8797 未启动；外部服务还受本机网络、系统凭据、接口权限和 iFinD 授权有效期影响。
4. 缺失数据不能被误显示为无信号。 分析师一致预期、Level-2 和部分宏观/新闻数据目前无正式来源；相关策略或页面必须显示数据缺失/阻塞。

5.2 维护风险

• frontend/pages/heaven/foundation.css 约 11,734 行、frontend/pages/screener/foundation.css 约 6,565 行、frontend/shared/shell.css 约 3,224 行；它们是当前最大 CSS 热点。没有具体回归证据时不得为了“减行数”盲拆。
• frontend/pages/heaven/page.js 约 2,069 行、backend/features/heaven/engine.py 约 1,183 行，问天仍是高复杂度领域。
• 根 database.py 仍是历史 schema/Repository 组合锚点，不是新增业务查询的位置；继续向其中加功能会破坏治理结果。
• 自动化测试不能替代产品规格第 25 至 27 节的全矩阵人工验收，尤其是外部真实数据、LLM、日夜主题、1080P/4K 和移动端。
• 当前脏工作区横跨 37 个文件。提交前必须按功能拆分或至少留下清晰回档说明，不能把无关改动混成无法审计的大提交。

6. 已作出的重要技术决策及原因

决策	原因
webapp/app/ 是唯一正式源码	已完成保真迁移并人工确认；避免继续依赖父目录旧代码或失败 next/
保持模块化单体	当前局域网单实例用一个进程和 SQLite 最简单；领域边界已经足以控制复杂度
不更换技术栈，前端保持无构建 HTML/CSS/JS	迁移目标是整理和减法，不是重拍功能；减少部署与人工维护成本
页面、功能、API、数据和任务采用注册表	防止入口散落、权限漂移和“代码有但系统不知道”
浏览器 API、外部数据和 LLM 各自只有一个网关出口	统一鉴权、错误、质量、额度、降级和审计
计算数据失败关闭，展示兜底隔离	防止公开网页源或旧快照静默污染情绪、选股、竞价和问天结果
智能选股由条件和数据确定执行，LLM 只编译公式	保证同日期同策略可复现，避免刷新结果漂移
问天确定性引擎负责历法/卦象，LLM 只解释	结果可复现、可测试，避免模型改卦或编造事实
问师外部工具自主取数暂缓	当前缺少成熟权限、来源和失败边界，风险高于收益
放弃通用金融爬虫 Skill	网页规则不稳定、版权/安全/口径不可控，不适合进入正式计算链
移动端暂停并要求独立设计	密集 PC 表格不能靠压缩获得可用手机体验；先保证 PC 功能与视觉
不确定代码默认保留，删除需扫描、差异测试和人工验收	防止“减法”误删隐含功能；历史迁移日志用于回档证据
公网能力不提前实现	当前用户场景是本地/局域网；多实例、PostgreSQL 和队列应由真实部署需求驱动

7. 当前正在处理的事项

7.1 问师改造

当前未提交代码已经完成：

• 经典 QQ 式 PC 三栏结构：联系人、对话、当前模型资料/证据。
• 动态追问：模型在同一次输出末尾返回 <XIAOBAI_FOLLOW_UPS> 机器块；服务端剥离机器块，并在最终 NDJSON meta.follow_ups 返回 2 至 3 条建议。
• 动态追问不额外调用 LLM、不重复扣额度；点击只预填输入框。
• 停止生成控制、Enter 发送、流式占位与回答状态。
• 问师 CSS 从历史约 2,800 行收敛到约 988 行。

相关文件：

• backend/features/mentor/agent.py
• backend/features/mentor/service.py
• frontend/pages/mentor/page.html
• frontend/pages/mentor/page.js
• frontend/pages/mentor/foundation.css
• tests/test_mentor_stream.py
• tests/e2e/app-shell.spec.js

尚缺：启动正式服务、接入真实 LLM 做一次端到端验证、用户人工确认日间/夜间及 1080P/4K 视觉、建立提交并推送回档点。

7.2 当前全站视觉改动

工作区还包含 Shell、设计令牌、公共组件以及市场、情绪、股池、天梯、轮动、竞价、题材、热榜、龙虎榜、选股、问天、复盘等页面样式改动。它们已进入自动化回归，但尚未形成独立验收结论。移动端已被产品决策暂停，因此不能因为这些 CSS 中存在移动规则就标记移动端完成。

8. 推荐的后续执行顺序

1. 先恢复运行环境并核验外部能力。 启动 8797，检查健康、登录、最近真实交易日、Tushare/iFinD、LLM 主辅模型和后台任务；不通过时先解决 Issue 010。
2. 人工验收问师。 完成 Issue 001 的真实 LLM、流式、停止、动态追问、日夜和分辨率检查。
3. 审查当前全站视觉差异。 按 16 页逐页检查 Issue 002，确认哪些是 PC 正式改动、哪些是已暂停移动尝试，保持功能等价。
4. 建立回档点。 将问师和全站视觉按可审计边界提交并推送，不夹带密钥、数据库或运行产物。
5. 清理活跃文档状态漂移。 完成 Issue 009，使 README、注册表和交接状态不再暗示移动端已验收。
6. 先补可获得的高价值数据，再升级算法。 先确定 Issue 005/006 的合法稳定来源，再实施 Issue 004；没有完整历史覆盖时不能伪造 IC。
7. 有正式授权后再做 Level-2。 Issue 007 不能用普通快照模拟。
8. 低优先级完善游资档案。 Issue 008 不应阻塞市场、选股、问师和问天稳定性。
9. PC 稳定后才重启移动端设计。 Issue 003 必须单独打样和逐页人工验收。
10. 确定公网商业化再做部署升级。 Issue 011 需要单独架构决策和迁移方案。

9. 每项任务的验收标准

本节是交接总表；独立 Issue 内给出更具体的范围和命令。产品规格第 25 至 27 节固定案例仍是最终依据。

任务	必须满足的验收标准
Issue 001 问师收口	真实 LLM 只输出一份正文；同次调用出现 2 至 3 条有效追问；点击只预填；停止后不上演回退重放；无额外额度；日夜、1080P/4K 人工通过
Issue 002 PC 视觉回档	16 页日间/夜间、1920×1080、4K 无白块、遮挡、双滚动和功能回归；当前差异可解释；提交可独立回退
Issue 003 移动端	320/375/390/430/768 及横屏无页面横溢；底部五入口、市场子导航、弹窗/抽屉、宽表和键盘交互可用；用户逐页验收
Issue 004 完整 IC	行业内去极值、z-score、行业/市值中性化、过去 12 月下期收益 Rank IC、季度重算、前 5% 均有版本化确定性测试；无未来函数；UI 明确基础/IC 模式
Issue 005 政策宏观隔夜	合法稳定来源、字段/单位/时间/版权/新鲜度登记完整；历史归档可复现；缺失显式失败；消息只按确认规则进入竞价量化
Issue 006 一致预期	五类字段有 point-in-time 历史、公告时点和覆盖率；策略缺数据与无命中可区分；回测无未来函数
Issue 007 Level-2	有正式授权；委托队列/逐笔/快照时间可追溯；盘中断线不伪造；与 9:25 最终归档区分；回放测试通过
Issue 008 游资画像	名录、别名、席位归类和历史操作可追溯；未知席位保留；同名误合并有回归测试；左名录右详情无超长弹窗
Issue 009 文档漂移	活跃文档、端口、移动端状态、完成状态与注册表一致；历史迁移文档明确只作审计，不被当运行说明；文档链接有效
Issue 010 在线就绪	/api/health 可达；登录和最近真实快照正常；数据源与 LLM 分别可诊断；失效凭据不泄露；重启后任务与结果不重复
Issue 011 公网部署	完成 ADR；TLS、可信 Host、限流、集中密钥、审计、备份恢复、多实例数据库和任务互斥全部通过；不破坏局域网数据边界

9.1 通用自动验收

cd C:\Users\MoBai\Documents\gupiaofupan\webapp\app
python tools/verify_baseline.py
python tools/verify_baseline.py --e2e
git diff --check

9.2 通用人工验收

• 普通、会员、管理员三种权限。
• 正常、有数据为空、数据缺失、上游失败、请求超时、最近快照九类状态。
• 日间、夜间、1920×1080、3840×2160；移动 Issue 开始后再加入完整移动视口矩阵。
• 真实行情日期与图表一致；开盘前不制造当天空 K 线。
• 用户甲乙的自选、复盘、日志、对话、问天历史互不可见。
• 所有保存/删除/添加只出现可关闭的规范反馈，不出现超长空弹窗。
• 密钥、数据库、日志和私有 Skill 不进入 Git diff。

10. 验证记录

2026-08-06 本轮结果；后续代码变化后不能沿用：

• Python：326 个测试全部通过（约 11.8 秒）。
• Playwright：49 个测试全部通过（约 2.2 分钟）。
• API 注册表与架构清单：均为 current。
• JavaScript：统一工具枚举的全部 .js/.mjs 均通过 node --check。
• SQLite：data/review.db 的 PRAGMA integrity_check 为 ok，验证时大小为 455,434,240 字节。
• Git：git diff --check 通过。
• 说明：组合命令在本代理的 120 秒命令上限处被终止于 Playwright 阶段；Playwright 随后以同一配置单独运行并完整通过，因此上述各子项均有本轮实际结果。