# 许愿树移动端功能设计文档 > 版本：V1.0 > 更新日期：2025-12-31 > 设计范围：Android移动端许愿树功能 --- ## 一、功能概述 ### 1.1 核心特性 - **服务端实时存储**：心愿数据通过API实时同步到服务端 - **节日主题**：支持不同节日的许愿活动 - **社交互动**：支持点赞、评论功能 - **多端同步**：数据云端存储，多设备共享 ### 1.2 数据流架构 ``` ┌─────────────────┐ API请求 ┌─────────────────┐ │ WishTreeActivity│ ◄──────────────► │ 后端服务 │ └─────────────────┘ └─────────────────┘ │ │ │ Retrofit │ MyBatis ▼ ▼ ApiService MySQL数据库 (许愿树接口) (eb_wishtree_*) ``` --- ## 二、页面设计 ### 2.1 主页面布局 (activity_wish_tree.xml) ``` ┌─────────────────────────────────────────────────────────┐ │ [许愿树标题] [🔍] [🔔] │ ← 顶部栏 ├─────────────────────────────────────────────────────────┤ │ ┌─────────────────────────────────────────────────────┐ │ │ │ 🎉 元旦许愿树 | 许下心愿，愿望成真 [12:30 05:00] │ │ ← 活动横幅 │ └─────────────────────────────────────────────────────┘ │ ├─────────────────────────────────────────────────────────┤ │ │ │ [心愿1] [心愿2] [心愿3] │ │ │ │ [心愿4] [心愿+] [心愿5] │ ← 许愿树区域 │ │ │ [心愿6] [心愿7] │ │ │ │ 元 │ │ 旦 │ │ 许 │ │ 愿 │ │ 树 │ │ │ ├─────────────────────────────────────────────────────────┤ │ 祈愿值：3/100 │ ← 底部区域 │ [ 前往祈愿 ] │ ├─────────────────────────────────────────────────────────┤ │ [首页] [缘池] [许愿树] [消息] [我的] │ ← 底部导航 └─────────────────────────────────────────────────────────┘ ``` ### 2.2 许愿对话框 (dialog_make_wish.xml) ``` ┌─────────────────────────────────────┐ │ 许下心愿 │ ├─────────────────────────────────────┤ │ ┌─────────────────────────────────┐ │ │ │ │ │ │ │ 请输入您的心愿... │ │ │ │ │ │ │ └─────────────────────────────────┘ │ │ 0/50 │ ├─────────────────────────────────────┤ │ [取消] [许愿] │ └─────────────────────────────────────┘ ``` ### 2.3 查看心愿对话框 (dialog_view_wish.xml) ``` ┌─────────────────────────────────────┐ │ 我的心愿 [✕] │ ├─────────────────────────────────────┤ │ ┌─────────────────────────────────┐ │ │ │ │ │ │ │ 新年快乐，万事如意！ │ │ │ │ │ │ │ └─────────────────────────────────┘ │ │ ❤ 128 💬 32 │ ├─────────────────────────────────────┤ │ [删除心愿] [愿望达成] │ └─────────────────────────────────────┘ ``` ### 2.4 成功提示对话框 (dialog_wish_success.xml) ``` ┌─────────────────────────────────────┐ │ │ │ ✨ │ │ 许愿成功！ │ │ │ └─────────────────────────────────────┘ ``` --- ## 三、API接口设计 ### 3.1 接口列表 | 接口 | 方法 | 路径 | 说明 | |------|------|------|------| | 获取节日列表 | GET | `/api/front/wishtree/festivals` | 获取所有启用的节日 | | 获取当前节日 | GET | `/api/front/wishtree/festivals/current` | 获取当前进行中的节日 | | 获取心愿列表 | GET | `/api/front/wishtree/wishes` | 分页获取心愿列表 | | 获取我的心愿 | GET | `/api/front/wishtree/wishes/my` | 获取当前用户的心愿 | | 发布心愿 | POST | `/api/front/wishtree/wishes` | 发布新心愿 | | 获取心愿详情 | GET | `/api/front/wishtree/wishes/{id}` | 获取心愿详情 | | 删除心愿 | DELETE | `/api/front/wishtree/wishes/{id}` | 删除我的心愿 | | 点赞心愿 | POST | `/api/front/wishtree/wishes/{id}/like` | 点赞 | | 取消点赞 | DELETE | `/api/front/wishtree/wishes/{id}/like` | 取消点赞 | | 获取评论 | GET | `/api/front/wishtree/wishes/{id}/comments` | 获取评论列表 | | 发表评论 | POST | `/api/front/wishtree/wishes/{id}/comments` | 发表评论 | | 获取背景素材 | GET | `/api/front/wishtree/backgrounds` | 获取背景素材列表 | ### 3.2 请求/响应示例 #### 发布心愿 ```json // POST /api/front/wishtree/wishes // Request: { "festivalId": 1, "content": "新年快乐，万事如意！", "backgroundId": 1 } // Response: { "code": 200, "message": "success", "data": { "id": 10001, "uid": 1001, "festivalId": 1, "content": "新年快乐，万事如意！", "status": 1, "likeCount": 0, "commentCount": 0, "createTime": "2025-12-31 12:00:00" } } ``` #### 获取我的心愿列表 ```json // GET /api/front/wishtree/wishes/my?page=1&limit=10 // Response: { "code": 200, "data": { "list": [ { "id": 10001, "uid": 1001, "nickname": "用户昵称", "avatar": "https://xxx/avatar.jpg", "festivalId": 1, "festivalName": "元旦", "festivalIcon": "🎉", "content": "新年快乐，万事如意！", "backgroundImage": "https://xxx/bg1.jpg", "status": 1, "likeCount": 128, "commentCount": 32, "isLiked": false, "createTime": "2025-12-31 12:00:00" } ], "total": 5, "pageNum": 1, "pageSize": 10 } } ``` --- ## 四、代码结构 ### 4.1 文件清单 ``` android-app/app/src/main/java/com/example/livestreaming/ ├── WishTreeActivity.java # 许愿树主页面 └── net/ ├── ApiService.java # API接口定义（含许愿树接口） ├── WishtreeRequest.java # 请求类 │ ├── PublishWish # 发布心愿请求 │ └── AddComment # 发表评论请求 └── WishtreeResponse.java # 响应类 ├── Festival # 节日信息 ├── Wish # 心愿信息 ├── Background # 背景素材 ├── Comment # 评论信息 ├── WishPage # 心愿分页数据 └── CommentPage # 评论分页数据 android-app/app/src/main/res/layout/ ├── activity_wish_tree.xml # 主页面布局 ├── dialog_make_wish.xml # 许愿对话框 ├── dialog_view_wish.xml # 查看心愿对话框 └── dialog_wish_success.xml # 成功提示对话框 android-app/app/src/main/res/drawable/ ├── bg_wish_tree_banner.xml # 横幅背景 ├── bg_wish_tree_timer.xml # 倒计时背景 ├── bg_wish_card.xml # 心愿卡片背景 ├── bg_wish_card_add.xml # 添加心愿卡片背景 ├── bg_trunk_text.xml # 树干文字背景 ├── bg_dialog_rounded.xml # 对话框圆角背景 ├── bg_edit_text.xml # 输入框背景 ├── bg_btn_primary.xml # 主按钮背景 └── bg_btn_cancel.xml # 取消按钮背景 ``` ### 4.2 核心类设计 #### WishTreeActivity.java ```java public class WishTreeActivity extends AppCompatActivity { private ActivityWishTreeBinding binding; private ApiService apiService; private List myWishes; private WishtreeResponse.Festival currentFestival; // 生命周期方法 onCreate() // 初始化页面、加载数据 onResume() // 刷新数据 onStart() // 启动倒计时 onStop() // 停止倒计时 // 数据加载 loadCurrentFestival() // 加载当前节日 loadMyWishes() // 加载我的心愿 // UI更新 updateBannerText() // 更新横幅文字 updateWishCards() // 更新心愿卡片 updateWishCount() // 更新祈愿值 updateBannerTimer() // 更新倒计时 // 用户交互 showMakeWishInputDialog() // 显示许愿对话框 showViewWishDialog() // 显示查看心愿对话框 showSuccessDialog() // 显示成功提示 // API调用 publishWish() // 发布心愿 deleteWish() // 删除心愿 } ``` #### WishtreeRequest.java ```java public class WishtreeRequest { // 发布心愿请求 public static class PublishWish { public Integer festivalId; public String content; public Integer backgroundId; } // 发表评论请求 public static class AddComment { public String content; public Long parentId; } } ``` #### WishtreeResponse.java ```java public class WishtreeResponse { // 节日信息 public static class Festival { public int id; public String name; public String icon; public String startDate; public String endDate; public String themeColor; public int status; } // 心愿信息 public static class Wish { public long id; public int uid; public String nickname; public String avatar; public int festivalId; public String festivalName; public String festivalIcon; public String content; public String backgroundImage; public int status; public int likeCount; public int commentCount; public Boolean isLiked; public String createTime; } // 背景素材 public static class Background { public int id; public String name; public String image; public int festivalId; public int status; } // 评论信息 public static class Comment { public long id; public long wishId; public int uid; public String nickname; public String avatar; public String content; public long parentId; public String createTime; } } ``` --- ## 五、交互流程 ### 5.1 页面加载流程 ``` ┌─────────────┐ │ onCreate │ └──────┬──────┘ │ ▼ ┌─────────────────────────────────────────────────────┐ │ 1. 初始化ApiService │ │ 2. 设置底部导航 │ │ 3. 设置心愿卡片点击事件 │ │ 4. 启动横幅倒计时 │ │ 5. 加载当前节日 (loadCurrentFestival) │ │ 6. 加载我的心愿 (loadMyWishes) │ └─────────────────────────────────────────────────────┘ ``` ### 5.2 发布心愿流程 ``` ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ 点击许愿按钮 │ ──► │ 显示许愿对话框│ ──► │ 输入心愿内容 │ └─────────────┘ └─────────────┘ └──────┬──────┘ │ ┌───────────────────────────────────────┘ │ ▼ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ 点击许愿按钮 │ ──► │ 调用API发布 │ ──► │ 显示成功提示 │ └─────────────┘ └─────────────┘ └──────┬──────┘ │ ┌───────────────────────────────────────┘ │ ▼ ┌─────────────────────┐ │ 重新加载心愿列表 │ │ 更新心愿卡片显示 │ └─────────────────────┘ ``` ### 5.3 查看/删除心愿流程 ``` ┌─────────────┐ ┌─────────────┐ │ 点击心愿卡片 │ ──► │ 显示心愿详情 │ └─────────────┘ └──────┬──────┘ │ ┌─────────────────┼─────────────────┐ │ │ │ ▼ ▼ ▼ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ 点击关闭 │ │ 点击删除 │ │ 愿望达成 │ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ │ │ │ ▼ ▼ ▼ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ 关闭对话框 │ │ 调用API删除│ │ 调用API删除│ └───────────┘ │ 刷新列表 │ │ 显示祝贺 │ └───────────┘ └───────────┘ ``` --- ## 六、状态管理 ### 6.1 心愿状态 | 状态值 | 说明 | 显示 | |--------|------|------| | 0 | 待审核 | 审核中 | | 1 | 已通过 | 正常显示 | | 2 | 已拒绝 | 不显示 | ### 6.2 页面状态 ```java // 心愿数据 private List myWishes = new ArrayList<>(); // 当前节日 private WishtreeResponse.Festival currentFestival; // 状态更新时机 - onCreate: 初始加载 - onResume: 每次返回页面刷新 - 发布/删除心愿后: 重新加载 ``` --- ## 七、错误处理 ### 7.1 网络错误 ```java @Override public void onFailure(Call<...> call, Throwable t) { Toast.makeText(context, "网络错误", Toast.LENGTH_SHORT).show(); } ``` ### 7.2 业务错误 ```java if (response.body().getCode() != 200) { String msg = response.body().getMessage(); Toast.makeText(context, msg != null ? msg : "操作失败", Toast.LENGTH_SHORT).show(); } ``` ### 7.3 空数据处理 ```java if (myWishes == null) { myWishes = new ArrayList<>(); } ``` --- ## 八、后续扩展 ### 8.1 待实现功能 - [ ] 心愿列表页面（查看所有用户心愿） - [ ] 点赞功能 - [ ] 评论功能 - [ ] 背景素材选择 - [ ] 节日主题切换 - [ ] 心愿分享功能 ### 8.2 优化方向 - 添加加载状态指示器 - 添加下拉刷新 - 添加心愿卡片动画效果 - 支持心愿图片上传 - 添加本地缓存减少网络请求 --- ## 九、数据库表结构 ### 9.1 相关表 ```sql -- 节日表 eb_wishtree_festival (id, name, icon, start_date, end_date, theme_color, status, ...) -- 心愿表 eb_wishtree_wish (id, uid, festival_id, content, background_id, status, like_count, comment_count, ...) -- 点赞表 eb_wishtree_like (id, uid, wish_id, create_time) -- 评论表 eb_wishtree_comment (id, wish_id, uid, content, parent_id, status, ...) -- 背景素材表 eb_wishtree_background (id, name, image, festival_id, status, ...) ``` --- ## 十、测试要点 ### 10.1 功能测试 - [ ] 页面正常加载 - [ ] 节日信息正确显示 - [ ] 心愿卡片正确显示 - [ ] 发布心愿成功 - [ ] 删除心愿成功 - [ ] 愿望达成功能正常 - [ ] 底部导航切换正常 ### 10.2 异常测试 - [ ] 网络断开时的提示 - [ ] 未登录时的处理 - [ ] 空数据时的显示 - [ ] 心愿内容为空时的校验