docs: 整理 app/docs 交接手册（需求/进度/任务/首页）并标记旧版 HANDOFF

Co-authored-by: multica-agent <github@multica.ai>

docs/HANDOFF.md

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

docs/README.md

@@ -1,11 +1,35 @@
-# 文档索引
+# 小白复盘 · 交接手册首页（首页说明）
 
-- `product/小白复盘-完整产品规格说明书.md`：从零恢复产品时的完整功能与行为资产。
+> 一句话：这是「小白复盘」项目的交接手册入口。新来的智能体（或人）先看这一页，再按下面顺序读四份文档，就能知道这个项目是干什么的、干到哪了、下一步做什么。
-- `HANDOFF.md`：当前仓库、架构、完成度、风险和后续验收的交接基线。
-- `issues/README.md`：尚未完成事项的独立 Issue 索引；Issue 不是已创建的 Gitea 工单。
-- `maintenance/人工维护指南.md`：当前正式源码的启动、修改、验收、数据和回退流程。
-- `governance/`：架构决策、注册表治理和历次结构治理记录。
-- `migration/`：从旧根目录保真迁入`app/`的历史账本、证据和失败版本记录。
 
-日常维护优先阅读根目录`AGENTS.md`、`ARCHITECTURE.md`、`HANDOFF.md`和维护指南。`migration/`只用于审计与
+## 先读哪些文件（按顺序）
-追溯，不参与应用启动、测试选择或运行时路径解析。
+
+1. `项目需求.md` —— 这个项目是干什么的、要解决什么问题、有哪些功能。
+2. `最新进度.md` —— 目前整体做到哪一步了。
+3. `任务清单.md` —— 正在做 / 已做完 / 还没安排，三栏一目了然。
+4. 本文件 `README.md` —— 就是你现在看的这一页。
+
+读完上面四份，就算“接手”了。想深入了解实现细节，再往下读。
+
+## 想深入了解时再读这些
+
+- `product/小白复盘-完整产品规格说明书.md` —— 最完整、最权威的“产品需求”说明书，从零重建项目都用它。
+- `maintenance/人工维护指南.md` —— 怎么启动、怎么改代码、怎么跑测试、怎么备份和回退。
+- `governance/` —— 架构决策和历次结构治理记录。
+- `migration/` —— 从旧代码保真迁进 `app/` 的历史账本和证据，只用于审计和追溯，不参与运行。
+- 根目录的 `AGENTS.md`（维护硬规矩）、`ARCHITECTURE.md`（技术架构）。
+
+## 更新规矩（每完成或新增一个任务都要做）
+
+任何智能体完成或新增一个任务后，必须顺手把这份手册更新到位，不能只改代码：
+
+1. 任务做完或新增 → 更新 `任务清单.md`：把任务从「正在做」挪到「已做完」，或把新任务加进对应栏目。
+2. 整体进度变了 → 更新 `最新进度.md`。
+3. 需求或功能变了 → 更新 `项目需求.md`（重大变化还要同步 `product/` 里的完整说明书）。
+4. 更新完提交并推送进仓库（保存并上传到放代码的网站），不能只留在自己电脑里。
+
+## 注意事项
+
+- 旧文档不能删：被替代的旧文档开头要加一行「⚠️ 本文档已过时，仅留档备查，请勿删除」，再写新版。
+- 用中文大白话写，专业词要带通俗解释，让不懂代码的人也能看懂。
+- 「问天」板块是冻结区，任何改动都不许碰；写文档时别误导后来人去改它。

docs/issues/README.md

@@ -16,4 +16,4 @@
 | [010](ISSUE-010-live-provider-llm-readiness.md) | 数据源与 LLM 在线就绪核验 | 待运行核验 | P0 |
 | [011](ISSUE-011-public-deployment-hardening.md) | 公网部署加固 | 未来范围 | P3 |
 
