auto(09213057c521): session end @ 2026-06-25T16:19:12 (+6f)

This commit is contained in:
ssw committed 2026-06-25 16:19:12 +08:00
1 parent 8374ca30ef
commit 43686d322d
6 files changed
+135 -140

No files matched your search

+1 -1
View File
@@ -372,7 +372,7 @@ jnpf-admin **仅支持 Java 8**,后端代码禁止使用 Java 11+ 特性(如
$ccWorkDir/
├── .claude/
│ ├── CLAUDE.md # 本文件
│ └── skills/ # 技能定义
│ └── skills/ # 技能定义 (含 dacli-ts 教 AI 何时用哪个命令)
├── boot/ # 后端 Spring Boot
│ ├── jnpf-admin/ # 主模块
│ └── ssw-{app_code}/ # 业务模块
+7 -13
View File
@@ -23,24 +23,18 @@ dacli doc list --dir=docs/{app_code}
### 步骤 2:按需读取节内容(**核心**)
```bash
# ⚠️ v0.8.1 校准: `dacli doc get/scan/refresh/clear` TS 版**未实现** (v0.8.1 doc 只有 list 子)
# 真替代: 用 Read 工具直接读 HTML 文件 (Claude 内置), 或
# ✅ 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; ..." 自抽纯文本
# 备: `dacli doc list --dir=docs/{app_code}` 拿索引 + 路径, 知道哪些文件存在即可
# 读取 design.html 的架构设计节 — TS 版无 `dacli doc get/section`
# 真替代: Read 工具读 design.html, 自行 grep "## 架构" 段
# python3 抽纯文本:
# python3 -c "import re,sys; html=open('docs/{app_code}/design.html').read(); text=re.sub('<[^>]+>',' ',html); text=re.sub('\s+',' ',text); print(text)"
# 如果只需要看 plan.html 第 10-60 行 — TS 版无 `dacli doc get --from/--lines`
# 真替代: Read 工具读 + 手动跳行, 或 sed/awk 处理
```
### 步骤 3(可选):刷新缓存
```bash
# 文档更新后强制刷新 — TS 版无 `dacli doc refresh` (v0.8.1 doc 只有 list)
# 真替代: 删除 `.dacli-cache.db` 让 dacli 重扫 (目前 dacli doc list 每次实扫, 无 cache, 不用刷)
# 文档更新后强制刷新 (v0.11+ 已实现)
# dacli doc 命令内置 mtime 感知 SQLite 缓存 7 天 TTL, 默认无需刷新
# 备: 用 Read 工具直接读新文件即可
```
@@ -1,4 +1,6 @@
# 8 盲点必查 (与 _blindspots.ts 共享 ID, v2026-06-24 tdd8 教训扩展)
# 8 盲点必查 (与 `_blindspot_guards.ts` 共享 ID, v2026-06-25 webapi 化更新)
> **⚠️ v0.11+ 更新 (2026-06-25)**: 旧版 `_blindspots.ts` 文件已删除 (v0.11+ 整合到 `src/commands/_blindspot_guards.ts` 22 条 guard). 盲点 ID (BS-23/31/32/15/V2/38/39/60/60b) 保留, 但 BS-51/52/54 已通过 webapi 镜像消除 (无需手动修).
**适用范围**: 不只 dispatch 阶段 (阶段 4) 子代理实施 form 时查; **plan/design 阶段写 spec/plan/design-jnpf.html 时也必查**——避免 17+ 偏差在源头就消除。
@@ -19,7 +19,7 @@
3. `dacli dm create --table={table} --tableName={fullName} --dbLinkId={dbLinkId} --fields='[...]'`
4. `dacli form create --enCode={enCode} --fullName={fullName} --table={table} --webType=2 --dbLinkId={dbLinkId} --autoTable --autoRelease --fields='[...]'`
5. `dacli form validate <id>` → FAIL 时调 `dacli form fixcolumndata <id>`, 重跑直到 PASS
6. 跑 **8 盲点**必查 (从 `_blindspots.ts` + `references/anti-blindspots.md`):
6. 跑 **8 盲点**必查 (从 `_blindspot_guards.ts` + `references/anti-blindspots.md`, v0.11+ webapi 化后 BS-51/52/54 自动 PASS):
- BS-23 use*Permission 4 字段齐
- BS-31 label 非空
- BS-32 decimal→inputNumber
+20 -34
View File
@@ -306,7 +306,7 @@ dacli apis info "POST /api/visualdev/OnlineDev/{modelId}"
```
> 💡 **AI 速算**:子表名 = `ct{主表ID+1}`,子表 vModel = `tableField{table容器的formId}`。
> 用 `dacli form msrelation <id>` 一键查主子表名+ER关系。
> 用 `dacli form info <id> --expand-subtable` 一键查主子表名+ER关系。
### 模板 3:关联表单字段(relationForm)
@@ -368,39 +368,26 @@ dacli form create --fullName="客户管理" --enCode=customerManage \
---
## 🔍 dacli form msrelation <id>(2026-06-08 新增)
## 🔍 dacli form info <id> --expand-subtable (v0.7+ 替代 form msrelation)
> 📦 **新增子命令**:`dacli form msrelation <id>` — 一键查主子表 ER 关系
> **dev-rs.md §11.2 已实现**
> ⚠️ **v0.11+ 更新 (2026-06-25)**: 旧版 `dacli form msrelation` 命令**不存在** (`src/commands/form/` 下无 `msrelation.ts`). 已合并到 `dacli form info --expand-subtable` 真实可达命令.
**输出**(主子表 + 字段 + 校验 + 外键):
**输出** (主子表 + 字段 + 校验 + 外键, JSON 格式):
```
Form 469047177461688709 (人才管理)
WebType: 2 | State: 1 | EnCode: rencaiguanli
主表 mt294012196562705413 (typeId=1, 物理字段 24)
中文名: 主表 | 主键: f_id
业务字段: 12 (姓名/性别/年纪/...)
系统字段 (自动): f_id, f_tenant_id, f_flow_id, ...
子表 (共 1 个):
1. ct294012196562705414 (typeId=0, 物理字段 11)
外键: ct.f_foreignId → mt.f_id
表单 vModel: tableField117
业务字段: 5 (开始日期/结束日期/...)
系统字段 (自动): f_id, f_foreignId, f_tenant_id
校验规则:
必填: 6 个主表字段
唯一: 0 个字段
业务主键: 未启用
```bash
dacli form info <id> --expand-subtable --json | jq
# 返回:
# {
# "mainTable": {"table": "mt...", "tableName": "主表", "fields": [...24]},
# "subTables": [{"table": "ct...", "foreignKey": "f_foreignId", ...}],
# "validation": {"required": 6, "unique": 0, "businessKey": false}
# }
```
**使用场景**:
- 拿到表单 ID 想看主子表结构(不用 parse 整 JSON)
- AI 自动化:先 `msrelation` 看结构,再 `dm query` 查数据
- 子表命名 = `ct{主表ID+1}`(见 dev-rs.md §2.1)
**使用场景**:
- 拿到表单 ID 想看主子表结构 (不用 parse 整 JSON)
- AI 自动化: 先 `info --expand-subtable` 看结构, 再 `dm query` 查数据
- 子表命名 = `ct{主表ID+1}` (见 dev-rs.md §2.1)
---
@@ -559,7 +546,7 @@ resp = urllib.request.urlopen(req, timeout=30)
tdd 应用 `/api/oauth/Login` 返回 404(与 polish-changes §7.5 同因)。
**不是 dacli 责任**。临时方案:
- 改用 workSystem 浏览器验证
- 或:用 API + structure 验证(`dacli form msrelation` / `--expand-subtable` / `dm query`)
- 或:用 API + structure 验证(`dacli form info --expand-subtable` / `dm query`)
---
@@ -585,7 +572,7 @@ tdd 应用 `/api/oauth/Login` 返回 404(与 polish-changes §7.5 同因)。
> **核心思路**:dacli **不内置模板**,也不"一键应用"整段 formData。**高频能力(视图/工作流/数据接口字段)已直接做进 `dacli form create`** 的参数(见上面"高频场景"),一行命令解决。**剩下的长尾场景**(联动/JS增强/列表样式/套打/i18n 等)AI 用下面的速查表找官方示例 ID → `dacli form info <id>` 读结构 → 仿造。
>
> 备份/迁移用 `dacli form export/import`,表单结构修复用 `dacli form fix`(内置 baseline-schema.json)。
> 备份/迁移用 `dacli form export/import`,表单结构修复用 `dacli form clone` (clone-baseline) 或 `dacli form update` (v0.11+ NEW-CMD 增量改 schema).
### 三步速查(长尾场景)
@@ -595,8 +582,7 @@ dacli app switch --appCode=workSystem --password=123456
# 2. 拿到示例完整 JSON(formData/columnData/tables/buttonData/flowTemplateJson 全在 data 里)
dacli form info <示例ID> # 全结构
dacli form info <示例ID> --expand-subtable # 主子表 ER 展开
dacli form msrelation <示例ID> # 主子表关系一行展示
dacli form info <示例ID> --expand-subtable # 主子表 ER 展开 (替代旧 form msrelation)
# 3. 抄思路(vModel/__config__/控件树等),自己写 fields,再:
dacli dm create --table=<新表> --dbLinkId=<...> --fields='[...]'
@@ -634,7 +620,7 @@ dacli form create --fullName=<...> --enCode=<...> --type=1 --webType=2 \
- ✅ **照思路仿造**:读 `formData.fields` 看用了哪些 `jnpfKey`、子表怎么排、`__config__` 关键字段,再用自己的字段命名重写一份
- ✅ **抄局部 JSON**:比如套打的 `printId`、行内编辑的 `inlineEdit` 配置块,可以局部复制到自己的 `columnData` 里
- ✅ **直接 fork**:需要"几乎一样"的表单,用 `dacli form export <id> --out=x.json` + `dacli form import x.json --enCode=Y --name=Z`,再用 `dacli form fix` 修字段
- ✅ **直接 fork**:需要"几乎一样"的表单,用 `dacli form export <id> --out=x.json` + `dacli form import x.json --enCode=Y --name=Z`,再用 `dacli form update` 改字段
- ❌ **不要"一键 apply"**:dacli 不再提供模板 apply。整段照搬不读 → 改动时找不到字段、子表 vModel 对不上,远比手写贵
- ❌ **不要把示例当生产表**:示例可能跨版本不稳定,仿造时只抄结构,业务字段全部自己重写
+103 -90
View File
@@ -1,25 +1,33 @@
# form-fix 技能
> **⚠️ v0.11+ 重大更新 (2026-06-25)**: 本文早期版本依赖的 `dacli form fix` 命令**根本不存在** (`src/commands/form/` 下无 `fix.ts`/`fixcolumndata.ts` 实现). 已重写, 改用 **`dacli form clone` + `dacli form update` + `dacli form info --expand-subtable`** 真实可达命令.
## 触发词
修复表单、表单不渲染、dacli form fix、columnList 字段不完整、appColumnData 错位、formData 字段不一致
修复表单、表单不渲染、columnList 字段不完整、appColumnData 错位、formData 字段不一致、BS-23/51/52/54
## 概述
当 JNPF 表单 API 返回 200 但浏览器不渲染时,使用 `dacli form fix` 命令修复。该命令采用 clone-baseline 模式:从基线复制完整 schema,然后 patch 业务字段。
当 JNPF 表单 API 返回 200 但浏览器不渲染时, 推荐 **clone-baseline 模式**:
- 从 workSystem/developSystem 已知可渲染的 form ID 复制完整 schema
- 用 `dacli form update` (v0.11+ NEW-CMD, PUT 语义, 自动 BS-49/50 防御 + 重发布) 改字段
- 验证: `dacli form info <id> --expand-subtable` + 浏览器 E2E
**2026-06-09 改进**:`--baseline` 参数现在是可选的。不指定时自动使用内置标准 baseline(`resources/dacli/baseline-schema.json`),无需依赖外部表单。
**v0.11+ webapi 镜像已消除 BS-51/52 根因**:
- `dacli form create` 走 `loadVisualDev` 镜像, schema 完整
- `dacli form import` 自动重建物理表 + 完整 columnData
- 多数 "列表白屏" 已无需手动 fix
## 6 类字段缺失诊断表
| 症状 | 根因 | 修复 |
|------|------|------|
| `Cannot read properties of undefined (reading 'jnpfKey')` | formData.fields[i] 缺 `__config__.jnpfKey` | dacli form fix |
| vxeTable=false,列表不渲染 | columnData.columnList[i] 缺 50+ 字段含 `__config__` | dacli form fix |
| 搜索栏不显示 | columnData.searchList[0] 缺完整 `__config__` | dacli form fix |
| 移动端表单不显示 | appColumnData 与 formData 不一致 | dacli form fix |
| 表单空白无字段 | tables 字段被替换为空数组 | dacli form fix |
| 表单不渲染但 API 正常 | state=1 (草稿发布) 必须 state=2 | dacli form release |
| 症状 | 根因 | 修复 (v0.11+ 真实命令) |
|------|------|------------------------|
| `Cannot read properties of undefined (reading 'jnpfKey')` | formData.fields[i] 缺 `__config__.jnpfKey` | `dacli form clone <workSystem_id> --enCode=新` + `dacli form update <id> --fields='[...]'` |
| vxeTable=false, 列表不渲染 | columnData.columnList[i] 缺 50+ 字段含 `__config__` | `dacli form clone <workSystem_id>` 拿完整 schema |
| 搜索栏不显示 | columnData.searchList[0] 缺完整 `__config__` | 同上 (clone 自带完整 searchList) |
| 移动端表单不显示 | appColumnData 与 formData 不一致 | 同上 (clone 自带 appColumnData) |
| 表单空白无字段 | tables 字段被替换为空数组 | `dacli form info <id> --expand-subtable` 检查 tables |
| 表单不渲染但 API 正常 | state=1 (草稿发布) 必须 state=2 | `dacli form release <id>` |
## 7 步法 Playbook
## 7 步法 Playbook (v0.11+ 重写版)
### 步骤 1: 诊断
```bash
@@ -29,96 +37,96 @@ dacli form info <formId> | head -100
# 检查菜单绑定
dacli menu list --keyword=<菜单名>
# 查主子表 ER 关系
dacli form info <formId> --expand-subtable
```
### 步骤 2: 选择基线(可选)
### 步骤 2: 选择基线 (从 workSystem / developSystem 拉)
**推荐:使用内置标准 baseline(不指定 --baseline)**
- 自动使用代码内置的标准 schema
- 不依赖任何外部表单
- 结构完整且版本可控
**推荐基线 form ID (已验证可渲染)**:
- 单表基线: `833005095028268677` (客户管理, workSystem)
- 主子表基线: `833737463619919749` (主子表测试A, workSystem)
- 也可以用 `dacli form selector --keyword=<关键词>` 找相似 form
**备选:使用指定基线表单**
- 单表基线: `833005095028268677` (客户管理,已验证可渲染)
- 主子表基线: `833737463619919749` (主子表测试A,已验证可渲染)
### 步骤 3: 运行 dacli form fix
### 步骤 3: clone-baseline 修复 (替代旧 form fix)
```bash
# 方式一:使用内置标准 baseline(推荐)
dacli form fix \
--target=<损坏表单ID> \
# 方式一: clone 工作流 (推荐)
dacli form clone <workSystem_baseline_id> \
--enCode=<新编码> \
--name=<新名称> \
--fieldsJson='[{"field":"f_xxx","label":"中文","jnpfKey":"input","required":true},...]' \
--release
--fullName=<新名称>
# 方式二:使用指定基线表单
dacli form fix \
--baseline=833005095028268677 \
--target=<损坏表单ID> \
--enCode=<新编码> \
--name=<新名称> \
--fieldsJson='[{"field":"f_xxx","label":"中文","jnpfKey":"input","required":true},...]' \
--release
# 主子表修复(使用内置 baseline)
dacli form fix \
--target=<损坏表单ID> \
--enCode=<新编码> \
--name=<新名称> \
--fieldsJson='[{"field":"f_xxx","label":"中文","jnpfKey":"input"},...]' \
--subFieldsJson='[{"field":"f_sub_xxx","label":"子表字段","jnpfKey":"input"},...]' \
--release
# 方式二: export + 改 + import (复杂改字段时)
dacli form export <workSystem_baseline_id> --out=baseline.json
# 编辑 baseline.json 改字段定义
dacli form import baseline.json --enCode=<新编码> --fullName=<新名称>
```
### 步骤 4: 验证修复结果
### 步骤 4: 增量改字段 (v0.11+ NEW-CMD: form update)
```bash
# 检查表单状态
dacli form list --keyword=<新编码>
# 改名
dacli form update <新form_id> --fullName="新名称"
# 检查字段完整性
dacli form msrelation <formId>
# 改 enCode
dacli form update <新form_id> --enCode="new_code"
# 改字段 (整体替换)
dacli form update <新form_id> --fields='[
{"field":"f_xxx","label":"中文","jnpfKey":"input","required":true}
]'
# 改主子表 children
dacli form update <新form_id> --children='[
{"table":"sub_table","fields":[...]}
]'
# 自动 BS-49/50 防御 + 重新发布 (默认 state 1)
```
### 步骤 5: 浏览器 E2E 验证
### 步骤 5: 发布 + 验证
```bash
# 强制重新发布 (state 0/2 → 1)
dacli form release <新form_id>
# 验证表单结构
dacli form info <新form_id> --json | jq '.columnData.columnList | length'
# 应输出 ≥ 50 (而非简化的 10)
# 验证主子表 ER
dacli form info <新form_id> --expand-subtable
# 验证物理表存在
dacli dm list --keyword=<新表名>
```
### 步骤 6: 浏览器 E2E 验证
```bash
# 打开浏览器访问表单
# URL: http://nginx/model/<enCode>
# 验证: 列表渲染 + 搜索栏 + 新建按钮 + 分页
```
## 参数说明
### 步骤 7: 创建菜单 (如需)
```bash
dacli menu create --formId=<新form_id> --parentId=<父菜单id> \
--fullName="<菜单名>" --icon=<图标>
```
| 参数 | 必填 | 说明 |
|------|------|------|
| `--baseline` | ❌ | 基线 form ID(不指定则使用内置标准 baseline) |
| `--target` | ✅ | 要修复的目标 form ID |
| `--enCode` | ✅ | 新编码 |
| `--name` | ✅ | 新名称 |
| `--fieldsJson` | ✅ | 业务字段定义 JSON 数组 |
| `--subFieldsJson` | ❌ | 主子表的子表字段 (无则单表) |
| `--webType` | ❌ | 1=仅表单, 2=表单+列表, 3=工作流 (默认 2) |
| `--enableFlow` | ❌ | 是否启用工作流 (默认 0) |
| `--flowId` | ❌ | 工作流模板 ID |
| `--dbLinkId` | ❌ | 数据源 ID (默认从 token.json 读) |
| `--release` | ❌ | 修复后立即发布 |
## 内置 baseline schema (resources/dacli/baseline-schema.json)
## 内置标准 baseline
**位置**: `dacli/src/main/resources/dacli/baseline-schema.json`
内置 baseline 文件位置:`src/main/resources/dacli/baseline-schema.json`
**包含内容**:
- formData: 完整的表单顶层结构 (50+ 字段配置)
- columnData: 完整的列表配置 (columnList / searchList / btnsList 等)
- appColumnData: 移动端配置 (与 columnData 一致)
**包含内容**:
- formData:完整的表单顶层结构(50+ 字段配置)
- columnData:完整的列表配置(columnList、searchList、btnsList 等)
- appColumnData:移动端配置(与 columnData 一致)
**优势**:
1. 不依赖外部表单, 永远可用
2. 版本可控, 随代码管理
3. 结构完整, 符合 JNPF 规范
**优势**:
1. 不依赖外部表单,永远可用
2. 版本可控,随代码管理
3. 结构完整,符合 JNPF 规范
4. 易于维护,修改 JSON 文件即可
## fieldsJson 字段格式
## fieldsJson 字段格式 (v0.11+ 与 webapi 一致)
```json
[
@@ -167,24 +175,29 @@ dacli form msrelation <formId>
## 常见问题
### Q: 为什么不用 dacli form create 从零创建?
A: `dacli form create` 生成的 columnList 只有 10 个字段,JNPF 前端需要 50+ 字段才能正常渲染。clone-baseline 模式复用已验证的完整 schema。
### Q: 为什么 `dacli form create` 直接建会列表白屏?
A: v0.10 及之前 columnList 只有 10 字段, JNPF 前端需 50+ 字段. **v0.11+ 已修复**: `dacli form create` 走 `loadVisualDev` webapi 镜像, 自动产完整 schema.
### Q: 什么时候需要指定 --baseline?
A: 大多数情况不需要指定,使用内置标准 baseline 即可。只有在需要复用特定表单的特殊配置(如自定义按钮、特殊校验规则)时才需要指定。
### Q: 什么时候用 clone vs update?
A:
- **clone**: 新表单与基线 schema 大体一致, 只改 enCode/name/少量字段
- **update**: 已存在的 form, 改名 / 改 enCode / 整体替换 fields
- **import**: 从 JSON 文件恢复 (备份还原 / 跨环境迁移)
### Q: 内置 baseline 在哪里?
A: 文件位置 `src/main/resources/dacli/baseline-schema.json`,包含完整的 formData + columnData 标准结构。修改此文件可自定义默认 baseline。
### Q: form update 的 PUT 语义会不会丢字段?
A: 是 PUT 语义, **整体替换**. 若只想改一个字段, 先 `dacli form info <id> --json` 拉完整, 改完再 PUT.
### Q: 修复后表单还是不显示?
A: 检查:
### Q: 修复后表单还是不显示?
A: 检查:
1. `dacli form list` 确认 state=1
2. `dacli menu list` 确认菜单存在且 propertyJson.moduleId 指向正确 formId
3. 浏览器 console 查看是否有 jnpfKey 错误
4. `dacli log exception --lines=10` 查后端异常
## 相关资源
- [[jnpf-form-fix-playbook]] — 7 步法详细说明
- [[jnpf-columndata-minimal-fail]] — columnList 字段不足问题
- `dacli form info --expand-subtable` — 查看主子表 ER 关系
- `dacli form msrelation` — 主子表关系查询
- `resources/dacli/baseline-schema.json` — 内置标准 baseline
- [[jnpf-columndata-minimal-fail]] — columnList 字段不足问题 (v0.11+ webapi 已修复)
- `dacli form info --expand-subtable` — 查看主子表 ER 关系 (替代旧 `form msrelation`)
- `dacli form update` — v0.11+ NEW-CMD 增量改 schema (commit `801a204`)
- `dacli form clone` — clone-baseline 模式 (webapi 化 commit `7bf7762`)
- `resources/dacli/baseline-schema.json` — 内置标准 baseline