diff --git a/docs/尚数网基本开发规范v3.0.md b/docs/尚数网基本开发规范v3.0.md index 380ce37..c7f2b4c 100644 --- a/docs/尚数网基本开发规范v3.0.md +++ b/docs/尚数网基本开发规范v3.0.md @@ -851,31 +851,10 @@ ssw-common-controller/ → 端点暴露 **三件套模板**: -```java -// 1. 接口 (ssw-common-biz/service/) -public interface XxxService { - ResultType doSomething(params); -} - -// 2. 实现 (ssw-common-biz/service/impl/) -@Service -public class XxxServiceImpl implements XxxService { - @Autowired private YyyUtil yyyUtil; - public ResultType doSomething(params) { - // 业务逻辑(调用工具类/数据库) - } -} - -// 3. Controller (ssw-common-controller/) -@RestController -@RequestMapping("/api/ssw") -public class XxxController { - @Autowired private XxxService xxxService; - @PostMapping("/xxx") - public ResultType doXxx(@RequestBody Params params) { - return xxxService.doSomething(params); - } -} +``` +1. 接口: ssw-common-biz/service/XxxService.java +2. 实现: ssw-common-biz/service/impl/XxxServiceImpl.java +3. Controller: ssw-common-controller/XxxController.java → @PostMapping("/api/ssw/xxx") ``` **关键约束**: @@ -1000,19 +979,12 @@ curl -X POST http://127.0.0.1:30000/api/ssw/xxx \ ``` 任务是什么? -├─ 新表单 + 走 UI 验证 → jnpf-browser-automation (Layer 1 浏览器) -├─ 已知模板批量重建 → dacli-ts form create --ai-json (Layer 2) -├─ JNPF 升级后回归 → jnpf-browser-automation (Layer 3 浏览器) -├─ API 层测试 → dacli-ts test run (~5s) -├─ 渲染层测试 → dacli-ts test render (~2s, ★ 替代浏览器) -├─ 浏览器 E2E → ssw-e2e-test (JNPF) / webapp-testing (通用) +├─ 表单/菜单/工作流 → dacli-ts / ssw-loop ├─ 后端业务开发 → backend-dev -├─ 前端 SPA 开发 → frontend-dev -├─ 独立 HTML 页面 → no-spa-page -├─ 编译/打包 → backend-dev (v0.12+ 合并) -├─ 完整 7 阶段开发 → ssw-loop -├─ 联网搜索/图片理解 → mmx-cli -└─ 命名规范问题 → basic-standards +├─ 前端开发 → frontend-dev / no-spa-page +├─ 测试 → dacli test run/render / ssw-e2e-test +├─ 浏览器交互 → jnpf-browser-automation +└─ 联网/其它 → mmx-cli / basic-standards ``` ### 12.7 改 web 端补丁管理 (MEMORY `feedback-web-patch-docs`) @@ -1331,27 +1303,19 @@ feat(): (vX.Y+) | v1.0 | 2025 | JNPF 手动, AI 不参与 | (基础) | | v2.0 | 2026-03 | + AIBridge (Python), 19 个独立 skill | aibridge 团队 | | **v3.0** | **2026-06-29** | **+ dacli (TS) + webapi 镜像 + 13 skill 收纳 + 7 阶段流程 + 4 关卡 CI + 3 HTML+4 MD 文档** | **Claude Code + dacli 团队** | -| **v3.0+** | **2026-06-29** | **+ 应用隔离方案 + CI 关卡 G + 回归审计 + webpatches 强制流程** | **Claude Code + dacli 团队** | -| **v3.0+** | **2026-07-03** | **+ ssw-common 扩展层使用规范 (§11.5, BS-新30 AI修复层/Workflow AI修复/DB clear 端点)** | **Claude Code + dacli 团队** | +| **v3.0+** | **2026-06 ~ 07** | **+ 应用隔离方案 + CI 关卡 G + 回归审计 + webpatches 强制流程 + ssw-common 扩展层** | **Claude Code + dacli 团队** | ### v3.0 vs v2.0 关键变化 | 维度 | v2.0 | v3.0 | |------|------|------| -| 工具栈 | Python `aibridge` (96 字符 AES 密文) | TS `dacli` (自动登录) | -| 命令 | 6 个 Python 构建器 | 22 父命令 / 116 子命令 / webapi 镜像 | -| 入口 | Python 脚本 | `dacli` 命令 + `--ai-json` 推荐 | -| 技能 | 19 个独立 skill | 13 个核心 skill (12 收纳到 dacli-ts) | -| 文档 | HTML only | 3 HTML + 4 MD (6 判据驱动) | -| 测试 | fixture | 真实业务数据 (`dacli test run --real-data`) | -| 反模式 | 文档约定 | CI 关卡强制 (4 关卡) | -| AI 协作 | 4 步流程 (手写) | 4 步前置 (Read CLAUDE.md / app context / dacli-ts SKILL / app status) | -| git 提交 | 手动 | 一轮一提交 + auto-push hook | -| 状态机 | 无 | dacli step machine 镜像 web 端 | -| 错误码 | 笼统 | 25+ 结构化错误码 (EXIST/FA/VS/FM/NET) | -| 子代理 | 手动 | 1 form = 1 代理, learnings.md 强制写入 | -| **CI 关卡 G** | 不存在 | **webapi 镜像架构自动检查 + git pre-commit hook 集成 + 故意 FAIL 白名单** | -| **回归审计方法论** | 不存在 | **盘点 → 并行审计 → 汇总报告 → 一轮一修复 (本 turn 产出 docs/cmd-review/regression-2026-06-29.md)** | +| 工具栈 | Python AIBridge | TS dacli + webapi 镜像 | +| 命令 | 6 个 Python 构建器 | 22 父命令 / 116 子命令 | +| 技能 | 19 个独立 skill | 13 个核心 skill | +| 文档 | HTML only | 3 HTML + 4 MD | +| 测试 | fixture | 真实业务数据 | +| 反模式 | 文档约定 | CI 关卡强制 | +| CI / 审计 | 无 | CI 关卡 G + 回归审计方法论 | --- @@ -1369,59 +1333,27 @@ feat(): (vX.Y+) | **2. _validate.ts 镜像精度** | "镜像 web" 注释数 + 精确行号引用 + ENCODE_REGEXP 复用 | 处理 enCode 但硬编码正则 (BS-56) | | **3. 回归盲点扫描** | 找出无 webapi 的命令 + 缺镜像注释的 _validate + 缺 ENCODE_REGEXP 的校验 | 同上 | -### 20.2 故意 FAIL 白名单机制 (v3.0+ 修 hook 误报) +### 20.2 白名单机制 -**背景**: 部分命令因 web 端架构差异, 故意不走标准镜像模式 (如 `di` 的 enCode 无正则), 之前 hook 会误报阻塞 commit. +部分命令因 web 端架构差异不走标准镜像模式(如 `di` 的 enCode 无正则),使用白名单避免误报。白名单命中 → WARN (exit 2);真实 FAIL → 阻塞 commit (exit 1)。添加白名单前必须明确 web 端架构差异。 -**机制** (`_gate_webapi.ts`): +### 20.3 git hooks 集成 -```typescript -const KNOWN_FALSE_POSITIVES: Record = { - di: 'web 端 di/Form.vue:172-178 明确"无 formValidate 正则, 只必填+maxlength" (架构差异, 不是 dacli 漏校验)', -} -``` +**pre-commit hook** 在每次 `git commit` 前自动跑 `npx tsx src/commands/_gate_webapi.ts`,真实 FAIL 阻塞 commit。跳过选项: `DACLI_SKIP_GATE=1` 环境变量(紧急绕过),`git config dacli.gate.enabled false`(永久禁用,不推荐)。 -- 白名单命中 → FAIL 转 WARN (exit 2) -- 真实 FAIL (排除白名单) 才阻塞 commit (exit 1) -- 输出明确标注 "(已知)" + 原因详情 - -**扩展指南**: 添加新白名单前必须明确 web 端架构差异, 避免掩盖真实问题. - -### 20.3 git hooks 自动集成 - -**pre-commit hook** (`dacli/.git/hooks/pre-commit`): - -- 触发: 每次 `git commit` 前 -- 跑: `npx tsx src/commands/_gate_webapi.ts` -- 真实 FAIL (exit 1) 阻塞 commit + 输出修复建议 -- WARN (exit 2) 通过但有提示 -- 跳过选项: - - `DACLI_SKIP_GATE=1` 环境变量 (紧急绕过) - - `git config dacli.gate.enabled false` (项目级永久禁用) - -### 20.4 用法 +### 20.4 用法与退出码 ```bash -# CI 关卡 G 单独跑 -npx tsx src/commands/_gate_webapi.ts - -# git commit 自动跑 (无需手动) -git commit -m "..." # hook 自动触发, 真实 FAIL 才阻塞 - -# 临时跳过 (紧急情况) -DACLI_SKIP_GATE=1 git commit -m "..." - -# 项目级禁用 (不推荐) -git config dacli.gate.enabled false +npx tsx src/commands/_gate_webapi.ts # 单独跑 +git commit -m "..." # 自动触发 +DACLI_SKIP_GATE=1 git commit -m "..." # 临时跳过 ``` -### 20.5 退出码 - | 退出码 | 含义 | 行为 | |--------|------|------| | 0 | PASS | 完全通过 | -| 1 | FAIL (真实违规) | **阻塞 commit** | -| 2 | WARN (有提示但不阻塞) | commit 通过 + 输出提示 | +| 1 | FAIL | **阻塞 commit** | +| 2 | WARN | commit 通过 + 提示 | ---