docs(v0.11+): plan §12-18 - Phase 3-6 详细执行 + 18 webapi 模块统计

§11 补完: 38 commit 完整列表 + REFACTOR-WEBAPI 100% 闭环
§12: Phase 3 .claude/ skill sync (24 skill audit + 5 批子代理)
§13: Phase 4 历史残留清理 (_blindspots.ts/_simplify.ts + 已删资源 + 22 盲点整合)
§14: Phase 5 官方示例验证 (baseline + vitest + 14 webapi 测试 + 10 NEW-CMD 抽样)
§15: Phase 6 web 端改动 (按需触发, 当前无)
§16: P1 长尾 NEW-CMD 清单 (10 个, 按 AI 痛点驱动)
§17: 立即开始指令 (push 38 → Phase 3 → 4 → 5)
§18: 整轮完成判定 (Phase 1+2 ✅, 3-5 待执行)

作者: 2026-06-25 v0.11+ 续写
This commit is contained in:
ssw committed 2026-06-25 15:42:58 +08:00
1 parent 7224156cf0
commit 3185022fdd
1 file changed
+447 -1
+447 -1
View File
@@ -439,4 +439,450 @@ cat /home/ubuntu/ccWorkDir/dacli/docs/v0.11-next-steps-plan.md
- `4669e35` refactor(v0.11+): bigscreen/workflow 6 个 NEW-CMD 改走 webapi 镜像
- `d1284c4` refactor(v0.11+): di 4 个 NEW-CMD 改走 webapi 镜像 (loadDataInterface)
- `27cf29b` refactor(v0.11+): log login/operate 改走 webapi 镜像 (loadLog)
- `72df65e` `3c312d7` `90e938f` docs(v0.11+): 更新 plan
- `cbe6a1e` refactor(v0.11+): monitor 3 子命令改走 webapi 镜像
- `bd11e1b` refactor(v0.11+): schedule 4 子命令 + 新建 onlineUser/flowMonitor webapi
- `7224156` refactor(v0.11+): user 3 子命令 (list/create/delete) 改走 webapi 镜像 (loadUser)
- `e79520c` docs(v0.11+): plan §11 - 完整提交记录 + webapi 化闭环
### 🎯 Phase 2 最终状态: REFACTOR-WEBAPI 100% + NEW-CMD 30+ 完成
**webapi 镜像模块统计** (从 6 → 18, +12):
```
已镜像 (18 模块, 累计消除 ~600 行硬编码):
- visualDev.ts 30 函数 (form/list, info, clone, validate, codegen, ...)
- dataModel.ts 10 函数 (dm/create, drop, list, fields)
- dataSource.ts 11 函数 (datasource/list, info, create, update)
- dict.ts 15 函数 (dict/list, info, data, typeCreate, ...)
- menu.ts 15 函数 (menu/list, info, create, update, delete)
- workflow.ts 14 函数 (workflow/list, info, selector, deploy, ...)
- role.ts 8 函数 (新增: role/list, info, update, selector, authorize)
- log.ts 9 函数 (新增: log/exception, request, login, operate)
- monitor.ts 7 函数 (新增: monitor/server, online, flow)
- schedule.ts 8 函数 (新增: schedule/list, info, create, update, delete)
- message.ts 9 函数 (新增: msg/templateList, noticeList, ...)
- visualdata.ts 8 函数 (新增: di/list, info, test, create, update, delete)
- report.ts 7 函数 (新增: report/list, info, category)
- onlineUser.ts 3 函数 (新增: 在线用户 webapi)
- flowMonitor.ts 3 函数 (新增: 流程监控 webapi)
- user.ts 5 函数 (新增: user/list, create, delete)
- di.ts 5 函数 (di/list 旧版保留兼容)
- _loader.ts + _defhttp_shim.ts (基础设施)
```
**NEW-CMD 完成清单** (30+ 全部交付):
| 父命令 | 新增子命令 | commit |
|--------|------------|--------|
| form | `form update` (高需求, 增量改 schema) | `801a204` |
| log | `log exception`, `log request` | `59a6b4a` |
| di | `di info`, `di test`, `di update`, `di delete` | `59a6b4a` `d1284c4` |
| role | `role update`, `role info`, `role selector` | `6effbcb` `51b1f04` |
| apis | `apis tags`, `apis search --field=` | `6effbcb` `7b8f9b1` |
| workflow | `workflow info`, `workflow update`, `workflow delete` | `5ec47e3` `4669e35` |
| schedule | `schedule update`, `schedule delete` | `6be66cb` `bd11e1b` |
| msg | `msg noticeList`, `msg noticeUpdate`, `msg noticeDelete`, `msg templateList`, `msg templateUpdate`, `msg templateDelete` | `6be66cb` `4505a6f` |
| monitor | `monitor server`, `monitor online`, `monitor flow` | `af9e5a6` `cbe6a1e` |
| bigscreen | `bigscreen update`, `bigscreen delete` | `af9e5a6` `4669e35` |
| dict | `dict typeUpdate`, `dict typeDelete`, `dict dataUpdate`, `dict dataDelete` | `d31fa51` `bed941b` |
| doc | `doc toc`, `doc search` | `5f663eb` |
| user | `user list` (全新), `user create`, `user delete` | `7224156` |
| apis | 修 3 处端点错误 (假 PASS) | `90a8b4e` |
**本地未推送**: `git status` 显示 "ahead of 'origin/feat/dacli-user-commands-v18' by 38 commits", 这是 Phase 1+2 的全部产出, 需在 Phase 3 前先 push.
---
## 12. Phase 3: .claude/** 全过同步 (24 skill audit)
### 12.1 目标
**24 个 skill + 父 CLAUDE.md 全部一致**, 提示信息反映 v0.11+ webapi 镜像架构 + 30+ NEW-CMD, 杜绝 AI 引用已删命令或旧端点.
### 12.2 范围清单 (24 skill + 2 CLAUDE.md)
**dacli/.claude/skills/** (1 个):
- `dacli-ts/SKILL.md` — 主技能 (v0.11+ webapi 架构段已更新, 需补 30+ NEW-CMD 章节)
**父 .claude/skills/** (23 个, 重点):
- `design-jnpf-execute/SKILL.md` — **必改** (主流程, 引用了 extract 脚本, v0.11+ 已删)
- `ssw-h5dev-flow/SKILL.md` — **必改** (H5 主流程, 引用 form create 旧流程)
- `form-development/SKILL.md` — 已加 selector, 需补 form/update 说明
- `form-fix/SKILL.md` — 引用 form/validate + fixcolumndata 已 deprecated, 需迁移
- `workflow-development/SKILL.md` — 已加 selector, 需补 workflow info/update/delete
- `menu-configuration/SKILL.md` — 引用 menu --formId 旧流程, 需同步
- `data-interface/SKILL.md` — 引用 di/list 旧版, 需补 di info/test/update/delete
- `data-management/SKILL.md` — 引用 dm create 旧版, 需同步
- `data-screen/SKILL.md` — bigscreen 是独立子项目, 需 v2 路径修正
- `troubleshooting/SKILL.md` — 历史归档, 保留但加 "v0.11+ 三层防御已覆盖" 提示
- `ssw-test/SKILL.md` — 同步 webapi 模式
- `no-spa-page/SKILL.md` — 检查是否有 dacli 命令引用
- `backend-dev/SKILL.md` — 检查
- `api-test/SKILL.md` — 检查
- `code-generator/SKILL.md` — 引用 form/codegen, 已 webapi 化需同步
- `frontend-dev/SKILL.md` — 检查
- `jnpf-browser-automation/SKILL.md` — 检查
- `platform-mechanism/SKILL.md` — 检查
- `mmx-cli/SKILL.md` — 检查
- `ssw-pack-init/SKILL.md` — 检查
- `ssw-e2e-test/SKILL.md` — 检查
- `webapp-testing/SKILL.md` — 检查
- `basic-standards/SKILL.md` — 检查
**父 CLAUDE.md** (`.claude/CLAUDE.md`):
- v0.10+ 防御体系段已更新, 需补 v0.11+ webapi 架构段
**dacli/CLAUDE.md**:
- 已知盲点段需精简 (22 条盲点已 guard 化, 表格缩小)
### 12.3 子代理 dispatch 协议
**每批 4-5 个 skill, 派 Explore 子代理**, prompt 模板:
```
你是 .claude/ skill 审计子代理.
任务: 审计 .claude/skills/{SKILL}/SKILL.md 是否引用已删命令/旧端点/旧模式.
输入:
- skill 当前内容: /home/ubuntu/ccWorkDir/.claude/skills/{SKILL}/SKILL.md
- v0.11+ dacli 命令清单: /home/ubuntu/ccWorkDir/dacli/docs/cmd-review/_summary.md
- v0.11+ NEW-CMD 表: docs/v0.11-next-steps-plan.md §11
输出: /home/ubuntu/ccWorkDir/dacli/docs/skill-audit/{SKILL}.md
内容:
1. skill 引用了哪些 dacli 命令 (按行号)
2. 哪些命令已 deprecated / 已重构 / 已新增 (NEW-CMD)
3. 需更新的部分 (具体到行号 + 替换建议)
4. 优先级 (P0 必修 / P1 同步 / P2 仅检查)
```
**分批** (每批 5 个 skill):
- Batch F: dacli-ts, design-jnpf-execute, ssw-h5dev-flow, form-development, form-fix
- Batch G: workflow-development, menu-configuration, data-interface, data-management, data-screen
- Batch H: troubleshooting, ssw-test, no-spa-page, backend-dev, api-test
- Batch I: code-generator, frontend-dev, jnpf-browser-automation, platform-mechanism, mmx-cli
- Batch J: ssw-pack-init, ssw-e2e-test, webapp-testing, basic-standards, (parent CLAUDE.md)
### 12.4 主代理执行清单
**P0 必修 (Batch F 主流程)**:
1. `design-jnpf-execute` SKILL.md — 删 extract 脚本引用, 改 webapi 路径
2. `ssw-h5dev-flow` SKILL.md — form create 旧流程 → webapi + 新命令
3. `form-development` SKILL.md — 补 form/update + 30+ NEW-CMD
4. `form-fix` SKILL.md — form/validate/fixcolumndata deprecated 提示
5. `dacli-ts` SKILL.md — 补 30+ NEW-CMD 章节 (form update, log exception, di CRUD, role CRUD, ...)
**P1 同步 (Batch G-H)**:
- 上述其它 13 个 skill, 按需补命令
**P2 仅检查 (Batch I-J)**:
- 不直接涉及 dacli 的 skill, 仅确认无残留引用
**父 CLAUDE.md**:
- 加 v0.11+ webapi 架构段 (1 段, 30 行)
- 简化"已知盲点"表格 (22 条 → 5 条高频)
**dacli/CLAUDE.md**:
- 同步 v0.10+ 防御段 + 加 v0.11+ webapi 段
### 12.5 完成标准
- [ ] 24 skill + 2 CLAUDE.md 全部审计 (产出 `dacli/docs/skill-audit/` 24 个 markdown)
- [ ] P0 必修 5 个 skill 已 commit + push
- [ ] P1 同步 13 个 skill 已 commit + push
- [ ] P2 仅检查 6 个 skill 已确认无残留
---
## 13. Phase 4: 历史残留清理
### 13.1 目标
**删旧 _blindspots.ts / 已 deprecated 文件 / 已删资源引用 / 22 条盲点表整合**, 避免 AI 误读.
### 13.2 清理清单
**A. _blindspots.ts vs _blindspot_guards.ts 重叠**:
- `src/commands/_blindspots.ts` (BS-23/31/32/15/v2 历史快照, 219 行)
- `src/commands/_blindspot_guards.ts` (22 条 guard, 449 行)
- 两份盲点表并存, AI 不知道用哪个
- **行动**: `_blindspots.ts` 内容已全部迁到 `_blindspot_guards.ts` + 实际 webapi 化已修复 BS-51/52/54, 删 `_blindspots.ts` 文件
**B. 已 deprecated 命令审计**:
- `form/_simplify.ts` (BS-51/52 根因, v0.11+ webapi 已消除, 文件 87 行)
- `form/_validate.ts` (功能已并入 `_buildformdata.ts`)
- 其它 `@deprecated` 标记文件
- **行动**: 列出所有 `@deprecated` 文件, 确认无人引用后删除
**C. 已删资源引用**:
- `scripts/extract-all.mjs` (v0.11+ 已删, 350 行)
- `scripts/extract-web-schema.py` (v0.11+ 已删, 220 行)
- `data/field-schemas.json` (v0.11+ 已删)
- `data/web-derived-schemas.json` (v0.11+ 已删)
- 旧 `data/*.json` (4 个, 已删)
- **行动**: grep 全 codebase, 任何引用这些文件的代码/文档全部更新
**D. 22 条盲点表整合**:
- 现在文档有 22 条盲点表 (3 处分写: CLAUDE.md + dacli-ts/SKILL.md + commands/_blindspot_guards.ts)
- **行动**: 三处统一引用 `src/commands/_blindspot_guards.ts` 为唯一源, 文档表格精简为 5 条高频
**E. dacli 自有 schema 残留**:
- `src/schema/FieldBuilder.ts` (已不用, 改 webapi 镜像)
- `src/data/field-defaults.json` (webapi 替代)
- **行动**: grep 引用, 删除未引用
**F. polish-changes-v*.md 历史归档**:
- `dacli/docs/polish-changes-v1.md` ~ `v18.md` (17 个历史归档, 累计 ~5000 行)
- **行动**: 全部移到 `dacli/docs/history/`, 主 docs 目录只保留 source-analysis.md / v0.11-next-steps-plan.md / cmd-review/ / web-patches/ / skill-audit/
**G. 引用 v0.10/v0.11 之前设计**:
- `dacli/doc/architecture.md` v1 决策, 部分已被 v0.11+ 推翻 (webapi 镜像替代 #/ alias)
- **行动**: architecture.md 加 "v0.11+ 更新" 段, 旧决策保留为参考
### 13.3 主代理执行清单
**Step 1 (grep 全面审计)**:
```bash
cd /home/ubuntu/ccWorkDir/dacli
grep -rln "extract-all.mjs\|extract-web-schema.py\|field-schemas.json\|web-derived-schemas.json\|_simplify.ts" --include="*.ts" --include="*.md" .
```
**Step 2 (按 grep 结果批量删/改)**:
- 引用的 .ts 文件 → 改用 webapi
- 引用的 .md 文档 → 更新或归档
**Step 3 (文件删除)**:
```bash
rm src/commands/_blindspots.ts # 219 行, 已迁 guard
rm src/commands/form/_simplify.ts # 87 行, webapi 替代
rm src/commands/form/_validate.ts # 并入 _buildformdata.ts
# 其它 deprecated 按需
```
**Step 4 (盲点表整合)**:
- dacli/CLAUDE.md 表格 22 → 5 条高频
- .claude/skills/dacli-ts/SKILL.md 表格保留 22 条 (权威), 引用 guards.ts
- 父 .claude/CLAUDE.md 表格保留 (用户常读), 引用 guards.ts
**Step 5 (历史归档)**:
```bash
mkdir -p dacli/docs/history
git mv dacli/docs/polish-changes-v*.md dacli/docs/history/
```
### 13.4 完成标准
- [ ] `_blindspots.ts` 已删
- [ ] `_simplify.ts` `_validate.ts` 已删 (或保留 + 强 deprecation warning)
- [ ] grep 全 codebase 无 `extract-all.mjs` `extract-web-schema.py` `field-schemas.json` 引用
- [ ] 22 条盲点表已整合 (1 处权威 + 2 处引用)
- [ ] 17 个 polish-changes-v*.md 已归档到 history/
---
## 14. Phase 5: 官方示例验证 (baseline)
### 14.1 目标
**所有改动用 workSystem (53 form) + developSystem (21 form) 跑通**, 验证 API 0 错 + webapi 镜像工作正常 + NEW-CMD 实际可用.
### 14.2 验证脚本
**API 层**:
```bash
cd /home/ubuntu/ccWorkDir/dacli
SKIP_PLAYWRIGHT=1 bash .claude/skills/dacli-ts/examples/baseline/all.sh
```
**vitest 单测**:
```bash
npx vitest run
```
**webapi 镜像测试** (新增):
```bash
npx tsx tests/test-webapi-loadVisualDev.ts # 30 函数
npx tsx tests/test-webapi-loadDataModel.ts # 10 函数
npx tsx tests/test-webapi-loadDataSource.ts # 11 函数
npx tsx tests/test-webapi-loadDict.ts # 15 函数
npx tsx tests/test-webapi-loadMenu.ts # 15 函数
npx tsx tests/test-webapi-loadWorkflow.ts # 14 函数
npx tsx tests/test-webapi-loadRole.ts # 8 函数 (新增)
npx tsx tests/test-webapi-loadLog.ts # 9 函数 (新增)
npx tsx tests/test-webapi-loadMonitor.ts # 7 函数 (新增)
npx tsx tests/test-webapi-loadSchedule.ts # 8 函数 (新增)
npx tsx tests/test-webapi-loadMessage.ts # 9 函数 (新增)
npx tsx tests/test-webapi-loadVisualdata.ts # 8 函数 (新增)
npx tsx tests/test-webapi-loadReport.ts # 7 函数 (新增)
npx tsx tests/test-webapi-loadUser.ts # 5 函数 (新增)
```
**TS 编译**:
```bash
npx tsc --noEmit
```
### 14.3 真实命令验证 (P0 NEW-CMD 抽样)
```bash
# form update (高需求)
dacli form update <workSystem_form_id> --fullName="测试改名"
# log exception (AI 调试杀手锏)
dacli log exception --lines=10
dacli log exception --keyword="<form_id>"
# di info + test (data interface 闭环)
dacli di info <id>
dacli di test <id> --params='{"key":"value"}'
# role update + selector + authorize (权限闭环)
dacli role update <id> --fullName="测试"
dacli role selector
dacli role authorize <id> --permissionIds='[...]'
# org position + selector
dacli org position list
dacli org selector
# msg notice CRUD
dacli msg noticeList
dacli msg noticeUpdate <id> --title="测试"
# storage CRUD
dacli storage ls /
dacli storage upload --file=./test.txt --path=/test/
# schedule + monitor + bigscreen
dacli schedule list
dacli monitor server
dacli bigscreen update <id> --categoryId=<cat>
```
### 14.4 完成标准
- [ ] `SKIP_PLAYWRIGHT=1 bash baseline/all.sh` 跑通 (114 form × API 0 错)
- [ ] `npx vitest run` 全 PASS (含 28 BS-54 测试 + 16 guard 集成测试)
- [ ] `npx tsc --noEmit` 0 error
- [ ] 14 个 webapi 模块测试全 PASS (待写)
- [ ] P0 NEW-CMD 抽样 10 个全 PASS
---
## 15. Phase 6: web 端改动 (按需触发)
### 15.1 触发条件 (满足任一)
1. **AI 用 selector 找不到 form/report** — selector 数据源缺
2. **AI 创建菜单/webapi 调用 web 端逻辑漏关键字段** (BS-51/52/54 类)
3. **web 端页面逻辑本身有 bug** (用户实测报错)
4. **webapi 镜像无法 1:1 复刻** (Pinia 状态机类, 如 workflow task.ts)
### 15.2 改前必做 (强制流程)
1. 在 `dacli/docs/web-patches/{component}.md` 写"待改清单" (diff 草稿 + 原因)
2. 改 web 源码 (`web/apps/jnpf-web-apps-main/src/views/ssw/**` 或授权范围)
3. **回写 web-patches/{component}.md** (实际 diff + 原因 + 验收步骤 + 升级重应用步骤)
4. commit + push (web 仓库 + dacli docs)
### 15.3 现有 web-patches/ (3 个, 已完成)
- `README.md` — web-patches 体系说明
- `_buildformdata-formUtils.md` — buildFormData 镜像架构记录
- `_visualDev-api-shim.md` — visualDev API shim 记录
### 15.4 当前不需要 web 改动 (Phase 1+2 已覆盖)
所有 23 命令审计发现的问题, webapi 镜像 + NEW-CMD + 端点修复均已覆盖, 无需 web 改动.
Phase 6 仅作为应急通道.
---
## 16. P0 NEW-CMD 剩余 + 执行顺序 (清单)
### 16.1 已完成 (30+ NEW-CMD, §11.4 列出)
所有 P0 NEW-CMD 已 commit, 包含:
- form update, log exception/request, di info/test/update/delete, role update/info/selector,
- workflow info/update/delete, schedule update/delete, msg notice CRUD 6, monitor server,
- bigscreen update/delete, dict typeUpdate/typeDelete/dataUpdate/dataDelete,
- doc toc/search, apis tags/search, user list/create/delete
### 16.2 P1 待评估 (次优先级, 按 AI 痛点驱动)
| 优先级 | 命令 | 触发场景 | 工作量 |
|--------|------|----------|--------|
| P1 | `workflow tasks` `workflow done` `workflow transfer` | 流程任务管理闭环 (AI 操作审批) | 1 周 |
| P1 | `storage upload/download` | 附件调试阻塞 | 3 天 |
| P1 | `datasource test` | 数据源连通性验证 | 1 天 |
| P1 | `datasource sync` | 数据库表结构同步 | 2 天 |
| P1 | `report preview` `report category` | 报表管理闭环 | 1 周 |
| P1 | `portal selector` | 门户选择器 (AI 挂载门户) | 2 天 |
| P1 | `dict typeSelector` | 字典类型选择器 | 1 天 |
| P1 | `bigscreen category` `bigscreen preview` | 大屏分类管理 | 1 周 |
| P1 | `org position create/update/delete` | 岗位 CRUD 闭环 | 3 天 |
| P1 | `msg templateTest` | 消息模板测试发送 | 2 天 |
### 16.3 P2 长尾 (按需)
- `print template/test/preview`
- `integration create/update/delete + dyform/sync`
- `di import/export`
- `monitor sql/job`
- `log clear/export`
---
## 17. 立即开始指令 (给下一轮 AI)
### 17.1 第一步: 上下文恢复
```bash
# 读这个 plan 文件 (从 §11 看进度, 从 §12 看接下来做什么)
cat /home/ubuntu/ccWorkDir/dacli/docs/v0.11-next-steps-plan.md
# 加载相关 skill
# - superpowers:executing-plans
# - superpowers:dispatching-parallel-agents
# - superpowers:verification-before-completion
```
### 17.2 第二步: push 38 commits (前置)
```bash
cd /home/ubuntu/ccWorkDir/dacli
git push origin feat/dacli-user-commands-v18
# 验证: git status 显示 "Your branch is up to date"
```
### 17.3 第三步: Phase 3 启动 (重点)
派 5 个 Explore 子代理审计 Batch F 5 个主流程 skill:
- dacli-ts, design-jnpf-execute, ssw-h5dev-flow, form-development, form-fix
### 17.4 第四步: Phase 4 启动
主代理直接执行清理 (无子代理), 按 §13.3 清单.
### 17.5 第五步: Phase 5 启动
跑 baseline + vitest + 14 个 webapi 测试, 修任何 regression.
### 17.6 第六步: 持续改进
按 §16.2 P1 清单, 每周补 2-3 个 NEW-CMD, 持续累积.
---
## 18. 完成判定 (整轮结束条件)
**Phase 1+2 (已完成 ✅)**:
- [x] 23 个 dacli 父命令审计 (cmd-review/ 24 文件)
- [x] 30+ P0 NEW-CMD 实现 + commit
- [x] 18 个 webapi 模块 + 100+ 函数镜像
- [x] 3 处端点错误修复
- [x] 38 commits 待 push
**Phase 3 (下一步)**:
- [ ] 24 skill 审计完成 (skill-audit/ 24 文件)
- [ ] P0 5 个 skill + P1 13 个 skill 同步
- [ ] 父 CLAUDE.md + dacli/CLAUDE.md 更新
**Phase 4**:
- [ ] `_blindspots.ts` `_simplify.ts` `_validate.ts` 已删
- [ ] grep 全 codebase 无已删资源引用
- [ ] 22 条盲点表整合
- [ ] polish-changes-v*.md 已归档
**Phase 5**:
- [ ] baseline 跑通
- [ ] vitest 跑通
- [ ] webapi 测试全 PASS
- [ ] P0 NEW-CMD 抽样 10 个全 PASS
**Phase 6 (按需)**:
- [ ] web 改动存 docs/web-patches/ (当前无触发)
---
**作者**: 2026-06-25 上一轮 (上下文爆了前) + 续写 §12-18
**状态**: Phase 1+2 完成 (38 commits), Phase 3-5 待执行
**下一步**: push 38 commits → Phase 3 派子代理审计 24 skill → Phase 4 清理 → Phase 5 baseline 验证