文档地图

按你想做什么找，不按文档名找。每条注明大致篇幅——先读小的，需要时再往下挖。

我想……

意图	去读	篇幅
知道这东西是什么、跑起来看看	../README.md	2 分钟
把它部署到本机	DEPLOY.md	5 分钟
调用 HTTP 接口	API.md	10 分钟，可当参考手册查
改代码 / 加功能	DEVELOPMENT.md	15 分钟
线上出问题了	OPERATIONS.md	按症状跳读
理解某个设计为什么是这样	ARCHITECTURE.md	长，按 §跳读
知道某个上游接口的真实口径	`probe-*.md`	长，按数据源查
知道某个行为的规格（MUST/SHALL）	`../openspec/specs/`	20 个 capability

四层结构

文档按「需要多少上下文才读得懂」分层。从上往下读，任何一层都能停：

第 0 层  README.md                这是什么、为什么、怎么跑起来
第 1 层  DEPLOY / API / OPERATIONS / DEVELOPMENT
                                  做具体的事。任务导向，互不依赖，可单独读
第 2 层  ARCHITECTURE.md          为什么是这样。设计决定与它们的代价
第 3 层  probe-*.md / openspec/   一手证据与形式规格

上层链接下层而不复述它。发现两处讲同一件事时，正确做法是删掉上层那份、留个链接—— 文档一旦有两份就必然分叉，而分叉的表现是「看起来都对，但只有一份是真的」。

各文档职责

第 1 层——任务导向

	回答的问题	不回答
DEPLOY.md	怎么起、首次启动会做什么、数据存哪	出问题怎么办（→ OPERATIONS）
API.md	有哪些接口、请求响应长什么样、错误码	接口背后的算法（→ ARCHITECTURE §6）
OPERATIONS.md	症状 → 排查步骤 → 处置	为什么会有这个故障模式（→ ARCHITECTURE）
DEVELOPMENT.md	环境、测试、改动流程、约定	具体模块怎么写（→ 读代码，注释很厚）

第 2 层——设计权威

ARCHITECTURE.md 是命名、目录、Schema、契约的唯一权威。代码与它不一致时，以它为准或改它，不要两边各说各话。§10「全局红线」是全项目的不可协商约束，改任何东西前先读那一节。

第 3 层——一手材料

probe-*.md 是上游数据源的实测记录：字段真名、单位、复权口径、返回体形状、哪些接口在什么情况下返回空。它们的价值在于已经踩过的坑不必再踩——比如港股财报字段与 A 股完全不同、东财与新浪的复权因子不是同一种口径。

openspec/specs/ 是行为规格（MUST / SHALL / SHALL NOT），20 个 capability。 openspec/changes/archive/ 保留 23 个已完成变更的提案与设计记录，含被否掉的方案。

找不到想要的？

代码注释是本项目的第一手文档，密度远高于常规项目——设计理由、踩过的坑、为什么不用另一种写法，大多写在实现旁边而不是文档里。找具体行为时直接读代码往往比翻文档快。

入口建议：backend/app/ingest/base.py（采集层公共设施）、 backend/app/valuation/engine.py（估值入口）、backend/app/clean/normalize.py（清洗）。

FilesExpand file tree

README.md

Latest commit

History