# 里程碑现状对齐

本文以仓库当前代码为依据，对 M1–M5 的 DoD 项做粗粒度盘点，便于例会与评审快速对齐。**不替代** 各里程碑文档的 DoD 原文。

> 状态图例：
> - `done`：代码已落地并经过基本验证
> - `partial`：部分项可用，关键缺口已知
> - `todo`：尚未开始或仅有占位
> - `docs-only`：仅文档定义，待实现承接
>
> 来源依据：`cc-haha/src/server/api/heicode-auth.ts`、`cc-haha/src/server/services/providerService.ts`、`heicode/controller/heicode_oauth.go`、`heicode/router/heicode-router.go`、本仓库 `docs/`。

## M1 · 契约与身份对齐

| DoD | 状态 | 备注 |
|-----|------|------|
| 登录与会话语义文档化 | `done` | 详见 [`../integration/heicode-oauth-flow.md`](../integration/heicode-oauth-flow.md) |
| `/v1/models` 模型发现契约 | `partial` | 客户端 `providerService.fetchProviderModels` 已支持探活与多种返回结构；分页/过滤约定尚未文档化 |
| 用户上下文 `tenant_id` / `org_id` 传播 | `todo` | Heicode 客户端尚未在请求中显式注入；预留位置在请求头层 |
| 版本协商 `User-Agent` / `X-Heicode-Client-Version` | `todo` | 未在客户端统一植入 |
| `X-Tenant-Id` 预留约定 | `docs-only` | 见 API 设计 §2.3 |

## M2 · 本地端到端闭环

| DoD | 状态 | 备注 |
|-----|------|------|
| 本地可启动 Manager 与客户端 | `done` | 步骤见 [`../onboarding/local-dev.md`](../onboarding/local-dev.md) |
| 登录 → 模型 → 至少一类任务调用 | `partial` | API Key 路径完整；浏览器登录可达；端到端任务回归未自动化 |
| 可追溯锚点（Git commit / CI Run） | `todo` | 客户端尚未把会话与 Git/CI 关联 |
| 文档：30 分钟内复现 | `done` | 根 README + `onboarding/` 已覆盖 |

## M3 · Agnet 编排桥接

| DoD | 状态 | 备注 |
|-----|------|------|
| Agnet 控制面最小集（部署/伸缩/停止） | `docs-only` | 设计完整，本仓库不含实现 |
| Heicode Manager「一键部署 Agnet 团队」 | `todo` | 尚未在 `heicode` 中提供 |
| SK 边界（写权仅 Heicode、子 agent 只读） | `partial` | 文档单点真相已就绪（[`../sk-lifecycle.md`](../sk-lifecycle.md)）；客户端 SK 编辑入口待落地 |
| Webhook / 回调（Agnet → Heicode） | `todo` | Manager 未提供回调注册端点 |
| 幂等与 `deployment_id` / `correlation_id` | `docs-only` | 字段约定见 API 设计 §5.1、§2.3 |
| 失败语义（超时 / 部分就绪 / 不可调度） | `docs-only` | 待与 Agnet 联合评审落地 |
| 联调环境对打成功 | `todo` | 需要真实 Agnet 接入 |

## M4 · 租户、RBAC 与隔离

| DoD | 状态 | 备注 |
|-----|------|------|
| 租户模型（`tenant` 顶层） | `partial` | `heicode` 自身有用户/组/Token 体系；Heicode 维度未与 Agnet 集成 |
| RBAC 角色矩阵 | `partial` | `heicode` 控制台已有基础角色；与 Agnet 设计（`agnet:*` 角色）未对齐 |
| 数据面隔离与跨租户负例 | `todo` | 待联合 Agnet 落地后补测 |
| 凭据写入隔离（Git Token / 云 SA） | `docs-only` | 见 API 设计 §3.2 |
| 审计日志（追加式） | `partial` | `heicode` 自带操作日志；统一 `correlation_id` 字段未规范化 |

## M5 · 可观测性与可视化

| DoD | 状态 | 备注 |
|-----|------|------|
| 实例快照 API | `docs-only` | 字段定义见 API 设计 §6.1 |
| 子 Agnet 输出流（SSE/WS） | `todo` | 客户端 UI 尚未实现订阅 |
| 项目级聚合 / Dashboard | `partial` | `heicode` 控制台具备模型/Token 指标基础 |
| 事件流（含 `Last-Event-ID` 重连） | `docs-only` | 见 API 设计 §7 |
| 与 RBAC 联动 | `todo` | 需在 M4 落地后回填 |
| SLI 指标导出 | `todo` | Prometheus / JSON 端点未配置 |

## 风险与建议

1. **SK 边界要尽早写到自动化校验**：避免后续在 Agnet 控制台或 Manager 误开 SK 写 API
2. **`correlation_id` 与 `tenant_id` 在客户端先注入**：即便 Agnet 还没接，也方便后续审计回看
3. **Webhook 与回调签名先做规范**：联调时再补会引入兼容包袱
4. **客户端订阅子 agent 输出的协议** 在 UI 还没动前就该确定多路 `type` 命名

## 维护约定

- 每次 PR 涉及 M1–M5 任一 DoD 变化时，在本文相应行更新状态并简述
- 状态从 `docs-only` 升到 `partial` / `done` 时，标注 PR 链接或代码入口
- 本文不写时间表，避免与里程碑原文重复