16 KiB

Raw Blame History

离线功能触发机制与页面集成规划

版本: v1.0
创建日期: 2026-02-26

一、离线/同步触发机制

1.1 离线触发场景

┌─────────────────────────────────────────────────────────────┐
│                    离线触发场景                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. 网络断开                                                 │
│     - 用户进入电梯、地下室、隧道等信号弱区域                  │
│     - 用户关闭移动数据/WiFi                                  │
│     - 飞行模式开启                                           │
│                                                             │
│  2. 服务器不可达                                             │
│     - 服务器维护                                             │
│     - 网关超时                                               │
│     - DNS解析失败                                            │
│                                                             │
│  3. 请求失败                                                 │
│     - 请求超时                                               │
│     - 连接错误                                               │
│                                                             │
└─────────────────────────────────────────────────────────────┘

1.2 同步触发场景

┌─────────────────────────────────────────────────────────────┐
│                    同步触发场景                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. 自动触发                                                 │
│     ├── 网络恢复时 (onNetworkStatusChange)                  │
│     ├── 操作完成后立即尝试 (如果在线)                        │
│     └── 定时同步 (可配置，默认30秒)                          │
│                                                             │
│  2. 手动触发                                                 │
│     ├── 用户下拉刷新                                        │
│     ├── 用户点击"同步"按钮                                   │
│     └── 用户重试失败项                                       │
│                                                             │
│  3. 应用生命周期                                             │
│     ├── 应用启动时                                          │
│     ├── 应用从后台恢复时                                    │
│     └── 应用退出前 (可选)                                    │
│                                                             │
└─────────────────────────────────────────────────────────────┘

1.3 当前代码中的触发点

触发点	文件	触发条件	处理逻辑
网络状态变化	`sync-queue.ts:36-44`	`uni.onNetworkStatusChange`	离线→在线时自动处理队列
操作添加时	`sync-queue.ts:74-76`	`add()` 方法调用	如果在线立即尝试同步
定时重试	`sync-queue.ts:184-188`	重试延迟后	检查网络后处理
手动触发	`sync-queue.ts:205-215`	`retryFailed()` 调用	重置失败项并处理

1.4 业务操作触发流程

用户操作 (如: 接单)
    │
    ▼
┌───────────────────────────────────────┐
│  Repository 方法 (如: accept)          │
│  if (在线) {                           │
│    直接调用API                         │
│    成功 → 更新本地状态                  │
│    失败 → 加入同步队列                  │
│  } else {                              │
│    更新本地状态                         │
│    加入同步队列                         │
│  }                                     │
└───────────────────────────────────────┘
    │
    ▼
┌───────────────────────────────────────┐
│  同步队列 (syncQueue.add)              │
│  - 生成唯一ID                          │
│  - 记录时间戳                          │
│  - 设置优先级                          │
│  - 持久化到本地存储                     │
└───────────────────────────────────────┘
    │
    ▼
┌───────────────────────────────────────┐
│  如果在线 → 立即尝试同步                │
│  如果离线 → 等待网络恢复                │
└───────────────────────────────────────┘

二、页面集成规划

2.1 需要集成的页面

页面	文件路径	集成内容
工单列表	`pages/work-order/list.vue`	离线工单显示、状态筛选
工单详情	`pages/work-order/detail.vue`	离线操作按钮、同步状态
巡检任务	`pages/inspection/task/index.vue`	离线任务显示
巡检执行	`pages/inspection/execute/index.vue`	离线签到、结果提交
访客登记	`pages/visitor/register.vue`	离线登记
访客记录	`pages/visitor/records.vue`	离线记录显示
首页	`pages/index/index.vue`	离线状态提示、待同步数量

2.2 公共组件

需要创建以下公共组件：

src/components/offline/
├── OfflineStatus.vue      # 离线状态指示器
├── SyncIndicator.vue      # 同步进度指示器
├── PendingBadge.vue       # 待同步数量徽章
└── OfflineNotice.vue      # 离线通知横幅

三、UI组件设计

3.1 离线状态指示器 (OfflineStatus.vue)

<template>
  <view class="offline-status" :class="{ offline: !isOnline }">
    <view class="status-icon">
      <text class="icon">{{ isOnline ? '📶' : '📵' }}</text>
    </view>
    <text class="status-text">{{ statusText }}</text>
    <view v-if="pendingCount > 0" class="pending-badge">
      <text>{{ pendingCount }}</text>
    </view>
  </view>
</template>

<script setup lang="ts">
import { computed } from 'vue'
import { syncQueue } from '@/offline'

const isOnline = computed(() => syncQueue.isOnline())
const pendingCount = computed(() => syncQueue.count.value)

const statusText = computed(() => {
  if (!isOnline.value) return '离线'
  if (pendingCount.value > 0) return `同步中(${pendingCount.value})`
  return '在线'
})
</script>

