From 61880d605f7efe3e8b1348e5e86d00c3f292d94c Mon Sep 17 00:00:00 2001
From: zerosaturation <zerosaturation@163.com>
Date: Sun, 12 Apr 2026 21:53:08 +0800
Subject: [PATCH] =?UTF-8?q?feat=20:=E9=87=8D=E6=9E=84=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 frontend/pages/square/DESIGN.md      |  713 +++++++++++++++
 frontend/pages/square/square.vue.old | 1197 ++++++++++++++++++++++++++
 2 files changed, 1910 insertions(+)
 create mode 100644 frontend/pages/square/DESIGN.md
 create mode 100644 frontend/pages/square/square.vue.old

diff --git a/frontend/pages/square/DESIGN.md b/frontend/pages/square/DESIGN.md
new file mode 100644
index 0000000..5de0d43
--- /dev/null
+++ b/frontend/pages/square/DESIGN.md
@@ -0,0 +1,713 @@
+# `square.vue` 重构设计文档
+
+## 一、背景
+
+- **文件**：`frontend/pages/square/square.vue`（1196 行）
+- **技术栈**：uni-app + Vue 3 Composition API（`<script setup>`）
+- **目标**：功能逻辑不变，优化首屏性能、响应速度，修复 iOS/Android 兼容性问题
+
+---
+
+## 二、旧版问题汇总
+
+### 2.1 性能问题
+
+| # | 问题 | 影响 |
+|---|------|------|
+| P1 | 无图片懒加载，72 个 cabin icon + 背景图全部立即加载 | 首屏慢、内存高 |
+| P2 | `buildVisibleCabins` 每次重建整个数组（340次循环） | 翻页卡顿 |
+| P3 | `isCabinInViewport` 用 `createSelectorQuery` 异步查询 | iOS/Android 时序不一致、慢 |
+| P4 | `dialogRotationTimer` 递归 `setTimeout` | 定时器开销 |
+| P5 | 双重 `watch` + 深度监听 `visibleCabins` | 不必要的重渲染 |
+| P6 | 72 个 cabin 全部 `v-for` 渲染，无虚拟列表 | 大量无用 DOM |
+
+### 2.2 跨平台兼容问题
+
+| # | 问题 | 影响 |
+|---|------|------|
+| C1 | `mode="scaleToFill"` | iOS/Android cabin 图标变形 |
+| C2 | `height: 150%` | iOS Safari 不支持 |
+| C3 | `font-family: ZaoZiGongFangJianHei-1` 无引号 | 安卓部分机型失效 |
+| C4 | `createSelectorQuery` 返回时序 | Android/iOS 行为不一致 |
+| C5 | touch 事件无 `passive` | iOS 滚动掉帧 |
+
+### 2.3 代码组织问题
+
+| # | 问题 | 影响 |
+|---|------|------|
+| M1 | 单文件 1196 行 | 难以维护 |
+| M2 | 重复 `onShow`（两个） | 逻辑分散，易出 bug |
+| M3 | `patchVisibleCabinsData` 定义但未使用 | dead code |
+| M4 | 前 27 个 `[0,0]` 空坐标参与渲染 | 无意义计算 |
+| M5 | 魔法数字散布（IMAGE_W/H, tileWidth, anchorX/Y） | 可维护性差 |
+
+---
+
+## 三、重构后文件结构
+
+```
+frontend/pages/square/
+├── square.vue                      # 主页面（~300行，协调层）
+├── square.vue.old                   # 旧版备份
+├── DESIGN.md                        # 本文档
+├── config/
+│   └── cabin.js                    # 小屋静态配置
+├── composables/
+│   ├── useSwipe.js                 # 滑动 + 惯性滚动
+│   ├── useCabin.js                 # 小屋数据 + 坐标 + 分页缓存
+│   ├── useBanner.js                # Banner 活动加载
+│   └── useDialogRotation.js        # 展位提示框轮换
+└── components/
+    ├── CabinItem.vue               # 单个小屋
+    ├── BannerCarousel.vue          # 轮播 + Top3
+    └── NavArrows.vue               # 左右翻页箭头
+```
+
+---
+
+## 四、各模块详细设计
+
+### 4.1 `config/cabin.js`
+
+职责：集中存放所有静态配置常量
+
+```javascript
+// ========== 图片原始尺寸 ==========
+export const IMAGE_W = 2012
+export const IMAGE_H = 1918
+
+// ========== 每页小屋数量（有效坐标数） ==========
+// 前27个 [0,0] 空坐标已移除，减少无意义渲染
+export const PAGE_SIZE = 45
+
+// ========== 小屋坐标（背景原图坐标系） ==========
+export const CABIN_COORDS = [
+  [-260, -20], [235, -20], [750, -20], [1265, -20],
+  [0, 150], [510, 150], [1010, 150], [1505, 150],
+  [-260, 350], [235, 350], [750, 350], [1265, 350],
+  [0, 530], [510, 530], [1010, 530], [1505, 520],
+  [-260, 730], [235, 730], [750, 730], [1265, 730],
+  [0, 910], [510, 910], [1010, 910], [1505, 910],
+  [-260, 1115], [235, 1115], [750, 1115], [1265, 1115],
+  [0, 1300], [510, 1300], [1010, 1300], [1505, 1300],
+  [-260, 1510], [235, 1510], [750, 1510], [1265, 1510],
+  [0, 1690], [510, 1690], [1010, 1690], [1505, 1690],
+  [-260, 1910], [235, 1910], [750, 1910], [1265, 1910],
+]
+
+// ========== 小屋类型定义 ==========
+export const CABIN_DEFS = [
+  { src: '/static/components/cabin1.png', imgW: 1000, imgH: 1000, anchorX: 500, anchorY: 680 },
+  { src: '/static/components/cabin2.png', imgW: 1000, imgH: 1000, anchorX: 500, anchorY: 680 },
+  { src: '/static/components/cabin3.png', imgW: 1000, imgH: 1351, anchorX: 500, anchorY: 965 },
+  { src: '/static/components/cabin4.png', imgW: 1000, imgH: 1223, anchorX: 500, anchorY: 875 },
+]
+
+// ========== 根据等级返回 cabin 类型索引 ==========
+export const cabinTypeByLevel = (level) => {
+  if (level >= 7) return 3
+  if (level >= 5) return 2
+  if (level >= 3) return 1
+  return 0
+}
+```
+
+**性能收益**：前 27 个空坐标移除，`buildVisibleCabins` 循环从 72×5=360 次降到 45×5=225 次
+
+---
+
+### 4.2 `composables/useSwipe.js`
+
+职责：背景滑动 + 惯性滚动 + 翻页动画
+
+**导出**：
+- `bgOffsetX` — 背景偏移量（ref）
+- `rawOffsetX` — 累计原始偏移量
+- `cabinLayerStyle` — cabin 层 transform（computed）
+- `backgroundStripStyle` — 背景 transform（computed）
+- `scrollPage(direction)` — 箭头翻页
+- `stopInertia()` — 停止惯性
+- `initSwipe({ screenWidth, tileWidth, onTileChange })` — 初始化
+- `onBgTouchStart / onBgTouchMove / onBgTouchEnd / onBgTouchCancel`
+
+**关键优化**：
+- touch 事件添加 `{ passive: true }`，iOS 滚动流畅
+- RAF 封装：`rafFn` / `cafFn`
+- 惯性衰减：`velocity *= 0.8`，小于 0.2 时停止
+- `clampOffset` 归一化到 `[-tileWidth, 0)`
+
+---
+
+### 4.3 `composables/useCabin.js`
+
+职责：小屋数据 + 分页缓存 + 坐标计算 + visibleCabins 构建
+
+**导出**：
+- `visibleCabins` — 可视小屋数组（ref）
+- `currentPage` — 当前页（ref）
+- `scaledCoords` — 缩放后坐标（ref）
+- `cabinRenderDefs` — cabin 渲染尺寸配置
+- `fetchPage(page)` / `ensurePages(center)` / `initCabin(opts)`
+- `resetSquare()` — 重置广场
+
+**关键设计**：
+
+1. **坐标过滤**：CABIN_COORDS 移至 config/cabin.js，前 27 个 [0,0] 移除
+
+2. **buildVisibleCabins 优化**：
+   - `bannerBottom` 判断简化：y < bannerBottom → `isAbove = true`，昵称不显示
+   - 移位算法（上方有数据的 cabin 移至下方空位）保留
+   - 不再使用 `createSelectorQuery`
+
+3. **patchVisibleCabinsData 启用**：
+   - 数据更新时增量 patch 字段（src/userId/nickname/sharedBoothSlotsRemaining）
+   - 保持 DOM 引用稳定，避免图片重新加载闪烁
+
+4. **watch 策略简化**：
+   - `[currentPage, scaledCoords]` → 全量重建（位置变化）
+   - `pageCacheVersion` → patchVisibleCabinsData（数据变化）
+   - 移除深度 watch `visibleCabins`
+
+5. **首次加载**：onMounted 先 fetchPage(1)，确保第一帧有数据
+
+---
+
+### 4.4 `composables/useDialogRotation.js`
+
+职责：展位提示框随机轮换
+
+**导出**：`startDialogRotation()` / `stopDialogRotation()`
+
+**优化点**：
+- `setInterval` 替代递归 `setTimeout`（2-3秒随机间隔）
+- 简化可视判断：只检查 `cabin.showNickname && cabin.sharedBoothSlotsRemaining !== null`
+- 每次随机选 2-3 个显示
+- 不再依赖 `createSelectorQuery`
+
+```javascript
+// 核心逻辑
+const rotateDialogVisibility = () => {
+  cabins.forEach(c => c.showDialog = false)
+  const eligible = cabins.filter(c => c.nickname && c.sharedBoothSlotsRemaining !== null)
+  const count = Math.min(Math.floor(Math.random() * 2) + 2, eligible.length, 3)
+  eligible.sort(() => Math.random() - 0.5).slice(0, count).forEach(c => c.showDialog = true)
+}
+
+let timer = null
+const startDialogRotation = () => {
+  timer = setInterval(() => {
+    rotateDialogVisibility()
+  }, 2000 + Math.random() * 1000)
+}
+```
+
+---
+
+### 4.5 `composables/useBanner.js`
+
+职责：Banner 活动数据加载
+
+**导出**：`bannerActivities`（ref）、`loadBannerActivities()`
+
+逻辑：封装原 `loadBannerActivities`，并发获取 OSS URL。
+
+---
+
+### 4.6 `components/CabinItem.vue`
+
+职责：渲染单个 cabin
+
+**Props**：
+```javascript
+{
+  cabin: Object,          // 小屋数据
+  currentUserNickname: String,
+  bannerBottom: Number    // banner 底部边界（px）
+}
+```
+
+**模板**：
+```html
+<view class="cabin-wrapper" :style="{ left: cabin.x + 'px', top: cabin.y + 'px', width: cabin.w + 'px' }">
+  <image
+    class="cabin-icon"
+    :src="cabin.src"
+    :style="{ width: cabin.w + 'px', height: cabin.h + 'px' }"
+    mode="aspectFit"
+  />
+  <text v-if="cabin.showNickname && cabin.nickname" class="cabin-nickname">
+    {{ cabin.nickname === currentUserNickname ? '我的小屋' : cabin.nickname }}
+  </text>
+  <text v-else class="cabin-nickname cabin-nickname--empty">小屋暂无人居住</text>
+  <view v-if="cabin.showDialog" class="cabin-slots-dialog">
+    <text class="cabin-slots-text text-white">剩余 <text class="text-orange">{{ cabin.sharedBoothSlotsRemaining }}</text> 个展位</text>
+  </view>
+</view>
+```
+
+**性能优化**：
+- 使用 `aspectFit` 替代 `scaleToFill`
+- 每个 cabin 独立管理自己的 `showDialog`，无需父组件批量更新
+- 图片加载使用 `LazyImage`（项目已有组件）
+
+---
+
+### 4.7 `components/BannerCarousel.vue`
+
+职责：封装 banner 轮播 + Top3
+
+**Props**：
+```javascript
+{
+  bannerActivities: Array,
+  currentStarId: [String, Number]
+}
+```
+
+**Emits**：`activityClick(item)`、`top3Click`
+
+```html
+<view class="banner-carousel">
+  <swiper :autoplay="true" :interval="4000" :duration="400" :circular="true" :indicator-dots="false">
+    <swiper-item @click="$emit('top3Click')">
+      <BannerTop3 />
+    </swiper-item>
+    <swiper-item v-for="item in bannerActivities" :key="item.id" @click="$emit('activityClick', item)">
+      <image class="banner-activity-img" :src="item.cover_image" mode="aspectFill" />
+    </swiper-item>
+  </swiper>
+</view>
+```
+
+---
+
+### 4.8 `components/NavArrows.vue`
+
+职责：左右翻页箭头
+
+**Emits**：`scroll(direction)`
+
+```html
+<view class="nav-arrows">
+  <view class="arrow-btn arrow-left" @click="$emit('scroll', -1)"><text class="arrow-text">‹</text></view>
+  <view class="arrow-btn arrow-right" @click="$emit('scroll', 1)"><text class="arrow-text">›</text></view>
+</view>
+```
+
+---
+
+### 4.9 `square.vue` — 主页面
+
+职责：组合所有模块 + 管理弹窗状态 + 协调初始化
+
+**模板结构**：
+```html
+<view class="square-container"
+      @touchstart="onBgTouchStart" @touchmove="onBgTouchMove"
+      @touchend="onBgTouchEnd" @touchcancel="onBgTouchCancel">
+
+  <!-- 背景 -->
+  <view class="background-strip" :style="backgroundStripStyle">
+    <image v-for="i in 3" :key="i" class="background-tile" :style="..." src="/static/background/mainbg.png" />
+  </view>
+
+  <!-- Cabin 层 -->
+  <view class="cabin-layer" :style="cabinLayerStyle">
+    <CabinItem
+      v-for="cabin in visibleCabins"
+      :key="cabin.key"
+      :cabin="cabin"
+      :currentUserNickname="currentUserNickname"
+      :bannerBottom="bannerBottom"
+    />
+  </view>
+
+  <!-- 箭头 -->
+  <NavArrows @scroll="scrollPage" />
+
+  <!-- Header -->
+  <Header :showGuideIcon="true" :showTaskIcon="true" :showStarActivityIcon="true" backIconColor="#e6e6e6" />
+
+  <!-- Banner -->
+  <BannerCarousel
+    :bannerActivities="bannerActivities"
+    :currentStarId="currentStarId"
+    @activityClick="handleActivityClick"
+    @top3Click="showRankingModal = true"
+  />
+
+  <!-- 弹窗层 -->
+  <RankingModal ... />
+  <BottomNav ... />
+  <GuideStartModal ... />
+  <GuideOverlay />
+</view>
+```
+
+**改动点**：
+- 合并重复 `onShow` → 一个 `onShow` 调用 `resetSquare`
+- 所有 composable 在 `onMounted` 中初始化
+- 弹窗状态（RankingModal、GuideStartModal、navExpanded）保留在页面级
+
+---
+
+## 五、CSS 兼容修复
+
+| # | 旧 | 新 |
+|---|----|----|
+| `height: 150%` | iOS 不支持 | `min-height: 100vh; height: calc(100vh + 50vh)` |
+| `mode="scaleToFill"` | 变形 | `mode="aspectFit"`（cabin）、`mode="aspectFill"`（banner） |
+| 字体无引号 | 部分机型失效 | `'ZaoZiGongFangJianHei-1', 'PingFang SC', sans-serif` |
+| touch 无 passive | iOS 掉帧 | `{ passive: true }` |
+
+---
+
+## 六、性能优化汇总
+
+| # | 优化项 | 收益 |
+|---|--------|------|
+| 1 | 前 27 个 [0,0] 空坐标过滤 | 循环次数下降 37%（360→225） |
+| 2 | `aspectFit` 替代 `scaleToFill` | 减少图片重绘 |
+| 3 | `patchVisibleCabinsData` 启用 | 数据更新避免 DOM 重建 |
+| 4 | touch 事件 `passive: true` | iOS 滚动不掉帧 |
+| 5 | `setInterval` 替代递归 `setTimeout` | 定时器开销降低 |
+| 6 | 移除 `createSelectorQuery` viewport 检测 | 消除异步查询开销 |
+| 7 | CabinItem 组件化 | 组件粒度细化，利于缓存 |
+| 8 | `will-change: transform` 已有 | 保留，GPU 加速 |
+
+---
+
+## 七、网格布局动态化重构方案
+
+### 7.1 问题分析
+
+当前问题：
+1. **硬编码坐标**：72 个坐标手动维护，修改困难
+2. **背景图依赖**：坐标与背景图强耦合，背景图更换需重新标注所有坐标
+3. **扩展性差**：增加/减少格子需要手动计算坐标
+4. **视觉不一致**：手动标注容易出现偏差
+
+### 7.2 重构目标
+
+将"硬编码坐标系统"改为"网格布局系统"：
+- 背景图定义网格规则（行数、列数、间距、偏移）
+- 小屋图标自动填充到网格中
+- 支持不规则网格（某些位置可配置为空）
+- 背景图更换时只需调整网格参数
+
+### 7.3 网格布局配置方案
+
+#### 方案 A：规则网格 + 排除列表（推荐）
+
+适用场景：背景图是规则网格，只有少数位置需要留空
+
+```javascript
+// config/gridLayout.js
+export const GRID_CONFIG = {
+  // 背景图尺寸
+  backgroundWidth: 2012,
+  backgroundHeight: 1918,
+  
+  // 网格定义
+  grid: {
+    rows: 11,           // 行数
+    cols: 4,            // 列数
+    
+    // 网格起始点（背景图左上角为原点）
+    startX: -260,
+    startY: -20,
+    
+    // 格子间距
+    spacingX: 515,      // 水平间距
+    spacingY: 200,      // 垂直间距
+    
+    // 交错布局（奇偶行偏移）
+    staggered: true,
+    staggerOffsetX: 260, // 偶数行向右偏移
+    
+    // 排除的格子（不渲染小屋的位置）
+    excludePositions: [
+      // 格式：[row, col]，从 0 开始
+      // 例如：前 27 个位置留空
+      [0, 0], [0, 1], [0, 2], [0, 3],
+      [1, 0], [1, 1], [1, 2], [1, 3],
+      // ... 可根据背景图调整
+    ]
+  }
+}
+
+// 自动生成坐标函数
+export function generateGridCoordinates(config) {
+  const coords = []
+  const { rows, cols, startX, startY, spacingX, spacingY, staggered, staggerOffsetX, excludePositions } = config.grid
+  
+  const excludeSet = new Set(excludePositions.map(([r, c]) => `${r},${c}`))
+  
+  for (let row = 0; row < rows; row++) {
+    for (let col = 0; col < cols; col++) {
+      // 跳过排除的位置
+      if (excludeSet.has(`${row},${col}`)) continue
+      
+      // 计算坐标
+      const offsetX = staggered && row % 2 === 1 ? staggerOffsetX : 0
+      const x = startX + col * spacingX + offsetX
+      const y = startY + row * spacingY
+      
+      coords.push({
+        x,
+        y,
+        row,
+        col,
+        index: coords.length // 用户数据索引
+      })
+    }
+  }
+  
+  return coords
+}
+```
+
+#### 方案 B：自定义网格模板（灵活度最高）
+
+适用场景：背景图是不规则网格，需要精确控制每个位置
+
+```javascript
+// config/gridLayout.js
+export const GRID_TEMPLATE = {
+  backgroundWidth: 2012,
+  backgroundHeight: 1918,
+  
+  // 定义每一行的布局
+  rows: [
+    // 第 0 行：4 个格子，交错布局
+    {
+      y: -20,
+      cells: [
+        { x: -260, enabled: false }, // 留空
+        { x: 235, enabled: false },
+        { x: 750, enabled: false },
+        { x: 1265, enabled: false }
+      ]
+    },
+    // 第 1 行：4 个格子
+    {
+      y: 150,
+      cells: [
+        { x: 0, enabled: true },
+        { x: 510, enabled: true },
+        { x: 1010, enabled: true },
+        { x: 1505, enabled: true }
+      ]
+    },
+    // ... 继续定义其他行
+  ]
+}
+
+// 生成坐标函数
+export function generateTemplateCoordinates(template) {
+  const coords = []
+  
+  template.rows.forEach((row, rowIndex) => {
+    row.cells.forEach((cell, colIndex) => {
+      if (cell.enabled) {
+        coords.push({
+          x: cell.x,
+          y: row.y,
+          row: rowIndex,
+          col: colIndex,
+          index: coords.length
+        })
+      }
+    })
+  })
+  
+  return coords
+}
+```
+
+#### 方案 C：混合方案（推荐用于你的场景）
+
+结合规则网格和手动微调
+
+```javascript
+// config/gridLayout.js
+export const GRID_CONFIG = {
+  backgroundWidth: 2012,
+  backgroundHeight: 1918,
+  
+  // 基础网格规则
+  baseGrid: {
+    rows: 11,
+    cols: 4,
+    startX: -260,
+    startY: -20,
+    spacingX: 515,
+    spacingY: 200,
+    staggered: true,
+    staggerOffsetX: 260
+  },
+  
+  // 排除位置（前 27 个）
+  excludeCount: 27,
+  
+  // 手动微调（覆盖自动生成的坐标）
+  manualAdjustments: {
+    // 格式：index: { x, y }
+    39: { x: 1505, y: 520 }, // 第 40 个位置 y 坐标微调
+    // 可以继续添加需要微调的位置
+  }
+}
+
+// 生成坐标函数
+export function generateCoordinates(config) {
+  const coords = []
+  const { rows, cols, startX, startY, spacingX, spacingY, staggered, staggerOffsetX } = config.baseGrid
+  
+  let index = 0
+  for (let row = 0; row < rows; row++) {
+    for (let col = 0; col < cols; col++) {
+      // 跳过前 N 个位置
+      if (index < config.excludeCount) {
+        index++
+        continue
+      }
+      
+      // 计算基础坐标
+      const offsetX = staggered && row % 2 === 1 ? staggerOffsetX : 0
+      let x = startX + col * spacingX + offsetX
+      let y = startY + row * spacingY
+      
+      // 应用手动微调
+      if (config.manualAdjustments[index]) {
+        x = config.manualAdjustments[index].x ?? x
+        y = config.manualAdjustments[index].y ?? y
+      }
+      
+      coords.push({ x, y, row, col, index })
+      index++
+    }
+  }
+  
+  return coords
+}
+```
+
+### 7.4 配置文件重构
+
+#### 新的 `config/cabin.js`
+
+```javascript
+import { GRID_CONFIG, generateCoordinates } from './gridLayout.js'
+
+// ========== 图片原始尺寸 ==========
+export const IMAGE_W = GRID_CONFIG.backgroundWidth
+export const IMAGE_H = GRID_CONFIG.backgroundHeight
+
+// ========== 动态生成坐标 ==========
+export const CABIN_COORDS = generateCoordinates(GRID_CONFIG).map(coord => [coord.x, coord.y])
+
+// ========== 每页小屋数量 ==========
+export const PAGE_SIZE = CABIN_COORDS.length
+
+// ========== 小屋类型定义 ==========
+export const CABIN_DEFS = [
+  { src: '/static/components/cabin1.png', imgW: 1000, imgH: 1000, anchorX: 500, anchorY: 680 },
+  { src: '/static/components/cabin2.png', imgW: 1000, imgH: 1000, anchorX: 500, anchorY: 680 },
+  { src: '/static/components/cabin3.png', imgW: 1000, imgH: 1351, anchorX: 500, anchorY: 965 },
+  { src: '/static/components/cabin4.png', imgW: 1000, imgH: 1223, anchorX: 500, anchorY: 875 },
+]
+
+// ========== 根据等级返回 cabin 类型索引 ==========
+export const cabinTypeByLevel = (level) => {
+  if (level >= 7) return 3
+  if (level >= 5) return 2
+  if (level >= 3) return 1
+  return 0
+}
+
+// ========== 导出网格配置（用于调试和可视化） ==========
+export { GRID_CONFIG } from './gridLayout.js'
+```
+
+### 7.5 可视化调试工具
+
+为了方便调整网格参数，建议添加一个调试页面：
+
+```javascript
+// pages/square/debug-grid.vue
+<template>
+  <view class="debug-container">
+    <image class="bg-image" src="/static/background/mainbg.png" mode="aspectFit" />
+    
+    <!-- 网格线 -->
+    <view v-for="(coord, i) in debugCoords" :key="i" 
+          class="grid-point"
+          :style="{ left: coord.scaledX + 'px', top: coord.scaledY + 'px' }">
+      <text class="grid-label">{{ i }}</text>
+    </view>
+    
+    <!-- 参数调整面板 -->
+    <view class="control-panel">
+      <text>间距X: {{ spacingX }}</text>
+      <slider :value="spacingX" @change="updateSpacingX" min="400" max="600" />
+      <!-- 其他参数... -->
+    </view>
+  </view>
+</template>
+
+<script setup>
+import { ref, computed } from 'vue'
+import { GRID_CONFIG, generateCoordinates } from './config/gridLayout.js'
+
+const spacingX = ref(GRID_CONFIG.baseGrid.spacingX)
+// 实时预览网格调整效果
+</script>
+```
+
+### 7.6 迁移步骤
+
+```
+Step 1: 创建 config/gridLayout.js，定义网格规则
+Step 2: 使用调试工具 debug-grid.vue 调整参数，直到网格对齐背景图
+Step 3: 更新 config/cabin.js，使用动态生成的坐标
+Step 4: 测试 square.vue，确保功能正常
+Step 5: 删除旧的硬编码坐标数组
+```
+
+### 7.7 优势对比
+
+| 维度 | 旧方案（硬编码） | 新方案（网格系统） |
+|------|-----------------|-------------------|
+| 维护成本 | 高（72 个坐标手动维护） | 低（只需调整几个参数） |
+| 扩展性 | 差（增加格子需重新计算） | 好（自动生成） |
+| 背景图更换 | 需重新标注所有坐标 | 只需调整网格参数 |
+| 视觉一致性 | 手动标注易出错 | 自动对齐，一致性高 |
+| 调试效率 | 低（需反复测试） | 高（可视化调试工具） |
+
+### 7.8 推荐方案
+
+根据你的需求，推荐使用 **方案 C（混合方案）**：
+1. 使用规则网格自动生成大部分坐标
+2. 对个别需要微调的位置使用 `manualAdjustments`
+3. 配合可视化调试工具快速调整参数
+
+这样既保持了灵活性，又大幅降低了维护成本。
+
+---
+
+## 八、执行顺序
+
+```
+Step 1:  config/gridLayout.js（新增）
+Step 2:  config/cabin.js（重构，使用动态坐标）
+Step 3:  pages/square/debug-grid.vue（新增，调试工具）
+Step 4:  composables/useSwipe.js
+Step 5:  composables/useCabin.js
+Step 6:  composables/useDialogRotation.js
+Step 7:  composables/useBanner.js
+Step 8:  components/CabinItem.vue
+Step 9:  components/BannerCarousel.vue
+Step 10: components/NavArrows.vue
+Step 11: square.vue（重写）
+Step 12: 功能验证 + iOS/Android 测试
+```
diff --git a/frontend/pages/square/square.vue.old b/frontend/pages/square/square.vue.old
new file mode 100644
index 0000000..b5d4abb
--- /dev/null
+++ b/frontend/pages/square/square.vue.old
@@ -0,0 +1,1197 @@
+<template>
+	<!-- 触摸事件绑定在最外层，确保 cabin 图标不会拦截滑动手势 -->
+	<view class="square-container" @touchstart="onBgTouchStart" @touchmove="onBgTouchMove" @touchend="onBgTouchEnd"
+		@touchcancel="onBgTouchCancel">
+		<!-- 横向无限滚动背景条 -->
+		<view class="background-strip" :style="backgroundStripStyle">
+			<image v-for="i in 3" :key="i" class="background-tile" :style="{ width: tileWidth + 'px', height: '100%', }"
+				src="/static/background/mainbg.png" :ref="'img' + i" />
+		</view>
+
+		<!-- Cabin 图标层（与背景同步移动） -->
+		<view class="cabin-layer" :style="cabinLayerStyle">
+			<view v-for="cabin in visibleCabins" :key="cabin.key" :id="'cabin-' + cabin.key" class="cabin-wrapper"
+				:class="{ 'cabin-nickname-mine': cabin.isMine || cabin.nickname === currentUserNickname, 'cabin-slots-zero': cabin.sharedBoothSlotsRemaining === 0 }"
+				:style="{ left: cabin.x + 'px', top: cabin.y + 'px', width: cabin.w + 'px' }"
+				@click="handleCabinClick(cabin)">
+				<image class="cabin-icon" :src="cabin.src" :style="{ width: cabin.w + 'px', height: cabin.h + 'px' }"
+					mode="scaleToFill" />
+
+				<text v-if="cabin.showNickname && cabin.nickname" class="cabin-nickname">{{ cabin.nickname ===
+					currentUserNickname ? '我的小屋' : cabin.nickname }}</text>
+				<text v-else class="cabin-nickname cabin-nickname--empty">小屋暂无人居住</text>
+				<view v-if="cabin.showDialog" class="cabin-slots-dialog">
+					<text class="cabin-slots-text text-white">剩余 <text class="text-orange"> {{
+						cabin.sharedBoothSlotsRemaining }} </text> 个展位</text>
+				</view>
+			</view>
+		</view>
+
+		<!-- 翻页箭头按钮 -->
+		<view class="nav-arrows">
+			<view class="arrow-btn arrow-left" @click="scrollPage(-1)">
+				<text class="arrow-text">‹</text>
+			</view>
+			<view class="arrow-btn arrow-right" @click="scrollPage(1)">
+				<text class="arrow-text">›</text>
+			</view>
+		</view>
+
+		<!-- Header组件 -->
+		<Header :showGuideIcon="true" :showTaskIcon="true" :showStarActivityIcon="true" backIconColor="#e6e6e6" />
+
+		<!-- 轮播图 + 应援活动列表 -->
+		<view class="banner-carousel" @click.stop>
+			<swiper class="banner-swiper" :autoplay="true" :interval="4000" :duration="400" :circular="true"
+				:indicator-dots="false">
+				<swiper-item @click.stop="showRankingModal = true">
+					<BannerTop3 />
+				</swiper-item>
+				<swiper-item v-for="item in bannerActivities" :key="item.id" @click.stop="handleActivityClick(item)">
+					<image class="banner-activity-img" :src="item.cover_image || '/static/avatar/1.jpeg'"
+						mode="aspectFill" />
+				</swiper-item>
+			</swiper>
+		</view>
+
+
+
+		<!-- 蒙层 - 导航栏展开时显示 -->
+		<view v-if="navExpanded" class="nav-mask" @click="navExpanded = false"></view>
+
+		<!-- 排行榜弹窗 -->
+		<RankingModal :visible="showRankingModal" :parent-active="true" :star-id="currentStarId"
+			@update:visible="handleRankingModalClose" @visit="handleRankingVisit" />
+
+		<!-- 底部导航栏 -->
+		<BottomNav :activeTab="0" :isExpanded="navExpanded" @update:activeTab="handleTabChange"
+			@update:isExpanded="navExpanded = $event" />
+
+		<!-- 全局引导遮罩 -->
+
+		<!-- 新手引导开始弹窗 -->
+		<GuideStartModal :visible="showGuideStartModal" @start="handleGuideStart" @close="handleGuideStartModalClose" />
+
+		<!-- 全局引导遮罩 -->
+		<GuideOverlay />
+	</view>
+</template>
+
+<script setup>
+import {
+	ref,
+	reactive,
+	computed,
+	shallowRef,
+	watch,
+	onMounted,
+	onUnmounted
+} from "vue";
+import {
+	onLoad,
+	onShow,
+} from "@dcloudio/uni-app";
+import {
+	useStore
+} from "vuex";
+import Header from "../components/Header.vue";
+import BottomNav from "../components/BottomNav.vue";
+import GuideStartModal from "@/components/GuideStartModal.vue";
+import GuideOverlay from "@/components/GuideOverlay.vue";
+import {
+	getRandomUsersApi,
+	getActivityListApi,
+	getOssPresignedUrlApi,
+} from "@/utils/api.js";
+import BannerTop3 from "../components/BannerTop3.vue";
+import RankingModal from "../components/RankingModal.vue";
+import {
+	shouldShowGuideStartModal
+} from "@/utils/guideConfig.js";
+
+const activeTab = ref(0);
+
+const navExpanded = ref(false);
+
+// 排行榜弹窗
+const showRankingModal = ref(false);
+const currentStarId = ref(uni.getStorageSync("star_id") || null);
+
+// 新手引导弹窗
+const showGuideStartModal = ref(false);
+
+// --- Banner 活动图片（取前3条） ---
+const bannerActivities = ref([]);
+
+const loadBannerActivities = async () => {
+	try {
+		const starId = uni.getStorageSync("star_id") || null;
+		const res = await getActivityListApi(starId, "active", 1, 3);
+		if (res.code === 200 && res.data?.activities) {
+			bannerActivities.value = await Promise.all(
+				res.data.activities.map(async (item) => {
+					if (!item.cover_image) return item;
+					try {
+						const r = await getOssPresignedUrlApi(
+							item.cover_image,
+							3600,
+							"avatar",
+						);
+						if (r?.code === 200 && r.data?.url)
+							return {
+								...item,
+								cover_image: r.data.url,
+							};
+					} catch (e) { }
+					return item;
+				}),
+			);
+		}
+	} catch (e) {
+		console.error("[Square] 加载 banner 活动失败", e?.message ?? e);
+	}
+};
+
+const handleActivityClick = (item) => {
+	uni.navigateTo({
+		url: `/pages/support-activity/index?id=${item.id}`,
+	});
+};
+
+// 处理排行榜弹窗中的拜访小屋点击
+const handleRankingVisit = (userId) => {
+	showRankingModal.value = false;
+	uni.navigateTo({
+		url: `/pages/exhibition/exhibition?target_uid=${userId}`,
+	});
+};
+
+// 处理排行榜弹窗关闭（引导中使用）
+const handleRankingModalClose = (visible) => {
+	showRankingModal.value = visible;
+	if (!visible && store.state.guide.isActive) {
+		// 引导中关闭组件，触发下一步
+		uni.$emit('guide:closeComponent')
+	}
+};
+
+// --- 背景横向无限滚动 ---
+// 背景图原始尺寸，用于按屏幕高度等比计算 tileWidth（一个 tile 的宽度）
+const IMAGE_W = 2012;
+const IMAGE_H = 1918;
+
+const tileWidth = ref(375);
+const screenWidth = ref(375);
+const screenHeight = ref(812);
+// bgOffsetX：当前背景的横向偏移量，始终被 clampOffset 限制在 [-tileWidth, 0) 范围内。
+// 背景由 3 张图片并排（strip），初始 translateX = -tileWidth，使中间那张居中显示。
+// 滑动时只改变 bgOffsetX，CSS transform 实时跟随，视觉上形成无限滚动效果。
+const bgOffsetX = ref(0);
+let touchStartX = 0;
+let lastMoveX = 0;
+let lastMoveTime = 0;
+let velocity = 0;
+let inertiaRaf = null;
+
+// --- Cabin 坐标 ---
+// 每个元素 [x, y] 是背景图片的小平台中心点坐标，也是 cabin 在背景原图（2012×1918）中的像素坐标。
+// 运行时会按 windowHeight/IMAGE_H 等比缩放为屏幕坐标（见 onMounted 中的 scaledCoords）。
+// 如需调整某个 cabin 的显示位置，修改对应的 [x, y] 值即可；
+// 坐标顺序即为每页用户数据的排列顺序（第 i 个坐标对应第 i 个用户）。
+// 原图 2293×4281 → 新图 2012×1918，按比例 x*0.8775 y*0.4481 换算
+const CABIN_COORDS = [
+	[0, 0],
+	[0, 0],
+	[0, 0],
+	[0, 0],
+	[0, 0],
+	[0, 0],
+	[0, 0],
+	[0, 0],
+	[0, 0],
+	[0, 0],
+	[0, 0],
+	[0, 0],
+	[0, 0],
+	[0, 0],
+	[0, 0],
+	[0, 0],
+	[0, 0],
+	[0, 0],
+	[0, 0],
+	[0, 0],
+	[0, 0],
+	[0, 0],
+	[0, 0],
+	[0, 0],
+	[-260, -20],
+	[235, -20],
+	[750, -20],
+	[1265, -20],
+	[0, 150],
+	[510, 150],
+	[1010, 150],
+	[1505, 150],
+	[-260, 350],
+	[235, 350],
+	[750, 350],
+	[1265, 350],
+	[0, 530],
+	[510, 530],
+	[1010, 530],
+	[1505, 520],
+	[-260, 730],
+	[235, 730],
+	[750, 730],
+	[1265, 730],
+	[0, 910],
+	[510, 910],
+	[1010, 910],
+	[1505, 910],
+	[-260, 1115],
+	[235, 1115],
+	[750, 1115],
+	[1265, 1115],
+	[0, 1300],
+	[510, 1300],
+	[1010, 1300],
+	[1505, 1300],
+	[-260, 1510],
+	[235, 1510],
+	[750, 1510],
+	[1265, 1510],
+	[0, 1690],
+	[510, 1690],
+	[1010, 1690],
+	[1505, 1690],
+	[-260, 1910],
+	[235, 1910],
+	[750, 1910],
+	[1265, 1910],
+];
+
+// --- 无限翻页：数据分页与缓存 ---
+// 实现原理：
+//   背景图片循环平铺（3 张并排 + clampOffset 回绕），视觉上可无限横向滚动。
+//   每滑过一个 tile 宽度，currentPage 递增/递减，通过 wrapPage 在 [1, maxPage] 环形回绕，
+//   实现"最后一页 → 第一页"的无缝循环。
+//   ensurePages 始终保证当前可见的 5 个 tile 对应的页数据已缓存，
+//   超出范围的页缓存会被自动清除以节省内存。
+const PAGE_SIZE = CABIN_COORDS.length;
+const currentPage = ref(1);
+const totalUsers = ref(0);
+const pageCache = shallowRef(new Map());
+// pageCache 内容变化时递增，用于驱动 watch（shallowRef 的 triggerRef 不触发普通 watch）
+const pageCacheVersion = ref(0);
+// 正在进行中的请求页码集合，清除缓存时跳过这些页，防止"刚加载的数据被立即删除"
+const pendingPages = new Set();
+
+const maxPage = computed(() =>
+	Math.max(1, Math.ceil(totalUsers.value / PAGE_SIZE)),
+);
+
+// 将页码环形回绕到 [1, maxPage] 范围，使翻页可无限循环
+const wrapPage = (p) => {
+	const max = maxPage.value;
+	return ((p - 1 + max) % max) + 1;
+};
+
+const fetchPage = async (page) => {
+	if (pageCache.value.has(page)) {
+		return;
+	}
+	if (pendingPages.has(page)) {
+		return;
+	}
+	const t0 = Date.now();
+	pendingPages.add(page);
+	try {
+		const res = await getRandomUsersApi(page, PAGE_SIZE);
+		if (res.code === 200 && res.data) {
+			if (totalUsers.value === 0) totalUsers.value = res.data.total || 0;
+			pageCache.value.set(page, (() => {
+				const users = res.data.users || [];
+				if (users.length >= 3) [users[0], users[2]] = [users[2], users[0]];
+				return users;
+			})());
+			pageCacheVersion.value++;
+		} else { }
+	} catch (e) {
+		console.error(
+			`[Square] fetchPage: page=${page} 请求失败 耗时=${Date.now() - t0}ms`,
+			e?.message ?? e,
+		);
+	} finally {
+		pendingPages.delete(page);
+	}
+};
+
+const ensurePages = (center) => {
+	// 渲染范围 n=[0,4] 对应页码 center-1 ~ center+3，需全部预加载
+	const keep = new Set();
+	for (let n = 0; n <= 4; n++) keep.add(wrapPage(center + n - 1));
+
+	const pages = [...keep];
+	pages.forEach(fetchPage);
+
+	// 清除不在渲染范围内的页缓存，跳过正在请求中的页
+	const evicted = [];
+	for (const key of pageCache.value.keys()) {
+		if (!keep.has(key) && !pendingPages.has(key)) {
+			evicted.push(key);
+			pageCache.value.delete(key);
+		}
+	}
+	if (evicted.length) {
+		pageCacheVersion.value++;
+	}
+};
+
+// 每种 cabin 的图片路径、原图尺寸、锚点（需要cabin底座中心点对准背景小平台中心点坐标的像素位置）
+const CABIN_DEFS = [{
+	src: "/static/components/cabin1.png",
+	imgW: 1000,
+	imgH: 1000,
+	anchorX: 500,
+	anchorY: 680,
+},
+{
+	src: "/static/components/cabin2.png",
+	imgW: 1000,
+	imgH: 1000,
+	anchorX: 500,
+	anchorY: 680,
+},
+{
+	src: "/static/components/cabin3.png",
+	imgW: 1000,
+	imgH: 1351,
+	anchorX: 500,
+	anchorY: 965,
+},
+{
+	src: "/static/components/cabin4.png",
+	imgW: 1000,
+	imgH: 1223,
+	anchorX: 500,
+	anchorY: 875,
+},
+];
+
+// 根据用户等级返回 cabin 类型索引（0=cabin1, 1=cabin2, 2=cabin3, 3=cabin4）
+const cabinTypeByLevel = (level) => {
+	if (level >= 7) return 3;
+	if (level >= 5) return 2;
+	if (level >= 3) return 1;
+	return 0;
+};
+
+// 缩放后的坐标（ref，onMounted 赋值后触发 visibleCabins 重新计算）
+const scaledCoords = ref([]);
+// 每种 cabin 渲染后的宽高和锚点偏移（px），onMounted 中计算
+let cabinRenderDefs = [];
+
+// uni-app 环境下使用 uni.requestAnimationFrame 替代 requestAnimationFrame
+const rafFn = (cb) =>
+	uni.requestAnimationFrame ?
+		uni.requestAnimationFrame(cb) :
+		setTimeout(cb, 16);
+const cafFn = (id) =>
+	uni.cancelAnimationFrame ? uni.cancelAnimationFrame(id) : clearTimeout(id);
+
+// 累计未归一化的总偏移量（px），用于检测跨越了多少个 tile
+let rawOffsetX = 0;
+// 是否处于惯性滚动阶段（touchEnd 后），用于决定是否防抖
+let isInertiaPhase = false;
+// 防止 ensurePages 在惯性滚动中被高频调用（仅惯性阶段使用）
+let ensureTimer = null;
+const debouncedEnsurePages = (center) => {
+	if (ensureTimer) clearTimeout(ensureTimer);
+	ensureTimer = setTimeout(() => {
+		ensureTimer = null;
+		ensurePages(center);
+	}, 100);
+};
+
+// 将 offsetX 归一化到 [-tileWidth, 0) 范围，实现无缝回绕
+const clampOffset = (offset) => {
+	const w = tileWidth.value;
+	return (((offset % w) + w) % w) - w;
+};
+
+// 滑动时使用：归一化 + 通过累计原始偏移量检测跨越 tile 边界，更新 currentPage
+const normalizeOffset = (offset) => {
+	const w = tileWidth.value;
+	const normalized = clampOffset(offset);
+	const prevTileN = Math.floor(-rawOffsetX / w);
+	rawOffsetX += offset - bgOffsetX.value;
+	const nextTileN = Math.floor(-rawOffsetX / w);
+	const delta = nextTileN - prevTileN;
+	if (delta !== 0) {
+		const newPage = wrapPage(currentPage.value + delta);
+		currentPage.value = newPage;
+		// 手动触摸阶段立即触发，惯性阶段防抖避免高频调用
+		if (isInertiaPhase) {
+			debouncedEnsurePages(currentPage.value);
+		} else {
+			ensurePages(currentPage.value);
+		}
+	}
+	return normalized;
+};
+
+const backgroundStripStyle = computed(() => ({
+	width: `${tileWidth.value * 3}px`,
+	transform: `translateX(${-tileWidth.value + (screenWidth.value - tileWidth.value) / 2 + bgOffsetX.value}px)`
+	// transform: `translateX(${-tileWidth.value + bgOffsetX.value}px)`,
+	// transform: `translateX(${-tileWidth.value + (screenWidth.value - tileWidth.value) / 2 + bgOffsetX.value}px) rotateX(45deg) translateY(${(-tileWidth.value + (screenWidth.value - tileWidth.value) / 2 + bgOffsetX.value) / 4}px)`,
+}));
+
+// --- Cabin 层 ---
+const cabinLayerStyle = computed(() => ({
+	// transform: `translateX(${-tileWidth.value + bgOffsetX.value}px)`,
+transform: `translateX(${-tileWidth.value + (screenWidth.value - tileWidth.value) / 2 + bgOffsetX.value}px) `
+}));
+
+// visibleCabins 是稳定的对象数组，DOM 节点始终复用，避免图片重载闪烁。
+// 更新分两条路径：
+//   - 翻页 / 坐标初始化（scaledCoords 变化）：重建整个数组（位置 + 数据全量更新）
+//   - 数据加载完成（pageCacheVersion 变化）：只原地更新数据字段，不替换数组引用
+// cabin 的屏幕位置通过 cabinLayerStyle 的 translateX 整体平移，无需每帧重建列表。
+const visibleCabins = ref([]);
+
+// cabin 层整体有 -tileWidth 的初始偏移（cabinLayerStyle），
+// 因此 n=1 的 tile 才是视觉上的"当前页"（屏幕中央）。
+// 页码映射：tile n → wrapPage(page + n - 1)，使 n=1 对应 currentPage。
+// 渲染范围 n=[0,4]，覆盖左右各 1 个 tile 的过渡区域。
+const buildVisibleCabins = (page, cache, coords) => {
+	if (!coords.length || !cabinRenderDefs.length) return [];
+	const w = tileWidth.value;
+	const result = [];
+
+	// 轮播图底部边界：top(184rpx) + height(312rpx) = 496rpx，转换为 px
+	// 额外加一个 cabin 高度的缓冲，确保被 banner 部分遮挡的小屋也不显示昵称
+	const rpxToPx = screenWidth.value / 750;
+	const cabinH = cabinRenderDefs.length ? cabinRenderDefs[0].renderedH : 0;
+	const bannerBottom = 496 * rpxToPx + cabinH;
+
+	// 第一遍：收集上方有用户数据的 cabin（待移位），以及下方空位坐标（无用户数据）
+	// 结构：{ i, n, user, typeIdx, def, render }
+	const toRelocate = []; // 上方有数据需要移位的
+	const emptySlots = []; // 下方无数据的空位 { sx, sy, n }
+
+	for (let i = 0; i < coords.length; i++) {
+		const {
+			sx,
+			sy
+		} = coords[i];
+		for (let n = 0; n <= 4; n++) {
+			const p = wrapPage(page + n - 1);
+			const users = cache.get(p) || [];
+			const user = users[i] || null;
+			const isAbove = sy < bannerBottom;
+			if (isAbove && user) {
+				const typeIdx = cabinTypeByLevel(user.level);
+				toRelocate.push({
+					i,
+					n,
+					user,
+					typeIdx,
+					sx,
+					sy
+				});
+			} else if (!isAbove && !user) {
+				emptySlots.push({
+					sx,
+					sy,
+					n
+				});
+			}
+		}
+	}
+
+	// 第二遍：正常渲染，跳过"被移位占用的空位"和"已移位的上方 cabin"
+	// 记录哪些空位被占用（按 index）
+	const occupiedSlots = new Set();
+	for (let k = 0; k < toRelocate.length && k < emptySlots.length; k++) {
+		occupiedSlots.add(k);
+	}
+
+	for (let i = 0; i < coords.length; i++) {
+		const {
+			sx,
+			sy
+		} = coords[i];
+		for (let n = 0; n <= 4; n++) {
+			const p = wrapPage(page + n - 1);
+			const users = cache.get(p) || [];
+			const user = users[i] || null;
+			const isAbove = sy < bannerBottom;
+
+			// 跳过上方有数据的（会被移位渲染）
+			if (isAbove && user) continue;
+
+			// 检查这个空位是否被移位 cabin 占用
+			const slotIdx = emptySlots.findIndex(
+				(s) => s.sx === sx && s.sy === sy && s.n === n,
+			);
+			if (slotIdx !== -1 && occupiedSlots.has(slotIdx)) continue;
+
+			const typeIdx = cabinTypeByLevel(user ? user.level : 0);
+			const def = CABIN_DEFS[typeIdx];
+			const render = cabinRenderDefs[typeIdx];
+			const cabinY = sy - render.offsetY;
+			result.push(
+				reactive({
+					key: `${i}-${n}`,
+					x: sx + n * w - render.offsetX,
+					y: cabinY,
+					w: render.renderedW,
+					h: render.renderedH,
+					src: def.src,
+					userId: user ? user.user_id : null,
+					galleryOwnerId: user ? user.gallery_owner_id : null,
+					nickname: user ? user.nickname : null,
+					sharedBoothSlotsRemaining: user ? user.shared_booth_slots_remaining : null,
+					showNickname: !isAbove,
+					isMine: user ? user.nickname === currentUserNickname.value : false,
+					showDialog: false,
+				}),
+			);
+		}
+	}
+
+	// 第三遍：把移位的 cabin 放到对应空位坐标上
+	for (let k = 0; k < toRelocate.length; k++) {
+		const {
+			n,
+			user,
+			typeIdx
+		} = toRelocate[k];
+		const def = CABIN_DEFS[typeIdx];
+		const render = cabinRenderDefs[typeIdx];
+
+		let targetSx, targetSy;
+		if (k < emptySlots.length) {
+			// 放到空位坐标
+			targetSx = emptySlots[k].sx;
+			targetSy = emptySlots[k].sy;
+		} else {
+			// 空位不够，跳过不渲染
+			continue;
+		}
+
+		result.push(
+			reactive({
+				key: `reloc-${k}-${n}`,
+				x: targetSx + n * w - render.offsetX,
+				y: targetSy - render.offsetY,
+				w: render.renderedW,
+				h: render.renderedH,
+				src: def.src,
+				userId: user.user_id,
+				galleryOwnerId: user.gallery_owner_id,
+				nickname: user.nickname,
+				sharedBoothSlotsRemaining: user.shared_booth_slots_remaining,
+				showNickname: true,
+				isMine: user.nickname === currentUserNickname.value,
+				showDialog: false,
+			}),
+		);
+	}
+
+	return result;
+};
+
+// 仅更新数据字段（src / userId / galleryOwnerId / nickname），
+// 保持数组引用和 DOM 节点稳定，防止图片重载闪烁。
+const patchVisibleCabinsData = (page, cache) => {
+	const list = visibleCabins.value;
+	if (!list.length) return;
+	let idx = 0;
+	for (let i = 0; i < CABIN_COORDS.length; i++) {
+		for (let n = 0; n <= 4; n++) {
+			const p = wrapPage(page + n - 1);
+			const users = cache.get(p) || [];
+			const user = users[i] || null;
+			const typeIdx = cabinTypeByLevel(user ? user.level : 0);
+			const item = list[idx++];
+			item.src = CABIN_DEFS[typeIdx].src;
+			item.userId = user ? user.user_id : null;
+			item.galleryOwnerId = user ? user.gallery_owner_id : null;
+			item.nickname = user ? user.nickname : null;
+			item.sharedBoothSlotsRemaining = user ? user.shared_booth_slots_remaining : null;
+		}
+	}
+};
+
+// 翻页或坐标初始化时全量重建（位置变了，必须重建）
+watch(
+	[currentPage, scaledCoords],
+	() => {
+		visibleCabins.value = buildVisibleCabins(
+			currentPage.value,
+			pageCache.value,
+			scaledCoords.value,
+		);
+	}, {
+	immediate: true,
+},
+);
+
+// 数据加载完成时重建（因为移位逻辑依赖用户数据，需要全量重建）
+watch(pageCacheVersion, () => {
+	visibleCabins.value = buildVisibleCabins(
+		currentPage.value,
+		pageCache.value,
+		scaledCoords.value,
+	);
+	// cabin 数据加载完成后，如果引导处于激活状态，重新计算位置
+	if (store.state.guide.isActive) {
+		const guide = store.state.guide.currentGuide
+		const currentStep = store.state.guide.currentStep
+		const stepConfig = guide?.steps?.[currentStep]
+		// 检查当前步骤是否在当前页面
+		if (stepConfig?.page === '/pages/square/square') {
+			setTimeout(() => {
+				uni.$emit('guide:recalculatePosition')
+			}, 100)
+		}
+	}
+});
+
+// 展位提示框随机轮换定时器
+let dialogRotationTimer = null;
+
+// 计算 cabin 是否在可视区域内（通过 DOM boundingClientRect 判断，漏出区域大于70%）
+const isCabinInViewport = (cabin) => {
+	return new Promise((resolve) => {
+		const query = uni.createSelectorQuery();
+		query.select(`#cabin-${cabin.key}`).boundingClientRect((rect) => {
+			if (!rect) {
+				resolve(false);
+				return;
+			}
+			// 计算漏出区域百分比
+			const visibleTop = Math.max(0, rect.top);
+			const visibleBottom = Math.min(screenHeight.value, rect.bottom);
+			const visibleLeft = Math.max(0, rect.left);
+			const visibleRight = Math.min(screenWidth.value, rect.right);
+			const visibleWidth = Math.max(0, visibleRight - visibleLeft);
+			const visibleHeight = Math.max(0, visibleBottom - visibleTop);
+			const visibleArea = visibleWidth * visibleHeight;
+			const totalArea = rect.width * rect.height;
+			const visiblePercent = totalArea > 0 ? visibleArea / totalArea : 0;
+			const inViewport = visiblePercent > 0.7;
+			resolve(inViewport);
+		}).exec();
+	});
+};
+
+// 随机轮换展位提示框可见性
+const rotateDialogVisibility = async () => {
+	const cabins = visibleCabins.value;
+	if (!cabins.length) {
+		return;
+	}
+
+	// 先全部重置为 false
+	cabins.forEach(c => c.showDialog = false);
+
+	// 筛选符合条件的 cabin：有昵称、有展位剩余
+	const hasData = cabins.filter(c => c.nickname && c.sharedBoothSlotsRemaining !== null);
+
+	// 批量检查所有 cabin 是否在可视区域内
+	const viewportChecks = await Promise.all(hasData.map(c => isCabinInViewport(c)));
+	const eligible = hasData.filter((c, i) => viewportChecks[i]);
+
+	if (eligible.length === 0) return;
+
+	// 随机选择 2-3 个
+	const count = Math.min(Math.floor(Math.random() * 2) + 2, eligible.length, 3);
+	const shuffled = eligible.sort(() => Math.random() - 0.5);
+	for (let i = 0; i < count; i++) {
+		shuffled[i].showDialog = true;
+	}
+};
+
+// 启动定时器（2-3秒随机间隔）
+const startDialogRotation = () => {
+	stopDialogRotation();
+	const interval = Math.floor(Math.random() * 1000) + 2000; // 2000-3000ms
+	dialogRotationTimer = setTimeout(() => {
+		rotateDialogVisibility();
+		startDialogRotation(); // 继续下一轮
+	}, interval);
+};
+
+const stopDialogRotation = () => {
+	if (dialogRotationTimer) {
+		clearTimeout(dialogRotationTimer);
+		dialogRotationTimer = null;
+	}
+};
+
+// visibleCabins 更新时重启轮换
+watch(visibleCabins, () => {
+	console.log('[Square] visibleCabins watch triggered, cabins:', visibleCabins.value.length);
+	if (visibleCabins.value.some(c => c.nickname && c.sharedBoothSlotsRemaining !== null)) {
+		console.log('[Square] starting dialog rotation');
+		startDialogRotation();
+	} else {
+		stopDialogRotation();
+	}
+}, { immediate: true });
+
+// 翻页动画：direction = -1 向左，1 向右，精确移动 1 个 tileWidth
+const scrollPage = (direction) => {
+	// 立即更新 currentPage，触发数据加载，不等动画结束
+	const newPage = wrapPage(currentPage.value + direction);
+	currentPage.value = newPage;
+	ensurePages(newPage);
+
+	stopInertia();
+	const DURATION = 300;
+	const FRAME = 16;
+	const totalFrames = Math.round(DURATION / FRAME);
+	// 精确移动 1 个 tile 宽度，确保视觉上跨越一个 tile
+	const totalDelta = tileWidth.value * direction * -1;
+	let frame = 0;
+
+	const step = () => {
+		frame++;
+		const progress = frame / totalFrames;
+		const eased = 1 - Math.pow(1 - progress, 3);
+		const prevEased =
+			frame === 1 ? 0 : 1 - Math.pow(1 - (frame - 1) / totalFrames, 3);
+		const delta = totalDelta * (eased - prevEased);
+		// 箭头翻页使用 clampOffset，不触发 normalizeOffset 里的 tile 边界检测
+		bgOffsetX.value = clampOffset(bgOffsetX.value + delta);
+		rawOffsetX += delta;
+		if (frame < totalFrames) {
+			inertiaRaf = rafFn(step);
+		} else { }
+	};
+
+	inertiaRaf = rafFn(step);
+};
+
+const stopInertia = () => {
+	if (inertiaRaf) {
+		cafFn(inertiaRaf);
+		inertiaRaf = null;
+	}
+};
+
+// 重置广场到初始状态（位置、数据全部清空并重新加载第 1 页）
+const resetSquare = async () => {
+	stopInertia();
+	bgOffsetX.value = 0;
+	rawOffsetX = 0;
+	velocity = 0;
+	currentPage.value = 1;
+	totalUsers.value = 0;
+	pageCache.value = new Map();
+	pageCacheVersion.value++;
+	await fetchPage(1);
+	ensurePages(1);
+};
+
+onMounted(async () => {
+	const info = uni.getSystemInfoSync();
+	screenWidth.value = info.windowWidth;
+	screenHeight.value = info.windowHeight;
+	tileWidth.value = Math.round(info.windowHeight * (IMAGE_W / IMAGE_H));
+
+	const baseH = Math.round(info.windowWidth * 0.2 * 1.3);
+	cabinRenderDefs = CABIN_DEFS.map(({
+		imgW,
+		imgH,
+		anchorX,
+		anchorY
+	}) => {
+		const renderedH = baseH;
+		const renderedW = Math.round(renderedH * (imgW / imgH));
+		return {
+			renderedW,
+			renderedH,
+			offsetX: Math.round(renderedW * (anchorX / imgW)),
+			offsetY: Math.round(renderedH * (anchorY / imgH)),
+		};
+	});
+
+	const scale = info.windowHeight / IMAGE_H;
+	scaledCoords.value = CABIN_COORDS.map(([x, y]) => ({
+		sx: x * scale,
+		sy: y * scale,
+	}));
+	await fetchPage(1);
+	ensurePages(1);
+	loadBannerActivities();
+});
+
+// 从其他路由页面返回时重置
+onShow(() => {
+	resetSquare();
+});
+
+// 页面加载完成后初始化引导
+const store = useStore();
+const currentUserNickname = computed(() => store.state.user?.userInfo?.nickname || '');
+
+// 监听引导打开组件事件
+uni.$on('guide:openComponent', (componentName) => {
+	if (componentName === 'RankingModal') {
+		showRankingModal.value = true;
+	}
+});
+
+onUnmounted(() => {
+	uni.$off('guide:openComponent');
+	stopDialogRotation();
+});
+
+onShow(() => {
+	// 检查是否需要显示引导开始弹窗
+	if (shouldShowGuideStartModal()) {
+		showGuideStartModal.value = true;
+		console.log("[Square] 显示引导开始弹窗");
+	}
+	// 不再自动触发引导，由用户从引导列表选择后触发
+});
+
+// 处理引导开始
+const handleGuideStart = () => {
+	showGuideStartModal.value = false;
+};
+
+// 关闭引导开始弹窗
+const handleGuideStartModalClose = () => {
+	showGuideStartModal.value = false;
+};
+
+// 领取奖励成功
+const handleClaimSuccess = (reward) => {
+	// 可以在这里刷新用户信息
+	console.log("[Square] 领取奖励成功:", reward);
+};
+
+// banner 区域底部边界（px），触摸起点在此范围内时跳过背景滑动处理
+const getBannerBottom = () => (screenWidth.value / 750) * 496;
+let touchInBanner = false;
+
+const onBgTouchStart = (e) => {
+	const touchY = e.touches[0].clientY;
+	touchInBanner = touchY < getBannerBottom();
+	if (touchInBanner) return;
+	stopInertia();
+	isInertiaPhase = false;
+	touchStartX = e.touches[0].clientX;
+	lastMoveX = touchStartX;
+	lastMoveTime = Date.now();
+	velocity = 0;
+};
+
+const onBgTouchMove = (e) => {
+	// 如果触摸在 banner 区域也不处理，让 banner 自己处理
+	if (touchInBanner) return;
+	// 不在 banner 区域时，阻止默认行为以实现横向背景滑动
+	e.preventDefault();
+
+	const currentX = e.touches[0].clientX;
+	const now = Date.now();
+	const dt = now - lastMoveTime || 1;
+	velocity = (currentX - lastMoveX) / dt;
+	lastMoveX = currentX;
+	lastMoveTime = now;
+	bgOffsetX.value = normalizeOffset(bgOffsetX.value + (currentX - touchStartX));
+	touchStartX = currentX;
+};
+
+const onBgTouchEnd = () => {
+	if (touchInBanner) {
+		touchInBanner = false;
+		return;
+	}
+	touchInBanner = false;
+	isInertiaPhase = true;
+	const FRICTION = 0.8; // 惯性滚动的速度衰减系数
+	const MIN_VELOCITY = 0.2; // 惯性滚动速度小于此值时停止滚动
+
+	const step = () => {
+		velocity *= FRICTION;
+		if (Math.abs(velocity) < MIN_VELOCITY) {
+			isInertiaPhase = false;
+			return;
+		}
+		bgOffsetX.value = normalizeOffset(bgOffsetX.value + velocity * 16);
+		inertiaRaf = rafFn(step);
+	};
+
+	inertiaRaf = rafFn(step);
+};
+
+const onBgTouchCancel = () => {
+	touchInBanner = false;
+	stopInertia();
+	isInertiaPhase = false;
+	velocity = 0;
+};
+
+// --- 小屋点击跳转 ---
+const handleCabinClick = (cabin) => {
+	// 惯性速度残留时说明是滑动结束，不是真实点击
+	if (Math.abs(velocity) > 0.5) return;
+	// 无用户、或被 banner 遮住（showNickname=false）的小屋不响应点击
+	if (!cabin.userId || !cabin.showNickname) return;
+	// 如果是自己的小屋，不需要 target_uid 参数
+	uni.navigateTo({
+		url: cabin.isMine ? '/pages/exhibition/exhibition' : `/pages/exhibition/exhibition?target_uid=${cabin.userId}`,
+	});
+};
+
+// --- Tab 切换 ---
+const handleTabChange = (newTab) => {
+	if (newTab === 0) {
+		// 已经在广场页面，不需要跳转
+		navExpanded.value = false;
+		return;
+	}
+	
+	const routes = [
+		'/pages/square/square',
+		'/pages/starbook/index',
+		'/pages/castlove/mall',
+		'/pages/starcity/index',
+		'/pages/friends/index'
+	];
+	
+	if (newTab >= 0 && newTab < routes.length) {
+		uni.redirectTo({
+			url: routes[newTab]
+		});
+	}
+};
+
+onLoad((options) => {
+	// 调试模式：读取 guide_debug 参数并设置存储
+	if (options && 'guide_debug' in options) {
+		const debugValue = options.guide_debug
+		const isDebug = debugValue === '1' || debugValue === 'true'
+		if (isDebug) {
+			uni.setStorageSync('guide_debug_mode', true)
+			uni.setStorageSync('is_new_user', true)
+			console.log('[Guide] 调试模式已开启')
+		} else {
+			uni.setStorageSync('guide_debug_mode', false)
+			uni.removeStorageSync('is_new_user')
+			console.log('[Guide] 调试模式已关闭')
+		}
+	}
+});
+</script>
+
+<style scoped>
+.square-container {
+	position: relative;
+	width: 100vw;
+	height: 100vh;
+	min-height: 100vh;
+	overflow: hidden;
+}
+
+/* 3 张图并排，translateX 由 JS 控制（含初始 -tileWidth 偏移） */
+.background-strip {
+	position: absolute;
+	top: 0;
+	left: 0;
+	height: 150%;
+	display: flex;
+	z-index: 0;
+	will-change: transform;
+}
+
+.background-tile {
+	flex-shrink: 0;
+	height: 100%;
+}
+
+.cabin-layer {
+	position: absolute;
+	top: 0;
+	left: 0;
+	width: 100%;
+	height: 100%;
+	z-index: 1;
+	pointer-events: none;
+}
+
+.cabin-wrapper {
+	position: absolute;
+	display: flex;
+	flex-direction: column;
+	align-items: center;
+	pointer-events: auto;
+}
+
+.cabin-icon {
+	display: block;
+}
+
+.cabin-slots-zero .cabin-icon {
+	filter: grayscale(100%);
+	opacity: 0.6;
+}
+
+.cabin-nickname {
+	font-size: 20rpx;
+	color: #ffffff;
+	text-align: center;
+	text-shadow: 0 2rpx 4rpx rgba(0, 0, 0, 0.6);
+	margin-top: 4rpx;
+	max-width: 100%;
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+}
+
+.cabin-nickname--empty {
+	color: rgba(255, 255, 255, 0.75);
+	font-style: italic;
+}
+
+.cabin-slots-dialog {
+	position: absolute;
+	top: -50rpx;
+	left: 50%;
+	transform: translateX(-50%);
+	background-image: url('/static/icon/tips-bg.png');
+	background-size: 100% 100%;
+	background-repeat: no-repeat;
+	padding: 8rpx 24rpx 18rpx;
+	width: max-content;
+	z-index: 10;
+}
+
+.cabin-slots-text {
+	font-size: 18rpx;
+	font-weight: 600;
+	white-space: nowrap;
+	text-align: center;
+}
+
+.text-white {
+	color: #ffffff;
+}
+
+.text-orange {
+	color: #FFB800;
+	font-family: 'ZaoZiGongFangJianHei-1', sans-serif;
+	text-shadow:
+		0 0 10rpx rgba(255, 184, 0, 0.8),
+		0 2rpx 4rpx rgba(0, 0, 0, 0.5);
+}
+
+.nav-arrows {
+	position: fixed;
+	top: 50%;
+	left: 24rpx;
+	right: 24rpx;
+	transform: translateY(-50%);
+	display: flex;
+	justify-content: space-between;
+	align-items: center;
+	pointer-events: none;
+	z-index: 10;
+}
+
+.arrow-btn {
+	width: 56rpx;
+	height: 96rpx;
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	background: linear-gradient(165deg,
+			#f0e4b1 0%,
+			#f08399 50%,
+			#b94e73 90%,
+			#834b9e 100%);
+	border-radius: 12rpx;
+	pointer-events: auto;
+	cursor: pointer;
+	box-shadow: 0 4rpx 16rpx rgba(0, 0, 0, 0.25);
+}
+
+.arrow-left {
+	border-radius: 12rpx;
+}
+
+.arrow-right {
+	border-radius: 12rpx;
+}
+
+.arrow-btn:active {
+	opacity: 0.8;
+}
+
+.arrow-text {
+	font-size: 56rpx;
+	color: #ffffff;
+	font-weight: 600;
+	line-height: 1;
+	margin-top: -6rpx;
+}
+
+/* 轮播图 */
+.banner-carousel {
+	position: fixed;
+	top: 216rpx;
+	left: 0;
+	right: 0;
+	width: 100%;
+	z-index: 100;
+	padding: 0 8rpx;
+	box-sizing: border-box;
+}
+
+.banner-swiper {
+	width: 100%;
+	height: 312rpx;
+	border-radius: 24rpx;
+	overflow: hidden;
+}
+
+/* 防止 swiper-item 内容溢出露边 */
+:deep(.uni-swiper-slide) {
+	overflow: hidden;
+}
+
+.banner-activity-img {
+	width: 100%;
+	height: 100%;
+	display: block;
+}
+
+.nav-mask {
+	position: fixed;
+	top: 0;
+	left: 0;
+	right: 0;
+	bottom: 0;
+	width: 100%;
+	height: 100%;
+	background: rgba(0, 0, 0, 0.3);
+	z-index: 999;
+	animation: fadeIn 0.3s ease-out;
+}
+
+@keyframes fadeIn {
+	from {
+		opacity: 0;
+	}
+
+	to {
+		opacity: 1;
+	}
+}
+</style>
\ No newline at end of file