danyang-match/docs/superpowers/plans/2026-09-13-ui-cleanup-and-document-governance.md

# 旧 UI 代码与冲突文档治理实施计划

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 在不丢失有效业务代码和审计证据的前提下，删除废弃 UI 实现与冲突文档，并建立唯一有效视觉事实源。

**Architecture:** 先以只读脚本生成引用证据，再用契约测试锁定文档权威和小程序源文件唯一性，最后分批执行显式删除与修订。清理过程不使用目录级通配删除，每批都通过双端构建门禁。

**Tech Stack:** PowerShell、Node.js、Git、Vue TypeScript、微信小程序 TypeScript

**Spec:** `docs/superpowers/specs/2026-09-13-reference-driven-dual-client-ui-redesign-design.md`

## Global Constraints

- 不删除后端业务、Flyway migration、Docker volume、数据库备份或用户未授权文件。
- 只删除引用证据明确且由 Git 可恢复的文件。
- `AGENTS.md` 最终只指向 2026-09-13 新 UI 规格。
- 旧 Phase 07 视觉结果必须标记为失效，不能继续作为通过证据。
- 小程序共享 `.js` 文件如仍被纯 JavaScript 页面运行时引用，必须保留并记录原因。

---

### Task 1: 建立清理候选与引用证据

**Files:**
- Create: `scripts/audit-ui-obsolete-files.ps1`
- Create: `docs/UI_CLEANUP_INVENTORY_2026-09-13.md`
- Test: `scripts/audit-ui-obsolete-files.ps1`

**Interfaces:**
- Consumes: `admin-web/src/router/index.ts`、`miniapp/app.json`、组件注册、import/require、Markdown 链接和 Git 状态。
- Produces: `KEEP/REFACTOR/DELETE/REVIEW` 四类清单，不执行删除。

- [ ] **Step 1: 编写只读审计脚本**

```powershell
param([string]$Root = (Resolve-Path "$PSScriptRoot\.."))
$miniappPages = (Get-Content -Raw -Encoding UTF8 "$Root\miniapp\app.json" | ConvertFrom-Json).pages
$status = git -C $Root status --short
$pairs = Get-ChildItem "$Root\miniapp" -Recurse -Filter *.ts | ForEach-Object {
  $js = [IO.Path]::ChangeExtension($_.FullName, '.js')
  if (Test-Path -LiteralPath $js) { "$(Resolve-Path -Relative $_.FullName)|$(Resolve-Path -Relative $js)" }
}
[PSCustomObject]@{
  activePages = $miniappPages
  duplicateSources = $pairs
  gitStatus = $status
} | ConvertTo-Json -Depth 4
```

- [ ] **Step 2: 运行脚本并确认未删除文件**

Run:

```powershell
& .\scripts\audit-ui-obsolete-files.ps1
git status --short
```

Expected: 终端输出活动页面、同名源和 Git 状态 JSON；脚本不写文件，Git 状态没有被脚本扩大。使用 `apply_patch` 将核对后的结果写入盘点文档。

- [ ] **Step 3: 人工补齐四类判定和证据**

在盘点文档中为每项写入：分类、引用位置、替代实现、删除风险和验证命令。证据不足的项目必须标记 `REVIEW`。

- [ ] **Step 4: 提交只读盘点能力**

```powershell
git add -- scripts/audit-ui-obsolete-files.ps1 docs/UI_CLEANUP_INVENTORY_2026-09-13.md
git commit -m "chore: inventory obsolete UI files"
```

### Task 2: 建立文档单一事实源契约

**Files:**
- Create: `ui-tests/ui-document-baseline-contracts.mjs`
- Modify: `AGENTS.md`
- Modify: `docs/STATUS.md`
- Modify: `docs/JIRA_BACKLOG.md`
- Modify: `docs/Phase-07-V11-Recovery-Completion-Report-2026-09-13.md`
- Modify: `docs/UI_REDESIGN_PAGE_MATRIX_V1.1.md`
- Modify: `docs/善缘丹阳 V1.1 客户需求基线增量开发与修复计划.md`
- Modify: `docs/善缘丹阳 V1.1 当前进度校正与严格Phase修复计划.md`
- Delete: `docs/善缘丹阳 V1.1 前端 UI-UX 高保真原型修订说明.md`
- Delete: spec 第 7.2 节列出的旧 UI 规格、计划和验收文件
- Delete: spec 第 7.2 节列出的旧 Phase 07 截图
- Test: `ui-tests/ui-document-baseline-contracts.mjs`

