lehuo/docs/15_FRONTEND_DESIGN_SPEC.md

# 15 前端界面设计与实现规范（Codex 执行版）

> 项目：乐活公益·暖心服务平台  
> 版本：V1.0  
> 适用范围：微信小程序端 + Web 管理后台  
> 目标：Codex 必须依照本文档实现，不得自行改变既定视觉方向、信息架构和核心交互。  
> 关联文档：`01_PROJECT_CONSTITUTION.md`、`02_PRODUCT_PRD_V1.md`、`07_UI_UX.md`、`09_TEST_ACCEPTANCE.md`  
> 视觉参考：`ui_reference.png`

---

# 一、设计总则

## 1.1 产品气质

本项目面向公益服务对象、老年人、困境妇女儿童、残疾人、志愿者、公益工作人员和社会爱心人士。

视觉关键词：

- 温暖
- 可信
- 清晰
- 简洁
- 亲和
- 公益感
- 服务感
- 不商业化
- 不娱乐化
- 不科技炫技

界面必须让普通用户第一眼就知道：

> “我在哪里、我能做什么、下一步点哪里。”

---

## 1.2 设计风格

整体采用：

- 浅色背景；
- 卡片式信息组织；
- 大留白；
- 大按钮；
- 圆角；
- 简洁图标；
- 真实公益服务照片；
- 橙色为主色；
- 绿色、蓝色、紫色作为业务辅助色。

禁止：

- 大面积深色背景；
- 霓虹渐变；
- 玻璃拟态；
- 复杂动效；
- 过度阴影；
- 过多装饰插画；
- 信息密度过高；
- 商城化设计；
- 抽奖、积分、红包等强商业视觉；
- 短视频平台式沉浸内容流。

---

# 二、视觉设计系统

## 2.1 主色

推荐 CSS / Design Token：

```ts
export const colors = {
  primary: '#FF6B35',
  primaryLight: '#FFF1EB',
  primaryHover: '#FF7A4D',
  primaryPressed: '#E95A28',

  success: '#52C41A',
  info: '#1890FF',
  warning: '#FAAD14',
  purple: '#722ED1',
  danger: '#E34D59',

  textPrimary: '#1F2329',
  textSecondary: '#646A73',
  textTertiary: '#8F959E',
  textDisabled: '#B8BDC6',

  background: '#F5F5F5',
  surface: '#FFFFFF',
  border: '#E5E6EB',
  divider: '#EBEDF0',
};
```

### 使用规则

橙色：

- 核心 CTA；
- “我需要帮助”；
- “提交申请”；
- “立即参与”；
- 强调数字。

绿色：

- 已完成；
- 服务正常；
- 志愿服务；
- 成功状态。

蓝色：

- 信息类；
- 进行中；
- 老年/残障等部分入口可辅助使用。

紫色：

- 妇女儿童、心理关怀类辅助标签；
- 禁止大面积使用。

红色：

- 错误、风险、失败；
- 不用于普通公益强调。

---

## 2.2 字体

优先使用系统字体。

微信小程序：

```text
-apple-system
BlinkMacSystemFont
"Helvetica Neue"
"PingFang SC"
"Microsoft YaHei"
sans-serif
```

Web 后台：
同上。

---

## 2.3 字号

### 小程序

```text
页面大标题        24px / 600
区块标题          20px / 600
卡片标题          17px / 600
正文              16px / 400
辅助文字          14px / 400
标签              12~13px
主要按钮          17px / 600
```

核心原则：

普通正文不得默认使用 12px。

适老场景：

- 可提供“大字模式”二期；
- V1 默认已经采用偏大字号。

---

## 2.4 圆角

```text
小卡片：12px
大卡片：16px
按钮：12~24px
头像：50%
图片：12px
标签：6px
```

---

## 2.5 间距体系

采用 4 的倍数：

```text
4 / 8 / 12 / 16 / 20 / 24 / 32
```

推荐：

```text
页面左右边距：16px
卡片内部：16px
区块之间：20~24px
列表项高度：56px 以上
主要按钮高度：48~52px
```

---

## 2.6 阴影

仅轻阴影：

```css
box-shadow: 0 4px 16px rgba(0, 0, 0, 0.06);
```

禁止重阴影。

---

# 三、图标规范

优先使用 TDesign 官方图标。

禁止：

- Emoji 代替正式图标；
- 多套图标风格混用；
- 图标无文字解释地承担核心操作。

核心图标：

```text
首页
服务
志愿者
项目
活动
用户
电话
消息
位置
日历
记录
回访
评价
文件
上传
提醒
公益爱心
```

---

# 四、图片规范

