From 9304b0e98cdb957a9b24be9b93346e2068458bfe Mon Sep 17 00:00:00 2001 From: logan Date: Mon, 19 Oct 2026 21:23:59 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20AGENTS/SDD=20=E5=AF=B9=E9=BD=90=20Shell?= =?UTF-8?q?=C2=B7DB=EF=BC=8C=E8=A1=A5=E6=9E=B6=E6=9E=84=E9=A1=B5=E5=B9=B6?= =?UTF-8?q?=E6=B8=85=E6=B5=8F=E8=A7=88=E5=99=A8=E5=B7=A5=E4=BD=9C=E5=8F=B0?= =?UTF-8?q?=E5=8F=A3=E5=BE=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 重写 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 当工作台的旧手测口径 --- AGENTS.md | 79 +++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 8 +++++ README.md | 12 +++---- docs/HANDTEST-P0.md | 6 ++-- docs/README.md | 12 +++++++ docs/architecture.md | 50 ++++++++++++++++++++++++++ docs/sdd-template.md | 64 +++++++++++++++++++++++++++++++++ docs/specs/README.md | 53 +++++++++++++++++++++++++++ docs/specs/_template.md | 74 ++++++++++++++++++++++++++++++++++++++ sdd-agents.md | 35 ++++++++++++++++++ 10 files changed, 384 insertions(+), 9 deletions(-) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 docs/README.md create mode 100644 docs/architecture.md create mode 100644 docs/sdd-template.md create mode 100644 docs/specs/README.md create mode 100644 docs/specs/_template.md create mode 100644 sdd-agents.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..aaa75d2 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,79 @@ +# OpsxAPI 开发指南 + +接口调试**桌面**客户端（HTTP / GraphQL / WebSocket / SSE / Socket.IO / MQTT）。请使用中文沟通。 + +## 产品形态（硬边界） + +```text +浏览器 → 只看官网 + 文档（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。 + +### 安全三句（写进日常约束，不另开专章） + +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)。 + +## 怎么跑 + +```bash +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/sdd-template.md)。评审入库与状态机用 [docs/specs/README.md](docs/specs/README.md) 和 [docs/specs/_template.md](docs/specs/_template.md)，不另造第三套字段。S3 写清风险与恢复。 +- 引用仓内契约与测试；未知标「待确认」。已授权的范围不重复审批；契约变化至少升到 S2。 +- 设计批准 ≠ 实现完成 ≠ 验证通过；没跑的检查标 Not Run。 diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..91fd68f --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,8 @@ +# OpsxAPI 项目入口 + +请先阅读 [AGENTS.md](AGENTS.md)。公共规则只维护在该文件中。 + +- 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) +- 架构一页：[docs/architecture.md](docs/architecture.md) diff --git a/README.md b/README.md index dc6cee3..20fa1b7 100644 --- a/README.md +++ b/README.md @@ -60,7 +60,7 @@ make install ./run.sh stop | status ``` -打开 http://127.0.0.1:8787/ 看落地页；操作请用 `./run.sh gui`。`:5173` 只是桌面 WebView 源。 +打开 http://127.0.0.1:8787/ 看落地页；操作只走 `./run.sh gui`。不要用浏览器打开 Vite 开发源当工作台。 ## 官网 / 文档 / 定价（homepage/，纯静态） @@ -104,14 +104,14 @@ cd server && go test ./... ## P0 自动化演示（本地） -1. `./run.sh gui` → 桌面工作台（Gin `:8787` + Vite 源） +1. `./run.sh gui` → 桌面操作入口（本机 Gin 默认 `:8787`） 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/` 保留本地辅助服务。 +前端在 `src/`（`core/`、`transport/`、`features/`、`components/`），Rust 在 `src-tauri/`，Gin 在 `server/`。本仓没有 `apps/` / `packages/` monorepo。`homepage/` 独立。边界与安全底线见 [docs/architecture.md](docs/architecture.md)。 ```bash npm install @@ -139,10 +139,10 @@ cargo test --manifest-path src-tauri/Cargo.toml --lib - Mock 页面顶部可直接启用或关闭 HTTP 响应，并可一键创建 `GET /demo` 示例；保存草稿后点击「发布全部已保存接口」，在已发布版本中试运行。设置 → Mock 服务保留相同开关及分享地址、环境关联配置。关闭后返回 503，保留数据和监听端口；彻底停止进程使用 `./run.sh stop`。随机数据生成规则位于「设置 → 数据生成」。 - 第一版使用单服务、方法 + 完整路径匹配（忽略尾斜杠），暂不支持路径参数、多响应条件及请求体匹配。JSON 可使用已有 `@integer` 等模板表达式；文本响应原样返回。 - `./run.sh gui` 默认启动本机管理服务 `127.0.0.1:8787` 和独立 Mock 响应监听 `0.0.0.0:8798`。后者默认仅接受回环/私有网段来源，不注册账号、发布或代理管理路由；内网同事按实际 HTTP 方法访问 `http://本机内网IP:8798/mock//接口路径`。 -- Mock 页的路径输入框只填写 `/example` 等相对路径；保存并发布后，编辑器顶部会显示可复制的完整地址。`http://localhost:5173/mock/example` 指向桌面开发界面，不是 Mock 响应。默认无需额外 Header，完整地址包含随机地址令牌。若要进一步限制已获知地址的访问，可在「设置 → Mock 服务 → 访问验证」生成并保存 Bearer 密钥；访问者须发送 `Authorization: Bearer <密钥>`，服务只保存密钥摘要。浏览器地址栏无法设置此 Header，请使用接口请求页或 curl；试运行框可临时填写密钥。 +- Mock 页的路径输入框只填写 `/example` 等相对路径；保存并发布后，编辑器顶部会显示可复制的完整地址。浏览器里的 Vite 开发源（含 `/mock/...`）不是 Mock 响应，也不是工作台入口。默认无需额外 Header，完整地址包含随机地址令牌。若要进一步限制已获知地址的访问，可在「设置 → Mock 服务 → 访问验证」生成并保存 Bearer 密钥；访问者须发送 `Authorization: Bearer <密钥>`，服务只保存密钥摘要。浏览器地址栏无法设置此 Header，请使用接口请求页或 curl；试运行框可临时填写密钥。 - 分享域名需由内网 DNS/hosts 解析到运行本机服务的机器；HTTPS 由内网反向代理提供，可将域名解析到内网 IP，也可自行端口映射或反向代理至公网 IP；数据仍保存在自有机器。输入分享地址不会自动修改 DNS、监听或部署。 - 若只允许本机访问，启动前设置 `OPSXAPI_MOCK_ADDR=127.0.0.1:8798`；更改监听配置需停止后重新启动。设置页会显示配置的监听地址及本机地址候选；访问仍需端口可达。 -- 更新后运行 `./run.sh gui` 会检查 Mock 管理接口，并在本项目旧后端缺少该接口时重启服务；也可手动运行 `./run.sh stop && ./run.sh gui`。`http://localhost:5173/mock` 不是内网 Mock 服务入口，`:5173` 只是桌面界面的开发源。已发布示例的分享地址为 `http://本机内网IP:8798/mock/<随机令牌>/demo`；令牌可在 Mock 页面「已发布版本」中复制。`homepage/` 不参与 Mock 数据保存。 +- 更新后运行 `./run.sh gui` 会检查 Mock 管理接口，并在本项目旧后端缺少该接口时重启服务；也可手动运行 `./run.sh stop && ./run.sh gui`。不要把 Vite 开发源当成内网 Mock 入口或浏览器工作台。已发布示例的分享地址为 `http://本机内网IP:8798/mock/<随机令牌>/demo`；令牌可在 Mock 页面「已发布版本」中复制。`homepage/` 不参与 Mock 数据保存。 ### 环境地址联动与自定义域名 diff --git a/docs/HANDTEST-P0.md b/docs/HANDTEST-P0.md index 16dc36e..fa2dcef 100644 --- a/docs/HANDTEST-P0.md +++ b/docs/HANDTEST-P0.md @@ -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。 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..1a452c1 --- /dev/null +++ b/docs/README.md @@ -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)。 diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..1ceaac9 --- /dev/null +++ b/docs/architecture.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 响应正文。分享用随机令牌，不暴露空间归属。 diff --git a/docs/sdd-template.md b/docs/sdd-template.md new file mode 100644 index 0000000..7452e55 --- /dev/null +++ b/docs/sdd-template.md @@ -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//.md`。 diff --git a/docs/specs/README.md b/docs/specs/README.md new file mode 100644 index 0000000..617baa8 --- /dev/null +++ b/docs/specs/README.md @@ -0,0 +1,53 @@ +# SDD 流程与规格索引 + +SDD 是 Software Design Document（软件设计文档）；本项目以版本化设计契约驱动开发。需求说明“做什么”，设计说明“如何实现”，测试证据说明“是否做到”。 + +## 分级与最小产物 + +按最高影响定级，不以代码行数定级。 + +| 级别 | 范围 | 实施前产物 | +| --- | --- | --- | +| S0 | 文案、格式、无行为变化的文档纠错 | 明确范围和检查方式，无需单独规格 | +| S1 | 恢复已批准行为的缺陷修复、契约内重构 | 任务记录中的问题、依据、不变量、验收步骤 | +| S2 | 新功能、API/IPC/配置/数据模型及跨模块行为变更 | 使用 [_template.md](_template.md) 创建或修订功能规格并评审 | +| S3 | 权限、安全、迁移、删除数据、生产部署 | S2 + 风险、兼容、审计/观测（按产品边界）、发布与恢复方案 | + +规格保存在 `docs/specs//.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 或分支保护；需要强制禁止合并时须另行配置仓库门禁。 + +## 规格索引 + +当前仅建立流程与模板，尚无已批准功能规格。 + +| 规格 | 版本 | 设计状态 | 实现状态 | 批准依据 | +| --- | --- | --- | --- | --- | diff --git a/docs/specs/_template.md b/docs/specs/_template.md new file mode 100644 index 0000000..b13dde0 --- /dev/null +++ b/docs/specs/_template.md @@ -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 | 初始草案 | 未批准 | diff --git a/sdd-agents.md b/sdd-agents.md new file mode 100644 index 0000000..ef33079 --- /dev/null +++ b/sdd-agents.md @@ -0,0 +1,35 @@ +# 主指令路径: AGENTS.md +# 软件设计与开发规范 + +你是本项目的软件设计与开发助手，采用 **SDD 驱动开发**。公共规则以 [AGENTS.md](AGENTS.md) 为准。 + +## 核心原则 +1. 若本次任务写明「只设计」，则不改业务代码；已授权实现则按批准范围继续，不重复审批。 +2. 不编造业务规则、性能指标、依赖版本或批准记录。未知内容标记「待确认」。 +3. 不擅自扩展需求范围，不改变现有接口、数据语义和权限。 +4. 优先引用项目中已有的权威来源（代码、OpenAPI、配置、测试）。 +5. 按实际影响定级，发现契约变化时必须升级。 + +## 变更级别 +| 级别 | 适用场景 | 文档要求 | +|------|----------|----------| +| S0 | 文案、格式、无行为变化的修正 | 直接改；简要说明即可 | +| S1 | 缺陷修复、契约内重构 | 直接改；说明问题、依据、不变量和验收方式 | +| S2 | 新功能、接口、数据模型、跨模块行为变更 | 使用 `docs/sdd-template.md` | +| S3 | 权限、安全、数据迁移/删除、生产变更 | S2 + 风险与回滚（模板第 6 节） | + +细流程与规格索引见 `docs/specs/README.md`，长表见 `docs/specs/_template.md`。与短模板二选一落盘，不并行第三套。 + +## 输出要求 +按以下顺序回复： + +1. **变更分级及理由** +2. **设计文档** + - S0 / S1：直接简要描述，然后改代码 + - S2 / S3：严格按照 `docs/sdd-template.md` 输出 +3. **需要负责人决策的问题**（附推荐方案；无则省略） + +## 补充说明 +- 设计批准 ≠ 实现完成 ≠ 验证通过。 +- 未运行的检查不能标记为通过。 +- 只暂停依赖阻塞问题的实现，可继续独立的调研和设计工作。