Isolate cloud model access before enabling product RAG workflows

The API and ingestion tools now use a fixed internal model gateway while
governed profiles, embedding cache assignments, traceable citations, and
stable API errors establish the boundaries required by later workflows.

Constraint: The current Alibaba Cloud workspace rejects all three live model calls with authentication failures
Rejected: Give the API or seed tools the Bailian key and direct egress | combines database access, cloud credentials, and public network access
Rejected: Mix offline and Bailian vectors in one demo namespace | makes profile activation and retrieval ambiguous
Confidence: high
Scope-risk: moderate
Reversibility: clean
Directive: Keep Bailian credentials and egress exclusive to model-gateway and create a new immutable profile hash for any embedding identity change
Tested: make verify; 121 backend tests; 14 frontend tests; fresh and populated Alembic upgrade-downgrade-upgrade; two idempotent offline seeds; Docker health and HTTP retrieval; isolated provider smoke
Not-tested: Successful live Bailian responses because the supplied workspace credential currently fails authentication

docs/04-project-todo.md

@@ -2,12 +2,12 @@
 
 | 项目 | 当前值 |
 |---|---|
-| 基线日期 | 2026-07-12 |
+| 基线日期 | 2026-07-13 |
 | 当前阶段 | Stage 1：模型与数据库 PoC，`IN_PROGRESS` |
 | 已完成阶段 | Stage 0：仓库、安全和设计基线 |
 | 整体完成度 | 约 12%，合理区间 10%–15% |
 | 设计完成度 | 设计基线已完成；实现中发现新约束时继续通过 ADR 和文档修订维护 |
-| 业务代码完成度 | 约 18%；Stage 1 的 Docker API、离线检索、数据库 PoC，以及 React 离线演示、Nginx 单入口和四网络隔离前置均已验收；真实百炼 smoke 仍待轮换后的新 Key |
+| 业务代码完成度 | 不以新增文件提前抬高里程碑；已增加独立 `model-gateway`、内部 token 身份、应用工厂/Problem/trace 和 `0002` profile/cache 迁移，完整产品主链路仍未完成 |
 | 当前预计剩余工期 | 约 9–13 周，含 300 题正式标注、盲测、论文和答辩缓冲 |
 | 进度权威来源 | 本文的阶段状态、验收证据和已推送提交 |
 
@@ -50,7 +50,7 @@
 | Stage 9 答辩、发布与归档 | 3% | `TODO` | 0% |
 | **合计** | **100%** | — | **12%** |
 
-Stage 1 已完成可离线验收的数据库、适配器契约、synthetic seed、只读 API 和 Web 演示子闭环，安全离线子阶段内部约完成 95%；但真实三模型 smoke 仍依赖轮换后的新 Key，因此 Stage 1 不提前计入整体里程碑。Stage 2 中不依赖云密钥的 React、Nginx、网络隔离和质量门禁前置已经完成，但 Worker 租约、完整产品工作流等必选项尚未完成，Stage 2 仍为 `TODO`。本文复选框表示“已通过验收”，不表示“文件是否已经出现”。当前可诚实表述为：**设计基线完成，整体里程碑约 12%，业务代码约 18%，Stage 1 安全离线链路可运行，真实百炼验证尚未完成。**
+Stage 1 已完成可离线验收的数据库、适配器契约、synthetic seed、只读 API 和 Web 演示子闭环，并已把百炼 Key/公网出口收敛到独立 `model-gateway`；但真实三模型请求当前均返回 401，因此 Stage 1 不提前计入整体里程碑。Stage 2 中应用工厂、Problem/trace、React、Nginx、网络隔离和质量门禁已作为前置落地，`0002_model_profiles` 迁移代码也已建立；Worker 租约、上传入库、正式检索/聊天和评测等必选项尚未完成，Stage 2 仍为 `TODO`。本文复选框表示“已通过对应层级的验收”，不表示“文件是否已经出现”。当前可诚实表述为：**设计基线完成，整体里程碑仍约 12%，安全离线链路可运行，真实百炼验证和产品主链路尚未完成。**
 
 ## 2. 阶段依赖与关键路径
 
