docs: 锁定 apps/desktop 目录权威与 SDD 短模板

- AGENTS/architecture：目录权威改为 apps/desktop + packages/* + apps/server；根 src 标误迁 - sdd-template：补何时必填与 FR→AC，保留 Shell/DB 短模板体；细流程仍 docs/specs/ - 安全三行钉死；HANDTEST/README 已无浏览器 :5173 工作台口径
2026-10-19 21:27:13 +08:00
1 parent 9304b0e98c
commit 0c0423d3a1
@@ -5,75 +5,51 @@
 ## 产品形态（硬边界）

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

-| 职责 | 放哪 |
+不要把请求工作台加回浏览器。
+
+| 职责 | 目录权威 |
 | --- | --- |
-| 桌面操作（请求 / 文档编辑 / Mock 管理 / 自动化测试） | **本仓** `src/` + `src-tauri/` |
-| 官网 + 用户文档 | **本仓** `homepage/`（`tools/homepage-build` 出 dist，Gin 只托管） |
-| 本机 API、Mock 响应、代理 | **本仓** `server/`（Go / Gin） |
+| 桌面操作（请求 / 文档编辑 / Mock / 自动化测试） | `apps/desktop` |
+| 共享 UI、传输、领域 | `packages/*` |
+| Gin（官网托管、代理、本机 API） | `apps/server` |
+| 官网 + 用户文档 | `homepage/` |

-同族：`opsxshell` / `opsxdb` 同形态（浏览器 = 官网/docs，操作 = 桌面）。`src/` 里的 React 是 **Tauri WebView UI**，不是浏览器 SaaS。
+根目录 `src/`、`src-tauri/`、根 `server/` 是误迁，**不是**目录权威。新功能写到上表，不要在根 `src` 上继续长。

-### 安全三句（写进日常约束，不另开专章）
+同族：`opsxshell` / `opsxdb` 同形态（浏览器 = 官网/docs，操作 = 桌面）。

-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)。
+1. 浏览器只看站 / 文档。运维与调试入口是 `./run.sh gui`。
+2. Mock 默认 `127.0.0.1`，不上公网。
+3. `/admin` 不落明文（令牌、密钥、未发布集合不进页面或分享正文）。

 ## 怎么跑

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

-改功能后按范围：`npm test`、`npm run build`、`server/` 下 `go test ./...`、`cargo test --manifest-path src-tauri/Cargo.toml --locked`。交互改动在桌面里点，构建通过不等于验收。
+交互改动在桌面里点，构建通过不等于验收。不把本机数据库、访问令牌、AI 密钥或真实请求体提交进 git。

 ## 给 AI

 - 需求清楚就直接改；不确定用最小假设并在回复里写明。
- 跟仓内模式，禁止平行架构或第二套客户端。
+- 跟目录权威改，禁止在根 `src` 再起一套客户端。
 - 少造文档；只改文档时核对链接，不要求重跑业务测试。
 - 依赖版本以锁文件为准，规划中的能力不要写成已实现。
- 设计验收：请求 / 环境 / 文档 / 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。
+- **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)。
@@ -5,15 +5,14 @@
 **HTTP · GraphQL · WebSocket · SSE · Socket.IO · MQTT，一个工作台全搞定；数据全在本地。**

 ```
-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
+apps/desktop     桌面操作（Tauri；./run.sh gui）
+packages/*       共享 UI / 传输 / 领域
+apps/server      Gin（官网托管与本机 API）
+homepage/        官网 + 文档（浏览器只看这里）
 ```

+根目录 `src/`、`src-tauri/` 是误迁，不是目录权威。详见 [docs/architecture.md](docs/architecture.md)。
+
 核心原则：**一套 UI、一份请求契约；浏览器只看官网/docs，操作只走桌面。**

 ## 功能总览
@@ -111,7 +110,7 @@ cd server && go test ./...

 ## 开发布局

-前端在 `src/`（`core/`、`transport/`、`features/`、`components/`），Rust 在 `src-tauri/`，Gin 在 `server/`。本仓没有 `apps/` / `packages/` monorepo。`homepage/` 独立。边界与安全底线见 [docs/architecture.md](docs/architecture.md)。
+目录权威是 `apps/desktop`、`packages/*`、`apps/server`。浏览器只看 `homepage/` 的站和文档；操作入口 `./run.sh gui`。根目录 `src/` 不算权威。边界见 [docs/architecture.md](docs/architecture.md)。

 ```bash
 npm install
@@ -1,50 +1,38 @@
 # 架构说明

-一页。细节以代码和 [AGENTS.md](../AGENTS.md) 为准，不在这里重写功能清单。
+一页。规则以 [AGENTS.md](../AGENTS.md) 为准。

 ## 两套壳

 | 壳 | 入口 | 做什么 | 不做什么 |
 | --- | --- | --- | --- |
-| 浏览器 | `./run.sh web` → `http://127.0.0.1:8787/` | 官网、`/docs`、定价（`homepage/dist`） | 请求、集合、Mock 管理、自动化测试 |
-| 桌面 | `./run.sh gui` | 全部操作（Tauri WebView + Rust） | 不把这套 UI 当成浏览器产品 |
-
-Vite 开发源只给桌面 WebView。不要用浏览器打开它当工作台。
+| 浏览器 | `./run.sh web` → `http://127.0.0.1:8787/` | 官网、文档、定价（`homepage/`） | 请求、集合、Mock 管理、自动化测试 |
+| 桌面 | `./run.sh gui` | 全部操作 | 不把这套 UI 当成浏览器产品 |

 ## 目录权威

-当前 `main` 是扁平根目录，**不是** monorepo：
-
 ```text
-src/                     唯一产品 UI（React）
-src/transport/           请求传输；Tauri 调用只走 ipc.ts
-src/features/            功能域
-src/components/          界面组合
-src-tauri/               Tauri 2；command 适配，业务在 src/services/
-server/                  Gin 管理面（默认 127.0.0.1:8787）+ Mock 响应监听
-homepage/                官网与文档源
-tools/homepage-build/    静态站构建
+apps/desktop     桌面 Tauri（唯一操作入口的代码）
+packages/*       共享 UI / 传输 / 领域
+apps/server      Gin：官网静态托管、代理、本机 API
+homepage/        官网与文档源
 ```

-`apps/desktop`、`apps/web`、`apps/server`、`packages/*` 在本仓库不存在。`docs/recovery/2026-10-14.md` 里的 `packages/` 是扁平化中途快照，不是现行路径。不要迁回，也不要再建第二棵 UI。
+根目录 `src/`、`src-tauri/`、根 `server/` 是误迁，不算权威，不要在上面继续长功能。

 ## 数据流

 ```text
-桌面 UI
-  → src/transport（直连 / Gin 代理 / Tauri）
-  → 127.0.0.1:8787  代理、账号、工作区、Mock 发布（仅本机管理）
-  → :8798           已发布 Mock 与只读文档分享（默认仅回环/私网来源）
-homepage/dist
-  → Gin 静态托管，与集合数据无关
+apps/desktop
+  → packages/*（传输与领域）
+  → apps/server  127.0.0.1   管理 / 代理 / Mock 发布
+  → Mock 响应    默认 127.0.0.1（不对公网）
+homepage
+  → 浏览器只读官网与文档，不碰集合与密钥
 ```

- 集合、环境、Mock 草稿在本机；发布进本机 SQLite，不因登录改存公网。
- 实时协议会话不落盘。
- 分享快照不含鉴权、环境变量和运行历史。
+## 安全三行

-## 安全底线
-
-1. **浏览器只站 + 文档。** 工作台只在 `./run.sh gui`。不要把操作面加回官网。
-2. **Mock 不上公网。** 管理 API 留在 `127.0.0.1:8787`。`:8798` 默认拒绝公网来源；要放开必须显式 `OPSXAPI_MOCK_ALLOW_PUBLIC=1`，且仍不开放发布/账号/代理管理。只本机时用 `OPSXAPI_MOCK_ADDR=127.0.0.1:8798`。
-3. **敏感不明文。** 无对公 `/admin`。令牌、密钥、未发布数据不进官网、文档分享和 Mock 响应正文。分享用随机令牌，不暴露空间归属。
+1. 浏览器只看站 / 文档。操作只走 `./run.sh gui`。
+2. Mock 默认 `127.0.0.1`，不上公网。
+3. `/admin` 不落明文。
@@ -1,4 +1,10 @@
-# SDD 模板路径: docs/sdd-template.md
+# SDD 模板（S2 / S3 必填）
+
+**何时必填：** S2（新功能、接口/配置/数据模型、跨模块行为）和 S3（权限、安全、迁移/删除、生产变更）动工前填本模板。S0 文案与 S1 契约内修复直接改代码，不套本模板。
+
+**FR → AC：** 第 2 节每条 FR/NFR 在第 5 节有对应 AC（前置、操作、预期、验证方式）。S3 另填第 6 节发布与恢复。
+
+细流程、评审状态与规格索引仍是 [docs/specs/README.md](specs/README.md)；入库长表用 [docs/specs/_template.md](specs/_template.md)。不另造第三套字段。

 # SDD 模板（S2 / S3 使用）

@@ -60,5 +66,3 @@
 | 问题 | 是否阻塞 | 推荐方案 |
 |------|----------|----------|
 |      |          |          |
-
-细流程、状态机与规格索引见 [docs/specs/README.md](specs/README.md)，长表用 [docs/specs/_template.md](specs/_template.md)。两套不并行发明第三份字段；S2/S3 起草可先填本短模板，评审入库时落到 `docs/specs/<domain>/<slug>.md`。