danyang-match/docs/superpowers/plans/2026-09-11-ui-foundation-and-pilot.md

# UI Foundation And Pilot Implementation Plan

> **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:** 建立双端品牌资产和设计系统，并交付管理端与小程序核心样板页供用户确认。

**Architecture:** 复用现有 Vue/Element Plus 与微信原生组件，在管理端 `theme/index.css` 和小程序 `app.wxss` 建立双主题令牌。先以契约测试锁定页面数量、固定导航、素材存在性和禁用占位符规则，再改造样板页面并进行同尺寸视觉对比。

**Tech Stack:** Vue 3、TypeScript、Element Plus、微信小程序原生、Node.js assert、ImageGen

**Spec:** `docs/superpowers/specs/2026-09-11-dual-client-full-ui-redesign-design.md`

## Global Constraints

- 管理端覆盖 19 条现有路由，小程序覆盖 63 个现有页面。
- 小程序底部导航固定为：首页、找对象、消息、活动、我的。
- 小程序首页保留 8 个固定入口和 V1.1 完整模块顺序。
- 管理端使用暖白、珊瑚红、深蓝灰；小程序使用紫蓝夜景、粉色高光和浅色正文卡片。
- 不改变后端、数据库、API、权限和核心业务不变量。
- 不硬编码参考图中的人物、活动和统计数字。
- 不使用 Emoji、文字方块、CSS 拼图或临时占位框作为正式视觉资产。
- 不新增前端框架或大型 UI 依赖。

---

### Task 1: 冻结 82 个页面的改造基线

**Files:**
- Create: `docs/UI_REDESIGN_PAGE_MATRIX_V1.1.md`
- Modify: `ui-tests/ui-contracts.mjs`
- Test: `ui-tests/ui-contracts.mjs`

**Interfaces:**
- Consumes: `admin-web/src/router/index.ts` 的 19 条路由与 `miniapp/app.json` 的 63 个页面。
- Produces: 页面矩阵，字段固定为 `终端 | 页面 | 路由 | 业务域 | 权限/能力 | 数据源 | 必备状态 | 状态`。

- [ ] **Step 1: 写入失败契约**

在 `ui-tests/ui-contracts.mjs` 增加：

```js
assert.equal(appConfig.pages.length, 63, '小程序页面清单必须完整覆盖 63 页')
const matrix = read('docs/UI_REDESIGN_PAGE_MATRIX_V1.1.md')
for (const page of appConfig.pages) {
  assert.ok(matrix.includes(`\`/${page}\``), `页面矩阵遗漏 /${page}`)
}
```

- [ ] **Step 2: 验证契约失败**

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

Expected: FAIL，提示缺少 `docs/UI_REDESIGN_PAGE_MATRIX_V1.1.md`。

- [ ] **Step 3: 建立页面矩阵**

逐条登记 19 条管理端路由和 63 个小程序页面。状态列只允许 `未开始`、`进行中`、`待验收`、`通过`、`阻塞`。

- [ ] **Step 4: 验证契约通过**

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

Expected: PASS，输出 `UI contracts passed`。

- [ ] **Step 5: 提交**

```bash
git add docs/UI_REDESIGN_PAGE_MATRIX_V1.1.md ui-tests/ui-contracts.mjs
git commit -m "test: freeze full UI redesign page matrix"
```

### Task 2: 制作原创品牌和首批页面素材

**Files:**
- Create: `admin-web/public/brand/logo-mark.png`
- Create: `admin-web/public/brand/login-illustration.jpg`
- Create: `miniapp/assets/brand/logo-mark.png`
- Create: `miniapp/assets/brand/home-nightscape.jpg`
- Create: `miniapp/assets/brand/default-avatar.png`
- Create: `miniapp/assets/covers/activity-default.jpg`
- Create: `miniapp/assets/covers/classroom-default.jpg`
- Create: `miniapp/assets/covers/counseling-default.jpg`
- Create: `miniapp/assets/covers/anti-fraud-default.jpg`
- Create: `miniapp/assets/covers/station-default.jpg`
- Create: `ui-tests/brand-assets.mjs`
- Test: `ui-tests/brand-assets.mjs`

**Interfaces:**
- Consumes: 两张已批准参考图的心形识别、丹阳城市意象与双端色彩方向。
- Produces: 不带个人身份的本地视觉资产；Logo 中文文字由真实文本渲染，图片只承载心形标志。

- [ ] **Step 1: 写入失败资产测试**

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

const assets = [
  'admin-web/public/brand/logo-mark.png',
  'admin-web/public/brand/login-illustration.jpg',
  'miniapp/assets/brand/logo-mark.png',
  'miniapp/assets/brand/home-nightscape.jpg',
  'miniapp/assets/brand/default-avatar.png',
  'miniapp/assets/covers/activity-default.jpg',
  'miniapp/assets/covers/classroom-default.jpg',
  'miniapp/assets/covers/counseling-default.jpg',
  'miniapp/assets/covers/anti-fraud-default.jpg',
  'miniapp/assets/covers/station-default.jpg',
]
for (const file of assets) {
  assert.ok(existsSync(file), `缺少品牌资产 ${file}`)
  assert.ok(readFileSync(file).length > 4096, `品牌资产为空或过小 ${file}`)
}
console.log('Brand asset contracts passed')
```