@@ -99,8 +99,8 @@ Stage 0 DONE
 
 - `git status --short --branch` 显示 `main...origin/main`，Stage 0 基线提交远端可见。
 - `make verify-design` 可检查 Secret、设计文档、相对链接和 diff。
-- [00-overall-design.md](00-overall-design.md) 明确状态为“设计基线，待实现验证”。
-- 当前不存在可运行应用，因此 Stage 0 的完成只代表设计和工程防线完成。
+- [00-overall-design.md](00-overall-design.md) 现已同步“设计基线；安全运行骨架部分实现，产品主链路未完成”。
+- Stage 0 完成时尚无可运行应用；后续运行骨架不改变“Stage 0 只代表设计和工程防线”的历史验收口径。
 
 ### 已完成提交/推送节点
 
@@ -133,11 +133,13 @@ Stage 0 DONE
 
 - [x] 创建 `backend/pyproject.toml` 和依赖锁文件，不引入未说明依赖。
 - [x] 创建最小 `backend/Dockerfile`，使用非 root 用户和固定基础镜像 digest。
-- [x] 创建最小 `compose.yaml`，包含 `db + migrate + provider-smoke + seed-demo/offline`。
+- [x] 创建 Compose，包含 `db + migrate + model-gateway + api + gateway + web + provider-smoke + seed-demo/offline`；Worker 仍待实现。
 - [x] 启动最小 FastAPI `api + gateway`，内部 API 无 egress，gateway 无 Secret 并仅发布回环端口；提供真实数据库 readiness、Swagger 和只读 synthetic demo 检索。
 - [x] 创建 PostgreSQL bootstrap、migrator 和 app 分权角色初始化脚本；备份只读角色在备份功能落地时单独创建。
 - [x] 创建 Alembic 基线迁移，启用 pgvector 并建立 1024 维向量表/HNSW 基线。
 - [x] 确保运行期服务不挂载 bootstrap 或 migrator Secret。
+- [x] 将百炼 Key 和公网出口隔离到独立 `model-gateway`；API/seed/smoke 只持对应内部 token，不直持 Key。
+- [x] 以 `Authorization: Bearer` + `X-RAG-Caller: api|worker` 建立内部身份，常量时间比较并限制 API 身份不得执行文档向量化。
 
 #### 4.3 三模型适配器
 
@@ -157,6 +159,7 @@ Stage 0 DONE
 - [x] 建立并执行迁移空 volume、角色权限和 Docker 重启持久化测试。
 - [x] 明确文档族 split、盲测保管人和“盲测用于调参即退役”规则。
 - [x] 扩展 `make verify`，纳入 Stage 1 后端格式、类型和测试门禁。
+- [x] 实现并实跑 `0002_model_profiles`：profile、embedding cache、chunk assignment、model invocation 与稳定 `citation_id`；空卷和已有数据均完成 upgrade/downgrade/upgrade。
 
 ### 验收证据
 
@@ -165,12 +168,13 @@ Stage 0 DONE
 - [x] `docker compose run --rm seed-demo-offline` 完成 20 条虚构数据写入、检索和重排；真实模式待新 Key。
 - [x] `api + gateway` 镜像构建并达到 healthy；live/ready/meta/demo status/demo search 均通过真实 HTTP 验收。
 - [x] 第二次运行 seed 后数据库计数与第一次相同，均为 chunks/vectors/searchable = 20/20/20。
-- [x] 65 项后端测试证明模型契约、健康检查、固定上游 gateway、SSE 代理分块与早断连释放契约、离线 demo、数据治理和失败路径正确。
+- [x] 已验证测试集证明模型契约、健康检查、固定上游 gateway、SSE 代理分块与早断连释放契约、离线 demo、数据治理和失败路径正确；本轮新增 model-gateway/0002 契约须随阶段提交重新运行全量门禁。
 - [x] `make verify`、Secret 扫描、固定镜像构建和 `git diff --check` 通过。
 
 ### 2026-07-12 已验证运行证据
 
 - 全新 volume 上 `db` 达到 healthy，`migrate` 以非超级用户退出码 0，版本为 `0001_initial_schema`。
