logan
9304b0e98c
- 重写 AGENTS：浏览器只站+文档、操作走 ./run.sh gui；目录以现仓 src/src-tauri/server 为准 - docs/sdd-template.md 填成与 Shell/DB 同款短模板；sdd-agents/CLAUDE 指向它与 specs - 新增 docs/architecture.md（两套壳、数据流、安全三底线）与 docs/README 索引 - HANDTEST/README 去掉用 :5173 当工作台的旧手测口径
80 lines
4.5 KiB
Markdown
80 lines
4.5 KiB
Markdown
# 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。
|