**Interfaces:**
- Consumes: 已确认新规格、旧文档中仍有效的业务状态/权限/交互要求。
- Produces: `AGENTS.md` 唯一视觉入口和不会声明旧视觉已通过的活动文档集。

- [ ] **Step 1: 编写失败的文档契约**

```js
import assert from 'node:assert/strict'
import { existsSync, readFileSync } from 'node:fs'
import { resolve } from 'node:path'

const root = resolve(import.meta.dirname, '..')
const read = (p) => readFileSync(resolve(root, p), 'utf8')
const spec = 'docs/superpowers/specs/2026-09-13-reference-driven-dual-client-ui-redesign-design.md'
const obsolete = [
  'docs/superpowers/specs/2026-09-10-ui-v11-fidelity-design.md',
  'docs/superpowers/specs/2026-09-11-codex-baseline-cleanup-design.md',
  'docs/superpowers/specs/2026-09-11-dual-client-full-ui-redesign-design.md',
  'docs/superpowers/plans/2026-09-10-ui-v11-fidelity.md',
  'docs/superpowers/plans/2026-09-11-codex-baseline-cleanup.md',
  'docs/superpowers/plans/2026-09-11-admin-full-ui-redesign.md',
  'docs/superpowers/plans/2026-09-11-miniapp-full-ui-redesign.md',
  'docs/superpowers/plans/2026-09-11-ui-foundation-and-pilot.md',
  'docs/UI-V11-Visual-Acceptance-2026-09-10.md',
  'docs/善缘丹阳 V1.1 前端 UI-UX 高保真原型修订说明.md',
  'design-qa.md',
]
assert.ok(read('AGENTS.md').includes(spec), 'AGENTS.md 未指向唯一视觉规格')
for (const file of obsolete) assert.equal(existsSync(resolve(root, file)), false, `旧有效文档仍存在: ${file}`)
assert.match(read('docs/STATUS.md'), /Phase 07.*视觉.*(否决|重新实现|待验收)/s)
assert.doesNotMatch(read('docs/Phase-07-V11-Recovery-Completion-Report-2026-09-13.md'), /视觉验收.*通过/)
console.log('UI document baseline contracts passed')
```

- [ ] **Step 2: 运行契约确认失败**

Run: `node ui-tests/ui-document-baseline-contracts.mjs`

Expected: FAIL，首先报告 `AGENTS.md` 未指向新规格或旧文档仍存在。

- [ ] **Step 3: 迁移有效规则并修订活动文档**

将旧高保真文档中仍有效的业务状态、权限、错误状态和可访问性要求逐条核对到新规格、页面功能文档或 API 文档；在迁移清单中记录目标章节。随后更新 `AGENTS.md`、状态、JIRA、Phase 07 报告和页面矩阵。

- [ ] **Step 4: 显式删除旧文档与失败截图**

使用以下数组中的每个 `$path` 调用 `git ls-files --error-unmatch -- $path` 区分已跟踪和未跟踪文件，再执行显式列表；不得使用递归删除或通配符。

```powershell
$trackedObsolete = @(
  'docs/superpowers/specs/2026-09-10-ui-v11-fidelity-design.md',
  'docs/superpowers/specs/2026-09-11-codex-baseline-cleanup-design.md',
  'docs/superpowers/specs/2026-09-11-dual-client-full-ui-redesign-design.md',
  'docs/superpowers/plans/2026-09-10-ui-v11-fidelity.md',
  'docs/superpowers/plans/2026-09-11-codex-baseline-cleanup.md',
  'docs/superpowers/plans/2026-09-11-admin-full-ui-redesign.md',
  'docs/superpowers/plans/2026-09-11-miniapp-full-ui-redesign.md',
  'docs/superpowers/plans/2026-09-11-ui-foundation-and-pilot.md',
  'docs/UI-V11-Visual-Acceptance-2026-09-10.md',
  'docs/善缘丹阳 V1.1 前端 UI-UX 高保真原型修订说明.md'
)
foreach ($path in $trackedObsolete) {
  if (git ls-files --error-unmatch -- $path 2>$null) { git rm -- $path }
}
$untrackedObsolete = @(
  'design-qa.md',
  'artifacts/phase07-miniapp-home.png',
  'artifacts/phase07-miniapp-discover.png',
  'artifacts/phase07-home-comparison.png',
  'artifacts/phase07-discover-comparison.png'
)
foreach ($path in $untrackedObsolete) {
  $resolved = Resolve-Path -LiteralPath $path -ErrorAction SilentlyContinue
  if ($resolved -and $resolved.Path.StartsWith((Resolve-Path '.').Path)) {
    Remove-Item -LiteralPath $resolved.Path
  }
}
```

