diff --git a/CLAUDE.md b/CLAUDE.md index c0f50cc..f0d899c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -640,12 +640,11 @@ cd $ccWorkDir/test && npx playwright test --project=chromium | 技能 | 触发词 | 用途 | |------|--------|------| | **dacli-ts** | dacli / JNPF CLI / form / menu / workflow / dict / dm / di / bigscreen / portal / role / log | **JNPF 单命令入口**(22 父命令 / 116 子命令 + 5 要素 + step machine + 错误码 + 9 个 references)| -| ssw-h5dev-flow | ssw-h5dev-flow | **H5开发主流程**(HTML格式设计/测试/计划/总结) | +| ssw-h5dev-flow | ssw-h5dev-flow | **H5开发主流程**(v0.11g+, 7阶段 + 4关卡 CI + 子代理派发, 模板+脚本在 skill 目录)| | ssw-onlinedev | ssw-onlinedev | 快速创建在线功能表单(自动发布) | | ssw-code-gen | ssw-code-gen | JNPF代码生成与菜单挂载 | -| ssw-test | ssw-test | Playwright E2E 测试 | +| ssw-e2e-test | ssw-e2e-test | E2E测试(基于Playwright + dacli, 含 ssw-test 已并入)| | ssw-pack-init | ssw-pack-init | boot模块编译打包 | -| ssw-e2e-test | ssw-e2e-test | E2E测试(基于Playwright + dacli) | | backend-dev | backend-dev | 后端业务类开发 | | frontend-dev | frontend-dev | 复杂前端页面开发 | | no-spa-page | no-spa-page | JNPF独立页面/非SPA页面开发 | @@ -657,11 +656,19 @@ cd $ccWorkDir/test && npx playwright test --project=chromium ## 开发流程(ssw-h5dev-flow) -使用 `/ssw-h5dev-flow` 进行完整功能开发,7个阶段: +使用 `/ssw-h5dev-flow` 进行完整功能开发,7个阶段 + 4 关卡 CI: ``` -初始化(dacli app init) → 设计(design.html+testcase.html) → 审核 → 执行(表单→代码生成→菜单) → 测试 → 总结 +初始化(dacli app init) → 设计(design.html+testcase.html) → 审核 → 执行(子代理派发,1 form=1代理) → 测试(TC-A→TC-C→TC-B三层 ladder) → 总结(关卡 B 防假 PASS) ``` +**4 关卡 CI**(写在 `.claude/skills/ssw-h5dev-flow/scripts/`): +- **关卡 A** `check_required_docs.sh` - 5 HTML 必填 (design/testcase/plan/debug/summary) +- **关卡 B** `check_summary_no_fake_pass.sh` - 4 铁律 (按钮存在性/skip modal≠PASS/CREATE failed≠PASS/截图去重) +- **关卡 C** `check_subagent_learnings.sh` - 子代理 learnings.md 强制写入 +- **关卡 F** `check_html_assets.sh` - HTML 必引 `../_assets/style.css` 不内联 + +> 模板/参考/脚本全部在 skill 目录, 零应用信息硬编码, 用 `dacli app context --json` 动态获取. + ### HTML 输出规范 所有设计/计划/测试/总结文档输出为 HTML 格式到 `docs/{app_code}/`: - **plan.html** 每完成一个关键步骤立即更新,**会话中断后第一件事读取它恢复上下文** diff --git a/commands/ssw-h5dev-flow.md b/commands/ssw-h5dev-flow.md deleted file mode 100644 index 0e6159d..0000000 --- a/commands/ssw-h5dev-flow.md +++ /dev/null @@ -1,533 +0,0 @@ ---- -skill: h5dev-flow -description: JNPF + dacli H5开发流程(HTML格式设计/测试/计划/总结) -triggerWords: [h5dev-flow, h5-dev-flow, ssw-h5dev-flow, ssw-h5dev, 开发流程, h5开发, dacli开发] -autoTrigger: false ---- - -# ssw-h5dev-flow - -基于 JNPF 低代码平台 + dacli 的通用软件开发流程(**HTML格式**设计/测试/计划/总结) - ---- - -## ⚠️ 上下文恢复警告(Compaction 后必读) - -**context 用完/会话中断后,第一件事是恢复上下文!** - -### 步骤 1:快速了解文档结构 -```bash -dacli doc list --dir=docs/{app_code} -``` -查看所有 HTML 文档的 section 索引、文件大小、修改时间(**1K tokens** vs Read 全部 25K)。 - -### 步骤 2:按需读取节内容(**核心**) -```bash -# ✅ v0.11+ 推荐: 用 doc toc + doc search (上下文恢复, 节省 40-60% token) -dacli doc toc --dir=docs/{app_code} # 看 section 索引 + 文件大小 -dacli doc search --dir=docs/{app_code} --keyword=架构 # 全文搜索关键词 - -# 备: Read 工具直接读 HTML 文件 (Claude 内置), 或 -# python3 -c "from html.parser import HTMLParser; ..." 自抽纯文本 -``` - -### 步骤 3(可选):刷新缓存 -```bash -# 文档更新后强制刷新 (v0.11+ 已实现) -# dacli doc 命令内置 mtime 感知 SQLite 缓存 7 天 TTL, 默认无需刷新 -# 备: 用 Read 工具直接读新文件即可 -``` - -### 步骤 4:继续阶段执行,不要从头开始! - -**`dacli doc` 优势**: -- 去除 HTML 标签/script/style/Mermaid 噪声 -- 按 section/行号精确读取 -- Redis 缓存命中时 <50ms 返回 -- **Token 用量降低 80%**(25K → 5K) - -**plan.html 必须及时更新**:每完成一个关键步骤就更新,不要等到最后才写。 - -**dacli 登录恢复**: -```bash -# 上下文恢复后先确认登录状态 -dacli app status -# 如未登录或 appCode 不对,重新登录 -dacli app login --account=admin --password=<密码> --appCode= -``` - -## ⚠️ 关键 7 字段必填 (本轮打磨核心发现) - -**菜单必填字段 (从 dacli 源码验证)**: -```java -{ - "parentId": "...", // 父菜单ID,顶级 "-1" - "fullName": "名称", - "enCode": "编码", - "type": 1|2|3, - "category": "Web", // 关键!不设不显示 - "linkTarget": "_self", // 关键!不设不显示 - "isButtonAuthorize": 1, // 关键! - "isColumnAuthorize": 1, // 关键! - "isDataAuthorize": 1, // 关键! - "isFormAuthorize": 1, // 关键! - "propertyJson": "..." // 关键!type=3 必须含 moduleId -} -``` - -**表单菜单 propertyJson**: -```json -{"moduleId": "FORM_ID", "iconBackgroundColor": "", "isTree": 0, "webType": 2} -``` - -> ⚠️ **D-12 防御 (2026-06-23 jxcj E2E 复盘)**: 低级 mode `dacli menu create --type=3 --urlAddress=model/{enCode}` 走 `/system/Menu` 直接 POST, **不会自动填 moduleId**, 浏览器层 form 列表/新增/编辑/详情全空白 (前端 vue vxe-table 用 moduleId 找数据源, 不看 urlAddress). 两种修法: -> 1. 改用高级 mode `dacli menu create --formId={form_id}` 走 `Actions/Module` (后端自动授权 + 自动构造 moduleId) -> 2. v0.11.4+ 自动检测 `--type=3 + urlAddress startsWith "model/"` → 拉 form 填 moduleId, 但仍需后续手动给角色授权 -> 兜底修复脚本: 拉菜单 + 改 `propertyJson.moduleId = form.id` + PUT (参考 jxcj 17_fix_moduleId_v2.py) - -**D-13 防御 (formData 渲染空)**: v0.11+ 删 `--fields` 简化版 (`wrapSimplifiedFields` 已删). 推荐走 `--ai-json` 路径, web 端 buildFormData 自动注入 formId/visibility/tableName/renderKey/tag/span 等 18+ 关键键, schema 100% 完整. - -**快速修复菜单不显示**: -```bash -# ⚠️ v0.7+ 校准 (2026-06-21): `dacli menu` 已有 7 子命令: list / info / create / delete / unrelease / releases / purge -# 真替代: 删菜单重建 `dacli menu create --formId=X`, 或 `dacli menu info --id=X` 校验 7 必填字段, 或 `dacli menu purge --formId=X` 一次清 -# 历史参考: Java v10.6 有 `dacli menu update --fixDisplay=true` + `cleanup/move/clone/export/import`, **TS 版**未实现 (无需再记) -``` - ---- - -## HTML文件命名规范 - -使用 `/ssw-h5dev-flow` 时,所有输出文件均为 **HTML格式**(人类可高效阅读/参与): - -| 文件 | 说明 | -|------|------| -| `design.html` | 详细设计方案 | -| `testcase.html` | 测试用例 | -| `debug.html` | 遇到的问题及处理措施 | -| `plan.html` | 开发计划 | -| `summary.html` | 总结报告 | - -**HTML生成提示词模板**: -``` -请生成 docs/{app_code}/ 目录下的 HTML 文件: -- CSS/JS 单独存放于 assets/ 目录(如 assets/style.css, assets/script.js) -- 主 HTML 文件仅引用外部资源,保持简洁 -- 暗黑风格、左侧可点击目录 -- 每个章节标题旁有「复制」按钮,点击生成 /ssw-h5dev-flow 提示词 -- Mermaid 图表展示架构、流程、状态图 -- 表格紧凑不换行 -- 基于以下内容设计:{source_path 或现有设计内容} -``` - -**目录结构示例**: -``` -docs/{app_code}/ -├── assets/ -│ ├── style.css # 共用样式(暗黑风格、表格、目录) -│ ├── script.js # 共用脚本(目录高亮、复制按钮、滚动监听) -│ └── mermaid.css # Mermaid 图表样式 -├── design.html # 详细设计方案 -├── testcase.html # 测试用例 -├── debug.html # 问题记录 -├── plan.html # 开发计划 -└── summary.html # 总结报告 -``` - -## 设计模板 - -设计阶段可使用以下模板快速生成高质量文档: - -| 模板 | 路径 | 用途 | -|------|------|------| -| 功能设计模板 | `.claude/templates/功能设计模板.md` | 阶段2 详细设计(字段定义、列表配置、菜单、流程) | -| 测试用例模板 | `.claude/templates/测试用例模板.md` | 阶段2 测试用例(TC编号、优先级、步骤、缺陷跟踪) | -| 需求文档模板 | `.claude/templates/需求文档模板.md` | 阶段2 需求分析(业务分析、功能需求、验收标准) | - -> 模板为 Markdown 格式,生成 design.html/testcase.html 时参考模板结构,输出为 HTML 格式。 - ---- - -## 阶段总览 - -| 阶段 | 内容 | 输出 | -|------|------|------| -| 阶段1 | 初始化环境 (dacli app init) | - | -| 阶段2 | 设计 → design.html + testcase.html | **design.html** + **testcase.html** | -| 阶段3 | 审核 | - | -| 阶段4 | 执行(/ssw-onlinedev → /ssw-code-gen → 扩展开发) | - | -| 阶段5 | 测试 (/ssw-test) | 测试报告 | -| 阶段6 | 总结 | **summary.html** | -| 阶段7 | 迭代 | - | - -> 配置通过 dacli 管理:`dacli app login --appCode=` 切换应用,token 自动存储在 `$ccWorkDir/.dacli-token/token.json` (注意: 实际是 .dacli-token, 不是 .dacli)(有效期7天)。执行 `dacli app status` 查看当前登录状态和 app_code。 - -> ⚠️ **后端运行环境**:jnpf-admin **仅支持 Java 8**,后端代码禁止使用 Java 11+ 特性(如 `var` 推断) - -> ⚠️ **浏览器层验证强约束**:`testcase.html` 必含 ≥ 3 个浏览器层 TC(`TC-{form#}-B{n}` 格式)+ 3 步截图(list/add/data)+ label 非空断言。详见阶段 5 铁律 1。 - ---- - -## plan.html 模板 - -**plan.html 仅用于进度追踪**,详细设计/需求查看 `design.html`。 - -```html - -{app_name} 开发计划 - -