公益项目展示使用真实、温暖、尊重被服务对象尊严的照片。

禁止：

- 悲情营销；
- 刻意展示脆弱、哭泣、伤残特征；
- 暴露儿童身份；
- 暴露家庭住址；
- 未授权特写；
- 过度摆拍。

建议图片比例：

```text
首页 Banner：16:7
项目卡片：16:9
活动卡片：16:9
头像：1:1
服务记录：4:3
```

---

# 五、小程序底部导航

固定四项：

```text
首页
服务
公益
我的
```

图标 + 中文。

默认：

- 未选中：灰色；
- 选中：主色橙。

不要设计第五个 Tab。

---

# 六、小程序首页

## 6.1 页面目标

用户 3 秒内知道：

1. 这里是乐活公益；
2. 可以申请帮助；
3. 可以帮家人申请；
4. 可以参与公益。

---

## 6.2 页面结构

```text
AppBar
品牌欢迎区 / Banner
核心入口区
服务分类区
服务进度入口
公益项目
公益活动
加入公益
Footer Safe Area
```

---

## 6.3 顶部

左：

- 乐活公益 Logo
- “乐活公益”

右：

- 微信原生胶囊区域，不模拟。

---

## 6.4 Banner

文案建议：

```text
用爱连接 · 让爱传递
乐活公益 · 助人为乐 · 服务社会
```

Banner 不做自动轮播。

CTA 不超过 1 个。

---

## 6.5 核心入口

必须视觉突出：

### 第一按钮

```text
我需要帮助
```

### 第二按钮

```text
帮家人申请
```

允许上下排列或左右双卡。

不得把这两个入口隐藏到二级菜单。

---

## 6.6 首页功能栏目

一个高权重主入口：

```text
帮扶服务
```

六个次级入口，使用 3×2 布局：

```text
志愿服务
公益项目
公益动态
旧物善用
财务公开
服务进度
```

具体服务类别进入帮扶服务后选择，不在首页重复展示。每项：

- 图标；
- 文字；
- 点击区域 >= 48px。

“服务进度”在主功能区提供入口后，不在下方便捷入口重复展示；便捷入口不展示“旧物善用”。

---

## 6.7 服务进度

若用户存在申请：

显示：

```text
我的服务
服务编号：LHXXXXXXXX
当前状态：工作人员正在联系
查看进度 >
```

若无：
不显示此卡片。

---

## 6.8 公益项目

标题：

```text
公益项目              更多 >
```

项目卡片内容：

- 图片
- 项目名
- 简介
- 服务对象
- 当前进展（可选）
- 查看详情

不要首页展示复杂捐赠进度。

---

# 七、帮扶服务页面（内部模型：服务申请）

## 7.1 页面原则

不一次展示长表单。

采用步骤式：

```text
步骤 1：需要什么帮助
步骤 2：帮谁申请
步骤 3：联系方式
步骤 4：描述需求
步骤 5：确认提交
```

---

## 7.2 步骤一：服务类型

大卡片选择：

```text
关爱老人
困境妇女
儿童关爱
残障帮扶
生活困难
其他
```

每张卡片包含：

- 图标/图片；
- 名称；
- 一句话解释。

---

## 7.3 步骤二：申请关系

```text
为自己申请
帮家人申请
社区/机构代办
志愿者代办
其他
```

---

## 7.4 步骤三：基本联系信息

字段：

```text
服务对象姓名/称呼
联系电话
所在地区
期望联系时间（可选）
```

精确地址不在第一步强制收集。

---

## 7.5 步骤四：需求描述

组件：

- 多行文本框；
- 上传图片；
- 字数提示；
- 可选“是否需要上门”；
- 可选“行动是否不方便”。

文案：

```text
请简单描述目前遇到的困难或希望得到的帮助
```

---

## 7.6 步骤五：确认

必须显示：

- 服务类型；
- 服务对象；
- 联系方式脱敏；
- 需求摘要；
- 隐私授权。

按钮：

```text
提交申请
```

---

## 7.7 提交成功

成功页：

图标：
✅

标题：

```text
申请已提交
```

说明：

```text
乐活公益工作人员将根据实际情况与您联系。
```

显示：

```text
服务编号
提交时间
当前状态
```

按钮：

```text
查看服务进度
返回首页
```

---

# 八、我的服务 / 进度页面

采用 Timeline。

状态：

```text
已提交
工作人员联系
需求评估
服务安排
服务中
服务完成
回访
```

当前状态高亮。

每个节点：

- 时间；
- 状态；
- 简要说明。

不向用户展示内部技术状态码。

---

# 九、服务对象档案页面（后台为主）

## 9.1 页面结构

