# CLAUDE.md — Heicode Manager 单仓导航（给 Claude Code / 助手）

本文是 **仓库根级** 的快速地图与协作约定。细分栈规则看子目录自带文档（避免重复与漂移）。

> **本仓 = Heicode Manager（HM）端。** 历史上客户端（`cc-haha`）、官网（`website`）与 Manager 曾在同一 monorepo；现已拆分，**本仓只保留 Heicode Manager**。客户端（终端 + 桌面）在 `heicode-macos-release-dev` / `heicode-winos-release-dev` 独立仓，不在本仓。

## 仓库地图

| 路径 | 角色 | 栈 / 备注 |
|------|------|-----------|
| `heicode/` | **Heicode Manager**：基于 new-api 的模型网关 + 管理控制台 | Go（Gin/GORM）后端 + `web/default` 前端（Bun/Rsbuild/React） |
| `docs/` | 产品共识 / 实施计划 / 集成契约 | Markdown，索引见 [`docs/README.md`](./docs/README.md) |

## 权威子文档（改代码前先打开对应一篇）

- **网关后端（`heicode/`，Go）**：[`heicode/CLAUDE.md`](./heicode/CLAUDE.md) — Go 分层、JSON / i18n / DB 规则、计费表达式等。
- **产品共识与实施计划**：[`docs/heicode.md`](./docs/heicode.md)、[`docs/plan.md`](./docs/plan.md)。
- **集成契约**：[`docs/integration/`](./docs/integration/) —— 当前模型「模板 Agent」见 `heicode-hm-template-agent-model.md`；HM↔AM 见 `heicode-am-contract.md`；桌面客户端对接见 `heicode-desktop-client-api.md`。
- **客户端**：在 `heicode-macos-release-dev` / `heicode-winos-release-dev` 独立仓，不在本仓。

## 最小开发闭环

Heicode Manager = `heicode/`（Go 后端 + `web/default` 前端）。构建 / 运行命令与分层规则以 [`heicode/CLAUDE.md`](./heicode/CLAUDE.md) 与 `heicode/README.md` 为准。

## 关键触摸点（代码索引）

- **客户端登录**：客户端走 HM 的 `/api/heicode-auth/*`（转发到登录服务）+ V2 设备签名；详见 `docs/integration/heicode-desktop-client-api.md`。
- **Manager 侧 Heicode OAuth**：`heicode/controller/heicode_oauth.go`，路由 `heicode/router/heicode-router.go`（如 `/heicode/oauth/authorize`、`/heicode/oauth/session`）。
- **HM↔AM（agent 部署）**：`heicode/controller/agent_template_runtime.go`、`agent_template_handlers.go`；契约见 `docs/integration/heicode-am-contract.md`。

## 协作约定（根级）

1. **改哪一层跟哪篇文档**：Go 行为以 `heicode/CLAUDE.md` 为准；产品 / 架构以 `docs/heicode.md` + `docs/plan.md` 为准。
2. **小步提交**：沿用历史风格（`feat:` / `fix:` / `docs:`）；PR 写清影响面与验证步骤。
3. **不要臆测计费**：计费在平台侧（new-api 计量），按 `docs/` 契约对接，不在本仓臆造扣费逻辑。

## 当前线上入口

- **Heicode Manager（生产）**：`https://code.xinghanlab.com/`

## Manager 生产拓扑（Azure）

- 应用层：Azure VM 上运行 `heicode`（Docker 容器承载应用进程）。
- 数据库与缓存：Azure 托管服务（不在 VM 上跑 PostgreSQL / Redis 容器）
  - PostgreSQL：`heicode.postgres.database.azure.com` / DB `heicode`
  - Redis：`heicode.redis.cache.windows.net:6380`（TLS）
- 容器落盘：容器内产生的文件（`/data` 上传与持久文件、`/app/logs`）通过 **bind mount** 写到 VM 本地磁盘。编排见 `heicode/docker-compose.azure-vm.yml`，目录由 `HEICODE_DATA_ROOT` 指定。
- **VM 部署后清镜像**：每次 `docker compose ... up -d --build` 后执行 `sudo docker image prune -f`；定期 `sudo docker system prune -f`（不删在用卷），避免旧层占满磁盘。
- **VM / 生产同步代码**：优先在目标机 `git clone` / `git pull` 与远程一致；不要用 `scp` 传整份源码（紧急热修例外）。

---

*若本文件与 `heicode/CLAUDE.md` 或 `docs/` 冲突，以子目录 / `docs` 为准并及时更新本文件。*