From 733f5fd40bc22e3712d4958db504f4927c62cd1d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=96=BD=E5=B7=A5=E5=91=98?= <4846a27a-ba87-49c9-939d-7275f63efcc7@agents.multica.local> Date: Sun, 23 Aug 2026 14:07:07 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=95=B4=E7=90=86=20app/docs=20?= =?UTF-8?q?=E4=BA=A4=E6=8E=A5=E6=89=8B=E5=86=8C=EF=BC=88=E9=9C=80=E6=B1=82?= =?UTF-8?q?/=E8=BF=9B=E5=BA=A6/=E4=BB=BB=E5=8A=A1/=E9=A6=96=E9=A1=B5?= =?UTF-8?q?=EF=BC=89=E5=B9=B6=E6=A0=87=E8=AE=B0=E6=97=A7=E7=89=88=20HANDOF?= =?UTF-8?q?F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: multica-agent --- docs/HANDOFF.md | 5 +++++ docs/README.md | 42 ++++++++++++++++++++++++++++++--------- docs/issues/README.md | 2 +- docs/任务清单.md | 35 ++++++++++++++++++++++++++++++++ docs/最新进度.md | 33 +++++++++++++++++++++++++++++++ docs/项目需求.md | 46 +++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 153 insertions(+), 10 deletions(-) create mode 100644 docs/任务清单.md create mode 100644 docs/最新进度.md create mode 100644 docs/项目需求.md diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md index d793cb1..8c10b66 100644 --- a/docs/HANDOFF.md +++ b/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） diff --git a/docs/README.md b/docs/README.md index f333b8b..d51cb26 100644 --- a/docs/README.md +++ b/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. 更新完提交并推送进仓库（保存并上传到放代码的网站），不能只留在自己电脑里。 + +## 注意事项 + +- 旧文档不能删：被替代的旧文档开头要加一行「⚠️ 本文档已过时，仅留档备查，请勿删除」，再写新版。 +- 用中文大白话写，专业词要带通俗解释，让不懂代码的人也能看懂。 +- 「问天」板块是冻结区，任何改动都不许碰；写文档时别误导后来人去改它。 diff --git a/docs/issues/README.md b/docs/issues/README.md index a148a80..264249e 100644 --- a/docs/issues/README.md +++ b/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` 已过时，仅留档备查。 diff --git a/docs/任务清单.md b/docs/任务清单.md new file mode 100644 index 0000000..ea92af8 --- /dev/null +++ b/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）。 diff --git a/docs/最新进度.md b/docs/最新进度.md new file mode 100644 index 0000000..2da7c84 --- /dev/null +++ b/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`。 diff --git a/docs/项目需求.md b/docs/项目需求.md new file mode 100644 index 0000000..b01454a --- /dev/null +++ b/docs/项目需求.md @@ -0,0 +1,46 @@ +# 项目需求 + +> 大白话版。逐页、逐字段的完整需求请看 `product/小白复盘-完整产品规格说明书.md`（那是最权威的“说明书”，从零重建项目都用它）。 + +## 这个项目是干什么的 + +「小白复盘」是一个给老板个人用的股票复盘工具网站，放在内网访问（地址 `192.168.200.36:8765`）。 + +它不是炒股下单软件，而是「收盘后和开盘前」用来复盘、观察市场的工具： + +- 把当天（或最近）的真实行情、涨停跌停、板块轮动、集合竞价等信息整理清楚，帮老板复盘。 +- 提供智能选股、问师（跟“游资思维”老师对话）等辅助分析。 +- 记录自己的交易和复盘。 + +一句话：它帮你“看清市场、想清楚思路、记下来”，但不替你做买卖决定。 + +## 要解决什么问题 + +1. **市场信息太散**：涨停池、炸板池、跌停板、龙虎榜、人气榜、板块轮动这些信息本来分散在各处，这个网站把它们集中到一处，还配了日间/夜间两套配色，看起来统一。 +2. **复盘靠脑子记不住**：提供“我的复盘”和交易日志，把每天的判断、操作、情绪记录下来。 +3. **选股没思路**：智能选股用规则和因子（影响股价的数据指标）帮你筛出候选股票。 +4. **想听“高手”怎么看**：问师模块可以按不同的游资思维（比如佛山无影脚、北京炒家等）跟老师对话。 + +## 主要功能（板块） + +登录后侧栏有 16 个主工作区，默认进入「情绪周期」： + +- **市场类（12 个）**：情绪周期、涨停池、炸板池、跌停板、昨日涨停、涨停表现、市场天梯、板块轮动、集合竞价、题材库、人气热榜、龙虎榜。 +- **智能工具类（3 个）**：智能选股、问师、问天。 +- **个人类（1 个）**：我的复盘。 + +其中「问天」是冻结区（见下面的硬规矩）。 + +## 几条硬规矩（不能破坏的边界） + +- 「问天」板块是**冻结区**，任何改动都不许碰它。 +- **不用假数据冒充真行情**；数据缺失就明说“没有/不可用”，不能编。 +- **每个用户自己的数据互相隔离**（自选、复盘、对话、问天历史等），看不到别人的。 +- **计算由程序确定性完成**（情绪周期、智能选股、问天排盘等），AI 大模型（LLM，就是会聊天的那个 AI）只负责解释或编译自然语言条件，不能改计算结果。 +- **不接券商、不自动下单**，不承诺收益。 + +## 权限 + +- **普通用户**：能用大部分市场页面和「我的复盘」。 +- **会员**：额外能用智能选股、问师、问天（需要管理员开通）。 +- **管理员**：管理公共行情密钥、会员额度和系统配置等。