```text
头像 / 姓名 / 标签
基本资料
联系方式
服务需求
历史服务
回访记录
附件
操作
```

---

## 9.2 顶部摘要

示例：

```text
张奶奶
女 / 78岁
[关爱老人] [独居] [重点关爱]
```

右侧操作：

```text
联系
新建服务
新增回访
编辑资料
```

---

## 9.3 敏感字段

默认脱敏。

点击“查看完整信息”：

- 检查权限；
- 记录审计；
- 可提示“此次查看将被记录”。

---

# 十、服务记录页面

记录卡片：

```text
上门探访
2026-08-10 10:00
服务人员：李志愿者
服务时长：1.5小时

服务内容：
……

服务照片：
[图][图][图]

服务对象反馈：
★★★★★
```

工作人员可新增。

普通用户只能查看与自己相关、允许公开给本人/监护人的记录。

---

# 十一、反馈与评价

页面保持简单：

```text
本次服务您满意吗？
★★★★★

是否还需要帮助？
○ 不需要
○ 需要继续帮助

其他反馈
[输入框]

提交反馈
```

如果选择“需要继续帮助”，提交后明确：

```text
我们已记录您的需求，工作人员会继续跟进。
```

---

# 十二、公益项目详情

结构：

```text
封面
项目名称
项目标签
项目简介
项目目标
服务内容
项目进展
项目动态
参与方式
```

底部固定 CTA：

```text
我要参与
```

如果没有公开募捐能力，不出现“立即捐款”。

---

# 十三、志愿者中心

## 13.1 顶部身份卡

```text
李志愿者
已认证志愿者

累计服务 56小时
参与活动 23次
帮助人数 18人
```

---

## 13.2 快捷入口

```text
我的报名
服务中
已完成
服务时长
```

---

## 13.3 功能

```text
服务记录
培训学习
证书/荣誉
我的团队
设置
```

V1 中证书/荣誉可先预留，不强做。

---

# 十四、个人中心

顶部用户卡：

```text
头像
昵称
手机号脱敏
```

数据摘要：

```text
我的关注
我的收藏
我的捐赠（若未来合规开放）
我的服务
```

V1 建议优先：

```text
我的帮扶服务
我的活动
我的志愿服务
我的消息
我的评价
帮助与反馈
关于乐活
隐私设置
设置
```

---

# 十五、Web 管理后台整体布局

## 15.1 页面结构

桌面优先：

```text
左侧导航 240px
顶部栏 56px
主内容区
```

左侧导航深色或浅深蓝灰均可，但整体不应压迫。

---

## 15.2 导航

```text
工作台
服务申请
服务对象
服务工单
回访管理
志愿者管理
公益项目
公益活动
内容管理
数据统计
用户与权限
系统设置
```

审计日志只对高权限显示。

---

# 十六、后台工作台

## 16.1 顶部数据卡

最多 4~6 项：

```text
今日新申请
待联系
服务中
待回访
重点关爱
今日服务
```

---

## 16.2 图表

V1 最多 2~3 张：

```text
服务趋势
服务类型分布
本月任务完成情况
```

不要堆 10 个图。

---

## 16.3 快捷入口

```text
新增服务对象
新增工单
志愿者招募
发布公益活动
```

---

# 十七、服务申请列表

## 17.1 筛选

```text
关键词
服务类型
状态
负责人
时间范围
```

按钮：

```text
查询
重置
```

---

## 17.2 表格列

```text
服务编号
服务对象
服务类型
年龄/年龄段
联系电话（脱敏）
状态
提交时间
负责人
操作
```

操作：

```text
查看
受理
```

“编辑”不是所有状态都显示。

---

# 十八、服务对象列表

列：

```text
姓名
服务类别
年龄
联系电话
重点关爱
最近服务
下次回访
状态
操作
```

默认手机号脱敏。

---

# 十九、服务工单详情

必须采用状态进度条：

```text
待指派
已指派
服务中
待回访
已完成
```

内容分左右两栏：

左：

- 工单信息；
- 服务对象；
- 服务需求；
- 服务记录。

右：

- 负责人；
- 协作人员；
- 时间；
- 操作日志；
- 后续计划。

---

# 二十、回访中心

按待办设计，不做普通信息表。

顶部：

```text
今日待回访
已逾期
本周待回访
重点关爱
```

列表：

```text
服务对象
上次服务
回访原因
计划日期
负责人
状态
```

明显突出逾期项。

---

# 二十一、志愿者管理

列表字段：

```text
姓名
地区
技能
服务方向
累计时长
审核状态
最近参与
操作
```

支持：

```text
查看
审核
暂停
恢复
```