+- `0002_model_profiles` 已在独立全新 volume 完成 `空库 -> 0001 -> 0002 -> 0001 -> 0002`，并在已有 20 条合成数据的 volume 完成 downgrade/upgrade；重复 seed 后 profile/active KB=1/1、cache/READY assignment/citation=20/20/20，citation 无重复。
 - `vector` 扩展与 HNSW 基线存在；app/migrator 均非超级用户，app 无 `rag` schema DDL 权限但具有所需 DML。
 - 两次离线 seed 均输出 20/20/20，9 个可回答虚构问题 Hit@3 = 9/9。
 - FastAPI 容器使用 app 最小权限角色，根文件系统只读且无 egress；无 Secret gateway 仅提供回环入口；Swagger 可见，demo search 返回合成片段与不透明 citation ID。
@@ -179,9 +183,9 @@ Stage 0 DONE
 - app 尝试修改已 `CLOUD_APPROVED` 的 `cloud_text` 被审批不可变触发器拒绝；尝试建表被权限拒绝。
 - React + TypeScript strict 离线演示已实现工作台与系统状态页；14 项前端测试、ESLint、类型检查和生产构建通过。
 - Nginx 成为唯一回环入口，Compose 仅发布 `127.0.0.1:8000`；`web -> gateway -> api` 同源链路、Swagger、OpenAPI、健康检查和 synthetic search 均通过真实 HTTP 验收。
-- `edge / ingress / data / egress` 四网络边界已落地；Web 不可解析数据库，API 与 gateway 无公网 TCP 出口，Web 与 gateway 均不持有 Secret。
+- `edge / ingress / data / model / egress` 五网络边界已落地；API、seed、smoke 不挂载百炼 Key，只有不连数据库/上传卷的 `model-gateway` 同时连接 internal model 与 egress。
 - gateway 与 Nginx 已关闭代理缓冲，自动测试证明两个 SSE 事件保持为独立下游分块，且响应头阶段断连也会释放上游流；真实聊天生成与取消传播仍属于 Stage 5，尚未实现。
-- 唯一未验收项是真实 `text-embedding-v4` / `qwen3-rerank` / `deepseek-v4-flash` smoke 与真实模式 seed。
+- 当前真实 `text-embedding-v4` / `qwen3-rerank` / `deepseek-v4-flash` 请求均到达供应商但返回 401；三能力与真实模式 seed 未验收。上传、正式检索、grounded chat、Worker 和评测仍属于后续阶段，不能称为“唯一剩余项”。
 
 ### 提交/推送节点
 
@@ -206,16 +210,16 @@ Stage 0 DONE
 - **状态：** `TODO`
 - **预计工期：** 3–4 个工作日
 - **依赖：** Stage 1 `DONE`
-- **已完成前置：** 不依赖云密钥的 React 离线演示、OpenAPI 类型、Nginx 单入口、四网络隔离和当前质量门禁已验收；这不代表 Stage 2 已启动或完成。
+- **已完成前置：** 不依赖云密钥的 React 离线演示、OpenAPI 类型、Nginx 单入口和质量门禁已验收；模型隔离网络加入后当前为五层网络。这不代表 Stage 2 已启动或完成。
 
 ### 具体实现任务
 
-- [ ] 建立 FastAPI 应用工厂、配置加载、稳定错误码和 OpenAPI。
+- [x] 建立 FastAPI 应用工厂、配置加载、稳定 Problem JSON、trace middleware 和 OpenAPI；导入阶段不连库、不读模型凭证。
 - [ ] 按 `domain -> ports -> services -> adapters/persistence` 落实后端依赖边界。
-- [ ] 建立 SQLAlchemy 仓储、Alembic 迁移运行器和事务边界。
+- [ ] 建立完整 SQLAlchemy 仓储和业务事务边界；Alembic 已推进到 `0002_model_profiles`，且空卷/已有数据升降级已验证。
 - [ ] 建立 PostgreSQL `background_jobs`、租约、lease token、fencing 和重试状态机。
 - [ ] 建立 Worker maintenance loop、advisory-lock reaper 和强杀恢复测试。
