70 lines
3.8 KiB
Markdown
70 lines
3.8 KiB
Markdown
# 人工维护手册
|
|
|
|
## 从哪里开始
|
|
|
|
产品行为先查`../../../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时必须停止合并。
|
|
- 新功能先更新规格、数据边界和固定案例，再写代码；删除功能先确认历史数据、导出和回退。
|