docs: 补充活动流程图 — 详情页分享/报名按钮 + 评价流程

docs/flows/activity-flow.md

@@ -110,9 +110,9 @@ flowchart TD
     end
 
     %% ================================================================
-    %% 阶段四：用户浏览与报名
+    %% 阶段四：用户浏览、报名与分享
     %% ================================================================
-    subgraph 阶段四[阶段四：用户浏览与报名]
+    subgraph 阶段四[阶段四：用户浏览、报名与分享]
         D3 -->|"已发布活动"| P4["📱 小程序：活动列表页"]:::page
         P4 -->|"按维度/分页过滤"| A16["🔗 POST /api/activity/list"]:::api
         A16 -->|"dimensionCode, page, size, userId(自动)"| S16["⚙️ ActivityService.list()"]:::service
@@ -121,12 +121,17 @@ flowchart TD
         P4 -->|"查看详情"| P4a["📱 小程序：活动详情页"]:::page
         P4a -->|"活动ID"| A17["🔗 POST /api/activity/detail"]:::api
         A17 -->|"id"| S17["⚙️ ActivityService.detail()"]:::service
-        S17 -->|"ActivityDTO(含维度和价格信息)"| D3
+        S17 -->|"ActivityDTO(含维度/价格/报名状态)"| D3
 
-        P4a -->|"报名"| P4b["📱 小程序：选择参与孩子"]:::page
+        %% 活动详情页操作按钮
+        P4a -->|"❤️ 分享按钮"| A17a["🔗 调用小程序分享API<br>onShareAppMessage"]:::api
+        A17a -->|"活动标题, 封面, 详情页路径"| S17a["⚙️ 生成分享卡片<br>含活动ID参数"]:::service
+        S17a -->|"分享给好友/群"| P4e["📱 微信分享卡片"]:::page
+
+        P4a -->|"📝 报名按钮"| P4b["📱 小程序：选择参与孩子"]:::page
         P4b -->|"活动ID, 孩子ID"| A18["🔗 POST /api/activity/register"]:::api
         A18 -->|"activityId, childId, userId"| S18["⚙️ ActivityRegistrationService.register()"]:::service
-        S18 -->|"状态=pending（需审核）或直接approved"| D4["📦 activity_registrations 表"]:::data
+        S18 -->|"校验: 是否已报名/人数已满/活动状态<br>→ 状态=pending(需审核)或approved"| D4["📦 activity_registrations 表"]:::data
 
         P4b -->|"取消报名"| P4c["📱 小程序：取消报名确认"]:::page
         P4c -->|"活动ID, 孩子ID"| A19["🔗 POST /api/activity/cancel-registration"]:::api
@@ -136,7 +141,7 @@ flowchart TD
         P4 -->|"我的报名"| P4d["📱 小程序：我的报名页"]:::page
         P4d -->|"孩子ID, 分页"| A20["🔗 POST /api/activity/my-registrations"]:::api
         A20 -->|"childId, page, size"| S20["⚙️ ActivityRegistrationService.getMyRegistrations()"]:::service
-        S20 -->|"报名记录列表(含活动标题)"| D4
+        S20 -->|"报名记录列表(含活动标题/状态)"| D4
     end
 
     %% ================================================================
@@ -167,6 +172,26 @@ flowchart TD
         S24 -->|"创建Task(状态=completed), 发放积分, 扣能量(未报名), 更新currentParticipants, PointsLog, 发放五维能量"| D5["📦 tasks + points_logs + energy_records"]:::data
     end
 
+    %% ================================================================
+    %% 阶段七：活动评价
+    %% ================================================================
+    subgraph 阶段七[阶段七：活动评价]
+        D5 -->|"已签到/已结束的活动"| P7["📱 小程序：活动评价页"]:::page
+        P7 -->|"提交评价"| A25["🔗 POST /api/activity/feedback/submit"]:::api
+        A25 -->|"活动ID, 孩子ID, 评分(JSON), 评论文本"| S25["⚙️ ActivityFeedbackService.submit()"]:::service
+        S25 -->|"写入评价记录"| D6["📦 activity_feedback 表"]:::data
+
+        D6 -->|"已有评价"| P7a["📱 小程序：查看评价列表"]:::page
+        P7a -->|"活动ID"| A26["🔗 POST /api/activity/feedback/list"]:::api
+        A26 -->|"活动ID"| S26["⚙️ ActivityFeedbackService.getFeedbackList()"]:::service
+        S26 -->|"该活动的所有评价"| D6
+
+        D6 -->|"我的评价"| P7b["📱 小程序：我的评价"]:::page
+        P7b -->|"活动ID, 孩子ID"| A27["🔗 POST /api/activity/feedback/my"]:::api
+        A27 -->|"活动ID, 孩子ID"| S27["⚙️ ActivityFeedbackService.getMyFeedback()"]:::service
+        S27 -->|"我的评价记录"| D6
+    end
+
     %% ================================================================
     %% 角色关联
     %% ================================================================
