feat: Implement notification system with document permissions and SSE support

- Added Notification and NotificationPreference models for user notifications.
- Implemented document-level permissions with the ability to restrict access.
- Introduced SSE endpoint for real-time notification delivery.
- Enhanced DocumentsService to handle comment notifications and document permission management.
- Updated API with new endpoints for managing document permissions and user notifications.
- Improved search functionality with full-text search capabilities for documents.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Jason-chen-coder

.claude/settings.local.json

@@ -3,7 +3,7 @@ node_modules/
 .pnpm-store/
 
 .claude/
-
+.claude/settings.local.json
 # Build outputs
 dist/
 build/

.gitignore

@@ -0,0 +1,45 @@
+-- CreateEnum
+CREATE TYPE "NotificationType" AS ENUM ('SPACE_INVITATION', 'INVITATION_ACCEPTED', 'MEMBER_JOINED', 'MEMBER_REMOVED', 'ROLE_CHANGED', 'DOCUMENT_COMMENTED', 'DOCUMENT_MENTIONED', 'DOCUMENT_SHARED', 'DOCUMENT_UPDATED', 'SPACE_DELETED', 'SYSTEM');
+
+-- CreateTable
+CREATE TABLE "notifications" (
+    "id" TEXT NOT NULL,
+    "recipientId" TEXT NOT NULL,
+    "type" "NotificationType" NOT NULL,
+    "title" TEXT NOT NULL,
+    "content" TEXT,
+    "isRead" BOOLEAN NOT NULL DEFAULT false,
+    "entityType" "EntityType",
+    "entityId" TEXT,
+    "spaceId" TEXT,
+    "actorId" TEXT,
+    "actorName" TEXT,
+    "metadata" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "notifications_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "notification_preferences" (
+    "id" TEXT NOT NULL,
+    "userId" TEXT NOT NULL,
+    "preferences" TEXT NOT NULL,
+
+    CONSTRAINT "notification_preferences_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "notifications_recipientId_isRead_createdAt_idx" ON "notifications"("recipientId", "isRead", "createdAt" DESC);
+
+-- CreateIndex
+CREATE INDEX "notifications_recipientId_createdAt_idx" ON "notifications"("recipientId", "createdAt" DESC);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "notification_preferences_userId_key" ON "notification_preferences"("userId");
+
+-- AddForeignKey
+ALTER TABLE "notifications" ADD CONSTRAINT "notifications_recipientId_fkey" FOREIGN KEY ("recipientId") REFERENCES "users"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "notification_preferences" ADD CONSTRAINT "notification_preferences_userId_fkey" FOREIGN KEY ("userId") REFERENCES "users"("id") ON DELETE CASCADE ON UPDATE CASCADE;

apps/api/prisma/migrations/20260321091901_add_notification_system/migration.sql

@@ -0,0 +1,31 @@
+-- CreateEnum
+CREATE TYPE "DocumentAccessLevel" AS ENUM ('EDITOR', 'VIEWER');
+
+-- AlterTable
+ALTER TABLE "documents" ADD COLUMN     "isRestricted" BOOLEAN NOT NULL DEFAULT false;
+
+-- CreateTable
+CREATE TABLE "document_permissions" (
+    "id" TEXT NOT NULL,
+    "documentId" TEXT NOT NULL,
+    "userId" TEXT NOT NULL,
+    "permission" "DocumentAccessLevel" NOT NULL DEFAULT 'EDITOR',
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "document_permissions_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "document_permissions_documentId_idx" ON "document_permissions"("documentId");
+
+-- CreateIndex
+CREATE INDEX "document_permissions_userId_idx" ON "document_permissions"("userId");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "document_permissions_documentId_userId_key" ON "document_permissions"("documentId", "userId");
+
+-- AddForeignKey
+ALTER TABLE "document_permissions" ADD CONSTRAINT "document_permissions_documentId_fkey" FOREIGN KEY ("documentId") REFERENCES "documents"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "document_permissions" ADD CONSTRAINT "document_permissions_userId_fkey" FOREIGN KEY ("userId") REFERENCES "users"("id") ON DELETE CASCADE ON UPDATE CASCADE;

apps/api/prisma/migrations/20260322132240_add_document_permissions/migration.sql

@@ -0,0 +1,29 @@
+-- 添加搜索向量列
+ALTER TABLE documents ADD COLUMN IF NOT EXISTS search_vector tsvector;
+
+-- 创建 GIN 索引（加速全文搜索）
+CREATE INDEX IF NOT EXISTS idx_documents_search_vector ON documents USING GIN(search_vector);
+
+-- 创建触发函数：在 INSERT 或 UPDATE title/content 时自动更新 search_vector
+-- 使用 'simple' 配置（不分词，按空格/标点拆分），中英文通用
+-- 标题权重 A（最高），内容权重 B
+CREATE OR REPLACE FUNCTION update_document_search_vector()
+RETURNS TRIGGER AS $$
+BEGIN
+  NEW.search_vector :=
+    setweight(to_tsvector('simple', COALESCE(NEW.title, '')), 'A') ||
+    setweight(to_tsvector('simple', COALESCE(NEW.content, '')), 'B');
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+-- 创建触发器
+DROP TRIGGER IF EXISTS trg_document_search_vector ON documents;
+CREATE TRIGGER trg_document_search_vector
+  BEFORE INSERT OR UPDATE OF title, content ON documents
+  FOR EACH ROW EXECUTE FUNCTION update_document_search_vector();
+
+-- 回填已有数据的 search_vector
+UPDATE documents SET search_vector =
+  setweight(to_tsvector('simple', COALESCE(title, '')), 'A') ||
+  setweight(to_tsvector('simple', COALESCE(content, '')), 'B');

apps/api/prisma/migrations/20260322132655_add_fulltext_search/migration.sql

@@ -1,3 +1,3 @@
 # Please do not edit this file manually
-# It should be added in your version-control system (e.g., Git)
-provider = "postgresql"
+# It should be added in your version-control system (i.e. Git)
+provider = "postgresql"

apps/api/prisma/migrations/migration_lock.toml

@@ -32,6 +32,9 @@ model User {
   documentVisits   DocumentVisit[]
   templates        DocumentTemplate[]
   favorites        DocumentFavorite[]
+  notifications           Notification[]          @relation("UserNotifications")
+  notificationPreference  NotificationPreference? @relation("UserNotificationPreference")
+  documentPermissions     DocumentPermission[]
 
   @@map("users")
 }
@@ -72,7 +75,9 @@ model Document {
   createdBy String
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt
-  deletedAt DateTime? // 软删除：非空表示已移至回收站
+  deletedAt    DateTime? // 软删除：非空表示已移至回收站
+  isRestricted Boolean   @default(false) // 是否启用文档级权限（默认继承空间权限）
+  search_vector Unsupported("tsvector")? // PostgreSQL 全文搜索向量（由 DB 触发器自动维护）
 
   // 关系
   space       Space        @relation(fields: [spaceId], references: [id], onDelete: Cascade)
@@ -83,6 +88,7 @@ model Document {
   snapshots   DocumentSnapshot[]
   visits      DocumentVisit[]
   favorites   DocumentFavorite[]
+  documentPermissions DocumentPermission[]
 
   @@index([spaceId])
   @@index([spaceId, deletedAt])
@@ -300,6 +306,82 @@ enum TemplateCategory {
   OTHER
 }
 
+// ==================== 文档权限模型 ====================
+model DocumentPermission {
+  id         String              @id @default(cuid())
+  documentId String
+  userId     String
+  permission DocumentAccessLevel @default(EDITOR)
+  createdAt  DateTime            @default(now())
+
+  document   Document @relation(fields: [documentId], references: [id], onDelete: Cascade)
+  user       User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@unique([documentId, userId])
+  @@index([documentId])
+  @@index([userId])
+  @@map("document_permissions")
+}
+
+enum DocumentAccessLevel {
+  EDITOR
+  VIEWER
+}
+
+// ==================== 通知模型 ====================
+model Notification {
+  id          String           @id @default(cuid())
+  recipientId String
+  type        NotificationType
+  title       String
+  content     String?
+  isRead      Boolean          @default(false)
+
+  // 关联上下文 — 点击通知时可跳转
+  entityType  EntityType?
+  entityId    String?
+  spaceId     String?
+
+  // 触发者信息（冗余存储，避免关联查询）
+  actorId     String?
+  actorName   String?
+
+  metadata    String?          @db.Text
+  createdAt   DateTime         @default(now())
+
+  recipient   User             @relation("UserNotifications", fields: [recipientId], references: [id], onDelete: Cascade)
+
+  @@index([recipientId, isRead, createdAt(sort: Desc)])
+  @@index([recipientId, createdAt(sort: Desc)])
+  @@map("notifications")
+}
+
+// 通知类型枚举
+enum NotificationType {
+  SPACE_INVITATION
+  INVITATION_ACCEPTED
+  MEMBER_JOINED
+  MEMBER_REMOVED
+  ROLE_CHANGED
+  DOCUMENT_COMMENTED
+  DOCUMENT_MENTIONED
+  DOCUMENT_SHARED
+  DOCUMENT_UPDATED
+  SPACE_DELETED
+  SYSTEM
+}
+
+// ==================== 通知偏好模型 ====================
+model NotificationPreference {
+  id          String @id @default(cuid())
+  userId      String @unique
+  preferences String @db.Text // JSON: { "SPACE_INVITATION": true, ... }
+
+  user        User   @relation("UserNotificationPreference", fields: [userId], references: [id], onDelete: Cascade)
+
+  @@map("notification_preferences")
+}
+
 // ==================== 文档收藏模型 ====================
 model DocumentFavorite {
   id         String   @id @default(cuid())

apps/api/prisma/schema.prisma

@@ -20,6 +20,7 @@ import { SnapshotsModule } from './snapshots/snapshots.module';
 import { SearchModule } from './search/search.module';
 import { ActivityModule } from './activity/activity.module';
 import { TemplatesModule } from './templates/templates.module';
+import { NotificationsModule } from './notifications/notifications.module';
 
 @Module({
   imports: [
@@ -45,13 +46,19 @@ import { TemplatesModule } from './templates/templates.module';
     SearchModule,
     ActivityModule,
     TemplatesModule,
+    NotificationsModule,
   ],
   controllers: [AppController],
   providers: [
     AppService,
     {
       provide: APP_PIPE,
-      useClass: ValidationPipe,
+      useFactory: () =>
+        new ValidationPipe({
+          transform: true, // 启用 class-transformer，自动将 query 字符串转为 DTO 类型
+          transformOptions: { enableImplicitConversion: true },
+          whitelist: true,
+        }),
     },
     {
       provide: APP_GUARD,

apps/api/src/app.module.ts

@@ -224,6 +224,7 @@ export class CollaborationService implements OnModuleInit, OnModuleDestroy {
                   permissions: { where: { userId } },
                 },
               },
+              documentPermissions: { where: { userId } },
             },
           });
 
@@ -232,15 +233,38 @@ export class CollaborationService implements OnModuleInit, OnModuleDestroy {
           }
 
           const isOwner = doc.space.ownerId === userId;
-          const isMember = doc.space.permissions.length > 0;
+          const spacePermission = doc.space.permissions[0];
+          const isMember = spacePermission != null;
 
           if (!isOwner && !isMember) {
             throw new Error('Unauthorized: no access to this document');
           }
 
-          // Set read-only for VIEWERs
-          const permission = doc.space.permissions[0];
-          if (permission?.role === 'VIEWER') {
+          // ─── 文档级权限检查 ───
+          let readOnly = false;
+
+          if (doc.isRestricted) {
+            const isOwnerOrAdmin =
+              isOwner || spacePermission?.role === 'ADMIN';
+
+            if (isOwnerOrAdmin) {
+              // OWNER/ADMIN 始终可编辑
+              readOnly = false;
+            } else {
+              const docPerm = doc.documentPermissions[0];
+              if (!docPerm) {
+                throw new Error(
+                  'Unauthorized: no access to this restricted document',
+                );
+              }
+              readOnly = docPerm.permission === 'VIEWER';
+            }
+          } else {
+            // 继承空间权限
+            readOnly = spacePermission?.role === 'VIEWER';
+          }
+
+          if (readOnly) {
             (data as any).connection.readOnly = true;
           }