admin/lehuo
Template
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
9622d249be534f77199999581c7195acf4eb95cf
lehuo/docs/15_FRONTEND_DESIGN_SPEC.md
T
admin c3dd9be674 feat: complete V1 phases 0-7
2026-08-12 14:35:12 +08:00

20 KiB
Raw Blame History

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：

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 字体

优先使用系统字体。

微信小程序：

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

Web 后台： 同上。

2.3 字号

小程序

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

核心原则：

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

适老场景：

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

2.4 圆角

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

2.5 间距体系

采用 4 的倍数：

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

推荐：

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

2.6 阴影

仅轻阴影：

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

禁止重阴影。

三、图标规范

优先使用 TDesign 官方图标。

禁止：

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

核心图标：

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

四、图片规范

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

禁止：

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

建议图片比例：

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

五、小程序底部导航

固定四项：

首页
服务
公益
我的

图标 + 中文。

默认：

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

不要设计第五个 Tab。

六、小程序首页

6.1 页面目标

用户 3 秒内知道：

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

6.2 页面结构

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

6.3 顶部

左：

  • 乐活公益 Logo
  • “乐活公益”

右：

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

6.4 Banner

文案建议：

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

Banner 不做自动轮播。

CTA 不超过 1 个。

6.5 核心入口

必须视觉突出：

第一按钮

我需要帮助

第二按钮

帮家人申请

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

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

6.6 服务分类

四个核心：

关爱老人
困境妇女
儿童关爱
残障帮扶

补充：

志愿服务
公益项目
爱心活动
更多服务

每项：

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

6.7 服务进度

若用户存在申请：

显示：

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

若无： 不显示此卡片。

6.8 公益项目

标题：

公益项目              更多 >

项目卡片内容：

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

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

七、服务申请页面

7.1 页面原则

不一次展示长表单。

采用步骤式：

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

7.2 步骤一：服务类型

大卡片选择：

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

每张卡片包含：

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

7.3 步骤二：申请关系

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

7.4 步骤三：基本联系信息

字段：

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

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

7.5 步骤四：需求描述

组件：

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

文案：

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

7.6 步骤五：确认

必须显示：

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

按钮：

提交申请

7.7 提交成功

成功页：

图标： ✅

标题：

申请已提交

说明：

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

显示：

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

按钮：

查看服务进度
返回首页

八、我的服务 / 进度页面

采用 Timeline。

状态：

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

当前状态高亮。

每个节点：

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

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

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

9.1 页面结构

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

9.2 顶部摘要

示例：

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

右侧操作：

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

9.3 敏感字段

默认脱敏。

点击“查看完整信息”：

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

十、服务记录页面

记录卡片：

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

服务内容：
……

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

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

工作人员可新增。

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

十一、反馈与评价

页面保持简单：

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

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

其他反馈
[输入框]

提交反馈

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

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

十二、公益项目详情

结构：

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

底部固定 CTA：

我要参与

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

十三、志愿者中心

13.1 顶部身份卡

李志愿者
已认证志愿者

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

13.2 快捷入口

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

13.3 功能

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

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

十四、个人中心

顶部用户卡：

头像
昵称
手机号脱敏

数据摘要：

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

V1 建议优先：

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

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

15.1 页面结构

桌面优先：

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

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

15.2 导航

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

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

十六、后台工作台

16.1 顶部数据卡

最多 4~6 项：

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

16.2 图表

V1 最多 2~3 张：

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

不要堆 10 个图。

16.3 快捷入口

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

十七、服务申请列表

17.1 筛选

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

按钮：

查询
重置

17.2 表格列

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

操作：

查看
受理

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

十八、服务对象列表

列：

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

默认手机号脱敏。

十九、服务工单详情

必须采用状态进度条：

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

内容分左右两栏：

左：

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

右：

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

二十、回访中心

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

顶部：

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

列表：

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

明显突出逾期项。

二十一、志愿者管理

列表字段：

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

支持：

查看
审核
暂停
恢复

二十二、公益项目后台

项目详情后台分：

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

V1 不做复杂甘特图。

二十三、活动管理

活动创建步骤：

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

报名列表：

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

二十四、内容管理

内容列表：

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

状态：

草稿
待审核
已发布
已归档

编辑器：

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

二十五、数据统计页面

25.1 顶部 KPI

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

25.2 图表

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

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

二十六、响应式

小程序

覆盖常见微信手机尺寸。

最低关注：

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

禁止水平滚动。

后台

主目标：

  • 1366×768
  • 1440×900
  • 1920×1080

最低：

  • 1280px 宽正常使用。

小于 1024：

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

二十七、组件清单

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

小程序

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

后台

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

二十八、状态规范

所有页面至少实现：

loading
success
empty
error
no-permission
offline / retry

不允许只有 success。

二十九、Skeleton

列表和首页采用 Skeleton。

不要用全屏 Spinner 阻断用户。

三十、Toast / Message

成功：

���交成功
保存成功
操作已完成

失败：

提交失败，请稍后重试

有 requestId 时：

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

三十一、确认弹窗

只用于高风险操作：

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

普通保存不弹确认。

三十二、权限 UI

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

前端权限不是安全边界。

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

如果接口 403： 显示：

您暂无权限执行此操作。

不得显示技术错误。

三十三、数据脱敏展示

手机号：

138****8888

地址： 普通列表：

丹阳市开发区

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

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

小明（化名）

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

三十四、可访问性与适老

必须：

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

三十五、前端工程结构

小程序

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

后台

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

三十六、Design Token

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

建议：

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

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

三十七、API 使用规范

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

统一：

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

必须覆盖：

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

四十二、视觉验收

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 前端是否成功的最终判断标准。

Reference in New Issue View Git Blame Copy Permalink