---

# 二十二、公益项目后台

项目详情后台分：

```text
基本信息
服务对象
项目工单
活动
成果数据
内容动态
```

V1 不做复杂甘特图。

---

# 二十三、活动管理

活动创建步骤：

```text
基本信息
招募设置
时间地点
内容说明
发布确认
```

报名列表：

```text
姓名
手机号
志愿者状态
报名时间
审核
签到
服务时长
```

---

# 二十四、内容管理

内容列表：

```text
标题
类型
状态
作者
发布时间
操作
```

状态：

```text
草稿
待审核
已发布
已归档
```

编辑器：

- Markdown / 富文本二选一；
- 建议成熟富文本；
- 禁止直接注入 HTML。

---

# 二十五、数据统计页面

## 25.1 顶部 KPI

```text
服务完成率
用户满意度
活跃志愿者
回访完成率
```

---

## 25.2 图表

```text
月度服务趋势
服务类型分布
项目服务量
志愿服务时长
```

所有指标必须能追溯到数据库真实数据。

---

# 二十六、响应式

## 小程序

覆盖常见微信手机尺寸。

最低关注：

- iPhone SE 宽度；
- 常见 Android 360~430 CSS px。

禁止水平滚动。

## 后台

主目标：

- 1366×768
- 1440×900
- 1920×1080

最低：

- 1280px 宽正常使用。

小于 1024：

- 导航折叠；
- 表格允许横向滚动；
- 不要求完整移动后台。

---

# 二十七、组件清单

Codex 必须优先抽取共享组件。

## 小程序

```text
AppHeader
HeroBanner
PrimaryActionCard
ServiceCategoryGrid
ProjectCard
ActivityCard
StatusTimeline
EmptyState
ErrorState
LoadingSkeleton
FormSection
PrivacyConsent
FileUploader
BeneficiarySummary
VolunteerProfileCard
BottomSafeArea
```

## 后台

```text
PageHeader
StatCard
FilterBar
StatusTag
SensitiveText
DataTable
EmptyState
ConfirmDialog
AuditNotice
BeneficiaryDrawer
ServiceTimeline
WorkOrderPanel
PermissionGuard
FilePreview
```

---

# 二十八、状态规范

所有页面至少实现：

```text
loading
success
empty
error
no-permission
offline / retry
```

不允许只有 success。

---

# 二十九、Skeleton

列表和首页采用 Skeleton。

不要用全屏 Spinner 阻断用户。

---

# 三十、Toast / Message

成功：

```text
提交成功
保存成功
操作已完成
```

失败：

```text
提交失败，请稍后重试
```

有 requestId 时：

```text
如问题持续，请联系客服并提供编号：XXXX
```

---

# 三十一、确认弹窗

只用于高风险操作：

- 取消服务；
- 删除草稿；
- 归档；
- 移除志愿者；
- 改关键状态；
- 导出敏感信息。

普通保存不弹确认。

---

# 三十二、权限 UI

前端可以隐藏无权限按钮，但：

> 前端权限不是安全边界。

所有敏感操作后端必须再次授权。

如果接口 403：
显示：

```text
您暂无权限执行此操作。
```

不得显示技术错误。

---

# 三十三、数据脱敏展示

手机号：

```text
138****8888
```

地址：
普通列表：

```text
丹阳市开发区
```

详细地址仅授权用户查看。

儿童信息：
列表优先使用：

```text
小明（化名）
```

具体规则由后台数据和权限控制。

---

# 三十四、可访问性与适老

必须：

- 点击区域充足；
- 对比度足够；
- 不仅靠颜色区分状态；
- 图标+文字；
- 表单错误有文字；
- 输入焦点明显；
- 主要按钮不放得过近；
- 不使用晃动/闪烁。

---

# 三十五、前端工程结构

## 小程序

```text
apps/miniprogram/
├─ miniprogram/
│  ├─ pages/
│  ├─ components/
│  ├─ services/
│  ├─ stores/
│  ├─ utils/
│  ├─ constants/
│  ├─ styles/
│  └─ assets/
├─ project.config.json
└─ tsconfig.json
```

---

## 后台

```text
apps/admin-web/src/
├─ api/
├─ assets/
├─ components/
├─ composables/
├─ constants/
├─ layouts/
├─ router/
├─ stores/
├─ styles/
├─ types/
├─ utils/
└─ views/
```

---

# 三十六、Design Token

必须统一定义，而不是组件内散落。

建议：

```ts
export const spacing = {
  xs: 4,
  sm: 8,
  md: 12,
  lg: 16,
  xl: 24,
  xxl: 32,
};
```

颜色、字号、圆角也集中。

