docs: AGENTS/SDD 对齐 Shell·DB，补架构页并清浏览器工作台口径

- 重写 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 当工作台的旧手测口径
2026-10-19 21:23:59 +08:00
1 parent 64bc8b1552
commit 9304b0e98c
@@ -1,8 +1,8 @@
 # OpsxAPI P0 手测脚本（10 步）

-前置：`export PATH="$HOME/.nvm/versions/node/v24.19.0/bin:$PATH"`，在仓库根目录 `./run.sh web`，打开 http://127.0.0.1:5173 。
+前置：`export PATH="$HOME/.nvm/versions/node/v24.19.0/bin:$PATH"`，在仓库根目录 `./run.sh gui`（桌面是唯一操作入口；不要用浏览器打开 Vite 开发源）。

-1. 打开工作台，确认左上可切到「自动化测试」（或顶栏进入测试视图）。
+1. 在桌面里确认左上可切到「自动化测试」（或顶栏进入测试视图）。
 2. 点 **装载回归示例**；环境应切到「本地」；出现用例「HTTP 八组合回归（本地 echo）」。
 3. 点该用例右上 **运行**；8 步应全绿（需 :8787 已起）。失败则看报告里哪一步断言挂了。
 4. 在报告区分别点 **导出 MD**、**导出 JSON**，确认文件可打开且 JSON 含 `schema: opsxapi.test-run.v1`。
@@ -11,6 +11,6 @@
 7. 对任一用例点定时图标：填 Cron `*/5 * * * *`（或短间隔），启用；保持页面打开。
 8. 等到命中分钟后，报告出现 trigger=定时；定时对话框可见「日志 …」一行；控制台有 `[OpsxAPI 定时]`。
 9. 手工再跑一遍八组合，确认与定时/AI 共用同一报告列表。
-10. 刷新页面：用例与最近报告仍在（localStorage）；`./run.sh status` 仍显示 server/web UP。
+10. 重启桌面后再开：用例与最近报告仍在（本机存储）；`./run.sh status` 里 desktop / server 为 UP。不要改用浏览器当工作台。

 回滚演示数据：设置里如有「重置工作区」则用之；或清站点 localStorage。
