rebuild(stage-15): complete governance and handoff

next/docs/final/maintenance-guide.md

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