3.2 同步进度指示器 (SyncIndicator.vue)

<template>
  <view v-if="show" class="sync-indicator">
    <view class="sync-animation">
      <text class="icon">🔄</text>
    </view>
    <text class="sync-text">正在同步...</text>
  </view>
</template>

<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue'
import { syncQueue } from '@/offline'

const show = ref(false)
let syncStartTime = 0

const handleSyncStart = () => {
  show.value = true
  syncStartTime = Date.now()
}

const handleSyncComplete = () => {
  const elapsed = Date.now() - syncStartTime
  setTimeout(() => {
    show.value = false
  }, Math.max(0, 500 - elapsed))
}
</script>

3.3 离线通知横幅 (OfflineNotice.vue)

<template>
  <view v-if="!isOnline" class="offline-notice">
    <text class="notice-icon">⚠️</text>
    <text class="notice-text">当前处于离线状态，操作将在联网后自动同步</text>
  </view>
</template>

<script setup lang="ts">
import { computed } from 'vue'
import { syncQueue } from '@/offline'

const isOnline = computed(() => syncQueue.isOnline())
</script>

<style scoped>
.offline-notice {
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  background: #ff9800;
  color: white;
  padding: 8px 16px;
  display: flex;
  align-items: center;
  z-index: 9999;
}
</style>

3.4 待同步徽章 (PendingBadge.vue)

<template>
  <view v-if="count > 0" class="pending-badge">
    <text class="badge-count">{{ count > 99 ? '99+' : count }}</text>
  </view>
</template>

<script setup lang="ts">
import { computed } from 'vue'
import { syncQueue } from '@/offline'

const count = computed(() => syncQueue.count.value)
</script>

<style scoped>
.pending-badge {
  background: #f56c6c;
  color: white;
  border-radius: 10px;
  padding: 2px 6px;
  font-size: 12px;
  min-width: 18px;
  text-align: center;
}
</style>

四、页面集成示例

4.1 工单详情页集成

<template>
  <view class="work-order-detail">
    <!-- 离线通知 -->
    <OfflineNotice />
    
    <!-- 同步状态 -->
    <view class="sync-status" v-if="entity._offline">
      <text v-if="entity._offline.syncStatus === 'PENDING'" class="pending">
        ⏳ 待同步
      </text>
      <text v-else-if="entity._offline.syncStatus === 'CONFLICT'" class="conflict">
        ⚠️ 同步冲突
      </text>
      <text v-else class="synced">
        ✅ 已同步
      </text>
    </view>
    
    <!-- 工单内容 -->
    <view class="content">
      <!-- ... -->
    </view>
    
    <!-- 操作按钮 -->
    <view class="actions">
      <button 
        v-if="canAccept" 
        @click="handleAccept"
        :loading="accepting"
      >
        接单
      </button>
      <button 
        v-if="canStart" 
        @click="handleStart"
        :loading="starting"
      >
        开始处理
      </button>
      <button 
        v-if="canComplete" 
        @click="handleComplete"
        :loading="completing"
      >
        完成工单
      </button>
    </view>
  </view>
</template>

<script setup lang="ts">
import { ref, computed, onMounted } from 'vue'
import { workOrderRepository, syncQueue } from '@/offline'
import OfflineNotice from '@/components/offline/OfflineNotice.vue'

const props = defineProps<{ id: string }>()
const entity = ref<any>({})
const accepting = ref(false)
const starting = ref(false)
const completing = ref(false)

const isOnline = computed(() => syncQueue.isOnline())

const canAccept = computed(() => 
  entity.value.status === 'ASSIGNED'
)

const canStart = computed(() => 
  entity.value.status === 'ACCEPTED'
)

const canComplete = computed(() => 
  entity.value.status === 'IN_PROGRESS'
)

onMounted(async () => {
  entity.value = await workOrderRepository.get(props.id)
})

async function handleAccept() {
  accepting.value = true
  try {
    await workOrderRepository.accept(props.id)
    entity.value = await workOrderRepository.get(props.id)
    
    if (!isOnline.value) {
      uni.showToast({
        title: '已离线接单，联网后自动同步',
        icon: 'none'
      })
    }
  } catch (error) {
    uni.showToast({ title: '操作失败', icon: 'none' })
  } finally {
    accepting.value = false
  }
}

async function handleStart() {
  starting.value = true
  try {
    await workOrderRepository.start(props.id)
    entity.value = await workOrderRepository.get(props.id)
  } catch (error) {
    uni.showToast({ title: '操作失败', icon: 'none' })
  } finally {
    starting.value = false
  }
}

async function handleComplete() {
  completing.value = true
  try {
    await workOrderRepository.complete(props.id, '处理完成')
    entity.value = await workOrderRepository.get(props.id)
  } catch (error) {
    uni.showToast({ title: '操作失败', icon: 'none' })
  } finally {
    completing.value = false
  }
}
</script>

