danyang-match/docs/superpowers/plans/2026-09-14-development-execution-plan.md

# 善缘丹阳 V1.1 开发执行计划

**日期**: 2026-09-14  
**分支**: `workbuddy-ui-v11-fidelity`  
**性质**: 当前进度评估 + 可直接执行的开发计划（替代并细化同日进度评估文档，不与既有 Phase 计划冲突）

---

## 一、当前进度评估（代码实际 vs 文档声明）

### 1.1 文档优先级基线（最近修改优先）

| # | 文件 | 修改时间 | 作用 |
|---|------|---------|------|
| 1 | `superpowers/specs/2026-09-13-reference-driven-dual-client-ui-redesign-design.md` | 9/13 20:02 | **唯一 UI 视觉验收基线**（用户已确认） |
| 2 | `superpowers/plans/2026-09-13-reference-driven-dual-client-ui-redesign.md` | 9/13 20:06 | **UI 重设计唯一总计划**（清理→管理端→小程序→终验） |
| 3 | `善缘丹阳 V1.1 客户需求基线增量开发与修复计划.md` | 9/13 20:18 | **业务 Phase 唯一执行计划** |
| 4 | `UI_CLEANUP_REPORT_2026-09-13.md` | 9/13 21:26 | UI 旧代码/冲突文档治理结论 |
| 5 | `ADMIN_REFERENCE_UI_QA_2026-09-13.md` | 9/13 22:06 | 管理端参考图 UI 验收记录 |
| 6 | `STATUS.md` | 9/13 20:17 | 当前有效状态台账 |

**核心约束**：两张参考图是唯一视觉来源；内置业务不变量（免费、Required 不放宽、Mutual 后聊天、Block 最高优先、活动互选双确认、Counselor 仅 Assigned、ContentEditor 零用户数据、服务站不可浏览全库、前端入口由服务端 Capability 决定）；管理端第一批 = 全局框架 + 工作台；小程序第一批 = 11 个核心页。

### 1.2 Git 提交历史（2026-09-13 清理后）

```
1aea6f7 feat: redesign public relationship services        ← 红娘/咨询/婚前（小程序 B 组最后一页）
a6037de feat: redesign activity and profile tabs           ← 活动/我的（小程序 A 组）
b7dc52b feat: redesign discovery and messages tabs         ← 找对象/消息（小程序 A 组）
36b15d9 feat: rebuild miniapp reference home               ← 首页（小程序 A 组）
df47543 feat: add miniapp reference assets and primitives ← 小程序公共设计令牌/组件
311f251 test: lock miniapp reference page scope
8b8972a test: verify admin reference UI fidelity            ← 管理端参考图 QA
72b0758 feat: recreate admin dashboard from reference      ← 管理端工作台
fbafe69 feat: add admin dashboard data adapter             ← 管理端数据适配层
9279359 feat: rebuild admin shell from reference           ← 管理端壳层
ad9d32f feat: establish admin reference design foundation  ← 管理端设计基础
3a634b4 docs: finalize UI cleanup report
097c4c4 chore: finalize miniapp page source cleanup
61ca737 docs: record UI cleanup checkpoint
eed4400 refactor: remove duplicate miniapp page sources
c66e42d docs: retire conflicting UI baselines
1deda1e chore: inventory obsolete UI files
```

### 1.3 代码实际进度 vs 文档声明偏差表

