# OpsxAPI 开发指南

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

## 产品形态（硬边界）

```text
浏览器  →  只看官网 + 文档（homepage/，Gin 托管 :8787）
操作    →  只走桌面 Tauri（./run.sh gui）
Vite    →  仅桌面 WebView 源，不是浏览器产品，不要把工作台加回浏览器
```

| 职责 | 放哪 |
| --- | --- |
| 桌面操作（请求 / 文档编辑 / Mock 管理 / 自动化测试） | **本仓** `src/` + `src-tauri/` |
| 官网 + 用户文档 | **本仓** `homepage/`（`tools/homepage-build` 出 dist，Gin 只托管） |
| 本机 API、Mock 响应、代理 | **本仓** `server/`（Go / Gin） |

同族：`opsxshell` / `opsxdb` 同形态（浏览器 = 官网/docs，操作 = 桌面）。`src/` 里的 React 是 **Tauri WebView UI**，不是浏览器 SaaS。

### 安全三句（写进日常约束，不另开专章）

1. 浏览器只站 + 文档。不要把请求工作台、集合或测试跑在浏览器里；Vite 开发源不是对外入口。
2. 管理服务默认只听 `127.0.0.1:8787`。Mock **响应**口默认 `0.0.0.0:8798` 且只接受回环/私网来源；不上公网，除非显式 `OPSXAPI_MOCK_ALLOW_PUBLIC=1`。官网不挂 Mock 管理或代理 API。
3. 没有对公网开放的 `/admin`。账号、令牌、密钥、未发布集合不得出现在官网、文档分享或 Mock 响应里的明文。以后若加管理面，敏感字段仍不明文。

## 目录（以当前 `main` 磁盘为准）

```text
src/            React / TS 桌面 UI（core、transport、features、components）
src-tauri/      Tauri 2 + Rust services
server/         Gin：官网静态托管、代理、账号/工作区、Mock 管理 API；另起 :8798 只出 Mock/文档分享
homepage/       官网与文档源（与 GUI 解耦）
tools/homepage-build   静态站构建
```

旧 monorepo（`apps/desktop`、`apps/web`、`apps/server`、`packages/*`）**本仓已不存在**（见 `docs/recovery/2026-10-14.md` 的迁移中快照）。不要把代码迁回去，也不要并行再造一套客户端。能 `./run.sh gui` 跑起来的就是这棵根目录树。

## 架构（怎么改代码）

```text
UI / store  →  src/transport（browser | gin-proxy | tauri-native；IPC 走 transport/ipc.ts）
            →  Tauri command  →  src-tauri/src/services/
server      →  Gin :8787（默认回环）+ Mock 响应 :8798（私网）
```

- UI 复用 `src/features/`、`src/components/` 与现有 store；不另起同功能架构。
- Rust command 只做边界校验和适配；业务优先 `src-tauri/src/services/`。
- 不把本机数据库、访问令牌、AI 密钥或真实请求体提交进 git。
- 实时会话（WS/SSE/Socket.IO/MQTT）不落盘。

一页说明见 [docs/architecture.md](docs/architecture.md)。

## 怎么跑

```bash
make install          # 或 npm install
./run.sh web          # 仅官网 + docs → http://127.0.0.1:8787/
./run.sh gui          # 桌面操作入口（推荐；默认顺带 Gin）
./run.sh stop | status
```

改功能后按范围：`npm test`、`npm run build`、`server/` 下 `go test ./...`、`cargo test --manifest-path src-tauri/Cargo.toml --locked`。交互改动在桌面里点，构建通过不等于验收。

## 给 AI

- 需求清楚就直接改；不确定用最小假设并在回复里写明。
- 跟仓内模式，禁止平行架构或第二套客户端。
- 少造文档；只改文档时核对链接，不要求重跑业务测试。
- 依赖版本以锁文件为准，规划中的能力不要写成已实现。
- 设计验收：请求 / 环境 / 文档 / Mock / 测试的标识、保存、失败与删除要一致；Mock 写清监听、鉴权、发布范围；自动化测试写清顺序、失败、取消、超时与定时。

## SDD 开发

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