-关闭任一 Issue 前，必须更新 `docs/HANDOFF.md` 的状态、验证日期和回档提交；不能只改 Issue 标题。
+关闭任一 Issue 前，必须同步更新 `docs/最新进度.md` 与 `docs/任务清单.md` 的状态、验证日期和回档提交；不能只改 Issue 标题。旧版 `docs/HANDOFF.md` 已过时，仅留档备查。

docs/任务清单.md

@@ -0,0 +1,35 @@
+# 任务清单
+
+> 分三栏：正在做 / 已做完 / 还没安排。以任务板（Multica）和仓库内 `issues/` 目录为准，核实日期 2026-08-23。
+
+## 正在做
+
+| 任务 | 说明 | 状态 |
+|---|---|---|
+| 全站视觉统一改造收尾 | 主线。17 个阶段已完成，正在最终验收、代码合并 | 收尾中 |
+| 手机端独立重新设计 | 先出视觉/交互规范和技术架构方案，等老板确认后再施工 | 方案送审中 |
+| 仓库交接手册整理 | 本批文档（任务卡 HEL-62） | 进行中 |
+
+## 已做完
+
+| 任务 | 说明 |
+|---|---|
+| 全站视觉统一改造（17 个阶段） | 公共外壳、各市场数据页、智能工具页、账户页、顶栏布局返工等，逐批通过功能 + 视觉双重审核 |
+| 数据库历史问题修复收口 | 老数据未被改动 |
+| 顶端栏图标对齐 | 集合竞价 / 题材库 / 人气热榜三页，已部署 `.36:8765`（提交 `ed9858e`） |
+| 情绪周期页头改造等页面细节 | 去背景框、圆角分段控件 / 导出按钮（任务卡 HEL-31/36/42 等） |
+| 架构治理（保真迁移） | 从旧根目录迁进 `app/`，模块化单体 + 注册表 + 统一验收工具，2026-08-01 人工验收 |
+
+## 还没安排
+
+| 任务 | 说明 | 大致优先级 |
+|---|---|---|
+| 游资档案历史画像 | 更完整的游资历史操作画像 | 低 |
+| 完整 IC 动态多因子选股 | 需要约 12 个月历史数据做因子有效性计算 | 中 |
+| 公网部署加固 | 多实例、TLS、PostgreSQL 等（当前只内网用） | 低 / 未来 |
+| 政策 / 宏观 / 隔夜消息数据 | 数据源还没定 | 中 |
+| 分析师一致预期数据 | 数据源被阻塞 | 中低 |
+| Level-2 竞价深度 | 需要授权 | 中低 |
+
+> 说明：手机端施工，以及上面这些数据/算法类功能，做之前都要先和老板确认优先级，不要擅自开工。
+> 仓库内更细的任务说明见 `issues/` 目录（ISSUE-001 到 ISSUE-011）。

docs/最新进度.md

@@ -0,0 +1,33 @@
+# 最新进度
+
+> 核实日期：2026-08-23，以代码仓库当前提交 `ed9858e` 为准。
+
+## 一句话总结
+
+项目主体功能早就做好并上线内网了。当前主线是「全站视觉统一改造」，已经走完 17 个阶段，正处于**最终验收、代码合并的收尾阶段**。同时新开了一条「手机端独立重新设计」的线（还在出方案，没动工），以及本手册的整理工作。
+
+## 已经做到哪了
+
+- **代码结构**：已经从历史杂乱目录保真迁移进 `app/`，整理成「模块化单体」（一个 Python 进程、一个 SQLite 数据库、不需要构建工具的前端），用户在 2026-08-01 人工验收通过。
+- **功能**：16 个主工作区都有正式实现（见 `项目需求.md`）。
+- **视觉统一**：17 个阶段全部完成，每批都过了功能和视觉双重审核，返修版已部署到内网验收地址 `192.168.200.36:8765`。
+- **数据库历史问题**：已修复收口，老数据没有被改动。
+- **最近的代码改动**（2026-08 下旬）：主要是视觉收尾的细节——顶端栏图标对齐、设计令牌统一、问师/情绪周期等页面样式修整等，已合并进 `main`，并部署到内网 `.36:8765`。
+
+## 正在做的事
+
+1. **全站视觉统一改造收尾**：最终验收 + 代码合并（主线）。
+2. **手机端独立重新设计**：先出视觉规范和架构方案，等老板确认后再施工（见 `任务清单.md`）。
+3. **整理仓库交接手册**：就是这批文档。
+
+## 哪些还不能算“完成”
+
+- **手机端**：当前有样式但基本是电脑端缩小，不可用。正在按“独立手机产品”重新设计，还没施工。
+- **一些依赖外部数据/算法的高级功能还没做**：完整 IC 动态多因子选股、政策/宏观/隔夜消息、分析师一致预期、Level-2 竞价深度、游资档案历史画像（详见 `任务清单.md`）。
+- **公网部署**：现在只在内网用，还没做公网加固。
+
+## 关键时间点
+
+- 2026-08-01：`app/` 保真迁移完成，用户人工验收通过。
+- 2026-08-06：上一版交接说明（`HANDOFF.md`）生成（现已过时，仅留档）。
+- 2026-08-21：视觉收尾提交 `ed9858e` 合并进 `main`，部署到内网 `.36:8765`。