| 维度 | 代码实际状态 | 文档/计划声明 | 偏差 |
|------|------------|--------------|------|
| **Git 未提交改动** | **56 个**（M）+ 未跟踪（??）详见下 | 计划 checkbox 全未勾 | **代码超前于计划** |
| **Flyway 迁移** | **V035**（V028~V035 含服务站范围/权限补齐/软删/审计对齐） | STATUS 记录 V001~V027 | **文档滞后 8 个迁移** |
| **CapabilityService** | **不存在独立类**，禁用逻辑内嵌 HomeApplicationService L324 | 进度校正计划要求"新建独立 Service" | **业务架构债务未清** |
| **管理端壳层+工作台** | ✅ 已提交并通过参考图 QA（ADMIN_REFERENCE_UI_QA） | 总计划 Task 2 未勾 | **需同步勾选** |
| **小程序 A 组（5 个 Tab 页）** | ✅ 已提交 | 总计划 Task 3 未勾 | **需同步勾选** |
| **小程序 B 组（6 个服务页）** | ✅ 已提交（红娘/咨询/婚前） | 总计划 Task 3 未勾 | **需同步勾选** |
| **小程序 C 组（课堂/反诈/服务站）** | ⚠️ **未提交 + 仍是 `.js` + WXML 仅 18~20 行（脚手架级别）** | 总计划 Task 3 未勾 | **核心缺口** |
| **后端 HomeApplicationService** | ⚠️ 有未提交改动（HomeDTO 也在 M 列表） | Phase 07 报告声明已完成 | **在途改动需确认** |
| **后端全量回归** | 277 tests → 4 failures、8 errors、3 skips | Phase 报告大量"✅ 通过" | **可信度债务** |
| **admin-web 业务 Vue** | ✅ 19 个模块 Vue 存在（含 banner/content/service-station/counseling 等） | 计划只提了壳层+工作台 | **代码超前** |
| **小程序 TS/JS 双轨** | C 组仍是 `.js`（anti-fraud/content/service-station） | 清理报告称"双源已清零" | **C 组未纳入清理** |

### 1.4 未提交改动详细分布

**已修改（M）** — 56 项：
- **后端核心**：HomeDTO、HomeApplicationService、LocalEligibilityService、MatchEligibilityService、RecommendationEngineService、RelationshipService、ReviewService/Controller/Mapper/DTO、SensitiveAccessLog、PhotoService、FeatureFlagConfig、application-docker.yml
- **管理端**：ReviewView.vue
- **小程序 C 组**：anti-fraud(.js/.json/.wxml/.wxss)、content(.js/.json/.wxml/.wxss)、service-station(.js/.json/.wxml/.wxss)
- **小程序公共**：env.js、env.ts、default-avatar.png、local-eligibility(.wxml)、local-eligibility-supplement(.wxml)
- **基础设施**：docker-compose.yml、nginx.conf、project.config.json
- **UI 契约**：miniapp-reference-contracts.mjs

**未跟踪（??）**：
- 参考图 2 张、UI 重设计小程序截图（artifacts/ui-redesign/miniapp/）
- Flyway V034/V035 迁移
- 4 份 Recovery Completion Report（Phase-04~06 已交付文档未落提交）
- UI 测试：phase06-match-eligibility-contracts.mjs
- 测试类：RecommendationEligibilityPhase06Test、RelationshipBlockPriorityPhase08Test、ReviewServicePhase05Test、local_eligibility 测试目录
- 评估计划本文档

### 1.5 综合进度结论

```
业务闭环（可验收）: ████████████████░░░░░░░░░░░░░░  ~40%~50%
UI 重设计（首批 11+1）: ████████████████░░░░░░░░░░  ~75%（缺 C 组）
后端 Phase 01~07 Recovery: ██████████████████████░░  ~95%（回归非全绿）
后端 Phase 08~26: ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  ⏸ 暂停
文档与代码口径一致度: ██████░░░░░░░░░░░░░░░░░░░░░░  ~30%（严重滞后）
自动化测试可信度: ███░░░░░░░░░░░░░░░░░░░░░░░░░░░░  ~15%
```

**整体 NO-GO**。核心矛盾：**代码超前、文档滞后、存在大量未提交在途改动，C 组小程序页面仅为脚手架**。

---

## 二、开发计划

### 计划原则

1. **先收口再推进**：必须先把 56 个未提交改动和 C 组脚手架收口，否则任何验收都是空中楼阁。
2. **用户验收门禁**：每个阶段完成后输出证据、等待人工确认，不自动进入下一阶段。
3. **真实后端联调**：UI 验收必须对接真实 API，不使用虚构数据。
4. **防偏航**：所有视觉实现必须对照两张参考图，以 ADMIN_REFERENCE_UI_QA 的验收标准执行。

---

### 阶段 0：在途工作收口（最高优先 — 预计 1~2 天）

#### 目标
消除 Git 工作区的不确定性，建立代码与文档的一致基线。

#### 任务清单