- [ ] **Step 2: 验证测试失败**

Run: `node ui-tests/brand-assets.mjs`

Expected: FAIL，提示首个品牌素材不存在。

- [ ] **Step 3: 使用 ImageGen 制作素材**

统一要求：原创、无文字、无水印、无真实人物身份、丹阳塔桥和城市夜景只作艺术化意象；后台素材低饱和浅色，小程序素材紫蓝夜景配粉色光晕。

- [ ] **Step 4: 优化尺寸与包体**

后台登录插画按桌面横幅裁切；小程序首页图按 750rpx 宽组件裁切；封面统一 16:9；头像统一正方形透明或浅色背景。

- [ ] **Step 5: 验证资产**

Run: `node ui-tests/brand-assets.mjs`

Expected: PASS，输出 `Brand asset contracts passed`。

- [ ] **Step 6: 提交**

```bash
git add admin-web/public/brand miniapp/assets/brand miniapp/assets/covers ui-tests/brand-assets.mjs
git commit -m "feat: add original Shanyuan Danyang brand assets"
```

### Task 3: 建立管理端设计令牌和整体框架

**Files:**
- Create: `ui-tests/admin-redesign-contracts.mjs`
- Modify: `admin-web/src/theme/index.css`
- Modify: `admin-web/src/layouts/MainLayout.vue`
- Modify: `admin-web/src/router/index.ts`
- Test: `ui-tests/admin-redesign-contracts.mjs`

**Interfaces:**
- Consumes: Pinia `useAuthStore().permissions` 和现有路由 `meta.permissions`。
- Produces: `--admin-sidebar-bg`、`--admin-page-bg`、`--admin-primary`、`--admin-card-radius`；按权限过滤的 9 组导航。

- [ ] **Step 1: 写入失败契约**

```js
import assert from 'node:assert/strict'
import { readFileSync } from 'node:fs'
const read = (file) => readFileSync(file, 'utf8')
const theme = read('admin-web/src/theme/index.css')
const layout = read('admin-web/src/layouts/MainLayout.vue')
for (const token of ['--admin-sidebar-bg', '--admin-page-bg', '--admin-primary', '--admin-card-radius']) {
  assert.ok(theme.includes(token), `缺少管理端令牌 ${token}`)
}
for (const group of ['用户与审核', '婚恋服务', '活动与阵地', '内容运营', '安全治理', '组织与权限']) {
  assert.ok(layout.includes(group), `缺少菜单组 ${group}`)
}
assert.ok(layout.includes('logo-mark.png'), '管理端未使用正式品牌标志')
console.log('Admin redesign contracts passed')
```

- [ ] **Step 2: 验证契约失败**

Run: `node ui-tests/admin-redesign-contracts.mjs`

Expected: FAIL，提示缺少 `--admin-sidebar-bg`。

- [ ] **Step 3: 实现管理端令牌**

在 `theme/index.css` 中增加双层变量映射，Element Plus 继续通过 `--el-color-primary` 使用统一主色；删除页面基础样式中的散落旧色值。

- [ ] **Step 4: 重构侧栏和顶栏**

保持现有权限判断函数；将路由分组映射到 9 个已批准业务域。加入真实图片标志、品牌文字、搜索外观、通知入口、操作员信息和 72px 收起态。

