# OpsxAPI 开发指南

接口调试**桌面**客户端（HTTP / GraphQL / WebSocket / SSE / Socket.IO / MQTT）。请使用中文沟通。

## 产品形态（硬边界）

```text
浏览器  →  只看官网 + 文档（homepage/，./run.sh web → :8787）
操作    →  只走桌面（./run.sh gui）
```

不要把请求工作台加回浏览器。

| 职责 | 目录权威 |
| --- | --- |
| 桌面操作（请求 / 文档编辑 / Mock / 自动化测试） | `apps/desktop` |
| 共享 UI、传输、领域 | `packages/*` |
| Gin（官网托管、代理、本机 API） | `apps/server` |
| 官网 + 用户文档 | `homepage/` |

根目录 `src/`、`src-tauri/`、根 `server/` 是误迁，**不是**目录权威。新功能写到上表，不要在根 `src` 上继续长。

同族：`opsxshell` / `opsxdb` 同形态（浏览器 = 官网/docs，操作 = 桌面）。

### 安全三句（不另开专章）

1. 浏览器只看站 / 文档。运维与调试入口是 `./run.sh gui`。
2. Mock 默认 `127.0.0.1`，不上公网。
3. `/admin` 不落明文（令牌、密钥、未发布集合不进页面或分享正文）。

## 怎么跑

```bash
./run.sh web          # 仅官网 + docs → http://127.0.0.1:8787/
./run.sh gui          # 桌面操作入口（推荐）
./run.sh stop | status
```

交互改动在桌面里点，构建通过不等于验收。不把本机数据库、访问令牌、AI 密钥或真实请求体提交进 git。

## 给 AI

- 需求清楚就直接改；不确定用最小假设并在回复里写明。
- 跟目录权威改，禁止在根 `src` 再起一套客户端。
- 少造文档；只改文档时核对链接，不要求重跑业务测试。
- 依赖版本以锁文件为准，规划中的能力不要写成已实现。

## SDD 开发

- 按实际影响取最高级别：S0 文案/格式；S1 契约内修复/重构；S2 新功能、契约或数据模型；S3 安全权限、迁移/删除或生产变更。跨文件不自动升级。
- **S0 / S1 直接改代码**，不套全模板。
- **S2 / S3 必填** [docs/sdd-template.md](docs/sdd-template.md)（FR 对应 AC）。评审入库与状态机仍用 [docs/specs/README.md](docs/specs/README.md)、[docs/specs/_template.md](docs/specs/_template.md)，不另造第三套。
- 未知标「待确认」。契约变化至少升到 S2。设计批准 ≠ 实现完成 ≠ 验证通过；没跑的检查标 Not Run。

一页架构见 [docs/architecture.md](docs/architecture.md)。