| # | 任务 | 产物 | 依赖 |
|---|------|------|------|
| 0.1 | **运行现有门禁，记录真实输出** | 门禁输出日志 | 无 |
| 0.1.1 | `backend` 全量测试，记录 failures/errors/skips | `docs/gate-output/backend-tests-2026-09-14.txt` | Docker 或 JDK 环境 |
| 0.1.2 | `admin-web` type-check + build | `docs/gate-output/admin-typecheck-2026-09-14.txt`、`admin-build-2026-09-14.txt` | Node.js + pnpm |
| 0.1.3 | `miniapp` type-check | `docs/gate-output/miniapp-typecheck-2026-09-14.txt` | Node.js + tsc |
| 0.1.4 | 运行全部 `ui-tests/*.mjs` 契约测试 | 各测试输出文件 | Node.js |
| 0.2 | **分类 56 个未提交改动** | 分类清单 | 0.1 |
| 0.2.1 | 确认 C 组（anti-fraud/content/service-station）的 `.js` 是脚手架还是有实质内容 | 分类：可删/需改/保留 | — |
| 0.2.2 | 确认 HomeApplicationService/HomeDTO 未提交改动的性质（UI 适配？业务修复？Capability 内嵌？） | 分类：合并/回退 | — |
| 0.2.3 | 确认 V034/V035 迁移和 4 份测试类是否应该纳入版本控制 | 分类：commit/忽略 | — |
| 0.2.4 | 确认 docker-compose.yml/nginx.conf/project.config.json 改动是否为本地配置还是应该共享 | 分类：commit/.gitignore | — |
| 0.3 | **分批提交在途改动** | Git 提交记录 | 0.2 |
| 0.3.1 | 提交文档类：4 份 Recovery Completion Report + 评估计划 + phase06 契约 | 独立 commit | — |
| 0.3.2 | 提交后端类：V034/V035 迁移 + 测试类 + FeatureFlagConfig/PhotoService/Review 相关改动 | 独立 commit | 需后端编译通过 |
| 0.3.3 | 提交 Home 类：HomeDTO + HomeApplicationService（确认无冲突后） | 独立 commit | 需 0.2.2 结论 |
| 0.3.4 | 提交 admin-web：ReviewView.vue | 独立 commit | — |
| 0.3.5 | 提交 miniapp 公共：env.{ts,js} + default-avatar + local-eligibility WXML | 独立 commit | — |
| 0.4 | **更新文档基线** | STATUS.md、JIRA_BACKLOG.md | 0.3 |
| 0.4.1 | 在 STATUS.md 记录 V028~V035 迁移内容 | — | 0.3.2 |
| 0.4.2 | 在 STATUS.md 标记管理端壳层+工作台、小程序 A/B 组已提交 | — | 0.3 全部完成 |
| 0.4.3 | 在 JIRA_BACKLOG.md 同步 checkbox | — | 0.3 全部完成 |
| 0.5 | **Git 工作区清零** | `git status` 无 M / 必要 ?? 已 commit 或 .gitignore | 0.3 全部完成 |

#### 退出门禁
- [ ] `git status --short` 输出 0 行或仅有预期 ??（如 IDE 配置）
- [ ] backend tests 输出已真实记录（不管通过与否）
- [ ] admin type-check + build 输出已真实记录
- [ ] miniapp type-check 输出已真实记录
- [ ] 所有计划文档 checkbox 与 Git 提交记录一致
- [ ] **用户确认收口完成**

---

### 阶段 1：小程序 C 组重设计 + TypeScript 化（预计 2~3 天）

#### 目标
完成 UI 重设计规格要求的最后 3 个核心页面，消除 TS/JS 双轨。

#### 任务清单