{app_name} 开发计划

-

app_code: {app_code} | 当前阶段: 阶段X | 最后更新: YYYY-MM-DD | design.html

-

阶段1: 初始化环境

-

阶段2: 设计

-
-

阶段3-5: 审核/执行/测试

-
-

阶段6: 总结

-

当前任务

(上下文恢复时从此处继续)

-

阶段 4 已决事项 (子代理摘要回写)

- - - - -
enCodeidstateidempotency关键决策
每 form 完成由子代理回写 1 行. 例:
tdss_user_ext8351684906786579891created用 inputNumber 不用 input (decimal 字段)
- -``` - ---- - -## 输入参数 - -| 参数 | 说明 | 必填 | -|------|------|------| -| `app_code` | 应用编码(英文唯一标识) | 是 | -| `app_name` | 应用名称 | 是 | -| `source_path` | 源码/文档路径(可空) | 否 | -| `db_name` | 数据库名(默认同 app_code) | 否 | - ---- - -## 开发阶段 - -### 阶段1: 初始化环境 -使用 dacli 初始化应用: -```bash -# ⚠️ v0.8.1 校准: `dacli app init` TS 版是子命令 `dacli app init`, 选项只有 --appCode / --restart -# 原 Java 版 `--appName / --dbName` TS 版无对应 (应用名/db 名从 JNPF 后端自动读) -dacli app init --appCode={app_code} [--restart] -dacli app login --account=admin --password=<密码> --appCode={app_code} -dacli app status # 确认登录状态 -``` - -### 阶段2: 设计 -1. 分析 `{source_path}` 文档、源码、数据库(如有) -2. 结合 JNPF 平台能力设计: - - **基本框架**:JNPF 用户、权限、菜单、角色 - - **模型设计**:表单控件、关联字段(**关联字段[必须用 relationForm 组件,禁止用 input 文本框!!!]**) - - **流程设计**:使用 Flowable 工作流 - - **功能表单**:优先用表单实现,复杂逻辑用扩展代码 - - **UI 设计**:基于 JNPF 组件 - - **【重要】relationForm 的 columnOptions 列数不能超过 5 列**,否则弹窗列表无法正常显示 - - 通过 dacli CLI 使用 JNPF 来开发实现 -3. 输出文档到 `$ccWorkDir/docs/{app_code}/`: - - `design.html` (**HTML格式**,人类可读) - - `testcase.html` (**HTML格式**,人类可读) - - **`design-jnpf.html`**(**JNPF 平台对齐的详细设计**,按 JNPF 维度:表结构/组件/接口/JS 增强/字典/权限/关联逻辑/查询字段/显示字段) - - **JNPF 详细设计骨架**:`.claude/templates/jnpf-design-card.tmpl`(单表)/ `jnpf-design-master-sub.tmpl`(主子表)/ `jnpf-design-workflow.tmpl`(工作流) -4. **JNPF 已有能力**:用户、权限、流程、表单、可视化、报表、文件预览、xxl-job 等优先使用平台功能 - -> 注意项目数据库、表单、编码、类名、属性名 API地址 页面路径严格遵循 JNPF平台 + dacli 命名规则 -> 包名:`ssw.{app_code}.*`,字段名:`f_snake_case`,类名:PascalCase -> 功能表单不能实现的业务,尽量不用di,应该用jnpf平台提供的代码生成器(先创建功能表单,然后生成代码,在代码的基础上进行修改) -> 可通过代码生成,扩展代码来完成较复杂的功能,包 ssw-boot/ssw-{app_code} 页面 views/ssw/{app_code}/** -> 功能表单(CRUD、多项配置) 定制页面+后端开发(注册、申请、开发、集成、复制操作逻辑、多表操作) 流程(多角色处理) -> **注意** 除特别要求,设计完成一定要等待用户确认 - -### 阶段 2.5: schema 完整性检查 (v0.11+ cleanup 已简化) -1. v0.11+ webapi 镜像已自动保证 schema 完整性 -2. **`dacli form lint` / `dacli form validate` / `dacli form fixcolumndata` 命令已删** (v0.11+ Phase B, webapi 镜像 + buildFormData 自动保证) -3. **无需 `design-jnpf.html` + `scripts/03_forms.py` 旧设计格式** (v0.11+ 直接 `docs/{app_code}/design.html` 即可) -4. 设计完成后, 直接进阶段 3 审核 - -### 阶段3: 审核 -1. 创建多角色agent虚拟评审(系统架构、项目管理、UI、程序设计、质量、测试角色) -2. 针对源码、文档、数据库,结合 JNPF 开发模式评审 -3. 逐项检查功能覆盖 -4. 调用 `dacli-ts/references/jnpf-design-rules.md`,根据业务核查表单组件类型等(jnpfKey 控件映射 / relationForm 规范 / columnOptions ≤ 5 列硬限制) -5. **【重点检查】关联字段是否全部使用 relationForm,有无遗漏用 input 文本框代替的** -6. **【重点检查】relationForm 的 columnOptions 是否超过 5 列**,如超过需精简到关键列 -7. 判断各功能,使用功能表单是否满足业务场景,还是需要扩展开发 -8. 同一功能多个环节应该是同一个功能表单或扩展页面来实现,而不是多个表单 -9. **【重点检查】是否用了 /ssw-code-gen 代码生成,禁止 AI 自己编造后端代码!** -10. 评审结果补充完善到 design.html testcase.html - -### 阶段4: 执行 (v0.9 改写: 主代理顺序执行, 已删除 dispatch 模式) -1. **【首先更新 plan.html】** - - 读 `plan.html` 找 "当前任务" 段 - - 主代理**顺序执行**每个 form 的 `dm create → form create → menu create` (v0.11+ 推荐 --ai-json 路径) - ```bash - # 切到目标 app - dacli app switch --appCode={app_code} - # 主代理直接调 dacli, 不再派 sub-agent (v0.11+ cleanup 删除 design-jnpf-execute) - dacli dm create --table=X --dbLinkId= --fields='[...]' - dacli form create --ai-json='[...{tableTitle, tableName, isMain, fields}]' --dbLinkId= --autoRelease - dacli menu create --formId= ... - ``` - - **每 form 完成强制写 1 行**到 plan.html "已决事项" 段 -2. **【schema 防御】**: v0.11+ webapi 镜像自动保证 schema 完整性 (form lint/validate 命令已删). 浏览器层 4 铁律仍在阶段 5 自检. -3. **【功能表单无法满足】**: 必须用 JNPF 代码生成器 (触发 `/ssw-code-gen` 技能); 禁止主代理自己编后端 -4. **【模块注册】**: 代码生成后必须在 `jnpf-admin/pom.xml` 中添加 controller 依赖 (由 `/ssw-code-gen` 技能处理) -5. **【失败处理】**: - - form create/menu create FAIL → 查 `dacli log exception` + `dacli tool logs --level=error` - - enCode 重复 (BS-49) → 改名加 `_v2` 或 `dacli form delete` 重建 - - 主表不存在 (BS-50) → 走低级模式 `dacli menu create --type=3 --urlAddress=model/{enCode}` -6. **【关键约束】**: 主代理直接调 dacli 命令, 不派 sub-agent (v0.11+ cleanup 删除 design-jnpf-execute + dispatch 模式) -7. **【plan.html 是上下文恢复唯一信源】**: 每 form 完成后主代理强制写 1 行 - -### 阶段5: 测试 (v0.11f+ 三层验证 Ladder: **TC-A → TC-C → TC-B 逐层 CRUD 过**) - -> ⚠️ **核心铁律(2026-06-27 拍板)**: **逐层 CRUD 过,不通过不要进入下一层验证**。 -> **源码渲染验证已固化为 `dacli test render`**(避免每次读 web 源码重写,2026-06-27)。 - -0. 用 `dacli doc get --file=docs/{app_code}/testcase.html` 或 `dacli doc list --dir=docs/{app_code}` 快速定位待测项 - -1. **TC-A (API 层, ~5s) — 必跑第一层** - ```bash - dacli test run --formId= # POST/GET/PUT/DELETE 全流程 - dacli form info # 读完整 schema (v0.11+ 替代 form check, webapi 镜像自动保证完整性) - ``` - - **期望**: 5/5 CRUD PASS, 真实数据 ≥ 3 条 - - **不通过** → 修业务代码(form schema / dm 字段 / token / dbLinkId)→ 重跑 TC-A - - **禁止**跳过 TC-A 直接跑 TC-C 或 TC-B - -2. **TC-C (源码渲染层, ~2s) ★ — TC-A 全 PASS 才进入** - ```bash - dacli test render --module=dict --typeId= --id= # 字典模块 - dacli test render --module=form --formId= # form 模块 - ``` - - **算法** (已固化到 `dacli/src/commands/test/render.ts`, 430 行): - - `@vue/compiler-sfc` 解析 web 端 .vue 文件 - - 提取 `BasicColumn[].dataIndex` (列表渲染) + `useForm({schemas:[{field}]}).field` (表单渲染) - - 调 JNPF API 拿当前数据 → 字段对比 (渲染字段 ⊆ API 字段) - - **期望**: 退出码 0, vue 字段 ⊆ API 字段 (无 missing) - - **不通过** → 修 form schema (formData/columnData 字段缺失) → 重跑 TC-C → 重跑 TC-A - - **禁止**跳过 TC-C 直接跑 TC-B - -3. **TC-B (浏览器层, ~30s+, 仅必要时) — TC-A + TC-C 全 PASS 后才进入** - - 浏览器 E2E 才能查 vmodel bind bug (如 tdd10 浏览器只 bind 2 字段 bug, TC-C 查不出) - - 推荐用 `ssw-e2e-test` 技能的 v17 标准库(`clickMenu` / `fillByLabel` / `saveModal` 等)跑端到端 - - `playwright -s=dacli open ... && playwright -s=dacli eval ...` 是底层 CLI - - **仅 JNPF 平台有效** - - 适用场景: 涉及 vmodel 绑定的复杂控件(relationForm 弹窗 / 树形 / 看板)/ 自定义 JS 增强 / 异步加载 / DI 动态渲染 - -4. **测试框架**: - - **API 集成测试 (TC-A)**: `dacli test run` 替代散落 curl + jq 脚本 - - **源码渲染验证 (TC-C)**: `dacli test render` (v0.11f+ 新增, 2026-06-27) - - **Schema 自检**: ~~`dacli test check`~~ (v0.11+ 已删) + `dacli form info ` 读 schema - - **E2E 测试 (TC-B, 可选)**: 见 `ssw-e2e-test` 技能 `🎯 v17 JNPF 浏览器验证标准库` 段 - -5. 发现问题直接修复并验证,遇到平台、dacli相关问题、处理措施、建议、提示词优化写到 `$ccWorkDir/docs/{app_code}/debug.html` - -#### 阶段 5.0.1: 三层验证执行模板(2026-06-27 拍板) - -```bash -# 必跑顺序: TC-A → TC-C → TC-B - -# === 第一层: TC-A (API) === -dacli test run --formId= -# 不通过 → 修业务 → 重跑, 不进入下一层 - -# === 第二层: TC-C (源码渲染) ★ === -dacli test render --module=form --formId= -# 不通过 → 修 form schema → 重跑 TC-C → 重跑 TC-A → 再进 TC-B - -# === 第三层: TC-B (浏览器, 仅必要时) === -playwright -s=dacli open "http://nginx/jnpf_app_{app}/" -# ... 跑 v17 标准库 ... -# 不通过 → 修 vmodel / 控件配置 → 重跑 TC-B -``` - -#### 阶段 5.0.2: 何时可以跳过 TC-B(省 30s+ 截图 token) - -| 场景 | 是否需要 TC-B | -|---|---| -| TC-A + TC-C 全 PASS,业务简单(CRUD/单表)| **否**(省时间省 token)| -| TC-A + TC-C 全 PASS,用户报告"按钮缺失/截图白屏" | **是**(排查 JS bug)| -| 涉及 vmodel 复杂控件(relationForm 弹窗 / 树 / 看板)| **是** | -| 自定义 JS 增强 / 异步加载 | **是** | -| DI / 大屏 / 门户(render 不能覆盖动态渲染)| **是** | - -> 📌 **省时间省 token**: 90% 渲染 bug 在 TC-C 已暴露(字段缺失/不对),不必每次跑浏览器。 -> 📌 **CLAUDE.md 顶部强制**: 浏览器截图贵,仅在数据层跑通后用。**TC-A → TC-C → TC-B 严格逐层**。 - -#### 阶段 5.0: 浏览器层硬约束 (2026-06-21 tds2 复盘新增, 4 条铁律) - -> ⚠️ **根因**: tds2 上一轮 e2e 报告 28/28 TC 100% PASS, summary.html 写"阶段5完成", 但用户实测发现"几乎所有功能没有新增按钮/设置功能区是空白". 复盘发现 4 类测试方法系统性漏洞, 全部让"假 PASS"混进报告. **以下 4 条铁律不可破**. - -1. **铁律 1: 按钮存在性 (列表页必含"新增"按钮)** - - E2E 浏览器层每个 form 的 TC-{name}-B1 必查: 列表页**有"新增"按钮** (button:has-text("新增") / icon-ym-generator-add) - - **缺按钮 = FAIL** (硬关卡, 不是 skip, 不是 PASS) - - 视图模式 (webType=4) 例外, msg="view-only (no add)" 接受 - - 验证: `dacli form info {id}` 看 `columnData.btnsList` 非空且含 "新增" 按钮配置 - -2. **铁律 2: skip modal ≠ PASS (找不到"新增"按钮必须 FAIL)** - - 反模式 (tds2 e2e_browser.py:271): `status = "FAIL" if is_404 else "PASS"` —— 把"无新增按钮"当 skip 反算 PASS - - **正确逻辑**: `has_add` False 且 webType≠4 → status="FAIL" msg="缺新增按钮" - - 凡是测试代码里出现 "skip" / "fallback" / "if not found" 仍然 PASS 的逻辑, **必视为 bug 修复** - -3. **铁律 3: create failed ≠ PASS (create 失败必须 FAIL, 不能用 list OK 兜底)** - - 反模式 (tds2 e2e_browser.py:497-500): create 返 "System abnormality" → fallback "list OK" → PASS - - **正确逻辑**: POST create HTTP 200 + body.code==200 才算 PASS, 任何 4xx/5xx/msg 含 "abnormal" / "Field cannot be empty" 都 FAIL - - E2E 报告里出现 "create attempted: ..." 字样, 一律视为 FAIL 报告造假 - -4. **铁律 4: 截图 md5 去重 (3 张截图 MD5 不能全相同)** - - 每个 TC 必截 3 张: list / add-modal / data - - 3 张 MD5 不能完全相同 (反模式: 连拍同一页面 3 次当 3 张) - - e2e 报告生成后必跑去重断言: - ```bash - python3 -c "import hashlib,glob; m={f:hashlib.md5(open(f,'rb').read()).hexdigest() for f in glob.glob('screenshots/TC-*-*-*.png')}; - from collections import Counter; dup=[k for k,v in Counter(m.values()).items() if v>1]; - assert not dup, f'重复截图 MD5: {dup}'" - ``` - - 断言失败 → 报告作废, 强制重跑 - - **真做交互**: shot 2 必先 `page.wait_for_selector('.ant-modal', timeout=5000)` 等弹窗出现再拍 - -#### 阶段 5.0 自检命令 (写完 e2e_report.md 后必跑) - -```bash -# 1. 按钮存在性抽查: 必查 1-2 个 form 的 btnsList -dacli form info {formId} | python3 -c " -import json,sys; d=json.load(sys.stdin); cd=json.loads(d['columnData']) -btns=cd.get('btnsList',[]); rows=cd.get('rowBtnsList',[]) -print('btnsList:', [b.get('label') for b in btns]) -print('rowBtnsList:', [b.get('label') for b in rows]) -assert any('新增' in b.get('label','') for b in btns), 'FAIL: 缺新增按钮' -assert any('编辑' in b.get('label','') for b in rows), 'FAIL: 缺编辑按钮' -print('按钮存在性 PASS') -" - -# 2. 截图去重断言 (见铁律 4) -python3 -c "import hashlib,glob; from collections import Counter; m={f:hashlib.md5(open(f,'rb').read()).hexdigest() for f in glob.glob('docs/{app_code}/screenshots/TC-*-*-*.png')}; dup=[k for k,v in Counter(m.values()).items() if v>1]; assert not dup, f'截图去重 FAIL: {dup}'; print('截图去重 PASS,', len(m), '张')" -``` - -### 阶段6: 总结 -输出 `$ccWorkDir/docs/{app_code}/summary.html`(**HTML格式**): -- 遇到的问题及处理措施 -- 设计方案修改建议 -- 测试用例修改建议 -- claude 技能、命令、脚本提示体系修改建议 -- dacli / JNPF 平台修改建议 - -#### 阶段 6.0: summary.html 自检硬关卡 (2026-06-21 tds2 复盘新增) - -> ⚠️ **根因**: tds2 summary.html 写"10 forms + 6 workflows + 20 menus + 12 dict + 1 dashboard, 28/28 TC PASS"——但 7 个 form 的 `columnData.btnsList=[]`, 列表页"新增"按钮空白. 报告数字漂亮, 实际功能区空白. **写完 summary.html 前必跑自检, 不通过不写"功能区完整"**. - -**自检硬关卡 (3 条, 缺一不写总结)**: - -1. **按钮存在性全量自查**: 抽查 ≥30% form (向上取整, 至少 3 个) 的 `columnData.btnsList/rowBtnsList`, 必含 "新增"+"编辑" 按钮. 不含 → 修完再写总结. - ```bash - # 抽 1/3 form 检查按钮存在性 - N=$(dacli form list 2>/dev/null | wc -l) - CHECK_N=$(( (N + 2) / 3 )) - for id in $(dacli form list 2>/dev/null | awk 'NR>3 && $1 ~ /^[0-9]+$/ {print $1}' | head -$CHECK_N); do - dacli form info $id | python3 -c "import json,sys; d=json.load(sys.stdin); cd=json.loads(d['columnData']); btns=cd.get('btnsList',[]); rows=cd.get('rowBtnsList',[]); assert any('新增' in b.get('label','') for b in btns), f'FAIL {d[\"enCode\"]}: 缺新增按钮'; assert any('编辑' in b.get('label','') for b in rows), f'FAIL {d[\"enCode\"]}: 缺编辑按钮'; print(f' {d[\"enCode\"]} PASS')" - done - ``` - -2. **截图去重自检**: 跑铁律 4 的 md5 去重断言. 通过才能写"44 截图覆盖 3 类 TC" 之类数字. - -3. **TC PASS 数字可重跑验证**: summary 写的 `X TC PASS` 必须能跑出同样结果. 反模式: e2e 跑 1 次, summary 写 28 TC, 重跑 0 TC (因 skip 兜底). 防御: 写完数字后, 立即重跑 e2e 1 次, 数字必须 100% 一致. - -**summary.html 数字段必含按钮存在性自检结果段**: -```html -