- [ ] **Step 5: 验证契约与构建**

Run:

```bash
node ui-tests/admin-redesign-contracts.mjs
npm --prefix admin-web run type-check
npm --prefix admin-web run build
```

Expected: 三条命令均退出码 0。

- [ ] **Step 6: 提交**

```bash
git add ui-tests/admin-redesign-contracts.mjs admin-web/src/theme/index.css admin-web/src/layouts/MainLayout.vue admin-web/src/router/index.ts
git commit -m "feat: establish admin visual foundation"
```

### Task 4: 完成管理端五个样板页面

**Files:**
- Modify: `admin-web/src/views/LoginView.vue`
- Modify: `admin-web/src/views/DashboardView.vue`
- Modify: `admin-web/src/modules/user/UserManagementView.vue`
- Modify: `admin-web/src/modules/user/UserDetailView.vue`
- Modify: `admin-web/src/modules/review/ReviewView.vue`
- Modify: `ui-tests/admin-redesign-contracts.mjs`
- Test: `ui-tests/admin-redesign-contracts.mjs`

**Interfaces:**
- Consumes: 现有登录、工作台、用户与审核 API，不修改响应字段。
- Produces: 登录、数据卡、待办列表、活动区、用户列表、详情区和审核状态的样板布局。

- [ ] **Step 1: 为五页加入失败契约**

```js
for (const file of [
  'admin-web/src/views/LoginView.vue',
  'admin-web/src/views/DashboardView.vue',
  'admin-web/src/modules/user/UserManagementView.vue',
  'admin-web/src/modules/user/UserDetailView.vue',
  'admin-web/src/modules/review/ReviewView.vue',
]) {
  const source = read(file)
  assert.ok(source.includes('page-shell') || source.includes('login-shell'), `${file} 未接入样板布局`)
  assert.doesNotMatch(source, /[\u{1F300}-\u{1FAFF}]/u, `${file} 仍包含 Emoji`)
}
```

- [ ] **Step 2: 验证契约失败**

Run: `node ui-tests/admin-redesign-contracts.mjs`

Expected: FAIL，指出尚未接入样板布局的页面。

- [ ] **Step 3: 实现五个样板页面**

所有数据继续读取现有 API。空数组显示空状态；请求中显示骨架或 loading；403 显示无权限说明；其他失败显示原因和重试按钮。

- [ ] **Step 4: 验证**

Run:

```bash
node ui-tests/admin-redesign-contracts.mjs
npm --prefix admin-web run type-check
npm --prefix admin-web run build
```

Expected: 全部 PASS。

- [ ] **Step 5: 提交**

```bash
git add admin-web/src/views admin-web/src/modules/user admin-web/src/modules/review ui-tests/admin-redesign-contracts.mjs
git commit -m "feat: deliver admin redesign pilot"
```

### Task 5: 建立小程序设计令牌和五个 Tab 样板

**Files:**
- Create: `ui-tests/miniapp-redesign-contracts.mjs`
- Modify: `miniapp/app.wxss`
- Modify: `miniapp/app.json`
- Modify: `miniapp/components/nav-bar/index.wxml`
- Modify: `miniapp/components/nav-bar/index.wxss`
- Modify: `miniapp/components/button/index.wxss`
- Modify: `miniapp/components/recommend-card/index.wxml`
- Modify: `miniapp/components/recommend-card/index.wxss`
- Modify: `miniapp/components/conversation-item/index.wxml`
- Modify: `miniapp/components/conversation-item/index.wxss`
- Modify: `miniapp/components/activity-card/index.wxml`
- Modify: `miniapp/components/activity-card/index.wxss`
- Modify: `miniapp/pages/index/index.wxml`
- Modify: `miniapp/pages/index/index.wxss`
- Modify: `miniapp/pages/discover/discover.wxml`
- Modify: `miniapp/pages/discover/discover.wxss`
- Modify: `miniapp/pages/messages/messages.wxml`
- Modify: `miniapp/pages/messages/messages.wxss`
- Modify: `miniapp/pages/activity/activity.wxml`
- Modify: `miniapp/pages/activity/activity.wxss`
- Modify: `miniapp/pages/mine/mine.wxml`
- Modify: `miniapp/pages/mine/mine.wxss`
- Test: `ui-tests/miniapp-redesign-contracts.mjs`

