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