Merge pull request #10 from Yaosanqi137/feature/p2-sync-engine

feat(sync): 完成离线同步链路并优化任务编辑体验

apps/api/src/app.module.ts

@@ -3,6 +3,7 @@ import { ConfigModule } from "@nestjs/config";
 import { AttachmentModule } from "./attachment/attachment.module";
 import { AuthModule } from "./auth/auth.module";
 import { PrismaModule } from "./prisma/prisma.module";
+import { SyncModule } from "./sync/sync.module";
 import { TaskModule } from "./task/task.module";
 
 @Module({
@@ -14,7 +15,8 @@ import { TaskModule } from "./task/task.module";
     PrismaModule,
     AuthModule,
     TaskModule,
-    AttachmentModule
+    AttachmentModule,
+    SyncModule
   ]
 })
 export class AppModule {}

apps/api/src/main.ts

@@ -1,10 +1,18 @@
 import "reflect-metadata";
 import { ValidationPipe } from "@nestjs/common";
 import { NestFactory } from "@nestjs/core";
+import type { NestExpressApplication } from "@nestjs/platform-express";
 import { AppModule } from "./app.module";
 
 async function bootstrap(): Promise<void> {
-  const app = await NestFactory.create(AppModule);
+  const app = await NestFactory.create<NestExpressApplication>(AppModule);
+  const bodyLimit = process.env.API_BODY_LIMIT ?? "8mb";
+
+  app.useBodyParser("json", { limit: bodyLimit });
+  app.useBodyParser("urlencoded", {
+    extended: true,
+    limit: bodyLimit
+  });
   app.enableCors({
     origin: true,
     credentials: true

apps/api/src/sync/dto/sync-pull.dto.ts

@@ -0,0 +1,16 @@
+import { Type } from "class-transformer";
+import { IsInt, IsOptional, IsString, Max, MaxLength, Min } from "class-validator";
+
+export class SyncPullQueryDto {
+  @IsOptional()
+  @IsString()
+  @MaxLength(512)
+  cursor?: string;
+
+  @Type(() => Number)
+  @IsOptional()
+  @IsInt()
+  @Min(1)
+  @Max(200)
+  limit?: number;
+}

apps/api/src/sync/dto/sync-push.dto.ts

@@ -0,0 +1,62 @@
+import { Type } from "class-transformer";
+import {
+  ArrayMaxSize,
+  ArrayMinSize,
+  IsArray,
+  IsEnum,
+  IsInt,
+  IsOptional,
+  IsString,
+  MaxLength,
+  Min,
+  ValidateNested
+} from "class-validator";
+
+export enum SyncEntityTypeDto {
+  TASK = "TASK"
+}
+
+export enum SyncActionTypeDto {
+  CREATE = "CREATE",
+  UPDATE = "UPDATE",
+  DELETE = "DELETE"
+}
+
+export class SyncPushOperationDto {
+  @IsString()
+  @MaxLength(64)
+  opId!: string;
+
+  @IsString()
+  @MaxLength(64)
+  entityId!: string;
+
+  @IsEnum(SyncEntityTypeDto)
+  entityType!: SyncEntityTypeDto;
+
+  @IsEnum(SyncActionTypeDto)
+  action!: SyncActionTypeDto;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(5000000)
+  payload?: string;
+
+  @Type(() => Number)
+  @IsInt()
+  @Min(0)
+  clientTs!: number;
+
+  @IsString()
+  @MaxLength(128)
+  deviceId!: string;
+}
+
+export class SyncPushDto {
+  @IsArray()
+  @ArrayMinSize(1)
+  @ArrayMaxSize(200)
+  @ValidateNested({ each: true })
+  @Type(() => SyncPushOperationDto)
+  operations!: SyncPushOperationDto[];
+}

apps/api/src/sync/sync.controller.ts

@@ -0,0 +1,34 @@
+import { Body, Controller, Get, Headers, Post, Query, UnauthorizedException } from "@nestjs/common";
+import { SyncPullQueryDto } from "./dto/sync-pull.dto";
+import { SyncPushDto } from "./dto/sync-push.dto";
+import { SyncPullResponse, SyncPushResponse, SyncService } from "./sync.service";
+
+@Controller("sync")
+export class SyncController {
+  constructor(private readonly syncService: SyncService) {}
+
+  @Get("pull")
+  async pullOperations(
+    @Headers("x-user-id") userIdHeader: string | string[] | undefined,
+    @Query() query: SyncPullQueryDto
+  ): Promise<SyncPullResponse> {
+    return this.syncService.pullOperations(this.resolveUserId(userIdHeader), query);
+  }
+
+  @Post("push")
+  async pushOperations(
+    @Headers("x-user-id") userIdHeader: string | string[] | undefined,
+    @Body() body: SyncPushDto
+  ): Promise<SyncPushResponse> {
+    return this.syncService.pushOperations(this.resolveUserId(userIdHeader), body);
+  }
+
+  private resolveUserId(userIdHeader: string | string[] | undefined): string {
+    const userId = Array.isArray(userIdHeader) ? userIdHeader[0] : userIdHeader;
+    if (!userId) {
+      throw new UnauthorizedException("缺少用户上下文");
+    }
+
+    return userId;
+  }
+}

apps/api/src/sync/sync.module.ts

@@ -0,0 +1,11 @@
+import { Module } from "@nestjs/common";
+import { PrismaModule } from "../prisma/prisma.module";
+import { SyncController } from "./sync.controller";
+import { SyncService } from "./sync.service";
+
+@Module({
+  imports: [PrismaModule],
+  controllers: [SyncController],
+  providers: [SyncService]
+})
+export class SyncModule {}

apps/api/src/sync/sync.service.ts

@@ -0,0 +1,313 @@
+import { BadRequestException, Injectable } from "@nestjs/common";
+import { Prisma } from "../../generated/prisma/client";
+import { PrismaService } from "../prisma/prisma.service";
+import { SyncPullQueryDto } from "./dto/sync-pull.dto";
+import { SyncPushDto, SyncPushOperationDto } from "./dto/sync-push.dto";
+
+export type SyncPushItemStatus = "accepted" | "duplicate" | "failed";
+
+export type SyncPushItemResult = {
+  opId: string;
+  status: SyncPushItemStatus;
+  serverTs: string | null;
+  reason: string | null;
+};
+
+export type SyncPushResponse = {
+  acceptedCount: number;
+  duplicateCount: number;
+  failedCount: number;
+  results: SyncPushItemResult[];
+};
+
+type ExistingOperationRecord = {
+  opId: string;
+  serverTs: Date;
+};
+
+type SyncPullCursorState = {
+  serverTs: string;
+  opId: string;
+};
+
+type SyncPullOperationRecord = {
+  opId: string;
+  entityId: string;
+  entityType: string;
+  action: string;
+  payload: Prisma.JsonValue | null;
+  clientTs: Date;
+  deviceId: string;
+  serverTs: Date;
+};
+
+export type SyncPullItem = {
+  opId: string;
+  entityId: string;
+  entityType: string;
+  action: string;
+  payload: string | null;
+  clientTs: number;
+  deviceId: string;
+  serverTs: string;
+};
+
+export type SyncPullResponse = {
+  items: SyncPullItem[];
+  nextCursor: string | null;
+  hasMore: boolean;
+};
+
+@Injectable()
+export class SyncService {
+  constructor(private readonly prismaService: PrismaService) {}
+
+  async pullOperations(userId: string, query: SyncPullQueryDto): Promise<SyncPullResponse> {
+    const limit = query.limit ?? 100;
+    const cursor = this.parseCursor(query.cursor);
+
+    const operations = (await this.prismaService.syncOperation.findMany({
+      where: this.buildPullWhereInput(userId, cursor),
+      orderBy: [{ serverTs: "asc" }, { opId: "asc" }],
+      take: limit + 1,
+      select: {
+        opId: true,
+        entityId: true,
+        entityType: true,
+        action: true,
+        payload: true,
+        clientTs: true,
+        deviceId: true,
+        serverTs: true
+      }
+    })) as SyncPullOperationRecord[];
+
+    const hasMore = operations.length > limit;
+    const pageItems = hasMore ? operations.slice(0, limit) : operations;
+    const lastOperation = pageItems.at(-1);
+
+    return {
+      items: pageItems.map((operation) => this.serializePullItem(operation)),
+      nextCursor: lastOperation
+        ? this.encodeCursor({
+            serverTs: lastOperation.serverTs.toISOString(),
+            opId: lastOperation.opId
+          })
+        : (query.cursor ?? null),
+      hasMore
+    };
+  }
+
+  async pushOperations(userId: string, body: SyncPushDto): Promise<SyncPushResponse> {
+    const existingOperations = await this.loadExistingOperations(userId, body.operations);
+    const results: SyncPushItemResult[] = [];
+    const seenOperationIds = new Set<string>();
+    const acceptedOperationServerTs = new Map<string, string>();
+
+    for (const operation of body.operations) {
+      if (seenOperationIds.has(operation.opId)) {
+        results.push({
+          opId: operation.opId,
+          status: "duplicate",
+          serverTs: acceptedOperationServerTs.get(operation.opId) ?? null,
+          reason: "same_batch_duplicate"
+        });
+        continue;
+      }
+
+      seenOperationIds.add(operation.opId);
+
+      const existingOperation = existingOperations.get(operation.opId);
+      if (existingOperation) {
+        results.push({
+          opId: operation.opId,
+          status: "duplicate",
+          serverTs: existingOperation.serverTs.toISOString(),
+          reason: "already_synced"
+        });
+        continue;
+      }
+
+      try {
+        const createdOperation = await this.prismaService.syncOperation.create({
+          data: {
+            opId: operation.opId,
+            userId,
+            deviceId: operation.deviceId,
+            entityType: operation.entityType,
+            entityId: operation.entityId,
+            action: operation.action,
+            payload: operation.payload,
+            clientTs: new Date(operation.clientTs)
+          },
+          select: {
+            opId: true,
+            serverTs: true
+          }
+        });
+
+        const serverTs = createdOperation.serverTs.toISOString();
+        acceptedOperationServerTs.set(createdOperation.opId, serverTs);
+        results.push({
+          opId: createdOperation.opId,
+          status: "accepted",
+          serverTs,
+          reason: null
+        });
+      } catch (error) {
+        if (this.isDuplicateOpIdError(error)) {
+          results.push({
+            opId: operation.opId,
+            status: "duplicate",
+            serverTs: null,
+            reason: "already_synced"
+          });
+          continue;
+        }
+
+        results.push({
+          opId: operation.opId,
+          status: "failed",
+          serverTs: null,
+          reason: "persist_failed"
+        });
+      }
+    }
+
+    return {
+      acceptedCount: results.filter((item) => item.status === "accepted").length,
+      duplicateCount: results.filter((item) => item.status === "duplicate").length,
+      failedCount: results.filter((item) => item.status === "failed").length,
+      results
+    };
+  }
+
+  private async loadExistingOperations(
+    userId: string,
+    operations: SyncPushOperationDto[]
+  ): Promise<Map<string, ExistingOperationRecord>> {
+    const opIds = Array.from(new Set(operations.map((operation) => operation.opId)));
+
+    const existingOperations = (await this.prismaService.syncOperation.findMany({
+      where: {
+        userId,
+        opId: {
+          in: opIds
+        }
+      },
+      select: {
+        opId: true,
+        serverTs: true
+      }
+    })) as ExistingOperationRecord[];
+
+    return new Map(
+      existingOperations.map((operation): [string, ExistingOperationRecord] => [
+        operation.opId,
+        operation
+      ])
+    );
+  }
+
+  private buildPullWhereInput(
+    userId: string,
+    cursor: SyncPullCursorState | null
+  ): Prisma.SyncOperationWhereInput {
+    if (!cursor) {
+      return { userId };
+    }
+
+    const cursorDate = new Date(cursor.serverTs);
+
+    return {
+      userId,
+      // 同一毫秒内可能有多条操作，必须使用 opId 作为二级游标来保证稳定分页。
+      OR: [
+        {
+          serverTs: {
+            gt: cursorDate
+          }
+        },
+        {
+          serverTs: cursorDate,
+          opId: {
+            gt: cursor.opId
+          }
+        }
+      ]
+    };
+  }
+
+  private serializePullItem(operation: SyncPullOperationRecord): SyncPullItem {
+    return {
+      opId: operation.opId,
+      entityId: operation.entityId,
+      entityType: operation.entityType,
+      action: operation.action,
+      payload: this.serializePayload(operation.payload),
+      clientTs: operation.clientTs.getTime(),
+      deviceId: operation.deviceId,
+      serverTs: operation.serverTs.toISOString()
+    };
+  }
+
+  private serializePayload(payload: Prisma.JsonValue | null): string | null {
+    if (payload === null) {
+      return null;
+    }
+
+    if (typeof payload === "string") {
+      return payload;
+    }
+
+    return JSON.stringify(payload);
+  }
+
+  private parseCursor(cursor: string | undefined): SyncPullCursorState | null {
+    if (!cursor) {
+      return null;
+    }
+
+    let decodedCursor: unknown;
+    try {
+      decodedCursor = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+    } catch {
+      throw new BadRequestException("Invalid sync cursor");
+    }
+
+    if (typeof decodedCursor !== "object" || decodedCursor === null) {
+      throw new BadRequestException("Invalid sync cursor");
+    }
+
+    const cursorRecord = decodedCursor as {
+      serverTs?: unknown;
+      opId?: unknown;
+    };
+
+    if (
+      typeof cursorRecord.serverTs !== "string" ||
+      typeof cursorRecord.opId !== "string" ||
+      Number.isNaN(Date.parse(cursorRecord.serverTs)) ||
+      cursorRecord.opId.trim().length === 0
+    ) {
+      throw new BadRequestException("Invalid sync cursor");
+    }
+
+    return {
+      serverTs: cursorRecord.serverTs,
+      opId: cursorRecord.opId
+    };
+  }
+
+  private encodeCursor(cursor: SyncPullCursorState): string {
+    return Buffer.from(JSON.stringify(cursor), "utf8").toString("base64url");
+  }
+
+  private isDuplicateOpIdError(error: unknown): boolean {
+    if (!(error instanceof Prisma.PrismaClientKnownRequestError)) {
+      return false;
+    }
+
+    return error.code === "P2002";
+  }
+}

apps/api/src/task/task.service.ts

@@ -75,7 +75,7 @@ export class TaskService {
     ]);
 
     return {
-      items: items.map((item) => this.serializeTask(item)),
+      items: items.map((item: TaskEntity) => this.serializeTask(item)),
       page,
       pageSize,
       total
@@ -363,7 +363,7 @@ export class TaskService {
     );
 
     await tx.taskTag.createMany({
-      data: tags.map((tag) => ({
+      data: tags.map((tag: { id: string }) => ({
         taskId,
         tagId: tag.id
       })),
@@ -382,7 +382,7 @@ export class TaskService {
       ddl: task.ddl?.toISOString() ?? null,
       completedAt: task.completedAt?.toISOString() ?? null,
       version: task.version,
-      tags: task.taskTags.map((taskTag) => taskTag.tag.name),
+      tags: task.taskTags.map((taskTag: { tag: { name: string } }) => taskTag.tag.name),
       createdAt: task.createdAt.toISOString(),
       updatedAt: task.updatedAt.toISOString()
     };

apps/api/test/sync-push.spec.ts

@@ -0,0 +1,419 @@
+import request from "supertest";
+import { INestApplication, ValidationPipe } from "@nestjs/common";
+import { Test, TestingModule } from "@nestjs/testing";
+import { PrismaService } from "../src/prisma/prisma.service";
+import { SyncController } from "../src/sync/sync.controller";
+import { SyncService } from "../src/sync/sync.service";
+
+type SyncOperationRecord = {
+  id: string;
+  opId: string;
+  userId: string;
+  deviceId: string;
+  entityType: string;
+  entityId: string;
+  action: string;
+  payload: string | null;
+  clientTs: Date;
+  serverTs: Date;
+};
+
+type SyncOperationSelect = {
+  opId?: true;
+  entityId?: true;
+  entityType?: true;
+  action?: true;
+  payload?: true;
+  clientTs?: true;
+  deviceId?: true;
+  serverTs?: true;
+};
+
+type SyncOperationFindManyArgs = {
+  where: {
+    userId: string;
+    opId?: {
+      in: string[];
+    };
+    OR?: Array<
+      | {
+          serverTs: {
+            gt: Date;
+          };
+        }
+      | {
+          serverTs: Date;
+          opId: {
+            gt: string;
+          };
+        }
+    >;
+  };
+  select: SyncOperationSelect;
+  orderBy?: Array<{
+    serverTs?: "asc" | "desc";
+    opId?: "asc" | "desc";
+  }>;
+  take?: number;
+};
+
+type SyncOperationCreateArgs = {
+  data: {
+    opId: string;
+    userId: string;
+    deviceId: string;
+    entityType: string;
+    entityId: string;
+    action: string;
+    payload?: string;
+    clientTs: Date;
+  };
+  select: {
+    opId: true;
+    serverTs: true;
+  };
+};
+
+class InMemoryPrismaService {
+  private syncOperationIdSequence = 1;
+  private syncOperations: SyncOperationRecord[] = [];
+
+  readonly syncOperation = {
+    findMany: async (args: SyncOperationFindManyArgs) => {
+      let items = this.syncOperations.filter((item) => item.userId === args.where.userId);
+
+      if (args.where.opId?.in) {
+        items = items.filter((item) => args.where.opId?.in.includes(item.opId));
+      }
+
+      if (args.where.OR && args.where.OR.length > 0) {
+        items = items.filter((item) =>
+          args.where.OR?.some((condition) => {
+            if ("gt" in condition.serverTs) {
+              return item.serverTs.getTime() > condition.serverTs.gt.getTime();
+            }
+
+            if ("opId" in condition) {
+              return (
+                item.serverTs.getTime() === condition.serverTs.getTime() &&
+                item.opId > condition.opId.gt
+              );
+            }
+
+            return false;
+          })
+        );
+      }
+
+      if (args.orderBy && args.orderBy.length > 0) {
+        items = [...items].sort((left, right) => {
+          for (const orderRule of args.orderBy ?? []) {
+            if (orderRule.serverTs) {
+              const diff = left.serverTs.getTime() - right.serverTs.getTime();
+              if (diff !== 0) {
+                return orderRule.serverTs === "asc" ? diff : -diff;
+              }
+            }
+
+            if (orderRule.opId) {
+              const diff = left.opId.localeCompare(right.opId);
+              if (diff !== 0) {
+                return orderRule.opId === "asc" ? diff : -diff;
+              }
+            }
+          }
+
+          return 0;
+        });
+      }
+
+      const limitedItems = args.take ? items.slice(0, args.take) : items;
+
+      return limitedItems.map((item) => this.pickSelectedFields(item, args.select));
+    },
+
+    create: async (args: SyncOperationCreateArgs) => {
+      const createdOperation: SyncOperationRecord = {
+        id: `sync_${this.syncOperationIdSequence++}`,
+        opId: args.data.opId,
+        userId: args.data.userId,
+        deviceId: args.data.deviceId,
+        entityType: args.data.entityType,
+        entityId: args.data.entityId,
+        action: args.data.action,
+        payload: args.data.payload ?? null,
+        clientTs: args.data.clientTs,
+        serverTs: new Date()
+      };
+
+      this.syncOperations.push(createdOperation);
+
+      return {
+        opId: createdOperation.opId,
+        serverTs: createdOperation.serverTs
+      };
+    }
+  };
+
+  getOperationCount(): number {
+    return this.syncOperations.length;
+  }
+
+  seedOperations(records: Array<Omit<SyncOperationRecord, "id">>): void {
+    for (const record of records) {
+      this.syncOperations.push({
+        ...record,
+        id: `sync_${this.syncOperationIdSequence++}`
+      });
+    }
+  }
+
+  private pickSelectedFields(
+    item: SyncOperationRecord,
+    select: SyncOperationSelect
+  ): Partial<SyncOperationRecord> {
+    const result: Record<string, unknown> = {};
+
+    for (const key of Object.keys(select) as Array<keyof SyncOperationSelect>) {
+      if (!select[key]) {
+        continue;
+      }
+
+      const recordKey = key as keyof SyncOperationRecord;
+      result[recordKey] = item[recordKey];
+    }
+
+    return result as Partial<SyncOperationRecord>;
+  }
+}
+
+describe("SyncController (integration)", () => {
+  let app: INestApplication;
+  let prismaService: InMemoryPrismaService;
+
+  beforeAll(async () => {
+    prismaService = new InMemoryPrismaService();
+
+    const moduleRef: TestingModule = await Test.createTestingModule({
+      controllers: [SyncController],
+      providers: [SyncService, { provide: PrismaService, useValue: prismaService }]
+    }).compile();
+
+    app = moduleRef.createNestApplication();
+    app.useGlobalPipes(
+      new ValidationPipe({
+        transform: true,
+        whitelist: true,
+        forbidNonWhitelisted: true
+      })
+    );
+    await app.init();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  it("should accept operations once and mark repeated push as duplicate", async () => {
+    const payload = {
+      operations: [
+        {
+          opId: "op-create-1",
+          entityType: "TASK",
+          entityId: "task-1",
+          action: "CREATE",
+          payload: '{"title":"任务一"}',
+          clientTs: 1712419200000,
+          deviceId: "device-a"
+        },
+        {
+          opId: "op-update-1",
+          entityType: "TASK",
+          entityId: "task-1",
+          action: "UPDATE",
+          payload: '{"title":"任务一-更新"}',
+          clientTs: 1712419201000,
+          deviceId: "device-a"
+        }
+      ]
+    };
+
+    const firstResponse = await request(app.getHttpServer())
+      .post("/sync/push")
+      .set("x-user-id", "user-1")
+      .send(payload)
+      .expect(201);
+
+    expect(firstResponse.body.acceptedCount).toBe(2);
+    expect(firstResponse.body.duplicateCount).toBe(0);
+    expect(firstResponse.body.failedCount).toBe(0);
+    expect(firstResponse.body.results).toEqual([
+      expect.objectContaining({
+        opId: "op-create-1",
+        status: "accepted"
+      }),
+      expect.objectContaining({
+        opId: "op-update-1",
+        status: "accepted"
+      })
+    ]);
+    expect(prismaService.getOperationCount()).toBe(2);
+
+    const secondResponse = await request(app.getHttpServer())
+      .post("/sync/push")
+      .set("x-user-id", "user-1")
+      .send(payload)
+      .expect(201);
+
+    expect(secondResponse.body.acceptedCount).toBe(0);
+    expect(secondResponse.body.duplicateCount).toBe(2);
+    expect(secondResponse.body.failedCount).toBe(0);
+    expect(secondResponse.body.results).toEqual([
+      expect.objectContaining({
+        opId: "op-create-1",
+        status: "duplicate",
+        reason: "already_synced"
+      }),
+      expect.objectContaining({
+        opId: "op-update-1",
+        status: "duplicate",
+        reason: "already_synced"
+      })
+    ]);
+    expect(prismaService.getOperationCount()).toBe(2);
+  });
+
+  it("should mark duplicated op ids in the same batch as duplicate", async () => {
+    const response = await request(app.getHttpServer())
+      .post("/sync/push")
+      .set("x-user-id", "user-2")
+      .send({
+        operations: [
+          {
+            opId: "op-dup-1",
+            entityType: "TASK",
+            entityId: "task-2",
+            action: "CREATE",
+            payload: '{"title":"任务二"}',
+            clientTs: 1712419300000,
+            deviceId: "device-b"
+          },
+          {
+            opId: "op-dup-1",
+            entityType: "TASK",
+            entityId: "task-2",
+            action: "UPDATE",
+            payload: '{"title":"任务二-重复"}',
+            clientTs: 1712419301000,
+            deviceId: "device-b"
+          }
+        ]
+      })
+      .expect(201);
+
+    expect(response.body.acceptedCount).toBe(1);
+    expect(response.body.duplicateCount).toBe(1);
+    expect(response.body.failedCount).toBe(0);
+    expect(response.body.results[0]).toEqual(
+      expect.objectContaining({
+        opId: "op-dup-1",
+        status: "accepted"
+      })
+    );
+    expect(response.body.results[1]).toEqual(
+      expect.objectContaining({
+        opId: "op-dup-1",
+        status: "duplicate",
+        reason: "same_batch_duplicate"
+      })
+    );
+    expect(prismaService.getOperationCount()).toBe(3);
+  });
+
+  it("should pull operations incrementally with a stable cursor", async () => {
+    prismaService.seedOperations([
+      {
+        opId: "pull-op-1",
+        userId: "user-pull",
+        deviceId: "device-c",
+        entityType: "TASK",
+        entityId: "task-10",
+        action: "CREATE",
+        payload: '{"title":"任务甲"}',
+        clientTs: new Date("2026-04-06T10:00:00.000Z"),
+        serverTs: new Date("2026-04-06T10:10:00.000Z")
+      },
+      {
+        opId: "pull-op-2",
+        userId: "user-pull",
+        deviceId: "device-c",
+        entityType: "TASK",
+        entityId: "task-10",
+        action: "UPDATE",
+        payload: '{"title":"任务甲-更新"}',
+        clientTs: new Date("2026-04-06T10:01:00.000Z"),
+        serverTs: new Date("2026-04-06T10:10:00.000Z")
+      },
+      {
+        opId: "pull-op-3",
+        userId: "user-pull",
+        deviceId: "device-c",
+        entityType: "TASK",
+        entityId: "task-11",
+        action: "CREATE",
+        payload: '{"title":"任务乙"}',
+        clientTs: new Date("2026-04-06T10:02:00.000Z"),
+        serverTs: new Date("2026-04-06T10:11:00.000Z")
+      },
+      {
+        opId: "pull-op-other-user",
+        userId: "user-other",
+        deviceId: "device-z",
+        entityType: "TASK",
+        entityId: "task-99",
+        action: "CREATE",
+        payload: '{"title":"其他用户任务"}',
+        clientTs: new Date("2026-04-06T10:03:00.000Z"),
+        serverTs: new Date("2026-04-06T10:12:00.000Z")
+      }
+    ]);
+
+    const firstResponse = await request(app.getHttpServer())
+      .get("/sync/pull")
+      .set("x-user-id", "user-pull")
+      .query({ limit: 2 })
+      .expect(200);
+
+    expect(firstResponse.body.items.map((item: { opId: string }) => item.opId)).toEqual([
+      "pull-op-1",
+      "pull-op-2"
+    ]);
+    expect(firstResponse.body.hasMore).toBe(true);
+    expect(firstResponse.body.nextCursor).toEqual(expect.any(String));
+
+    const secondResponse = await request(app.getHttpServer())
+      .get("/sync/pull")
+      .set("x-user-id", "user-pull")
+      .query({
+        limit: 2,
+        cursor: firstResponse.body.nextCursor
+      })
+      .expect(200);
+
+    expect(secondResponse.body.items.map((item: { opId: string }) => item.opId)).toEqual([
+      "pull-op-3"
+    ]);
+    expect(secondResponse.body.hasMore).toBe(false);
+    expect(secondResponse.body.nextCursor).toEqual(expect.any(String));
+  });
+
+  it("should reject invalid cursor payload", async () => {
+    await request(app.getHttpServer())
+      .get("/sync/pull")
+      .set("x-user-id", "user-invalid-cursor")
+      .query({
+        cursor: "not-a-valid-cursor"
+      })
+      .expect(400);
+  });
+});

apps/web/src/components/task-rich-editor.tsx

@@ -1,9 +1,9 @@
-import { useEffect, useRef, useState, type ChangeEvent } from "react";
+import { memo, useEffect, useRef, useState, type ChangeEvent } from "react";
 import imageCompression from "browser-image-compression";
 import type { Editor as TiptapEditor } from "@tiptap/core";
 import Link from "@tiptap/extension-link";
 import StarterKit from "@tiptap/starter-kit";
-import { EditorContent, type JSONContent, useEditor } from "@tiptap/react";
+import { EditorContent, type JSONContent, useEditor, useEditorState } from "@tiptap/react";
 import { ResizableImage } from "@/extensions/resizable-image";
 import { ResizableVideo } from "@/extensions/resizable-video";
 import { ResizableYoutube } from "@/extensions/resizable-youtube";
@@ -11,6 +11,7 @@ import { cn } from "@/lib/utils";
 
 const MAX_IMAGE_UPLOAD_BYTES = 20 * 1024 * 1024;
 const MAX_VIDEO_UPLOAD_BYTES = 10 * 1024 * 1024;
+const EDITOR_CHANGE_DEBOUNCE_MS = 120;
 
 type TaskRichEditorProps = {
   valueJson: string | null;
@@ -25,7 +26,37 @@ type ToolbarButtonProps = {
   onClick: () => void;
 };
 
-function ToolbarButton({ label, disabled = false, active = false, onClick }: ToolbarButtonProps) {
+type ToolbarState = {
+  bold: boolean;
+  italic: boolean;
+  heading: boolean;
+  bulletList: boolean;
+  link: boolean;
+};
+
+type EditorToolbarProps = {
+  editor: TiptapEditor | null;
+  onInsertImageUrl: () => void;
+  onOpenImageUpload: () => void;
+  onInsertVideoUrl: () => void;
+  onOpenVideoUpload: () => void;
+  onSetLink: () => void;
+};
+
+const DEFAULT_TOOLBAR_STATE: ToolbarState = {
+  bold: false,
+  italic: false,
+  heading: false,
+  bulletList: false,
+  link: false
+};
+
+const ToolbarButton = memo(function ToolbarButton({
+  label,
+  disabled = false,
+  active = false,
+  onClick
+}: ToolbarButtonProps) {
   return (
     <button
       type="button"
@@ -42,8 +73,84 @@ function ToolbarButton({ label, disabled = false, active = false, onClick }: Too
       {label}
     </button>
   );
+});
+
+const EditorToolbar = memo(function EditorToolbar({
+  editor,
+  onInsertImageUrl,
+  onOpenImageUpload,
+  onInsertVideoUrl,
+  onOpenVideoUpload,
+  onSetLink
+}: EditorToolbarProps) {
+  const toolbarState =
+    useEditorState({
+      editor,
+      selector: ({ editor: currentEditor }) => {
+        if (!currentEditor) {
+          return DEFAULT_TOOLBAR_STATE;
         }
 
+        return {
+          bold: currentEditor.isActive("bold"),
+          italic: currentEditor.isActive("italic"),
+          heading: currentEditor.isActive("heading", { level: 2 }),
+          bulletList: currentEditor.isActive("bulletList"),
+          link: currentEditor.isActive("link")
+        };
+      }
+    }) ?? DEFAULT_TOOLBAR_STATE;
+
+  const disabled = !editor;
+
+  return (
+    <div className="flex flex-wrap gap-1 rounded-t-lg border border-input border-b-0 bg-muted/30 px-2 py-2">
+      <ToolbarButton
+        label={"\u7c97\u4f53"}
+        disabled={disabled}
+        active={toolbarState.bold}
+        onClick={() => editor?.chain().focus().toggleBold().run()}
+      />
+      <ToolbarButton
+        label={"\u659c\u4f53"}
+        disabled={disabled}
+        active={toolbarState.italic}
+        onClick={() => editor?.chain().focus().toggleItalic().run()}
+      />
+      <ToolbarButton
+        label={"\u6807\u9898"}
+        disabled={disabled}
+        active={toolbarState.heading}
+        onClick={() => editor?.chain().focus().toggleHeading({ level: 2 }).run()}
+      />
+      <ToolbarButton
+        label={"\u65e0\u5e8f\u5217\u8868"}
+        disabled={disabled}
+        active={toolbarState.bulletList}
+        onClick={() => editor?.chain().focus().toggleBulletList().run()}
+      />
+      <ToolbarButton
+        label={"\u94fe\u63a5"}
+        disabled={disabled}
+        active={toolbarState.link}
+        onClick={onSetLink}
+      />
+      <ToolbarButton label={"\u56fe\u7247 URL"} disabled={disabled} onClick={onInsertImageUrl} />
+      <ToolbarButton
+        label={"\u4e0a\u4f20\u56fe\u7247"}
+        disabled={disabled}
+        onClick={onOpenImageUpload}
+      />
+      <ToolbarButton label={"\u89c6\u9891 URL"} disabled={disabled} onClick={onInsertVideoUrl} />
+      <ToolbarButton
+        label={"\u4e0a\u4f20\u89c6\u9891"}
+        disabled={disabled}
+        onClick={onOpenVideoUpload}
+      />
+    </div>
+  );
+});
+
 function resolveEditorContent(
   valueJson: string | null,
   textFallback: string
@@ -155,10 +262,55 @@ function removeMediaByUploadToken(editor: TiptapEditor, uploadToken: string): bo
   });
 }
 
-export function TaskRichEditor({ valueJson, textFallback, onChange }: TaskRichEditorProps) {
+export const TaskRichEditor = memo(function TaskRichEditor({
+  valueJson,
+  textFallback,
+  onChange
+}: TaskRichEditorProps) {
   const [mediaHint, setMediaHint] = useState<string | null>(null);
   const imageInputRef = useRef<HTMLInputElement | null>(null);
   const videoInputRef = useRef<HTMLInputElement | null>(null);
+  const changeTimeoutRef = useRef<number | null>(null);
+  const latestOnChangeRef = useRef(onChange);
+  const lastSyncedPayloadRef = useRef<{
+    json: string | null;
+    text: string;
+  }>({
+    json: valueJson,
+    text: textFallback
+  });
+
+  useEffect(() => {
+    latestOnChangeRef.current = onChange;
+  }, [onChange]);
+
+  function flushEditorChange(currentEditor: TiptapEditor): void {
+    const nextPayload = {
+      json: JSON.stringify(currentEditor.getJSON()),
+      text: currentEditor.getText()
+    };
+
+    if (
+      nextPayload.json === lastSyncedPayloadRef.current.json &&
+      nextPayload.text === lastSyncedPayloadRef.current.text
+    ) {
+      return;
+    }
+
+    lastSyncedPayloadRef.current = nextPayload;
+    latestOnChangeRef.current(nextPayload);
+  }
+
+  function scheduleEditorChange(currentEditor: TiptapEditor): void {
+    if (changeTimeoutRef.current !== null) {
+      window.clearTimeout(changeTimeoutRef.current);
+    }
+
+    changeTimeoutRef.current = window.setTimeout(() => {
+      flushEditorChange(currentEditor);
+      changeTimeoutRef.current = null;
+    }, EDITOR_CHANGE_DEBOUNCE_MS);
+  }
 
   const editor = useEditor({
     extensions: [
@@ -185,10 +337,17 @@ export function TaskRichEditor({ valueJson, textFallback, onChange }: TaskRichEd
           "min-h-40 rounded-b-lg border border-t-0 border-input bg-background px-3 py-2 text-sm text-foreground outline-none"
       }
     },
+    shouldRerenderOnTransaction: false,
     onUpdate({ editor: currentEditor }) {
-      const nextJson = JSON.stringify(currentEditor.getJSON());
+      scheduleEditorChange(currentEditor);
-      const nextText = currentEditor.getText();
+    },
-      onChange({ json: nextJson, text: nextText });
+    onBlur({ editor: currentEditor }) {
+      if (changeTimeoutRef.current !== null) {
+        window.clearTimeout(changeTimeoutRef.current);
+        changeTimeoutRef.current = null;
+      }
+
+      flushEditorChange(currentEditor);
     }
   });
 
@@ -197,6 +356,18 @@ export function TaskRichEditor({ valueJson, textFallback, onChange }: TaskRichEd
       return;
     }
 
+    if (
+      valueJson === lastSyncedPayloadRef.current.json &&
+      textFallback === lastSyncedPayloadRef.current.text
+    ) {
+      return;
+    }
+
+    if (changeTimeoutRef.current !== null) {
+      window.clearTimeout(changeTimeoutRef.current);
+      changeTimeoutRef.current = null;
+    }
+
     if (valueJson) {
       const nextJson = parseEditorJson(valueJson);
 
@@ -207,21 +378,32 @@ export function TaskRichEditor({ valueJson, textFallback, onChange }: TaskRichEd
         return;
       }
 
-      if (JSON.stringify(editor.getJSON()) === JSON.stringify(nextJson)) {
-        return;
-      }
-
       editor.commands.setContent(nextJson, { emitUpdate: false });
+      lastSyncedPayloadRef.current = {
+        json: valueJson,
+        text: textFallback
+      };
       return;
     }
 
-    if (editor.getText() === textFallback) {
+    if (editor.getText() !== textFallback) {
-      return;
-    }
-
       editor.commands.setContent(textFallback, { emitUpdate: false });
+    }
+
+    lastSyncedPayloadRef.current = {
+      json: valueJson,
+      text: textFallback
+    };
   }, [editor, textFallback, valueJson]);
 
+  useEffect(() => {
+    return () => {
+      if (changeTimeoutRef.current !== null) {
+        window.clearTimeout(changeTimeoutRef.current);
+      }
+    };
+  }, []);
+
   async function handleImageFileChange(event: ChangeEvent<HTMLInputElement>): Promise<void> {
     const file = event.target.files?.[0];
     event.target.value = "";
@@ -399,41 +581,18 @@ export function TaskRichEditor({ valueJson, textFallback, onChange }: TaskRichEd
         onChange={handleVideoFileChange}
       />
 
-      <div className="flex flex-wrap gap-1 rounded-t-lg border border-input border-b-0 bg-muted/30 px-2 py-2">
+      <EditorToolbar
-        <ToolbarButton
+        editor={editor}
-          label="粗体"
+        onInsertImageUrl={handleInsertImageUrl}
-          disabled={!editor}
+        onOpenImageUpload={() => imageInputRef.current?.click()}
-          active={editor?.isActive("bold")}
+        onInsertVideoUrl={handleInsertVideoUrl}
-          onClick={() => editor?.chain().focus().toggleBold().run()}
+        onOpenVideoUpload={() => videoInputRef.current?.click()}
-        />
+        onSetLink={() => {
-        <ToolbarButton
-          label="斜体"
-          disabled={!editor}
-          active={editor?.isActive("italic")}
-          onClick={() => editor?.chain().focus().toggleItalic().run()}
-        />
-        <ToolbarButton
-          label="标题"
-          disabled={!editor}
-          active={editor?.isActive("heading", { level: 2 })}
-          onClick={() => editor?.chain().focus().toggleHeading({ level: 2 }).run()}
-        />
-        <ToolbarButton
-          label="无序列表"
-          disabled={!editor}
-          active={editor?.isActive("bulletList")}
-          onClick={() => editor?.chain().focus().toggleBulletList().run()}
-        />
-        <ToolbarButton
-          label="链接"
-          disabled={!editor}
-          active={editor?.isActive("link")}
-          onClick={() => {
           if (!editor) {
             return;
           }
 
-            const url = window.prompt("请输入链接地址");
+          const url = window.prompt("\u8bf7\u8f93\u5165\u94fe\u63a5\u5730\u5740");
 
           if (!url) {
             return;
@@ -442,21 +601,8 @@ export function TaskRichEditor({ valueJson, textFallback, onChange }: TaskRichEd
           editor.chain().focus().setLink({ href: url }).run();
         }}
       />
-        <ToolbarButton label="图片 URL" disabled={!editor} onClick={handleInsertImageUrl} />
-        <ToolbarButton
-          label="上传图片"
-          disabled={!editor}
-          onClick={() => imageInputRef.current?.click()}
-        />
-        <ToolbarButton label="视频 URL" disabled={!editor} onClick={handleInsertVideoUrl} />
-        <ToolbarButton
-          label="上传视频"
-          disabled={!editor}
-          onClick={() => videoInputRef.current?.click()}
-        />
-      </div>
       <EditorContent editor={editor} />
       {mediaHint ? <p className="mt-2 text-xs text-muted-foreground">{mediaHint}</p> : null}
     </div>
   );
-}
+});

apps/web/src/hooks/use-sync-engine.ts

@@ -0,0 +1,296 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useLiveQuery } from "dexie-react-hooks";
+import {
+  countBlockedSyncOperations,
+  countPendingRemoteOperations,
+  countPendingSyncOperations,
+  getLocalSyncState
+} from "@/services/local-sync-repo";
+import type { WebSession } from "@/services/session-storage";
+import { applyPendingRemoteOperations } from "@/services/sync-merge";
+import { runSyncWorkerCycle } from "@/services/sync-worker";
+
+const PERIODIC_SYNC_INTERVAL_MS = 30_000;
+const MAX_RETRY_DELAY_MS = 60_000;
+const BASE_RETRY_DELAY_MS = 2_000;
+
+export type SyncEngineStatus = {
+  isOnline: boolean;
+  phase: "idle" | "syncing" | "offline" | "backoff" | "attention";
+  pendingCount: number;
+  blockedCount: number;
+  pendingRemoteCount: number;
+  lastSyncedAt: number | null;
+  nextRetryAt: number | null;
+  lastError: string | null;
+};
+
+function getErrorMessage(error: unknown): string {
+  if (error instanceof Error && error.message.trim()) {
+    return error.message;
+  }
+
+  return "同步失败，请稍后重试";
+}
+
+function calculateRetryDelay(attempt: number): number {
+  return Math.min(BASE_RETRY_DELAY_MS * 2 ** Math.max(attempt - 1, 0), MAX_RETRY_DELAY_MS);
+}
+
+export function useSyncEngine(session: WebSession | null): {
+  status: SyncEngineStatus;
+  triggerSync: () => void;
+} {
+  const userId = session?.user.id ?? "";
+  const pendingCount = useLiveQuery(async () => countPendingSyncOperations(), [userId]) ?? 0;
+  const blockedCount = useLiveQuery(async () => countBlockedSyncOperations(), [userId]) ?? 0;
+  const pendingRemoteCount =
+    useLiveQuery(async () => {
+      if (!userId) {
+        return 0;
+      }
+
+      return countPendingRemoteOperations(userId);
+    }, [userId]) ?? 0;
+  const storedSyncState =
+    useLiveQuery(async () => {
+      if (!userId) {
+        return null;
+      }
+
+      return getLocalSyncState(userId);
+    }, [userId]) ?? null;
+
+  const [isOnline, setIsOnline] = useState(() => window.navigator.onLine);
+  const [phase, setPhase] = useState<SyncEngineStatus["phase"]>(
+    window.navigator.onLine ? "idle" : "offline"
+  );
+  const [lastError, setLastError] = useState<string | null>(null);
+  const [nextRetryAt, setNextRetryAt] = useState<number | null>(null);
+  const [lastSyncedAt, setLastSyncedAt] = useState<number | null>(null);
+
+  const retryAttemptRef = useRef(0);
+  const runningRef = useRef(false);
+  const mergeRunningRef = useRef(false);
+
+  useEffect(() => {
+    setLastSyncedAt(storedSyncState?.lastSyncedAt ?? null);
+  }, [storedSyncState]);
+
+  const runCycle = useCallback(async () => {
+    if (!userId || runningRef.current || !window.navigator.onLine) {
+      return;
+    }
+
+    runningRef.current = true;
+    setPhase("syncing");
+    setLastError(null);
+    setNextRetryAt(null);
+
+    try {
+      const result = await runSyncWorkerCycle(userId);
+      retryAttemptRef.current = 0;
+      setLastSyncedAt(result.lastSyncedAt);
+
+      if (result.hasFailures) {
+        const nextAttempt = retryAttemptRef.current + 1;
+        retryAttemptRef.current = nextAttempt;
+        const delay = calculateRetryDelay(nextAttempt);
+        setLastError(result.failureMessage ?? "同步失败");
+        setNextRetryAt(Date.now() + delay);
+        setPhase("backoff");
+        return;
+      }
+
+      setPhase(blockedCount > 0 ? "attention" : "idle");
+    } catch (error) {
+      const nextAttempt = retryAttemptRef.current + 1;
+      retryAttemptRef.current = nextAttempt;
+      const delay = calculateRetryDelay(nextAttempt);
+      setLastError(getErrorMessage(error));
+      setNextRetryAt(Date.now() + delay);
+      setPhase("backoff");
+    } finally {
+      runningRef.current = false;
+    }
+  }, [blockedCount, userId]);
+
+  const triggerSync = useCallback(() => {
+    void runCycle();
+  }, [runCycle]);
+
+  const runMerge = useCallback(async () => {
+    if (!userId || mergeRunningRef.current) {
+      return;
+    }
+
+    mergeRunningRef.current = true;
+
+    try {
+      await applyPendingRemoteOperations(userId);
+
+      if (!runningRef.current) {
+        setPhase((currentPhase) => {
+          if (!window.navigator.onLine) {
+            return "offline";
+          }
+
+          if (currentPhase === "backoff") {
+            return currentPhase;
+          }
+
+          return blockedCount > 0 ? "attention" : "idle";
+        });
+      }
+    } catch (error) {
+      setLastError(getErrorMessage(error));
+      setPhase("attention");
+    } finally {
+      mergeRunningRef.current = false;
+    }
+  }, [blockedCount, userId]);
+
+  useEffect(() => {
+    function handleOnline(): void {
+      setIsOnline(true);
+      setPhase(blockedCount > 0 ? "attention" : "idle");
+      void runCycle();
+    }
+
+    function handleOffline(): void {
+      setIsOnline(false);
+      setNextRetryAt(null);
+      setPhase("offline");
+    }
+
+    function handleVisibilityChange(): void {
+      if (document.visibilityState === "visible" && window.navigator.onLine) {
+        void runCycle();
+      }
+    }
+
+    window.addEventListener("online", handleOnline);
+    window.addEventListener("offline", handleOffline);
+    document.addEventListener("visibilitychange", handleVisibilityChange);
+
+    return () => {
+      window.removeEventListener("online", handleOnline);
+      window.removeEventListener("offline", handleOffline);
+      document.removeEventListener("visibilitychange", handleVisibilityChange);
+    };
+  }, [blockedCount, runCycle]);
+
+  useEffect(() => {
+    if (!userId || !isOnline) {
+      return;
+    }
+
+    if (pendingCount === 0 && pendingRemoteCount === 0) {
+      return;
+    }
+
+    void runCycle();
+  }, [isOnline, pendingCount, pendingRemoteCount, runCycle, userId]);
+
+  useEffect(() => {
+    if (!userId || !isOnline) {
+      return;
+    }
+
+    const intervalId = window.setInterval(() => {
+      void runCycle();
+    }, PERIODIC_SYNC_INTERVAL_MS);
+
+    return () => {
+      window.clearInterval(intervalId);
+    };
+  }, [isOnline, runCycle, userId]);
+
+  useEffect(() => {
+    if (!nextRetryAt || !isOnline) {
+      return;
+    }
+
+    const timeoutId = window.setTimeout(
+      () => {
+        void runCycle();
+      },
+      Math.max(nextRetryAt - Date.now(), 0)
+    );
+
+    return () => {
+      window.clearTimeout(timeoutId);
+    };
+  }, [isOnline, nextRetryAt, runCycle]);
+
+  useEffect(() => {
+    if (!userId || pendingRemoteCount === 0 || runningRef.current) {
+      return;
+    }
+
+    void runMerge();
+  }, [pendingRemoteCount, runMerge, userId]);
+
+  useEffect(() => {
+    if (!userId) {
+      setLastError(null);
+      setLastSyncedAt(null);
+      setNextRetryAt(null);
+      setPhase(window.navigator.onLine ? "idle" : "offline");
+      retryAttemptRef.current = 0;
+    }
+  }, [userId]);
+
+  const status = useMemo<SyncEngineStatus>(() => {
+    if (!isOnline) {
+      return {
+        isOnline,
+        phase: "offline",
+        pendingCount,
+        blockedCount,
+        pendingRemoteCount,
+        lastSyncedAt,
+        nextRetryAt: null,
+        lastError
+      };
+    }
+
+    if (blockedCount > 0 && phase !== "syncing") {
+      return {
+        isOnline,
+        phase: "attention",
+        pendingCount,
+        blockedCount,
+        pendingRemoteCount,
+        lastSyncedAt,
+        nextRetryAt,
+        lastError
+      };
+    }
+
+    return {
+      isOnline,
+      phase,
+      pendingCount,
+      blockedCount,
+      pendingRemoteCount,
+      lastSyncedAt,
+      nextRetryAt,
+      lastError
+    };
+  }, [
+    blockedCount,
+    isOnline,
+    lastError,
+    lastSyncedAt,
+    nextRetryAt,
+    pendingCount,
+    pendingRemoteCount,
+    phase
+  ]);
+
+  return {
+    status,
+    triggerSync
+  };
+}

apps/web/src/pages/todo-shell-page.tsx

@@ -1,6 +1,14 @@
-import { useCallback, useEffect, useRef, useState } from "react";
+import { memo, useCallback, useEffect, useRef, useState } from "react";
 import { useLiveQuery } from "dexie-react-hooks";
-import { CheckCircle2, CircleAlert } from "lucide-react";
+import {
+  CheckCircle2,
+  CircleAlert,
+  CloudOff,
+  LoaderCircle,
+  RefreshCw,
+  ServerCrash
+} from "lucide-react";
+import { useSyncEngine, type SyncEngineStatus } from "@/hooks/use-sync-engine";
 import { TaskRichEditor } from "@/components/task-rich-editor";
 import { Button } from "@/components/ui/button";
 import { cn } from "@/lib/utils";
@@ -31,27 +39,37 @@ type TodoShellPageProps = {
 
 type TaskFormState = {
   title: string;
-  contentJson: string | null;
-  contentText: string;
   priority: LocalTaskPriority;
   status: LocalTaskStatus;
   ddlInput: string;
 };
 
+type TaskEditorState = {
+  contentJson: string | null;
+  contentText: string;
+};
+
 type FeedbackNotice = {
   message: string;
   tone: "success" | "error";
 };
 
+type StorageQuotaSnapshot = Awaited<ReturnType<typeof getStorageQuotaSnapshot>>;
+
+const DRAFT_PERSIST_DEBOUNCE_MS = 500;
+
 const DEFAULT_FORM_STATE: TaskFormState = {
   title: "",
-  contentJson: null,
-  contentText: "",
   priority: "MEDIUM",
   status: "TODO",
   ddlInput: ""
 };
 
+const DEFAULT_EDITOR_STATE: TaskEditorState = {
+  contentJson: null,
+  contentText: ""
+};
+
 const PRIORITY_OPTIONS: Array<{ value: LocalTaskPriority; label: string }> = [
   { value: "LOW", label: "低" },
   { value: "MEDIUM", label: "中" },
@@ -115,29 +133,412 @@ function formatUpdatedAt(timestamp: number): string {
 function createFormStateFromTask(task: LocalTaskRecord): TaskFormState {
   return {
     title: task.title,
-    contentJson: task.contentJson,
-    contentText: task.contentText ?? "",
     priority: task.priority,
     status: task.status,
     ddlInput: toDatetimeLocalValue(task.ddlAt)
   };
 }
 
+function createEditorStateFromTask(task: LocalTaskRecord): TaskEditorState {
+  return {
+    contentJson: task.contentJson,
+    contentText: task.contentText ?? ""
+  };
+}
+
 function createFormStateFromDraft(draft: LocalTaskDraftRecord): TaskFormState {
   return {
     title: draft.title,
-    contentJson: draft.contentJson,
-    contentText: draft.contentText,
     priority: draft.priority,
     status: draft.status,
     ddlInput: draft.ddlInput
   };
 }
 
-function serializeFormState(formState: TaskFormState): string {
+function createEditorStateFromDraft(draft: LocalTaskDraftRecord): TaskEditorState {
-  return JSON.stringify(formState);
+  return {
+    contentJson: draft.contentJson,
+    contentText: draft.contentText
+  };
 }
 
+function serializeFormState(formState: TaskFormState, editorState: TaskEditorState): string {
+  return JSON.stringify({
+    ...formState,
+    ...editorState
+  });
+}
+
+function formatSyncTimestamp(timestamp: number | null): string {
+  if (timestamp === null) {
+    return "尚未完成同步";
+  }
+
+  return new Date(timestamp).toLocaleString("zh-CN", {
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit"
+  });
+}
+
+function formatRetryTime(timestamp: number | null): string {
+  if (timestamp === null) {
+    return "稍后";
+  }
+
+  return new Date(timestamp).toLocaleTimeString("zh-CN", {
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit"
+  });
+}
+
+function getSyncSummary(status: SyncEngineStatus): {
+  title: string;
+  description: string;
+  accentClassName: string;
+  icon: typeof RefreshCw;
+  iconClassName: string;
+} {
+  if (status.phase === "offline") {
+    return {
+      title: "离线工作中",
+      description:
+        status.pendingCount > 0
+          ? `当前离线，已保留 ${status.pendingCount} 条待上传改动。`
+          : "当前离线，本地仍可继续编辑，联网后会自动同步。",
+      accentClassName: "border-amber-200/80 bg-amber-50/80 text-amber-950",
+      icon: CloudOff,
+      iconClassName: "text-amber-600"
+    };
+  }
+
+  if (status.phase === "syncing") {
+    return {
+      title: "正在同步",
+      description: "正在上传本地改动并拉取最新云端增量。",
+      accentClassName: "border-primary/20 bg-primary/10 text-foreground",
+      icon: LoaderCircle,
+      iconClassName: "animate-spin text-primary"
+    };
+  }
+
+  if (status.phase === "backoff") {
+    return {
+      title: "同步稍后重试",
+      description: `${status.lastError ?? "同步失败"}，系统将在 ${formatRetryTime(
+        status.nextRetryAt
+      )} 再试一次。`,
+      accentClassName: "border-destructive/20 bg-destructive/8 text-foreground",
+      icon: ServerCrash,
+      iconClassName: "text-destructive"
+    };
+  }
+
+  if (status.phase === "attention") {
+    return {
+      title: "需要人工关注",
+      description: `有 ${status.blockedCount} 条同步记录已达到重试上限，请检查接口配置或网络环境。`,
+      accentClassName: "border-destructive/20 bg-destructive/8 text-foreground",
+      icon: CircleAlert,
+      iconClassName: "text-destructive"
+    };
+  }
+
+  if (status.pendingRemoteCount > 0) {
+    return {
+      title: "云端变更已接收",
+      description: `已收到 ${status.pendingRemoteCount} 条云端变更，后续会进入本地合并流程。`,
+      accentClassName: "border-sky-200/80 bg-sky-50/80 text-sky-950",
+      icon: RefreshCw,
+      iconClassName: "text-sky-600"
+    };
+  }
+
+  return {
+    title: "同步状态正常",
+    description:
+      status.pendingCount > 0
+        ? `还有 ${status.pendingCount} 条本地改动待处理。`
+        : "本地改动与云端增量传输均处于正常状态。",
+    accentClassName: "border-emerald-200/80 bg-emerald-50/80 text-emerald-950",
+    icon: CheckCircle2,
+    iconClassName: "text-emerald-600"
+  };
+}
+
+type SyncStatusCardProps = {
+  syncStatus: SyncEngineStatus;
+  onTriggerSync: () => void;
+};
+
+const SyncStatusCard = memo(function SyncStatusCard({
+  syncStatus,
+  onTriggerSync
+}: SyncStatusCardProps) {
+  const syncSummary = getSyncSummary(syncStatus);
+  const SyncSummaryIcon = syncSummary.icon;
+
+  return (
+    <section
+      className={cn(
+        "rounded-[1.75rem] border px-4 py-4 shadow-[0_24px_70px_-42px_hsl(var(--primary)/0.38)] backdrop-blur md:px-5",
+        syncSummary.accentClassName
+      )}
+    >
+      <div className="flex flex-col gap-4 md:flex-row md:items-center md:justify-between">
+        <div className="flex items-start gap-3">
+          <div className="rounded-2xl bg-white/70 p-2.5 shadow-sm ring-1 ring-black/5">
+            <SyncSummaryIcon className={cn("h-5 w-5", syncSummary.iconClassName)} />
+          </div>
+          <div className="space-y-1">
+            <p className="text-sm font-semibold">{syncSummary.title}</p>
+            <p className="text-sm leading-6 text-current/80">{syncSummary.description}</p>
+          </div>
+        </div>
+
+        <div className="flex flex-wrap items-center gap-2">
+          <span className="rounded-full border border-current/10 bg-white/70 px-3 py-1 text-xs text-current/80">
+            待上传 {syncStatus.pendingCount}
+          </span>
+          <span className="rounded-full border border-current/10 bg-white/70 px-3 py-1 text-xs text-current/80">
+            云端待合并 {syncStatus.pendingRemoteCount}
+          </span>
+          {syncStatus.blockedCount > 0 ? (
+            <span className="rounded-full border border-destructive/20 bg-white/70 px-3 py-1 text-xs text-destructive">
+              阻塞 {syncStatus.blockedCount}
+            </span>
+          ) : null}
+          <span className="rounded-full border border-current/10 bg-white/70 px-3 py-1 text-xs text-current/80">
+            上次成功 {formatSyncTimestamp(syncStatus.lastSyncedAt)}
+          </span>
+          <Button
+            type="button"
+            variant="outline"
+            className="border-current/15 bg-white/70 text-current hover:bg-white"
+            onClick={onTriggerSync}
+            disabled={!syncStatus.isOnline || syncStatus.phase === "syncing"}
+          >
+            {syncStatus.phase === "syncing" ? "同步中..." : "立即同步"}
+          </Button>
+        </div>
+      </div>
+    </section>
+  );
+});
+
+type TaskListPanelProps = {
+  tasks: LocalTaskRecord[];
+  selectedTaskId: string | null;
+  quotaSnapshot: StorageQuotaSnapshot | null;
+  creating: boolean;
+  onCreateTask: () => void;
+  onSelectTask: (taskId: string) => void;
+};
+
+const TaskListPanel = memo(function TaskListPanel({
+  tasks,
+  selectedTaskId,
+  quotaSnapshot,
+  creating,
+  onCreateTask,
+  onSelectTask
+}: TaskListPanelProps) {
+  return (
+    <section className="rounded-2xl border border-border bg-card/90 p-4 shadow-[0_24px_70px_-42px_hsl(var(--primary)/0.6)] backdrop-blur">
+      <div className="mb-3 flex items-center justify-between gap-2">
+        <h2 className="text-base font-semibold text-foreground">任务列表</h2>
+        <Button
+          type="button"
+          size="sm"
+          className="bg-primary text-primary-foreground hover:bg-primary/90"
+          onClick={onCreateTask}
+          disabled={creating}
+        >
+          {creating ? "创建中..." : "新建任务"}
+        </Button>
+      </div>
+
+      {quotaSnapshot ? (
+        <p
+          className={cn(
+            "mb-3 text-xs",
+            quotaSnapshot.usedPercent >= 85 ? "text-destructive" : "text-muted-foreground"
+          )}
+        >
+          空间占用（估算）：{formatStorageSize(quotaSnapshot.usedBytes)} /{" "}
+          {formatStorageSize(quotaSnapshot.quotaBytes)}（{quotaSnapshot.usedPercent.toFixed(1)}%）
+        </p>
+      ) : null}
+
+      {tasks.length === 0 ? (
+        <p className="rounded-xl border border-dashed border-border bg-muted/40 p-4 text-sm text-muted-foreground">
+          还没有任务，点击右上角“新建任务”。
+        </p>
+      ) : (
+        <div className="space-y-2">
+          {tasks.map((task) => {
+            const isActive = task.id === selectedTaskId;
+            return (
+              <button
+                key={task.id}
+                type="button"
+                className={cn(
+                  "w-full rounded-xl border px-3 py-2 text-left transition-colors",
+                  isActive
+                    ? "border-primary/45 bg-primary/10"
+                    : "border-border bg-background hover:border-primary/25 hover:bg-primary/5"
+                )}
+                onClick={() => onSelectTask(task.id)}
+              >
+                <p className="truncate text-sm font-medium text-foreground">{task.title}</p>
+                <p className="mt-1 text-xs text-muted-foreground">
+                  {STATUS_LABEL_MAP[task.status]} · {PRIORITY_LABEL_MAP[task.priority]} · 更新于{" "}
+                  {formatUpdatedAt(task.updatedAt)}
+                </p>
+              </button>
+            );
+          })}
+        </div>
+      )}
+    </section>
+  );
+});
+
+type TaskDetailPanelProps = {
+  selectedTaskId: string | null;
+  selectedTask: LocalTaskRecord | undefined;
+  formState: TaskFormState;
+  editorKey: string;
+  editorSeedState: TaskEditorState;
+  saving: boolean;
+  deleting: boolean;
+  onSaveTask: () => void;
+  onDeleteTask: () => void;
+  onTitleChange: (value: string) => void;
+  onStatusChange: (value: LocalTaskStatus) => void;
+  onPriorityChange: (value: LocalTaskPriority) => void;
+  onDdlChange: (value: string) => void;
+  onEditorChange: (payload: { json: string | null; text: string }) => void;
+};
+
+const TaskDetailPanel = memo(function TaskDetailPanel({
+  selectedTaskId,
+  selectedTask,
+  formState,
+  editorKey,
+  editorSeedState,
+  saving,
+  deleting,
+  onSaveTask,
+  onDeleteTask,
+  onTitleChange,
+  onStatusChange,
+  onPriorityChange,
+  onDdlChange,
+  onEditorChange
+}: TaskDetailPanelProps) {
+  return (
+    <section className="rounded-2xl border border-border bg-card/90 p-4 shadow-[0_24px_70px_-42px_hsl(var(--primary)/0.6)] backdrop-blur">
+      <div className="mb-4 flex flex-wrap items-center justify-between gap-2">
+        <h2 className="text-base font-semibold text-foreground">任务详情</h2>
+        <div className="flex items-center gap-2">
+          <Button
+            type="button"
+            variant="outline"
+            onClick={onSaveTask}
+            disabled={!selectedTaskId || saving}
+          >
+            {saving ? "保存中..." : "保存"}
+          </Button>
+          <Button
+            type="button"
+            variant="outline"
+            className="border-destructive/50 text-destructive hover:bg-destructive/10"
+            onClick={onDeleteTask}
+            disabled={!selectedTaskId || deleting}
+          >
+            {deleting ? "删除中..." : "删除"}
+          </Button>
+        </div>
+      </div>
+
+      {!selectedTaskId || !selectedTask ? (
+        <p className="rounded-xl border border-dashed border-border bg-muted/40 p-4 text-sm text-muted-foreground">
+          请选择一个任务进行编辑。
+        </p>
+      ) : (
+        <div className="space-y-3">
+          <label className="block text-sm text-muted-foreground">
+            任务标题
+            <input
+              className="mt-1 w-full rounded-lg border border-input bg-background px-3 py-2 text-sm text-foreground outline-none focus:border-primary focus:ring-2 focus:ring-ring/30"
+              value={formState.title}
+              onChange={(event) => onTitleChange(event.target.value)}
+              placeholder="请输入任务标题"
+            />
+          </label>
+
+          <div className="grid gap-3 sm:grid-cols-2">
+            <label className="block text-sm text-muted-foreground">
+              状态
+              <select
+                className="mt-1 w-full rounded-lg border border-input bg-background px-3 py-2 text-sm text-foreground outline-none focus:border-primary focus:ring-2 focus:ring-ring/30"
+                value={formState.status}
+                onChange={(event) => onStatusChange(event.target.value as LocalTaskStatus)}
+              >
+                {STATUS_OPTIONS.map((option) => (
+                  <option key={option.value} value={option.value}>
+                    {option.label}
+                  </option>
+                ))}
+              </select>
+            </label>
+
+            <label className="block text-sm text-muted-foreground">
+              优先级
+              <select
+                className="mt-1 w-full rounded-lg border border-input bg-background px-3 py-2 text-sm text-foreground outline-none focus:border-primary focus:ring-2 focus:ring-ring/30"
+                value={formState.priority}
+                onChange={(event) => onPriorityChange(event.target.value as LocalTaskPriority)}
+              >
+                {PRIORITY_OPTIONS.map((option) => (
+                  <option key={option.value} value={option.value}>
+                    {option.label}
+                  </option>
+                ))}
+              </select>
+            </label>
+          </div>
+
+          <label className="block text-sm text-muted-foreground">
+            截止时间
+            <input
+              type="datetime-local"
+              className="mt-1 w-full rounded-lg border border-input bg-background px-3 py-2 text-sm text-foreground outline-none focus:border-primary focus:ring-2 focus:ring-ring/30"
+              value={formState.ddlInput}
+              onChange={(event) => onDdlChange(event.target.value)}
+            />
+          </label>
+
+          <div className="block text-sm text-muted-foreground">
+            <p>任务内容</p>
+            <div className="mt-1">
+              <TaskRichEditor
+                key={editorKey}
+                valueJson={editorSeedState.contentJson}
+                textFallback={editorSeedState.contentText}
+                onChange={onEditorChange}
+              />
+            </div>
+          </div>
+        </div>
+      )}
+    </section>
+  );
+});
+
 export function TodoShellPage({ session }: TodoShellPageProps) {
   const [selectedTaskId, setSelectedTaskId] = useState<string | null>(null);
   const [formState, setFormState] = useState<TaskFormState>(DEFAULT_FORM_STATE);
@@ -147,7 +548,13 @@ export function TodoShellPage({ session }: TodoShellPageProps) {
   const [feedback, setFeedback] = useState<FeedbackNotice | null>(null);
   const [feedbackVisible, setFeedbackVisible] = useState(false);
   const [draftReadyTaskId, setDraftReadyTaskId] = useState<string | null>(null);
-  const savedTaskSnapshotRef = useRef(serializeFormState(DEFAULT_FORM_STATE));
+  const [editorSeedState, setEditorSeedState] = useState<TaskEditorState>(DEFAULT_EDITOR_STATE);
+  const [editorKey, setEditorKey] = useState("editor-empty");
+  const savedTaskSnapshotRef = useRef(serializeFormState(DEFAULT_FORM_STATE, DEFAULT_EDITOR_STATE));
+  const formStateRef = useRef(DEFAULT_FORM_STATE);
+  const editorStateRef = useRef(DEFAULT_EDITOR_STATE);
+  const draftPersistTimeoutRef = useRef<number | null>(null);
+  const { status: syncStatus, triggerSync } = useSyncEngine(session);
 
   const userId = session?.user.id ?? "";
 
@@ -175,6 +582,49 @@ export function TodoShellPage({ session }: TodoShellPageProps) {
     return getLocalTaskById(selectedTaskId);
   }, [selectedTaskId]);
 
+  useEffect(() => {
+    formStateRef.current = formState;
+  }, [formState]);
+
+  const scheduleDraftPersist = useCallback((): void => {
+    if (!selectedTaskId || draftReadyTaskId !== selectedTaskId || !userId) {
+      return;
+    }
+
+    if (draftPersistTimeoutRef.current !== null) {
+      window.clearTimeout(draftPersistTimeoutRef.current);
+    }
+
+    const currentTaskId = selectedTaskId;
+    const currentUserId = userId;
+    const currentFormState = formStateRef.current;
+    const currentEditorState = editorStateRef.current;
+    const currentSnapshot = serializeFormState(currentFormState, currentEditorState);
+
+    draftPersistTimeoutRef.current = window.setTimeout(() => {
+      async function persistDraft(): Promise<void> {
+        if (currentSnapshot === savedTaskSnapshotRef.current) {
+          await deleteLocalTaskDraft(currentTaskId);
+          return;
+        }
+
+        await saveLocalTaskDraft({
+          taskId: currentTaskId,
+          userId: currentUserId,
+          title: currentFormState.title,
+          contentJson: currentEditorState.contentJson,
+          contentText: currentEditorState.contentText,
+          priority: currentFormState.priority,
+          status: currentFormState.status,
+          ddlInput: currentFormState.ddlInput
+        });
+      }
+
+      void persistDraft();
+      draftPersistTimeoutRef.current = null;
+    }, DRAFT_PERSIST_DEBOUNCE_MS);
+  }, [draftReadyTaskId, selectedTaskId, userId]);
+
   useEffect(() => {
     if (!tasks || tasks.length === 0) {
       setSelectedTaskId(null);
@@ -195,8 +645,12 @@ export function TodoShellPage({ session }: TodoShellPageProps) {
   useEffect(() => {
     if (!selectedTaskId) {
       setFormState(DEFAULT_FORM_STATE);
+      formStateRef.current = DEFAULT_FORM_STATE;
+      editorStateRef.current = DEFAULT_EDITOR_STATE;
+      setEditorSeedState(DEFAULT_EDITOR_STATE);
+      setEditorKey("editor-empty");
       setDraftReadyTaskId(null);
-      savedTaskSnapshotRef.current = serializeFormState(DEFAULT_FORM_STATE);
+      savedTaskSnapshotRef.current = serializeFormState(DEFAULT_FORM_STATE, DEFAULT_EDITOR_STATE);
       return;
     }
 
@@ -209,14 +663,26 @@ export function TodoShellPage({ session }: TodoShellPageProps) {
 
     async function hydrateFormState(): Promise<void> {
       const persistedTaskState = createFormStateFromTask(currentTask);
+      const persistedEditorState = createEditorStateFromTask(currentTask);
       const localDraft = await getLocalTaskDraft(currentTask.id);
 
       if (cancelled) {
         return;
       }
 
-      savedTaskSnapshotRef.current = serializeFormState(persistedTaskState);
+      const nextFormState = localDraft ? createFormStateFromDraft(localDraft) : persistedTaskState;
-      setFormState(localDraft ? createFormStateFromDraft(localDraft) : persistedTaskState);
+      const nextEditorState = localDraft
+        ? createEditorStateFromDraft(localDraft)
+        : persistedEditorState;
+
+      savedTaskSnapshotRef.current = serializeFormState(persistedTaskState, persistedEditorState);
+      formStateRef.current = nextFormState;
+      editorStateRef.current = nextEditorState;
+      setFormState(nextFormState);
+      setEditorSeedState(nextEditorState);
+      setEditorKey(
+        `${currentTask.id}:${currentTask.updatedAt}:${localDraft?.updatedAt ?? currentTask.updatedAt}`
+      );
       setDraftReadyTaskId(currentTask.id);
     }
 
@@ -228,34 +694,16 @@ export function TodoShellPage({ session }: TodoShellPageProps) {
   }, [selectedTask, selectedTaskId]);
 
   useEffect(() => {
-    if (!selectedTaskId || !selectedTask || draftReadyTaskId !== selectedTaskId || !userId) {
+    scheduleDraftPersist();
-      return;
+  }, [formState, scheduleDraftPersist]);
+
+  useEffect(() => {
+    return () => {
+      if (draftPersistTimeoutRef.current !== null) {
+        window.clearTimeout(draftPersistTimeoutRef.current);
       }
-
+    };
-    const currentSnapshot = serializeFormState(formState);
+  }, []);
-    const currentTaskId = selectedTaskId;
-    const currentUserId = userId;
-
-    async function persistDraft(): Promise<void> {
-      if (currentSnapshot === savedTaskSnapshotRef.current) {
-        await deleteLocalTaskDraft(currentTaskId);
-        return;
-      }
-
-      await saveLocalTaskDraft({
-        taskId: currentTaskId,
-        userId: currentUserId,
-        title: formState.title,
-        contentJson: formState.contentJson,
-        contentText: formState.contentText,
-        priority: formState.priority,
-        status: formState.status,
-        ddlInput: formState.ddlInput
-      });
-    }
-
-    void persistDraft();
-  }, [draftReadyTaskId, formState, selectedTask, selectedTaskId, userId]);
 
   const showFeedback = useCallback((message: string, tone: FeedbackNotice["tone"]): void => {
     setFeedback({ message, tone });
@@ -339,11 +787,12 @@ export function TodoShellPage({ session }: TodoShellPageProps) {
 
     try {
       setSaving(true);
+      const currentEditorState = editorStateRef.current;
       const updatedTask = await updateLocalTask({
         id: selectedTaskId,
         title: formState.title,
-        contentText: formState.contentText || null,
+        contentText: currentEditorState.contentText || null,
-        contentJson: formState.contentJson,
+        contentJson: currentEditorState.contentJson,
         priority: formState.priority,
         status: formState.status,
         ddlAt: parseDatetimeLocalValue(formState.ddlInput)
@@ -354,7 +803,10 @@ export function TodoShellPage({ session }: TodoShellPageProps) {
         return;
       }
 
-      savedTaskSnapshotRef.current = serializeFormState(createFormStateFromTask(updatedTask));
+      savedTaskSnapshotRef.current = serializeFormState(
+        createFormStateFromTask(updatedTask),
+        createEditorStateFromTask(updatedTask)
+      );
       await deleteLocalTaskDraft(selectedTaskId);
       showFeedback("任务已保存。", "success");
     } finally {
@@ -382,6 +834,49 @@ export function TodoShellPage({ session }: TodoShellPageProps) {
     }
   }, [deleting, selectedTaskId, showFeedback]);
 
+  const handleEditorChange = useCallback(
+    (payload: { json: string | null; text: string }): void => {
+      editorStateRef.current = {
+        contentJson: payload.json,
+        contentText: payload.text
+      };
+      scheduleDraftPersist();
+    },
+    [scheduleDraftPersist]
+  );
+
+  const handleSelectTask = useCallback((taskId: string): void => {
+    setSelectedTaskId(taskId);
+  }, []);
+
+  const handleTitleChange = useCallback((value: string): void => {
+    setFormState((previous) => ({
+      ...previous,
+      title: value
+    }));
+  }, []);
+
+  const handleStatusChange = useCallback((value: LocalTaskStatus): void => {
+    setFormState((previous) => ({
+      ...previous,
+      status: value
+    }));
+  }, []);
+
+  const handlePriorityChange = useCallback((value: LocalTaskPriority): void => {
+    setFormState((previous) => ({
+      ...previous,
+      priority: value
+    }));
+  }, []);
+
+  const handleDdlChange = useCallback((value: string): void => {
+    setFormState((previous) => ({
+      ...previous,
+      ddlInput: value
+    }));
+  }, []);
+
   useEffect(() => {
     function handleKeydown(event: KeyboardEvent): void {
       const isSaveShortcut = (event.ctrlKey || event.metaKey) && event.key.toLowerCase() === "s";
@@ -417,192 +912,42 @@ export function TodoShellPage({ session }: TodoShellPageProps) {
   }
 
   const taskList = tasks ?? [];
+  const quotaPanelSnapshot = quotaSnapshot ?? null;
 
   return (
     <>
       {renderFeedbackBanner()}
+      <div className="space-y-4">
+        <SyncStatusCard syncStatus={syncStatus} onTriggerSync={triggerSync} />
+
         <div className="grid gap-4 lg:grid-cols-[320px_minmax(0,1fr)]">
-        <section className="rounded-2xl border border-border bg-card/90 p-4 shadow-[0_24px_70px_-42px_hsl(var(--primary)/0.6)] backdrop-blur">
+          <TaskListPanel
-          <div className="mb-3 flex items-center justify-between gap-2">
+            tasks={taskList}
-            <h2 className="text-base font-semibold text-foreground">任务列表</h2>
+            selectedTaskId={selectedTaskId}
-            <Button
+            quotaSnapshot={quotaPanelSnapshot}
-              type="button"
+            creating={creating}
-              size="sm"
+            onCreateTask={handleCreateTask}
-              className="bg-primary text-primary-foreground hover:bg-primary/90"
+            onSelectTask={handleSelectTask}
-              onClick={handleCreateTask}
-              disabled={creating}
-            >
-              {creating ? "创建中..." : "新建任务"}
-            </Button>
-          </div>
-
-          {quotaSnapshot ? (
-            <p
-              className={cn(
-                "mb-3 text-xs",
-                quotaSnapshot.usedPercent >= 85 ? "text-destructive" : "text-muted-foreground"
-              )}
-            >
-              空间占用（估算）：{formatStorageSize(quotaSnapshot.usedBytes)} /{" "}
-              {formatStorageSize(quotaSnapshot.quotaBytes)}（{quotaSnapshot.usedPercent.toFixed(1)}
-              %）
-            </p>
-          ) : null}
-
-          {taskList.length === 0 ? (
-            <p className="rounded-xl border border-dashed border-border bg-muted/40 p-4 text-sm text-muted-foreground">
-              还没有任务，点击右上角“新建任务”。
-            </p>
-          ) : (
-            <div className="space-y-2">
-              {taskList.map((task) => {
-                const isActive = task.id === selectedTaskId;
-                return (
-                  <button
-                    key={task.id}
-                    type="button"
-                    className={cn(
-                      "w-full rounded-xl border px-3 py-2 text-left transition-colors",
-                      isActive
-                        ? "border-primary/45 bg-primary/10"
-                        : "border-border bg-background hover:border-primary/25 hover:bg-primary/5"
-                    )}
-                    onClick={() => setSelectedTaskId(task.id)}
-                  >
-                    <p className="truncate text-sm font-medium text-foreground">{task.title}</p>
-                    <p className="mt-1 text-xs text-muted-foreground">
-                      {STATUS_LABEL_MAP[task.status]} · {PRIORITY_LABEL_MAP[task.priority]} · 更新于{" "}
-                      {formatUpdatedAt(task.updatedAt)}
-                    </p>
-                  </button>
-                );
-              })}
-            </div>
-          )}
-        </section>
-
-        <section className="rounded-2xl border border-border bg-card/90 p-4 shadow-[0_24px_70px_-42px_hsl(var(--primary)/0.6)] backdrop-blur">
-          <div className="mb-4 flex flex-wrap items-center justify-between gap-2">
-            <h2 className="text-base font-semibold text-foreground">任务详情</h2>
-            <div className="flex items-center gap-2">
-              <Button
-                type="button"
-                variant="outline"
-                onClick={handleSaveTask}
-                disabled={!selectedTaskId || saving}
-              >
-                {saving ? "保存中..." : "保存"}
-              </Button>
-              <Button
-                type="button"
-                variant="outline"
-                className="border-destructive/50 text-destructive hover:bg-destructive/10"
-                onClick={handleDeleteTask}
-                disabled={!selectedTaskId || deleting}
-              >
-                {deleting ? "删除中..." : "删除"}
-              </Button>
-            </div>
-          </div>
-
-          {!selectedTaskId || !selectedTask ? (
-            <p className="rounded-xl border border-dashed border-border bg-muted/40 p-4 text-sm text-muted-foreground">
-              请选择一个任务进行编辑。
-            </p>
-          ) : (
-            <div className="space-y-3">
-              <label className="block text-sm text-muted-foreground">
-                任务标题
-                <input
-                  className="mt-1 w-full rounded-lg border border-input bg-background px-3 py-2 text-sm text-foreground outline-none focus:border-primary focus:ring-2 focus:ring-ring/30"
-                  value={formState.title}
-                  onChange={(event) =>
-                    setFormState((previous) => ({
-                      ...previous,
-                      title: event.target.value
-                    }))
-                  }
-                  placeholder="请输入任务标题"
           />
-              </label>
 
-              <div className="grid gap-3 sm:grid-cols-2">
+          <TaskDetailPanel
-                <label className="block text-sm text-muted-foreground">
+            selectedTaskId={selectedTaskId}
-                  状态
+            selectedTask={selectedTask}
-                  <select
+            formState={formState}
-                    className="mt-1 w-full rounded-lg border border-input bg-background px-3 py-2 text-sm text-foreground outline-none focus:border-primary focus:ring-2 focus:ring-ring/30"
+            editorKey={editorKey}
-                    value={formState.status}
+            editorSeedState={editorSeedState}
-                    onChange={(event) =>
+            saving={saving}
-                      setFormState((previous) => ({
+            deleting={deleting}
-                        ...previous,
+            onSaveTask={handleSaveTask}
-                        status: event.target.value as LocalTaskStatus
+            onDeleteTask={handleDeleteTask}
-                      }))
+            onTitleChange={handleTitleChange}
-                    }
+            onStatusChange={handleStatusChange}
-                  >
+            onPriorityChange={handlePriorityChange}
-                    {STATUS_OPTIONS.map((option) => (
+            onDdlChange={handleDdlChange}
-                      <option key={option.value} value={option.value}>
+            onEditorChange={handleEditorChange}
-                        {option.label}
-                      </option>
-                    ))}
-                  </select>
-                </label>
-
-                <label className="block text-sm text-muted-foreground">
-                  优先级
-                  <select
-                    className="mt-1 w-full rounded-lg border border-input bg-background px-3 py-2 text-sm text-foreground outline-none focus:border-primary focus:ring-2 focus:ring-ring/30"
-                    value={formState.priority}
-                    onChange={(event) =>
-                      setFormState((previous) => ({
-                        ...previous,
-                        priority: event.target.value as LocalTaskPriority
-                      }))
-                    }
-                  >
-                    {PRIORITY_OPTIONS.map((option) => (
-                      <option key={option.value} value={option.value}>
-                        {option.label}
-                      </option>
-                    ))}
-                  </select>
-                </label>
-              </div>
-
-              <label className="block text-sm text-muted-foreground">
-                截止时间
-                <input
-                  type="datetime-local"
-                  className="mt-1 w-full rounded-lg border border-input bg-background px-3 py-2 text-sm text-foreground outline-none focus:border-primary focus:ring-2 focus:ring-ring/30"
-                  value={formState.ddlInput}
-                  onChange={(event) =>
-                    setFormState((previous) => ({
-                      ...previous,
-                      ddlInput: event.target.value
-                    }))
-                  }
-                />
-              </label>
-
-              <div className="block text-sm text-muted-foreground">
-                <p>任务内容</p>
-                <div className="mt-1">
-                  <TaskRichEditor
-                    valueJson={formState.contentJson}
-                    textFallback={formState.contentText}
-                    onChange={(payload) =>
-                      setFormState((previous) => ({
-                        ...previous,
-                        contentJson: payload.json,
-                        contentText: payload.text
-                      }))
-                    }
           />
         </div>
       </div>
-            </div>
-          )}
-        </section>
-      </div>
     </>
   );
 }

apps/web/src/services/local-db.ts

@@ -17,6 +17,7 @@ export type LocalTaskRecord = {
   priority: LocalTaskPriority;
   status: LocalTaskStatus;
   ddlAt: number | null;
+  version: number;
   createdAt: number;
   updatedAt: number;
   deletedAt: number | null;
@@ -47,10 +48,33 @@ export type LocalTaskDraftRecord = {
   updatedAt: number;
 };
 
+export type LocalSyncStateRecord = {
+  userId: string;
+  cursor: string | null;
+  lastSyncedAt: number | null;
+  updatedAt: number;
+};
+
+export type LocalSyncInboxRecord = {
+  opId: string;
+  userId: string;
+  entityId: string;
+  entityType: SyncEntityType;
+  action: SyncActionType;
+  payload: string | null;
+  clientTs: number;
+  deviceId: string;
+  serverTs: number;
+  receivedAt: number;
+  appliedAt: number | null;
+};
+
 class TodoLocalDb extends Dexie {
   declare tasks: Table<LocalTaskRecord, string>;
   declare opLogs: Table<LocalOpLogRecord, string>;
   declare taskDrafts: Table<LocalTaskDraftRecord, string>;
+  declare syncStates: Table<LocalSyncStateRecord, string>;
+  declare syncInbox: Table<LocalSyncInboxRecord, string>;
 
   constructor() {
     super("todolist-web-db");
@@ -66,9 +90,38 @@ class TodoLocalDb extends Dexie {
       task_drafts: "&taskId,userId,updatedAt"
     });
 
+    this.version(3).stores({
+      tasks: "&id,userId,status,priority,ddlAt,updatedAt,deletedAt",
+      op_logs: "&opId,entityId,entityType,action,clientTs,syncedAt",
+      task_drafts: "&taskId,userId,updatedAt",
+      sync_states: "&userId,updatedAt,lastSyncedAt",
+      sync_inbox: "&opId,userId,entityId,serverTs,appliedAt"
+    });
+
+    this.version(4)
+      .stores({
+        tasks: "&id,userId,status,priority,ddlAt,updatedAt,deletedAt",
+        op_logs: "&opId,entityId,entityType,action,clientTs,syncedAt",
+        task_drafts: "&taskId,userId,updatedAt",
+        sync_states: "&userId,updatedAt,lastSyncedAt",
+        sync_inbox: "&opId,userId,entityId,serverTs,appliedAt"
+      })
+      .upgrade(async (tx) => {
+        await tx
+          .table("tasks")
+          .toCollection()
+          .modify((task: Partial<LocalTaskRecord>) => {
+            if (typeof task.version !== "number") {
+              task.version = 1;
+            }
+          });
+      });
+
     this.tasks = this.table("tasks");
     this.opLogs = this.table("op_logs");
     this.taskDrafts = this.table("task_drafts");
+    this.syncStates = this.table("sync_states");
+    this.syncInbox = this.table("sync_inbox");
   }
 }
 

apps/web/src/services/local-sync-repo.ts

@@ -0,0 +1,167 @@
+import {
+  localDb,
+  type LocalOpLogRecord,
+  type LocalSyncInboxRecord,
+  type LocalSyncStateRecord
+} from "@/services/local-db";
+import type { SyncPullItem } from "@/services/sync-api";
+
+export const MAX_SYNC_RETRY_COUNT = 5;
+
+export async function listPendingSyncOperations(limit = 20): Promise<LocalOpLogRecord[]> {
+  const records = await localDb.opLogs.orderBy("clientTs").toArray();
+
+  return records
+    .filter((record) => record.syncedAt === null && record.retryCount < MAX_SYNC_RETRY_COUNT)
+    .slice(0, limit);
+}
+
+export async function countPendingSyncOperations(): Promise<number> {
+  const records = await localDb.opLogs.toArray();
+  return records.filter(
+    (record) => record.syncedAt === null && record.retryCount < MAX_SYNC_RETRY_COUNT
+  ).length;
+}
+
+export async function countBlockedSyncOperations(): Promise<number> {
+  const records = await localDb.opLogs.toArray();
+  return records.filter(
+    (record) => record.syncedAt === null && record.retryCount >= MAX_SYNC_RETRY_COUNT
+  ).length;
+}
+
+export async function markSyncOperationsSucceeded(
+  opIds: string[],
+  syncedAt: number
+): Promise<void> {
+  if (opIds.length === 0) {
+    return;
+  }
+
+  const records = await localDb.opLogs.bulkGet(opIds);
+  const nextRecords = records
+    .filter((record): record is LocalOpLogRecord => record !== undefined)
+    .map((record) => ({
+      ...record,
+      syncedAt,
+      errorMessage: null
+    }));
+
+  if (nextRecords.length > 0) {
+    await localDb.opLogs.bulkPut(nextRecords);
+  }
+}
+
+export async function markSyncOperationsFailed(
+  failures: Array<{ opId: string; errorMessage: string }>
+): Promise<void> {
+  if (failures.length === 0) {
+    return;
+  }
+
+  const failureMap = new Map(failures.map((failure) => [failure.opId, failure.errorMessage]));
+  const records = await localDb.opLogs.bulkGet(failures.map((failure) => failure.opId));
+  const nextRecords = records
+    .filter((record): record is LocalOpLogRecord => record !== undefined)
+    .map((record) => ({
+      ...record,
+      retryCount: record.retryCount + 1,
+      errorMessage: failureMap.get(record.opId) ?? "同步失败"
+    }));
+
+  if (nextRecords.length > 0) {
+    await localDb.opLogs.bulkPut(nextRecords);
+  }
+}
+
+export async function getLocalSyncState(userId: string): Promise<LocalSyncStateRecord | undefined> {
+  return localDb.syncStates.get(userId);
+}
+
+export async function saveLocalSyncState(input: {
+  userId: string;
+  cursor: string | null;
+  lastSyncedAt: number | null;
+}): Promise<void> {
+  await localDb.syncStates.put({
+    userId: input.userId,
+    cursor: input.cursor,
+    lastSyncedAt: input.lastSyncedAt,
+    updatedAt: Date.now()
+  });
+}
+
+export async function enqueueRemoteSyncOperations(
+  userId: string,
+  operations: SyncPullItem[]
+): Promise<number> {
+  if (operations.length === 0) {
+    return 0;
+  }
+
+  const receivedAt = Date.now();
+  const records: LocalSyncInboxRecord[] = operations.map((operation) => ({
+    opId: operation.opId,
+    userId,
+    entityId: operation.entityId,
+    entityType: operation.entityType,
+    action: operation.action,
+    payload: operation.payload,
+    clientTs: operation.clientTs,
+    deviceId: operation.deviceId,
+    serverTs: new Date(operation.serverTs).getTime(),
+    receivedAt,
+    appliedAt: null
+  }));
+
+  await localDb.syncInbox.bulkPut(records);
+  return records.length;
+}
+
+export async function listPendingRemoteOperations(
+  userId: string,
+  limit = 100
+): Promise<LocalSyncInboxRecord[]> {
+  const records = await localDb.syncInbox.where("userId").equals(userId).toArray();
+
+  return records
+    .filter((record) => record.appliedAt === null)
+    .sort((left, right) => {
+      if (left.serverTs !== right.serverTs) {
+        return left.serverTs - right.serverTs;
+      }
+
+      if (left.clientTs !== right.clientTs) {
+        return left.clientTs - right.clientTs;
+      }
+
+      return left.opId.localeCompare(right.opId);
+    })
+    .slice(0, limit);
+}
+
+export async function markRemoteOperationsApplied(
+  opIds: string[],
+  appliedAt: number
+): Promise<void> {
+  if (opIds.length === 0) {
+    return;
+  }
+
+  const records = await localDb.syncInbox.bulkGet(opIds);
+  const nextRecords = records
+    .filter((record): record is LocalSyncInboxRecord => record !== undefined)
+    .map((record) => ({
+      ...record,
+      appliedAt
+    }));
+
+  if (nextRecords.length > 0) {
+    await localDb.syncInbox.bulkPut(nextRecords);
+  }
+}
+
+export async function countPendingRemoteOperations(userId: string): Promise<number> {
+  const records = await localDb.syncInbox.where("userId").equals(userId).toArray();
+  return records.filter((record) => record.appliedAt === null).length;
+}

apps/web/src/services/local-task-repo.ts

@@ -24,6 +24,21 @@ export type UpdateLocalTaskInput = {
   ddlAt?: number | null;
 };
 
+type SyncTaskPayload = {
+  id?: string;
+  userId?: string;
+  title: string;
+  contentJson: string | null;
+  contentText?: string | null;
+  priority: LocalTaskPriority;
+  status: LocalTaskStatus;
+  ddlAt: number | null;
+  version: number;
+  createdAt?: number;
+  updatedAt: number;
+  deletedAt?: number | null;
+};
+
 function resolveDeviceId(): string {
   const savedDeviceId = window.localStorage.getItem(DEVICE_ID_STORAGE_KEY);
   if (savedDeviceId) {
@@ -54,6 +69,18 @@ function createOpLogRecord(
   };
 }
 
+function createSyncTaskPayload(payload: SyncTaskPayload): string {
+  const nextPayload: Record<string, unknown> = {
+    ...payload
+  };
+
+  if (payload.contentJson !== null) {
+    delete nextPayload.contentText;
+  }
+
+  return JSON.stringify(nextPayload);
+}
+
 export async function listLocalTasksByUser(userId: string): Promise<LocalTaskRecord[]> {
   const tasks = await localDb.tasks.where("userId").equals(userId).toArray();
   return tasks
@@ -81,12 +108,30 @@ export async function createLocalTask(input: CreateLocalTaskInput): Promise<Loca
     priority: "MEDIUM",
     status: "TODO",
     ddlAt: null,
+    version: 1,
     createdAt: now,
     updatedAt: now,
     deletedAt: null
   };
 
-  const opLog = createOpLogRecord(task.id, "CREATE", JSON.stringify(task));
+  const opLog = createOpLogRecord(
+    task.id,
+    "CREATE",
+    createSyncTaskPayload({
+      id: task.id,
+      userId: task.userId,
+      title: task.title,
+      contentJson: task.contentJson,
+      contentText: task.contentText,
+      priority: task.priority,
+      status: task.status,
+      ddlAt: task.ddlAt,
+      version: task.version,
+      createdAt: task.createdAt,
+      updatedAt: task.updatedAt,
+      deletedAt: task.deletedAt
+    })
+  );
 
   await localDb.transaction("rw", localDb.tasks, localDb.opLogs, async () => {
     await localDb.tasks.add(task);
@@ -104,6 +149,7 @@ export async function updateLocalTask(
     return undefined;
   }
 
+  const nextVersion = currentTask.version + 1;
   const nextTask: LocalTaskRecord = {
     ...currentTask,
     title: input.title !== undefined ? input.title.trim() || "未命名任务" : currentTask.title,
@@ -112,19 +158,21 @@ export async function updateLocalTask(
     priority: input.priority ?? currentTask.priority,
     status: input.status ?? currentTask.status,
     ddlAt: input.ddlAt !== undefined ? input.ddlAt : currentTask.ddlAt,
+    version: nextVersion,
     updatedAt: Date.now()
   };
 
   const opLog = createOpLogRecord(
     nextTask.id,
     "UPDATE",
-    JSON.stringify({
+    createSyncTaskPayload({
       title: nextTask.title,
-      contentText: nextTask.contentText,
       contentJson: nextTask.contentJson,
+      contentText: nextTask.contentText,
       priority: nextTask.priority,
       status: nextTask.status,
       ddlAt: nextTask.ddlAt,
+      version: nextTask.version,
       updatedAt: nextTask.updatedAt
     })
   );
@@ -144,13 +192,23 @@ export async function deleteLocalTask(id: string): Promise<boolean> {
   }
 
   const deletedAt = Date.now();
+  const nextVersion = currentTask.version + 1;
   const nextTask: LocalTaskRecord = {
     ...currentTask,
+    version: nextVersion,
     deletedAt,
     updatedAt: deletedAt
   };
 
-  const opLog = createOpLogRecord(id, "DELETE", JSON.stringify({ deletedAt }));
+  const opLog = createOpLogRecord(
+    id,
+    "DELETE",
+    JSON.stringify({
+      deletedAt,
+      version: nextTask.version,
+      updatedAt: nextTask.updatedAt
+    })
+  );
 
   await localDb.transaction("rw", localDb.tasks, localDb.opLogs, async () => {
     await localDb.tasks.put(nextTask);

apps/web/src/services/sync-api.ts

@@ -0,0 +1,159 @@
+import type { LocalOpLogRecord } from "@/services/local-db";
+
+export type SyncPushResult = {
+  acceptedCount: number;
+  duplicateCount: number;
+  failedCount: number;
+  results: Array<{
+    opId: string;
+    status: "accepted" | "duplicate" | "failed";
+    serverTs: string | null;
+    reason: string | null;
+  }>;
+};
+
+export type SyncPullItem = {
+  opId: string;
+  entityId: string;
+  entityType: "TASK";
+  action: "CREATE" | "UPDATE" | "DELETE";
+  payload: string | null;
+  clientTs: number;
+  deviceId: string;
+  serverTs: string;
+};
+
+export type SyncPullResult = {
+  items: SyncPullItem[];
+  nextCursor: string | null;
+  hasMore: boolean;
+};
+
+const DEFAULT_API_BASE_URL = "http://localhost:3000";
+
+function resolveApiBaseUrl(): string {
+  const envBaseUrl = import.meta.env.VITE_API_BASE_URL as string | undefined;
+  if (!envBaseUrl) {
+    return DEFAULT_API_BASE_URL;
+  }
+
+  return envBaseUrl.replace(/\/+$/, "");
+}
+
+async function parseErrorMessage(response: Response): Promise<string> {
+  if (response.status === 413) {
+    return "单次同步内容过大，请精简本次任务内容或等待系统分批重试。";
+  }
+
+  try {
+    const body = (await response.json()) as { message?: string | string[] };
+    if (Array.isArray(body.message)) {
+      return body.message.join("，");
+    }
+
+    if (typeof body.message === "string" && body.message.trim()) {
+      return body.message;
+    }
+  } catch {
+    return `请求失败（${response.status}）`;
+  }
+
+  return `请求失败（${response.status}）`;
+}
+
+type SyncPushOperationRequest = {
+  opId: string;
+  entityId: string;
+  entityType: LocalOpLogRecord["entityType"];
+  action: LocalOpLogRecord["action"];
+  payload: string;
+  clientTs: number;
+  deviceId: string;
+};
+
+function compactOperationPayload(payload: string): string {
+  try {
+    const parsed = JSON.parse(payload) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return payload;
+    }
+
+    const nextPayload = { ...(parsed as Record<string, unknown>) };
+    if (nextPayload.contentJson !== undefined && nextPayload.contentJson !== null) {
+      delete nextPayload.contentText;
+    }
+
+    return JSON.stringify(nextPayload);
+  } catch {
+    return payload;
+  }
+}
+
+export function serializeSyncOperationForRequest(
+  operation: LocalOpLogRecord
+): SyncPushOperationRequest {
+  return {
+    opId: operation.opId,
+    entityId: operation.entityId,
+    entityType: operation.entityType,
+    action: operation.action,
+    payload: compactOperationPayload(operation.payload),
+    clientTs: operation.clientTs,
+    deviceId: operation.deviceId
+  };
+}
+
+export async function pushSyncOperations(
+  userId: string,
+  operations: LocalOpLogRecord[]
+): Promise<SyncPushResult> {
+  const requestOperations = operations.map((operation) =>
+    serializeSyncOperationForRequest(operation)
+  );
+
+  const response = await fetch(`${resolveApiBaseUrl()}/sync/push`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "x-user-id": userId
+    },
+    body: JSON.stringify({
+      operations: requestOperations
+    })
+  });
+
+  if (!response.ok) {
+    throw new Error(await parseErrorMessage(response));
+  }
+
+  return (await response.json()) as SyncPushResult;
+}
+
+export async function pullSyncOperations(input: {
+  userId: string;
+  cursor: string | null;
+  limit?: number;
+}): Promise<SyncPullResult> {
+  const requestUrl = new URL(`${resolveApiBaseUrl()}/sync/pull`);
+
+  if (input.cursor) {
+    requestUrl.searchParams.set("cursor", input.cursor);
+  }
+
+  if (input.limit !== undefined) {
+    requestUrl.searchParams.set("limit", String(input.limit));
+  }
+
+  const response = await fetch(requestUrl, {
+    method: "GET",
+    headers: {
+      "x-user-id": input.userId
+    }
+  });
+
+  if (!response.ok) {
+    throw new Error(await parseErrorMessage(response));
+  }
+
+  return (await response.json()) as SyncPullResult;
+}

apps/web/src/services/sync-merge.ts

@@ -0,0 +1,261 @@
+import {
+  localDb,
+  type LocalSyncInboxRecord,
+  type LocalTaskPriority,
+  type LocalTaskRecord,
+  type LocalTaskStatus
+} from "@/services/local-db";
+import { listPendingRemoteOperations } from "@/services/local-sync-repo";
+
+const TASK_PRIORITY_VALUES: LocalTaskPriority[] = ["LOW", "MEDIUM", "HIGH", "URGENT"];
+const TASK_STATUS_VALUES: LocalTaskStatus[] = ["TODO", "IN_PROGRESS", "DONE", "ARCHIVED"];
+
+type RemoteTaskPayload = {
+  userId?: unknown;
+  title?: unknown;
+  contentJson?: unknown;
+  contentText?: unknown;
+  priority?: unknown;
+  status?: unknown;
+  ddlAt?: unknown;
+  version?: unknown;
+  createdAt?: unknown;
+  updatedAt?: unknown;
+  deletedAt?: unknown;
+};
+
+function normalizePriority(value: unknown, fallback: LocalTaskPriority): LocalTaskPriority {
+  if (typeof value === "string" && TASK_PRIORITY_VALUES.includes(value as LocalTaskPriority)) {
+    return value as LocalTaskPriority;
+  }
+
+  return fallback;
+}
+
+function normalizeStatus(value: unknown, fallback: LocalTaskStatus): LocalTaskStatus {
+  if (typeof value === "string" && TASK_STATUS_VALUES.includes(value as LocalTaskStatus)) {
+    return value as LocalTaskStatus;
+  }
+
+  return fallback;
+}
+
+function normalizeStringOrNull(value: unknown, fallback: string | null): string | null {
+  if (typeof value === "string") {
+    return value;
+  }
+
+  if (value === null) {
+    return null;
+  }
+
+  return fallback;
+}
+
+function collectTextFromRichContent(value: unknown, fragments: string[]): void {
+  if (!value || typeof value !== "object") {
+    return;
+  }
+
+  const node = value as {
+    text?: unknown;
+    content?: unknown;
+  };
+
+  if (typeof node.text === "string" && node.text.trim().length > 0) {
+    fragments.push(node.text.trim());
+  }
+
+  if (Array.isArray(node.content)) {
+    for (const child of node.content) {
+      collectTextFromRichContent(child, fragments);
+    }
+  }
+}
+
+function extractTextFromContentJson(contentJson: string | null): string | null {
+  if (!contentJson) {
+    return null;
+  }
+
+  try {
+    const parsed = JSON.parse(contentJson) as unknown;
+    const fragments: string[] = [];
+    collectTextFromRichContent(parsed, fragments);
+    return fragments.length > 0 ? fragments.join(" ") : null;
+  } catch {
+    return null;
+  }
+}
+
+function normalizeNullableNumber(value: unknown, fallback: number | null): number | null {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+
+  if (value === null) {
+    return null;
+  }
+
+  return fallback;
+}
+
+function normalizePositiveNumber(value: unknown, fallback: number): number {
+  if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+    return value;
+  }
+
+  return fallback;
+}
+
+function parseOperationPayload(operation: LocalSyncInboxRecord): RemoteTaskPayload {
+  if (!operation.payload) {
+    return {};
+  }
+
+  const parsed = JSON.parse(operation.payload) as unknown;
+  if (!parsed || typeof parsed !== "object") {
+    return {};
+  }
+
+  return parsed as RemoteTaskPayload;
+}
+
+function createFallbackTask(
+  operation: LocalSyncInboxRecord,
+  userId: string,
+  updatedAt: number,
+  version: number
+): LocalTaskRecord {
+  return {
+    id: operation.entityId,
+    userId,
+    title: "未命名任务",
+    contentJson: null,
+    contentText: null,
+    priority: "MEDIUM",
+    status: "TODO",
+    ddlAt: null,
+    version,
+    createdAt: updatedAt,
+    updatedAt,
+    deletedAt: null
+  };
+}
+
+function buildIncomingTaskRecord(
+  operation: LocalSyncInboxRecord,
+  currentTask: LocalTaskRecord | undefined
+): LocalTaskRecord {
+  const payload = parseOperationPayload(operation);
+  const fallbackVersion = currentTask?.version ?? 1;
+  const version = normalizePositiveNumber(payload.version, fallbackVersion);
+  const updatedAt = normalizePositiveNumber(
+    payload.updatedAt,
+    normalizePositiveNumber(payload.deletedAt, operation.clientTs)
+  );
+  const fallbackTask =
+    currentTask ?? createFallbackTask(operation, operation.userId, updatedAt, version);
+  const contentJson = normalizeStringOrNull(payload.contentJson, fallbackTask.contentJson);
+  const contentText = normalizeStringOrNull(
+    payload.contentText,
+    extractTextFromContentJson(contentJson) ?? fallbackTask.contentText
+  );
+
+  if (operation.action === "DELETE") {
+    const deletedAt = normalizePositiveNumber(payload.deletedAt, updatedAt);
+    return {
+      ...fallbackTask,
+      version,
+      updatedAt: deletedAt,
+      deletedAt
+    };
+  }
+
+  return {
+    ...fallbackTask,
+    userId: typeof payload.userId === "string" ? payload.userId : fallbackTask.userId,
+    title:
+      typeof payload.title === "string" && payload.title.trim().length > 0
+        ? payload.title
+        : fallbackTask.title,
+    contentJson,
+    contentText,
+    priority: normalizePriority(payload.priority, fallbackTask.priority),
+    status: normalizeStatus(payload.status, fallbackTask.status),
+    ddlAt: normalizeNullableNumber(payload.ddlAt, fallbackTask.ddlAt),
+    version,
+    createdAt: normalizePositiveNumber(payload.createdAt, fallbackTask.createdAt),
+    updatedAt,
+    deletedAt: normalizeNullableNumber(payload.deletedAt, null)
+  };
+}
+
+function getOperationTieBreaker(operation: LocalSyncInboxRecord): number {
+  if (operation.action === "DELETE") {
+    return 3;
+  }
+
+  if (operation.action === "UPDATE") {
+    return 2;
+  }
+
+  return 1;
+}
+
+function shouldApplyIncomingTask(
+  currentTask: LocalTaskRecord | undefined,
+  incomingTask: LocalTaskRecord,
+  operation: LocalSyncInboxRecord
+): boolean {
+  if (!currentTask) {
+    return true;
+  }
+
+  if (incomingTask.updatedAt > currentTask.updatedAt) {
+    return true;
+  }
+
+  if (incomingTask.updatedAt < currentTask.updatedAt) {
+    return false;
+  }
+
+  if (incomingTask.version > currentTask.version) {
+    return true;
+  }
+
+  if (incomingTask.version < currentTask.version) {
+    return false;
+  }
+
+  return getOperationTieBreaker(operation) >= (currentTask.deletedAt === null ? 1 : 3);
+}
+
+export async function applyPendingRemoteOperations(userId: string): Promise<number> {
+  const pendingOperations = await listPendingRemoteOperations(userId);
+  if (pendingOperations.length === 0) {
+    return 0;
+  }
+
+  const appliedAt = Date.now();
+
+  await localDb.transaction("rw", localDb.tasks, localDb.syncInbox, async () => {
+    for (const operation of pendingOperations) {
+      if (operation.entityType !== "TASK") {
+        await localDb.syncInbox.update(operation.opId, { appliedAt });
+        continue;
+      }
+
+      const currentTask = await localDb.tasks.get(operation.entityId);
+      const incomingTask = buildIncomingTaskRecord(operation, currentTask);
+
+      if (shouldApplyIncomingTask(currentTask, incomingTask, operation)) {
+        await localDb.tasks.put(incomingTask);
+      }
+
+      await localDb.syncInbox.update(operation.opId, { appliedAt });
+    }
+  });
+
+  return pendingOperations.length;
+}

apps/web/src/services/sync-worker.ts

@@ -0,0 +1,142 @@
+import {
+  enqueueRemoteSyncOperations,
+  getLocalSyncState,
+  listPendingSyncOperations,
+  markSyncOperationsFailed,
+  markSyncOperationsSucceeded,
+  saveLocalSyncState
+} from "@/services/local-sync-repo";
+import { applyPendingRemoteOperations } from "@/services/sync-merge";
+import {
+  pullSyncOperations,
+  pushSyncOperations,
+  serializeSyncOperationForRequest
+} from "@/services/sync-api";
+import type { LocalOpLogRecord } from "@/services/local-db";
+
+const PUSH_BATCH_LIMIT = 20;
+const PUSH_BATCH_MAX_BYTES = 256 * 1024;
+const PULL_BATCH_LIMIT = 100;
+const MAX_PULL_PAGES_PER_CYCLE = 5;
+
+function estimateOperationBytes(operation: LocalOpLogRecord): number {
+  return new TextEncoder().encode(JSON.stringify(serializeSyncOperationForRequest(operation)))
+    .length;
+}
+
+function createPushBatch(operations: LocalOpLogRecord[]): LocalOpLogRecord[] {
+  const batch: LocalOpLogRecord[] = [];
+  let batchBytes = 0;
+
+  for (const operation of operations) {
+    const operationBytes = estimateOperationBytes(operation);
+    if (batch.length > 0 && batchBytes + operationBytes > PUSH_BATCH_MAX_BYTES) {
+      break;
+    }
+
+    batch.push(operation);
+    batchBytes += operationBytes;
+  }
+
+  return batch;
+}
+
+export type SyncCycleResult = {
+  pushedCount: number;
+  pulledCount: number;
+  appliedRemoteCount: number;
+  lastSyncedAt: number;
+  hasFailures: boolean;
+  failureMessage: string | null;
+};
+
+export async function runSyncWorkerCycle(userId: string): Promise<SyncCycleResult> {
+  const lastSyncedAt = Date.now();
+  let pushedCount = 0;
+  let pulledCount = 0;
+  let appliedRemoteCount = 0;
+  let hasFailures = false;
+  let failureMessage: string | null = null;
+
+  for (;;) {
+    const pendingCandidates = await listPendingSyncOperations(PUSH_BATCH_LIMIT);
+    if (pendingCandidates.length === 0) {
+      break;
+    }
+
+    const pendingOperations = createPushBatch(pendingCandidates);
+    const pushResult = await pushSyncOperations(userId, pendingOperations);
+    const syncedOperationIds = pushResult.results
+      .filter((result) => result.status === "accepted" || result.status === "duplicate")
+      .map((result) => result.opId);
+    const failedOperations = pushResult.results
+      .filter((result) => result.status === "failed")
+      .map((result) => ({
+        opId: result.opId,
+        errorMessage: result.reason ?? "同步失败"
+      }));
+
+    await markSyncOperationsSucceeded(syncedOperationIds, lastSyncedAt);
+    await markSyncOperationsFailed(failedOperations);
+
+    pushedCount += syncedOperationIds.length;
+
+    if (failedOperations.length > 0) {
+      hasFailures = true;
+      failureMessage = failedOperations[0]?.errorMessage ?? "同步失败";
+      break;
+    }
+
+    if (
+      pendingCandidates.length < PUSH_BATCH_LIMIT ||
+      pendingOperations.length < pendingCandidates.length
+    ) {
+      break;
+    }
+  }
+
+  const currentState = await getLocalSyncState(userId);
+  let nextCursor = currentState?.cursor ?? null;
+
+  for (let page = 0; page < MAX_PULL_PAGES_PER_CYCLE; page += 1) {
+    const pullResult = await pullSyncOperations({
+      userId,
+      cursor: nextCursor,
+      limit: PULL_BATCH_LIMIT
+    });
+
+    if (pullResult.items.length > 0) {
+      pulledCount += await enqueueRemoteSyncOperations(userId, pullResult.items);
+    }
+
+    nextCursor = pullResult.nextCursor;
+    await saveLocalSyncState({
+      userId,
+      cursor: nextCursor,
+      lastSyncedAt
+    });
+
+    if (!pullResult.hasMore) {
+      break;
+    }
+  }
+
+  if (currentState === undefined && nextCursor === null) {
+    await saveLocalSyncState({
+      userId,
+      cursor: null,
+      lastSyncedAt
+    });
+  }
+
+  appliedRemoteCount = await applyPendingRemoteOperations(userId);
+
+  return {
+    pushedCount,
+    pulledCount,
+    appliedRemoteCount,
+    lastSyncedAt,
+    hasFailures,
+    failureMessage
+  };
+}