| # | 任务 | 说明 | 依赖 |
|---|------|------|------|
| 1.1 | **将 anti-fraud 迁移为 TypeScript 唯一源** | 当前 `.js` + 18 行 WXML 脚手架，需按参考图重设计，提供防骗文章列表 + 详情入口 | 阶段 0 |
| 1.2 | **将 content（婚恋课堂）迁移为 TypeScript 唯一源** | 当前 `.js` + 18 行 WXML 脚手架，需按参考图重设计，提供课堂文章列表 + 详情 + 分类筛选 | 阶段 0 |
| 1.3 | **将 service-station 迁移为 TypeScript 唯一源** | 当前 `.js` + 20 行 WXML 脚手架，需按参考图重设计，展示服务站地址/时间/预约入口 | 阶段 0 |
| 1.4 | **对齐设计令牌与已完成页面** | 复用 `home.css` 中的品牌 Token、按钮、卡片、空状态、错误状态样式 | 1.1~1.3 |
| 1.5 | **接入真实后端 API** | 内容列表→`GET /api/v1/content/articles`；服务站→`GET /api/v1/service-locations`；反诈→复用内容 API 过滤 category | 后端 Home 已完成 |
| 1.6 | **运行门禁** | `node ui-tests/miniapp-reference-contracts.mjs` + `tsc --noEmit` + 微信开发者工具编译 | 1.1~1.5 |
| 1.7 | **截图比对 + 提交** | 3 页面截图 → `artifacts/ui-redesign/miniapp/` → 独立 commit | 1.6 通过 |

#### 退出门禁
- [ ] anti-fraud / content / service-station 均为 `.ts` 唯一源（无同名 `.js`）
- [ ] 3 页面均能在微信开发者工具中编译通过
- [ ] 真实 API 数据可加载（空数据时有 Skeleton/空状态降级）
- [ ] 设计 Token 一致（颜色、卡片圆角、间距、按钮样式）
- [ ] 截图与参考图视觉对齐（ADMIN_REFERENCE_UI_QA 同等级验收）
- [ ] **用户确认 C 组完成**

---

### 阶段 2：管理端业务 Vue 新框架适配（预计 2 天）

#### 目标
将已存在的 19 个 admin-web 业务 Vue 迁移到参考图驱动的新壳层框架中，不逐页重绘视觉，但保证路由/权限/布局可用。

#### 说明
管理端第一批只重绘全局壳层和工作台（已完成并通过 QA），其余业务页面按规格"不进行逐页高保真重构，但必须继续在新框架中可用，且不得破坏路由、权限和操作流程"。

#### 任务清单

| # | 任务 | 说明 | 依赖 |
|---|------|------|------|
| 2.1 | **验证现有 19 个业务 Vue 在新壳层下可用** | 逐个打开 banner/content/service-station/appointment/program/counseling/referral/analytics/review/risk/user 等路由 | 阶段 0 |
| 2.2 | **修复路由问题** | 如有路由跳转/404/侧栏菜单不匹配，修复 router/index.ts | 2.1 |
| 2.3 | **修复权限问题** | 确保七类后台角色只看到自己的工作，无越权菜单跳转/URL 访问 | 2.1 |
| 2.4 | **修复布局问题** | 业务页面在新深色侧栏 + 白色壳层下溢出/截断/对齐问题 | 2.1 |
| 2.5 | **运行门禁** | `admin-reference-contracts.mjs` + `admin-dashboard-data-contracts.mjs` + type-check + build | 2.1~2.4 |
| 2.6 | **提交** | 独立 commit | 2.5 通过 |

#### 退出门禁
- [ ] 19 个业务模块路由均可访问
- [ ] 七类角色权限隔离正确（正向 200 / 负向 403/404）
- [ ] type-check + build 零错误
- [ ] 控制台无 error/warning
- [ ] **用户确认管理端框架适配完成**

---

### 阶段 3：CapabilityService 独立化 + 文档基线治理（可与阶段 1/2 并行，预计 1 天）

#### 目标
消除业务架构债务和文档滞后，为 Phase 08+ 恢复打好基础。

#### 任务清单

| # | 任务 | 说明 | 依赖 |
|---|------|------|------|
| 3.1 | **抽出独立 CapabilityService** | 从 HomeApplicationService 中抽取禁用原因逻辑（当前 L324 `setDisabledReason`），形成独立 `com.danyang.match.platform.capability.CapabilityService`，Home 只聚合不复制规则 | 阶段 0 的 Home 未提交改动分类 |
| 3.2 | **V028~V035 迁移文档登记** | 在 `docs/database/MIGRATION_GUIDE.md`、`docs/database/TABLE_INVENTORY.md`、`善缘丹阳 V1.1 数据库与API增量设计.md` 补充 V028~V035 内容 | 阶段 0 |
| 3.3 | **backend 测试债务登记** | 对 4 failures / 8 errors / 3 skips 逐项登记责任人/原因/修复计划，挂 `Phase 08+` 待办 | 阶段 0 的测试输出 |
| 3.4 | **提交** | CapabilityService 独立 commit；文档更新独立 commit | 3.1~3.3 |