---

# 三十七、API 使用规范

前端禁止页面内直接 `wx.request` / `fetch`。

统一：

```text
services/apiClient
```

统一处理：

- baseURL；
- auth；
- requestId；
- timeout；
- 401；
- 403；
- 429；
- 5xx；
- 重试策略。

---

# 三十八、前端缓存

可缓存：

- 用户基本资料；
- 公益项目公开列表；
- 服务分类；
- 表单草稿；
- UI 设置。

不得长期本地保存：

- 完整服务对象敏感档案；
- 详细家庭困难；
- 儿童敏感信息；
- 后台敏感数据；
- 长期访问 Token。

---

# 三十九、小程序性能

要求：

- 首页不要一次请求所有业务数据；
- 图片 lazy-load；
- 图片压缩；
- 分包；
- 首屏只加载必要资源；
- 避免超大组件库全量引入；
- 每个页面按需引用。

---

# 四十、管理后台性能

要求：

- 路由懒加载；
- 列表分页；
- 筛选防抖；
- 图表按需加载；
- 不一次性加载全部历史服务；
- 大附件不 preload。

---

# 四十一、前端测试

## Unit

测试：

- 状态格式化；
- 权限组件；
- 表单校验；
- 脱敏函数；
- timeline mapping；
- API error mapping。

## Component

关键组件：

- ServiceCategoryGrid
- StatusTimeline
- SensitiveText
- FileUploader
- DataTable

## E2E

必须覆盖：

```text
首页 → 我需要帮助 → 提交申请
首页 → 帮家人申请 → 提交申请
我的 → 我的服务 → 查看进度
后台 → 申请 → 受理 → 创建工单
后台 → 工单 → 服务记录 → 完成
后台 → 回访 → 继续帮助
志愿者 → 活动报名
```

---

# 四十二、视觉验收

Codex 完成页面后必须对照 `ui_reference.png`。

重点不是逐像素复制，而是保证：

- 色彩方向一致；
- 卡片风格一致；
- 信息密度一致；
- 主 CTA 一致；
- 圆角一致；
- 页面留白一致；
- 不出现复杂科技感；
- 不出现商业商城风。

---

# 四十三、页面完成定义

单页面只有满足以下条件才算完成：

- UI 完成；
- loading 完成；
- empty 完成；
- error 完成；
- 权限状态完成；
- API 对接完成；
- 表单校验完成；
- 防重复提交完成；
- 小尺寸测试完成；
- 真实设备测试完成；
- 无 Console Error；
- 无 TypeScript Error；
- 单元/组件测试通过；
- 对照设计规范完成。

---

# 四十四、Codex 前端执行指令

每次前端任务开始：

1. 阅读本文档；
2. 阅读 PRD；
3. 阅读 UI/UX 规范；
4. 检查 `ui_reference.png`；
5. 确认当前 Phase；
6. 只实现当前页面；
7. 不扩大功能。

每次页面完成后：

1. 运行 lint；
2. typecheck；
3. component tests；
4. build；
5. 截图；
6. 对照设计图自检；
7. 更新 `10_TASK_STATE.md`；
8. 汇报差异。

---

# 四十五、V1 前端开发顺序

严格顺序：

## Sprint UI-01

- Design Tokens
- 小程序导航
- 小程序首页
- 空状态/错误态/Skeleton
- 后台 Layout

## Sprint UI-02

- 服务类型选择
- 本人申请
- 代申请
- 提交成功
- 我的申请
- 服务进度

## Sprint UI-03

- 后台服务申请列表
- 服务申请详情
- 服务对象列表
- 服务对象详情

## Sprint UI-04

- 工单列表
- 工单详情
- 服务记录
- 回访中心

## Sprint UI-05

- 志愿者中心
- 志愿者后台
- 公益项目
- 公益活动

## Sprint UI-06

- 内容管理
- 数据统计
- 权限页面
- 系统设置
- 全局视觉修正
- 真机验收

未经批准，不要提前实现捐赠、AI、地图。

---

# 四十六、最终界面原则

前端实现结果必须使不同用户获得以下体验：

### 对老年人

“按钮大、字清楚、步骤少，我知道怎么求助。”

### 对家属

“我能方便地替父母或亲属申请。”

### 对志愿者

“我知道哪里需要我、我参加了什么、服务了多久。”

### 对工作人员

“每天打开后台，我就知道今天要处理什么。”

### 对负责人

“项目做了多少服务、服务了谁、完成到什么程度，都能看清。”

### 对社会公众

“我能看见乐活公益真正做了什么，也知道怎么参与。”

这就是 V1 前端是否成功的最终判断标准。