perf(web-toolbar): reduce rich editor toolbar update cost

feat(web): 登录页独占布局并优化侧栏交互

README.md

@@ -74,9 +74,9 @@
 | 顺序 | 功能实现项（用户视角）             | 你会看到的效果                          | 状态 |
 | ---- | ---------------------------------- | --------------------------------------- | ---- |
 | 1    | 明确产品能力与交互流程             | 确认 TodoList 的核心使用方式与页面路径  | [x]  |
-| 2    | 实现基础登录（邮箱验证码）         | 可以注册/登录并进入主页面               | [ ]  |
+| 2    | 实现基础登录（邮箱验证码）         | 可以注册/登录并进入主页面               | [x]  |
-| 3    | 实现任务基础能力（增删改查）       | 可以创建、编辑、删除、完成任务          | [ ]  |
+| 3    | 实现任务基础能力（增删改查）       | 可以创建、编辑、删除、完成任务          | [x]  |
-| 4    | 实现富文本与媒体内容               | 任务详情可插入图片、视频、链接等内容    | [ ]  |
+| 4    | 实现富文本与媒体内容               | 任务详情可插入图片、视频、链接等内容    | [x]  |
 | 5    | 实现本地离线存储（Dexie）          | 无网时仍可打开并编辑任务                | [ ]  |
 | 6    | 实现云端同步与冲突处理             | 恢复网络后自动同步，冲突按规则合并      | [ ]  |
 | 7    | 实现提醒系统（邮件）               | DDL 临近时收到邮件提醒                  | [ ]  |

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/package.json