- [ ] **Step 5: 运行文档契约**

Run:

```powershell
node ui-tests/ui-document-baseline-contracts.mjs
rg -n "2026-09-10-ui-v11-fidelity|2026-09-11-dual-client-full-ui-redesign|视觉验收.*通过" AGENTS.md docs
```

Expected: 契约 PASS；`rg` 只允许在新规格和清理报告的历史删除清单中命中。

- [ ] **Step 6: 提交文档治理**

```powershell
git add -- AGENTS.md docs/STATUS.md docs/JIRA_BACKLOG.md docs/Phase-07-V11-Recovery-Completion-Report-2026-09-13.md docs/UI_REDESIGN_PAGE_MATRIX_V1.1.md 'docs/善缘丹阳 V1.1 客户需求基线增量开发与修复计划.md' 'docs/善缘丹阳 V1.1 当前进度校正与严格Phase修复计划.md' ui-tests/ui-document-baseline-contracts.mjs
git commit -m "docs: retire conflicting UI baselines"
```

### Task 3: 处理小程序 TypeScript/JavaScript 同名源

**Files:**
- Create: `ui-tests/miniapp-source-uniqueness-contracts.mjs`
- Modify: 当前 11 个同名页面的 `.ts` 文件（仅在行为缺失时）
- Delete: `miniapp/pages/activity-mutual-result/activity-mutual-result.js`
- Delete: `miniapp/pages/activity-mutual-waiting/activity-mutual-waiting.js`
- Delete: `miniapp/pages/chat/chat.js`
- Delete: `miniapp/pages/counseling-intro/counseling-intro.js`
- Delete: `miniapp/pages/counseling-request/counseling-request.js`
- Delete: `miniapp/pages/local-eligibility/local-eligibility.js`
- Delete: `miniapp/pages/local-eligibility-supplement/local-eligibility-supplement.js`
- Delete: `miniapp/pages/login/login.js`
- Delete: `miniapp/pages/my-counseling/my-counseling.js`
- Delete: `miniapp/pages/premarital-intro/premarital-intro.js`
- Delete: `miniapp/pages/premarital-request/premarital-request.js`
- Keep: `miniapp/env.js`
- Keep: `miniapp/utils/api.js`
- Test: `ui-tests/miniapp-source-uniqueness-contracts.mjs`

**Interfaces:**
- Consumes: `project.config.json` 的 TypeScript 编译器、页面 `.js/.ts` 行为差异和现有 JS 页面对共享模块的依赖。
- Produces: 页面级 TypeScript 唯一手写源；共享 JS 兼容层暂时保留并有明确理由。

- [ ] **Step 1: 编写失败的页面唯一源契约**

```js
import assert from 'node:assert/strict'
import { existsSync, readdirSync } from 'node:fs'
import { extname, join, resolve } from 'node:path'

const pages = resolve(import.meta.dirname, '../miniapp/pages')
const duplicates = []
for (const dir of readdirSync(pages, { withFileTypes: true }).filter((item) => item.isDirectory())) {
  const base = join(pages, dir.name, dir.name)
  if (existsSync(`${base}.ts`) && existsSync(`${base}.js`)) duplicates.push(dir.name)
}
assert.deepEqual(duplicates, [], `页面仍有 TS/JS 双源: ${duplicates.join(', ')}`)
console.log('Miniapp page sources are unique')
```

- [ ] **Step 2: 运行契约确认失败**

Run: `node ui-tests/miniapp-source-uniqueness-contracts.mjs`

Expected: FAIL，并列出 activity-mutual、chat、counseling、local-eligibility、login、premarital 等重复页面。

