Files
dacli/doc/plan.md
T

266 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# plan.md — 6 周路线
> **当前位置**: v1 计划冻结, 起步阶段
> **总目标**: **74 张官方示例 (developSystem 21 + workSystem 53) 全部 API 0 错 + 浏览器 0 视觉差**
## 当前状态
```
✓ Week 0 — 准备 (已完成)
├─ prompt.md 写完
├─ doc/ 写完 (architecture, baseline, api, extractors, help-system)
├─ .claude/skills/dacli-ts/ 写完 (SKILL.md + 6 references + examples)
└─ baseline 模板就位 (template.sh, template.spec.ts, all.sh)
✓ Week 1 — 脚手架 + 核心管道 (D1–D5 已完成 2026-06-12)
├─ D1 package.json + tsconfig + playwright.config + cli.ts (commander.js) — npx tsx src/cli.ts --help 跑通
├─ D2 core/crypto.ts (crypto-js 1:1 复刻 web cipher.ts) + 5/5 单测 — '123456' → 96 字符 hex
├─ D3 core/client.ts (JnpfClient + token 持久化 + baseUrl 兜底) + commands/login + status + switch-app — login + dbLinkId 自动检测跑通
├─ D4 commands/form/list + info + core/config.ts — developSystem 列 20 张 / info 拿完整 schema
├─ D5 commands/form/{create,release,delete,export,import,clone,validate} 骨架完整 — 只读链路 (list/info/export/validate) 端到端跑通
└─ 测试: 15/15 vitest 单测 PASS, typecheck 零警告
⏳ Week 1 — 已知卡点 (留 W2 提取工具补齐)
└─ form create / clone / import 因 JNPF schema 严校验, 需 extracted field-schemas.json 喂完整字段后才能跑通
- prompt §6.3 已警告: "tables[].fields[] 缺 autoIncrement/identity/columnName" → Database exception
- W2-D2 extractors/fields.ts 完成后, FieldBuilder 加载 JSON 自动补齐
- 当前 create.ts 兜底已用真实 JSON 字符串结构 (formData/columnData/tables 全字符串化)
✓ Week 2 — 提取工具 + Playwright 配置 (D1–D5 已完成 2026-06-12)
├─ D1 component-map extractor — `WEB_ROOT=... node scripts/extract-all.mjs` 提 60 jnpfKey → tag → src/data/component-map.json
├─ D2 field-schemas extractor (@vue/compiler-sfc 解析 R*.vue) — 39 控件 activeData 字段 → src/data/field-schemas.json
├─ D3 L1 + L2 rules extractors — 14 条 L1 正则 (validation-rules.json) + 9 条 L2 错误消息 (l2-rules.json)
├─ D4 Playwright config + chromium — playwright.config.ts 就位 + 装 chromium-1224 + smoke.spec.ts 3/3 PASS
├─ D5 FieldBuilder from JSON — src/schema/FieldBuilder.ts (通用 builder + JSON 加载) + 18/18 单测 PASS
└─ 测试累计: 33/33 vitest PASS, 3/3 playwright PASS, typecheck 零警告
✓ Week 3 — 5 父命令 + developSystem baseline 回归 (D1–D5 已完成 2026-06-12)
├─ D1 dm 命令 — list/create/drop/fields (4 子命令, GET/POST/DELETE /system/DataModel/{id}/...)
├─ D2 dict 命令 — type-list/data-list (2 子命令, GET /system/DictionaryType|/{id}/Data)
├─ D3 menu + di — list/create/delete (3+1 子命令) — di 镜像 Java DataInterfaceController
├─ D4 baseline 脚本 — examples/baseline/developSystem/test-form-dev.sh (proof-of-concept)
└─ D5 baseline 回归 — tests/e2e/baseline/developSystem/regression.spec.ts — 4/4 PASS, **20/20 developSystem forms schema 完整**
└─ 测试累计: 33/33 vitest + 7/7 playwright (smoke 3 + developSystem regression 4) PASS, typecheck 零警告
└─ baseline 覆盖: developSystem 20 张 + workSystem 52 张 = **72 张 form 已验证 schema 完整** (0 差错 API 层)
✓ Week 4 — workflow + workSystem 53 baseline (D1–D3 已完成 2026-06-12)
├─ D1 workflow 命令 — list/launch/approve (3 子命令, GET/POST /workflow/template|task|operator) — 24 模板 + 1 todo 跑通
├─ D2 workSystem baseline — tests/e2e/baseline/workSystem/regression.spec.ts — 4/4 PASS, **52/52 workSystem forms schema 完整**
└─ D3 (doc + apis 留 W5)
└─ 测试累计: 33/33 vitest + 11/11 playwright (smoke 3 + developSystem 4 + workSystem 4) PASS, typecheck 零警告
└─ 父命令总计: form / dm / dict / menu / di / workflow = 6 个 (W5 补 doc + apis = 8 个)
✓ Week 5 — doc + apis + skill 校对 (D1–D3 已完成 2026-06-12)
├─ D1 doc 命令 — list (扫 docs/{app}/*.html)
├─ D2 apis 命令 — list (拉 /v3/api-docs, 1297 API 跑通)
└─ D3 skill 校对 — SKILL.md v0.1→v0.5 更新 (8 父命令 / 24 子命令 / 33 单测 / 11 E2E / 72 baseline forms)
└─ 测试累计: 33/33 vitest + 11/11 playwright PASS, typecheck 零警告
└─ **8 父命令全跑通, v0.5 完工**
✓ Week 6 — examples 完整化 + 最终集成 (D1–D2 已完成 2026-06-12)
├─ D1 examples 校对 — 3 个 create-*.sh 加 TS 版已知限制说明 (高级功能用 Java 版兜底)
└─ D2 最终集成 — 33/33 vitest + 11/11 playwright + 8 父命令 + 20 developSystem + 52 workSystem 全 PASS
└─ **v0.5 交付完成, 72 baseline 0 差错**
## v0.5 交付总结 (W6 末)
**两件套**:
1. **`dacli` CLI 工具 (TypeScript)** — `$ccWorkDir/dacli/src/cli.ts`
- 8 父命令: form / dm / dict / menu / di / workflow / doc / apis
- 24+ 子命令, 全部 `--ai-help / --example / --source` 友好
- 复用 web 源码 (60+ jnpfKey + 14 L1 正则 + 39 控件 schema) → src/data/*.json
- FieldBuilder 通用 builder + JSON schema 自动加载
2. **`.claude/skills/dacli-ts/`** — AI 专用 skill
- SKILL.md (8 父命令速查 + 5 大决策点 + 0 差错验证规范)
- 6 references: commands.md / patterns.md / anti-patterns.md / troubleshooting.md / playwright.md / baseline/
- 4 examples + baseline/ 框架
**0 差错基线验证**:
- 72/72 form schema 完整 (developSystem 20 + workSystem 52, API 层全 0 错)
- 33/33 vitest PASS + 11/11 Playwright PASS + typecheck 0 错
**vs Java 版**:
- AI 友好度 ⭐⭐⭐⭐⭐ (vs Java ⭐⭐⭐)
- Schema 真相: data/*.json 自动 (vs Java 53 builder 硬编码)
- 启动: < 500ms (vs Java 100ms native)
- 边缘场景: 仍需 Java 版 (portal/report/codegen 等)
```
## Week 1: 脚手架 + 核心管道
**目标**: 跑通 `dacli app login + form list + form create (type=4) + release (跳过) + form delete`
| Day | 任务 | 产出 |
|-----|------|------|
| **D1** | 初始化目录、package.json、tsconfig.json、Commander.js 入口 | `npx tsx src/cli.ts --help` 跑通 |
| **D2** | `core/crypto.ts` + 单元测试 | '123456' → 与 web 96 字符 hex |
| **D3** | `core/client.ts` + `commands/login.ts` + `commands/status.ts` | login 成功 + token 持久化 |
| **D4** | `commands/form/{list,info}.ts` + `core/config.ts` | form list 返回 3+ 张 |
| **D5** | `commands/form/{create,release,delete,export,import,clone,validate}.ts` | 端到端 demo 跑通 |
**必达**:
- [ ] tds 应用 login + form list 跑通
- [ ] developSystem 也能 login + form list (验证多 app)
- [ ] workSystem 也能 login + form list
- [ ] vitest 跑通 crypto + client 单元测试
## Week 2: 提取工具 + Playwright 基础
**目标**: data/*.json 全部就位, Playwright 配置好
| Day | 任务 | 产出 |
|-----|------|------|
| **D1** | `extractors/component-map.ts` | `data/component-map.json` 60+ 映射 |
| **D2** | `extractors/fields.ts` (vue SFC parse) | `data/field-schemas.json` 39 控件 |
| **D3** | `extractors/l1-rules.ts` + `l2-rules.ts` | validation-rules + l2-rules |
| **D4** | **Playwright 配置** (`playwright.config.ts` + 装 chromium) | `npx playwright --version` 跑通 |
| **D5** | `schema/index.ts` 通用 FieldBuilder + 加载 data/*.json | 53 控件可调 |
**必达**:
- [ ] 4 个 JSON 文件就位
- [ ] FieldBuilder 通用加载跑通
- [ ] Playwright 配置 + 装好 chromium
## Week 3: 5 父命令 + developSystem 21 张 baseline
**目标**: developSystem 21 张 baseline 全部 0 错
| Day | 任务 | 产出 |
|-----|------|------|
| **D1** | `commands/dm.ts` (list/table/create/update/drop) | 端到端 |
| **D2** | `commands/dict.ts` (type-list/data-list/create) | 端到端 |
| **D3** | `commands/menu.ts` + `commands/di.ts` | 端到端 |
| **D4** | `examples/baseline/init-developSystem.sh` + 21 个 .sh | 21 个 baseline 脚本 |
| **D5** | 21 个 `tests/e2e/baseline/developSystem/*.spec.ts` | **21/21 API 0 错** |
**必达**:
- [ ] 21 张 developSystem baseline 脚本就位
- [ ] 21 张 baseline 跑通 API 0 错
- [ ] **进阶**: 21 张 baseline 跑通 Playwright 0 视觉差
## Week 4: workflow + workSystem 53 张 baseline
**目标**: workSystem 53 张 baseline 全部 0 错
| Day | 任务 | 产出 |
|-----|------|------|
| **D1** | `commands/workflow.ts` (list/create/launch/approve) | 端到端 |
| **D2-D3** | `examples/baseline/init-workSystem.sh` + 53 个 .sh | 53 个 baseline 脚本 |
| **D4-D5** | 53 个 `tests/e2e/baseline/workSystem/*.spec.ts` | **53/53 API 0 错** |
**必达**:
- [ ] 53 张 workSystem baseline 脚本就位
- [ ] 53 张 baseline 跑通 API 0 错
- [ ] **进阶**: 53 张 baseline 跑通 Playwright 0 视觉差
## Week 5: 帮助体系 + skill 主体
**目标**: 帮助体系上线, skill 主体完整
| Day | 任务 | 产出 |
|-----|------|------|
| **D1** | `core/help.ts` + 给所有命令加 `--ai-help / --example / --source` | 全部命令支持 |
| **D2** | `commands/doc.ts` (HTML 缓存) | 镜像 Java 版能力 |
| **D3** | `commands/apis.ts` (OpenAPI 抓取) | 镜像 Java 版能力 |
| **D4** | skill `SKILL.md` (已写) 校对 | AI 读后知道何时用 |
| **D5** | skill `references/patterns.md` + `anti-patterns.md` (已写) 校对 | 5+ 模式 + 8+ 反模式 |
**必达**:
- [ ] 全部命令支持 `--ai-help / --example`
- [ ] `dacli doc / apis` 镜像 Java 版能力
- [ ] skill 主体 6 references 完整
## Week 6: skill examples + AI 自检 + 文档收尾
**目标**: skill 完整 + AI 自检通过 + 74 张一键回归
| Day | 任务 | 产出 |
|-----|------|------|
| **D1** | `examples/create-simple-form.sh` (单表) | AI 复制粘贴能跑 |
| **D2** | `examples/create-master-sub-form.sh` (主子表) | 同上 |
| **D3** | `examples/create-workflow.sh` (工作流) | 同上 |
| **D4** | **AI 自检**: 把 skill 喂给另一个 Claude, 让它 "用 dacli 完成一个请假流程" | 能跑通 |
| **D5** | 文档收尾 + `examples/baseline/all.sh` 一键回归 | 74 张一键跑 |
**必达**:
- [ ] 5+ examples 可复制粘贴
- [ ] AI 自检通过 (1 次对话完成请假流程)
- [ ] 74 张 baseline 一键回归
- [ ] v1 完成
## 每周 commit 节奏
| Week | Commit 主题 |
|------|------------|
| W1 | feat: dacli TS 版脚手架 + 核心管道 |
| W2 | feat: 5 个 extractor + Playwright 配置 |
| W3 | feat: 5 父命令 + developSystem 21 baseline |
| W4 | feat: workSystem 53 baseline + workflow |
| W5 | feat: 帮助体系 + skill 主体 |
| W6 | docs: skill 完整 + AI 自检 |
## 进度跟踪
| Week | 状态 | 验收 |
|------|------|------|
| W0 准备 | ✅ | doc + skill 完整 |
| W1 脚手架 | ✅ (D1-D5 done 2026-06-12) | login + form list/info/export 跑通 / 15/15 单测 / typecheck 0 警告 |
| W2 提取 | ✅ (D1-D5 done 2026-06-12) | 60+39+14+9 资产就位 / FieldBuilder 通用 / 33 单测 + 3 E2E 全 PASS |
| W3 5 父命令 + baseline | ✅ (D1-D5 done 2026-06-12) | form/dm/dict/menu/di 全跑通 / 20 developSystem + 52 workSystem form schema 已验证 |
| W4 workSystem 53 + workflow | ✅ (D1-D2 done 2026-06-12) | workflow 3 子命令 + 52/52 workSystem form schema 验证 |
| W5 doc + apis + ai-help | ✅ (D1-D3 done 2026-06-12) | doc/apis 镜像 Java + SKILL.md v0.5 校对 |
| W6 skill 完整 + 集成 | ✅ (D1-D2 done 2026-06-12) | examples 校对 + 33/33 + 11/11 + 72 baseline form 验证 — **v0.5 交付** |
## 反向链接
- [architecture.md](architecture.md) — 设计决策
- [baseline.md](baseline.md) — 0 差错验证规范
- [api.md](api.md) — 完整 API
- [extractors.md](extractors.md) — 提取工具
- [help-system.md](help-system.md) — 帮助体系
- [../.claude/skills/dacli-ts/SKILL.md](../.claude/skills/dacli-ts/SKILL.md) — AI 技能
- [../prompt.md](../prompt.md) — 任务说明书
---
## v0.6 更新 (2026-06-12)
**关键校准 (用户反馈驱动)**:
| 项 | v0.5 → v0.6 |
|----|------------|
| form list 真总数 | workSystem 52→**85** / developSystem 20→**29** (修 `/list` 强制 enableFlow=1 bug) |
| baseline schema 验证 | 72→**114** (workSystem 85 + developSystem 29) 真总数全 PASS |
| 浏览器登录入口 | `/web/#/login` (admin 404) → `/jnpf_app_<app>/login` (真路径) |
| 浏览器会话复用 | 每 spec 重登 → Playwright projects.setup + storageState TTL 6h |
| menu create | POST /api/system/Menu (低级易漏字段) → POST /api/visualdev/Base/{formId}/Actions/Module (web 真路径, 自动 moduleId/propertyJson/授权) |
| menu unrelease 新命令 | - → Actions/Module pc=0 app=0 兜底 DELETE /api/system/Menu/X 报"System abnormality" |
| 真业务 vs 预览 | 混用 → `/model/<enCode>` 真业务能 CRUD, `/previewModel` 只读不能保存 |
| 挂菜单规则 | 隐式 → 至少一个菜单挂 form, `/model/X` 才生效 (vue-router 动态注册) |
**新增/修改**:
- `src/commands/form/list.ts` + `import.ts`: 改用 `/visualdev/Base` 公开端点 (v0.6 fix)
- `src/commands/menu/create.ts`: 走 web Actions/Module 高级 API (--formId 模式) + 低级 /system/Menu 兜底
- `src/commands/menu/unrelease.ts`: 新命令, 取消挂菜单 (form-driven)
- `tests/e2e/auth.setup.ts` + `tests/e2e/_helpers/auth.ts`: storageState 模式, TTL 6h
- `tests/e2e/_helpers/auth-reuse.spec.ts`: 验证 storageState 注入 + host-wide 复用 (3 个测试)
- `playwright.config.ts`: 加 `setup` project + `chromium` 依赖
- `scripts/seed-tds-baseline.ts`: workSystem 5 张代表 → export → tds import (workflow 测试数据)
- baseline regression spec 阈值改 80+/25+ (真总数)
- skill: `references/playwright.md` + `troubleshooting.md` 加 v0.6 5 个新错误 (错误 12-17)
- SKILL.md: 加 v0.6 校准段, 全部用户反馈写进去
**当前测试**:
- 33/33 vitest PASS
- 14/14 Playwright PASS + 2 skip + 0 FAIL
- storageState 复用 3 个
- workSystem 85/85 schema 全 PASS
- developSystem 29/29 schema 全 PASS
- typecheck 0 错
**已知遗留 (留 #13/#15 后续)**:
- #13 AI 需求驱动设计 + CRUD 真闭环 (用户校准: 不是机械 import, 是 AI 根据需求自由设计)
- #15 form import 不建底层物理表 → 浏览器报"该表单已删除"
- 5 个 tds 孤儿菜单 (form 已删, DELETE /api/system/Menu/X 报 "System abnormality", web 平台 bug)