#### 退出门禁
- [ ] CapabilityService 独立类存在且 HomeApplicationService 改为调用而非内嵌
- [ ] 禁用原因来自 `CapabilityService.getEntryStatus(userId, entryCode)` 而非直接 if/else
- [ ] V028~V035 在迁移指南中有完整记录
- [ ] **用户确认架构与文档基线对齐**

---

### 阶段 4：双端总验收（预计 1~2 天）

#### 目标
对应 UI 重设计规格 Stage 6：交付唯一视觉基线。

#### 任务清单

| # | 任务 | 说明 | 依赖 |
|---|------|------|------|
| 4.1 | **运行全部契约测试** | 7 个 mjs 测试全部退出码 0 | 阶段 1~3 全部完成 |
| 4.2 | **运行双端构建检查** | admin type-check + build；miniapp tsc + 开发者工具编译 | 阶段 1~3 全部完成 |
| 4.3 | **管理端双分辨率截图验收** | 1366×768 + 1920×1080 截图对比参考图 | 阶段 2 |
| 4.4 | **小程序 11 页逐页截图验收** | 11 张截图 + 参考图对比 | 阶段 1 |
| 4.5 | **业务不变量回归** | 手动验证：Required 不放宽、Mutual 后才聊天、Block 后不可见、活动互选二阶段、入口由 Capability 控制 | Phase 01~07 业务逻辑 |
| 4.6 | **文档同步** | STATUS.md / JIRA_BACKLOG.md / 三份计划 checkbox 全部与 Git 记录一致 | 阶段 0 |
| 4.7 | **Git Tag + Completion Report** | 打 `ui-v11-fidelity` tag，输出 UI 重设计总 Completion Report | 4.1~4.6 |

#### 退出门禁
- [ ] 7 个契约测试 + 双端构建 + 编译全部通过
- [ ] 截图验收无 P0/P1 缺陷
- [ ] 业务不变量无回归
- [ ] 文档与代码 100% 一致
- [ ] **用户完成最终截图验收并签批**

---

### 阶段 5：后端业务恢复 — Phase 08~26（UI 验收后执行，每 Phase 单独报告）

> **不早于阶段 4 完成并签批**。Phase 顺序严格按 `善缘丹阳 V1.1 客户需求基线增量开发与修复计划.md` 执行，每 Phase 输出 Completion Report 并暂停。

| Phase | 名称 | 类型 | 核心任务 |
|-------|------|------|---------|
| 08 | Like / Match / Block | KEEP-VERIFY/EXTEND | 验证全链路 + Activity Match 兼容 + Block 全链路 |
| 09 | Text Chat | KEEP-VERIFY/EXTEND | REST+WS、幂等、活动 Conversation 复用 |
| 10 | Image & Chat Safety | KEEP-VERIFY | 风险关键词 + 限流 + 首次安全提示 |
| 11 | Notification 事务后发送 | KEEP-VERIFY | 6 种新类型通知 + 审核通知 |
| 12 | Relationship 轻量扩展 | KEEP-VERIFY | 服务建议规则 |
| 13 | 红娘转介 | KEEP-VERIFY | 咨询/活动/服务站转介 + 二阶段确认 |
| 13A | 咨询权限与状态机 | KEEP-VERIFY | INV-012 + 状态流转 |
| 14 | 多类型公益活动 | KEEP-VERIFY | 6 个新字段 + 多组织 + 容量分组 |
| 15 | 活动签到 | KEEP-VERIFY | 扫码/手动签到 |
| 16 | 活动互选二阶段确认事务 | REFACTOR | INV-014/015 双方确认后才建 Match |
| 17 | 风控 | KEEP-VERIFY | 扩展 risk 来源 |
| 18 | 申诉 | KEEP-VERIFY | appeal 模块 |
| 19 | 统一运营后台 | KEEP-VERIFY/EXTEND | Banner + Content + Program 管理 |
| 20 | Analytics 真实口径 | KEEP-VERIFY | 11 项统计指标 |
| 21 | Account Lifecycle | KEEP-VERIFY | 注销时级联取消 |
| 22 | Deployment/Ops | KEEP-VERIFY | Feature Flags + 配置 |
| 23 | 可信系统测试重建 | REFACTOR | 清除空 pass，实现 INV-001~020 真实测试 |
| 24 | UAT | ADD | 分角色闭环 + 线下链路 |
| 25 | RC 内容填充 | ADD | 运营提供真实素材 |
| 26 | Production 初始化 | ADD | 生产迁移 + Smoke |

