logan
0c0423d3a1
- AGENTS/architecture：目录权威改为 apps/desktop + packages/* + apps/server；根 src 标误迁 - sdd-template：补何时必填与 FR→AC，保留 Shell/DB 短模板体；细流程仍 docs/specs/ - 安全三行钉死；HANDTEST/README 已无浏览器 :5173 工作台口径
56 lines
2.4 KiB
Markdown
56 lines
2.4 KiB
Markdown
# 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)。
|