From d52744d697ffd699fea3105727e66a6bf69d3b9b Mon Sep 17 00:00:00 2001 From: ssw Date: Fri, 24 Jul 2026 08:44:55 +0800 Subject: [PATCH] docs(decisions): add ADR 0016 app clear p1-2e scope ghost Co-Authored-By: Claude --- .../0016-app-clear-p1-2e-scope-ghost.md | 118 ++++++++++++++++++ 1 file changed, 118 insertions(+) create mode 100644 docs/decisions/0016-app-clear-p1-2e-scope-ghost.md diff --git a/docs/decisions/0016-app-clear-p1-2e-scope-ghost.md b/docs/decisions/0016-app-clear-p1-2e-scope-ghost.md new file mode 100644 index 0000000..748180d --- /dev/null +++ b/docs/decisions/0016-app-clear-p1-2e-scope-ghost.md @@ -0,0 +1,118 @@ +# 0016-app-clear-p1-2e-scope-ghost + +> **日期**: 2026-07-23 +> **状态**: Accepted (dacli 端 + ssw-common 端已落地 7 类范围 + ghost 模式) +> **作者**: claude-code + +## Context + +**业务背景**: dacli app clear v1.0 (P1-2c 2026-07-21) + v1.1 (P1-2d 2026-07-21 `--clean-docs`) 清了 18 张主库表 (form/menu/db_link/dict/system) + 业务库 RENAME + docs。但**实战发现 4 大类遗漏**导致用户反复撞 enCode 冲突。 + +**事实证据** (docs/jxcj 2026-07-23 实测): + +1. **dict LIKE 模式漏 20 条** — `LIKE CONCAT(:app_code, '.%')` 要求带点,但实际 jxcjxxx 不带点 → **0 条匹配** +2. **workflow/di/portal/print/report/schedule 6 大类完全缺失** — 平台全局资源, 创建后 enCode 永久占用 +3. **跨 systemId 残留 (ghost)** — 应用被删再重建, 旧 systemId 的 workflow_template 等仍占 enCode, 重建后报 "Encoding cannot be repeated" (jxcjRegistrationReview 反复撞) +4. **column name 误用** — workflow_reject_data/subtask_data 没有 f_task_id, workflow_print_version 字段是 f_template_id, base_data_interface_log 用 f_invok_id, base_schedule_log/user 用 f_schedule_id — 跨流程/DI/调度共享表不能靠 FK 链删 + +## 决策 + +### 1. 扩展 MAIN_TABLE_PLANS 18 张 → 50 张 (新增 32 张) + +| 范围 | 表数 | where 模板 | +|---|---|---| +| 字典 (修复) | 2 | `f_en_code LIKE CONCAT(:app_code, '%')` (兼容 `jxcj.xxx` 和 `jxcjxxx`) | +| workflow_template + 子表 | 22 | `f_flow_id IN (SELECT f_id FROM workflow_template WHERE f_system_id = ?)` 或 task 类用 `f_flow_code IN (SELECT f_en_code ...)` | +| base_data_interface + variate | 2 | `f_en_code LIKE CONCAT(:app_code, '%')` (DI 表无 systemId, 全平台共享) | +| base_portal + 子表 | 3 | `f_system_id = ?` | +| base_print_template + 子表 | 3 | `f_system_id = ?` | +| report_template | 1 | `f_system_id = ?` | +| base_schedule + 子表 | 3 | `f_category = ?` (systemId 存 f_category) | + +### 2. 跨流程/DI/调度共享表跳过 (避免误删) + +| 表 | 跳过原因 | +|---|---| +| workflow_reject_data | 无 f_task_id, 跨流程共享 | +| workflow_subtask_data | 无 f_task_id, 跨流程共享 | +| base_data_interface_log | f_invok_id 而非 f_interface_id, 跨 DI 共享 | +| base_data_interface_oauth | f_data_interface_ids (varchar 列表, 无真 FK) | +| base_data_interface_user | f_oauth_id 而非 f_data_id | +| workflow_launch_user | 无 f_flow_id | + +### 3. 新增 GHOST_PLANS (跨 systemId 残留, 22 表) + +``` +SELECT f_id FROM workflow_template WHERE f_en_code LIKE 'appCode%' AND f_system_id != :current_system_id +``` + +- 默认 false (高危, 跨 systemId 清) +- 当 currentSystemId 为空 (app 已删), 自动改成 "f_system_id != ''" 模式清所有同 enCode 残留 +- bak 表名加 `-ghost-` 前缀区别于正常清理 + +### 4. scope 短手预设 + +| scope | 含义 | 用例 | +|---|---|---| +| `all` (默认) | 7 大类全开, ghost 关 | 正常清应用 | +| `conservative` | 只 form + dict + biz | 跨 app 试探, 不动全局资源 | +| `ghost` | 7 大类全开 + ghost 开 | 应用被删重建后清旧 enCode | +| `conservative,ghost` | conservative + ghost | 保守跨 app 清残留 | +| `--only=workflow,di` | 只清 workflow + DI | 跨 app 精准清某类 | + +### 5. dacli 端 flag + +| Flag | 默认 | 行为 | +|---|---|---| +| `--scope ` | - | 短手预设 (all/conservative/...) | +| `--only ` | - | 逗号分隔, 只清这些范围 | +| `--no-include-workflow` | (默认 true) | 跳过 workflow 类 | +| `--no-include-di` | (默认 true) | 跳过 DI | +| `--no-include-portal` | (默认 true) | 跳过 Portal | +| `--no-include-print` | (默认 true) | 跳过 Print | +| `--no-include-report` | (默认 true) | 跳过 Report | +| `--no-include-schedule` | (默认 true) | 跳过 Schedule | +| `--no-include-dict` | (默认 true) | 跳过 Dict | +| `--no-include-biz` | (默认 true) | 跳过业务库 | +| `--include-ghost` | (默认 false) | 启用 ghost 模式 | + +**注意**: 用 `--no-include-xxx` (不是 `--include-xxx=false`) — commander 12.x 风格 + +### 6. dry-run preview 准确性 + +- 顶部打印 "当前 scope=..., 不清理: ..." +- 被 scope 关闭的组标 `[SKIP-by-scope] (N 张, 实际不清理):` 仍展示数据, 让用户看到 "如果开了能清什么" +- 已分类的表从 "其他" 兜底分组中排除 (避免重复) + +## 实施清单 + +- [x] `boot/ssw-common/.../DbClearService.java` — MAIN_TABLE_PLANS 18→50, 新增 GHOST_PLANS, 新增 DbClearScope.includeGhost + withGhost() factory +- [x] `boot/ssw-common/.../DbClearServiceImpl.java` — DbClearPreview 加 ghostHits 字段, preview 查 ghost, execute 加 clearGhostTables (Phase 1/2/3 拆事务), GHOST_PARAMS_BY_APP_CODE 路由 +- [x] `boot/ssw-common/.../DbClearController.java` — parseScope 加 `ghost` key +- [x] `dacli/.../commands/app/clear.ts` — `--scope/--only/--no-include-*/--include-ghost` flag, buildScopeString/computeScopeFlags/renderPreview 分组+SKIP, ghostHits 透传 + +## 验证 + +``` +执行 jxcj clear (all scope): +✓ mainBaks: 12 张 (含 workflow_template 1 + data_interface 2 + dict 20+72 + form 23) +✓ bizBaks: 0 (已先清) +✓ 验证: base_visual_dev=0 base_module=0 workflow_template=0 base_data_interface=0 base_dictionary_type/data=0 base_db_link=0 base_system=0 + +执行 jxcj ghost (历史 enCode jxcjRegistrationReview 被旧 systemId 占): +✓ mainBaks: 22 张 ghost- 前缀 +✓ 验证: workflow_template (enCode LIKE 'jxcj%')=0 +✓ 验证: workflow create --enCode=jxcjRegistrationReview 成功 (之前报 "Encoding cannot be repeated") +``` + +## 风险 + +- ghost 模式跨 systemId 清, **默认关**, 需显式 `--include-ghost` +- DI 表无 systemId, ghost 模式按 enCode 匹配 + f_creator_user_id IS NOT NULL 兜底, 可能误清其他用户创建的同名 DI (低概率, enCode 必须 LIKE 'appCode%') +- workflow_record.task_json / reject_data 等跨流程共享表已明确跳过, 不会有跨流程污染 + +## 后续 + +- [ ] DI 表加 systemId 字段 (平台级需求, 不在 dacli 范围) +- [ ] ghost 模式增加 "dry-run 必跑" 强制, 避免误清 +- [ ] 与 `dacli form delete --cascade` 联动 (form 删除时自动 ghost 检查)