feat: 初始化设计文档草稿

- SPEC.md: 项目概览与文档索引 - docs/architecture.md: 系统架构设计 - docs/api.md: 后台 API 接口设计 - docs/database.md: 数据库表结构设计 - docs/h5.md: H5 页面结构与交互设计 - docs/offline.md: 离线数据方案状态: 设计中，待设备API协议确认后细化
2026-04-14 11:25:17 +08:00
commit 86777f585e
6 changed files with 1165 additions and 0 deletions
--- a/docs/offline.md
+++ b/docs/offline.md
@@ -0,0 +1,191 @@
+# 离线数据方案
+
+> 状态: 设计中（MVP 阶段可简化）
+
+---
+
+## 1. 背景
+
+工地现场网络环境不稳定，H5 移动端可能出现网络中断。需要保证：
+
+1. **已加载数据可继续浏览**（设备列表、预警等）
+2. **网络恢复后数据自动同步**
+3. **离线期间的操作不丢失**
+
+---
+
+## 2. 离线存储策略
+
+### 2.1 存储层级
+
+| 层级 | 技术 | 容量 | 适用场景 |
+|------|------|------|----------|
+| Memory | JavaScript 变量 | 无限 | 页面运行期间 |
+| LocalStorage | 浏览器本地存储 | ~5MB | 永久存储（小数据） |
+| IndexedDB | 浏览器索引数据库 | ~50MB+ | 结构化数据存储 |
+
+**选型**: 以 **IndexedDB** 为主，LocalStorage 辅助。
+
+---
+
+## 3. 离线缓存设计
+
+### 3.1 IndexedDB 表设计
+
+```javascript
+// 数据库: SmartProjectDB
+// 版本: 1
+
+// 对象存储 1: devices
+{
+  store: 'devices',
+  keyPath: 'id',
+  indexes: ['type', 'status'],
+  data: { id, name, type, model, location, status, last_seen }
+}
+
+// 对象存储 2: alerts
+{
+  store: 'alerts',
+  keyPath: 'id',
+  indexes: ['status', 'level', 'created_at'],
+  data: { id, device_id, device_name, level, message, status, created_at }
+}
+
+// 对象存储 3: sync_queue（离线操作队列）
+{
+  store: 'sync_queue',
+  keyPath: 'id',
+  autoIncrement: true,
+  data: { id, action, payload, created_at, status }
+}
+```
+
+### 3.2 缓存更新策略
+
+| 数据类型 | 更新频率 | 缓存策略 |
+|----------|----------|----------|
+| 设备列表 | 每 5 分钟 | 后台静默更新 |
+| 设备详情 | 每 30 秒 | 页面打开时拉取 + 定时刷新 |
+| 预警列表 | 每 1 分钟 | 后台静默更新 + 新预警推送 |
+| 预警详情 | 实时 | 打开时拉取 |
+
+**更新流程**:
+```
+用户打开页面
+    │
+    ├─ 有网络 → API 请求 → 更新 IndexedDB → 渲染
+    │
+    └─ 无网络 → 读取 IndexedDB → 渲染（显示"离线模式"）
+```
+
+---
+
+## 4. 离线操作队列
+
+### 4.1 场景
+
+用户在离线状态下执行操作（如处理预警、提交备注），操作记录存入 `sync_queue`，网络恢复后自动同步。
+
+### 4.2 同步流程
+
+```
+检测到网络恢复（navigator.onLine 事件）
+    │
+    ▼
+读取 sync_queue（status: pending）
+    │
+    ▼
+逐条执行 API 请求
+    │
+    ├─ 成功 → 删除队列记录，更新本地数据
+    │
+    └─ 失败 → 重试3次，仍失败标记为 failed，用户手动处理
+```
+
+### 4.3 队列记录格式
+
+```javascript
+{
+  id: 1,
+  action: 'handle_alert',
+  payload: {
+    alert_id: 'alert_001',
+    action: 'handled',
+    note: '已现场确认'
+  },
+  created_at: '2026-04-14T10:00:00Z',
+  status: 'pending',   // pending / syncing / failed
+  retry_count: 0
+}
+```
+
+---
+
+## 5. Service Worker
+
+### 5.1 职责
+
+- 拦截 H5 页面的 HTTP 请求
+- 实现缓存策略（静态资源优先缓存，网络优先等）
+- 离线时返回缓存的页面
+
+### 5.2 缓存策略
+
+| 资源类型 | 缓存策略 | 说明 |
+|----------|----------|------|
+| HTML | Network First | 始终尝试获取最新 |
+| CSS/JS | Cache First | 优先使用缓存，性能优先 |
+| API 数据 | Network Only | 实时性要求高，不缓存 |
+| 图标/字体 | Cache First | 长期不变 |
+
+### 5.3 Service Worker 注册
+
+```javascript
+// main.js
+if ('serviceWorker' in navigator) {
+  navigator.serviceWorker.register('/sw.js')
+    .then(reg => console.log('SW registered'))
+    .catch(err => console.error('SW registration failed:', err));
+}
+```
+
+---
+
+## 6. 网络状态提示
+
+页面监听网络状态，给用户明确反馈：
+
+```javascript
+// 监听网络状态
+window.addEventListener('online', () => {
+  showToast('网络已恢复，正在同步...');
+  syncPendingOperations();
+});
+
+window.addEventListener('offline', () => {
+  showToast('网络已断开，显示离线数据');
+});
+```
+
+---
+
+## 7. 简化方案（MVP）
+
+MVP 阶段可降低离线复杂度：
+
+| 方案 | 说明 |
+|------|------|
+| 简单缓存 | 仅在 LocalStorage 缓存用户信息 + 最后设备列表，H5 页面可离线展示 |
+| 无离线操作 | 离线期间禁用操作按钮，提示"网络异常" |
+| 手动刷新 | 网络恢复后用户下拉刷新 |
+
+**后续迭代再实现完整离线能力**。
+
+---
+
+## 8. 待确认
+
+- [ ] 是否需要 PWA（可安装到桌面/主屏幕）
+- [ ] IndexedDB 库选型（idb / Dexie.js 还是原生）
+- [ ] 离线数据保留时长策略