Files
dacli/docs/decisions/0014-app-clear-docs-coverage.md
T
ssw f7bc8d55d0 docs(0014-app-clear-docs-coverage): app clear docs 残留缺口决策记录
事实: docs/jxcj 实测 14 项残留 (8 MD + 4 子目录 + 设计说明)
      不被清理, 历史 DOC_HTML_FILES 只清 4 html

根因: docs/dacli/ssw-dacli/.../ClearAppCommand.java 用 DOC_HTML_FILES 白名单
      Dacli 也复用了同样限制, 漏了所有非 html 文件

修复 (P1-2d commit 60adaab): dacli 端加 --clean-docs flag (默认 false 保持向后兼容)
  true:  docs/{app}/ 整体打包成 FileTarget, 移到 history-bak/{ts}/files/docs/{app}/
  false: 历史行为 + DRY-RUN 警告提示残留项数 + 提示 --clean-docs

决策依据:
- docs/{app}/ 是 ssw-loop 关卡 A/B/C 强依赖 (design/testcase/summary/learnings/plan/debug + _assets 6+ MD)
- 默认不改, 用户显式加 --clean-docs 才真清, history-bak 保留可还原
- 与 P0-3 (2026-07-15) DB fallback 同模式: --no-relation-form-auto / --autoRelease 等 flag

已知 ssw-common 端点 bug (留下游路线 §1):
- DbClearServiceImpl.listBizTables 走 openConn(appCode, null) 把 jxcj 当独立 db
- 但 jxcj 在 PG 共享库 j62 schema=jxcj, 不是独立 db
- 修复需要改 Java 5-10 处 + Maven 编译 + JNPF 重启 (Java 无 devtools auto-reload)
- 风险: testspace 当前活跃测试会中断
- 跨项目路线, 不在 dacli 端实现

下游路线 (ADR §Downstream):
1. ssw-common 端点改进 (跨项目, 高优)
2. dacli 端 fallback 查询 (P1, 中优)
3. ssw-loop 关卡 check_clear_coverage.sh (P2, 低优)
4. dacli app history 子命令 (P3, 远期)

E2E 验证 (testspace 默认应用):
- DRY-RUN --clean-docs 显示 [MOVE] docs/testspace/ 整体打包
- 业务库 preview 列出 72 张表 (testspace schema=public 正常工作)
- jxcj schema=public 不识别业务表 (符合 ADR §已知风险)

README 路径速查表加 "--clean-docs 行为" 行, 指向 0014-ADR
2026-07-21 15:47:19 +08:00

8.3 KiB
Raw Blame History

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/ 默认 — 符合 "设计依据默认保留" 原则,向后兼容
# 行为 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): 警告文案中 <ts-yyyyMMdd-HHmmss> 占位符
    • 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 <ts> 还原单 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