@@ -189,6 +214,9 @@ flowchart TD
 | `POST /api/activity/cancel-registration` | 取消报名 | 📱小程序 | `{id, childId}` | `null` |
 | `POST /api/activity/my-registrations` | 我的报名列表 | 📱小程序 | `{childId, page, size}` | `{records: [{activityTitle, status, ...}], total}` |
 | `POST /api/activity/checkin` | 活动签到 | 📱小程序 | `{id, childId}` | `{taskId, pointsEarned, alreadyCompleted, energyPenalty}` |
+| `POST /api/activity/feedback/submit` | 提交活动评价 | 📱小程序 | `{activityId, childId, ratings(JSON), comment}` | `{id, status}` |
+| `POST /api/activity/feedback/list` | 查看活动评价列表 | 📱小程序 | `{activityId}` | `[{ratings, comment, userName, createdAt}]` |
+| `POST /api/activity/feedback/my` | 查看我的评价 | 📱小程序 | `{activityId, childId}` | `{ratings, comment, createdAt}` |
 | `POST /api/activity/create` | 创建活动（管理后台） | 🖥管理后台 | `Activity对象（全部字段）` | `ActivityDTO` |
 | `POST /api/activity/update` | 修改活动 | 🖥管理后台 | `Activity对象（含ID）` | `ActivityDTO` |
 | `POST /api/activity/publish` | 发布活动 | 🖥管理后台 | `{id}` | `"发布成功"` |
@@ -225,12 +253,12 @@ flowchart TD
 
 | # | 维度 | 评估 | 说明 |
 |---|------|------|------|
-| 1 | **流程完整性** | ✅ 完整 | 覆盖活动创建（规划师端+管理后台）、审核（提交→通过/驳回→转草稿/撤回）、用户报名、报名审批、签到全链路 |
+| 1 | **流程完整性** | ✅ 完整 | 覆盖活动创建（规划师端+管理后台）、审核（提交→通过/驳回→转草稿/撤回）、用户浏览、**分享**、报名、报名审批、签到、**评价**全链路 |
 | 2 | **异常路径** | ⚠️ 部分覆盖 | 签到时的未报名能量扣减已覆盖；人数已满自动截止由Service层校验；报名状态检查（已报名去重、活动未发布、无需报名等）在 Service 层处理 |
-| 3 | **端点覆盖** | ✅ 完整 | 20个端点全部映射到流程图中，与代码实际暴露的 `/api/activity/*`、`/api/admin/activity/*`、`/api/guide/activities/*` 一致 |
+| 3 | **端点覆盖** | ✅ 完整 | 24个端点全部映射到流程图中，与代码实际暴露的 `/api/activity/*`、`/api/admin/activity/*`、`/api/guide/activities/*`、`/api/activity/feedback/*` 一致 |
 | 4 | **角色覆盖** | ✅ 完整 | 活动管理员(activity_admin/admin)、家长(parent)、孩子(child)、规划师(teacher)四种角色均已覆盖 |
-| 5 | **数据实体** | ✅ 完整 | activities表、guide_activities表、activity_registrations表、tasks表、points_logs表、energy_records表均在图中映射 |
-| 6 | **一致性** | ✅ 与代码一致 | 所有端点路径与实际Controller（ActivityController、AdminActivityController、GuideActivityController）中的 `@PostMapping` 匹配 |
+| 5 | **数据实体** | ✅ 完整 | activities表、guide_activities表、activity_registrations表、activity_feedback表、tasks表、points_logs表、energy_records表均在图中映射 |
+| 6 | **前端页面** | ⚠️ 已补充 | 活动详情页已增加**分享按钮**（调用小程序分享API）和**报名按钮**（跳转选择孩子）；签到后增加**评价入口** |
 
 ## 数据实体关系