---

### 阶段 6：发布前序（UAT → RC → Production）

- UAT：分角色（群众/红娘/Counselor/ContentEditor/ServiceStationOperator/Manager）闭环验收
- RC：真实内容填充 + 安全/隐私/无障碍/弱网复检 + Go/No-Go 清单
- Production：备份/恢复演练 + V027~V035 向前迁移 + Smoke + 回滚手册

---

## 三、风险与对策

| # | 风险 | 影响 | 对策 |
|---|------|------|------|
| R1 | 56 个未提交改动分类不清导致提交后回滚 | 延误阶段 0 | 每类改动单独 commit，在途改动分类记录在 `docs/gate-output/` 下 |
| R2 | C 组 `.js` 脚手架内容过少，需要从零构建 | 阶段 1 耗时超预期 | 按参考图风格快速搭建骨架，先保证视觉 + 空状态，再接真实 API |
| R3 | CapabilityService 独立化引入回归 | 首页入口行为变化 | 独立 commit + 单元测试 + 契约测试，不与 UI 改动混在一起 |
| R4 | 后端 277 tests 的 4 failures/8 errors/3 skips 阻塞 | 阶段 0 无法输出干净结果 | 登记为"已知债务"，阶段 0 只要求记录，阶段 5 Phase 23 统一清零 |
| R5 | 管理端业务 Vue 在新壳层下布局错乱 | 阶段 2 阻塞 | 按"路由→权限→布局"顺序逐项验证，有问题先修复再推进 |
| R6 | 真实后端联调环境不可用（Docker Desktop 问题） | 无法验证 API 数据 | 优先启动本地 backend，或用 Seed 数据 + Mock 降级 |
| R7 | 参考图驱动但缺少明确像素级规格 | 验收主观性 | 按 ADMIN_REFERENCE_UI_QA 的验收标准（P0/P1/P2/P3）执行，有争议处优先参考图 |

---

## 四、执行方式建议

本文档可直接加载执行。建议：
1. 从阶段 0 开始，严格按任务编号顺序执行。
2. 每个阶段完成后暂停，展示证据，等待用户签批后再进入下一阶段。
3. 如需并行阶段 3（CapabilityService）与阶段 1（小程序 C 组），建议 CapabilityService 改动独立 commit 不与 UI commit 混合。
4. 所有 Git commit message 遵循 `feat:` / `fix:` / `docs:` / `test:` / `refactor:` / `chore:` 前缀规范。

---

## 五、当前立即行动项

如果现在开始执行，第一步是：

```powershell
# 1. 创建 gate-output 目录
mkdir docs/gate-output

# 2. 跑后端全量测试（如果有 JDK/Maven）
cd backend ; ./mvnw test 2>&1 | Tee-Object ../docs/gate-output/backend-tests-2026-09-14.txt

# 3. 跑管理端检查
cd admin-web ; npm run type-check 2>&1 | Tee-Object ../docs/gate-output/admin-typecheck-2026-09-14.txt
cd admin-web ; npm run build 2>&1 | Tee-Object ../docs/gate-output/admin-build-2026-09-14.txt

# 4. 跑小程序类型检查
cd miniapp ; npx tsc --noEmit 2>&1 | Tee-Object ../docs/gate-output/miniapp-typecheck-2026-09-14.txt

# 5. 跑全部契约测试
foreach ($f in Get-ChildItem ui-tests/*.mjs) { node $f.FullName 2>&1 | Tee-Object "docs/gate-output/$($f.Name -replace '\.mjs$','-2026-09-14.txt)" }
```

然后按任务 0.2 分类 56 个未提交改动，逐步推进。