-- [ ] 建立 `/health/live`、`/health/ready` 和管理员模型能力探测端点。
+- [ ] `/health/live`、数据库 `/health/ready` 及 model-gateway 本地 readiness 已有；管理员模型能力探测 API 仍待实现。
 - [x] 建立 React + TypeScript strict、路由、TanStack Query 和 OpenAPI 客户端生成。
 - [x] 建立 Nginx，仅发布 Web 端口；当前 API、DB 只在内部网络，Worker 落地后必须沿用同一边界。
 - [ ] 建立完整 Compose：`web/api/worker/db/migrate`，OCR profile 默认关闭。
@@ -229,11 +233,11 @@ Stage 0 DONE
 - [x] 当前 `docker compose ps` 只暴露 Nginx/Web 回环端口；加入 Worker 后须重新验收。
 - [ ] Docker 重启后数据库数据保留。
 - [ ] 强杀 Worker 后验证可重领、耗尽进入 `FAILED`、旧 token 不能提交。
-- [x] 当前后端 65 项、前端 14 项测试及两端 lint、类型和构建门禁均通过；Stage 2 新功能仍需增量验证。
+- [x] 已提交基线的两端 lint、类型、测试和构建门禁通过；本轮新增 model-gateway、应用工厂和 `0002` 仍须在提交前以 `make verify` 重新确认。
 
 ### 提交/推送节点
 
-- [x] `S2-PREP`：React 离线演示、Nginx 单入口、四网络隔离、SSE 代理安全修复与质量门禁已随 `c3bad0f` 验证并推送；该前置提交不代表 Stage 2 已启动或完成。
+- [x] `S2-PREP`：React 离线演示、Nginx 单入口、当时的四网络隔离、SSE 代理安全修复与质量门禁已随 `c3bad0f` 验证并推送；后续 `model` 网络把当前拓扑扩为五层，该前置提交不代表 Stage 2 已启动或完成。
 - [ ] `S2-A`：FastAPI、持久化、健康端点和错误契约。
 - [ ] `S2-B`：任务租约、reaper、fencing 和恢复测试。
 - [ ] `S2-C`：React、Nginx、完整 Compose、CI 和文档；其中 React/Nginx/CI 前置已完成，缺 Worker 与完整 Compose 验收，节点不得提前关闭。
@@ -561,12 +565,12 @@ Stage 0 DONE
 
 ## 15. 下一步执行顺序
 
-当前主线仍是关闭 Stage 1 的真实供应商门禁；已完成的 React/Nginx 工作仅作为 Stage 2 安全前置保留。建议按以下顺序继续：
+当前主线仍是关闭 Stage 1 的真实供应商门禁，同时继续不依赖云授权的安全骨架。建议按以下顺序继续：
 
-1. 在百炼控制台撤销聊天中暴露的旧 Key，创建新 Key，并仅通过未提交的 Docker Secret 注入。
-2. 分别运行 `text-embedding-v4`、`qwen3-rerank`、`deepseek-v4-flash` 受控 live smoke，记录脱敏 provider profile、能力指纹、维度、流式协议和错误映射。
-3. 用现有 20 条 synthetic 数据运行真实 Embedding/Rerank/Chat 链路和幂等 seed；真实地质资料仍不得出域。
-4. 关闭 S1-B 并把 Stage 1 标记为 `DONE` 后，再实现 Stage 2 的 Worker 租约、fencing、reaper、恢复测试和完整 Compose。
+1. 在百炼控制台确认旧 Key 已撤销，并核对当前本地 Secret 对应的工作空间、北京地域、端点、计费方案和模型权限；Key 只保存在未提交 Secret 中。
+2. 通过独立 `model-gateway` 重跑三能力 smoke；当前三项 401 未消除前保持 S1-B 未完成。
+3. 三能力成功后，用现有 20 条 synthetic 数据运行真实 Embedding/Rerank/Chat 链路和幂等 seed；真实地质资料仍不得出域。
+4. 继续实现 Stage 2 的 Worker 租约、fencing、reaper、恢复测试和完整 Compose，不让外部 401 阻塞可离线验证的工程工作。
 5. Stage 3 实现数字 PDF/DOCX/TXT/Markdown 的隔离解析、页码/章节恢复、审批状态机、切分、向量化写库和可追溯版本激活。
 6. Stage 4 完成真实向量召回、重排与验证集评测；Stage 5 再实现 grounded chat SSE、取消传播、引用解析和聊天 UI，不把当前代理分块测试误称为聊天功能完成。