diff --git a/README.md b/README.md index 4728ec5..51fae01 100644 --- a/README.md +++ b/README.md @@ -303,6 +303,7 @@ dacli form update --fields='[...]' # 按 suggestion 建议的修正 | 改菜单 | `dacli/src/commands/menu/*.ts` | | 改数据模型 | `dacli/src/commands/dm/*.ts` (create/drop/list/fields 已接) | | 改报表 | `dacli/src/commands/report/*.ts` (8 文件, BACKEND-7 已修 2026-07-21) | +| 改 app clear `--clean-docs` 行为 | `dacli/src/commands/app/clear.ts` (P1-2d 2026-07-21, docs/{app}/ 整体清理) + `dacli/docs/decisions/0014-app-clear-docs-coverage.md` | | 加新模块接入 (三层模式) | 跟 `report/create.ts` 同样 4 步 pattern: imports → addOutputOptions → setupOutputFilter + runCommandAutoFix → printCommandEnd | --- diff --git a/docs/decisions/0014-app-clear-docs-coverage.md b/docs/decisions/0014-app-clear-docs-coverage.md new file mode 100644 index 0000000..6c3a233 --- /dev/null +++ b/docs/decisions/0014-app-clear-docs-coverage.md @@ -0,0 +1,158 @@ +# 0014-app-clear-docs-coverage + +> **日期**: 2026-07-21 +> **状态**: Accepted (dacli 端已落地 `--clean-docs` flag) +> **作者**: claude-code + +## Context + +**业务背景**: dacli app clear 应该"清干净"应用相关的所有痕迹,但实战发现**漏了 docs/{app}/ 目录下的非 html 文件**。 + +**事实证据** (docs/jxcj 实测, 2026-07-21): + +``` +$ ls docs/jxcj/ +_assets/ ← 子目录, 不清 +debug.md ← 6 个 markdown 之一, 不清 +design.md ← 不清 +learnings.md ← 不清 +plan.md ← 不清 +render.html ← DOC_HTML_FILES 不含此 +research.md ← 不清 +screenshots/ ← 不清 +scripts/ ← 不清 +summary.html ← DOC_HTML_FILES 含此 ✓ +summary.md ← 不清 +test_logs/ ← 不清 +testcase.md ← 不清 +数据要素人工智能创新大赛系统设计说明.md ← 不清 +``` + +**DRY-RUN 输出** (`dacli app clear --appCode=jxcj --dry-run --verbose`): + +``` +[1] 文件/目录: + [MOVE] docs/jxcj/summary.html +… + ⚠️ docs/jxcj/ 残留 14 项 (默认保留): _assets, debug.md, design.md, learnings.md, plan.md, ... +``` + +**根因** (历史漂移): + +| 版本 | 清理范围 | docs/{app} 残留 | +|------|---------|-----------------| +| Java `ClearAppCommand.java` (docs/dacli/ssw-dacli) | DOC_HTML_FILES = 4 html | 14+ 项残留 | +| TS `app/clear.ts` (原始) | DOC_HTML_FILES = ['plan/testcase/debug/summary.html'] | 14+ 项残留 | + +两边都用了白名单方式管理 docs 清理,**漏了所有非 html 文件**。`DOC_HTML_FILES = ['plan.html', 'testcase.html', 'debug.html', 'summary.html']` 的设计是错误的隐喻 — docs 不只是 html 视图渲染,还有 MD 源 + 子目录素材。 + +**业务诉求**: +- 用户视角: "clear 应该真干净" (docs/jxcj 14 项残留是不干净的) +- 设计原则: docs/{app}/ 是**项目历史档案** + **设计依据** (ssw-loop 关卡 A 强制保留 design.md / testcase.md / learnings.md / plan.md / debug.md + summary.md+html, 关卡 B 要求 summary.md 4 铁律自检) +- 矛盾: docs 同时是"会保留的设计依据"又是"清理时会被误伤的设计依据" + +## Decision + +**dacli 端落地** (commit 60adaab, v3.0+): + +1. **加 `--clean-docs` flag (默认 false)**: 用户显式 trigger 时把 docs/{app}/ 整体移到 history-bak/{ts}/files/docs/{app}/ +2. **DRY-RUN 默认行为升级**: docs/{app}/ 存在时**警告**残留项数 + `--clean-docs` 提示,让用户知情 +3. **不**强制清 docs/ 默认 — 符合 "设计依据默认保留" 原则,向后兼容 + +```bash +# 行为 1: 默认 — docs 残留警告 + 4 html 清掉 +dacli app clear --appCode=jxcj --dry-run +# ⚠️ docs/jxcj/ 残留 14 项 (默认保留): _assets, debug.md, design.md, ... + +# 行为 2: --clean-docs — 整个 docs/ 整体打包成 history-bak +dacli app clear --appCode=jxcj --dry-run --clean-docs +# [MOVE] docs/jxcj/ (整体而非单 html) + +# 真实执行 (需要 TTY + 双人工确认): +dacli app clear --appCode=jxcj # 历史行为 +dacli app clear --appCode=jxcj --clean-docs # 完整清理 +``` + +**改动文件**: + +- `src/commands/app/clear.ts` + - L246-252 (接口 ClearOpts): 加 `cleanDocs?: boolean` + - L121 (option 列表): `--clean-docs` flag, 默认 false, 注释明确"默认保留" + - L529-540 (`collectFileTargets`): `cleanDocs=true` 时 push `{ path: docsAppDir, isDir: true }` 整体 + - L306-310 (DRY-RUN 警告): 检测 `!opts.cleanDocs && existsSync(docsAppDir)` 输出残留提示 + - L567 (helper `fsTsBakHint`): 警告文案中 `` 占位符 + - L57 (imports): 加 `readdirSync` 用于残留检测 + +## Alternatives Considered + +### 替代 1: 默认清 docs/{app}/ (无 flag) +- 优点: 用户视角 "真干净",少输入 +- 拒绝: docs 是 ssw-loop 关卡 A/B/C 强依赖 (design.md, summary.md, learnings.md 等是关卡必读)。默认清会破坏 ssw-loop 流程,与现有项目工作流冲突。 + +### 替代 2: 加 `--keep-docs` (反向,默认清) +- 优点: 用户主动保 docs 默认清,符合"干净优先"原则 +- 拒绝: ssw-loop 流程中 docs 是过程产物而非清理目标。强制清会意外清掉未提交的关卡 1-4 工作进度。 + +### 替代 3: 改 ssw-common DbClearServiceImpl 让 PG schema 共享库识别 jxcj 业务表 +- **最干净路径** — 让 jxcj 业务库 (j62 schema=jxcj) 在 DRY-RUN 真正列出来 +- 拒绝 (NOGO): 需要改 boot/ssw-common/ Java 5-10 处 + Maven 编译 + JNPF 重启,跨项目跨模块,且当前 Java 进程无 devtools auto-reload,重启会破坏 testspace 活跃测试 +- **留 ADR 路线图** (见下游路线 §1) + +### 替代 4: dacli 端直接连 PG schema 列出 jxcj 业务表 +- 优点: 绕后端限制 +- 拒绝: 违反 CLAUDE.md §"代码修改权限" 关于 "boot/ssw-common 走 Spring/MyBatis 同栈,不被 JNPF 升级覆盖" 的设计 — dacli 不应承担后端职责 + +## Consequences + +### 正面 +- ✅ clear 默认行为向后兼容,dry-run **警告** docs 残留,用户知情 +- ✅ `--clean-docs` 让用户能"真干净",且 history-bak 保留设计依据 (可还原) +- ✅ 三层接入完整 (L1+L2 silent+L3 audit trail),destructive 操作强 audit +- ✅ `--dry-run + --json` 给 AI 解析清单 (清理范围脚本化分析) + +### 负面 +- ⚠️ 用户必须**显式加 --clean-docs** 才能真清 docs — 默认行为仍"不干净" +- ⚠️ **jxcj 业务库 (j62 schema=jxcj) 实际不被识别** — ssw-common `listBizTables` 走 `openConn(appCode, null)` 把 jxcj 当 dbName 但 jxcj 没独立 db,business tables preview 显示 `(无表或不存在)`。即使加 `--clean-docs` 也只清文档,不清业务数据 +- ⚠️ ssw-common 这层 bug 需要 Java 修复,dacli 端无法绕过 + +## 下游路线 (Follow-ups) + +### 1. ssw-common 端点改进 (高优, 跨项目) +- 文件: `boot/ssw-common/ssw-common-biz/.../DbClearServiceImpl.java` +- 改动: + - `openConn(appCode, null)` 对 PG 应回退到 `mainDb + schema=appCode` (跨 schema 模式共享单数据库) + - `listBizTables` 接收 bizSchema 参数, 默认从 `base_db_link.f_full_name` 查关联 schema + - PG `listBizTables` SQL 改为 `WHERE table_schema = appCode OR table_schema = defaultSchema` (兼容独立 db + 共享 schema 两种模式) +- 需要: Maven 重编 ssw-common + JNPF 重启 (Java 不热重载) +- 风险: testspace 当前活跃测试会中断 (建议在另一空闲 app 上验证) + +### 2. dacli 端 fallback 查询 (P1, 中优) +- 当 ssw-common 业务库 preview 报 `(无表或不存在)` 时, dacli 自动 fallback 走 `dacli dm list` 端点列业务表 +- 优势: 兼容现有 ssw-common (不动 Java),扩展性 +- 改动文件: `src/commands/app/clear.ts` 的 `fetchDbPreview` 处 +- 风险: 无 (只读 fallback) + +### 3. ssw-loop 关卡增强 (P2, 低优) +- 在 `.claude/skills/ssw-loop/scripts/check_clear_coverage.sh` 加新关卡: + 跑 `dacli app clear --appCode=X --dry-run --json` 解析残留清单 + 当残留 docs/* > 5 时 WARN ("建议加 --clean-docs") +- 优势: 自动化提示 docs 残留,无需手记 +- 风险: 无 + +### 4. dacli app history 子命令 (P3, 远期) +- `dacli app history list` 列历史归档 (history-bak/{ts}/files/, history_bak schema 等) +- `dacli app history restore ` 还原单 app 的某次备份 +- 优势: --clean-docs 后有可逆路径 +- 改动: 新命令实现 + 接三层 + +## Cross-refs + +- **CLAUDE.md §"代码修改权限"**: ✅ boot/ssw-common/ 可改, ⚠️ JNPF baseline 禁止动 +- **CLAUDE.md §"ssw-loop 阶段 5: 测试"**: docs/testcase.md / summary.md 是关卡 A 必读 +- **dacli README.md §"三层处理"**: L2 silent/assertive 三级 fix 在本 ADR 中以 docs 残留警告形式落地 +- **docs/jxcj/summary.md §4.1**: M2 重启已用 `dacli app init --auto-recover` 重建 system (依赖 clear 已删 base_system) +- **docs/jxcj/plan.md §3.1**: "jxcj 应用重建" 流程本身依赖 clear 是有效清理 (本次 ADR 强化 docs 部分) +- **dacli/docs/decisions/0011-dm-drop-data-blocked.md**: 类似缺口模式 (dacli 端无法绕过 ssw-common 限制) +- **dacli/docs/decisions/0013-menu-create-currentuser-cache.md**: 前序 ADR 同样需要 JNPF 重启的修复路径 +- **Java 参考**: `docs/dacli/ssw-dacli/.../ClearAppCommand.java` 的 DOC_HTML_FILES (历史漂移源) +- **下一轮触发点**: ssw-loop 阶段 8 收尾验证时再次跑 `dacli app clear --dry-run --clean-docs`, 验证 docs/jxcj 残留 → 0