@@ -12,8 +12,17 @@
   "dependencies": {
     "@base-ui/react": "^1.3.0",
     "@fontsource-variable/geist": "^5.2.8",
+    "@tiptap/core": "^3.22.2",
+    "@tiptap/extension-image": "^3.22.2",
+    "@tiptap/extension-link": "^3.22.2",
+    "@tiptap/extension-youtube": "^3.22.2",
+    "@tiptap/react": "^3.22.2",
+    "@tiptap/starter-kit": "^3.22.2",
+    "browser-image-compression": "^2.0.2",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
+    "dexie": "^4.4.2",
+    "dexie-react-hooks": "^4.4.0",
     "lucide-react": "^1.7.0",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",

apps/web/src/components/editor/resizable-media-node-view.tsx

@@ -0,0 +1,283 @@
+import { useEffect, useRef, useState } from "react";
+import { NodeViewWrapper, type NodeViewProps } from "@tiptap/react";
+import { cn } from "@/lib/utils";
+
+type MediaAlign = "left" | "center" | "right";
+type MediaKind = "image" | "video" | "youtube";
+type ResizeSide = "left" | "right";
+
+type ResizableMediaNodeViewProps = NodeViewProps & {
+  mediaKind: MediaKind;
+};
+
+type HandleDescriptor = {
+  key: string;
+  side: ResizeSide;
+  className: string;
+};
+
+const HANDLE_DESCRIPTORS: HandleDescriptor[] = [
+  {
+    key: "top-left",
+    side: "left",
+    className: "-left-1.5 -top-1.5 cursor-ew-resize"
+  },
+  {
+    key: "bottom-left",
+    side: "left",
+    className: "-bottom-1.5 -left-1.5 cursor-ew-resize"
+  },
+  {
+    key: "top-right",
+    side: "right",
+    className: "-right-1.5 -top-1.5 cursor-ew-resize"
+  },
+  {
+    key: "bottom-right",
+    side: "right",
+    className: "-bottom-1.5 -right-1.5 cursor-ew-resize"
+  }
+];
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}
+
+function readWidthPercent(value: unknown): number {
+  const numericValue = typeof value === "number" ? value : Number(value);
+
+  if (Number.isNaN(numericValue)) {
+    return 100;
+  }
+
+  return clamp(numericValue, 25, 100);
+}
+
+function readAlign(value: unknown): MediaAlign {
+  if (value === "left" || value === "right" || value === "center") {
+    return value;
+  }
+
+  return "center";
+}
+
+function resolveAlignClass(align: MediaAlign): string {
+  if (align === "left") {
+    return "mr-auto";
+  }
+
+  if (align === "right") {
+    return "ml-auto";
+  }
+
+  return "mx-auto";
+}
+
+function isStringValue(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+export function ResizableMediaNodeView({
+  editor,
+  getPos,
+  mediaKind,
+  node,
+  selected,
+  updateAttributes
+}: ResizableMediaNodeViewProps) {
+  const [isResizing, setIsResizing] = useState(false);
+  const mediaFrameRef = useRef<HTMLDivElement | null>(null);
+  const cleanupResizeRef = useRef<(() => void) | null>(null);
+
+  const widthPercent = readWidthPercent(node.attrs.widthPercent);
+  const align = readAlign(node.attrs.align);
+  const src = isStringValue(node.attrs.src) ? node.attrs.src : "";
+  const alt = isStringValue(node.attrs.alt) ? node.attrs.alt : "";
+  const title = isStringValue(node.attrs.title) ? node.attrs.title : "";
+  const showControls = selected || isResizing;
+
+  useEffect(() => {
+    return () => {
+      cleanupResizeRef.current?.();
+    };
+  }, []);
+
+  function selectCurrentNode(): void {
+    const position = getPos();
+
+    if (typeof position !== "number") {
+      return;
+    }
+
+    editor.chain().focus().setNodeSelection(position).run();
+  }
+
+  function applyAlign(nextAlign: MediaAlign): void {
+    selectCurrentNode();
+    updateAttributes({ align: nextAlign });
+  }
+
+  function startResize(side: ResizeSide) {
+    return (event: React.PointerEvent<HTMLButtonElement>): void => {
+      event.preventDefault();
+      event.stopPropagation();
+
+      selectCurrentNode();
+
+      const mediaFrame = mediaFrameRef.current;
+      const editorRoot = mediaFrame?.closest(".ProseMirror") as HTMLElement | null;
+
+      if (!mediaFrame || !editorRoot) {
+        return;
+      }
+
+      const startX = event.clientX;
+      const startWidth = mediaFrame.getBoundingClientRect().width;
+      const maxWidth = Math.max(editorRoot.clientWidth - 24, 240);
+
+      const handlePointerMove = (moveEvent: PointerEvent): void => {
+        const delta = moveEvent.clientX - startX;
+        const resizedWidth = side === "right" ? startWidth + delta : startWidth - delta;
+        const nextWidth = clamp(resizedWidth, 180, maxWidth);
+        const nextWidthPercent = clamp((nextWidth / maxWidth) * 100, 25, 100);
+
+        updateAttributes({
+          widthPercent: Math.round(nextWidthPercent)
+        });
+      };
+
+      const handlePointerUp = (): void => {
+        cleanupResizeRef.current?.();
+        cleanupResizeRef.current = null;
+        setIsResizing(false);
+      };
+
+      cleanupResizeRef.current = () => {
+        window.removeEventListener("pointermove", handlePointerMove);
+        window.removeEventListener("pointerup", handlePointerUp);
+      };
+
+      window.addEventListener("pointermove", handlePointerMove);
+      window.addEventListener("pointerup", handlePointerUp, { once: true });
+      setIsResizing(true);
+    };
+  }
+
+  function renderMediaContent() {
+    if (mediaKind === "image") {
+      return (
+        <img
+          src={src}
+          alt={alt}
+          title={title}
+          draggable={false}
+          className="block h-auto w-full rounded-xl object-contain"
+        />
+      );
+    }
+
+    if (mediaKind === "youtube") {
+      return (
+        <div className="aspect-video w-full overflow-hidden rounded-xl bg-black">
+          <iframe
+            src={src}
+            title={title || "????"}
+            allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+            allowFullScreen
+            className="h-full w-full border-0"
+          />
+        </div>
+      );
+    }
+
+    return (
+      <video src={src} title={title} controls className="block h-auto w-full rounded-xl bg-black" />
+    );
+  }
+
+  return (
+    <NodeViewWrapper className="my-4" contentEditable={false}>
+      <div
+        ref={mediaFrameRef}
+        className={cn("relative transition-[width] duration-150", resolveAlignClass(align))}
+        style={{ width: `${widthPercent}%` }}
+        onMouseDown={selectCurrentNode}
+      >
+        {showControls ? (
+          <div className="absolute left-0 top-0 z-20 flex -translate-y-[calc(100%+8px)] items-center gap-1 rounded-lg border border-border bg-card/95 px-2 py-1 shadow-sm backdrop-blur">
+            <button
+              type="button"
+              className={cn(
+                "rounded px-1.5 py-0.5 text-[11px] transition-colors",
+                align === "left"
+                  ? "bg-primary/10 text-primary"
+                  : "text-muted-foreground hover:bg-muted hover:text-foreground"
+              )}
+              onClick={() => applyAlign("left")}
+            >
+              ?
+            </button>
+            <button
+              type="button"
+              className={cn(
+                "rounded px-1.5 py-0.5 text-[11px] transition-colors",
+                align === "center"
+                  ? "bg-primary/10 text-primary"
+                  : "text-muted-foreground hover:bg-muted hover:text-foreground"
+              )}
+              onClick={() => applyAlign("center")}
+            >
+              ?
+            </button>
+            <button
+              type="button"
+              className={cn(
+                "rounded px-1.5 py-0.5 text-[11px] transition-colors",
+                align === "right"
+                  ? "bg-primary/10 text-primary"
+                  : "text-muted-foreground hover:bg-muted hover:text-foreground"
+              )}
+              onClick={() => applyAlign("right")}
+            >
+              ?
+            </button>
+            <span className="pl-1 text-[11px] text-muted-foreground">{widthPercent}%</span>
+          </div>
+        ) : null}
+
+        <div
+          className={cn(
+            "relative rounded-xl border bg-muted/20 transition-colors",
+            showControls ? "border-primary/40 ring-2 ring-primary/20" : "border-border/70"
+          )}
+        >
+          {(mediaKind === "video" || mediaKind === "youtube") && !showControls ? (
+            <button
+              type="button"
+              aria-label="????"
+              className="absolute inset-0 z-10 rounded-xl"
+              onClick={selectCurrentNode}
+            />
+          ) : null}
+
+          {renderMediaContent()}
+        </div>
+
+        {showControls
+          ? HANDLE_DESCRIPTORS.map((handle) => (
+              <button
+                key={handle.key}
+                type="button"
+                aria-label="??????"
+                className={cn(
+                  "absolute z-20 h-3 w-3 rounded-full border border-background bg-primary shadow-sm",
+                  handle.className
+                )}
+                onPointerDown={startResize(handle.side)}
+              />
+            ))
+          : null}
+      </div>
+    </NodeViewWrapper>
+  );
+}

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

@@ -0,0 +1,608 @@
+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, useEditorState } from "@tiptap/react";
+import { ResizableImage } from "@/extensions/resizable-image";
+import { ResizableVideo } from "@/extensions/resizable-video";
+import { ResizableYoutube } from "@/extensions/resizable-youtube";
+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;
+  textFallback: string;
+  onChange: (payload: { json: string | null; text: string }) => void;
+};
+
+type ToolbarButtonProps = {
+  label: string;
+  disabled?: boolean;
+  active?: boolean;
+  onClick: () => void;
+};
+
+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"
+      className={cn(
+        "rounded-md border px-2 py-1 text-xs transition-colors",
+        active
+          ? "border-primary/50 bg-primary/10 text-primary"
+          : "border-border bg-background text-foreground hover:border-primary/25 hover:bg-primary/5",
+        disabled && "cursor-not-allowed opacity-50"
+      )}
+      onClick={onClick}
+      disabled={disabled}
+    >
+      {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
+): JSONContent | string {
+  if (valueJson) {
+    try {
+      return JSON.parse(valueJson) as JSONContent;
+    } catch {
+      return textFallback;
+    }
+  }
+
+  return textFallback;
+}
+
+function parseEditorJson(valueJson: string): JSONContent | null {
+  try {
+    return JSON.parse(valueJson) as JSONContent;
+  } catch {
+    return null;
+  }
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) {
+    return `${bytes} B`;
+  }
+
+  if (bytes < 1024 * 1024) {
+    return `${(bytes / 1024).toFixed(1)} KB`;
+  }
+
+  return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+}
+
+function isYoutubeUrl(url: string): boolean {
+  return /(youtube\.com|youtu\.be)/i.test(url);
+}
+
+function readFileAsDataUrl(file: File): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+
+    reader.onload = () => {
+      if (typeof reader.result === "string") {
+        resolve(reader.result);
+        return;
+      }
+
+      reject(new Error("读取文件失败"));
+    };
+
+    reader.onerror = () => {
+      reject(new Error("读取文件失败"));
+    };
+
+    reader.readAsDataURL(file);
+  });
+}
+
+function createUploadToken(): string {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+
+  return `upload-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+}
+
+function replaceMediaSourceByUploadToken(
+  editor: TiptapEditor,
+  uploadToken: string,
+  attributes: Record<string, string | number | null>
+): boolean {
+  return editor.commands.command(({ tr, state }) => {
+    let updated = false;
+
+    state.doc.descendants((node, position) => {
+      if (node.attrs.uploadToken !== uploadToken) {
+        return true;
+      }
+
+      tr.setNodeMarkup(position, undefined, {
+        ...node.attrs,
+        ...attributes
+      });
+      updated = true;
+      return false;
+    });
+
+    return updated;
+  });
+}
+
+function removeMediaByUploadToken(editor: TiptapEditor, uploadToken: string): boolean {
+  return editor.commands.command(({ tr, state }) => {
+    let removed = false;
+
+    state.doc.descendants((node, position) => {
+      if (node.attrs.uploadToken !== uploadToken) {
+        return true;
+      }
+
+      tr.delete(position, position + node.nodeSize);
+      removed = true;
+      return false;
+    });
+
+    return removed;
+  });
+}
+
+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: [
+      StarterKit,
+      Link.configure({
+        openOnClick: true,
+        autolink: true,
+        linkOnPaste: true,
+        HTMLAttributes: {
+          rel: "noopener noreferrer",
+          target: "_blank"
+        }
+      }),
+      ResizableImage,
+      ResizableVideo,
+      ResizableYoutube.configure({
+        controls: true
+      })
+    ],
+    content: resolveEditorContent(valueJson, textFallback),
+    editorProps: {
+      attributes: {
+        class:
+          "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 }) {
+      scheduleEditorChange(currentEditor);
+    },
+    onBlur({ editor: currentEditor }) {
+      if (changeTimeoutRef.current !== null) {
+        window.clearTimeout(changeTimeoutRef.current);
+        changeTimeoutRef.current = null;
+      }
+
+      flushEditorChange(currentEditor);
+    }
+  });
+
+  useEffect(() => {
+    if (!editor) {
+      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);
+
+      if (!nextJson) {
+        if (editor.getText() !== textFallback) {
+          editor.commands.setContent(textFallback, { emitUpdate: false });
+        }
+        return;
+      }
+
+      editor.commands.setContent(nextJson, { emitUpdate: false });
+      lastSyncedPayloadRef.current = {
+        json: valueJson,
+        text: textFallback
+      };
+      return;
+    }
+
+    if (editor.getText() !== textFallback) {
+      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 = "";
+
+    if (!file || !editor) {
+      return;
+    }
+
+    if (file.size > MAX_IMAGE_UPLOAD_BYTES) {
+      setMediaHint(`图片过大，请选择小于 ${formatBytes(MAX_IMAGE_UPLOAD_BYTES)} 的文件。`);
+      return;
+    }
+
+    const uploadToken = createUploadToken();
+    const previewUrl = URL.createObjectURL(file);
+
+    editor
+      .chain()
+      .focus()
+      .insertContent({
+        type: "image",
+        attrs: {
+          src: previewUrl,
+          alt: file.name,
+          title: file.name,
+          widthPercent: 100,
+          align: "center",
+          uploadToken
+        }
+      })
+      .run();
+
+    try {
+      const compressedImage = await imageCompression(file, {
+        maxSizeMB: 1,
+        maxWidthOrHeight: 1920,
+        useWebWorker: true,
+        initialQuality: 0.8
+      });
+      const imageSource = await imageCompression.getDataUrlFromFile(compressedImage);
+
+      replaceMediaSourceByUploadToken(editor, uploadToken, {
+        src: imageSource,
+        alt: file.name,
+        title: file.name,
+        uploadToken: null
+      });
+      setMediaHint(null);
+    } catch {
+      removeMediaByUploadToken(editor, uploadToken);
+      setMediaHint("图片处理失败，请重试。");
+    } finally {
+      URL.revokeObjectURL(previewUrl);
+    }
+  }
+
+  async function handleVideoFileChange(event: ChangeEvent<HTMLInputElement>): Promise<void> {
+    const file = event.target.files?.[0];
+    event.target.value = "";
+
+    if (!file || !editor) {
+      return;
+    }
+
+    if (file.size > MAX_VIDEO_UPLOAD_BYTES) {
+      setMediaHint(`视频过大，请选择小于 ${formatBytes(MAX_VIDEO_UPLOAD_BYTES)} 的文件。`);
+      return;
+    }
+
+    const uploadToken = createUploadToken();
+    const previewUrl = URL.createObjectURL(file);
+
+    editor
+      .chain()
+      .focus()
+      .insertContent({
+        type: "video",
+        attrs: {
+          src: previewUrl,
+          title: file.name,
+          widthPercent: 100,
+          align: "center",
+          uploadToken
+        }
+      })
+      .run();
+
+    try {
+      const videoSource = await readFileAsDataUrl(file);
+
+      replaceMediaSourceByUploadToken(editor, uploadToken, {
+        src: videoSource,
+        title: file.name,
+        uploadToken: null
+      });
+      setMediaHint(null);
+    } catch {
+      removeMediaByUploadToken(editor, uploadToken);
+      setMediaHint("视频处理失败，请重试。");
+    } finally {
+      URL.revokeObjectURL(previewUrl);
+    }
+  }
+
+  function handleInsertImageUrl(): void {
+    if (!editor) {
+      return;
+    }
+
+    const url = window.prompt("请输入图片 URL");
+
+    if (!url) {
+      return;
+    }
+
+    editor
+      .chain()
+      .focus()
+      .setImage({
+        src: url
+      })
+      .run();
+    setMediaHint(null);
+  }
+
+  function handleInsertVideoUrl(): void {
+    if (!editor) {
+      return;
+    }
+
+    const url = window.prompt("请输入视频 URL");
+
+    if (!url) {
+      return;
+    }
+
+    if (isYoutubeUrl(url)) {
+      editor
+        .chain()
+        .focus()
+        .setYoutubeVideo({
+          src: url,
+          width: 640,
+          height: 360
+        })
+        .run();
+      setMediaHint(null);
+      return;
+    }
+
+    editor
+      .chain()
+      .focus()
+      .setVideo({
+        src: url
+      })
+      .run();
+    setMediaHint(null);
+  }
+
+  return (
+    <div>
+      <input
+        ref={imageInputRef}
+        type="file"
+        accept="image/*"
+        className="hidden"
+        onChange={handleImageFileChange}
+      />
+      <input
+        ref={videoInputRef}
+        type="file"
+        accept="video/*"
+        className="hidden"
+        onChange={handleVideoFileChange}
+      />
+
+      <EditorToolbar
+        editor={editor}
+        onInsertImageUrl={handleInsertImageUrl}
+        onOpenImageUpload={() => imageInputRef.current?.click()}
+        onInsertVideoUrl={handleInsertVideoUrl}
+        onOpenVideoUpload={() => videoInputRef.current?.click()}
+        onSetLink={() => {
+          if (!editor) {
+            return;
+          }
+
+          const url = window.prompt("\u8bf7\u8f93\u5165\u94fe\u63a5\u5730\u5740");
+
+          if (!url) {
+            return;
+          }
+
+          editor.chain().focus().setLink({ href: url }).run();
+        }}
+      />
+      <EditorContent editor={editor} />
+      {mediaHint ? <p className="mt-2 text-xs text-muted-foreground">{mediaHint}</p> : null}
+    </div>
+  );
+});

apps/web/src/extensions/resizable-image.tsx

@@ -0,0 +1,42 @@
+import Image from "@tiptap/extension-image";
+import { ReactNodeViewRenderer } from "@tiptap/react";
+import { ResizableMediaNodeView } from "@/components/editor/resizable-media-node-view";
+
+export const ResizableImage = Image.extend({
+  addAttributes() {
+    return {
+      ...(this.parent?.() ?? {}),
+      widthPercent: {
+        default: 100,
+        parseHTML: (element: HTMLElement) =>
+          Number(element.getAttribute("data-width-percent") ?? 100),
+        renderHTML: (attributes: { widthPercent?: number }) => ({
+          "data-width-percent": attributes.widthPercent ?? 100
+        })
+      },
+      align: {
+        default: "center",
+        parseHTML: (element: HTMLElement) => element.getAttribute("data-align") ?? "center",
+        renderHTML: (attributes: { align?: string }) => ({
+          "data-align": attributes.align ?? "center"
+        })
+      },
+      uploadToken: {
+        default: null,
+        parseHTML: (element: HTMLElement) => element.getAttribute("data-upload-token"),
+        renderHTML: (attributes: { uploadToken?: string | null }) =>
+          attributes.uploadToken
+            ? {
+                "data-upload-token": attributes.uploadToken
+              }
+            : {}
+      }
+    };
+  },
+
+  addNodeView() {
+    return ReactNodeViewRenderer((props) => (
+      <ResizableMediaNodeView {...props} mediaKind="image" />
+    ));
+  }
+});

apps/web/src/extensions/resizable-video.tsx

@@ -0,0 +1,99 @@
+import { Node, mergeAttributes } from "@tiptap/core";
+import { ReactNodeViewRenderer } from "@tiptap/react";
+import { ResizableMediaNodeView } from "@/components/editor/resizable-media-node-view";
+
+declare module "@tiptap/core" {
+  interface Commands<ReturnType> {
+    video: {
+      setVideo: (attributes: {
+        src: string;
+        title?: string | null;
+        widthPercent?: number;
+        align?: "left" | "center" | "right";
+      }) => ReturnType;
+    };
+  }
+}
+
+export const ResizableVideo = Node.create({
+  name: "video",
+  group: "block",
+  atom: true,
+  selectable: true,
+  draggable: true,
+
+  addAttributes() {
+    return {
+      src: {
+        default: null
+      },
+      title: {
+        default: null
+      },
+      widthPercent: {
+        default: 100,
+        parseHTML: (element: HTMLElement) =>
+          Number(element.getAttribute("data-width-percent") ?? 100),
+        renderHTML: (attributes: { widthPercent?: number }) => ({
+          "data-width-percent": attributes.widthPercent ?? 100
+        })
+      },
+      align: {
+        default: "center",
+        parseHTML: (element: HTMLElement) => element.getAttribute("data-align") ?? "center",
+        renderHTML: (attributes: { align?: string }) => ({
+          "data-align": attributes.align ?? "center"
+        })
+      },
+      uploadToken: {
+        default: null,
+        parseHTML: (element: HTMLElement) => element.getAttribute("data-upload-token"),
+        renderHTML: (attributes: { uploadToken?: string | null }) =>
+          attributes.uploadToken
+            ? {
+                "data-upload-token": attributes.uploadToken
+              }
+            : {}
+      }
+    };
+  },
+
+  parseHTML() {
+    return [
+      {
+        tag: "video[src]"
+      }
+    ];
+  },
+
+  renderHTML({ HTMLAttributes }) {
+    return [
+      "video",
+      mergeAttributes(HTMLAttributes, {
+        controls: "true"
+      })
+    ];
+  },
+
+  addCommands() {
+    return {
+      setVideo:
+        (attributes) =>
+        ({ commands }) =>
+          commands.insertContent({
+            type: this.name,
+            attrs: {
+              align: "center",
+              widthPercent: 100,
+              ...attributes
+            }
+          })
+    };
+  },
+
+  addNodeView() {
+    return ReactNodeViewRenderer((props) => (
+      <ResizableMediaNodeView {...props} mediaKind="video" />
+    ));
+  }
+});

apps/web/src/extensions/resizable-youtube.tsx

@@ -0,0 +1,32 @@
+import Youtube from "@tiptap/extension-youtube";
+import { ReactNodeViewRenderer } from "@tiptap/react";
+import { ResizableMediaNodeView } from "@/components/editor/resizable-media-node-view";
+
+export const ResizableYoutube = Youtube.extend({
+  addAttributes() {
+    return {
+      ...(this.parent?.() ?? {}),
+      widthPercent: {
+        default: 100,
+        parseHTML: (element: HTMLElement) =>
+          Number(element.getAttribute("data-width-percent") ?? 100),
+        renderHTML: (attributes: { widthPercent?: number }) => ({
+          "data-width-percent": attributes.widthPercent ?? 100
+        })
+      },
+      align: {
+        default: "center",
+        parseHTML: (element: HTMLElement) => element.getAttribute("data-align") ?? "center",
+        renderHTML: (attributes: { align?: string }) => ({
+          "data-align": attributes.align ?? "center"
+        })
+      }
+    };
+  },
+
+  addNodeView() {
+    return ReactNodeViewRenderer((props) => (
+      <ResizableMediaNodeView {...props} mediaKind="youtube" />
+    ));
+  }
+});

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,33 +1,953 @@
-import type { WebSession } from "@/services/session-storage";
+import { memo, useCallback, useEffect, useRef, useState } from "react";
+import { useLiveQuery } from "dexie-react-hooks";
+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";
+import type {
+  LocalTaskDraftRecord,
+  LocalTaskPriority,
+  LocalTaskRecord,
+  LocalTaskStatus
+} from "@/services/local-db";
+import {
+  deleteLocalTaskDraft,
+  getLocalTaskDraft,
+  saveLocalTaskDraft
+} from "@/services/local-task-draft-repo";
+import {
+  createLocalTask,
+  deleteLocalTask,
+  getLocalTaskById,
+  listLocalTasksByUser,
+  updateLocalTask
+} from "@/services/local-task-repo";
+import { formatStorageSize, getStorageQuotaSnapshot } from "@/services/storage-quota";
+import type { WebSession } from "@/services/session-storage";
 
 type TodoShellPageProps = {
   session: WebSession | null;
 };
 
-export function TodoShellPage({ session }: TodoShellPageProps) {
+type TaskFormState = {
+  title: 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: "",
+  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: "中" },
+  { value: "HIGH", label: "高" },
+  { value: "URGENT", label: "紧急" }
+];
+
+const STATUS_OPTIONS: Array<{ value: LocalTaskStatus; label: string }> = [
+  { value: "TODO", label: "待办" },
+  { value: "IN_PROGRESS", label: "进行中" },
+  { value: "DONE", label: "已完成" },
+  { value: "ARCHIVED", label: "已归档" }
+];
+
+const PRIORITY_LABEL_MAP: Record<LocalTaskPriority, string> = {
+  LOW: "低",
+  MEDIUM: "中",
+  HIGH: "高",
+  URGENT: "紧急"
+};
+
+const STATUS_LABEL_MAP: Record<LocalTaskStatus, string> = {
+  TODO: "待办",
+  IN_PROGRESS: "进行中",
+  DONE: "已完成",
+  ARCHIVED: "已归档"
+};
+
+function toDatetimeLocalValue(timestamp: number | null): string {
+  if (timestamp === null) {
+    return "";
+  }
+
+  const date = new Date(timestamp);
+  const timezoneOffset = date.getTimezoneOffset() * 60_000;
+  return new Date(timestamp - timezoneOffset).toISOString().slice(0, 16);
+}
+
+function parseDatetimeLocalValue(value: string): number | null {
+  if (!value) {
+    return null;
+  }
+
+  const parsed = new Date(value).getTime();
+  if (Number.isNaN(parsed)) {
+    return null;
+  }
+
+  return parsed;
+}
+
+function formatUpdatedAt(timestamp: number): string {
+  return new Date(timestamp).toLocaleString("zh-CN", {
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit"
+  });
+}
+
+function createFormStateFromTask(task: LocalTaskRecord): TaskFormState {
+  return {
+    title: task.title,
+    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,
+    priority: draft.priority,
+    status: draft.status,
+    ddlInput: draft.ddlInput
+  };
+}
+
+function createEditorStateFromDraft(draft: LocalTaskDraftRecord): TaskEditorState {
+  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 (
-    <div className="rounded-2xl border border-border bg-card/90 p-6 shadow-[0_24px_70px_-42px_hsl(var(--primary)/0.6)] backdrop-blur">
+    <section
-      <h1 className="text-2xl font-semibold text-foreground">TodoList 工作台</h1>
+      className={cn(
-      <p className="mt-2 text-sm text-muted-foreground">
+        "rounded-[1.75rem] border px-4 py-4 shadow-[0_24px_70px_-42px_hsl(var(--primary)/0.38)] backdrop-blur md:px-5",
-        {session ? `当前登录邮箱：${session.user.email}` : "当前未建立登录会话，请先完成登录。"}
+        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>
-      <div className="mt-6 grid gap-3 sm:grid-cols-3">
+      ) : null}
-        <div className="rounded-xl border border-border bg-muted/40 p-4">
+
-          <p className="text-xs text-muted-foreground">今日重点</p>
+      {tasks.length === 0 ? (
-          <p className="mt-2 text-lg font-semibold text-foreground">待接入</p>
+        <p className="rounded-xl border border-dashed border-border bg-muted/40 p-4 text-sm text-muted-foreground">
-        </div>
+          还没有任务，点击右上角“新建任务”。
-        <div className="rounded-xl border border-border bg-muted/40 p-4">
-          <p className="text-xs text-muted-foreground">临近截止</p>
-          <p className="mt-2 text-lg font-semibold text-foreground">待接入</p>
-        </div>
-        <div className="rounded-xl border border-border bg-muted/40 p-4">
-          <p className="text-xs text-muted-foreground">任务分析</p>
-          <p className="mt-2 text-lg font-semibold text-foreground">待接入</p>
-        </div>
-      </div>
-      <p className="mt-4 text-xs 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);
+  const [saving, setSaving] = useState(false);
+  const [creating, setCreating] = useState(false);
+  const [deleting, setDeleting] = useState(false);
+  const [feedback, setFeedback] = useState<FeedbackNotice | null>(null);
+  const [feedbackVisible, setFeedbackVisible] = useState(false);
+  const [draftReadyTaskId, setDraftReadyTaskId] = useState<string | null>(null);
+  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 ?? "";
+
+  const tasks = useLiveQuery(async () => {
+    if (!userId) {
+      return [];
+    }
+
+    return listLocalTasksByUser(userId);
+  }, [userId]);
+
+  const quotaSnapshot = useLiveQuery(async () => {
+    if (!userId) {
+      return null;
+    }
+
+    return getStorageQuotaSnapshot(userId);
+  }, [userId]);
+
+  const selectedTask = useLiveQuery(async () => {
+    if (!selectedTaskId) {
+      return undefined;
+    }
+
+    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);
+      return;
+    }
+
+    if (!selectedTaskId) {
+      setSelectedTaskId(tasks[0].id);
+      return;
+    }
+
+    const exists = tasks.some((task) => task.id === selectedTaskId);
+    if (!exists) {
+      setSelectedTaskId(tasks[0].id);
+    }
+  }, [selectedTaskId, tasks]);
+
+  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, DEFAULT_EDITOR_STATE);
+      return;
+    }
+
+    if (!selectedTask) {
+      return;
+    }
+
+    let cancelled = false;
+    const currentTask = selectedTask;
+
+    async function hydrateFormState(): Promise<void> {
+      const persistedTaskState = createFormStateFromTask(currentTask);
+      const persistedEditorState = createEditorStateFromTask(currentTask);
+      const localDraft = await getLocalTaskDraft(currentTask.id);
+
+      if (cancelled) {
+        return;
+      }
+
+      const nextFormState = 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);
+    }
+
+    void hydrateFormState();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [selectedTask, selectedTaskId]);
+
+  useEffect(() => {
+    scheduleDraftPersist();
+  }, [formState, scheduleDraftPersist]);
+
+  useEffect(() => {
+    return () => {
+      if (draftPersistTimeoutRef.current !== null) {
+        window.clearTimeout(draftPersistTimeoutRef.current);
+      }
+    };
+  }, []);
+
+  const showFeedback = useCallback((message: string, tone: FeedbackNotice["tone"]): void => {
+    setFeedback({ message, tone });
+  }, []);
+
+  useEffect(() => {
+    if (!feedback) {
+      setFeedbackVisible(false);
+      return;
+    }
+
+    setFeedbackVisible(false);
+    const enterAnimationId = window.requestAnimationFrame(() => {
+      setFeedbackVisible(true);
+    });
+
+    const visibleDuration = feedback.tone === "success" ? 2200 : 3200;
+    const hideTimeoutId = window.setTimeout(() => {
+      setFeedbackVisible(false);
+    }, visibleDuration);
+
+    const cleanupTimeoutId = window.setTimeout(() => {
+      setFeedback((currentFeedback) =>
+        currentFeedback?.message === feedback.message ? null : currentFeedback
+      );
+    }, visibleDuration + 260);
+
+    return () => {
+      window.cancelAnimationFrame(enterAnimationId);
+      window.clearTimeout(hideTimeoutId);
+      window.clearTimeout(cleanupTimeoutId);
+    };
+  }, [feedback]);
+
+  function renderFeedbackBanner() {
+    if (!feedback) {
+      return null;
+    }
+
+    return (
+      <div className="pointer-events-none fixed inset-x-0 top-0 z-50 flex justify-center px-4 pt-4">
+        <div
+          className={cn(
+            "flex min-w-[240px] max-w-[520px] items-center gap-3 rounded-2xl border px-4 py-3 shadow-[0_18px_50px_-24px_hsl(var(--foreground)/0.35)] backdrop-blur transition-all duration-300 ease-out",
+            feedbackVisible ? "translate-y-0 opacity-100" : "-translate-y-6 opacity-0",
+            feedback.tone === "success"
+              ? "border-emerald-200 bg-emerald-50/95 text-emerald-900"
+              : "border-destructive/30 bg-background/95 text-foreground"
+          )}
+        >
+          {feedback.tone === "success" ? (
+            <CheckCircle2 className="h-5 w-5 shrink-0 text-emerald-600" />
+          ) : (
+            <CircleAlert className="h-5 w-5 shrink-0 text-destructive" />
+          )}
+          <p className="text-sm font-medium">{feedback.message}</p>
+        </div>
       </div>
     );
   }
+
+  const handleCreateTask = useCallback(async (): Promise<void> => {
+    if (creating || !userId) {
+      return;
+    }
+
+    try {
+      setCreating(true);
+      const createdTask = await createLocalTask({ userId });
+      setSelectedTaskId(createdTask.id);
+      showFeedback("已创建新任务。", "success");
+    } finally {
+      setCreating(false);
+    }
+  }, [creating, showFeedback, userId]);
+
+  const handleSaveTask = useCallback(async (): Promise<void> => {
+    if (!selectedTaskId || saving) {
+      return;
+    }
+
+    try {
+      setSaving(true);
+      const currentEditorState = editorStateRef.current;
+      const updatedTask = await updateLocalTask({
+        id: selectedTaskId,
+        title: formState.title,
+        contentText: currentEditorState.contentText || null,
+        contentJson: currentEditorState.contentJson,
+        priority: formState.priority,
+        status: formState.status,
+        ddlAt: parseDatetimeLocalValue(formState.ddlInput)
+      });
+
+      if (!updatedTask) {
+        showFeedback("任务不存在或已被删除。", "error");
+        return;
+      }
+
+      savedTaskSnapshotRef.current = serializeFormState(
+        createFormStateFromTask(updatedTask),
+        createEditorStateFromTask(updatedTask)
+      );
+      await deleteLocalTaskDraft(selectedTaskId);
+      showFeedback("任务已保存。", "success");
+    } finally {
+      setSaving(false);
+    }
+  }, [formState, saving, selectedTaskId, showFeedback]);
+
+  const handleDeleteTask = useCallback(async (): Promise<void> => {
+    if (!selectedTaskId || deleting) {
+      return;
+    }
+
+    try {
+      setDeleting(true);
+      const deleted = await deleteLocalTask(selectedTaskId);
+      if (!deleted) {
+        showFeedback("任务已不存在。", "error");
+        return;
+      }
+
+      await deleteLocalTaskDraft(selectedTaskId);
+      showFeedback("任务已删除。", "success");
+    } finally {
+      setDeleting(false);
+    }
+  }, [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";
+
+      if (!isSaveShortcut) {
+        return;
+      }
+
+      event.preventDefault();
+
+      if (!selectedTaskId || saving) {
+        return;
+      }
+
+      void handleSaveTask();
+    }
+
+    window.addEventListener("keydown", handleKeydown);
+    return () => {
+      window.removeEventListener("keydown", handleKeydown);
+    };
+  }, [handleSaveTask, saving, selectedTaskId]);
+
+  if (!session) {
+    return (
+      <>
+        {renderFeedbackBanner()}
+        <div className="rounded-2xl border border-border bg-card/90 p-6 text-sm text-muted-foreground">
+          当前未建立登录会话，请先完成登录。
+        </div>
+      </>
+    );
+  }
+
+  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)]">
+          <TaskListPanel
+            tasks={taskList}
+            selectedTaskId={selectedTaskId}
+            quotaSnapshot={quotaPanelSnapshot}
+            creating={creating}
+            onCreateTask={handleCreateTask}
+            onSelectTask={handleSelectTask}
+          />
+
+          <TaskDetailPanel
+            selectedTaskId={selectedTaskId}
+            selectedTask={selectedTask}
+            formState={formState}
+            editorKey={editorKey}
+            editorSeedState={editorSeedState}
+            saving={saving}
+            deleting={deleting}
+            onSaveTask={handleSaveTask}
+            onDeleteTask={handleDeleteTask}
+            onTitleChange={handleTitleChange}
+            onStatusChange={handleStatusChange}
+            onPriorityChange={handlePriorityChange}
+            onDdlChange={handleDdlChange}
+            onEditorChange={handleEditorChange}
+          />
+        </div>
+      </div>
+    </>
+  );
+}

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

@@ -0,0 +1,128 @@
+import Dexie, { type Table } from "dexie";
+
+export type LocalTaskPriority = "LOW" | "MEDIUM" | "HIGH" | "URGENT";
+
+export type LocalTaskStatus = "TODO" | "IN_PROGRESS" | "DONE" | "ARCHIVED";
+
+export type SyncEntityType = "TASK";
+
+export type SyncActionType = "CREATE" | "UPDATE" | "DELETE";
+
+export type LocalTaskRecord = {
+  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;
+};
+
+export type LocalOpLogRecord = {
+  opId: string;
+  entityId: string;
+  entityType: SyncEntityType;
+  action: SyncActionType;
+  payload: string;
+  clientTs: number;
+  deviceId: string;
+  syncedAt: number | null;
+  retryCount: number;
+  errorMessage: string | null;
+};
+
+export type LocalTaskDraftRecord = {
+  taskId: string;
+  userId: string;
+  title: string;
+  contentJson: string | null;
+  contentText: string;
+  priority: LocalTaskPriority;
+  status: LocalTaskStatus;
+  ddlInput: string;
+  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");
+
+    this.version(1).stores({
+      tasks: "&id,userId,status,priority,ddlAt,updatedAt,deletedAt",
+      op_logs: "&opId,entityId,entityType,action,clientTs,syncedAt"
+    });
+
+    this.version(2).stores({
+      tasks: "&id,userId,status,priority,ddlAt,updatedAt,deletedAt",
+      op_logs: "&opId,entityId,entityType,action,clientTs,syncedAt",
+      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");
+  }
+}
+
+export const localDb = new TodoLocalDb();

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-draft-repo.ts

@@ -0,0 +1,32 @@
+import { localDb, type LocalTaskDraftRecord } from "@/services/local-db";
+
+export type SaveLocalTaskDraftInput = {
+  taskId: string;
+  userId: string;
+  title: string;
+  contentJson: string | null;
+  contentText: string;
+  priority: LocalTaskDraftRecord["priority"];
+  status: LocalTaskDraftRecord["status"];
+  ddlInput: string;
+};
+
+export async function getLocalTaskDraft(taskId: string): Promise<LocalTaskDraftRecord | undefined> {
+  return localDb.taskDrafts.get(taskId);
+}
+
+export async function saveLocalTaskDraft(
+  input: SaveLocalTaskDraftInput
+): Promise<LocalTaskDraftRecord> {
+  const draft: LocalTaskDraftRecord = {
+    ...input,
+    updatedAt: Date.now()
+  };
+
+  await localDb.taskDrafts.put(draft);
+  return draft;
+}
+
+export async function deleteLocalTaskDraft(taskId: string): Promise<void> {
+  await localDb.taskDrafts.delete(taskId);
+}

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

@@ -0,0 +1,219 @@
+import {
+  localDb,
+  type LocalOpLogRecord,
+  type LocalTaskPriority,
+  type LocalTaskRecord,
+  type LocalTaskStatus,
+  type SyncActionType
+} from "@/services/local-db";
+
+const DEVICE_ID_STORAGE_KEY = "todolist.web.device-id";
+
+export type CreateLocalTaskInput = {
+  userId: string;
+  title?: string;
+};
+
+export type UpdateLocalTaskInput = {
+  id: string;
+  title?: string;
+  contentText?: string | null;
+  contentJson?: string | null;
+  priority?: LocalTaskPriority;
+  status?: LocalTaskStatus;
+  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) {
+    return savedDeviceId;
+  }
+
+  const nextDeviceId = crypto.randomUUID();
+  window.localStorage.setItem(DEVICE_ID_STORAGE_KEY, nextDeviceId);
+  return nextDeviceId;
+}
+
+function createOpLogRecord(
+  entityId: string,
+  action: SyncActionType,
+  payload: string
+): LocalOpLogRecord {
+  return {
+    opId: crypto.randomUUID(),
+    entityId,
+    entityType: "TASK",
+    action,
+    payload,
+    clientTs: Date.now(),
+    deviceId: resolveDeviceId(),
+    syncedAt: null,
+    retryCount: 0,
+    errorMessage: null
+  };
+}
+
+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
+    .filter((task) => task.deletedAt === null)
+    .sort((left, right) => right.updatedAt - left.updatedAt);
+}
+
+export async function getLocalTaskById(id: string): Promise<LocalTaskRecord | undefined> {
+  const task = await localDb.tasks.get(id);
+  if (!task || task.deletedAt !== null) {
+    return undefined;
+  }
+
+  return task;
+}
+
+export async function createLocalTask(input: CreateLocalTaskInput): Promise<LocalTaskRecord> {
+  const now = Date.now();
+  const task: LocalTaskRecord = {
+    id: crypto.randomUUID(),
+    userId: input.userId,
+    title: input.title?.trim() ? input.title.trim() : "未命名任务",
+    contentJson: null,
+    contentText: null,
+    priority: "MEDIUM",
+    status: "TODO",
+    ddlAt: null,
+    version: 1,
+    createdAt: now,
+    updatedAt: now,
+    deletedAt: null
+  };
+
+  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);
+    await localDb.opLogs.add(opLog);
+  });
+
+  return task;
+}
+
+export async function updateLocalTask(
+  input: UpdateLocalTaskInput
+): Promise<LocalTaskRecord | undefined> {
+  const currentTask = await getLocalTaskById(input.id);
+  if (!currentTask) {
+    return undefined;
+  }
+
+  const nextVersion = currentTask.version + 1;
+  const nextTask: LocalTaskRecord = {
+    ...currentTask,
+    title: input.title !== undefined ? input.title.trim() || "未命名任务" : currentTask.title,
+    contentText: input.contentText !== undefined ? input.contentText : currentTask.contentText,
+    contentJson: input.contentJson !== undefined ? input.contentJson : currentTask.contentJson,
+    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",
+    createSyncTaskPayload({
+      title: nextTask.title,
+      contentJson: nextTask.contentJson,
+      contentText: nextTask.contentText,
+      priority: nextTask.priority,
+      status: nextTask.status,
+      ddlAt: nextTask.ddlAt,
+      version: nextTask.version,
+      updatedAt: nextTask.updatedAt
+    })
+  );
+
+  await localDb.transaction("rw", localDb.tasks, localDb.opLogs, async () => {
+    await localDb.tasks.put(nextTask);
+    await localDb.opLogs.add(opLog);
+  });
+
+  return nextTask;
+}
+
+export async function deleteLocalTask(id: string): Promise<boolean> {
+  const currentTask = await getLocalTaskById(id);
+  if (!currentTask) {
+    return false;
+  }
+
+  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,
+      version: nextTask.version,
+      updatedAt: nextTask.updatedAt
+    })
+  );
+
+  await localDb.transaction("rw", localDb.tasks, localDb.opLogs, async () => {
+    await localDb.tasks.put(nextTask);
+    await localDb.opLogs.add(opLog);
+  });
+
+  return true;
+}

apps/web/src/services/storage-quota.ts

@@ -0,0 +1,57 @@
+import { localDb } from "@/services/local-db";
+
+export const DEFAULT_CLOUD_QUOTA_BYTES = 100 * 1024 * 1024;
+
+type StorageQuotaSnapshot = {
+  usedBytes: number;
+  quotaBytes: number;
+  remainingBytes: number;
+  usedPercent: number;
+};
+
+function measureTextBytes(value: string | null): number {
+  if (!value) {
+    return 0;
+  }
+
+  return new Blob([value]).size;
+}
+
+export async function getStorageQuotaSnapshot(userId: string): Promise<StorageQuotaSnapshot> {
+  const tasks = await localDb.tasks.where("userId").equals(userId).toArray();
+
+  const usedBytes = tasks.reduce((total, task) => {
+    if (task.deletedAt !== null) {
+      return total;
+    }
+
+    return (
+      total +
+      measureTextBytes(task.title) +
+      measureTextBytes(task.contentText) +
+      measureTextBytes(task.contentJson)
+    );
+  }, 0);
+
+  const remainingBytes = Math.max(DEFAULT_CLOUD_QUOTA_BYTES - usedBytes, 0);
+  const usedPercent = Math.min((usedBytes / DEFAULT_CLOUD_QUOTA_BYTES) * 100, 100);
+
+  return {
+    usedBytes,
+    quotaBytes: DEFAULT_CLOUD_QUOTA_BYTES,
+    remainingBytes,
+    usedPercent
+  };
+}
+
+export function formatStorageSize(bytes: number): string {
+  if (bytes < 1024) {
+    return `${bytes} B`;
+  }
+
+  if (bytes < 1024 * 1024) {
+    return `${(bytes / 1024).toFixed(1)} KB`;
+  }
+
+  return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+}

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
+  };
+}