zhibo/.kiro/specs/wishtree-mobile/requirements.md

许愿树移动端设计规范

版本：V2.1
更新日期：2025-12-31
设计范围：Android移动端许愿树功能完善

---

一、设计原则

1. 不修改后端：复用现有API，不做任何后端改动
2. 不修改管理端：管理端功能保持不变
3. 功能完善：确保所有功能逻辑正确

---

二、现有后端API（不可修改）

接口	方法	路径	说明
获取节日列表	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	获取背景素材列表

---

三、用户故事与验收标准

US-001: 查看许愿树主页

作为 用户
我想要 进入许愿树页面查看许愿树和我的心愿
以便于 了解当前活动和管理我的心愿

验收标准：

• 页面显示许愿树背景图
• 显示当前节日活动横幅（调用 /festivals/current）
• 显示我的心愿卡片（调用 /wishes/my，最多7个）
• 显示"添加心愿"按钮
• 底部导航栏正确高亮"许愿树"选项
• 显示倒计时
• 显示祈愿值统计

---

US-002: 发布心愿

作为 已登录用户
我想要 发布一个新的心愿
以便于 表达我的愿望

验收标准：

• 点击"添加心愿"或空白卡片弹出许愿对话框
• 输入框限制50字，显示字数统计
• 未登录时提示登录并跳转登录页
• 调用 POST /wishes 发布心愿
• 提交成功后显示成功动画
• 心愿列表自动刷新

---

US-003: 查看我的心愿

作为 用户
我想要 查看我已发布的心愿详情
以便于 回顾我的愿望

验收标准：

• 点击心愿卡片弹出详情对话框
• 显示心愿内容、点赞数、评论数
• 提供"删除心愿"和"愿望达成"操作

---

US-004: 删除心愿

作为 用户
我想要 删除我不想要的心愿
以便于 管理我的心愿列表

验收标准：

• 点击"删除心愿"弹出确认对话框
• 确认后调用 DELETE /wishes/{id} 删除
• 删除成功后刷新列表
• 显示删除成功提示

---

US-005: 愿望达成

作为 用户
我想要 标记我的愿望已达成
以便于 庆祝愿望实现

验收标准：

• 点击"愿望达成"弹出确认对话框
• 确认后调用 DELETE /wishes/{id} 删除心愿
• 显示庆祝动画（持续2秒）
• 刷新心愿列表

---

US-006: 查看节日活动

作为 用户
我想要 看到当前进行中的节日活动
以便于 参与节日许愿

验收标准：

• 页面顶部显示活动横幅
• 横幅显示节日名称
• 显示倒计时
• 无活动时显示默认文案

---

四、移动端文件结构

android-app/app/src/main/java/com/example/livestreaming/
├── WishTreeActivity.java              # 许愿树主页面
└── net/
    ├── ApiService.java                # API接口定义
    ├── WishtreeRequest.java           # 请求类
    └── WishtreeResponse.java          # 响应类

android-app/app/src/main/res/layout/
├── activity_wish_tree.xml             # 主页面布局
├── dialog_make_wish.xml               # 许愿对话框
├── dialog_view_wish.xml               # 查看心愿对话框
├── dialog_wish_success.xml            # 成功提示对话框
└── dialog_wish_complete.xml           # 愿望达成对话框

---

五、数据模型

5.1 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 int isLunar;
        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 int backgroundId;
        public String backgroundImage;
        public int status;          // 0待审核 1通过 2拒绝
        public int likeCount;
        public int commentCount;
        public Boolean isLiked;
        public String createTime;
    }
    
    // 分页数据
    public static class WishPage {
        public List<Wish> list;
        public int total;
        public int pageNum;
        public int pageSize;
    }
}

5.2 WishtreeRequest.java

public class WishtreeRequest {
    // 发布心愿请求
    public static class PublishWish {
        public Integer festivalId;
        public String content;
        public Integer backgroundId;
    }
}

---

六、核心交互流程

6.1 页面加载

onCreate()
    ├── 初始化ApiService
    ├── 启动横幅倒计时
    ├── 设置底部导航
    ├── 设置心愿卡片点击事件
    ├── loadCurrentFestival() → 更新横幅文字
    └── loadMyWishes() → 更新心愿卡片、祈愿值

6.2 发布心愿

点击"添加心愿"
    ├── checkLogin() → 未登录跳转登录页
    ├── showMakeWishInputDialog()
    ├── 输入内容（≤50字）
    ├── publishWish() → POST /wishes
    ├── 成功 → showSuccessDialog() → loadMyWishes()
    └── 失败 → Toast提示

6.3 删除/达成心愿

点击心愿卡片
    ├── showViewWishDialog()
    ├── 点击"删除心愿"
    │   ├── 确认对话框
    │   ├── DELETE /wishes/{id}
    │   └── 成功 → Toast → loadMyWishes()
    └── 点击"愿望达成"
        ├── 确认对话框
        ├── DELETE /wishes/{id}
        └── 成功 → 庆祝动画 → loadMyWishes()

---

七、错误处理

场景	处理方式
网络错误	Toast "网络错误"
业务错误	Toast 显示后端返回的message
未登录	跳转LoginActivity
空数据	显示空列表，卡片显示空白
内容为空	Toast "请输入心愿内容"
内容超长	Toast "心愿内容不能超过50字"

---

八、实现任务清单

Phase 1: 数据层 ✅

• WishtreeResponse.java - 响应类
• WishtreeRequest.java - 请求类
• ApiService.java - 接口定义

Phase 2: UI层 ✅

• activity_wish_tree.xml - 主页面
• dialog_make_wish.xml - 许愿对话框
• dialog_view_wish.xml - 查看心愿对话框
• dialog_wish_success.xml - 成功提示
• dialog_wish_complete.xml - 愿望达成

Phase 3: 逻辑层 ✅

• WishTreeActivity.java - 核心逻辑
• 页面加载与数据刷新
• 发布心愿功能
• 删除心愿功能
• 愿望达成功能
• 登录检查
• 错误处理

---

九、测试要点

功能测试

• 页面正常加载
• 节日信息正确显示
• 心愿卡片正确显示（最多7个）
• 发布心愿成功
• 删除心愿成功
• 愿望达成功能正常
• 底部导航切换正常

异常测试

• 网络断开时的提示
• 未登录时跳转登录页
• 空数据时的显示
• 心愿内容校验（空、超长）