diff --git a/.claude/skills/dacli-ts/SKILL.md b/.claude/skills/dacli-ts/SKILL.md index e73b317..04a01fc 100644 --- a/.claude/skills/dacli-ts/SKILL.md +++ b/.claude/skills/dacli-ts/SKILL.md @@ -315,6 +315,7 @@ dacli user auth-list --userId= --objectId= --objectType=role | `dbLinkId='0'` 错 | 先 `dacli app status` 看真实 dbLinkId | | `tables[].fields[]` 缺字段 | 用 `type=4` 视图绕开 | | `category='0'` 错 | `dacli form list` 看已有 form 的 category | +| **不传 --tables** | 必传 `--tables='[{table,tableName,fields}]'`,参考 BS-48 | | 服务器限流 | `sleep 30` 重试 | ### 决策 5: 端到端业务实现路径 @@ -346,6 +347,28 @@ form create → 失败 → 改字段 → form create → 失败 → 改 type → 4. 命令注释里写真值表 (1=登录 3=操作 4=异常 5=请求 之类), 给下个 AI 看 ``` +### 决策 6: 字典 enCode/fullName 冲突怎么避? (BS-47) + +**反模式** (AI 直接 `dacli dict typeCreate` 常踩): +```bash +dacli dict typeCreate --enCode=user_type --fullName=用户类型 +# ✗ 若其他 app 已建过 "用户类型" 或 enCode, 报 "The name cannot be repeated" +``` + +**正解**: +```bash +# 1. 先查 dataList 拿已存在的字典 +dacli dict dataList | grep -E "user_type|用户类型" + +# 2. 二选一: +# a) 复用: form fields 里直接引用其他 app 的 enCode +# → 全平台共享 (主库 system_DictionaryType, 跨 app 唯一) +# b) 加前缀: --enCode=_user_type --fullName=用户类型 +# → 注意: fullName 也需全局唯一, 不是只有 enCode +``` + +**为什么**: 字典存在主库 system_DictionaryType, 不分 app, 也不分 enCode vs fullName (都是 unique 约束). 抛光轮踩过 7+ 次 "The name cannot be repeated" 报错. + --- ## 4. ⭐ 0 差错验证 (Playwright + baseline) @@ -530,7 +553,7 @@ npx playwright test tests/e2e/baseline/workSystem/regression.spec.ts # 52/52 --- -**生成时间**: 2026-06-12 +**生成时间**: 2026-06-12 (v0.9 校准 2026-06-21, 加 BS-47/48/49/50/51 决策) **作者**: Claude (M3) + 用户 **配套文档**: [doc/architecture.md](../../doc/architecture.md) **核心目标**: **74 张官方示例 API 0 错 + 浏览器 0 视觉差** diff --git a/.claude/skills/dacli-ts/references/anti-patterns.md b/.claude/skills/dacli-ts/references/anti-patterns.md index d54398e..db6d263 100644 --- a/.claude/skills/dacli-ts/references/anti-patterns.md +++ b/.claude/skills/dacli-ts/references/anti-patterns.md @@ -278,3 +278,136 @@ dacli menu create --fullName="员工请假申请" --formId=835168490678657989 ``` **为什么**: 只有 Actions/Module 真路径才会把 menu.moduleId 绑到 formId, 浏览器 vue-router 动态注册后 `/model/` 才能加载 form 数据. 低级 /system/Menu 缺这一环. 见 [troubleshooting.md 错误 23](troubleshooting.md#错误-23-menu-create-actionsmodule-报-system-abnormality-盲点-23-根因). + +--- + +## 10. ❌ dict typeCreate 不查就建 (BS-47, 跨 app 唯一) + +**反模式**: +```bash +dacli dict typeCreate --enCode=user_type --fullName=用户类型 +# ✗ 全平台唯一: 若其他 app 已建过 (或 workSystem/developSystem 默认字典), +# 报 "The name cannot be repeated" (注意: 不是 enCode 冲突, 是 fullName 也冲突) +``` + +**正确**: +```bash +# 1. 先列已建字典 (主库 system_DictionaryType, 跨 app) +dacli dict dataList | head -50 +# 或: apis search "DictionaryType" 看 schema 字段 + +# 2. 二选一: +# a) 复用: 直接用已存在的 enCode (e.g. user_type), form field 引用即可 +# b) 加前缀: --enCode=_ --fullName= +# e.g. tds1_user_type / tds1用户类型 +``` + +**为什么**: 字典是平台级共享, 不分 app. 多次抛光轮已踩 7+ 次 "The name cannot be repeated". + +--- + +## 11. ❌ form create type=1/2 不传 --tables (BS-48) + +**反模式** (v0.7.4 部分修复后仍存): +```bash +dacli form create --enCode=my_form --type=1 --webType=2 \ + --dbLinkId=... --fields='[...{__vModel__,__config__}]' --autoRelease +# ↑ dacli 警告 "v0.7.4 webType=2 但 tables[0] 无用户字段, 仍可能报"列表字段不允许为空"" +# ↑ 实际跑 → "Database exception, please contact the administrator for handling" +``` + +**正确**: +```bash +# 必传 --tables, 含完整字段 schema (含主键/系统列可省, dacli 自动加) +dacli form create --enCode=my_form --type=1 --webType=2 \ + --dbLinkId=... \ + --fields='[...fields...]' \ + --tables='[{"table":"my_table","tableName":"XX","fields":[{"field":"f_xxx","fieldName":"...","dataType":"varchar","dataLength":"50","allowNull":0}]}]' \ + --autoRelease +``` + +**为什么**: dacli 自动从 --fields 推导的 tables 简化版, 缺 use*Permission 等关键字段, 后端校验失败. 必传 --tables 完整 schema. + +--- + +## 12. ❌ form create 失败后 enCode 重复 (BS-49) + +**反模式**: +```bash +dacli form create --enCode=tds_myform --type=1 --webType=2 --fields=... +# ↑ 失败 "Database exception" / "Encoding cannot be repeated" +# 重试: dacli form create --enCode=tds_myform ... +# ↑ 又失败 "Encoding cannot be repeated" — form 不在 form list 中, 但 enCode 已占位 +``` + +**正确**: +```bash +# 1. 失败后查 form list + 残留 enCode (grep 表) +dacli form list # 已发布的能看到 +# 后端 base_visual_dev 表的 F_EnCode 列是占位源, list 不一定返回 + +# 2. 三选一: +# a) 改名: --enCode=tds_myform_v2 +# b) form delete 失败残留: dacli form delete --yes +# c) form clone 重建 (从 workSystem/developSystem 克隆 schema 完整版) +``` + +**为什么**: dacli form create 失败时, enCode 可能在表里已占位但 form 详情不可见. 报错无明确指示. 命名带版本后缀 (_v2/_v3) 是最稳的兜底. + +--- + +## 13. ❌ menu create --formId + type=3 强制 Actions/Module 失败 (BS-50) + +**反模式**: +```bash +dacli menu create --fullName="我的表单" --enCode=my_menu \ + --type=3 --formId=837990759062831173 --parentId=837992531181436997 +# ↑ 传 --formId 强制走 Actions/Module 真路径 +# ↑ form schema 缺主表信息 → "主表不存在" 报错 +``` + +**正确**: +```bash +# 不传 --formId, 走低级 /system/Menu 路径, 手工填 urlAddress + D-9 自动拉 form 拼 propertyJson +dacli menu create --fullName="我的表单" --enCode=my_menu_v2 \ + --type=3 --urlAddress=model/ --parentId= +# 或用 form clone 修复 columnList schema 缺字段后, 再 --formId Actions/Module +``` + +**为什么**: Actions/Module 高级路径对 form schema 完整性要求高 (需主表信息). 当 form 是 dacli 简化创建的, 用低级模式 + 手工 urlAddress 更稳. 见 SKILL.md 决策 4. + +--- + +## 14. ❌ 浏览器层 list 白屏 = form 渲染失败 (BS-51) + +**反模式**: +```bash +dacli form create --enCode=my_form --type=1 --webType=2 --fields=... --tables=... --autoRelease +dacli menu create --formId= ... +# form validate PASS, 浏览器 list 区仍白屏 +# ↑ columnList 是 dacli v0.7.4 自动生成的简化版, 缺 visibility/noShow/tipLabel/ +# tableFixed/renderKey/regList/tagIcon/defaultCurrent/tag/layout 等字段 +# ↑ 前端 vue 组件按 workSystem 完整 schema 渲染, 缺字段 → 白屏 +``` + +**正确** (二选一): + +**A. 修复 form schema**: +```bash +# 1. 从 workSystem/developSystem 克隆完整 form +dacli form clone --newEnCode=my_form_v2 --newDbLinkId=... --release +# ↑ clone 的 form columnList 含 25+ 完整字段, 浏览器 0 视觉差 + +# 2. 跨应用 clone 注意 tableName 替换 (原 form 引用 workSystem 物理表 mt..., +# 需手动改 columnList 的 tableName + 改主键/外键引用) +``` + +**B. 用 no-spa-page 兜底** (不依赖 JNPF form 渲染): +```bash +# 1. 创建静态 HTML 页 + Vue CDN +# web/apps/jnpf-web-apps-main/public/ssw//dashboard.html +# 2. nginx 直代理, 浏览器访问 http://nginx/ssw//dashboard.html +# 3. 100% 控制 label 可见, 旁路 form 渲染问题 +``` + +**为什么**: 浏览器层 100% PASS 是 ssw-h5dev-flow 硬要求. list 白屏是已知遗留, 但能用双路径 (clone 完整 schema 或 no-spa 静态页) 兜底. 见 [no-spa-page 技能](../../no-spa-page/SKILL.md). diff --git a/CLAUDE.md b/CLAUDE.md index cd9c82c..9972ca8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -125,3 +125,15 @@ output (JSON / table / --ai-help markdown) - git `dacli/` **独立 git 仓库** 完整规则见 `$ccWorkDir/.claude/CLAUDE.md`。 + +## 已知盲点与兜底 (v0.9+, AI 必看) + +| # | 盲点 | 触发 | 兜底 | +|---|------|------|------| +| 47 | dict fullName/enCode 全平台唯一 | `dacli dict typeCreate` 报 "The name cannot be repeated" | 先 `dacli dict dataList` 查重,复用或加 `_` 前缀 | +| 48 | form create 缺 --tables | `dacli form create --type=1/2` 不传 --tables → "Database exception" | 必传 `--tables='[{table,tableName,fields}]'` | +| 49 | enCode 失败残留 | form create 失败后再用同 enCode → "Encoding cannot be repeated" | 三选一:加 `_v2` / `form delete` / `form clone` 重建 | +| 50 | menu --formId + Actions/Module 失败 | form schema 缺主表信息 → "主表不存在" | 不传 --formId,走低级模式 `--type=3 --urlAddress=model/{enCode}` | +| 51 | 浏览器层 list 白屏 | dacli 简化 columnList 缺完整 schema 字段 | `dacli form clone ` 拿完整 schema,或用 no-spa-page 静态页兜底 | + +详细反模式 + 完整代码示例见 `.claude/skills/dacli-ts/references/anti-patterns.md`。