1671 lines
20 KiB
Markdown
1671 lines
20 KiB
Markdown
# 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
|
||
关爱老人
|
||
困境妇女
|
||
儿童关爱
|
||
残障帮扶
|
||
```
|
||
|
||
补充：
|
||
|
||
```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 前端是否成功的最终判断标准。
|