0 Fork 0

Files

T

logan 0c0423d3a1 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

2.4 KiB

Raw Permalink Blame History

OpsxAPI 开发指南

接口调试桌面客户端（HTTP / GraphQL / WebSocket / SSE / Socket.IO / MQTT）。请使用中文沟通。

产品形态（硬边界）

浏览器  →  只看官网 + 文档（homepage/，./run.sh web → :8787）
操作    →  只走桌面（./run.sh gui）

不要把请求工作台加回浏览器。

职责	目录权威
桌面操作（请求 / 文档编辑 / Mock / 自动化测试）	`apps/desktop`
共享 UI、传输、领域	`packages/*`
Gin（官网托管、代理、本机 API）	`apps/server`
官网 + 用户文档	`homepage/`

根目录 src/、src-tauri/、根 server/ 是误迁，不是目录权威。新功能写到上表，不要在根 src 上继续长。

同族：opsxshell / opsxdb 同形态（浏览器 = 官网/docs，操作 = 桌面）。

安全三句（不另开专章）

浏览器只看站 / 文档。运维与调试入口是 ./run.sh gui。
Mock 默认 127.0.0.1，不上公网。
/admin 不落明文（令牌、密钥、未发布集合不进页面或分享正文）。

怎么跑

./run.sh web          # 仅官网 + docs → http://127.0.0.1:8787/
./run.sh gui          # 桌面操作入口（推荐）
./run.sh stop | status

交互改动在桌面里点，构建通过不等于验收。不把本机数据库、访问令牌、AI 密钥或真实请求体提交进 git。

给 AI

需求清楚就直接改；不确定用最小假设并在回复里写明。
跟目录权威改，禁止在根 src 再起一套客户端。
少造文档；只改文档时核对链接，不要求重跑业务测试。
依赖版本以锁文件为准，规划中的能力不要写成已实现。

SDD 开发

按实际影响取最高级别：S0 文案/格式；S1 契约内修复/重构；S2 新功能、契约或数据模型；S3 安全权限、迁移/删除或生产变更。跨文件不自动升级。
S0 / S1 直接改代码，不套全模板。
S2 / S3 必填 docs/sdd-template.md（FR 对应 AC）。评审入库与状态机仍用 docs/specs/README.md、docs/specs/_template.md，不另造第三套。
未知标「待确认」。契约变化至少升到 S2。设计批准 ≠ 实现完成 ≠ 验证通过；没跑的检查标 Not Run。

一页架构见 docs/architecture.md。

2.4 KiB Raw Permalink Blame History Unescape Escape