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 当工作台的旧手测口径
4.5 KiB
4.5 KiB
OpsxAPI 开发指南
接口调试桌面客户端（HTTP / GraphQL / WebSocket / SSE / Socket.IO / MQTT）。请使用中文沟通。
产品形态（硬边界）
浏览器 → 只看官网 + 文档（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。
安全三句（写进日常约束，不另开专章）
- 浏览器只站 + 文档。不要把请求工作台、集合或测试跑在浏览器里；Vite 开发源不是对外入口。
- 管理服务默认只听
127.0.0.1:8787。Mock 响应口默认0.0.0.0:8798且只接受回环/私网来源；不上公网，除非显式OPSXAPI_MOCK_ALLOW_PUBLIC=1。官网不挂 Mock 管理或代理 API。 - 没有对公网开放的
/admin。账号、令牌、密钥、未发布集合不得出现在官网、文档分享或 Mock 响应里的明文。以后若加管理面，敏感字段仍不明文。
目录（以当前 main 磁盘为准）
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 跑起来的就是这棵根目录树。
架构（怎么改代码）
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。
怎么跑
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/specs/README.md 和 docs/specs/_template.md，不另造第三套字段。S3 写清风险与恢复。
- 引用仓内契约与测试；未知标「待确认」。已授权的范围不重复审批；契约变化至少升到 S2。
- 设计批准 ≠ 实现完成 ≠ 验证通过；没跑的检查标 Not Run。