docs/项目需求.md

@@ -0,0 +1,46 @@
+# 项目需求
+
+> 大白话版。逐页、逐字段的完整需求请看 `product/小白复盘-完整产品规格说明书.md`（那是最权威的“说明书”，从零重建项目都用它）。
+
+## 这个项目是干什么的
+
+「小白复盘」是一个给老板个人用的股票复盘工具网站，放在内网访问（地址 `192.168.200.36:8765`）。
+
+它不是炒股下单软件，而是「收盘后和开盘前」用来复盘、观察市场的工具：
+
+- 把当天（或最近）的真实行情、涨停跌停、板块轮动、集合竞价等信息整理清楚，帮老板复盘。
+- 提供智能选股、问师（跟“游资思维”老师对话）等辅助分析。
+- 记录自己的交易和复盘。
+
+一句话：它帮你“看清市场、想清楚思路、记下来”，但不替你做买卖决定。
+
+## 要解决什么问题
+
+1. **市场信息太散**：涨停池、炸板池、跌停板、龙虎榜、人气榜、板块轮动这些信息本来分散在各处，这个网站把它们集中到一处，还配了日间/夜间两套配色，看起来统一。
+2. **复盘靠脑子记不住**：提供“我的复盘”和交易日志，把每天的判断、操作、情绪记录下来。
+3. **选股没思路**：智能选股用规则和因子（影响股价的数据指标）帮你筛出候选股票。
+4. **想听“高手”怎么看**：问师模块可以按不同的游资思维（比如佛山无影脚、北京炒家等）跟老师对话。
+
+## 主要功能（板块）
+
+登录后侧栏有 16 个主工作区，默认进入「情绪周期」：
+
+- **市场类（12 个）**：情绪周期、涨停池、炸板池、跌停板、昨日涨停、涨停表现、市场天梯、板块轮动、集合竞价、题材库、人气热榜、龙虎榜。
+- **智能工具类（3 个）**：智能选股、问师、问天。
+- **个人类（1 个）**：我的复盘。
+
+其中「问天」是冻结区（见下面的硬规矩）。
+
+## 几条硬规矩（不能破坏的边界）
+
+- 「问天」板块是**冻结区**，任何改动都不许碰它。
+- **不用假数据冒充真行情**；数据缺失就明说“没有/不可用”，不能编。
+- **每个用户自己的数据互相隔离**（自选、复盘、对话、问天历史等），看不到别人的。
+- **计算由程序确定性完成**（情绪周期、智能选股、问天排盘等），AI 大模型（LLM，就是会聊天的那个 AI）只负责解释或编译自然语言条件，不能改计算结果。
+- **不接券商、不自动下单**，不承诺收益。
+
+## 权限
+
+- **普通用户**：能用大部分市场页面和「我的复盘」。
+- **会员**：额外能用智能选股、问师、问天（需要管理员开通）。
+- **管理员**：管理公共行情密钥、会员额度和系统配置等。