feat: 添加分支管理说明

(cherry picked from commit a6becf67ff)

doc.md

@@ -0,0 +1,116 @@
+# 微信小程序多人协作分支管理规范
+
+## 一、分支结构
+
+```
+main (主分支/生产环境)
+  └── test (测试分支)
+        └── feature/xxx (个人开发分支)
+```
+
+| 分支 | 用途 | 稳定性 |
+|------|------|--------|
+| main | 生产环境代码 | 最高，仅接受测试通过的代码合并 |
+| test | 测试环境，用于体验版发布 | 中，需验证后合并到 main |
+| feature/xxx | 个人开发分支 | 低，按需命名，如 `feature/user-center` |
+
+---
+
+## 二、开发流程
+
+### 1. 开始开发
+
+```bash
+# 确保本地 main 最新
+git checkout main
+git pull origin main
+
+# 从 main 创建自己的开发分支
+git checkout -b feature/your-name-work
+```
+
+### 2. 开发阶段
+
+- 在个人分支上开发功能
+- 频繁提交，保持原子性提交
+- 定期 `git pull origin main` 同步主线变更，避免合并冲突累积
+
+```bash
+git add .
+git commit -m "feat: 完成xxx功能"
+```
+
+### 3. 合并到 test 分支
+
+```bash
+# 切换到 test
+git checkout test
+git pull origin test
+
+# 合并个人分支
+git merge feature/your-name-work
+
+# 推送 test 分支
+git push origin test
+```
+
+### 4. 打包上传体验版
+
+```bash
+# 执行打包
+npm run build
+```
+
+打包完成后：
+
+1. 打开 **微信开发者工具**
+2. 导入项目，选择 `dist/build/mp-weixin` 目录
+3. 在开发者工具中点击 **上传**
+4. 登录 [微信公众平台](https://mp.weixin.qq.com)
+5. 进入 **管理->版本管理**
+6. 找到刚上传的版本，点击 **选为体验版**
+
+---
+
+## 三、合并到 main 分支
+
+当 test 分支验证通过后，将其合并到 main：
+
+```bash
+git checkout main
+git pull origin main
+
+git merge origin/test
+
+git push origin main
+```
+
+---
+
+## 四、冲突处理
+
+合并时如有冲突，在个人分支解决后再合并：
+
+```bash
+git checkout feature/your-name-work
+git merge main
+# 解决冲突后
+git add .
+git commit -m "merge: 解决与main的冲突"
+git push origin feature/your-name-work
+
+# 重新合并到 test
+git checkout test
+git merge feature/your-name-work
+git push origin test
+```
+
+---
+
+## 五、注意事项
+
+1. **禁止直接向 main 和 test 分支提交代码**，必须通过合并
+2. **每次合并前先拉取最新代码**，避免覆盖他人改动
+3. **体验版发布前确认代码已提交**，避免遗漏
+4. **开发分支命名建议**：`feature/姓名-功能名`，如 `feature/zhangsan-login`
+5. **删除已合并的开发分支**：`git branch -d feature/your-name-work`

src/components/Header.vue

@@ -6,7 +6,7 @@ import Avatar from "@/components/Avatar.vue";
 import useStore from "@/store";
 import { storeToRefs } from "pinia";
 const store = useStore();
-const { user } = storeToRefs(store);
+const { user, game } = storeToRefs(store);
 
 const currentPage = computed(() => {
   const pages = getCurrentPages();
@@ -59,8 +59,6 @@ const loading = ref(false);
 const pointBook = ref(null);
 const showProgress = ref(false);
 const heat = ref(0);
-/** 当前对战房间的房号，由 battle-room 页面通过 uni.$emit 传入 */
-const battleRoomNumber = ref("");
 
 const updateLoading = (value) => {
   loading.value = value;
@@ -70,14 +68,6 @@ const updateHot = (value) => {
   heat.value = value;
 };
 
-/**
- * 接收 battle-room 页面发出的房间信息，更新房号展示
- * @param {{ roomNumber: string }} info
- */
-const updateBattleRoomInfo = (info) => {
-  battleRoomNumber.value = info.roomNumber || "";
-};
-
 onMounted(() => {
   const pages = getCurrentPages();
   const currentPage = pages[pages.length - 1];
@@ -94,11 +84,9 @@ onMounted(() => {
     showProgress.value = true;
   }
   uni.$on("update-hot", updateHot);
-  uni.$on("battle-room-info", updateBattleRoomInfo);
 });
 onBeforeUnmount(() => {
   uni.$off("update-hot", updateHot);
-  uni.$off("battle-room-info", updateBattleRoomInfo);
 });
 </script>
 
@@ -185,14 +173,14 @@ onBeforeUnmount(() => {
     <view v-if="showProgress" class="battle-progress">
       <HeaderProgress />
     </view>
-    <!-- 对战房间：整个胶囊为分享按钮，点击任意区域均可触发分享 -->
+    <!-- 对战房间：整个胶囊为分享按钮，房号从 Store 读取 -->
     <button
-      v-if="currentPage === 'pages/battle-room' && battleRoomNumber"
+      v-if="currentPage === 'pages/battle-room' && game.roomNumber"
       open-type="share"
       hover-class="none"
       class="battle-room-number"
     >
-      <text class="battle-room-number__text">房号: {{ battleRoomNumber }}</text>
+      <text class="battle-room-number__text">房号: {{ game.roomNumber }}</text>
       <image src="../static/share2.png" mode="widthFix" class="battle-room-number__icon" />
     </button>
   </view>

src/components/ShootProgress.vue

@@ -139,7 +139,7 @@ async function onReceiveMessage(msg) {
     halfTime.value = false;
     audioManager.play("比赛开始");
   } else if (msg.type === MESSAGETYPESV2.BattleEnd) {
-    audioManager.play("比赛结束");
+    audioManager.play("比赛结束", false);
   } else if (msg.type === MESSAGETYPESV2.ShootResult) {
     let arrow = {};
     if (msg.details && Array.isArray(msg.details)) {

src/pages/battle-room.vue

@@ -47,6 +47,10 @@ const allReady = ref(false);
 const timer = ref(null);
 const goBattle = ref(false);
 
+/**
+ * 从服务端刷新当前房间数据，更新成员列表、准备状态等信息
+ * 仅在 roomNumber 有效且房间未开始时执行
+ */
 async function refreshRoomData() {
   if (!roomNumber.value) return;
   const result = await getRoomAPI(roomNumber.value);
@@ -109,9 +113,6 @@ async function refreshRoomData() {
   }
   if (timer.value) clearInterval(timer.value);
   // timer.value = setTimeout(refreshRoomData, 2000);
-
-  // 通知 Header 组件更新房号展示
-  uni.$emit("battle-room-info", { roomNumber: roomNumber.value });
 }
 
 const startGame = async () => {
@@ -248,19 +249,32 @@ onShareAppMessage(() => {
   };
 });
 
+/**
+ * onShow 生命周期：页面显示时刷新房间数据
+ * 注：uni-app 中 onShow 可能早于 onLoad 执行，此时 roomNumber 尚未赋值，
+ * refreshRoomData 会提前 return。
+ */
 onShow(() => {
   goBattle.value = false;
   refreshRoomData();
 });
 
+/**
+ * 页面加载时解析路由参数，初始化房间号
+ * - 存入本地 ref（供页面内部逻辑使用）
+ * - 同步到 Pinia Store（供 Header 组件展示房号胶囊）
+ */
 onLoad(async (options) => {
   if (options.roomNumber) {
     roomNumber.value = options.roomNumber;
-    // 立即通知 Header 显示房号，无需等待异步 API 返回
-    uni.$emit("battle-room-info", { roomNumber: options.roomNumber });
+    store.updateRoomNumber(options.roomNumber);
   }
 });
 
+/**
+ * 组件挂载后：保持屏幕常亮、注册 WebSocket 消息监听
+ * 房间号已通过 onLoad 同步到 Store，Header 从 Store 直接读取，无需额外通知
+ */
 onMounted(() => {
   uni.setKeepScreenOn({
     keepScreenOn: true,

src/pages/practise-one.vue

@@ -59,7 +59,7 @@ async function onReceiveMessage(msg) {
   if (msg.type === MESSAGETYPESV2.ShootResult) {
     scores.value = msg.details;
   } else if (msg.type === MESSAGETYPESV2.BattleEnd) {
-    setTimeout(onOver, 1500);
+    // setTimeout(onOver, 1500);
   }
 }
 
@@ -84,6 +84,12 @@ const onClickShare = debounce(async () => {
   await wxShare("shareCanvas");
 });
 
+function onAudioEnded(s) {
+  if (s.indexOf("比赛结束") >= 0) {
+    onOver()
+  }
+}
+
 onMounted(async () => {
   // audioManager.play("第一轮");
   uni.setKeepScreenOn({
@@ -91,6 +97,7 @@ onMounted(async () => {
   });
   uni.$on("socket-inbox", onReceiveMessage);
   uni.$on("share-image", onClickShare);
+  uni.$on("audioEnded", onAudioEnded);
   const result = await createPractiseAPI(total, 120, targetType.value);
   if (result) practiseId.value = result.id;
 });
@@ -101,6 +108,7 @@ onBeforeUnmount(() => {
   });
   uni.$off("socket-inbox", onReceiveMessage);
   uni.$off("share-image", onClickShare);
+  uni.$off("audioEnded", onAudioEnded);
   audioManager.stopAll();
   endPractiseAPI();
 });

src/store.js

@@ -79,6 +79,7 @@ export default defineStore("store", {
     game: {
       roomID: "",
       inBattle: false,
+      roomNumber: "", // 当前房间号，供 Header 展示房号胶囊
     },
   }),
 
@@ -135,6 +136,10 @@ export default defineStore("store", {
       this.game.roomID = roomID;
       this.game.inBattle = inBattle;
     },
+    /** 更新当前房间号，供 Header 组件展示房号胶囊 */
+    updateRoomNumber(number) {
+      this.game.roomNumber = number;
+    },
   },
 
   // 开启数据持久化