289 lines
12 KiB
Markdown
289 lines
12 KiB
Markdown
# 管理端框架与工作台参考图重设计实施计划
|
||
|
||
> **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:** 由全局 Token 和背景资产提供视觉基础，`MainLayout.vue` 负责外框、侧栏和顶部栏，独立 dashboard service/adapter 负责聚合现有统计与活动 API，`DashboardView.vue` 只负责呈现六指标和四个业务区块。
|
||
|
||
**Tech Stack:** Vue 3、TypeScript、Vite、Pinia、Element Plus、Node.js contracts、浏览器截图
|
||
|
||
**Spec:** `docs/superpowers/specs/2026-09-13-reference-driven-dual-client-ui-redesign-design.md`
|
||
|
||
## Global Constraints
|
||
|
||
- 只重构全局框架与工作台，不逐页重写业务模块。
|
||
- 菜单继续由服务端权限映射控制。
|
||
- 统计数字和活动数据来自现有 API，不硬编码参考图演示值。
|
||
- 背景和品牌素材本地化，不增加境外运行时依赖。
|
||
- 支持 `1366×768` 与 `1920×1080`，不使用整体缩放。
|
||
|
||
---
|
||
|
||
### Task 1: 锁定管理端参考图契约与资产
|
||
|
||
**Files:**
|
||
- Create: `ui-tests/admin-reference-contracts.mjs`
|
||
- Create: `admin-web/public/brand/admin-danyang-backdrop.jpg`
|
||
- Keep: `admin-web/public/brand/logo-mark.png`
|
||
- Modify: `admin-web/src/theme/index.css`
|
||
- Test: `ui-tests/admin-reference-contracts.mjs`
|
||
|
||
**Interfaces:**
|
||
- Consumes: 管理端参考图和现有 `logo-mark.png`。
|
||
- Produces: `--admin-*` 视觉 Token、正式背景资产和失败优先契约。
|
||
|
||
- [ ] **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 theme = read('admin-web/src/theme/index.css')
|
||
const layout = read('admin-web/src/layouts/MainLayout.vue')
|
||
const dashboard = read('admin-web/src/views/DashboardView.vue')
|
||
for (const token of ['--admin-coral', '--admin-shell-bg', '--admin-sidebar-bg', '--admin-card-radius', '--admin-shell-radius']) {
|
||
assert.ok(theme.includes(token), `缺少管理端参考图令牌 ${token}`)
|
||
}
|
||
assert.ok(existsSync(resolve(root, 'admin-web/public/brand/admin-danyang-backdrop.jpg')))
|
||
for (const item of ['工作台','用户管理','资料审核','匹配管理','公益红娘','公益咨询','活动管理','内容管理','善缘服务站','举报风控','数据统计','组织人员','系统设置']) {
|
||
assert.ok(layout.includes(item), `侧栏缺少 ${item}`)
|
||
}
|
||
assert.match(dashboard, /class="metric-card/, '工作台缺少指标卡结构')
|
||
assert.match(dashboard, /metrics/, '工作台缺少指标数据绑定')
|
||
for (const title of ['今日待办事项','近期公益活动','服务数据概览','项目服务成效']) assert.ok(dashboard.includes(title))
|
||
console.log('Admin reference contracts passed')
|
||
```
|
||
|
||
- [ ] **Step 2: 运行契约确认失败**
|
||
|
||
Run: `node ui-tests/admin-reference-contracts.mjs`
|
||
|
||
Expected: FAIL，至少缺少新 Token、背景资产或六项指标。
|
||
|
||
- [ ] **Step 3: 生成并检查背景资产**
|
||
|
||
使用参考图风格生成不含 UI 文字的浅粉丹阳城市背景，包含塔、桥、远山、爱心和低对比人物剪影；输出 `1920×1080` JPG。生成后检查无乱码文字、无第三方 Logo、主要装饰不遮挡中央系统容器。
|
||
|
||
- [ ] **Step 4: 建立主题 Token**
|
||
|
||
```css
|
||
:root {
|
||
--admin-coral: #f45f68;
|
||
--admin-coral-soft: #fff0f1;
|
||
--admin-shell-bg: rgba(255, 255, 255, 0.96);
|
||
--admin-sidebar-bg: #202d38;
|
||
--admin-page-bg: #f7f9fb;
|
||
--admin-card-radius: 14px;
|
||
--admin-shell-radius: 22px;
|
||
--admin-shadow: 0 18px 48px rgba(57, 40, 45, 0.14);
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 5: 运行契约并提交基础**
|
||
|
||
```powershell
|
||
node ui-tests/admin-reference-contracts.mjs
|
||
git add -- ui-tests/admin-reference-contracts.mjs admin-web/public/brand admin-web/src/theme/index.css
|
||
git commit -m "feat: establish admin reference design foundation"
|
||
```
|
||
|
||
Expected: 契约可能继续因布局未完成而失败，但 Token 和资产断言通过。
|
||
|
||
### Task 2: 重构全局框架、侧栏与顶部栏
|
||
|
||
**Files:**
|
||
- Modify: `admin-web/src/layouts/MainLayout.vue`
|
||
- Modify: `admin-web/src/router/index.ts`（仅在需要给现有路由补充菜单元数据时）
|
||
- Test: `ui-tests/admin-reference-contracts.mjs`
|
||
|
||
**Interfaces:**
|
||
- Consumes: `useAuthStore().permissions`、现有路由、主题 Token 和品牌资产。
|
||
- Produces: `.admin-scene`、`.admin-shell`、`.admin-sidebar`、`.admin-topbar` 四层框架。
|
||
|
||
- [ ] **Step 1: 为框架结构补充失败断言**
|
||
|
||
```js
|
||
for (const className of ['admin-scene','admin-shell','admin-sidebar','admin-topbar','admin-content']) {
|
||
assert.ok(layout.includes(className), `缺少框架结构 ${className}`)
|
||
}
|
||
assert.match(layout, /admin-danyang-backdrop\.jpg/)
|
||
assert.match(layout, /permissions/)
|
||
```
|
||
|
||
- [ ] **Step 2: 运行断言确认失败**
|
||
|
||
Run: `node ui-tests/admin-reference-contracts.mjs`
|
||
|
||
Expected: FAIL，报告缺少新框架结构。
|
||
|
||
- [ ] **Step 3: 实现参考图布局**
|
||
|
||
将外层背景、中央圆角壳、约 208px 深色侧栏、64px 顶栏和滚动内容区分层实现。侧栏按参考图名称组织现有路由；多个现有路由归入同一一级入口时使用模块内二级菜单，不删除路由。
|
||
|
||
- [ ] **Step 4: 保持权限与操作反馈**
|
||
|
||
搜索框必须有可操作状态；通知入口提供抽屉或明确提示；管理员菜单保留退出登录。无权限入口不渲染，路由守卫继续后端权限同名校验。
|
||
|
||
- [ ] **Step 5: 验证框架**
|
||
|
||
```powershell
|
||
node ui-tests/admin-reference-contracts.mjs
|
||
npm --prefix admin-web run type-check
|
||
npm --prefix admin-web run build
|
||
```
|
||
|
||
Expected: 类型检查和构建 PASS；契约只可能因工作台尚未完成而失败。
|
||
|
||
- [ ] **Step 6: 提交框架**
|
||
|
||
```powershell
|
||
git add -- admin-web/src/layouts/MainLayout.vue admin-web/src/router/index.ts ui-tests/admin-reference-contracts.mjs
|
||
git commit -m "feat: rebuild admin shell from reference"
|
||
```
|
||
|
||
### Task 3: 建立工作台数据适配层
|
||
|
||
**Files:**
|
||
- Create: `admin-web/src/services/dashboard.ts`
|
||
- Create: `admin-web/src/types/dashboard.ts`
|
||
- Create: `ui-tests/admin-dashboard-data-contracts.mjs`
|
||
- Modify: `admin-web/src/views/DashboardView.vue`
|
||
- Test: `ui-tests/admin-dashboard-data-contracts.mjs`
|
||
|
||
**Interfaces:**
|
||
- Consumes: `GET /operator/analytics/dashboard`、`GET /operator/analytics/v11-dashboard` 和现有活动列表接口。
|
||
- Produces: `DashboardModel`，包含 `metrics[6]`、`todos`、`activities`、`serviceOverview`、`effectiveness`。
|
||
|
||
- [ ] **Step 1: 定义工作台模型**
|
||
|
||
```ts
|
||
export interface DashboardMetric { key: string; label: string; value: number; trendText: string; tone: 'rose'|'amber'|'blue'|'green'|'purple' }
|
||
export interface DashboardTodo { key: string; title: string; description: string; count: number; actionText: string; route: string }
|
||
export interface DashboardActivity { id: string; title: string; coverUrl: string; startAt: string; locationName: string; registered: number; capacity: number; statusText: string }
|
||
export interface DashboardModel {
|
||
metrics: DashboardMetric[]
|
||
todos: DashboardTodo[]
|
||
activities: DashboardActivity[]
|
||
serviceOverview: Array<{ key: string; label: string; value: number; compareText: string }>
|
||
effectiveness: Array<{ key: string; label: string; value: number; max: number; unit: string }>
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: 编写失败的数据契约**
|
||
|
||
契约读取 `dashboard.ts`，断言导出 `loadDashboard`、设置请求超时、失败时返回显式错误而不是演示数字，并断言类型文件包含上述五个字段。
|
||
|
||
- [ ] **Step 3: 实现并发加载与适配**
|
||
|
||
使用现有 `api/client.ts` 并发读取授权接口。缺少某一接口权限时，仅将对应模块标记为不可用；不得用 `|| 3`、`|| 12` 等演示值替代真实的 0。
|
||
|
||
- [ ] **Step 4: 验证数据层**
|
||
|
||
```powershell
|
||
node ui-tests/admin-dashboard-data-contracts.mjs
|
||
npm --prefix admin-web run type-check
|
||
```
|
||
|
||
Expected: PASS；无硬编码非零业务统计。
|
||
|
||
- [ ] **Step 5: 提交数据适配层**
|
||
|
||
```powershell
|
||
git add -- admin-web/src/services/dashboard.ts admin-web/src/types/dashboard.ts admin-web/src/views/DashboardView.vue ui-tests/admin-dashboard-data-contracts.mjs
|
||
git commit -m "feat: add admin dashboard data adapter"
|
||
```
|
||
|
||
### Task 4: 实现六指标与四个工作台区块
|
||
|
||
**Files:**
|
||
- Modify: `admin-web/src/views/DashboardView.vue`
|
||
- Modify: `admin-web/src/theme/index.css`
|
||
- Test: `ui-tests/admin-reference-contracts.mjs`
|
||
|
||
**Interfaces:**
|
||
- Consumes: `loadDashboard(): Promise<DashboardModel>`。
|
||
- Produces: `.dashboard-metrics`、`.todo-panel`、`.activity-panel`、`.service-overview-panel`、`.effectiveness-panel`。
|
||
|
||
- [ ] **Step 1: 将完整工作台结构加入契约**
|
||
|
||
断言六个 `metric-card`、四个标题、Loading、Empty、Error/Retry 和无权限状态类名全部存在。
|
||
|
||
- [ ] **Step 2: 运行契约确认失败**
|
||
|
||
Run: `node ui-tests/admin-reference-contracts.mjs`
|
||
|
||
Expected: FAIL，报告缺少新工作台结构或状态。
|
||
|
||
- [ ] **Step 3: 实现欢迎区与六项指标**
|
||
|
||
六项指标使用一行卡片；在 `1366px` 可缩小间距与字号但不隐藏指标。日期使用 `zh-CN` 与 `Asia/Shanghai`，不接入外部天气服务。
|
||
|
||
- [ ] **Step 4: 实现四个内容区块**
|
||
|
||
桌面宽度使用两列布局：今日待办/近期活动、服务数据/项目成效。活动封面失败时使用本地默认图；进度条的 `max` 为 0 时显示 0%，避免除零。
|
||
|
||
- [ ] **Step 5: 实现状态与操作**
|
||
|
||
加载显示骨架；接口失败显示重试；数组为空显示紧凑空状态；待办操作按现有路由跳转；无权限区块不显示敏感数字。
|
||
|
||
- [ ] **Step 6: 验证并提交工作台**
|
||
|
||
```powershell
|
||
node ui-tests/admin-reference-contracts.mjs
|
||
node ui-tests/admin-dashboard-data-contracts.mjs
|
||
npm --prefix admin-web run type-check
|
||
npm --prefix admin-web run build
|
||
git add -- admin-web/src/views/DashboardView.vue admin-web/src/theme/index.css
|
||
git commit -m "feat: recreate admin dashboard from reference"
|
||
```
|
||
|
||
Expected: 所有自动化门禁 PASS。
|
||
|
||
### Task 5: 浏览器视觉 QA 与人工验收
|
||
|
||
**Files:**
|
||
- Create: `artifacts/ui-redesign/admin/dashboard-1366x768.png`
|
||
- Create: `artifacts/ui-redesign/admin/dashboard-1920x1080.png`
|
||
- Create: `artifacts/ui-redesign/admin/dashboard-comparison.png`
|
||
- Create: `docs/ADMIN_REFERENCE_UI_QA_2026-09-13.md`
|
||
|
||
**Interfaces:**
|
||
- Consumes: 运行中的 Docker 后端与管理端开发服务器、管理端参考图。
|
||
- Produces: 两种尺寸截图、并排对比和差异结论。
|
||
|
||
- [ ] **Step 1: 启动并打开真实管理端**
|
||
|
||
```powershell
|
||
docker compose -f infrastructure/docker-compose.yml ps
|
||
npm --prefix admin-web run dev -- --host 0.0.0.0
|
||
```
|
||
|
||
Expected: 后端可访问，管理端页面能登录并进入 `/dashboard`。
|
||
|
||
- [ ] **Step 2: 检查主要交互和控制台**
|
||
|
||
验证菜单跳转、权限隐藏、搜索反馈、通知反馈、管理员菜单、退出登录、待办跳转和重试；浏览器控制台无未处理错误。
|
||
|
||
- [ ] **Step 3: 分别截图并制作对比图**
|
||
|
||
在 `1366×768` 和 `1920×1080` 真实 viewport 截图。对比背景氛围、侧栏宽度、顶栏高度、六卡一行、两列面板、圆角、阴影、颜色和信息密度。
|
||
|
||
- [ ] **Step 4: 修复差异并重新截图**
|
||
|
||
所有 P0/P1/P2 差异修复后覆盖最终截图；报告记录仍存在但经确认可接受的差异。
|
||
|
||
- [ ] **Step 5: 最终验证与提交**
|
||
|
||
```powershell
|
||
node ui-tests/admin-reference-contracts.mjs
|
||
npm --prefix admin-web run type-check
|
||
npm --prefix admin-web run build
|
||
git add -- artifacts/ui-redesign/admin docs/ADMIN_REFERENCE_UI_QA_2026-09-13.md admin-web
|
||
git commit -m "test: verify admin reference UI fidelity"
|
||
```
|
||
|
||
Expected: 自动化 PASS；人工验收后才可进入小程序计划。
|