人工维护手册（失败实现历史资料）

next/已被冻结，禁止依据本手册继续维护或扩展该实现。后续保真迁移不得把这里的结构当作既定方案。权威冻结决定见../../../docs/migration/next失败冻结记录.md。

从哪里开始

产品行为先查../../../docs/product/小白复盘-完整产品规格说明书.md，迁移约束查 ../../../docs/migration/重建迁移章程.md。新代码根目录只有next/；旧根目录代码不得作为新运行时依赖。

请求主链为：页面 -> shared/api -> HTTP Route -> Service -> Repository/DataGateway/LLMGateway。 bootstrap/container.py是唯一依赖组装点，页面注册在workspaceRegistry.ts，数据库版本在 database/migrations/registry.py按连续编号登记。

常见改动

改动	修改入口	必须补的测试
页面字段/布局	对应`frontend/src/pages`与领域CSS	日夜、1080P、4K、390px
新市场页面	页面+`workspaceRegistry.ts`+市场Route/Service	空态、缺失、日期、移动入口
数据源字段	Provider契约+DataGateway策略	来源、单位、新鲜度、覆盖率、失败关闭
情绪/竞价/选股公式	纯计算模块+版本字段	固定样本、边界、缺失与确定性
新策略	`config/screener-strategies.json`	因子覆盖、无信号、数据不足、顺序稳定
新思维模型	公开或私有Skill目录	目录发现、等级、私密性、上下文路由
LLM功能	业务Prompt+唯一`LLMGateway`	会员、配额、回退、中断、去重
私有记录	领域Repository每条SQL带`user_id`	甲乙账号交叉读写删
数据表变更	新增连续migration	前进、失败原子性、回退、旧库升级

不要在页面直接fetch、在Feature直接访问外网、在Controller计算评分、为单页创建第二个弹窗或把颜色/间距写成新字面值。确需新共享抽象时，至少应有两个真实调用方或消除一个高风险全局出口。

数据源维护

Tushare：交易日、目录、日线、正式盘后事件和财务基础。
iFinD：实时K线、分时、动态竞价和已授权补充字段。
东方财富：仅展示分时兜底，不进入正式计算。
腾讯：已登记但无正式消费者前不创建空Provider。
每个保存结果都要带来源、实际日期、观察时间、用途、复权、单位、新鲜度和覆盖率。
供应商失败不得返回模拟数据；跨源替代必须在DataSourcePolicy显式登记并向用户显示实际日期。

日常命令

cd next
.\.venv\Scripts\python.exe -m tools.database status
.\.venv\Scripts\python.exe -m ruff check backend tools tests
.\.venv\Scripts\python.exe -m pytest
cd frontend
npm.cmd run check
npm.cmd run test
npm.cmd run build
cd ..
npx.cmd playwright test

数据库status只读查询，不执行升级。应用启动时执行有序前进migration；显式回退只允许在副本演练。生产代码回退不自动降级数据，需恢复升级前整套备份。

故障定位

先看/api/health和结构化日志的request_id，不要从前端提示猜供应商原因。
行情问题查快照的实际日期、来源、覆盖率和质量门，再查Provider；不要直接加兜底。
LLM问题查llm_requests和llm_attempts，确认失败发生在首字前还是首字后。
私有数据问题用两个测试账号交叉验证SQL所有权，不只检查页面隐藏。
视觉问题先确认Shell、令牌和领域CSS归属，不追加override/final-fix覆盖层。
migration失败先停写并恢复备份，不编辑已执行migration的签名或SQL。

复杂度红线

页面容器超过300行、业务Service超过400行、CSS超过400行时必须复核职责并记录原因。
同一行为出现第二个算法、API客户端、外部数据出口、LLM入口或弹窗Host时必须停止合并。
新功能先更新规格、数据边界和固定案例，再写代码；删除功能先确认历史数据、导出和回退。

4.0 KiB Raw Blame History