# SIP 管理后台

独立于仓库其它业务的管理项目：Go 负责最终鉴权、版本/CAS、发布屏障、Cell 状态和统计；TanStack Start 只负责管理页面。运行时不导入 `agent_call`、不读取其它项目数据库、不代理 Python API，也不会因启动而拨打真实电话。

## 技术栈与固定基座

- 后端：Go 1.26、Fiber v3、Viper、Cobra、Logrus、SQLite、sqlc。
- 前端：上游 `Kiranism/tanstack-start-dashboard`，锁定提交 `f3375fcce5d2b2fbc35caef776e5a1c61b030439`；许可证保留在 `frontend/LICENSE`，依赖和 `bun.lock` 随项目发布。
- 契约：`docs/contracts/` 是唯一来源；`contracts/` 是打包后的生成快照，使用 `scripts/sync-contracts.sh --check` 校验。

## 本地运行

```bash
cd management/backend
go test -race ./...
go vet ./...
go run ./cmd/management serve
```

默认监听 `127.0.0.1:8080`，默认 SQLite 为 `backend/data/management.db`。首次演示数据：

```bash
MANAGEMENT_DB_PATH=/tmp/agent-call-management.db go run ./cmd/management seed-demo
curl -H 'Authorization: Bearer dev-admin-token' http://127.0.0.1:8080/admin/v1/sip-status
```

演示数据仅使用合成的 TEST-NET SIP 地址；`dev-*` 令牌仅适用于 `mock` 本地开发，生产必须通过受控环境注入专用令牌和 mTLS 文件。可用令牌域隔离：`dev-admin-token`、`dev-config-token`、`dev-publisher-token`、`dev-observer-token`、`dev-audit-token`、`dev-saas-token`。调度器令牌不会被管理 API 接受。

前端另开终端：

```bash
cd management/frontend
bun install --frozen-lockfile
VITE_MANAGEMENT_API_URL=http://127.0.0.1:8080 bun run dev
```

页面首次打开后在当前浏览器会话输入管理令牌；令牌不写入源码、URL、localStorage 或日志。

## 独立验证

```bash
# contract source/snapshot
management/scripts/sync-contracts.sh --check

# backend
cd management/backend
gofmt -w .
go test -race ./...
go vet ./...

# frontend
cd ../frontend
bun run lint
bun run format:check
bun run build
```

后端测试覆盖鉴权域隔离、资源范围、幂等重放、CAS 冲突、全 Cell 发布屏障、Mock 意图恢复、观察 boot/sequence、新鲜度和统计事实语义。默认 `mock` 发布不声称 Cell 已应用；需要协议 Mock 完整验收时显式设置 `MANAGEMENT_MOCK_CELL_APPLY=true`。

## 模式与安全边界

`MANAGEMENT_MODE=mock` 只处理合成/协议 Mock 数据；`MANAGEMENT_MODE=real` 发布前要求 HTTPS Cell Agent、mTLS 客户端证书、CA 和主机白名单，失败时保留原活动版本并保持 admission barrier，绝不静默回退 Mock。SIP 凭据只能是 secret-store reference，管理读取、审计和统计均不返回密钥或完整被叫号码。

`real` 模式不会把 `123.56.71.98` 当 SIP 服务端；该地址只作为固定出口白名单事实。真实供应商、MQ/OSS、云资源和真实呼叫验收需要另行安排，不是本项目启动前置。

## 一键 Compose 部署

从仓库根目录执行：

```bash
docker compose -f management/deploy/compose.yaml up -d --build
```

打开 <http://localhost:3000/dashboard/overview>，输入 `dev-admin-token`。健康检查和日志：

```bash
curl http://localhost:8080/healthz/live
docker compose -f management/deploy/compose.yaml logs -f management-api
```

停止服务：

```bash
docker compose -f management/deploy/compose.yaml down
```

默认仍是隔离 Mock。使用 Gitea Registry 镜像时，将 `MANAGEMENT_API_IMAGE`、`MANAGEMENT_UI_IMAGE` 传给 `deploy/compose.images.yaml`；镜像由根目录 `.gitea/workflows/management-images.yml` 在 PR 构建、在 `main`/版本标签推送。不要将示例令牌和 Mock 配置用于生产。