**Interfaces:**
- Consumes: `GET /api/v1/home`、推荐、消息、活动和个人中心现有数据。
- Produces: 紫蓝夜景令牌、浅色正文卡片、五个固定 Tab 页面和统一导航组件。

- [ ] **Step 1: 写入失败契约**

```js
import assert from 'node:assert/strict'
import { readFileSync } from 'node:fs'
const read = (file) => readFileSync(file, 'utf8')
const app = JSON.parse(read('miniapp/app.json'))
assert.deepEqual(app.tabBar.list.map((item) => item.text), ['首页', '找对象', '消息', '活动', '我的'])
const style = read('miniapp/app.wxss')
for (const token of ['--mini-night-start', '--mini-night-end', '--mini-accent-pink', '--mini-card-bg']) {
  assert.ok(style.includes(token), `缺少小程序令牌 ${token}`)
}
for (const page of ['index', 'discover', 'messages', 'activity', 'mine']) {
  const source = read(`miniapp/pages/${page}/${page}.wxml`)
  assert.ok(source.includes('app-page'), `${page} 未接入统一页面容器`)
  assert.doesNotMatch(source, /[\u{1F300}-\u{1FAFF}]/u, `${page} 仍包含 Emoji`)
}
console.log('Miniapp redesign contracts passed')
```

- [ ] **Step 2: 验证契约失败**

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

Expected: FAIL，提示缺少小程序夜景令牌。

- [ ] **Step 3: 实现全局令牌和公共组件**

夜景只用于品牌区、导航区和营销卡片；表单、正文和数据列表使用 `--mini-card-bg`。保留现有事件名和组件属性，避免改动业务逻辑。

- [ ] **Step 4: 实现五个 Tab 页面**

首页必须保留现有注释标识的十段顺序及 8 个入口。找对象、消息、活动、我的继续使用真实 API，并补齐加载、空、错误和禁用状态。

- [ ] **Step 5: 验证**

Run:

```bash
node ui-tests/ui-contracts.mjs
node ui-tests/tabbar-icons.mjs
node ui-tests/miniapp-redesign-contracts.mjs
npm --prefix miniapp run type-check
```

Expected: 全部 PASS。

- [ ] **Step 6: 提交**

```bash
git add miniapp/app.wxss miniapp/app.json miniapp/components miniapp/pages/index miniapp/pages/discover miniapp/pages/messages miniapp/pages/activity miniapp/pages/mine ui-tests/miniapp-redesign-contracts.mjs
git commit -m "feat: deliver miniapp navigation pilot"
```

### Task 6: 样板视觉验收门禁

**Files:**
- Create: `docs/Phase-UI-Pilot-Completion-Report.md`
- Create: `artifacts/ui-redesign/pilot/admin-dashboard-1440.png`
- Create: `artifacts/ui-redesign/pilot/miniapp-home-375.png`
- Create: `artifacts/ui-redesign/pilot/miniapp-tabs-375.png`

**Interfaces:**
- Consumes: 已批准参考图及 Task 4、Task 5 的可运行页面。
- Produces: 同尺寸截图、差异清单和用户审批结论。

- [ ] **Step 1: 启动双端**

Run:

```bash
docker compose -f infrastructure/docker-compose.yml up -d --build
```

Expected: 管理端和后端健康；小程序由微信开发者工具打开 `miniapp/`。

- [ ] **Step 2: 捕获指定尺寸**

管理端捕获 1440px 工作台；小程序捕获 375px 首页和五个 Tab。不得使用加载中、空白或错误截图代替稳定页面。

- [ ] **Step 3: 并排比较**

比较颜色关系、卡片层次、圆角、间距、字体重量、图片裁切、图标、导航和首屏信息密度；逐项修正可见差异。

- [ ] **Step 4: 执行最终检查**

Run:

```bash
node ui-tests/ui-contracts.mjs
node ui-tests/brand-assets.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
```

Expected: 全部退出码 0。

- [ ] **Step 5: 提交报告**

```bash
git add docs/Phase-UI-Pilot-Completion-Report.md
git commit -m "docs: report UI pilot completion"
```

停止并等待用户确认样板视觉，不自动进入管理端和小程序全量计划。