> ⚠️ **本文档已过时，仅留档备查，请勿删除。**
> 本交接说明核实于 2026-08-06，其中「当前提交」「当前状态」「正在处理的事项」「验证记录」等已与代码现状不符（当时的未提交改动现已合并，项目已推进到全站视觉统一收尾阶段）。
> 最新内容请看 `docs/项目需求.md`、`docs/最新进度.md`、`docs/任务清单.md` 和 `docs/README.md`。
> 架构与维护规矩仍以根目录 `AGENTS.md`、`ARCHITECTURE.md` 为准；本文第 2、6 节（架构与决策）仍可作参考。

# 小白复盘项目交接说明

> 核实日期：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 前端。

```text
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](issues/ISSUE-001-finalize-mentor-redesign.md) | 待人工验收/提交 | P0 | 问师三栏界面、停止生成和动态追问收口 |
| [ISSUE-002](issues/ISSUE-002-checkpoint-current-pc-visual-work.md) | 待审查/提交 | P0 | 当前全站 PC 视觉改动的逐页验收、拆分和回档点 |
| [ISSUE-003](issues/ISSUE-003-mobile-redesign.md) | 明确延期 | P2 | 独立移动 Shell、逐页信息架构和触控交互 |
| [ISSUE-004](issues/ISSUE-004-full-ic-multifactor.md) | 未实现 | P1 | 12 个月 Rank IC、季度重算、中性化和前 5% 输出 |
| [ISSUE-005](issues/ISSUE-005-policy-macro-overnight-data.md) | 数据源未定 | P1 | 稳定政策/宏观/隔夜消息序列与竞价量化 |
| [ISSUE-006](issues/ISSUE-006-analyst-consensus-data.md) | 数据阻塞 | P2 | 一致预期、预测修正、评级/目标价等字段 |
| [ISSUE-007](issues/ISSUE-007-level2-auction.md) | 授权阻塞 | P2 | Level-2 委托队列、逐笔和动态竞价深度 |
| [ISSUE-008](issues/ISSUE-008-hot-money-profile-history.md) | 低优先级 | P3 | 游资档案的更完整历史画像和归类质量 |
| [ISSUE-009](issues/ISSUE-009-documentation-status-drift.md) | 待整理 | P1 | 活跃文档/注册表中移动端、端口和验收状态漂移 |
| [ISSUE-010](issues/ISSUE-010-live-provider-llm-readiness.md) | 待运行核验 | P0 | 启动正式服务并验证数据源、iFinD、LLM 与任务健康 |
| [ISSUE-011](issues/ISSUE-011-public-deployment-hardening.md) | 未来范围 | 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 通用自动验收

```powershell
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 随后以同一配置单独运行并完整通过，因此上述各子项均有本轮实际结果。