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
This commit is contained in:
1 parent
60adaab4b1
commit
f7bc8d55d0
2 files changed
+159
No files matched your search
@@ -303,6 +303,7 @@ dacli form update <id> --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 |
|
||||
|
||||
---
|
||||
|
||||
@@ -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`): 警告文案中 `<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
|
||||
Reference in new issue
Block a user