桌面 GUI 外链修复 + 主题顺序调整（含结构扁平化进行中的工作区基线）
- 集成 tauri-plugin-opener：Cargo/lib.rs/capabilities/npm 四处接线，新增 src/openExternal.ts（桌面走 opener，浏览器回退 window.open，相对路径绝对化） - 关于页 4 个链接、活动栏官网菜单、代理错误横幅 2 处健康检查链接全部改走 openExternal，桌面端可正常跳转 - 设置→外观 主题顺序调整为 深色/浅色/跟随系统 - release 二进制重编并验证（浏览器实测关于页链接可开文档页） - 附带工作区中未提交的扁平化重构现状（另一会话进行中） - homepage 落地页与文档终检通过（8787 / 与 /docs 双 200）
This commit is contained in:
logan committed
1 parent
6452026fd6
commit
2bb4ef7a95
299 files changed
+6059
-3322
No files matched your search
@@ -5,15 +5,16 @@
|
||||
**HTTP · GraphQL · WebSocket · SSE · Socket.IO · MQTT，一个工作台全搞定；数据全在本地。**
|
||||
|
||||
```
|
||||
packages/core 数据模型 / 树操作 / 导入导出器（纯 TS，21 个单测）
|
||||
packages/transport browser | gin-proxy | tauri-native + 流式/SSE/WS隧道/Socket.IO/MQTT 客户端
|
||||
packages/ui 共享工作台 UI（集合树 / 多标签 / 编辑器 / 对话框）
|
||||
apps/web Vite + React 入口（:5173）
|
||||
apps/desktop Tauri 2 壳（frontendDist → web dist）
|
||||
apps/server Gin：HTTP 代理 + 流式代理 + WebSocket 隧道（:8787）
|
||||
src/ 前端入口（React；进 Tauri WebView，勿当浏览器产品）
|
||||
src-tauri/ Tauri 2 壳（唯一操作入口）
|
||||
server/ Gin：代理 API + health（:8787；本地托管 homepage/dist）
|
||||
homepage/ 官网落地页 + 文档静态站（不变）
|
||||
src/core 数据模型 / 树操作 / 导入导出器
|
||||
src/transport browser | gin-proxy | tauri-native
|
||||
src 工作台 UI
|
||||
```
|
||||
|
||||
核心原则：**一套 UI、一份请求契约，Web / Desktop 只换 Transport。**
|
||||
核心原则：**一套 UI、一份请求契约；浏览器只看官网/docs，操作只走桌面。**
|
||||
|
||||
## 功能总览
|
||||
|
||||
@@ -53,14 +54,13 @@ apps/server Gin：HTTP 代理 + 流式代理 + WebSocket 隧道（:8787
|
||||
## 怎么跑
|
||||
|
||||
```bash
|
||||
make install # npm install（含 desktop 依赖）
|
||||
./run.sh web # 浏览器：Gin(:8787) + Vite(:5173) ← 推荐
|
||||
./run.sh gui # 桌面 Tauri 窗口（共用 Vite）
|
||||
./run.sh all # 全开
|
||||
make install
|
||||
./run.sh web # 官网 + docs → http://127.0.0.1:8787/
|
||||
./run.sh gui # 桌面操作入口（推荐）
|
||||
./run.sh stop | status
|
||||
```
|
||||
|
||||
打开 http://127.0.0.1:5173 —— 内置「示例集合」覆盖全部协议，开箱即用。
|
||||
打开 http://127.0.0.1:8787/ 看落地页；操作请用 `./run.sh gui`。`:5173` 只是桌面 WebView 源。
|
||||
|
||||
## 用户文档站（/docs）
|
||||
|
||||
@@ -69,7 +69,7 @@ Gin 内置产品文档，Markdown 嵌入二进制、SSR 渲染，随服务一键
|
||||
- 地址：`http://127.0.0.1:8787/docs`（开发态 `http://127.0.0.1:5173/docs`，Vite 已反代；工作台顶栏「📖 文档」直达）
|
||||
- 布局：顶栏搜索 + 左侧分组导航（16 篇：开始使用 / 请求调试 / 数据管理 / 参考）+ 右侧本页目录
|
||||
- 能力：全文搜索、代码块复制 + 高亮、提示块、上一页/下一页、反馈组件、打印导出 PDF、移动端响应式、404 页
|
||||
- 内容在 `apps/server/internal/docs/content/*.md`，改完重新 `go build` 即生效
|
||||
- 内容在 `server/internal/docs/content/*.md`（本地预览优先托管 `homepage/dist`）
|
||||
|
||||
## 产品官网（/home）
|
||||
|
||||
@@ -81,7 +81,7 @@ Gin 内置营销单页，与 /docs 同为 SSR 嵌入交付（`internal/site`）
|
||||
- 让利机制四项：早鸟创始价（前 20 席 5–7 折永久）、教育/开源 6–8 折、多年预付 8–9 折、案例换授权；销售原则：不直接降价，用「永久授权 + 1 年升级 + 5 人团队 1–2 年回本」回应预算顾虑
|
||||
- 交付前替换：联系邮箱 `hello@opsxapi.dev`（template.html 内两处）与对比表脚注中的价格核对
|
||||
|
||||
## 服务端端点（apps/server）
|
||||
## 服务端端点（server/）
|
||||
|
||||
| 端点 | 用途 |
|
||||
| --- | --- |
|
||||
@@ -96,7 +96,7 @@ Gin 内置营销单页，与 /docs 同为 SSR 嵌入交付（`internal/site`）
|
||||
|
||||
## 架构决策
|
||||
|
||||
- **一套 UI**：集合 / 编辑器 / 对话框全部在 `packages/ui`，Web 与桌面零分叉
|
||||
- **一套 UI**：集合 / 编辑器 / 对话框全部在 `src`，Web 与桌面零分叉
|
||||
- **判别联合数据模型**：`node.kind === "http"` 自动收窄 `node.data` 类型
|
||||
- **实时会话不落盘**：WS/SSE/Socket.IO/MQTT 会话存模块级注册表，消息（500 条上限）与状态进 store
|
||||
- **zustand 选择器必须返回稳定引用**：`?? []` 会触发 useSyncExternalStore 无限重渲染（踩过的坑）
|
||||
@@ -104,13 +104,56 @@ Gin 内置营销单页，与 /docs 同为 SSR 嵌入交付（`internal/site`）
|
||||
## 测试
|
||||
|
||||
```bash
|
||||
make test # core 21 个单测：导入导出全格式往返、树操作、cURL 解析
|
||||
cd apps/server && go test ./...
|
||||
npm test # core / transport / features 全量测试
|
||||
cd server && go test ./...
|
||||
```
|
||||
|
||||
## P0 自动化演示（本地）
|
||||
|
||||
1. `./run.sh web` → http://127.0.0.1:5173
|
||||
1. `./run.sh gui` → 桌面工作台（Gin `:8787` + Vite 源）
|
||||
2. 进入自动化测试 → **装载回归示例** → **运行**（依赖本机 Gin `:8787/v1/echo`）
|
||||
3. AI：**保存并运行** 与手动/定时共用同一执行器与报告
|
||||
4. 定时：支持 5 段 Cron 或间隔；应用保持打开；见 `docs/HANDTEST-P0.md`
|
||||
|
||||
## 根目录 Tauri 开发布局
|
||||
|
||||
前端全部位于 `src/`（`core/`、`transport/`、`features/`、`components/`），Rust 位于 `src-tauri/`。不再使用 `apps/` 或 npm workspace；`homepage/` 落地页保持独立，`server/` 保留本地辅助服务。
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npm run build # 先类型检查，再构建前端
|
||||
npm test # 全量前端单测
|
||||
cargo test --manifest-path src-tauri/Cargo.toml --lib
|
||||
./run.sh gui # 编译当前 Rust 后启动桌面，默认附带本地 Gin
|
||||
```
|
||||
|
||||
`./run.sh gui` 每次通过 Cargo 增量编译当前源码，不再回退到旧 release。只运行原生桌面可用 `OPSXAPI_GUI_WITH_SERVER=0 ./run.sh gui`。标准 Tauri 开发热重载入口为 `npm run dev:desktop`。
|
||||
|
||||
## 请求代理与内网 Mock
|
||||
|
||||
### API 文档与 OpenAPI 同步
|
||||
|
||||
侧栏「文档」以现有集合为项目，按 OpenAPI 标签分组浏览 HTTP 接口，显示参数、请求体、响应示例及说明。导入入口支持 OpenAPI 3.0/3.1、Swagger 2.0 的 JSON/YAML 文件、粘贴内容与 URL；导入时选择新建、按同名项目合并、或覆盖。合并按 HTTP 方法和相对路径更新同一接口，保留没有出现在本次导入里的接口；手动编辑并保存的说明与文档字段会在下次合并时保留。覆盖会移除该项目未导入的接口，使用前先检查选择。文档字段与请求一起保存在工作区备份；选择云端空间时也遵循现有工作区同步规则。
|
||||
|
||||
侧栏按「接口 → 文档 → Mock → 测试」排列。文档详情可直接打开请求页试用，或从 2xx 响应 example/schema 生成 Mock 草稿；已有相同方法和具体路径的 Mock 会显示关联状态并直接打开编辑，不覆盖手动修改的模拟响应。生成时把路径参数示例实例化为具体路径（例如 `/pets/{id}` 和 `id=42` 对应 `/pets/42`）；发布后文档详情和内网只读文档快照均可展示对应 Mock 地址（快照需重新发布才会更新）。当前 Mock 服务只支持完整路径匹配，暂无动态路径匹配、请求体条件或多响应规则。
|
||||
|
||||
「发布当前项目」会将所选项目的名称、接口说明、参数和示例生成单独的本机 SQLite 只读快照；鉴权、环境变量及运行历史不会加入快照。分享地址是 `<IP或域名>:8788/docs/<随机令牌>`，和 Mock 响应共用独立监听与来源限制。修改文档后需点「更新分享快照」；「撤销分享」立即令旧链接失效。公开访问需明确配置 `OPSXAPI_MOCK_ALLOW_PUBLIC=1`，自行处理 DNS/端口映射/HTTPS。分享页面不提供请求执行或编辑入口。
|
||||
|
||||
- 顶栏仅保留环境管理和环境切换；请求代理在「设置 → 网络」配置。支持自动检测、自定义 HTTP/HTTPS 代理、不使用代理、绕过主机和代理认证。配置仅存本机，不进入工作区同步/导出；适用于桌面 HTTP、GraphQL 及自动化测试，实时协议不受此设置控制。
|
||||
- 侧栏「Mock」是独立接口管理页面：新建接口 → 选择方法与路径 → 编辑 JSON/文本响应、状态码、延迟 → 保存草稿 → 发布全部已保存接口。也可在 HTTP 编辑器通过「创建 Mock」或「用响应创建 Mock」复制为独立接口，不修改原请求。
|
||||
- 草稿与未保存编辑缓存在本机浏览器存储；发布结果保存在本机 SQLite，不因登录而切换到团队或公网存储。发布会替换此本机服务的全部接口，禁用/删除接口需发布后生效；未保存编辑不参与发布。接口页提供已发布地址、复制和试运行。
|
||||
- Mock 页面顶部可直接启用或关闭 HTTP 响应，并可一键创建 `GET /demo` 示例；保存草稿后点击「发布全部已保存接口」，在已发布版本中试运行。设置 → Mock 服务保留相同开关及分享地址、环境关联配置。关闭后返回 503，保留数据和监听端口；彻底停止进程使用 `./run.sh stop`。随机数据生成规则位于「设置 → 数据生成」。
|
||||
- 第一版使用单服务、方法 + 完整路径匹配（忽略尾斜杠），暂不支持路径参数、多响应条件及请求体匹配。JSON 可使用已有 `@integer` 等模板表达式；文本响应原样返回。
|
||||
- `./run.sh gui` 默认启动本机管理服务 `127.0.0.1:8787` 和独立 Mock 响应监听 `0.0.0.0:8788`。后者默认仅接受回环/私有网段来源，不注册账号、发布或代理管理路由；内网同事按实际 HTTP 方法访问 `http://本机内网IP:8788/mock/<token>/接口路径`。
|
||||
- Mock 页的路径输入框只填写 `/example` 等相对路径；保存并发布后，编辑器顶部会显示可复制的完整地址。`http://localhost:5173/mock/example` 指向桌面开发界面，不是 Mock 响应。默认无需额外 Header，完整地址包含随机地址令牌。若要进一步限制已获知地址的访问，可在「设置 → Mock 服务 → 访问验证」生成并保存 Bearer 密钥；访问者须发送 `Authorization: Bearer <密钥>`，服务只保存密钥摘要。浏览器地址栏无法设置此 Header，请使用接口请求页或 curl；试运行框可临时填写密钥。
|
||||
- 分享域名需由内网 DNS/hosts 解析到运行本机服务的机器；HTTPS 由内网反向代理提供，可将域名解析到内网 IP，也可自行端口映射或反向代理至公网 IP；数据仍保存在自有机器。输入分享地址不会自动修改 DNS、监听或部署。
|
||||
- 若只允许本机访问，启动前设置 `OPSXAPI_MOCK_ADDR=127.0.0.1:8788`；更改监听配置需停止后重新启动。设置页会显示配置的监听地址及本机地址候选；访问仍需端口可达。
|
||||
- 更新后运行 `./run.sh gui` 会检查 Mock 管理接口，并在本项目旧后端缺少该接口时重启服务；也可手动运行 `./run.sh stop && ./run.sh gui`。`http://localhost:5173/mock` 不是内网 Mock 服务入口，`:5173` 只是桌面界面的开发源。已发布示例的分享地址为 `http://本机内网IP:8788/mock/<随机令牌>/demo`；令牌可在 Mock 页面「已发布版本」中复制。`homepage/` 不参与 Mock 数据保存。
|
||||
|
||||
### 环境地址联动与自定义域名
|
||||
|
||||
请求建议保存 `/pet/1` 等相对路径，环境分别填写前置 URL（例如本地 `http://127.0.0.1:3000`、正式 `https://api.example.com`）。顶栏切换环境会同时改变地址栏前缀、实际请求和代码生成地址；方法及接口路径不变。完整 URL 保持固定，可通过「关联环境」把匹配已知环境前缀的 URL 转为相对路径。
|
||||
|
||||
Mock 设置支持「使用此 Mock 环境」，生成前置 URL `<分享地址>/mock/<token>`，同一接口路径即可在本地、正式、自托管 Mock 之间切换。下线后 token 失效，重新发布后需再次更新 Mock 环境。
|
||||
|
||||
分享地址支持自定义域名，用户自行配置 DNS、端口映射或反向代理及 HTTPS。若需要公网来源直接访问 Mock 响应端口，先停止服务，再运行 `OPSXAPI_MOCK_ALLOW_PUBLIC=1 ./run.sh gui`。此开关仅影响独立 Mock 响应端口，不开放发布、账号、工作区或代理管理接口，也不改变本地数据存储方式。
|
||||
Reference in new issue
Block a user