zhibo/android-app/移动端许愿树功能设计文档.md

许愿树移动端功能设计文档

版本：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 请求/响应示例

发布心愿

// 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"
  }
}

获取我的心愿列表

// 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

public class WishTreeActivity extends AppCompatActivity {
    
    private ActivityWishTreeBinding binding;
    private ApiService apiService;
    private List<WishtreeResponse.Wish> myWishes;
    private WishtreeResponse.Festival currentFestival;
    
    // 生命周期方法
    onCreate()      // 初始化页面、加载数据
    onResume()      // 刷新数据
    onStart()       // 启动倒计时
    onStop()        // 停止倒计时
    
    // 数据加载
    loadCurrentFestival()   // 加载当前节日
    loadMyWishes()          // 加载我的心愿
    
    // UI更新
    updateBannerText()      // 更新横幅文字
    updateWishCards()       // 更新心愿卡片
    updateWishCount()       // 更新祈愿值
    updateBannerTimer()     // 更新倒计时
    
    // 用户交互
    showMakeWishInputDialog()   // 显示许愿对话框
    showViewWishDialog()        // 显示查看心愿对话框
    showSuccessDialog()         // 显示成功提示
    
    // API调用
    publishWish()           // 发布心愿
    deleteWish()            // 删除心愿
}

WishtreeRequest.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

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 页面状态

// 心愿数据
private List<WishtreeResponse.Wish> myWishes = new ArrayList<>();

// 当前节日
private WishtreeResponse.Festival currentFestival;

// 状态更新时机
- onCreate: 初始加载
- onResume: 每次返回页面刷新
- 发布/删除心愿后: 重新加载

---

七、错误处理

7.1 网络错误

@Override
public void onFailure(Call<...> call, Throwable t) {
    Toast.makeText(context, "网络错误", Toast.LENGTH_SHORT).show();
}

7.2 业务错误

if (response.body().getCode() != 200) {
    String msg = response.body().getMessage();
    Toast.makeText(context, msg != null ? msg : "操作失败", Toast.LENGTH_SHORT).show();
}

7.3 空数据处理

if (myWishes == null) {
    myWishes = new ArrayList<>();
}

---

八、后续扩展

8.1 待实现功能

• 心愿列表页面（查看所有用户心愿）
• 点赞功能
• 评论功能
• 背景素材选择
• 节日主题切换
• 心愿分享功能

8.2 优化方向

• 添加加载状态指示器
• 添加下拉刷新
• 添加心愿卡片动画效果
• 支持心愿图片上传
• 添加本地缓存减少网络请求

---

九、数据库表结构

9.1 相关表

-- 节日表
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 异常测试

• 网络断开时的提示
• 未登录时的处理
• 空数据时的显示
• 心愿内容为空时的校验