fix(dacli): resolve merge conflicts + add v2 architecture spec

- resolve 10 merge conflicts across 4 files (app/init, dict/typecreate, form/create, webapi/_defhttp)
- fix syntax errors in typecreate.ts (commented-out if block)
- add ADR-0010: dacli v2 self-correcting CLI architecture design
- add simulation test comparing v1 vs v2 behavior

Co-Authored-By: Claude <[email protected]>
This commit is contained in:
sswandClaude committed 2026-07-20 10:11:41 +08:00
1 parent ec10f7ddfc
commit 61405e128d
6 files changed
+794 -107

No files matched your search

@@ -0,0 +1,481 @@
# ADR-0010: dacli v2 — 自修正 CLI 架构
> **日期**: 2026-07-20
> **状态**: 草案
> **决策者**: 基于 jxcj M1 实战复盘 + JNPF 源码分析 + ssw-loop 优化讨论
---
## 1. 问题陈述
### 1.1 当前 dacli 的核心问题
dacli v0.x-v1.x 积累了 46,923 行 TypeScript,但存在三个结构性问题:
| # | 问题 | 表现 | 根因 |
|---|------|------|------|
| 1 | **知识与工具分离** | 同一规则出现在 CLAUDE.md / ssw-loop references / anti_patterns.ts / blindspot_guards.ts / decisions/ / debug.md 共 7 处 | 知识存储位置错位,没有单一真值源 |
| 2 | **检测但不修正** | 22 个 blindspot guard 只 WARN 不修,AI 需要读懂 WARN → 翻译成操作 → 重试 | 防御层设计目标是"提醒"而非"修复" |
| 3 | **输出不分级** | step machine 校验、autoStrip 通知、API 调用日志全部混在 stdout,AI 被淹没 | 没有日志分离机制 |
### 1.2 dacli 的定位
dacli 的用户是 **AI(Claude)**,而非人类。AI 通过 dacli 替代人类在 JNPF 低代码平台上的基础操作。目标不是"完美配置"(人类可后续精细调整),而是"**可运行**":
- 表单能创建成功(API 200)
- 页面能打开(前端不崩溃)
- 数据能保存(数据库不报错)
- 列表能显示(不白屏)
### 1.3 JNPF 平台自身的做法
JNPF 的 AI 建表单(`VisualAiServiceImpl.form()`)只有 150 行,5 条后处理规则。每一条都是**防崩溃**的,不是"好看"的:
| JNPF 规则 | 防什么 |
|-----------|--------|
| 字段名含中文 → 重命名 `{jnpfKey}_num{001}` | SQL 不支持中文列名 |
| jnpfKey 不在白名单 → fallback `input` | 组件不存在,前端渲染崩溃 |
| 子表 radio/checkbox → `select` | 子表不支持这些组件 |
| 子表 editor/barcode → `input` | 同上 |
| `_fk` 结尾字段 → 丢弃 | JNPF 自己管外键,重复创建冲突 |
**JNPF 的哲学**:AI 起头 + 人类完善。AI 生成的不完美部分,人类在表单设计器里手动调整。
**dacli 的差异化价值**:在 JNPF 的基线之上,多修一层高置信度的改进(如 FK→relationForm、datetime→datePicker+format),让开发人员体验更好,但修错了可以一键回滚。
---
## 2. 设计原则
1. **可运行优先于正确**:静默修正和 assertive 修正必须保证"不修会崩溃或体验极差",不确定的不修
2. **修了就能回滚**:每条 assertive 修正提供精确的一行回滚命令
3. **AI 看结果,人看日志**:stdout 只输出结果摘要 + 下一步操作。详细信息写入结构化日志
4. **单一知识源**:所有规则定义在 registry.ts,自动生成 fix 函数 + --help + guide
5. **跟随 JNPF 不超越**:后处理规则优先镜像 JNPF 源码,不自己发明 JNPF 没有的规则
---
## 3. 三级修正策略
### 3.1 概述
```
Silent (100% 确定) Assertive (高置信) Suggest (不确定)
自动修 自动修 不修
一行日志 通知 + 回滚命令 给候选选项
```
### 3.2 Silent 级(静默修正)
| # | 规则 | 触发条件 | 修正 | 来源 |
|---|------|----------|------|------|
| S1 | enCode strip | 含 `-` `_` 空格 | 自动去特殊字符 | BS-新38 |
| S2 | fullName soften | 含 `-` `—` `_` | 自动替换为 `·` | BS-新52 |
| S3 | 字段名含中文 | `[一-龥]` | 重命名 `{jnpfKey}_num{001}` | JNPF VisualAiServiceImpl |
| S4 | jnpfKey 不在白名单 | 不在 JnpfKeyConsts | fallback `input` | JNPF VisualAiServiceImpl |
| S5 | 子表不支持组件 | radio/checkbox/editor/barcode 等 | radio/checkbox→select, 其余→input | JNPF VisualAiServiceImpl |
| S6 | dbLinkId 无效 | `'0'` / `''` / `'default'` | 从 app context 解析业务库 | BS-48 |
| S7 | buildFormData 缺关键字段 | formId/renderKey 为空 | UUID 补全 | BS-51/52 |
| S8 | sortCode 缺失 | undefined/null | 默认 0 | 平台默认值 |
| S9 | enabledMark 缺失 | undefined/null | 默认 1 | 平台默认值 |
| S10 | _fk 后缀字段 | fieldName.endsWith('_fk') | 丢弃 | JNPF VisualAiServiceImpl |
### 3.3 Assertive 级(自动修正 + 通知 + 回滚)
| # | 规则 | 触发条件 | 修正 | 回滚命令 | 可靠性 |
|---|------|----------|------|----------|--------|
| A1 | FK→relationForm | `/^f_(.+)_id$/` 且 jnpfKey≠relationForm | jnpfKey=relationForm, 从 form list 查 modelId | `dacli form update <id> --set='[{"field":"f_x_id","jnpfKey":"inputNumber"}]'` | 高(能找到关联表单) |
| A2 | datetime→datePicker | dataType=datetime 且 jnpfKey≠datePicker | jnpfKey=datePicker, format=yyyy-MM-dd HH:mm:ss | `dacli form update <id> --set='[{"field":"f_x","jnpfKey":"timePicker"}]'` | 极高 |
| A3 | date→datePicker | dataType=date 且 jnpfKey≠datePicker | jnpfKey=datePicker, format=yyyy-MM-dd | `dacli form update <id> --set='[{"field":"f_x","jnpfKey":"input"}]'` | 极高 |
| A4 | int+dictType→select | dataType=int 且 dictType 存在 且 jnpfKey≠select | jnpfKey=select | `dacli form update <id> --set='[{"field":"f_x","jnpfKey":"inputNumber"}]'` | 高(dictType 已验证存在) |
| A5 | timePicker→datePicker | jnpfKey=timePicker 且 dataType=datetime | jnpfKey=datePicker | `dacli form update <id> --set='[{"field":"f_x","jnpfKey":"timePicker"}]'` | 极高 |
### 3.4 Suggest 级(不修,给候选)
| # | 场景 | 提示内容 |
|---|------|----------|
| G1 | FK 关联表有多个候选 | 列出匹配的 form enCode,让 AI 选 |
| G2 | int 字段无 dictType 但有多个匹配字典 | 列出候选字典 enCode/fullName |
| G3 | relationForm 回显列可选 | 列出关联表的字段,当前默认回显第一个文本字段 |
| G4 | 本表是否建 FK 字段 | 提醒:可在 description 中加"本表不建FK字段" |
| G5 | 多个相似表名 | f_team_info_id 匹配到 team_info 和 team_info_v2 |
### 3.5 修正结果汇总
```
Silent Assertive Suggest ← 级别
自动修 自动修 不修
不通知 通知+回滚 给候选
现在 dacli: 2 条 0 条 20 条 ← 几乎全是 WARN,AI 自己修
改后 dacli: 10 条 5 条 5 条 ← 自动修为主,AI 只处理不确定的
```
---
## 4. 日志分离
### 4.1 设计
```
stdout (AI 看) ~/.dacli/logs/{appCode}/ (人查)
结果摘要 + 修正计数 完整修正详情含回滚命令
下一步操作提示 原始请求/响应
错误信息 堆栈跟踪
时间线
```
### 4.2 日志存储
```
~/.dacli/logs/{appCode}/
├── {timestamp}-{command}-{enCode}.json
├── tail # 符号链接指向最新日志
└── index.jsonl # 行式索引,快速查询
```
### 4.3 日志命令
```bash
dacli log --last # 最近一次命令摘要
dacli log --last --detail # 含回滚命令、堆栈
dacli log --form=<enCode> # 按表单查历史
dacli log --level=fix # 只看修正记录
dacli log --since=2026-07-20 # 时间范围
```
### 4.4 输出对比
**现在** (AI 看到 ~40 行):
```
$ dacli form create --ai "报名表,含 f_user_id..."
loadVisualDev.create formId=...
[BS-新38] enCode 含 `-`, auto strip: registration-form → registrationform
[BS-新52] fullName 含特殊符号, auto soften...
[step 0 基础信息] enCode=registrationform ✓
[step 1 平台唯一性] enCode 不冲突 ✓
[step 2 字典项] 0 items, skip
✓ step machine 校验通过 (3/3)
[BS-54] f_user_id jnpfKey=inputNumber 建议改为 relationForm,
因 f_*_id 关联字段需 relationForm 组件
[BS-60] f_start_time 缺 format, 建议 datePicker + format="yyyy-MM-dd HH:mm:ss"
[BS-61] f_status int+dictType jxcjcompetitionstatus 但 jnpfKey 不是 select
... (20+ 行省略)
✓ 表单创建: id=8471... enCode=registrationform
```
**改后** (AI 看到 ~6 行):
```
$ dacli form create --ai "报名表,含 f_user_id、f_start_time、f_status..."
✓ registration_form 已创建 (id=8471...) 修正 5 处 建议 1 项
测试: dacli test run --formId=8471...
详情: dacli log --last
```
---
## 5. 知识注册中心(单一真值源)
### 5.1 设计
```
registry.ts (唯一知识定义)
│
├──→ 自动生成: fix 函数(_auto_fix.ts)
├──→ 自动生成: --help 输出
├──→ 自动生成: dacli guide 输出
├──→ 自动生成: decisions/*.md 文档
└──→ 编译时检查: 与 JNPF 源码一致性
```
### 5.2 规则注册示例
```typescript
// dacli/src/registry.ts
export interface FixRule {
id: string
level: 'silent' | 'assertive' | 'suggest'
category: 'form' | 'dict' | 'menu' | 'dm' | 'workflow' | 'universal'
trigger: TriggerFn
fix: FixFn | null // suggest 级为 null
rollback?: RollbackFn // assertive 级必填
source: string // JNPF 源码引用 或 BS 编号
}
const RULES: FixRule[] = [
{
id: 'A1-fk-relation-form',
level: 'assertive',
category: 'form',
trigger: (f: Field) => /^f_(.+)_id$/.test(f.field) && f.jnpfKey !== 'relationForm',
fix: async (f: Field, ctx: Ctx) => {
const target = f.field.match(/^f_(.+)_id$/)?.[1]
const forms = await ctx.formList()
const matched = forms.find(f => f.enCode === target)
if (!matched) return null // 降级为 suggest
return { ...f, jnpfKey: 'relationForm', modelId: matched.id, dictType: target }
},
rollback: (f: Field, formId: string) =>
`dacli form update ${formId} --set='[{"field":"${f.field}","jnpfKey":"inputNumber"}]'`,
source: 'decisions/0001-fk-relation-form-required.md, web/RelationForm.vue',
},
// ... 所有规则
]
```
### 5.3 合并当前防御文件
| 当前文件 | 行数 | 处理 |
|----------|------|------|
| `_blindspot_guards.ts` | 36K | 提取 fix 函数 → registry;删除 WARN-only guard |
| `_anti_patterns.ts` | 10K | wrong/right 对 → registry 的 trigger/fix/rollback |
| `_error_codes.ts` | 17K | 保留错误分类;enhanceFromBackend 独立 |
| `_selfcheck.ts` | 21K | 删除(融入 test render) |
| `_precheck.ts` | 10K | step machine 保留;WARN 降级 |
| `_encode_validator.ts` | 7K | → registry S1/S2 silent rules |
| `_dirty_check.ts` | 4K | 删除(未被使用) |
**预计合并后**: 7 文件 3,593 行 → 1 文件 registry.ts ~500 行 + _auto_fix.ts ~300 行。
---
## 6. 命令输出规范
### 6.1 stdout 输出格式(AI 看的)
```
$ dacli <command> [options]
{emoji} {enCode} {动作} (id={id}) 修正 {n} 处 建议 {m} 项 [{耗时}]
测试: dacli test run --formId={id}
详情: dacli log --last
```
emoji 含义:
- `✓` 成功
- `✗` 失败
- `⚠` 部分成功(创建成功但有关键警告)
### 6.2 失败输出
```
$ dacli <command> [options]
✗ {动作} 失败 [{耗时}]
{错误摘要}(1 行,人类可读)
详情: dacli log --last
重试: {修正建议,如果有}
```
### 6.3 日志文件结构
```json
{
"command": "form create",
"timestamp": "2026-07-20T14:30:52.123Z",
"duration_ms": 3200,
"result": "success",
"summary": {
"enCode": "registration_form",
"id": "8471...",
"silent_fixes": 2,
"assertive_fixes": 3,
"suggestions": 1
},
"fixes": [
{
"id": "S1",
"level": "silent",
"field": "enCode",
"from": "registration-form",
"to": "registration_form"
},
{
"id": "A1",
"level": "assertive",
"field": "f_user_id",
"from": "inputNumber",
"to": "relationForm",
"rollback": "dacli form update 8471... --set='[{\"field\":\"f_user_id\",\"jnpfKey\":\"inputNumber\"}]'"
}
],
"suggestions": [
{
"id": "G2",
"field": "f_status",
"message": "int 字段有候选字典",
"candidates": ["jxcjcompetitionstatus", "jxcjauditstate"]
}
],
"raw": {
"request": { "...": "..." },
"response": { "...": "..." }
}
}
```
---
## 7. dacli guide 命令
### 7.1 定位
`dacli guide` 不执行任何操作,仅输出 AI 所需的场景化知识。数据来源:registry.ts。
```bash
dacli guide form-create # form create 的场景推荐 + 已知陷阱
dacli guide form-create --context='{...}' # 携带当前字段上下文,输出定制建议
dacli guide dict-create # dict 创建指南(BS-47 等)
dacli guide troubleshoot --error='...' # 根据错误消息匹配修复路径
```
### 7.2 guide 输出示例
```
$ dacli guide form-create --context='{"fields":["f_user_id","f_start_time"],"appCode":"testspace"}'
━━ 模式推荐:
含 FK 字段 (f_user_id) → 推荐 --fields 模式
--ai 模式可用但 FK 字段不会自动设为 relationForm,创建后需 form update 修正
━━ 字段检查:
f_user_id (FK): 将自动修正为 relationForm (关联 user 表)
f_start_time (datetime): 将自动修正为 datePicker (format=yyyy-MM-dd HH:mm:ss)
━━ 建议命令:
dacli form create \
--fields='[
{"field":"f_user_id","fieldName":"用户","dataType":"varchar","dataLength":"50"},
{"field":"f_start_time","fieldName":"开始时间","dataType":"datetime"}
]' \
--fullName="..." --enCode="..." --autoRelease
```
---
## 8. CLAUDE.md + ssw-loop 精简
### 8.1 CLAUDE.md 精简
| 段 | 现在 | 改后 | 理由 |
|----|------|------|------|
| §2 dacli 用法 | ~100 行 | 3 行: "所有操作走 dacli,查操作用 `dacli guide`" | 知识在 registry |
| §2.5-2.7 架构 | ~50 行 | 删除 | 入 dacli 文档 |
| §3 命名规范 | ~20 行 | 保留 | 环境常识 |
| §4-14 行为准则 | ~80 行 | ~20 行 | 精简为 5 条核心准则 |
| §已知盲点 | 嵌入文本 | 删除 | 入 registry |
| 总计 | 386 行 | ~50 行 | |
### 8.2 ssw-loop 精简
| 文件 | 现在 | 改后 |
|------|------|------|
| SKILL.md | 203 行 | ~80 行(7 阶段流程 + 派发规则) |
| references/stages.md | 250 行 | 保留(阶段详细步骤) |
| references/anti-patterns.md | 228 行 | **删除**(入 registry) |
| references/lessons-from-apps.md | 317 行 | **删除**(入 registry) |
| references/subagent-must-do.md | 132 行 | ~40 行(前置步骤改为 `dacli guide --precheck`) |
---
## 9. 实施计划
### Phase 1: 核心改造(1 周)
| # | 任务 | 产出 |
|---|------|------|
| 1 | 创建 `dacli/src/registry.ts`,迁移 Silent 级 10 条规则 | registry.ts |
| 2 | 创建 `dacli/src/commands/_auto_fix.ts`,实现 fix pipeline | _auto_fix.ts |
| 3 | 创建日志系统(`dacli/src/core/logfile.ts` + `dacli log` 命令) | 结构化日志 |
| 4 | 改 `form create` 输出格式(stdout 精简 + 日志写入) | 命令适配 |
### Phase 2: Assertive + guide(1 周)
| # | 任务 | 产出 |
|---|------|------|
| 5 | 迁移 Assertive 级 5 条规则到 registry | 含 rollback |
| 6 | 迁移 Suggest 级 5 条规则到 registry | 候选逻辑 |
| 7 | 实现 `dacli guide` 命令 | guide 命令 |
| 8 | 合并 7 防御文件 → registry 引用 | 删除旧文件 |
### Phase 3: 文档 + CLAUDE.md(3 天)
| # | 任务 | 产出 |
|---|------|------|
| 9 | 精简 CLAUDE.md(386 → ~50 行) | CLAUDE.md v2 |
| 10 | 精简 ssw-loop(删除 3 个 reference,精简 SKILL.md) | ssw-loop v2 |
| 11 | 适配 `form-create.md.tmpl` 子代理模板 | 模板更新 |
### Phase 4: 其他命令适配(1 周)
| # | 任务 | 产出 |
|---|------|------|
| 12 | dict/menu/dm/workflow 命令适配新输出格式 | 全命令统一 |
| 13 | 每类命令的 silent/assertive/suggest 规则注册 | registry 完整 |
| 14 | 旧 defense 文件删除 + import 清理 | 代码清理 |
---
## 10. 验证
### 10.1 回归测试
```bash
# 核心命令不受影响
dacli form create --fields='...' --autoRelease
dacli dict typeCreate --enCode=test_dict --fullName="测试字典"
dacli menu create --formId=xxx --fullName="测试菜单" --parentId=yyy
# 新功能
dacli log --last
dacli guide form-create
dacli guide dict-create
```
### 10.2 效果验证
用同一个输入"报名表单(含 f_user_id, f_start_time, f_status)"对比:
| 指标 | 现在 | 改后 |
|------|------|------|
| 命令成功率 | ~60%(AI 需读 WARN 后重试) | ~95%(自动修正) |
| AI 阅读行数 | ~40 行 | ~6 行 |
| 表单可运行 | 不一定(FK 未设 relationForm 时存数据报错) | 保证可运行 |
| 回滚能力 | 无(需手动重建) | 精确一行命令 |
| 防御代码维护点 | 7 文件 | 1 文件 |
| 同一规则出现次数 | 平均 4 处 | 1 处 |
---
## 11. 不在本方案范围
- **全自动完美配置**:assertive 修正仅覆盖高置信场景,不确定的不修
- **webapi 自动代码生成**:`_loader.ts` 模式目前工作正常,后续单独评估
- **子代理断点续跑**:ssw-loop 优化的一部分,不在 dacli v2 范围
- **MCP server 模式**:CLI 仍然是 AI 的主要接口,MCP 后续评估
- **uniapp 移动端**:同问题但独立处理
---
## 12. 参考
- ADR-0001: FK 字段必须 relationForm
- ADR-0002: form create --ai 4 限制
- ADR-0003: form update --fields 不同步物理表
- ADR-0009: 代码注释规范
- jxcj M1 实战复盘: `docs/jxcj/meta-issues-ssw-loop.md`
- ssw-loop 优化分析: `docs/jxcj/ssw-loop-optimization.md`
- JNPF 源码: `VisualAiServiceImpl.form()` — AI 后处理基线
- JNPF 源码: `AiConstants.GEN_MODEL_QUETION` — AI prompt 模板
- JNPF 源码: `JnpfKeyConsts` — 组件白名单
---
<!--
本文档是 dacli v2 架构决策记录。
待 CLAUDE.md §13 复现验证后进入实施。
跨项目通用,不包含任何 appCode 特定信息。
-->
@@ -0,0 +1,291 @@
# dacli v2 模拟测试:比赛报名表
> **测试场景**: AI 通过 dacli 创建一个"比赛报名表"
> **输入特征**: 6 字段、2 个 FK、1 个 datetime、1 个 int+dict、enCode 含 `-`、fullName 含 `-`
> **目标**: 对比 dacli v1(现在)vs dacli v2(设计)的行为
---
## 输入
AI 发出命令(含 AI 生成 schema):
```bash
dacli form create \
--ai='[{
"tableTitle": "比赛报名",
"tableName": "registration",
"isMain": true,
"fields": [
{"fieldTitle": "用户", "fieldName": "f_user_id", "fieldDbType": "bigint", "fieldComponent": "inputNumber"},
{"fieldTitle": "比赛", "fieldName": "f_competition_id", "fieldDbType": "bigint", "fieldComponent": "inputNumber"},
{"fieldTitle": "团队名称", "fieldName": "f_team_name", "fieldDbType": "varchar", "fieldComponent": "input"},
{"fieldTitle": "报名时间", "fieldName": "f_start_time", "fieldDbType": "datetime", "fieldComponent": "timePicker"},
{"fieldTitle": "状态", "fieldName": "f_status", "fieldDbType": "int", "fieldComponent": "inputNumber"},
{"fieldTitle": "备注", "fieldName": "f_remark", "fieldDbType": "text", "fieldComponent": "textarea"}
]
}]' \
--fullName="比赛报名-表" \
--enCode="registration-form" \
--autoRelease
```
**注意这个输入的问题**(真实 AI 输出常见):
1. `f_user_id` / `f_competition_id`: FK 字段配了 `inputNumber` ← 应配 `relationForm`
2. `f_start_time` (datetime): 配了 `timePicker` ← 应配 `datePicker`
3. `f_status` (int + dictType): 配了 `inputNumber` ← 应配 `select`
4. `enCode`: 含 `-` ← 后端 400
5. `fullName`: 含 `-` ← 后端校验失败
---
## 对比
### dacli v1 行为(现在)
```
$ dacli form create --ai='[...]' --fullName="比赛报名-表" --enCode="registration-form" --autoRelease
[AI] NCPF backend 生成 schema...
[AI] ✓ AI 生成 1 个主表, 6 个字段
[buildFormData] ✓ 构建 formData...
loadVisualDev.create formId=...
[BS-新38] enCode 含 `-`, auto strip: registration-form → registrationform
[BS-新52] fullName 含特殊符号, auto soften: 比赛报名-表 → 比赛报名·表
[preCheck] 表单预检查:
[step 0 基础信息] enCode=registrationform ✓ fullName=比赛报名·表 ✓
[step 1 平台唯一性] enCode 不冲突 ✓
[step 2 字段校验]
[WARN] f_user_id: f_*_id 字段应配 relationForm, 当前 inputNumber
修复: 显式 jnpfKey=relationForm + dictType=<关联表enCode>
[WARN] f_competition_id: f_*_id 字段应配 relationForm, 当前 inputNumber
修复: 显式 jnpfKey=relationForm + dictType=<关联表enCode>
[WARN] f_start_time: datetime 应配 datePicker, 当前 timePicker
修复: jnpfKey=datePicker, format="yyyy-MM-dd HH:mm:ss"
[WARN] f_status: int + dictType 应配 select, 当前 inputNumber
修复: jnpfKey=select
[step 3 字段名] ✓ 无中文/保留字
[blindspot guard] 检测:
[BS-54] f_user_id jnpfKey=inputNumber 建议改为 relationForm
因 f_*_id 关联字段需 relationForm 组件, 否则列表显示 ID 数字
[BS-54] f_competition_id jnpfKey=inputNumber 建议改为 relationForm
[BS-60] f_start_time 缺 format, 建议 datePicker + format="yyyy-MM-dd HH:mm:ss"
[BS-61] f_status int+dictType jxcjcompetitionstatus 但 jnpfKey 不是 select
✓ 表单创建: id=847134936094737350 enCode=registrationform
━━ 创建成功但需手动修正 4 处:
1. f_user_id → relationForm (关联 user)
2. f_competition_id → relationForm (关联 competition)
3. f_start_time → datePicker (format=yyyy-MM-dd HH:mm:ss)
4. f_status → select (dictType=jxcjcompetitionstatus)
运行: dacli form update 847134936094737350 --fields='[修正后的字段JSON]'
```
**统计**:
- stdout 行数: ~35 行
- 表单能创建: ✓
- 数据能保存: ✗(f_user_id / f_competition_id 存的是数字,POST 报 "Field cannot be empty" 如果物理列是 varchar FK)
- AI 需要: 读 35 行 → 理解 4 个 WARN → 手写修正 JSON → 跑 form update → 可能还要 form import --autoTable 重建物理表
---
### dacli v2 行为(设计)
```
$ dacli form create --ai='[...]' --fullName="比赛报名-表" --enCode="registration-form" --autoRelease
✓ registration_form 已创建 (id=8471...) 修正 6 处 建议 1 项 [3.2s]
测试: dacli test run --formId=8471...
详情: dacli log --last
```
**AI 看到的**: 1 行。表单已可用。
如果需要了解更多:
```bash
$ dacli log --last
```
```
━━ dacli form create — 2026-07-20 14:30:52
结果: ✓ 成功
表单: registration_form (id=8471...) 6 字段 / 2 子表 / 1 主表
━━ 修正 6 处:
[silent] enCode: registration-form → registration_form
[silent] fullName: 比赛报名-表 → 比赛报名·表
✅ f_user_id: inputNumber → relationForm (关联 user)
回滚: dacli form update 8471... --set='[{"field":"f_user_id","jnpfKey":"inputNumber"}]'
✅ f_competition_id: inputNumber → relationForm (关联 competition)
回滚: dacli form update 8471... --set='[{"field":"f_competition_id","jnpfKey":"inputNumber"}]'
✅ f_start_time: timePicker → datePicker (format=yyyy-MM-dd HH:mm:ss)
回滚: dacli form update 8471... --set='[{"field":"f_start_time","jnpfKey":"timePicker"}]'
✅ f_status: inputNumber → select (dictType=jxcjcompetitionstatus)
回滚: dacli form update 8471... --set='[{"field":"f_status","jnpfKey":"inputNumber"}]'
━━ 建议 1 项:
💡 f_competition_id: relationForm 回显列可选
[1] f_competition_name (比赛名称) ← 默认
[2] f_competition_code (比赛编码)
调整: dacli form columnOptions 8471... --field=f_competition_id --columns='["f_competition_name","f_competition_code"]'
━━ 原始请求/响应用于调试:
dacli log --last --detail
```
**统计**:
- stdout 行数: 6 行
- 表单能创建: ✓
- 数据能保存: ✓(FK 字段已修正为 relationForm,物理表列正确)
- AI 需要: 看 1 行确认成功 → 跑 test → 根据建议决定是否调整 columnOptions
- 如果修正错了: 复制一条回滚命令
---
### 关键差异总结
| | dacli v1(现在) | dacli v2(设计) |
|---|---|---|
| AI 阅读行数 | ~35 | ~6 |
| 表单可运行 | ✗(FK 未设 relationForm 存数据报错) | ✓ |
| AI 操作步骤 | 创建 → 读 WARN → 手写 JSON → 修正 → 可能重建表 | 创建 → 测试 |
| 回滚 | 手动重建表单 | 一行命令 |
| 信息查找 | grep stdout 历史 | `dacli log --last` 结构化查询 |
| 开发人员体验 | 需要深入理解 JNPF 组件体系 | 创建即用,不满意可回滚 |
---
## 日志文件示例
```json
{
"timestamp": "2026-07-20T14:30:52.123+08:00",
"command": "form create",
"duration_ms": 3200,
"result": "success",
"summary": {
"enCode": "registration_form",
"formId": "847134936094737350",
"fields_count": 6,
"silent_fixes": 2,
"assertive_fixes": 4,
"suggestions": 1
},
"silent_fixes": [
{
"id": "S1",
"field": "enCode",
"original": "registration-form",
"fixed": "registration_form",
"reason": "含特殊字符 `-`,后端校验会 400"
},
{
"id": "S2",
"field": "fullName",
"original": "比赛报名-表",
"fixed": "比赛报名·表",
"reason": "含特殊符号 `-`,后端校验不允许"
}
],
"assertive_fixes": [
{
"id": "A1",
"field": "f_user_id",
"from": {"jnpfKey": "inputNumber"},
"to": {"jnpfKey": "relationForm", "modelId": "user_form_id_xxx", "dictType": "user"},
"rollback": "dacli form update 847134936094737350 --set='[{\"field\":\"f_user_id\",\"jnpfKey\":\"inputNumber\"}]'",
"confidence": "high",
"reason": "f_*_id 字段名 + 找到匹配表单 user"
},
{
"id": "A1",
"field": "f_competition_id",
"from": {"jnpfKey": "inputNumber"},
"to": {"jnpfKey": "relationForm", "modelId": "competition_form_id_xxx", "dictType": "competition"},
"rollback": "dacli form update 847134936094737350 --set='[{\"field\":\"f_competition_id\",\"jnpfKey\":\"inputNumber\"}]'",
"confidence": "high",
"reason": "f_*_id 字段名 + 找到匹配表单 competition"
},
{
"id": "A2",
"field": "f_start_time",
"from": {"jnpfKey": "timePicker"},
"to": {"jnpfKey": "datePicker", "format": "yyyy-MM-dd HH:mm:ss"},
"rollback": "dacli form update 847134936094737350 --set='[{\"field\":\"f_start_time\",\"jnpfKey\":\"timePicker\"}]'",
"confidence": "extremely_high",
"reason": "datetime 类型应配 datePicker,timePicker 只能选时间不能选日期"
},
{
"id": "A4",
"field": "f_status",
"from": {"jnpfKey": "inputNumber"},
"to": {"jnpfKey": "select", "dictType": "jxcjcompetitionstatus"},
"rollback": "dacli form update 847134936094737350 --set='[{\"field\":\"f_status\",\"jnpfKey\":\"inputNumber\"}]'",
"confidence": "high",
"reason": "int 类型且 dictType=jxcjcompetitionstatus 已存在,应配 select 下拉框"
}
],
"suggestions": [
{
"id": "G3",
"field": "f_competition_id",
"message": "relationForm 回显列可选",
"current": ["f_competition_name"],
"available": [
{"field": "f_competition_name", "label": "比赛名称"},
{"field": "f_competition_code", "label": "比赛编码"}
],
"action": "dacli form columnOptions 847134936094737350 --field=f_competition_id --columns='[\"f_competition_name\",\"f_competition_code\"]'"
}
]
}
```
---
## 回滚场景演练
假设 A1 规则把 `f_user_id` 错误地关联到了 `user` 表(实际应该关联 `sys_user` 表):
```
$ dacli form create --ai "..."
✓ registration_form 已创建 (id=8471...) 修正 6 处 建议 1 项
测试: dacli test run --formId=8471...
详情: dacli log --last
$ dacli log --last --detail | grep "f_user_id" -A3
✅ f_user_id: inputNumber → relationForm (关联 user)
回滚: dacli form update 8471... --set='[{"field":"f_user_id","jnpfKey":"inputNumber"}]'
# 开发人员发现关联错了 → 回滚 + 重指定
$ dacli form update 8471... --set='[{"field":"f_user_id","jnpfKey":"inputNumber"}]'
# 或者直接指定正确的关联表:
$ dacli form update 8471... --set='[{"field":"f_user_id","jnpfKey":"relationForm","dictType":"sys_user"}]'
```
**开发人员体验**: 复制日志里的一行回滚命令 → 跑。10 秒内修正,不需要重建表单。
---
## 结论
| 问题 | dacli v1 | dacli v2 |
|------|---------|---------|
| 知识在哪里 | 7 个防御文件 + CLAUDE.md + ssw-loop | registry.ts(单一源) |
| AI 看什么 | ~35 行混合输出 | ~6 行结果摘要 |
| 检测到问题怎么办 | WARN → 期望 AI 读+改+重试 | 自动修 → 通知+回滚命令 |
| 表单能用吗 | 不一定 | 保证可运行 |
| 修错了怎么办 | 不存在(没修) | 一行回滚命令 |
| 细节去哪了 | 全部 stdout | 结构化日志文件 |
**核心变化**: dacli 从"检测+提醒"变成"修正+回滚"。AI 不需要学 JNPF 规则,只需要确认结果。
-45
View File
@@ -1,7 +1,6 @@
/**
* commands/app/init.ts — `dacli app init` (v3.0+ 移除 --restart 虚假 flag)
*
<<<<<<< Updated upstream
* v3.0+ (2026-06-29) 移除 --restart 参数:
* - 历史: v0.9 设计要实做 kill+nohup+健康检查, 一直是 dry-run (误导)
* - 90% 场景根本不需要重启 JVM (改配置/数据源/菜单都能热加载)
@@ -13,11 +12,6 @@
* - system 缺失检测 (v0.11e+ B-2 fix)
* - --auto-recover (真工作, 重建 system)
*
=======
* 注: v0.7.1+ init 是 "JNPF 后端一键启动/重启 + 健康检查 + 重登 + 自动恢复" 工具,
* 不是 form 初始化. 走 dacli.conf 读 jar-pattern/port, 杀进程 + nohup.
*
>>>>>>> Stashed changes
* v0.11e+ Bug B-2: 检测 base_system 缺失时自动调 `app create` 重建.
* 复盘: `dacli app clear --appCode=X` 把 base_system 中 X 删到 history_bak,
* 之后 form/menu create 触发后端 NPE at VisualdevController.java:506
@@ -36,10 +30,6 @@ import { healthCheck, formatHealthCheckForHuman } from '../../core/_health_check
interface InitAppOpts {
appCode?: string
<<<<<<< Updated upstream
=======
restart?: boolean
>>>>>>> Stashed changes
/** v0.11e+ B-2 fix: 检测到 system 缺失时自动调 app create 重建 */
autoRecover?: boolean
/** 同上, 重建时传给 app create 的中文名 */
@@ -48,21 +38,14 @@ interface InitAppOpts {
export function buildAppInitCommand(): Command {
const cmd = new Command('init')
<<<<<<< Updated upstream
.description('应用初始化 (健康检查 + system 缺失检测; --auto-recover system 缺失时自动重建; v3.0+ 移除 --restart)')
.option('--appCode <code>', '应用 code (不传则用当前登录)')
=======
.description('应用初始化 (健康检查; --restart 重启 JNPF; --auto-recover system 缺失时自动重建; v0.11e+)')
.option('--appCode <code>', '应用 code (不传则用当前登录)')
.option('--restart', '重启 JNPF 后端 (v0.9+ 集成, 现在 dry-run)', false)
>>>>>>> Stashed changes
.option('--auto-recover', 'v0.11e+ B-2: 检测到 base_system 缺失时自动调 app create 重建', false)
.option('--appName <name>', 'auto-recover 时传给 app create 的中文名 (默认 "未知应用")')
.action(async (opts: InitAppOpts) => {
const c = await JnpfClient.fromToken()
const appCode = opts.appCode || c.appCode
<<<<<<< Updated upstream
// 0. v0.11h+ (2026-06-28) BS-56-helper: baseUrl 健康检查 (前置)
// 不通时立即给明确指引, 避免后续 form/dm/menu 全 fail "ECONNREFUSED"
// 注: 不带 token, 仅看 TCP + HTTP 是否可达 (与 baseUrl 探活对齐)
@@ -77,9 +60,6 @@ export function buildAppInitCommand(): Command {
}
// 1. 健康检查: 拉 form list 看是否能返 (v0.11+ 兼容保留, 与 baseUrl 自检互为补充)
=======
// 1. 健康检查: 拉 form list 看是否能返
>>>>>>> Stashed changes
const r = await c.get<{ list: unknown[] }>('/visualdev/Base', { currentPage: 1, pageSize: 1 })
if (r.code === 200) {
log.ok(`✓ JNPF 健康: appCode=${c.appCode} (form 列表可访问)`)
@@ -103,38 +83,18 @@ export function buildAppInitCommand(): Command {
log.info(' 提示: 加 --auto-recover 自动调 app create 重建')
log.info(` 或手动: dacli app create --appCode=${appCode} --appName=<中文名> --force-rebuild`)
}
<<<<<<< Updated upstream
}
})
installHelpHook(cmd, {
purpose: '应用初始化 (健康检查 + system 缺失检测; v3.0+ 移除 --restart)',
optional: {
'--appCode': '应用 code (不传则用当前登录)',
=======
}
// 3. --restart: v0.9+ 才实做, 现在 dry-run
if (opts.restart) {
log.warn('--restart 当前 v0.9+ 才实做, 现在 dry-run')
log.info(' 计划: 读 dacli.conf 的 jar-pattern/port, kill+rm+nohup+健康检查+重登')
}
})
installHelpHook(cmd, {
purpose: '应用初始化 (健康检查 / 重启 JNPF / system 缺失时自动重建)',
optional: {
'--appCode': '应用 code (不传则用当前登录)',
'--restart': '重启 JNPF 后端 (v0.9+ 集成, 现在 dry-run)',
>>>>>>> Stashed changes
'--auto-recover': 'v0.11e+ B-2: 检测到 base_system 缺失时自动调 app create 重建',
'--appName': 'auto-recover 时传给 app create 的中文名 (默认 "未知应用")',
},
example: [
'dacli app init',
<<<<<<< Updated upstream
'dacli app init --appCode=tds',
=======
'dacli app init --appCode=tds --restart',
>>>>>>> Stashed changes
'dacli app init --appCode=tds --auto-recover',
'dacli app init --appCode=tds --auto-recover --appName=可信数据空间',
].join('\n'),
@@ -144,15 +104,10 @@ export function buildAppInitCommand(): Command {
ref: 'doc/v0.8-plan.md §4 D1 + MEMORY dacli-v011e-100percent-final-2026-06-27.md (B-2); backend: jnpf/.../VisualdevController.java:506 (infoByEnCode null → NPE)',
},
notes: [
<<<<<<< Updated upstream
'**v3.0+ 移除 --restart**: 90% 场景不需要 JVM 重启 (热加载/手动 nohup 都能解决)',
' 历史: v0.9 设计 kill+nohup+健康检查, 一直是 dry-run (误导)',
' 后续 v0.12+ 可能加 --reload-config (actuator/refresh) 热加载替代',
'**当前 init 职责**: 健康检查 + system 缺失检测 + --auto-recover 重建',
=======
'**v0.9+ 实做**: --restart 走 dacli.conf 自动 kill+nohup+健康+重登',
'**当前**: --restart dry-run 提示计划',
>>>>>>> Stashed changes
'**v0.11e+ B-2 fix**: --auto-recover 检测 base_system 缺失时, 自动调 app create 重建',
' appName 优先级: --appName 参数 > 兜底 "未知应用"',
' 重建后会重新 login 到新 appCode 并自动重登',
+3 -2
View File
@@ -59,8 +59,9 @@ export function buildDictTypeCreateCommand(): Command {
opts.fullName = softened
}
// (fullName 含 space/parens 自动 strip + WARN
// dict 已 soften `-` → `·`, 但 space/parens/其他标点仍会触发 if (opts.fullName) {
// fullName 含 space/parens 自动 strip + WARN
// dict 已 soften `-` → `·`, 但 space/parens/其它标点仍会触发
if (opts.fullName) {
const _fnStrip = autoStripFullName(opts.fullName)
if (_fnStrip.wasStriped) {
log.warn(`! autoStrip fullName: ${_fnStrip.original} → ${_fnStrip.value} (BS-新52, 下次别用空格/括号/标点)`)
+19 -56
View File
@@ -1305,64 +1305,12 @@ export function buildFormCreateCommand(): Command {
log.ok(`创建成功: id=${newId} enCode=${opts.enCode}`)
if (opts.autoRelease && type !== 4 && newId !== '(unknown)') {
<<<<<<< Updated upstream
log.info(`loadVisualDev.release (formId=${newId})`)
// Bug release 失败时重试 1 次 (500ms 间隔), 仍失败 process.exit(1)
// 之前 log.warn + 继续 → state=1 假成功, base_visual_release 表无 release 行, 后续 NPE
// 后端: VisualdevController.java:639 setState(1) + :673 saveOrUpdate(releaseEntity)
// web: web/.../api/onlineDev/visualDev.ts:43 release(id) → POST Actions/Release
const tryRelease = async (): Promise<{ code?: number; msg?: string }> => {
try {
return (await loadVisualDev.release(newId)) as { code?: number; msg?: string }
} catch (e) {
return { code: -1, msg: (e as Error).message?.slice(0, 200) }
}
}
let rr = await tryRelease()
if (rr.code !== 200 && rr.code !== undefined) {
log.warn(`首次发布失败 (code=${rr.code}, msg=${rr.msg}), 重试 1 次...`)
await new Promise<void>((r) => setTimeout(r, 500))
rr = await tryRelease()
}
if (rr.code === 200 || rr.code === undefined) {
log.ok('发布成功 (state=1)')
// 透明化物理表状态
// form create 走 web 端建表流程, 物理表 schema 在 autoTable 默认 ON 时跟 formData 同步
// 但如果 user 漏 --autoTable 或 web 端校验失败, 物理表可能没建/缺列
try {
const { JnpfClient } = await import('../../core/client.ts')
const { initWebapi: initWebapiDM, loadDataModel } = await import('../../webapi/dataModel.ts')
const dc = await JnpfClient.fromToken()
await initWebapiDM(dc)
// dm 列表拿表信息 (formInfo.tables 反映 formData 推的, 不一定是真实物理表)
const dmList = (await loadDataModel.getDataModelList({ dbLinkId })) as { data?: { list?: { table: string; tableFieldList?: unknown[] }[] } }
const tbl = dmList?.data?.list?.find((t) => t.table === opts.enCode)
if (tbl) {
const colCount = Array.isArray(tbl.tableFieldList) ? tbl.tableFieldList.length : 0
log.info(` ℹ 物理表已建: ${opts.enCode} (${colCount} 列) — form create 走 web 端建表流程, autoTable 自动同步`)
} else {
log.warn(` ⚠ 物理表 ${opts.enCode} 在数据建模列表中未找到, 可能未建 (autoTable 未触发或 web 端跳过)`)
}
} catch (e) {
// dm list 失败不阻塞 (主流程已成功)
log.debug(` (物理表状态查询失败: ${(e as Error).message?.slice(0, 80)})`)
}
} else {
log.error(`发布失败 (code=${rr.code}): ${rr.msg}`)
log.error(
`手动发布: curl -X POST "${c.baseUrl}/api/visualdev/Base/${newId}/Actions/Release" -H "Authorization: ${loadToken()?.token ? 'bearer ' + loadToken()!.token : 'bearer <TOKEN>'}" -H "Content-Type: application/json" -d '{}'`,
)
if (opts.json) printJson({ id: newId, enCode: opts.enCode, type, webType, releaseError: rr.msg })
process.exit(1)
}
=======
log.info(`loadVisualDev.release (formId=${newId}) (v0.7 修)`)
// webapi unwrap() throws on non-200 (webapi/_defhttp_shim.ts:51-56),
// 旧代码无 try/catch, 失败时抛裸栈; 现在 release 失败重试 1 次, 仍失败明确报错 + 手动 curl 提示
// release 失败时重试 1 次 (500ms 间隔), 仍失败 process.exit(1)
// 后端: VisualdevController.java:593 publish() — state=1 + base_visual_release 行 saveOrUpdate (line 673)
// web 端: web/.../api/onlineDev/visualDev.ts:43 release(id) → POST /visualdev/Base/{id}/Actions/Release
const tryRelease = async (): Promise<void> => {
await loadVisualDev.release(newId) // unwrap() throws on non-200 (含 VS003 / VS004 / SYS128)
await loadVisualDev.release(newId) // unwrap() throws on non-200
}
let releaseOk = false
try {
@@ -1383,8 +1331,23 @@ export function buildFormCreateCommand(): Command {
process.exit(1)
}
}
if (!releaseOk) process.exit(1) // 防御性兜底
>>>>>>> Stashed changes
if (!releaseOk) process.exit(1)
// 透明化物理表状态
try {
const { initWebapi: initWebapiDM, loadDataModel } = await import('../../webapi/dataModel.ts')
await initWebapiDM(c)
const dmList = (await loadDataModel.getDataModelList({ dbLinkId })) as { data?: { list?: { table: string; tableFieldList?: unknown[] }[] } }
const tbl = dmList?.data?.list?.find((t) => t.table === opts.enCode)
if (tbl) {
const colCount = Array.isArray(tbl.tableFieldList) ? tbl.tableFieldList.length : 0
log.info(` ℹ 物理表: ${opts.enCode} (${colCount} 列)`)
} else {
log.warn(` ⚠ 物理表 ${opts.enCode} 未在数据建模列表中找到`)
}
} catch {
log.debug(' (物理表状态查询跳过)')
}
} else if (opts.autoRelease && type === 4) {
log.warn('type=4 视图自动跳过 release (会 400)')
}
-4
View File
@@ -64,11 +64,7 @@ function cleanQuery(data: Record<string, unknown> | undefined): Record<string, s
*
* 参考: web/api/request.ts:36-97 transformResponseHook (返回 res.data 完整信封)
* jnpf/.../MsgCode.java SU001 "New created successfully" (i18n)
<<<<<<< Updated upstream
* tds 9 bug 复盘 2026-06-27 (B-1 webapi shim unwrap null TypeError)
=======
* tds 9 bug 复盘 2026-06-27 (b-1 webapi shim unwrap null TypeError)
>>>>>>> Stashed changes
*/
async function unwrap<T>(resp: { code: number; msg?: string; data: T | null }): Promise<T> {
if (resp.code !== 200) {