538 lines
19 KiB
Markdown
538 lines
19 KiB
Markdown
# 许愿树移动端功能设计文档
|
||
|
||
> 版本：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<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
|
||
|
||
```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<WishtreeResponse.Wish> 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 异常测试
|
||
|
||
- [ ] 网络断开时的提示
|
||
- [ ] 未登录时的处理
|
||
- [ ] 空数据时的显示
|
||
- [ ] 心愿内容为空时的校验
|