docs(v0.11): dacli/docs/web-patches/ 建立 - patch 文档化流程
按 feedback-web-patch-docs.md 规则, 建立 dacli/docs/web-patches/ 目录:
- README.md: 文档化规则 + 当前 patches 状态 + Phase 3 候选 (说明)
- _visualDev-api-shim.md: Phase 1 webapi/visualDev patch (commit d4506fe)
- _buildformdata-formUtils.md: Task 4-10 _buildformdata.ts patch (commit bb3ebaf~fd8ef3b)
Phase 3 候选改造 (formDesign/Form.vue / CreateMenuModal.vue / sysForm/Form.vue)
通过 Phase 1 webapi 间接覆盖 (web 端组件仍调原端点, dacli 用 webapi 调同样端点),
直接抽纯函数价值有限, 暂不执行. 如果未来 BS-48/49/50 反复修, 再启动真正 Phase 3.
升级 web 后, AI 读本目录所有 patch 文档逐个对照, 缺失的重新应用.
Co-Authored-By: Claude <[email protected]>
This commit is contained in:
1 parent
b9729f1855
commit
a0242714ef
3 files changed
+199
No files matched your search
@@ -0,0 +1,64 @@
|
||||
# web-patches — dacli 对 web 端的改造记录
|
||||
|
||||
## 目的
|
||||
|
||||
dacli v0.11+ 镜像架构阶段, 当 dacli 需要复用 web 端 Vue 组件 setup() 中的业务逻辑,
|
||||
我们会修改 web/ 端源码. 但 web/ 端是平台源码 (JNPF 升级时会覆盖), 所以
|
||||
**每个 web 端改动必须在这里单独存档一份 patch**, 升级后能 re-apply.
|
||||
|
||||
## 规则
|
||||
|
||||
1. **改 web 前**先在本目录写 `<component>.md` (含"待改动清单")
|
||||
2. **改 web 后**完善该文档, 含:
|
||||
- 实际 diff (改前 vs 改后)
|
||||
- 改动原因 (为什么 dacli 需要这个改动)
|
||||
- 验收方法 (怎么验证 patch 还在)
|
||||
3. **web 升级后** 重新读本目录所有 patch, 逐个对照, 缺失的重新应用
|
||||
|
||||
不写文档 = 改动 100% 会被升级覆盖丢失.
|
||||
|
||||
## 当前 Patches 状态
|
||||
|
||||
| Patch 文件 | 对应 web 端文件 | 状态 | 备注 |
|
||||
|-----------|----------------|------|------|
|
||||
| `_buildformdata-formUtils.md` | `web/.../helper/formUtils.ts` | ✅ 已应用 (v0.11+ Task 4-10) | 已是纯函数, 无需 patch |
|
||||
| `_ai_prompts-GEN_MODEL_QUESTION.md` | `web/.../views/onlineDev/.../AiCreateModal.vue` | ✅ 已应用 (v0.11+ Task 7-10) | prompt 抽到 `_ai_prompts.ts` |
|
||||
| `_visualDev-api-shim.md` | `web/.../api/onlineDev/visualDev.ts` | ✅ 已应用 (v0.11+ Phase 1) | 通过 `webapi/visualDev.ts` 镜像 |
|
||||
|
||||
## Phase 3 候选 (未来可做)
|
||||
|
||||
按 docs/dacli/v0.11-mirror-refactor.md §3 Phase 3, 候选改造:
|
||||
|
||||
1. `web/.../views/onlineDev/formDesign/Form.vue` 抽 `buildFormSubmitPayload(state)`
|
||||
2. `web/.../views/onlineDev/formDesign/components/CreateMenuModal.vue` 抽 `buildMenuMountPayload(formId, type)`
|
||||
3. `web/.../views/onlineDev/sysForm/Form.vue` 系统表单 submit 逻辑
|
||||
|
||||
**当前状态 (2026-06-25)**: 这 3 个候选都通过 Phase 1 webapi 间接覆盖 (web 端组件
|
||||
仍调原端点 `/visualdev/Base/{id}/Actions/Module` 等, dacli 用 webapi/visualDev 调用
|
||||
同样的端点). 直接抽纯函数的额外价值有限, 暂不执行.
|
||||
|
||||
如果未来 BS-48/49/50 等盲点反复修, 再考虑 Phase 3 真正执行.
|
||||
|
||||
## 验收 / 升级流程
|
||||
|
||||
每次 web 升级 (JNPF 平台 release) 后:
|
||||
|
||||
```bash
|
||||
# 1. 看 patch 清单
|
||||
ls dacli/docs/web-patches/*.md
|
||||
|
||||
# 2. 对每个 patch:
|
||||
# - 读 patch 文档的"实际 diff"
|
||||
# - 对照当前 web/ 端文件: 改动还在吗?
|
||||
# - 不在 → 重新应用, 跑 baseline 验证
|
||||
# - 在 → 文档标 ✅
|
||||
|
||||
# 3. 跑 baseline 验证
|
||||
SKIP_PLAYWRIGHT=1 bash /home/ubuntu/ccWorkDir/dacli/.claude/skills/dacli-ts/examples/baseline/all.sh
|
||||
```
|
||||
|
||||
## 不在本目录的事
|
||||
|
||||
- **删 web 端文件**: 大概率不行 (其他模块依赖), 不在 patch 范围
|
||||
- **改 web 端 bug**: 不属于 dacli 范围, 应报给 JNPF 平台组
|
||||
- **dacli 自有模块改动**: 走 git log, 不在本目录
|
||||
@@ -0,0 +1,71 @@
|
||||
# Patch: _buildformdata-formUtils — v0.11+ buildFormData 直 import
|
||||
|
||||
**状态**: ✅ 已应用 (从 v0.11+ Task 4 起的多次 commit)
|
||||
**生效 commit**: `bb3ebaf` `3a388dc` `5473fd4` `d9505ae` `fd8ef3b`
|
||||
**对应 web 端文件**: `web/apps/jnpf-web-apps-main/src/components/FormGenerator/src/helper/formUtils.ts`
|
||||
|
||||
## 改动原因
|
||||
|
||||
dacli form create 之前复刻了 web 端 `buildFormData()` 函数, 但漏 formId / renderKey /
|
||||
isSubTable / options 等关键字段 → 浏览器层渲染空 (BS-51/52/54/55 反复修).
|
||||
|
||||
v0.11+ Task 4-10: 用 `dacli/src/commands/form/_buildformdata.ts` 直接 dynamic import
|
||||
web 端 `formUtils.ts` 原版 `buildFormData + buildFields`, 0 复刻.
|
||||
|
||||
## 实际改动
|
||||
|
||||
### 新增 dacli 端
|
||||
|
||||
| 文件 | 作用 |
|
||||
|------|------|
|
||||
| `dacli/src/commands/form/_buildformdata.ts` | 读 formUtils.ts → 替换 import → 写 tmp → dynamic import |
|
||||
| `dacli/src/commands/form/_ai.ts` | 双路径 (ANTHROPIC_* env 直连 / JNPF backend) |
|
||||
| `dacli/src/commands/form/_ai_prompts.ts` | 抽 JNPF 原版 prompt (GEN_MODEL_QUESTION 等) |
|
||||
| `dacli/data/buildformdata-contract.md` | buildFormData 契约清单 (16+50+23 keys) |
|
||||
|
||||
### web 端零改动
|
||||
|
||||
web/apps/jnpf-web-apps-main/src/components/FormGenerator/src/helper/formUtils.ts **保持原样**.
|
||||
|
||||
## import 替换规则
|
||||
|
||||
```ts
|
||||
// _buildformdata.ts 应用的 3 条替换
|
||||
src = src
|
||||
.replace(/from\s+['"]#\/(.+?)['"]/g, (_, p) => `from '${WEB_SRC}/${p}'`)
|
||||
.replace(/from\s+['"]@jnpf\/utils['"]/g, `from '${JNPF_UTILS_UUID}'`)
|
||||
.replace(/import\s*\{\s*cloneDeep\s*\}\s*from\s+['"]lodash-es['"];?/g,
|
||||
`const cloneDeep = (x) => structuredClone(x);`);
|
||||
```
|
||||
|
||||
## 验收方法
|
||||
|
||||
```bash
|
||||
# 1. 跑 AI 建表端到端
|
||||
dacli form create --ai "建一个员工表, 含姓名/年龄" --autoRelease
|
||||
# 期望: 成功, state=1, 浏览器能渲染
|
||||
|
||||
# 2. 跑 AI JSON 直入
|
||||
dacli form create --ai-json '[{"vmodel":"f_name","label":"姓名","jnpfKey":"input"}]' \
|
||||
--fullName=test --enCode=test_v011_aijson --autoRelease
|
||||
# 期望: 成功, 无 LLM 调用
|
||||
|
||||
# 3. 跑视觉测试
|
||||
npx tsx dacli/tests/test-import-buildformdata.ts
|
||||
# 期望: 成功 import buildFormData + buildFields
|
||||
```
|
||||
|
||||
## web 升级后如何重应用
|
||||
|
||||
web 升级如果:
|
||||
- **formUtils.ts buildFormData 签名没变**: 不需任何操作
|
||||
- **buildFormData 加了新字段** (web 自动透传, dacli 自动受益):
|
||||
- 跑 AI 建表, 看 form 浏览器渲染是否完整
|
||||
- 如有字段缺, 跑 baseline 验证
|
||||
- **buildFormData 签名大变** (破坏性): 升级 _buildformdata.ts 替换规则, 加新 import 处理
|
||||
|
||||
## 不需要做的事
|
||||
|
||||
- ❌ 不要重写 buildFormData
|
||||
- ❌ 不要在 dacli 端维护 schema defaults (web 端是唯一权威)
|
||||
- ❌ 不要修改 web/.../helper/formUtils.ts
|
||||
@@ -0,0 +1,64 @@
|
||||
# Patch: _visualDev-api-shim — v0.11+ Phase 1 webapi 镜像
|
||||
|
||||
**状态**: ✅ 已应用
|
||||
**生效 commit**: `d4506fe` (2026-06-25)
|
||||
**对应 web 端文件**: `web/apps/jnpf-web-apps-main/src/api/onlineDev/visualDev.ts`
|
||||
|
||||
## 改动原因
|
||||
|
||||
dacli 之前用自有 `JnpfClient.postJson('/visualdev/Base', ...)` 调用 web 端 30+ 函数,
|
||||
每次 JNPF 升级 web 端加新参数/字段, dacli 都漏. 6 周修 50+ 盲点根因都是"复刻漂移".
|
||||
|
||||
v0.11+ Phase 1: 用 `dacli/src/webapi/_loader.ts` 直接 dynamic import
|
||||
`web/.../api/onlineDev/visualDev.ts` 原版, dacli 调 web 端函数 → 0 漂移.
|
||||
|
||||
## 实际改动
|
||||
|
||||
### 新增 dacli 端 (3 文件)
|
||||
|
||||
| 文件 | 作用 |
|
||||
|------|------|
|
||||
| `dacli/src/webapi/_loader.ts` | 读 web 源 → 替换 import → 写 tmp → dynamic import |
|
||||
| `dacli/src/webapi/_defhttp_shim.ts` | 用 JnpfClient 实现 web 端 defHttp (get/post/put/delete) |
|
||||
| `dacli/src/webapi/visualDev.ts` | 30+ 函数 Proxy re-export |
|
||||
|
||||
### web 端零改动
|
||||
|
||||
web/apps/jnpf-web-apps-main/src/api/onlineDev/visualDev.ts **保持原样**.
|
||||
通过 `_loader.ts` 的 import 替换:
|
||||
- `from '#/api/request'` → `from '<_defhttp_shim path>'`
|
||||
- 其他保持不变 (visualDev.ts 只 import defHttp)
|
||||
|
||||
## 验收方法
|
||||
|
||||
```bash
|
||||
# 1. 跑视觉端到端测试
|
||||
npx tsx dacli/tests/test-webapi-visualdev.ts
|
||||
|
||||
# 期望输出:
|
||||
# ✓ 11 个核心函数可用
|
||||
# ✓ getVisualDevList 返回数据
|
||||
# ✓ getInfo 返回数据
|
||||
|
||||
# 2. 跑 baseline (API 0 错)
|
||||
SKIP_PLAYWRIGHT=1 bash dacli/.claude/skills/dacli-ts/examples/baseline/all.sh
|
||||
|
||||
# 3. 跑 dacli form list (已切换样板命令)
|
||||
dacli form list --limit=3
|
||||
# 期望: 输出与改 webapi 前完全一致
|
||||
```
|
||||
|
||||
## web 升级后如何重应用
|
||||
|
||||
web 升级如果:
|
||||
- **visualDev.ts API 没变**: 不需任何操作, `_loader.ts` 会自动 import 最新版本
|
||||
- **visualDev.ts API 变了** (新增/删除/重命名函数):
|
||||
- 跑 `npx tsx dacli/tests/test-webapi-visualdev.ts`, 看哪个函数不在了
|
||||
- dacli 端命令按需更新 import (一般不需要动)
|
||||
- 跑 baseline 验证
|
||||
|
||||
## 不需要做的事
|
||||
|
||||
- ❌ 不要修改 web/apps/jnpf-web-apps-main/src/api/onlineDev/visualDev.ts
|
||||
- ❌ 不要重写 _loader.ts / _defhttp_shim.ts
|
||||
- ❌ 不要把 `from '#/api/request'` 替换写死 (让 _loader.ts 处理)
|
||||
Reference in new issue
Block a user