4.2 首页集成

<template>
  <view class="home">
    <!-- 离线状态栏 -->
    <view class="status-bar">
      <OfflineStatus />
      <view v-if="failedCount > 0" class="failed-sync" @click="handleRetryFailed">
        <text>{{ failedCount }}项同步失败，点击重试</text>
      </view>
    </view>
    
    <!-- 统计卡片 -->
    <view class="stats">
      <view class="stat-card">
        <text class="stat-value">{{ pendingWorkOrders }}</text>
        <text class="stat-label">待处理工单</text>
      </view>
      <view class="stat-card">
        <text class="stat-value">{{ todayInspections }}</text>
        <text class="stat-label">今日巡检</text>
      </view>
      <view class="stat-card">
        <text class="stat-value">{{ todayVisitors }}</text>
        <text class="stat-label">今日访客</text>
      </view>
    </view>
    
    <!-- 快捷入口 -->
    <!-- ... -->
  </view>
</template>

<script setup lang="ts">
import { ref, computed, onMounted } from 'vue'
import { workOrderRepository, inspectionRepository, visitorRepository, syncQueue } from '@/offline'
import OfflineStatus from '@/components/offline/OfflineStatus.vue'

const pendingWorkOrders = ref(0)
const todayInspections = ref(0)
const todayVisitors = ref(0)

const failedCount = computed(() => syncQueue.getFailedItems().length)

onMounted(async () => {
  // 从离线存储加载数据
  const workOrders = await workOrderRepository.getByStatus('ASSIGNED')
  pendingWorkOrders.value = workOrders.length
  
  const inspections = await inspectionRepository.getTodayTasks()
  todayInspections.value = inspections.length
  
  const visitors = await visitorRepository.getTodayVisitors()
  todayVisitors.value = visitors.length
})

function handleRetryFailed() {
  syncQueue.retryFailed()
  uni.showToast({ title: '正在重试同步...', icon: 'none' })
}
</script>

五、初始化集成

5.1 main.ts 集成

// src/main.ts
import { createSSRApp } from 'vue'
import App from './App.vue'
import { initOfflineStorage } from './offline'

// 初始化离线存储
initOfflineStorage()

export function createApp() {
  const app = createSSRApp(App)
  return { app }
}

5.2 App.vue 全局状态

<script setup lang="ts">
import { onLaunch, onShow, onHide } from '@dcloudio/uni-app'
import { syncQueue } from '@/offline'

onLaunch(() => {
  console.log('App Launch')
})

onShow(() => {
  // 应用从后台恢复时，尝试同步
  if (syncQueue.isOnline()) {
    syncQueue.process()
  }
})

onHide(() => {
  console.log('App Hide')
})
</script>

六、实施计划

阶段一：公共组件开发 (1天)

任务	预计时间
创建 OfflineStatus.vue	1小时
创建 SyncIndicator.vue	1小时
创建 OfflineNotice.vue	0.5小时
创建 PendingBadge.vue	0.5小时
组件测试	2小时

阶段二：页面集成 (2天)

任务	预计时间
首页集成	2小时
工单列表/详情集成	3小时
巡检任务/执行集成	3小时
访客登记/记录集成	2小时
集成测试	4小时

阶段三：优化完善 (1天)

任务	预计时间
照片离线处理	3小时
消息模块离线	2小时
性能优化	2小时
文档完善	1小时

七、注意事项

数据一致性: 离线操作可能与服务器数据冲突，需要处理冲突场景
存储容量: 注意本地存储容量限制，定期清理过期数据
用户体验: 离线操作要有明确提示，避免用户困惑
错误处理: 同步失败要有重试机制和错误提示
测试覆盖: 需要覆盖离线/在线切换场景的测试

16 KiB Raw Blame History Unescape Escape

离线功能触发机制与页面集成规划

一、离线/同步触发机制

1.1 离线触发场景

1.2 同步触发场景

1.3 当前代码中的触发点

1.4 业务操作触发流程

二、页面集成规划

2.1 需要集成的页面

2.2 公共组件

三、UI组件设计

3.1 离线状态指示器 (OfflineStatus.vue)

3.2 同步进度指示器 (SyncIndicator.vue)

3.3 离线通知横幅 (OfflineNotice.vue)

3.4 待同步徽章 (PendingBadge.vue)

四、页面集成示例

4.1 工单详情页集成

4.2 首页集成

五、初始化集成

5.1 main.ts 集成

5.2 App.vue 全局状态

六、实施计划

阶段一：公共组件开发 (1天)

阶段二：页面集成 (2天)

阶段三：优化完善 (1天)

七、注意事项

16 KiB

Raw Blame History