docs(readme): consolidate truth-index and docs navigation

docs/REAL_HOST_ACCEPTANCE_LEARNINGS.md

@@ -0,0 +1,173 @@
+# 真实宿主验收经验与已调通细节
+
+日期：2026-05-21
+
+## 目的
+
+这份文档不替代 `docs/REAL_HOST_ACCEPTANCE_RUNBOOK.md`，而是把已经在线下真实打通过、以及多次踩坑后确认的细节沉淀下来，避免后续重复误判。
+
+建议阅读顺序：
+1. `docs/EXECUTION_BOARD.md` —— 看当前 gate 与最新真相
+2. `docs/REAL_HOST_ACCEPTANCE_RUNBOOK.md` —— 看标准执行步骤
+3. 本文 —— 看调试经验、误判点、诊断顺序
+
+## 已经确认打通的事实
+
+1. account 视角模型暴露可以正确落库
+   - CRM 在 account 创建/导入时写入 `credentials.model_mapping`
+   - 宿主 `GET /api/v1/admin/accounts/:id/models` 已能返回目标 provider 模型，而不是一律回退到 GPT 默认集合
+   - DeepSeek / MiniMax 都已在 live 验收中确认
+
+2. channel 视角模型映射与定价可以正确落库
+   - channel 创建时需要同时下发：
+     - `model_mapping`
+     - `model_pricing`
+     - `restrict_models=true`
+     - `billing_model_source=channel_mapped`
+   - 对既有 channel，CRM 需要走 `UpdateChannel` 做纠偏；这一点已在 latest-head fresh rerun 上确认生效
+   - 旧现象“MiniMax channel 有 model_mapping 但没有 pricing”已经被 `ca1d448` 修复并完成 live 验证
+
+3. subscription 场景的真实 probe key 语义已经确认
+   - closure 最终用于宿主 `/v1/models` 探测的，不是外部传入的原始 `access_api_key`
+   - 真正使用的是 CRM 在宿主侧创建/查找出来的 managed key（`sk-relay-*` 风格）
+   - 因此 subscription 验收如果直接拿调用方原始 probe key 去打 `/v1/models`，出现 `403 not assigned to any group` 并不代表 CRM 主链路失败，而是 probe key 用错了
+
+4. group 聚合视角与 account 单体视角必须分开看
+   - `GET /api/v1/admin/accounts/:id/models` 是 account 单体视角
+   - `GET /v1/models` 是普通用户 key + group 聚合视角
+   - 二者语义不同，不能互相替代
+   - 正确诊断顺序应该是：
+     1) 先看 account models 是否正确
+     2) 再看 managed key 视角 `/v1/models` 是否正确
+     3) 最后才看 completion smoke 是否通过
+
+## 已调通的宿主侧前置动作
+
+### self_service
+
+至少满足：
+1. 普通用户已真实创建
+2. 普通用户 key 已生成且可用
+3. 该 key 已绑定目标标准 group
+4. 用户具备可用余额
+
+经验结论：
+- 若只做了 key/group 绑定但没余额，`/v1/models` 可能从 403 进入 `INSUFFICIENT_BALANCE`
+- 这不是 CRM 导入逻辑失败，而是宿主运营前置未完成
+
+### subscription
+
+至少满足：
+1. 普通用户已真实创建
+2. 普通用户 key 已生成且可用
+3. 目标 group 是 `subscription` 类型
+4. 普通用户已完成 subscription 分配
+5. 普通用户 key 已绑定该 subscription group
+
+经验结论：
+- 只有管理员主体、只有 group、或者只有 subscription 记录都不够
+- 必须把“普通用户 + key + group + subscription”整条链补齐，`/v1/models` 才会稳定通过
+
+## 已确认的高频误判点
+
+1. 把 `/accounts/:id/models` 和 `/v1/models` 混为一谈
+   - 前者对，后者错，不代表 account 落库失败；往往是 key/group/subscription 问题
+
+2. 用错 probe key
+   - subscription 场景拿原始 `access_api_key` 直打宿主 `/v1/models`，很容易得到 403
+   - 这时应先回到 closure 结果或 managed access 证据，而不是先否定产品链路
+
+3. 旧 CRM 进程误导当前结论
+   - live 行为必须先确认运行中的 CRM 进程是否真的包含最新提交
+   - 之前 MiniMax existing channel 没自动补 `model_pricing`，最终确认根因就是在线 CRM 进程早于修复提交 `ca1d448`
+
+4. `PACK_PATH` 使用了 operator 机器的概念路径，而不是 CRM 进程本机可读路径
+   - 当 CRM 改在本机运行时，继续传远端 `/home/ubuntu/...` 会直接触发 `stat pack path ... no such file or directory`
+   - 这个报错属于验收 harness / 环境参数问题，不是 import 业务逻辑问题
+
+5. remote43/fresh-host 的 Postgres/Redis 容器目标写错
+   - 若脚本仍打到旧 relaymgr 宿主，会看到 managed user / key / subscription 状态为空或串台
+   - 需要确保脚本明确指向 fresh host 对应的 `{postgres,redis}` 容器
+
+6. 把 `/v1/models` 已通误认为 completion 也一定通
+   - 这不成立
+   - 当前最新真相就是：DeepSeek / MiniMax 的 `/v1/models` 可以 200，但 `/v1/chat/completions` 仍可能因为 host 兼容性或上游 quota 问题失败
+
+## 推荐诊断顺序
+
+### 一、先确认是不是环境/脚本问题
+
+1. 确认当前运行 CRM 的提交版本与启动时间
+2. 确认 `PACK_PATH` 是 CRM 本机可读路径
+3. 确认 `CRM_HOST_BASE` 是否与实际 CRM 到 host 的可达地址一致
+4. 确认脚本命中的 Postgres/Redis 容器属于目标 fresh host，而不是旧环境
+
+### 二、再确认导入数据是否正确写入宿主
+
+1. account
+   - `GET /api/v1/admin/accounts/:id`
+   - 看 `credentials.model_mapping`
+2. account models
+   - `GET /api/v1/admin/accounts/:id/models`
+3. channel
+   - `GET /api/v1/admin/channels/:id`
+   - 看：
+     - `model_mapping`
+     - `model_pricing`
+     - `restrict_models`
+     - `billing_model_source`
+
+### 三、最后再确认普通用户访问链路
+
+1. self_service：看普通用户 key/group/balance
+2. subscription：看 managed key / allowed_groups / user_subscriptions
+3. 宿主 `/v1/models`
+4. 宿主 `/v1/chat/completions`
+
+## 如何解释常见现象
+
+### 现象 A：`/accounts/:id/models` 正确，但 `/v1/models` 返回 403
+优先判断：
+- 普通用户 key 没绑定 group
+- subscription 场景用错了原始 probe key
+- subscription 分配或 allowed_groups 未完成
+
+### 现象 B：`/v1/models` 返回 GPT 系模型，而不是目标国产模型
+优先判断：
+- account `credentials.model_mapping` 是否落库
+- channel 是否同时具备 `model_mapping + model_pricing + restrict_models + billing_model_source=channel_mapped`
+- 是否误打到了旧 CRM 进程
+
+### 现象 C：`/v1/models` 已 200，但 `/v1/chat/completions` 返回 502
+优先判断：
+- host 侧 provider 兼容性问题
+- 上游 provider key/quota 问题
+- 不要再把问题回退归因为 CRM 导入或 access closure
+
+## 当前建议固化到后续文档/脚本的规则
+
+1. 所有真实宿主验收结论都要同时记录：
+   - account 视角结果
+   - managed key 视角 `/v1/models` 结果
+   - completion smoke 结果
+
+2. 任何“MiniMax/DeepSeek 没生效”的结论前，必须先检查在线 CRM 是否为最新提交
+
+3. 任何 subscription 验收脚本都不应默认把外部 `access_api_key` 当最终 probe key
+
+4. 任何 fresh-host 验收脚本都必须参数化：
+   - `PACK_PATH`
+   - `CRM_HOST_BASE`
+   - 目标 Postgres 容器
+   - 目标 Redis 容器
+
+## 相关证据入口
+
+- 当前执行真相：`docs/EXECUTION_BOARD.md`
+- 当前收口真相：`docs/PRODUCTION_CLOSURE_BOARD.md`
+- 标准操作步骤：`docs/REAL_HOST_ACCEPTANCE_RUNBOOK.md`
+- 关键 live 证据：
+  - `artifacts/real-host-acceptance/20260520_222713_crm18100_live_model_mapping_validation`
+  - `artifacts/real-host-acceptance/20260521_011544_remote43_minimax_key_import`
+  - `artifacts/real-host-acceptance/20260521_011717_remote43_deepseek_key_import`
+  - `artifacts/real-host-acceptance/20260521_064910_completion_smoke_calibration.md`