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

> `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显式登记并向用户显示实际日期。

## 日常命令

```powershell
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；显式回退只允许在副本演练。
生产代码回退不自动降级数据，需恢复升级前整套备份。

## 故障定位

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

## 复杂度红线

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