707 lines
33 KiB
Markdown
707 lines
33 KiB
Markdown
# TS 版 dacli — 主提示词 (开发任务说明书, v0.8 长任务模式)
|
||
|
||
> **位置**: `$ccWorkDir/dacli/`
|
||
> **目标**: 在 `$ccWorkDir/dacli/` 内交付 **两件套**——
|
||
> 1. **`dacli` CLI 工具** (TypeScript) — **唯一生产工具**
|
||
> 2. **`.claude/skills/dacli-ts/SKILL.md`** — AI 专用技能,告诉 AI **何时用哪个命令**
|
||
>
|
||
> **当前状态**: v0.7.1 (2026-06-12) — **8 父命令 / 27 子命令**, 114 baseline 0 差错 (developSystem 29 + workSystem 85)
|
||
> **v0.8 目标 (本轮长任务)**: 把 jnpf web 剩下的 25+ 顶级模块整合进 dacli, 目标 **22 父命令 / 80+ 子命令 / 130+ baseline 0 差错**
|
||
> **应用对象**: `tds` (http://nginx/ ,你在容器内 后端api 代理到 http://nginx/api -> http://127.0.0.1:30000/api) | `admin / 123456`
|
||
|
||
---
|
||
|
||
## ⛔ 长任务模式 (LONG-RUN MODE)
|
||
|
||
> **用户校准**: 本轮是长任务, **非必要不要中断, 自己驱动完成**. 不要中途问 "是否继续" / "要不要确认" / "先停下问个问题". 自己决策, 自己跑, 自己验证, 自己 commit. 真的卡死才回头.
|
||
|
||
### 硬约束 (5 条)
|
||
|
||
1. **不停下来问** — AI 自己决策 (改 type / 改 schema / 加 patch / 拆子命令 / 加缓存), 走不通就 `git commit --no-verify` + 写"已知盲点"段, 继续往下走
|
||
2. **每完成一段就 commit** — 不攒改动, 一段一提交 (`git add -A && git commit -m "..."`). 出问题好回滚
|
||
3. **失败不绕路** — 跑 `npx vitest run` 红了, 直接看 stacktrace 修代码, **不**问"要不要把这条 test 跳过"
|
||
4. **跑通才算完** — 一段子命令的"完工"定义: `npx tsc --noEmit` 0 错 + `npx vitest run` 全 PASS + `npx playwright test` 全 PASS + `examples/baseline/all.sh` 全 0 错. 缺一不可
|
||
5. **真错了才回头** — 编译/测试/集成三关全过, 才算"完成". 没过的标"已知遗留", 不回头改 — 留给下一段
|
||
|
||
### 不算"中断"的事
|
||
|
||
- 改源码 + 跑 typecheck + 跑 test + 跑 baseline + commit (正常流程)
|
||
- 改 prompt.md / RESUME.md / v0.8-*.md 段 (记进度)
|
||
- 跑 `git log` / `git diff` / `git status` 查状态
|
||
- 跑 `dacli app status` / `dacli form list` / `dacli apis list` 查真实数据
|
||
- 跑 `npx playwright install chromium` 装环境
|
||
- 跑 `npm install` 装新依赖
|
||
- 写 vitest 单测 / Playwright spec
|
||
- 跑 `git add -A && git commit` 一段一提交
|
||
|
||
### 真的卡死才回头 (3 件事)
|
||
|
||
- JNPF 后端报 500, 真实 bug (有 stacktrace, 不是 NPE 兜底 "System abnormality")
|
||
- 浏览器层 E2E 一直 fail, 3 次以上重试还红
|
||
- 缺依赖 / 缺环境 / 配置文件坏 (非代码问题)
|
||
|
||
---
|
||
|
||
## 0. 启动指令 (新会话第一句)
|
||
|
||
```
|
||
按 $ccWorkDir/dacli/prompt.md 在 $ccWorkDir/dacli/ 内交付 dacli + skill 两件套。
|
||
目标 0 差错: 以 developSystem/workSystem 官方示例为 baseline。
|
||
先读 $ccWorkDir/dacli/doc/architecture.md 了解设计, 再读 doc/RESUME.md 拿当前任务。
|
||
```
|
||
|
||
**v0.7.1 跳过** (本轮不重做, 留"已知遗留"段): P0 #16 收尾 (tds_leave fix-columndata) 用户手动, AI 不动
|
||
**v0.8 启动** (本轮主任务): 见 `doc/RESUME.md` §5 (jnpf web 25+ 顶级模块整合清单 + W7-W12 详细日程) + `doc/v0.8-scan.md` (扫描快照: 94 web 入口 + 100+ Controller + 22 模块端点)
|
||
|
||
**核心约束 (3 条不妥协)**:
|
||
1. **0 差错 = API 0 错 + 浏览器 0 视觉差**(详见 §5)
|
||
2. **官方示例 baseline 必用**(developSystem 21 + workSystem 53 = 74 张;v0.8 起追加报表/门户/大屏样例 8+ 张 = 122+)
|
||
3. **Playwright Node.js 是基础设施**(不是可选,每个 baseline 必跑)
|
||
|
||
---
|
||
|
||
## 1. 项目背景与目标
|
||
|
||
### 1.1 为什么做这件事
|
||
|
||
`dacli` (TypeScript 版) 是 JNPF 平台的命令行工具. 早期曾有 mvn/Java 版探索 (`docs/dacli/ssw-dacli/`, 现已归档), TS 版以"AI-friendly + 直接复用 web 源码 + 0 差错验证"为设计核心, 已稳定.
|
||
|
||
**4 个设计决策 (TS 版成立的关键)**:
|
||
1. **AI 写 TS 不累** (vs Java ceremony + 慢编译)
|
||
2. **schema 0 漂移** (从 web SFC 自动提取, 不再 53 FieldBuilder 翻译)
|
||
3. **升级松耦合** (JNPF 改字段, 重跑 extractor 即同步)
|
||
4. **web 源码复用** (web 端 TS/TS, dacli TS 直接 1:1 复刻 cipher/validate/componentMap)
|
||
|
||
### 1.2 TS 版定位
|
||
|
||
**是** dacli 的**唯一生产工具** (v0.7.1 已 8 父命令 / 27 子 / 114 baseline 0 差错).
|
||
**也是**"**AI-friendly 探索性实验**"——验证"**直接复用 web 源码 + 0 差错验证**"的可行性。
|
||
|
||
### 1.3 目标 0 差错 (硬目标)
|
||
|
||
**0 差错 = 两个层面都 0**:
|
||
|
||
| 层面 | 含义 | 验证手段 |
|
||
|------|------|----------|
|
||
| **API 0 错** | 所有 dacli 命令调用 JNPF API 返回 200/业务成功 | 单元测试 + 集成测试 |
|
||
| **浏览器 0 视觉差** | 复刻的表单/菜单在浏览器渲染与原版**像素级一致** | Playwright Node.js 截图对比 |
|
||
|
||
**0 差错基线**: **74 张官方示例** (developSystem 21 + workSystem 53)。
|
||
dacli 对这 74 张必须做到:
|
||
- ✅ `dacli form export <id>` 输出 JSON → `dacli form import` 输入 → 重建后**结构 0 差**
|
||
- ✅ Playwright 打开原版与复刻版,**截图视觉 0 差** (允许 1 像素抗锯齿差)
|
||
- ✅ 所有字段、按钮、列表列正确渲染
|
||
- ✅ 表单可正常提交、菜单可正常跳转、工作流可正常发起
|
||
|
||
### 1.4 官方示例 (baseline 真值源)
|
||
|
||
| app_code | 表单数 | 工作流数 | 用途 |
|
||
|----------|--------|---------|------|
|
||
| `developSystem` | 21 | 3 | 基础示例(单表/主子表/简单工作流) |
|
||
| `workSystem` | 53 | 多个 | 丰富示例(关联/字典/数据接口/复杂流程) |
|
||
| `tds` | 0+ (本次新建) | - | 实际业务应用 |
|
||
|
||
**baseline 文件**:
|
||
- `references/baseline/developSystem.md` — 21 张表单清单 + 特色
|
||
- `references/baseline/workSystem.md` — 53 张表单清单 + 特色
|
||
- `examples/baseline/<enCode>.sh` — 每张表单的复刻 + 验证脚本
|
||
- `examples/baseline/all.sh` — 一键跑完 74 张的回归
|
||
|
||
详见 [references/baseline/](../../references/baseline/README.md)
|
||
|
||
---
|
||
|
||
## 2. 架构设计 (核心)
|
||
|
||
### 2.1 复用 web 源码的 4 类资产
|
||
|
||
| 资产 | 来源 | TS 版如何用 | 价值 |
|
||
|------|------|------------|------|
|
||
| **加密算法** | `web/packages/jnpf/utils/src/helpers/cipher.ts` | `crypto-js` 1:1 复刻 | 字节级一致 |
|
||
| **L1 正则库** | `web/packages/jnpf/utils/src/helpers/formValidate.ts` | 直接 `import` + 提 JSON | 14 条规则 |
|
||
| **componentMap** | `web/.../components/FormGenerator/src/helper/componentMap.ts` | 提 → `component-map.json` | 60+ jnpfKey → tag |
|
||
| **Rxxx.vue template** | `web/.../components/FormGenerator/src/rightComponents/*.vue` | `@vue/compiler-sfc` parse 提 `activeData.*` | 39 控件 schema |
|
||
|
||
### 2.2 Playwright Node.js = 基础设施
|
||
|
||
**不**是"可选的 E2E 工具",**是** 0 差错验证的核心:
|
||
|
||
| 用途 | Playwright 角色 |
|
||
|------|-----------------|
|
||
| **baseline 截图对比** | 原版 vs 复刻版像素级 diff |
|
||
| **业务功能验证** | 提交表单/审批流程/翻页/搜索真实能跑 |
|
||
| **API + UI 双层验证** | API 0 错 + 浏览器 0 视觉差 (双层 0 错) |
|
||
| **回归基线** | JNPF 升级时一键跑 74 张,5 分钟看出 regression |
|
||
| **AI 自检** | AI 改完 dacli 后跑 Playwright 看实际效果 |
|
||
|
||
**技术选型**:
|
||
- `@playwright/test` (Node.js) 而**非** Playwright Python
|
||
- 原因: 与 dacli 同 Node 进程,可直接 import dacli 模块做集成测试
|
||
- 浏览器: chromium (headless) + 截图 + DOM 比对
|
||
- 截图对比: `pixelmatch` 库像素级 diff
|
||
|
||
**目录**:
|
||
```
|
||
dacli/tests/
|
||
├── e2e/
|
||
│ ├── baseline/ # 114 张官方示例
|
||
│ │ ├── developSystem/ # 21 张
|
||
│ │ │ ├── <enCode>.spec.ts # 每张一个
|
||
│ │ │ └── ...
|
||
│ │ └── workSystem/ # 53 张
|
||
│ │ ├── <enCode>.spec.ts
|
||
│ │ └── ...
|
||
│ ├── api/ # API 层 0 错测试
|
||
│ │ ├── form.spec.ts
|
||
│ │ ├── menu.spec.ts
|
||
│ │ └── ...
|
||
│ └── visual/ # 视觉对比
|
||
│ ├── <form-enCode>-diff.spec.ts
|
||
│ └── screenshots/ # 截图 + diff 输出
|
||
└── unit/
|
||
├── crypto.test.ts
|
||
├── extractors.test.ts
|
||
└── schema.test.ts
|
||
```
|
||
|
||
### 2.3 目录结构 ($ccWorkDir/dacli/) - 更新
|
||
|
||
```
|
||
dacli/
|
||
├── prompt.md # 本文件
|
||
├── README.md # 项目入口
|
||
├── package.json # 加 @playwright/test
|
||
├── tsconfig.json
|
||
├── playwright.config.ts # Playwright 配置
|
||
│
|
||
├── src/ # ⭐ 第一件交付物: dacli CLI
|
||
│ ├── cli.ts # Commander.js 入口
|
||
│ ├── commands/ # 嵌套子命令
|
||
│ │ ├── login.ts
|
||
│ │ ├── status.ts
|
||
│ │ ├── form/{list,info,create,release,delete,export,import,clone,validate,fix}.ts
|
||
│ │ ├── menu/{list,create,update,delete}.ts
|
||
│ │ ├── dm/{list,table,create,update,drop}.ts
|
||
│ │ ├── dict/{type-list,type-create,data-list,data-create}.ts
|
||
│ │ ├── workflow/{list,create,launch,approve}.ts
|
||
│ │ ├── doc/{list,get,scan,refresh,clear}.ts
|
||
│ │ └── apis/{list,info,search,refresh,status}.ts
|
||
│ ├── core/
|
||
│ │ ├── client.ts
|
||
│ │ ├── crypto.ts
|
||
│ │ ├── config.ts
|
||
│ │ ├── cache.ts # better-sqlite3
|
||
│ │ ├── help.ts # --ai-help / --example / --source
|
||
│ │ └── log.ts
|
||
│ ├── extractors/ # web 源码提取工具
|
||
│ │ ├── fields.ts
|
||
│ │ ├── l1-rules.ts
|
||
│ │ ├── l2-rules.ts
|
||
│ │ ├── flow.ts
|
||
│ │ ├── component-map.ts
|
||
│ │ # ↓ v0.8+ 新增 extractor
|
||
│ │ ├── report-schemas.ts # [P0] 报表组件 schema (W8)
|
||
│ │ ├── portal-schemas.ts # [P0] 门户布局 schema (W8)
|
||
│ │ ├── bigdata-schemas.ts # [P0] 大屏图表 schema (W8)
|
||
│ │ └── datasource-drivers.ts # [P0] 数据源 driver 列表 (W8)
|
||
│ ├── data/ # 提取 JSON (git-tracked)
|
||
│ │ ├── component-map.json
|
||
│ │ ├── field-schemas.json
|
||
│ │ ├── validation-rules.json
|
||
│ │ └── l2-rules.json
|
||
│ ├── schema/ # FieldBuilder (从 JSON 加载)
|
||
│ └── types.ts
|
||
│
|
||
├── .claude/skills/dacli-ts/ # ⭐ 第二件交付物: AI 专用 skill
|
||
│ ├── SKILL.md # 主入口
|
||
│ ├── references/
|
||
│ │ ├── commands.md # 完整命令清单
|
||
│ │ ├── patterns.md # 5+ 业务模式
|
||
│ │ ├── anti-patterns.md # 8+ 反模式
|
||
│ │ ├── troubleshooting.md # 8+ 排错
|
||
│ │ ├── baseline/ # ⭐ 官方示例 baseline
|
||
│ │ │ ├── README.md
|
||
│ │ │ ├── developSystem.md # 21 张表单清单
|
||
│ │ │ └── workSystem.md # 53 张表单清单
|
||
│ │ └── playwright.md # Playwright 使用指南
|
||
│ ├── examples/ # 可复制粘贴的示例
|
||
│ │ ├── create-simple-form.sh
|
||
│ │ ├── create-master-sub-form.sh
|
||
│ │ ├── create-workflow.sh
|
||
│ │ └── baseline/ # 74 张 baseline 复刻脚本
|
||
│ │ ├── all.sh
|
||
│ │ ├── developSystem/
|
||
│ │ │ ├── <enCode>.sh
|
||
│ │ │ └── ...
|
||
│ │ └── workSystem/
|
||
│ │ ├── <enCode>.sh
|
||
│ │ └── ...
|
||
│ └── scripts/ # AI 调用的辅助脚本
|
||
│
|
||
├── doc/ # 人类可读详细文档
|
||
│ ├── README.md
|
||
│ ├── architecture.md
|
||
│ ├── plan.md # 6 周路线
|
||
│ ├── api.md
|
||
│ ├── extractors.md
|
||
│ ├── help-system.md
|
||
│ └── baseline.md # ⭐ baseline 验证规范
|
||
│
|
||
├── tests/ # ⭐ Playwright + vitest 测试套件
|
||
│ ├── e2e/
|
||
│ │ ├── baseline/ # 74 张 baseline 复刻 + 验证
|
||
│ │ │ ├── developSystem/
|
||
│ │ │ └── workSystem/
|
||
│ │ ├── api/ # API 层 0 错
|
||
│ │ └── visual/ # 截图视觉对比
|
||
│ └── unit/ # vitest 单元测试
|
||
│
|
||
├── screenshots/ # baseline 截图 (gitignored)
|
||
│ ├── developSystem/
|
||
│ └── workSystem/
|
||
│
|
||
├── scripts/
|
||
│ ├── extract-all.mjs # 一键提取 web 源码
|
||
│ ├── verify-baseline.mjs # ⭐ baseline 一键回归
|
||
│ └── install-playwright.mjs # 一键装 playwright + chromium
|
||
│
|
||
└── .dacli-cache.db # SQLite 缓存 (gitignored)
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 6 周路线 (Week 1-6: dacli + skill)
|
||
|
||
### Week 1: 脚手架 + 核心管道 (登录 + form CRUD)
|
||
|
||
| Day | 任务 | 验收 |
|
||
|-----|------|------|
|
||
| D1 | 初始化目录、package.json、tsconfig.json、Commander.js 入口、playwright 装好 | `npx tsx src/cli.ts --help` 跑通 |
|
||
| D2 | `core/crypto.ts` (从 web cipher.ts 移植 crypto-js) + 单元测试 | '123456' → 与 web 同 96 hex |
|
||
| D3 | `core/client.ts` (JnpfClient: login + HTTP) + `commands/login.ts` | login 成功 + token 持久化 |
|
||
| D4 | `commands/form/{list,info}.ts` + `core/config.ts` | form list 返回 3+ 张 |
|
||
| D5 | `commands/form/{create,release,delete}.ts` | 端到端 demo 跑通 |
|
||
|
||
**Week 1 必达 (0 差错第 1 步)**:
|
||
- [ ] tds 应用 login + form list 跑通
|
||
- [ ] developSystem / workSystem 也能 login + form list (验证多 app)
|
||
|
||
### Week 2: 提取工具 + 53 控件 schema + 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 | 53 控件可调,无需硬编码 |
|
||
|
||
**Week 2 必达**: 提取 + Playwright 基础完成
|
||
|
||
### Week 3: 5 父命令 + 第一批 baseline (developSystem 21)
|
||
|
||
| Day | 任务 | 验收 |
|
||
|-----|------|------|
|
||
| D1 | `commands/dm.ts` (list/table/create) | 端到端 |
|
||
| D2 | `commands/dict.ts` (type-list/data-list/create) | 端到端 |
|
||
| D3 | `commands/menu.ts` (list/create) + `commands/di.ts` | 端到端 |
|
||
| D4 | **写 21 张 developSystem baseline 脚本** (export → import → Playwright 截图对比) | 21/21 API 0 错 |
|
||
| D5 | 21 张 baseline 浏览器 0 视觉差 | **API + UI 双 0 错** |
|
||
|
||
**Week 3 必达**: developSystem 21 张 baseline 全 0 错
|
||
|
||
### Week 4: workflow + 第二批 baseline (workSystem 53)
|
||
|
||
| Day | 任务 | 验收 |
|
||
|-----|------|------|
|
||
| D1 | `commands/workflow.ts` (list/create/launch/approve) | 端到端 |
|
||
| D2-D4 | **写 53 张 workSystem baseline 脚本** | 53/53 API 0 错 |
|
||
| D5 | 53 张 baseline 浏览器 0 视觉差 | **API + UI 双 0 错** |
|
||
|
||
**Week 4 必达**: workSystem 53 张 baseline 全 0 错
|
||
|
||
### Week 5: 帮助体系 + skill 主体
|
||
|
||
| Day | 任务 | 验收 |
|
||
|-----|------|------|
|
||
| D1 | `core/help.ts` + `--ai-help / --example / --source` | 全部命令支持 |
|
||
| D2 | `commands/doc.ts` (HTML 缓存) | TS 版独立能力 |
|
||
| D3 | `commands/apis.ts` (OpenAPI 抓取) | TS 版独立能力 |
|
||
| D4 | skill `SKILL.md` + `references/commands.md` | AI 读后知道何时用 |
|
||
| D5 | skill `references/patterns.md` + `anti-patterns.md` | 5+ 模式 + 8+ 反模式 |
|
||
|
||
**Week 5 必达**: 帮助体系 + skill 主体
|
||
|
||
### Week 6: skill examples + AI 自检 + 文档收尾
|
||
|
||
| 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 张一键跑 |
|
||
|
||
**Week 6 必达**: skill 完整 + AI 自检通过 + 74 张 baseline 一键回归
|
||
|
||
---
|
||
|
||
## 3.5 v0.8 路线 (Week 7-12: jnpf web 剩余主要功能整合)
|
||
|
||
> **目标**: 把 jnpf web 剩下的 25+ 顶级模块整合进 dacli, 从 8 父命令扩到 **22 父命令 / 80+ 子命令**, baseline 从 114 张扩到 **130+ 张** (新增报表/门户/大屏/打印/打印模板样例 16+ 张).
|
||
>
|
||
> **扫描快照** (web 94 入口 + 后端 100+ Controller + 22 模块端点): 见 `doc/v0.8-scan.md`.
|
||
> **详细盘点** (按 AI 业务价值排序, 25+ 子功能): 见 `doc/RESUME.md` §5.1.
|
||
> **详细路线** (W7-W12): 见 `doc/RESUME.md` §5.2-5.7.
|
||
|
||
### Week 7: 整合基础设施 (情报收集 + 脚手架)
|
||
| Day | 任务 | 验收 |
|
||
|-----|------|------|
|
||
| D1 | 扫 `web/views/` 全部 25+ 顶级模块, 整理 6.1 表格 | `/tmp/jnpf-web-views.txt` ≥ 25 行 |
|
||
| D2 | `dacli apis refresh` + 拉新 API 缓存, 找新模块端点 | apis list 含 report/portal/codegen 等新 tag |
|
||
| D3 | 4 个新父命令脚手架 (datasource / report / portal / codegen) | 全部 `npx tsx src/cli.ts <新命令> --help` 跑通 |
|
||
| D4 | 新 extractor 脚手架 (report-schemas / portal-schemas / bigdata-schemas / datasource-drivers) | 4 个 extractor 各跑出 JSON |
|
||
| D5 | `doc/v0.8-plan.md` (从 RESUME.md §6.1/6.2 抄), `doc/v0.8-changelog.md` 框架 | 2 文档就位 |
|
||
|
||
**Week 7 必达**: 4 父命令占位 + 4 extractor 跑通 + 8 父命令基线 (v0.7.1 收尾) 全 PASS
|
||
|
||
### Week 8: P0 第 1 波 (数据源 + 报表 + 门户)
|
||
| Day | 任务 | 验收 |
|
||
|-----|------|------|
|
||
| D1 | `dacli datasource list/create/delete/test` (dataSource 4 子) | 端到端 |
|
||
| D2 | `dacli report list/info/create/release` (onlineDev/report 4 子) | workSystem 报表样例 2+ 张 0 错 |
|
||
| D3 | `dacli portal list/info/create` (visualPortal 3 子) | workSystem 门户样例 1+ 张 0 错 |
|
||
| D4 | baseline 验证: 报表 + 门户样例 5+ 张 (API 层 0 错) | 5+ 张 schema 完整 |
|
||
| D5 | Playwright 视觉对比 (报表 / 门户 0 视觉差) | UI 层 0 错 |
|
||
|
||
**Week 8 必达**: 3 父命令 (datasource / report / portal) + 5+ 样例 API 0 错
|
||
|
||
### Week 9: P0 第 2 波 (代码生成 + 大屏 + 打印)
|
||
| Day | 任务 | 验收 |
|
||
|-----|------|------|
|
||
| D1 | `dacli codegen module/list/import` (从 form 模板生成 ssw-后端模块 3 子) | Java 模块生成跑通 |
|
||
| D2 | `dacli bigscreen list/info/create` (extend/bigData 3 子) | 大屏样例 2+ 张 0 错 |
|
||
| D3 | `dacli print template list/info/create` (printDev 3 子) | 打印模板 1+ 张 0 错 |
|
||
| D4 | baseline 验证: 大屏 + 打印样例 3+ 张 (API 层 0 错) | 3+ 张 schema 完整 |
|
||
| D5 | Playwright 视觉对比 (大屏 / 打印 0 视觉差) | UI 层 0 错 |
|
||
|
||
**Week 9 必达**: 3 父命令 (codegen / bigscreen / print) + 3+ 样例 API 0 错; **P0 全部完成, 11 父命令 / 27+13=40 子命令**
|
||
|
||
### Week 10: P1 权限三角 (role + user + organize)
|
||
| Day | 任务 | 验收 |
|
||
|-----|------|------|
|
||
| D1 | `dacli role list/create/delete/assign` (4 子) | 角色 CRUD + 赋权 |
|
||
| D2 | `dacli user list/create/delete/reset-pwd` (4 子) | 用户 CRUD + 密码重置 |
|
||
| D3 | `dacli org list/tree/create` (组织/部门/岗位 3 子) | 组织树 CRUD |
|
||
| D4 | 联动验证: 建用户 → 分配组织 → 赋角色 → 登录 tds 看菜单 | 端到端 1 套 |
|
||
| D5 | AI 自检 1: 跑通"权限三角"完整流程 | subagent 验证 |
|
||
|
||
**Week 10 必达**: 3 父命令 (role / user / org) + 权限闭环
|
||
|
||
### Week 11: P1 消息中心 + 调度 + 应用管理
|
||
| Day | 任务 | 验收 |
|
||
|-----|------|------|
|
||
| D1 | `dacli msg notice list/create/send` + `dacli msg template` (5 子) | 通知公告 + 模板 |
|
||
| D2 | `dacli schedule list/create/pause/trigger/log` (定时任务 5 子) | Quartz job CRUD |
|
||
| D3 | `dacli app list/create/delete/initapp` (应用管理 4 子, initapp 升级) | 多 app 生命周期 |
|
||
| D4 | 端到端: 通知公告真发出 + 定时任务真触发 | 2 套验证 |
|
||
| D5 | AI 自检 2: 跑通"建通知 + 触发定时任务"完整流程 | subagent 验证 |
|
||
|
||
**Week 11 必达**: 3 父命令 (msg / schedule / app) + 闭环验证; **14 父命令 / 60+ 子命令, P0+P1 全部完成**
|
||
|
||
### Week 12: P2 收尾 + 全量回归
|
||
| Day | 任务 | 验收 |
|
||
|-----|------|------|
|
||
| D1 | `dacli monitor online/sql/flow` (3 子) | 监控查 |
|
||
| D2 | `dacli log login/operate` (2 子) | 日志查 |
|
||
| D3 | `dacli integration email/sms/webhook test` (集成测试 3 子) | 集成渠道 |
|
||
| D4 | `dacli import excel/... --template=X` (批量导入 1 子) | Excel 导入 |
|
||
| D5 | **全量回归**: 14 父命令 vitest + 11 父命令 Playwright (新父命令 W8-W11 跑通回归) | 0 错 |
|
||
|
||
**Week 12+ 必达**: 14 父命令 / 60+ 子命令 + **122+ baseline 0 差错** + v0.8 完整交付
|
||
|
||
### v0.8 末交付 (硬目标)
|
||
- ✅ **22 父命令** / 80+ 子命令 (v0.7.1 的 8 → v0.8 的 22, 翻 2.7 倍)
|
||
- ✅ **130+ baseline** 0 差错 (114 + 报表/门户/大屏/打印/打印模板 16+)
|
||
- ✅ **3 个 AI 自检** (权限三角 / 通知调度 / v0.8 总体闭环)
|
||
- ✅ **`doc/v0.8-changelog.md`** 详 v0.8 全部变更
|
||
- ✅ **`.claude/skills/dacli-ts/SKILL.md` v0.8 校准**: 加 P0/P1/P2 命令速查 + 4 大新决策点
|
||
|
||
### v0.8 关键决策点 (AI 必读, 决策错率高的 4 点)
|
||
|
||
#### 决策 6: 报表/门户/大屏用哪个 type?
|
||
| 场景 | webType | 是否需要物理表 | 镜像命令 |
|
||
|------|---------|--------------|----------|
|
||
| 普通报表 | 1-2 (报表设计器) | ❌ 不需要 (走数据接口拉) | `dacli report create` |
|
||
| 大屏/仪表盘 | 3-4 (大屏设计器) | ❌ 不需要 | `dacli bigscreen create` |
|
||
| 门户 (经典/全屏) | 5-6 (门户设计器) | ❌ 不需要 | `dacli portal create` |
|
||
| 打印模板 | 1-2 (printDev) | ❌ 不需要 (绑 form 数据) | `dacli print template create` |
|
||
|
||
**AI 反模式**: 给报表/门户硬建物理表 → 100% "Database exception" (它们走 di / dataInterface 拉数据)
|
||
**AI 正解**: 先 `dacli di list` 看有什么数据接口 → 报表直接 bind dataInterfaceId
|
||
|
||
#### 决策 7: 权限三角优先级
|
||
| 角色 | 优先级 | 必含字段 |
|
||
|------|--------|---------|
|
||
| **角色 (role)** | 1 | name, enCode, type (0业务/1系统), organizeIds, positionIds, userIds |
|
||
| **用户 (user)** | 2 | account, realName, password, organizeId, positionId, roleId, enabled |
|
||
| **组织 (org)** | 3 | name, enCode, parentId, category (公司/部门/岗位), sortCode |
|
||
|
||
**AI 反模式**: 先建用户再建组织 → 用户 organizeId=null 报 "组织不存在"
|
||
**AI 正解**: 先建组织树 → 再建用户绑组织 → 最后建角色赋权
|
||
|
||
#### 决策 8: 通知/消息发送通道怎么选?
|
||
| 场景 | 通道 | dacli 命令 |
|
||
|------|------|-----------|
|
||
| 站内信 (tds 内部) | msgCenter 站内信 | `dacli msg notice send --type=site` |
|
||
| 邮件 | integrationCenter/email | `dacli integration email send` |
|
||
| 短信 | integrationCenter/sms | `dacli integration sms send` |
|
||
| 钉钉/企微/微信 | integrationCenter | `dacli integration <渠道> send` |
|
||
| Webhook (自定义) | integrationCenter/webhook | `dacli integration webhook send --url=...` |
|
||
|
||
**AI 反模式**: 邮件配置直接改 `application.yml` → 走不到 JNPF 通知管理
|
||
**AI 正解**: 先 `dacli integration email config` 在 JNPF 配 → 再用通知发送命令
|
||
|
||
#### 决策 9: 定时任务 vs 工作流调度?
|
||
| 场景 | 用什么 | 触发 |
|
||
|------|--------|------|
|
||
| 定时报表生成 / 数据清理 / 缓存刷新 | **schedule (Quartz)** | cron 表达式 |
|
||
| 业务审批流程 (请假/报销/合同) | **workflow (Flowable)** | 人工发起 / 事件触发 |
|
||
| 数据同步 (外部接口) | **schedule (Quartz)** | cron 表达式 |
|
||
| 多步审批 + 条件分支 | **workflow (Flowable)** | 流程引擎 |
|
||
|
||
**AI 反模式**: 用工作流做"每天凌晨跑一次" → 流程引擎不适合 cron
|
||
**AI 正解**: 用 schedule, cron="0 0 0 * * ?"
|
||
|
||
---
|
||
|
||
## 4. 0 差错验证规范 (baseline.md)
|
||
|
||
### 4.1 验证金字塔
|
||
|
||
```
|
||
┌──────────────┐
|
||
│ Playwright │ ← 浏览器 0 视觉差
|
||
│ (E2E) │
|
||
├──────────────┤
|
||
│ dacli CLI │ ← API 0 错
|
||
│ (集成测试) │
|
||
├──────────────┤
|
||
│ vitest │ ← 函数 0 错
|
||
│ (单元测试) │
|
||
└──────────────┘
|
||
```
|
||
|
||
**每一层都必须 0 错**。
|
||
|
||
### 4.2 baseline 复刻流程 (每张表单)
|
||
|
||
```bash
|
||
# 1. export 原表单 JSON
|
||
dacli form export <original-id> --out=/tmp/<enCode>-orig.json
|
||
|
||
# 2. 拿到原表单的 dbLinkId / category / webType / type 等元数据
|
||
dacli form info <original-id>
|
||
|
||
# 3. import 到 tds (或新应用)
|
||
dacli form import /tmp/<enCode>-orig.json --enCode=<enCode>_clone
|
||
|
||
# 4. 拿克隆 id
|
||
CLONE_ID=$(dacli form list | jq -r '.data.list[] | select(.enCode=="<enCode>_clone") | .id')
|
||
|
||
# 5. release
|
||
dacli form release $CLONE_ID
|
||
|
||
# 6. Playwright 验证 (API + UI)
|
||
npx playwright test e2e/baseline/<app>/<enCode>.spec.ts
|
||
|
||
# 7. 视觉对比 (0 差 = 像素级)
|
||
npx playwright test e2e/visual/<enCode>-diff.spec.ts
|
||
```
|
||
|
||
### 4.3 0 差错的精确含义
|
||
|
||
| 维度 | 0 差错标准 | 验证 |
|
||
|------|------------|------|
|
||
| **HTTP 状态码** | 200/业务成功 (无 4xx/5xx) | Playwright API fixture |
|
||
| **响应数据** | 重建后 form info 字段集与原版**完全一致** (允许 id/enCode/state 不同) | 单元对比 |
|
||
| **字段渲染** | 浏览器看到的 input/select/textarea 数量、类型、默认值 0 差 | DOM 断言 |
|
||
| **按钮位置** | 保存/取消/审批按钮位置 0 差 | 截图 |
|
||
| **列表列** | 列表页列数/列名/列宽 0 差 | 截图 + DOM |
|
||
| **工作流节点** | 流程图节点数/连线 0 差 | 截图 |
|
||
|
||
**允许差异** (不算错):
|
||
- id / enCode 必然不同
|
||
- 物理表名前缀 (e.g. `tds_asset` vs `tds_asset_clone`)
|
||
- 时间戳 / 创建人
|
||
- 像素级抗锯齿差异 (1-2 像素)
|
||
|
||
### 4.4 不算 0 差错的常见 bug
|
||
|
||
- ❌ 字段缺失 (e.g. input 缺 `maxlength` 属性)
|
||
- ❌ 控件类型错 (e.g. select 被渲染成 input)
|
||
- ❌ 字典数据加载失败 (下拉框空白)
|
||
- ❌ 列表分页错 (pageSize 不一致)
|
||
- ❌ 工作流节点缺失
|
||
- ❌ 表单提交后跳错页
|
||
|
||
---
|
||
|
||
## 5. 关键命令 (AI 一眼能看完)
|
||
|
||
```bash
|
||
# ===== 登录/状态 =====
|
||
dacli app login --appCode=tds
|
||
dacli app switch --appCode=developSystem # 切到 baseline
|
||
dacli app status
|
||
|
||
# ===== baseline 复刻 (74 张) =====
|
||
bash examples/baseline/all.sh # 一键全跑 74 张
|
||
bash examples/baseline/developSystem/leave.sh
|
||
bash examples/baseline/workSystem/contract.sh
|
||
|
||
# ===== 验证 =====
|
||
npx playwright test # 跑全部 E2E
|
||
npx playwright test e2e/baseline/developSystem # 跑 21 张
|
||
npx vitest run # 跑单元测试
|
||
|
||
# ===== 提取 (JNPF 升级时重跑) =====
|
||
node scripts/extract-all.mjs
|
||
|
||
# ===== 文档/API 查 =====
|
||
dacli doc list --dir=docs/tds
|
||
dacli doc get --file=docs/tds/plan.html
|
||
dacli apis list --tag=visualdev
|
||
dacli apis info "POST /api/visualdev/Base"
|
||
|
||
# ===== v0.8 启动预研 (新增) =====
|
||
# 扫 web 端所有顶级模块入口
|
||
find /home/ubuntu/ccWorkDir/web/apps/jnpf-web-apps-main/src/views \
|
||
-maxdepth 2 -name "index.vue" | sort > /tmp/jnpf-web-views.txt
|
||
wc -l /tmp/jnpf-web-views.txt
|
||
# 拉新 API 缓存 (报表/门户/大屏端点)
|
||
dacli apis refresh
|
||
dacli apis list --tag=visualReport # 报表 (待 v0.8 W8 实测 tag)
|
||
dacli apis list --tag=visualPortal # 门户 (待 v0.8 W8 实测 tag)
|
||
# 列 developSystem/workSystem 现有报表/门户样例 (作 baseline)
|
||
dacli app switch --appCode=workSystem
|
||
dacli form list | jq -r '.data.list[] | "\(.id) \(.category) \(.fullName)"' | head -50
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 已知陷阱 (踩过的坑 + 必防)
|
||
|
||
### 6.1 URL 重复
|
||
baseUrl 已含 `/api`,path 不含。`/api/api/...` → 404/401
|
||
|
||
### 6.2 加密字节级不一致
|
||
`Hex.stringify(Base64.parse(result))` 是对 Base64 字符串做 hex,**不是**密文字节。用 `crypto-js` 严格 1:1 复刻 cipher.ts
|
||
|
||
### 6.3 表单 "Database exception"
|
||
- `dbLinkId='0'` 错(用 `/api/system/DataSource` 拉)
|
||
- `tables[].fields[]` 缺 `autoIncrement/identity/columnName` 等
|
||
- `category='0'` 错(用 `dacli form list` 查真实值)
|
||
- **type=4 (视图) 绕过 tables 问题**
|
||
|
||
### 6.4 release 视图表失败
|
||
type=4 (视图) release 报 "System abnormality"。**软跳过**。
|
||
|
||
### 6.5 菜单 API 不回 data.id
|
||
响应只有 `{code, msg}`。解析时用 enCode 反查 list。
|
||
|
||
### 6.6 Playwright 浏览器层 tdd 应用 404
|
||
nginx 容器可能不通,dacli/login 失败。**用 developSystem/workSystem 兜底验证**(已通)。
|
||
|
||
### 6.7 baseline 表单的 dbLinkId
|
||
74 张表单的 dbLinkId **各异**(不同业务库)。脚本里**动态拉**,不写死。
|
||
|
||
### 6.8 baseline 工作流的 formId
|
||
克隆工作流时 formId 失效(指向原 formId)。**必须重建** formId 映射。
|
||
|
||
---
|
||
|
||
## 7. 提取工具 (TS 版通用资产)
|
||
|
||
`dacli/src/extractors/` (component-map / field-schemas / l1-rules / l2-rules / **v0.8+ report-schemas / portal-schemas / bigdata-schemas / datasource-drivers**) 是 TS 版通用资产. 用法:
|
||
- TS 版 `FieldBuilder` 加载 `data/*.json` 自动构建表单/报表/门户/大屏字段
|
||
- 提取脚本 `scripts/extract-all.mjs` JNPF 升级时重跑 (出新版字段)
|
||
- 提取 JSON 入 git (跟版本, 可对比 diff)
|
||
- v0.8 新增 4 个 extractor 直接跑出 `data/report-schemas.json` / `data/portal-schemas.json` / `data/bigdata-schemas.json` / `data/datasource-drivers.json`
|
||
|
||
---
|
||
|
||
## 8. 上下文恢复指引
|
||
|
||
**新会话第一句**:
|
||
```
|
||
按 $ccWorkDir/dacli/prompt.md 继续。当前周次/任务查 doc/RESUME.md (v0.7.1 收尾 + v0.8 启动)。
|
||
目标 0 差错: developSystem 21 + workSystem 53 baseline 全跑通 (v0.8 起追加报表/门户/大屏 8+ 张).
|
||
```
|
||
|
||
**关键文件** (按恢复时阅读顺序):
|
||
- `doc/RESUME.md` — **第一份读** (v0.7.1 状态 + v0.8 启动盘点, §6 路线最关键)
|
||
- `doc/v0.7.1-changelog.md` — 本轮 (盲点 23 闭环)
|
||
- `doc/v0.7-changelog.md` — 上轮 (P0 #13 + P1 #15)
|
||
- `doc/plan.md` — 6 周路线 + v0.6 段 (v0.8 路线见 prompt §3.5)
|
||
- `doc/v0.8-plan.md` — **待写** (v0.8 路线展开)
|
||
- `doc/architecture.md` — 设计决策
|
||
- `doc/baseline.md` — 0 差错验证规范
|
||
- `references/baseline/developSystem.md` + `workSystem.md` — 74 张清单
|
||
- `examples/baseline/all.sh` — 一键回归
|
||
- `src/data/*.json` — 提取的资产
|
||
- `tests/e2e/baseline/` — 74 张的 Playwright 测试
|
||
- `test/ddcc/` — 上一轮实验
|
||
- `/tmp/jnpf-web-views.txt` — **下次会话第一波扫出的 web 模块入口清单** (v0.8 启动用)
|
||
|
||
**关键命令**:
|
||
```bash
|
||
cd $ccWorkDir/dacli
|
||
npx tsx src/cli.ts --help
|
||
npx tsx src/cli.ts login --appCode=tds
|
||
bash examples/baseline/all.sh # 74 张一键回归
|
||
npx playwright test # 跑全部 E2E
|
||
npx vitest run # 跑单元测试
|
||
node scripts/extract-all.mjs # 提取 web 源码
|
||
|
||
# v0.7.1 收尾 (第一波)
|
||
npx tsx src/cli.ts form fix-columndata 835168490678657989
|
||
npx tsx src/cli.ts menu create --fullName="员工请假申请" --formId=835168490678657989
|
||
|
||
# v0.8 启动预研 (第二波)
|
||
find /home/ubuntu/ccWorkDir/web/apps/jnpf-web-apps-main/src/views \
|
||
-maxdepth 2 -name "index.vue" | sort > /tmp/jnpf-web-views.txt
|
||
npx tsx src/cli.ts apis refresh
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 反向链接 (Related)
|
||
|
||
- [doc/RESUME.md](doc/RESUME.md) — **会话恢复指引** (v0.7.1 收尾 + v0.8 启动盘点)
|
||
- [doc/architecture.md](doc/architecture.md) — 架构设计
|
||
- [doc/plan.md](doc/plan.md) — 6 周路线 (W1-W6)
|
||
- [doc/v0.8-plan.md](doc/v0.8-plan.md) — **待写** v0.8 路线 (W7-W12)
|
||
- [doc/baseline.md](doc/baseline.md) — 0 差错验证规范
|
||
- [doc/api.md](doc/api.md) — API 完整列表
|
||
- [doc/implementation.md](doc/implementation.md) — 实现细节
|
||
- [doc/extractors.md](doc/extractors.md) — 提取工具
|
||
- [doc/help-system.md](doc/help-system.md) — 帮助体系
|
||
- [doc/v0.7.1-changelog.md](doc/v0.7.1-changelog.md) — 本轮详细 (盲点 23 闭环)
|
||
- [doc/v0.7-changelog.md](doc/v0.7-changelog.md) — 上轮 (P0 #13 + P1 #15)
|
||
- [doc/v0.6-changelog.md](doc/v0.6-changelog.md) — 上上轮 (Playwright + 浏览器会话)
|
||
- [SKILL.md](.claude/skills/dacli-ts/SKILL.md) — AI 技能主入口 (v0.7.1 校准)
|
||
- [references/baseline/developSystem.md](.claude/skills/dacli-ts/references/baseline/developSystem.md) — 21 张清单
|
||
- [references/baseline/workSystem.md](.claude/skills/dacli-ts/references/baseline/workSystem.md) — 53 张清单
|
||
- [examples/baseline/all.sh](.claude/skills/dacli-ts/examples/baseline/all.sh) — 一键回归
|
||
- [../ddcc/](../ddcc/) — 上一轮实验
|
||
|
||
---
|
||
|
||
**生成时间**: 2026-06-12
|
||
**作者**: Claude (M3) + 用户
|
||
**状态**: v0.7.1 完工, v0.8 启动准备就绪
|
||
**v0.7.1 目标**: 8 父命令 / 27 子命令, 72 baseline 0 差错 ✅
|
||
**v0.8+ 目标**: 14 父命令 / 60+ 子命令, 122+ baseline 0 差错 (本轮)
|
||
**核心目标**: **jnpf web 主要功能 90% 整合进 dacli + API 0 错 + 浏览器 0 视觉差**
|