# 技术分析与复刻范围

## 证据与范围

依据用户提供账号的正常登录流程、返回的 HTML/JS/CSS 和只读数据接口。没有访问服务器文件系统、数据库或管理员后台，也没有绕过功能权限。源码归档、请求参数、响应状态与 JSON 文件可在相邻文档中逐项追溯。

前端资源可以完整保留已访问页面的客户端逻辑；后端内部代码、数据库结构、定时采集器和计算模型只能根据客户端契约推断，不能声称已恢复。这次没有抓取所有交易日和所有标的的历史数据库。

## 页面与模块

| 模块 | 路由 | 主要数据路径 | 已保留的客户端功能 |
|---|---|---|---|
| 首页 | `/` | 静态展示与入口 | 导航、说明入口、主题 |
| 资金驾驶舱 | `/photosynthesis-finance-terminal/dashboard` | `/photosynthesis-finance-terminal/api/v2/dashboard/page-vm`，失败回落 first-paint 等 | 市场概览、自选卡片、发现列表、提醒、详情抽屉 |
| 自选关注 | `/photosynthesis-finance-terminal/watchlist` | `/photosynthesis-finance-terminal/api/v2/watchlist/items`、search | 分类、搜索、添加、删除；写入由本地服务接管 |
| 主力动向 | `/photosynthesis-finance-terminal/chart`、`/photosynthesis-finance-terminal/chart/embed/watch` | watch-sectors、history、intraday、replay-* | 选择板块、资金曲线、相对变化、回放、侧栏、详情 |
| 个股动向 | `/photosynthesis-finance-terminal/stock-flow` | stock-flow realtime-range/replay-range、history | 默认五股、名称检索、金额/标准化、多日回放、质量状态 |
| 资金拥挤 | `/photosynthesis-finance-terminal/chart/crowding` | crowding market/sector/stock | 总览、指标、榜单和模型可用性提示 |
| ETF 追踪 | `/photosynthesis-finance-terminal/etf-tracker` 及 flow/change 嵌入页 | etf-flow bootstrap/history/intraday、v2/etf/detail-vm | ETF 选择、曲线、涨跌列表、回放和详情 |
| 题材中枢 | `/photosynthesis-finance-terminal/theme-library` | themes/list/detail、v2/theme-hub/* | 题材筛选、分支、成分股、关联与新闻 |
| 市场快讯 | `/photosynthesis-finance-terminal/market_news_dashboard.html` | market-news summary/items | 列表、分类、搜索、分页和展开；本地仅有采集批次 |
| 集合竞价 | `/photosynthesis-finance-terminal/chart/auction` | auction dashboard/cache/replay | 早盘/尾盘、股票/板块排名、竞价回放 |
| 强势雷达 | `/photosynthesis-finance-terminal/chart/radar` | radar bootstrap/dashboard/curves/events/rankings | 实时榜单、异动事件、分时曲线、历史回放 |
| 暗盘隔夜 | `/photosynthesis-finance-terminal/chart/overnight` | overnight summary/dark/*/heat/* | 隔夜与热度列表、侧栏 |
| 情绪与天梯 | sector-emotion、market-emotion、limit-ladder | 对应同名 API | 板块情绪、市场情绪、连板梯队 |
| 手机版本 | chart/mobile、etf-tracker/mobile 及嵌入页面 | 复用上述 API | 手机布局、筛选、回放控制 |
| 账号与说明 | me、login、activate、change-password、manual、membership 等 | 表单及静态页面 | 界面归档；真实登录使用本地控制台，兑换/改密不提交 |

“保留客户端功能”指保留原始实现，并不表示每个按钮都已经浏览器验收。有限快照无法覆盖每一个筛选组合；在线模式用于读取未归档的合法请求。

## 客户端架构

页面是服务端返回的多页 HTML，不是单一打包的 React SPA。大量页面直接内联业务逻辑，公共功能分散在 static 下。CSS 桌面壳使用 226px 侧栏，移动布局采用媒体查询和独立嵌入页面。主题由 `sf-theme` 本地存储控制，共享 theme-tokens.css 与 chart-theme-adapter.js。

图表依赖 `static/echarts.min.js`。主力动向主体在 `static/watch_flow/desktop.js`，个股主体在 `static/stock_flow/validation.js`。回放抽象分布在 `static/replay_core/`，数据质量和交易日处理分布在 `static/m18/`、`static/m19/`。本次扫描到的主体数据链路使用 fetch 轮询；没有观察到必须实现的 WebSocket/SSE 通道。

V2 页面优先消费页面视图模型（page-vm/bootstrap）或详情 host_dto，失败时转向旧接口或本地组件。`v2_*_bypass.js` 是原站自己的兼容适配层文件名，其内容不是本项目进行权限绕过的实现。详情以 type、id、source_page、source_action 定位 stock/sector/theme/ETF 上下文。

## 数据协议与口径

- 主力、ETF 常见结构：`items`、`timeline`、`by_code`、`trade_date`、`last_minute`；多日回放还包含日期集合与各代码历史序列。
- 个股查询：POST `/photosynthesis-finance-terminal/api/stock-flow/realtime-range`，请求体 `{codes:[...],days:1}`；多日使用 replay-range。默认代码为 000001、000333、300750、600519、688981。
- 资金字段 `main_net` 以元计，`main_net_yi` 为亿元展示字段。不要将百分比字段 `pct` 与净流入金额混用。
- 个股 `normalizeDayPoints` 按序列最大绝对净流入值归一化：`main_net / maxAbs × 100`；支持调用者传入固定比例尺。它不是收益率或 z-score。源码见 validation.js 的同名函数。
- 多日展示可组合 `cumulative_main_net` 和 `day_offset`；回放 UI 根据数据集和状态机前进，不应以模拟正弦曲线替换原始行情。
- 日期不可只看设备日历：响应含 `display_date`、`curve_date`、`latest_trade_date`、`last_trade_date`、`trade_status`、`data_mode`。午休、非交易日、盘前和采集延迟有不同路径。
- 数据可信度需保留 `source`、`quality`、`stale/is_stale`、`fallback_reason`、`data_time`。本次样本中实际出现 fallback 和缓存数据，因此不能把所有 200 响应称为无延迟实时行情。
- 原站注释和资源命名出现 Flask、collector、cache 等线索，只能作为后端架构推断；没有服务器代码证据时不能确认框架版本、数据库类型或完整拓扑。

## 本地实现

Node.js 标准库 HTTP 服务将路由映射到归档 HTML，静态资源保持原始路径，动态数据由 `data/index.json` 定位。响应时注入本地模式标记；对原站 trade_date_resolver.js 做了一处有记录的修改，使离线模式显示快照状态。其余业务源码保留，发布构建阶段统一适配仓库路径、名称和账号入口。

请求 key 包含方法、排序后的查询参数及 POST JSON。精确命中优先；兼容命中检查日期、实体、时间范围和代码覆盖，避免不同股票或交易日串用数据。没有样本时返回明确的 `offline_snapshot_missing`，控制台列出缺失请求。搜索在已采集股票/板块/ETF/题材目录中执行；快讯分页在已采集列表内执行。

在线代理固定目标为原站域名，只转发已发现的 GET 路径及明确列出的 POST 查询。密码只用于正常登录；认证 Cookie 不返回浏览器、不写文件。15 秒内相同在线查询可复用内存缓存。上游失败返回明确错误，不静默将旧行情当作在线数据。

本地自选和板块设置持久化到 .runtime/preferences.json，优先于在线读取。采集任务触发接口由本地响应接管，新闻写入、账号注册、密码变更和会员兑换不转发。

## 未完成或无法由客户端恢复的部分

1. 原站服务器源码、数据库、行情供应商私有协议、指标计算与定时采集作业。
2. 所有标的与所有交易日的完整历史数据；当前离线样本仅覆盖列出的请求。
3. 所有新闻附件和教程视频；教程 MP4 下载超时，样例 mock JSON 在原站返回 404。
4. 未开放功能与管理员工作流；静态代码出现的写接口只做记录，没有远程执行。
5. 尚未逐项验收所有交互组合和手机页面；已完成的桌面浏览器流程、截图与限制见 BROWSER_QA.md。

因此本交付应描述为“已访问前端的本地复刻、接口契约与真实快照服务”，不能称为原站全栈源码完整恢复。

## Pages 适配与源码改动

local/offline-engine.mjs 在 Node.js 与浏览器之间共享请求匹配、目录检索、自选、驾驶舱联动、提醒过滤与快讯分页逻辑。local/pages-bootstrap.js 在原站业务脚本前接管 fetch，从静态 JSON 读取真实采集数据；缺失请求明确提示。它不连接原站认证服务。

scripts/build-pages.mjs 生成带仓库前缀的多页网站，将账号入口替换为说明页，并清理账号标识与认证字段。账户 Cookie、密码和本地偏好文件不包含在发布包中。公开版文字和状态说明与离线数据一致；原站尚未开放的“板块涨幅”仍保留原有提示。