X.1 按钮存在性自检 (2026-06-21 防御)

-
    -
  • 抽样: N/M form (≥30%)
  • -
  • 结果: 全部 PASS / X 个 FAIL (列名)
  • -
  • 截图去重: 16 unique / 44 total, dup 28 (FAIL) ← 这种情况不能写"截图覆盖完整"
  • -
-``` - -### 阶段7: 迭代 -根据总结文档、详细设计、测试用例文档,从阶段2开始迭代 - ---- - -## 关键约束 - -| 约束类型 | 规范 | -|---------|------| -| 包名 | `ssw.{app_code}.*` (不是 `com.ssw.{app_code}.*`) | -| 类名/属性名 | PascalCase | -| 字段名 | `f_snake_case` | -| 前端地址 | `http://127.0.0.1:3000/jnpf_app_{app_code}` | -| JNPF app form URL 模板 | `/jnpf_app_{appCode}/model/{formEnCode}` (menu.urlAddress = `model/{formEnCode}`) | -| 扩展代码 | 优先代码生成器,复杂逻辑在生成的后端代码上修改 | -| 数据库 | 使用配置的 `db_link_id`,不是 `"0"` | -| 配置统一 | `dacli app login --appCode=` 切换应用,token 在 `$ccWorkDir/.dacli-token/token.json` (注意: 实际是 .dacli-token, 不是 .dacli) | - ---- - -## ⚠️ UI组件库警告 - -**JNPF 平台使用 Ant Design Vue,禁止使用 Element Plus!** - -| 场景 | UI 库 | -|------|-------| -| JNPF 管理后台(平台页面) | **Ant Design Vue** | -| 前端定制页面(Vite /views/ssw/) | **Ant Design Vue**(AIS 系统) | - -混用 Element Plus 会导致样式冲突或组件不生效。 - -```vue - -提交 - - - -提交 - -``` - ---- - -## 使用示例 - -``` -/ssw-h5dev-flow - -app_code: xx -app_name: xxxxx -source_path: /xx/xx/xx -``` - ---- - -## 相关命令 - -| 命令 | 说明 | -|------|------| -| dacli app init | 初始化应用环境 | -| dacli form create | 创建功能表单 | -| dacli form release | 发布表单 | -| dacli codegen | 代码生成 | -| dacli menu create | 创建菜单 | -| /ssw-onlinedev | 在线开发创建表单 | -| /ssw-code-gen | 代码生成与菜单挂载 | -| /ssw-test | E2E 测试 | -| /dacli-ts | JNPF 单命令入口(22 父命令 / 116 子命令)| -| /ssw-pack-init | boot模块编译打包 | -| (form-development / menu-configuration / workflow-development / dict-management / data-management / data-interface / data-screen / code-generator / platform-mechanism / troubleshooting / api-test / ai-debug-* 已收纳到 dacli-ts, 见 SKILL.md references/ 决策树) | -| /backend-dev | 后端业务类开发(技能) | -| `dacli doc` | HTML 文档缓存读取(降低 token 80%) | diff --git a/commands/ssw-test.md b/commands/ssw-test.md deleted file mode 100644 index 6ddf989..0000000 --- a/commands/ssw-test.md +++ /dev/null @@ -1,252 +0,0 @@ ---- -skill: ssw-e2e-test -description: JNPF E2E + API 测试(基于 playwright Node.js + curl + dacli) -triggerWords: [ssw-test, e2e, 表单测试, 功能测试, 测试表单, e2e测试, 浏览器测试, api测试] -autoTrigger: false ---- - -# SSW E2E + API Testing - -JNPF 测试工具集: -- **UI 自动化**:playwright Node.js 版 CLI 直接调(无 dacli 包装) -- **API 验证**:curl + jq + dacli 业务命令 - -> 📦 **2026-06-05 变更**:dacli 不再包装 curl / playwright(移除 `dacli test` / `dacli e2e`)。 -> -> 📦 **2026-06-15 变更**:从 `@playwright/cli` 迁移到 `playwright` Node.js 包,命令 `playwright-cli` → `playwright`(同一 `playwright-core` CLI program,session 模式 `playwright -s=X ...` 不变)。 - -## 双模式测试架构 - -| 场景 | 工具 | 说明 | -|------|------|------| -| 浏览器 UI 自动化 | `playwright -s=dacli ...` | Playwright Node.js 版 CLI,UI 操作测试 | -| API 验证 | `curl + jq` + `dacli <业务命令>` | 调 JNPF 后端接口 | - -## 🪜 三层验证 Ladder(2026-06-27 拍板,**逐层 CRUD 过,不通过不要进入下一层**) - -> ⚠️ **核心铁律**:**TC-A → TC-C → TC-B 顺序执行,前一层不 PASS 禁止进入下一层**。 -> **源码渲染验证已固化为 `dacli test render`,避免每次读源码重写**(2026-06-27)。 - -| 层 | 命令 | 速度 | 验证内容 | 不通过时 | -|---|---|---|---|---| -| **TC-A** (API 层) | `dacli test run --formId=` | ~5s | POST/GET/PUT/DELETE 5/5 CRUD | 修业务代码 + 重跑,**禁止**跳过到 TC-C | -| **TC-C** (源码渲染层) ★ | `dacli test render --module= [--typeId=Y] [--id=Z]` | ~2s | web 端 .vue 渲染字段 ⊆ API 字段(避免浏览器 SPA 404 风险) | 修 form schema + 重跑,**禁止**跳过到 TC-B | -| **TC-B** (浏览器层) | `playwright -s=dacli ...` 或 `dacli test generate` | ~30s+ | B 铁律 1-4(新增按钮 / 截图去重 / create POST 200 / vmodel bind) | 修 vmodel / 控件配置 + 重跑 | - -### 执行规则 - -```bash -# 1. TC-A: API 层 -dacli test run --formId= -# 期望: 5/5 CRUD PASS, 输出真实 id + 数据 -# 不通过 → 修业务代码 (dacli form update / dm 字段) → 重跑 TC-A - -# 2. TC-C: 源码渲染层 (★ 替代浏览器) -dacli test render --module=dict [--typeId=] [--id=] -dacli test render --module=form --formId= # 验证 form 渲染契约 -# 期望: 退出码 0, vue 字段 ⊆ API 字段 (无 missing) -# 不通过 → 修 form schema (formData/columnData 字段缺失) → 重跑 TC-C - -# 3. TC-B: 浏览器层 (仅必要时, TC-A + TC-C 全 PASS 后) -playwright -s=dacli open "http://nginx/jnpf_app_{app}/" -playwright -s=dacli click ".jnpf-menu-item:has-text('XXX')" -playwright -s=dacli eval "() => !!document.querySelector('button:has-text(\"新 增\")')" -# 期望: B 铁律 1-4 全 PASS -# 不通过 → 修 vmodel bind / 控件配置 → 重跑 TC-B -``` - -### 反模式(**必避免**) - -- ❌ **跳过 TC-A 直接跑 TC-B**:webapi 没通,浏览器层 100% 假 PASS -- ❌ **跳过 TC-C 直接跑 TC-B**:字段缺失 bug 在浏览器才能查,但 SPA 404 概率高,截图贵 -- ❌ **TC-A 失败但仍跑 TC-C**:API 不存在时对比 vue 字段无意义 -- ❌ **3 层混合跑**:批次中某个 form 跑 TC-A、另一个 form 跑 TC-C → 失去逐层验证意义 -- ❌ **重读 web 源码每次验证**:`dacli test render` 已固化 web 端 .vue 解析逻辑 (430 行 @vue/compiler-sfc) - -### 覆盖矩阵 (v0.11f+, 2026-06-27) - -| 模块 | TC-C 命令 | 覆盖页面 | -|---|---|---| -| dict | `dacli test render --module=dict --typeId=X --id=Y` | 类型列表 + 类型编辑 + 数据列表 + 数据编辑 | -| form | `dacli test render --module=form --formId=X` | formDesign/Form + ColumnDesign/Main + FormGenerator | -| menu | `dacli test render --module=menu` (设计阶段) | menu/index.vue 树形表格 | -| workflow | `dacli test render --module=workflow` (设计阶段) | flowDesign 节点渲染 | - -### 何时需要 TC-B - -| 场景 | 是否需要 TC-B | -|---|---| -| TC-A + TC-C 全 PASS, 业务简单 | 否(省 30s+ 截图 token)| -| TC-A + TC-C 全 PASS, 但用户报告"按钮缺失"等浏览器 JS bug | 是(仅排查 JS bug)| -| 涉及 vmodel 绑定的复杂控件(relationForm 弹窗 / 树形 / 看板)| 是 | -| 涉及自定义 JS 增强 / 异步加载 | 是 | -| 数据接口 (DI) / 大屏 (bigscreen) | 是(render 不能覆盖动态渲染)| - -> 📌 **省时间省 token**: 90% 渲染 bug 在 TC-C 已暴露(字段缺失/不对),不必每次跑浏览器。 -> 📌 **CLAUDE.md 顶部强制**: 浏览器截图贵,仅在数据层跑通后用。TC-A → TC-C → TC-B 严格逐层。 - -## 🎯 v17 JNPF 标准库(仅 JNPF 平台有效) - -> ⚠️ **平台专用**:以下库依赖 JNPF 6.2.0 稳定契约 (`.jnpf-menu-item` / `.vxe-body--row` / `/model/` 路由) 和 jnpf 后端 urlAddress 构造机制,**仅在测试 JNPF 平台上开发的应用时使用**,不要套到非 jnpf 项目。 - -详见 `.claude/skills/ssw-e2e-test/SKILL.md` `🎯 v17 JNPF 浏览器验证标准库` 段(双语言 API 速查 + 端到端示例 + 验证记录)。 - -**快速入口**: -- **TypeScript** (playwright test): `import { ... } from '../_helpers'` (来自 `dacli/tests/e2e/_helpers/`) -- **Python** (ad-hoc 脚本): `from lib import ...` (来自 `.claude/skills/ssw-e2e-test/scripts/lib/`) - -核心 API: `clickMenu` / `clickAdd` / `fillByLabel` / `selectByLabel` / `fillDateByLabel` / `fillTextareaByLabel` / `fillNumberByLabel` / `saveModal` / `closeModal` / `countRows` / `findRow` / `clickRowAction` / `waitTableReady` / `waitFormModalReady` / `waitRowCountChange` / `getErrors` - -## playwright 基本模式 - -**所有调用都用 `-s=dacli` 共享 session**: - -```bash -# 启动 -playwright -s=dacli open "http://nginx/jnpf_app_tds/login" - -# 登录 -playwright -s=dacli fill "#form_item_account" "admin" -playwright -s=dacli fill "#form_item_password" "123456" -playwright -s=dacli click "button:has-text('登 录')" - -# 菜单/点击/填写/截图 -playwright -s=dacli click ".jnpf-menu-item:has-text('用户管理')" -playwright -s=dacli fill "#f_name" "测试值" -playwright -s=dacli screenshot "/tmp/screen.png" - -# 执行 JS -playwright -s=dacli eval "() => document.title" - -# 控制台 -playwright -s=dacli console - -# 关闭 -playwright -s=dacli close -``` - -底层子命令:`open`, `goto`, `click`, `fill`, `select`, `eval`, `type`, `console`, `snapshot` - -## curl + jq API 测试 - -**前置**:dacli 登录获取 token - -```bash -# 登录 -dacli app login --account=admin --password=123456 --appCode=tds - -# 取 token -TOKEN=$(jq -r .token $ccWorkDir/.dacli-token/token.json) -APP_CODE=$(jq -r .appCode $ccWorkDir/.dacli-token/token.json) -BASE="http://127.0.0.1:30000" - -# GET 列表 -curl -s "$BASE/api/visualdev/Base/list" -H "App-Code: $APP_CODE" -H "Authorization: $TOKEN" | jq . - -# POST 创建 -curl -s -X POST "$BASE/api/visualdev/Base" \ - -H "App-Code: $APP_CODE" -H "Authorization: $TOKEN" \ - -H "Content-Type: application/json" \ - -d '{"fullName":"测试","enCode":"test","table":"test"}' | jq . - -# 取 ID -FORM_ID=$(curl -s "$BASE/api/visualdev/Base/list?keyword=test" \ - -H "App-Code: $APP_CODE" -H "Authorization: $TOKEN" | jq -r '.data.list[0].id') - -# 详情 -curl -s "$BASE/api/visualdev/Base/$FORM_ID" \ - -H "App-Code: $APP_CODE" -H "Authorization: $TOKEN" | jq . -``` - -## 用 dacli 业务命令(推荐) - -业务命令 = 一行 curl(自动拼好 headers/token/appCode): - -| 业务命令 | 等价 curl | -|---------|----------| -| `dacli form list` | `curl /api/visualdev/Base/list` | -| `dacli form info ` (v0.7+ 位置参数) | `curl /api/visualdev/Base/{id}` | -| `dacli form create --fullName=...` (v0.7+: --name 改 --fullName) | `curl POST /api/visualdev/Base` | -| `dacli menu list` | `curl /api/system/Menu/ModuleBySystem` | -| `dacli user list` | `curl /api/permission/User/list` | -| `dacli tool logs --level=error` | `curl /api/ssw/system/logs` | - -## 常用 JS 模式(playwright eval) - -### 点击菜单 -```javascript -() => { - const items = document.querySelectorAll('.jnpf-menu-item'); - for (const item of items) { - if (item.innerText.includes('目标菜单')) { - item.click(); - return 'clicked: ' + item.innerText; - } - } - return 'not found'; -} -``` - -### 检测 Modal -```javascript -() => !!document.querySelector('.ant-modal') -``` - -### 获取表单字段 -```javascript -() => { - const fields = []; - document.querySelectorAll('.ant-modal .ant-form-item').forEach(item => { - const label = item.querySelector('.ant-form-item-label label')?.innerText; - const id = item.querySelector('input,select')?.getAttribute('id'); - fields.push({ label, id }); - }); - return fields; -} -``` - -### 查找 vxe-table 行 -```javascript -() => { - const rows = document.querySelectorAll('.vxe-body--row'); - for (const row of rows) { - if (row.innerText.includes('目标文本')) return 'found'; - } - return 'not found'; -} -``` - -## 组合使用示例 - -```bash -# 1. 登录(API) -dacli app login --account=admin --password=123456 --appCode=tds - -# 2. API 验证表单列表(curl + jq) -curl -s "http://127.0.0.1:30000/api/visualdev/Base/list" \ - -H "App-Code: tds" -H "Authorization: $TOKEN" | jq '.data.list | length' - -# 3. UI 测试新增(playwright) -playwright -s=dacli open "http://nginx/jnpf_app_tds/" -playwright -s=dacli eval "() => { - document.querySelectorAll('.jnpf-menu-item').forEach(item => { - if (item.innerText.includes('数据资产')) { item.click(); return; } - }); -}" -playwright -s=dacli click "button:has-text('新 增')" -# ... 填写表单,保存 ... - -# 4. API 验证数据 -curl -s "http://127.0.0.1:30000/api/visualdev/Base/$FORM_ID" \ - -H "App-Code: tds" -H "Authorization: $TOKEN" | jq '.data | {id, fullName, state}' -``` - -## 常见问题 - -| 问题 | 解决 | -|------|------| -| 菜单点击无效 | `playwright -s=dacli eval` + JS `element.click()` | -| 下拉选项无法点击 | 用 `playwright -s=dacli eval` 取坐标后 `mouse click` | -| 表格无数据 | curl + jq 验证 API 返回 | -| 登录失败 | `dacli app login` 先确保登录成功 | -| 密码加密 | JNPF 前端用 MD5+AES 加密,`dacli app login` 自动处理 | diff --git a/settings.local.json b/settings.local.json index 2141576..8a4c487 100644 --- a/settings.local.json +++ b/settings.local.json @@ -91,7 +91,10 @@ "Bash(cd /home/ubuntu/ccWorkDir/dacli && npx tsx src/cli.ts menu list)", "Bash(cd /home/ubuntu/ccWorkDir/dacli && npx tsx src/cli.ts workflow list)", "Bash(cd /home/ubuntu/ccWorkDir/dacli && npx tsx src/cli.ts app login --account=admin --password=123456 --appCode=tdd10)", - "Bash(cd /home/ubuntu/ccWorkDir/dacli && npx tsx src/cli.ts form list)" + "Bash(cd /home/ubuntu/ccWorkDir/dacli && npx tsx src/cli.ts form list)", + "Bash(mv /home/ubuntu/ccWorkDir/.claude/skills/ssw-hdev-flow/scripts/check_html_assets.sh /home/ubuntu/ccWorkDir/.claude/skills/ssw-h5dev-flow/scripts/check_html_assets.sh)", + "Bash(rm -rf /home/ubuntu/ccWorkDir/.claude/skills/ssw-hdev-flow)", + "Bash(chmod +x /home/ubuntu/ccWorkDir/.claude/skills/ssw-h5dev-flow/scripts/check_html_assets.sh)" ] } }