- [ ] **Step 3: 逐页比较行为并补齐 TypeScript**

对每一对文件使用 `git diff --no-index -- <page>.js <page>.ts`，确认 API 路径、事件处理、状态字段和路由均保留。只将 `.js` 中仍有效且 `.ts` 缺失的行为迁入 `.ts`。

- [ ] **Step 4: 显式删除页面 JavaScript 双源**

逐个删除盘点中确认的页面 `.js`，不删除 `miniapp/env.js` 和 `miniapp/utils/api.js`，因为其仍被未迁移的 JavaScript 页面使用。

- [ ] **Step 5: 验证唯一源和编译**

Run:

```powershell
node ui-tests/miniapp-source-uniqueness-contracts.mjs
npm --prefix miniapp run type-check
node ui-tests/miniapp-auth-contracts.mjs
node ui-tests/phase04-local-eligibility-contracts.mjs
```

Expected: 全部 PASS；微信开发者工具编译插件继续以 `.ts` 生成运行代码。

- [ ] **Step 6: 提交页面源清理**

```powershell
git add -- miniapp/pages/activity-mutual-result miniapp/pages/activity-mutual-waiting miniapp/pages/chat miniapp/pages/counseling-intro miniapp/pages/counseling-request miniapp/pages/local-eligibility miniapp/pages/local-eligibility-supplement miniapp/pages/login miniapp/pages/my-counseling miniapp/pages/premarital-intro miniapp/pages/premarital-request ui-tests/miniapp-source-uniqueness-contracts.mjs
git commit -m "refactor: remove duplicate miniapp page sources"
```

### Task 4: 清理剩余无引用 UI 资产并生成报告

**Files:**
- Modify: `docs/UI_CLEANUP_INVENTORY_2026-09-13.md`
- Create: `docs/UI_CLEANUP_REPORT_2026-09-13.md`
- Delete: 本任务不新增删除目标；证据不足的组件、样式和素材保留为 `REVIEW`
- Test: 现有全部 UI contract tests

**Interfaces:**
- Consumes: 盘点文档、引用证据、前两项任务的删除结果。
- Produces: 可审核的清理报告和保持可构建的双端代码库。

- [ ] **Step 1: 对候选资产执行引用复核**

Run:

```powershell
$candidateNames = Select-String -Path 'docs/UI_CLEANUP_INVENTORY_2026-09-13.md' -Pattern '^\| DELETE \|' | ForEach-Object { ($_ -split '\|')[2].Trim() }
foreach ($candidateName in $candidateNames) {
  rg -n --fixed-strings $candidateName admin-web miniapp ui-tests docs
  git ls-files -- "*$candidateName*"
}
```

Expected: 仅当运行代码、配置和测试均无引用时才保持 `DELETE`；否则改为 `KEEP/REFACTOR/REVIEW`。

- [ ] **Step 2: 分批显式删除并立即回归**

本轮只执行 Task 2 与 Task 3 已列明的精确删除目标。其他无引用组件、样式或素材即使进入候选清单，也保持 `REVIEW`；需要新增精确路径并获得确认后，才能加入后续清理批次。

- [ ] **Step 3: 运行清理总门禁**

```powershell
node ui-tests/ui-document-baseline-contracts.mjs
node ui-tests/miniapp-source-uniqueness-contracts.mjs
node ui-tests/ui-contracts.mjs
node ui-tests/admin-redesign-contracts.mjs
node ui-tests/miniapp-redesign-contracts.mjs
npm --prefix admin-web run type-check
npm --prefix admin-web run build
npm --prefix miniapp run type-check
git diff --check
```

Expected: 全部通过；如旧视觉契约本身已被新规格废弃，应在 Task 2 中先删除或改写该契约，不能为通过测试保留错误设计。

- [ ] **Step 4: 写清理报告**

报告必须包含：删除文件、保留文件及原因、待确认项、清理前后文件数、执行命令、测试结果、可恢复提交和未触及范围。

- [ ] **Step 5: 提交并暂停等待用户确认**

```powershell
git add -- docs/UI_CLEANUP_INVENTORY_2026-09-13.md docs/UI_CLEANUP_REPORT_2026-09-13.md
git commit -m "chore: remove obsolete UI implementation"
```

Expected: 完成清理 Completion Report；不得自动进入管理端重构。