@@ -0,0 +1,12 @@
+# 文档索引
+
+| 文档 | 何时看 |
+| --- | --- |
+| [architecture.md](architecture.md) | 两套壳、目录、数据流、安全底线 |
+| [sdd-template.md](sdd-template.md) | S2/S3 短模板（与 OpsxShell / OpsxDB 同款） |
+| [specs/README.md](specs/README.md) | SDD 分级、评审状态、规格索引 |
+| [specs/_template.md](specs/_template.md) | 入库用长表；不与短模板并行第三套 |
+| [ROADMAP_ACTIVE.md](ROADMAP_ACTIVE.md) | 主动排期 |
+| [HANDTEST-P0.md](HANDTEST-P0.md) | P0 手测（走桌面，不走开浏览器工作台） |
+
+S0/S1 直接改代码。入口规则在仓库根 [AGENTS.md](../AGENTS.md)。
@@ -0,0 +1,50 @@
+# 架构说明
+
+一页。细节以代码和 [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。不要用浏览器打开它当工作台。
+
+## 目录权威
+
+当前 `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`、`apps/web`、`apps/server`、`packages/*` 在本仓库不存在。`docs/recovery/2026-10-14.md` 里的 `packages/` 是扁平化中途快照，不是现行路径。不要迁回，也不要再建第二棵 UI。
+
+## 数据流
+
+```text
+桌面 UI
+  → src/transport（直连 / Gin 代理 / Tauri）
+  → 127.0.0.1:8787  代理、账号、工作区、Mock 发布（仅本机管理）
+  → :8798           已发布 Mock 与只读文档分享（默认仅回环/私网来源）
+homepage/dist
+  → Gin 静态托管，与集合数据无关
+```
+
+- 集合、环境、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 响应正文。分享用随机令牌，不暴露空间归属。
@@ -0,0 +1,64 @@
+# SDD 模板路径: docs/sdd-template.md
+
+# SDD 模板（S2 / S3 使用）
+
+# SDD-xxx：<功能名称>
+
+| 字段           | 内容                  |
+|----------------|-----------------------|
+| 版本 / 变更级别 | 0.1 / S2 或 S3        |
+| 设计状态       | Draft                 |
+| 实现状态       | Not Started           |
+| 负责人 / 日期  | 待指定 / YYYY-MM-DD   |
+| 关联需求       | -                     |
+| 批准状态       | 未批准                |
+
+## 1. 背景、目标与范围
+- **当前行为与证据**：
+- **本次目标**：
+- **非目标**：
+- **必须保留的行为**：
+
+## 2. 需求与约束
+- FR-01：当 <条件> 时，系统必须 <行为>。
+- NFR-01：<性能 / 安全 / 兼容要求及测量方式>
+- 边界条件、异常场景、权限要求
+
+## 3. 架构与方案
+- 涉及模块及职责
+- 关键数据流 / 调用关系
+- 复用哪些现有能力
+- 关键取舍及理由
+- Agent 可自主决定的实现细节
+
+## 4. 接口、数据与配置契约
+（已有权威文件时直接引用路径，仅说明差异）
+- 接口变更：
+- 数据模型 / 迁移：
+- 配置变更：
+- 兼容性：
+
+## 5. 风险与验收
+
+### 风险
+| 风险或失败场景 | 防护 / 降级 / 恢复 | 可观察信号 |
+|----------------|--------------------|------------|
+|                |                    |            |
+
+### 验收标准
+| AC    | 对应需求 | 前置条件与操作 | 预期结果 | 验证方式 | 结果     |
+|-------|----------|----------------|----------|----------|----------|
+| AC-01 | FR-01    |                |          |          | Not Run  |
+
+## 6. 发布与恢复（S3 必填）
+- 前置条件（配置、迁移、备份等）
+- 发布顺序与健康检查
+- 回滚或前向修复步骤
+- 不可逆操作说明
+
+## 7. 待决问题
+| 问题 | 是否阻塞 | 推荐方案 |
+|------|----------|----------|
+|      |          |          |
+
+细流程、状态机与规格索引见 [docs/specs/README.md](specs/README.md)，长表用 [docs/specs/_template.md](specs/_template.md)。两套不并行发明第三份字段；S2/S3 起草可先填本短模板，评审入库时落到 `docs/specs/<domain>/<slug>.md`。
@@ -0,0 +1,53 @@
+# SDD 流程与规格索引
+
+SDD 是 Software Design Document（软件设计文档）；本项目以版本化设计契约驱动开发。需求说明“做什么”，设计说明“如何实现”，测试证据说明“是否做到”。
+
+## 分级与最小产物
+
+按最高影响定级，不以代码行数定级。
+
+| 级别 | 范围 | 实施前产物 |
+| --- | --- | --- |
+| S0 | 文案、格式、无行为变化的文档纠错 | 明确范围和检查方式，无需单独规格 |
+| S1 | 恢复已批准行为的缺陷修复、契约内重构 | 任务记录中的问题、依据、不变量、验收步骤 |
+| S2 | 新功能、API/IPC/配置/数据模型及跨模块行为变更 | 使用 [_template.md](_template.md) 创建或修订功能规格并评审 |
+| S3 | 权限、安全、迁移、删除数据、生产部署 | S2 + 风险、兼容、审计/观测（按产品边界）、发布与恢复方案 |
+
+规格保存在 `docs/specs/<domain>/<slug>.md`。持续开发同一能力时修订已有规格，不重复创建。小功能可将需求与设计分节写在同一文件；大型需求可单独成文并引用。不适用项写明原因。
+
+## 工作流与权限
+
+1. 调研：读取实际代码、适用规则、测试和未提交改动；区分事实、假设、提案。
+2. 需求：定义范围、非目标、用户场景、FR/NFR 及 AC；未知指标标待确认。
+3. 设计：明确边界、接口、数据、失败路径与测试预期，再评审。
+4. 实现：依据已批准版本实施，允许自主选择契约内实现细节。
+5. 验证：将每条 AC 映射至实现位置和测试证据，记录未运行项。
+6. 交付：报告差异、结果和剩余问题，不把构建成功等同功能验收。
+
+S2/S3 的业务行为和契约在实施前需要明确批准依据。已有明确授权覆盖该设计版本与范围时，记录原授权，不重复询问。Agent 不得将“需求看起来清楚”视为自行批准新设计的依据。
+阻塞问题只暂停依赖它的实现，其他调研、设计和独立工作可继续。
+
+## 版本与状态
+
+- 设计状态：Draft → In Review → Approved → Superseded。
+- 实现状态单独记录：Not Started / In Progress / Implemented / Verified。
+- 批准记录包含版本、批准人、日期和可追溯依据；模板不预填批准人。
+- 冻结代表版本受控。改变接口、数据语义、权限或验收预期时，先记录旧/新差异及影响，新版本重新评审；批准旧版本不等于批准新版本。
+- 现有代码只能作为“待评审现状基线”，不能直接标为已批准设计。
+- 文档更正但不改变契约时记录更正即可；不得借文档修订掩盖实现偏差。
+
+## 契约归属与完成条件
+
+SDD 明确接口、Schema、迁移及依赖锁文件的权威路径和版本，不复制多份字段表。当前代码与设计冲突时先判断是缺陷还是设计变更；不能自动以代码覆盖设计。
+仓库规范不覆盖适用的系统/工具限制；后续明确用户指令导致契约变化时应同步修订，不静默执行旧设计。
+
+测试场景和预期结果在实现前定义，测试代码可随实现完成。覆盖受影响的成功、边界、失败、权限和兼容行为。
+所有 AC 有通过证据且实现与契约一致，才可标 Verified。Blocked/Not Run 不算通过；记录命令/环境/日期或人工步骤及结果，不能仅写“已检查”。
+本文件是工作约定，不代表已启用 CI 或分支保护；需要强制禁止合并时须另行配置仓库门禁。
+
+## 规格索引
+
+当前仅建立流程与模板，尚无已批准功能规格。
+
+| 规格 | 版本 | 设计状态 | 实现状态 | 批准依据 |
+| --- | --- | --- | --- | --- |
@@ -0,0 +1,74 @@
+# SDD-<编号>：<功能名称>
+
+> 按需填写；不适用项说明原因。先写第 1–2 节需求，再写设计；实现前确定第 7 节的场景和预期。占位符不代表已完成评审。
+
+| 字段 | 内容 |
+| --- | --- |
+| 版本 / 变更级别 | 0.1 / S2 或 S3 |
+| 设计状态 / 实现状态 | Draft / Not Started |
+| 负责人 / 日期 | 待指定 / YYYY-MM-DD |
+| 关联需求 / 替代规格 | 待填写 / 无 |
+| 批准版本 / 人 / 日期 / 依据 | 未批准 |
+
+## 1. 现状、目标与范围
+
+- 当前行为与证据：<代码/配置/测试路径，区分事实和推测>
+- 用户角色与场景：<谁在什么条件下做什么>
+- 本次目标：<可观察结果>
+- 非目标及必须保留的行为：<明确边界>
+
+## 2. 需求（不写实现）
+
+- FR-01：当 <条件> 时，系统必须 <行为>。
+- NFR-01：<指标、适用规模、测量方式；未知值标待确认，不编造>。
+- 涉及的权限、兼容、输入边界和异常场景：<说明>。
+
+## 3. 架构与职责
+
+<模块、所有权、依赖方向、复用点、关键流程；复杂交互按需附时序图。>
+<备选方案及选择理由；契约内可自主决定的实现细节。>
+
+## 4. 接口、数据与配置契约
+
+| 契约 | 权威文件/版本或本节定义 | 本次差异及兼容策略 |
+| --- | --- | --- |
+| HTTP / IPC / 事件 | <路径、方法、请求、响应、错误码、校验、权限> | <填写或不适用原因> |
+| 数据 / 配置 | <字段、默认值、约束、持久化、迁移、锁文件> | <填写或不适用原因> |
+
+<涉及任务时明确超时、取消、重试、幂等、并发和状态转换；涉及列表时明确分页/排序；避免重复抄写已有 Schema。>
+
+## 5. UI 与交互（不适用则注明）
+
+<入口、主要操作、保存/失败恢复、空/加载/错误/禁用状态。>
+<最小尺寸、全局分栏、滚动区域、长内容、亮暗主题、键盘可达性及国际化。>
+
+## 6. 风险、安全与运行约束
+
+| 失败/风险场景 | 防护、降级或恢复 | 日志/指标/可观察状态 |
+| --- | --- | --- |
+| <场景> | <策略> | <验证方式> |
+
+<权限、凭据、脱敏、执行目标、外部调用及数据保留按需填写；不得扩展产品未授权的审计/审批能力。>
+
+## 7. 验收与验证证据
+
+| AC | FR/NFR | 给定/当/则（含明确预期） | 设计章节/实现位置 | 测试或人工步骤 | 结果及证据 |
+| --- | --- | --- | --- | --- | --- |
+| AC-01 | FR-01 | <正常场景> | <实现前可待填> | <用例/步骤> | Not Run |
+| AC-02 | FR-01 | <异常/边界场景> | <实现前可待填> | <用例/步骤> | Not Run |
+
+<运行后填写命令、环境、日期、结果或证据链接；阻塞与跳过必须说明原因。>
+
+## 8. 发布、迁移与恢复
+
+<适用时：前置条件、备份、发布顺序、健康检查、兼容窗口、回退触发条件、恢复步骤和不可逆限制；S3 必填。>
+
+## 9. 待决问题与变更记录
+
+| 问题 | 影响/是否阻塞 | 负责人/结论依据 |
+| --- | --- | --- |
+| <问题或明确无> | <影响> | <依据> |
+
+| 日期/版本 | 旧→新差异、原因与影响 | 批准依据 |
+| --- | --- | --- |
+| YYYY-MM-DD / 0.1 | 初始草案 | 未批准 |