事实: 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
8.3 KiB
8.3 KiB
0014-app-clear-docs-coverage
日期: 2026-07-21 状态: Accepted (dacli 端已落地
--clean-docsflag) 作者: 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+):
- 加
--clean-docsflag (默认 false): 用户显式 trigger 时把 docs/{app}/ 整体移到 history-bak/{ts}/files/docs/{app}/ - DRY-RUN 默认行为升级: docs/{app}/ 存在时警告残留项数 +
--clean-docs提示,让用户知情 - 不强制清 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-docsflag, 默认 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用于残留检测
- L246-252 (接口 ClearOpts): 加
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
listBizTablesSQL 改为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