docs(decisions): add ADR 0016 app clear p1-2e scope ghost

Co-Authored-By: Claude <[email protected]>
This commit is contained in:
sswandClaude committed 2026-07-24 08:44:55 +08:00
1 parent 4042bac60f
commit d52744d697
1 file changed
+118
@@ -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 <preset>` | - | 短手预设 (all/conservative/...) |
| `--only <list>` | - | 逗号分隔, 只清这些范围 |
| `--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 检查)