# 同步

**Repository Path**: my_module/sync

## Basic Information

- **Project Name**: 同步
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-12
- **Last Updated**: 2026-04-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# sync 模块 - 多端数据同步

为 myAdmin 提供服务端数据同步能力，支持电脑端、手机端、浏览器插件等多端的数据增量同步、设备管理、模块功能同步。

详细设计见项目根目录 `docs/同步.md`。

## 安装

通过后台「模块管理 → 安装模块 → 本地」安装，或直接在数据库中执行 `sync.sql`。

安装后会创建：
- `sync_device` 表 - 用户已注册的同步设备
- `sync_cursor` 表 - 每个设备每张表的同步游标

## 让模块可同步

在模块的 `module.json` 中增加 `sync` 字段：

```json
{
    "sync": {
        "enabled": true,
        "tables": {
            "memo": "module\\memo\\model\\Memo",
            "memo_tag": "module\\memo\\model\\MemoTag"
        }
    }
}
```

约束：
- 同步表**必须**有 `id` 主键、`uid` 字段、`utime` 字段
- 关系表（无 `id` 主键）暂不支持，需在客户端做 ID 映射后再推送
- 软删除使用 `status = -1` 表示，参与同步

## API 一览

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/sync/device/register` | 注册或更新设备 |
| GET  | `/sync/device/list` | 当前用户的设备列表 |
| POST | `/sync/device/remove` | 移除设备（清除游标） |
| POST | `/sync/device/rename` | 重命名设备 |
| POST | `/sync/sync/push` | 推送本地变更 |
| POST | `/sync/sync/pull` | 拉取服务端变更 |
| POST | `/sync/sync/ack` | 确认拉取完成（更新游标） |
| GET  | `/sync/sync/status` | 查询同步状态 |
| GET  | `/sync/module/list` | 可同步模块列表 |

所有接口需 JWT 认证：`Authorization: Bearer {token}`。

## 后台管理

- `admin/sync/index` - 同步统计（设备数、用户数、可同步模块）
- `admin/sync/device` - 设备列表（按用户、类型筛选；可移除）

## 测试

```bash
bash test/test-sync.sh http://10.0.0.219:8052 testuser 123456
```

测试脚本会：
1. 登录获取 token
2. 注册一个临时设备
3. 列出可同步模块
4. 推送一条新便签 → 拉取 → ack
5. 推送对该便签的更新（验证更新分支）
6. 列出设备 → 移除测试设备