Files

T

Codex c66e42dd8a docs: retire conflicting UI baselines

2026-09-13 21:12:50 +08:00

14 KiB

Raw Blame History

旧 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: 编写只读审计脚本

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:

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

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

Step 3: 人工补齐四类判定和证据

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

Step 4: 提交只读盘点能力

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: 编写失败的文档契约

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 区分已跟踪和未跟踪文件，再执行显式列表；不得使用递归删除或通配符。

$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:

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: 提交文档治理

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: 编写失败的页面唯一源契约

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:

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: 提交页面源清理

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:

$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: 运行清理总门禁

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/phase07-home-contracts.mjs
node ui-tests/brand-assets.mjs
node ui-tests/tabbar-icons.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: 提交并暂停等待用户确认

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；不得自动进入管理端重构。

14 KiB Raw Blame History Unescape Escape

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

Global Constraints

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

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

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

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

14 KiB

Raw Blame History