@things-factory/board-ai 10.0.0-beta.108

package/server/service/chat-message/chat-message-broadcast.integration.test.ts

@@ -0,0 +1,73 @@
+/**
+ * chat-message 방송 spine — 독립 통합 테스트 (실서버·WS 없이 자족적).
+ *
+ * 순수 필터(chat-message-broadcast.test.ts)와 달리, 실제 서버가 쓰는 동일한 경로를 구동:
+ *   publishChatMessage → shell pubsub(in-memory) → 토픽 → chatMessageFilter → async iterator.
+ * = resolver 의 subscribe 합성과 동일. WS/Apollo 전송 계층은 patch spine(C2)에서 검증된
+ * generic 인프라라 본 테스트 범위 밖 (수동 스모크로 1회 확인).
+ */
+import { filter, pipe } from 'graphql-yoga'
+import { pubsub } from '@things-factory/shell'
+import { publishChatMessage } from './chat-message-publish'
+import { CHAT_MESSAGE_TOPIC, chatMessageFilter } from './chat-message-broadcast'
+
+const msg = (id: string, role = 'user', content = 'hi') => ({ id, role, content } as any)
+
+/** resolver 의 subscribe 와 동일한 합성으로 구독 이터레이터를 만든다. */
+function subscribe(domainId: string, sessionId: string) {
+  return pipe(pubsub.subscribe(CHAT_MESSAGE_TOPIC), filter(chatMessageFilter(domainId, sessionId)))[
+    Symbol.asyncIterator
+  ]()
+}
+
+/** it.next() 를 timeout 과 race — 안 오면 'TIMEOUT'. */
+function nextOrTimeout(it: AsyncIterator<any>, ms = 400): Promise<any> {
+  return Promise.race([
+    it.next().then(r => r.value),
+    new Promise(resolve => setTimeout(() => resolve('TIMEOUT'), ms))
+  ])
+}
+
+describe('chat-message 방송 통합 (publish → 필터 → 구독)', () => {
+  it('같은 domain+session 구독자가 방송 메시지를 수신', async () => {
+    const it = subscribe('d1', 's1')
+    const p = nextOrTimeout(it)
+    publishChatMessage({ domainId: 'd1', sessionId: 's1', message: msg('m1', 'assistant', 'done') })
+    const value = await p
+    expect(value).not.toBe('TIMEOUT')
+    expect(value.message.id).toBe('m1')
+    expect(value.message.role).toBe('assistant')
+    await it.return?.()
+  })
+
+  it('다른 세션 메시지는 격리 — 내 세션 것만 수신', async () => {
+    const it = subscribe('d1', 's1')
+    const p = nextOrTimeout(it)
+    publishChatMessage({ domainId: 'd1', sessionId: 's2', message: msg('other') }) // 다른 세션 — 필터됨
+    publishChatMessage({ domainId: 'd1', sessionId: 's1', message: msg('mine') }) // 내 세션
+    const value = await p
+    expect(value).not.toBe('TIMEOUT')
+    expect(value.message.id).toBe('mine')
+    await it.return?.()
+  })
+
+  it('다른 domain 메시지는 격리 (도메인 보안)', async () => {
+    const it = subscribe('d1', 's1')
+    const p = nextOrTimeout(it)
+    publishChatMessage({ domainId: 'd2', sessionId: 's1', message: msg('foreign') }) // 다른 도메인 — 필터됨
+    publishChatMessage({ domainId: 'd1', sessionId: 's1', message: msg('local') })
+    const value = await p
+    expect(value).not.toBe('TIMEOUT')
+    expect(value.message.id).toBe('local')
+    await it.return?.()
+  })
+
+  it('sessionId 없는 publish 는 방송 안 함 (구독자 미수신)', async () => {
+    const it = subscribe('d1', 's1')
+    const p = nextOrTimeout(it, 250)
+    publishChatMessage({ domainId: 'd1', sessionId: undefined, message: msg('nope') })
+    const value = await p
+    expect(value).toBe('TIMEOUT') // 아무것도 안 옴
+    await it.return?.()
+  })
+})

package/server/service/chat-message/chat-message-broadcast.test.ts

@@ -0,0 +1,40 @@
+/**
+ * chat-message 브로드캐스트 — 단위 테스트 (순수 로직).
+ *  - chatMessageFilter: domain+session 격리(보안 핵심) — 일치만 통과, 불일치/널/session없음 차단.
+ * (publishChatMessage / 구독 resolver 는 pubsub·graphql-ws 통합 영역 — 별도 검증.)
+ */
+import { chatMessageFilter, CHAT_MESSAGE_TOPIC } from './chat-message-broadcast'
+import type { ChatMessagePayload } from './chat-message-broadcast'
+
+const payload = (domainId: string, sessionId?: string): ChatMessagePayload => ({
+  domainId,
+  sessionId,
+  message: { id: 'm1' } as any
+})
+
+describe('chatMessageFilter (domain+session 격리)', () => {
+  it('domain+session 모두 일치 → 통과', () => {
+    expect(chatMessageFilter('d1', 's1')(payload('d1', 's1'))).toBe(true)
+  })
+
+  it('domain 불일치 → 차단 (도메인 격리)', () => {
+    expect(chatMessageFilter('d1', 's1')(payload('d2', 's1'))).toBe(false)
+  })
+
+  it('session 불일치 → 차단 (다른 세션 메시지 누수 방지)', () => {
+    expect(chatMessageFilter('d1', 's1')(payload('d1', 's2'))).toBe(false)
+  })
+
+  it('sessionId 없는 페이로드 → 차단', () => {
+    expect(chatMessageFilter('d1', 's1')(payload('d1', undefined))).toBe(false)
+  })
+
+  it('null/undefined 페이로드 안전 → 차단', () => {
+    expect(chatMessageFilter('d1', 's1')(null as any)).toBe(false)
+    expect(chatMessageFilter('d1', 's1')(undefined as any)).toBe(false)
+  })
+
+  it('토픽 상수', () => {
+    expect(CHAT_MESSAGE_TOPIC).toBe('board-ai-chat-message')
+  })
+})

package/server/service/chat-message/chat-message-broadcast.ts

@@ -0,0 +1,27 @@
+/*
+ * chat-message 브로드캐스트 — 순수 로직 (토픽/페이로드/필터). 데코레이터·pubsub import 없음
+ * → 단위테스트 가능. 데코레이터 resolver(chat-message-subscription.ts)와 pubsub 의존
+ * publishChatMessage 는 별도.
+ *
+ * patch spine(board-patch-broadcast.ts)과 동일 컨벤션. 다만 채팅 메시지는 board 가 아니라
+ * **ChatSession 단위**로 묶이므로 필터 키가 sessionId (+ domain 격리).
+ */
+import type { ChatMessage } from './chat-message.js' // type-only — 런타임 import 아님
+
+/** chat-message 브로드캐스트 토픽. */
+export const CHAT_MESSAGE_TOPIC = 'board-ai-chat-message'
+
+/** 방송 페이로드 — 구독 필터(domain+session)용 메타 + ChatMessage 본체. */
+export interface ChatMessagePayload {
+  domainId: string
+  sessionId?: string
+  message: ChatMessage
+}
+
+/**
+ * 같은 domain + session 구독자에게만 통과시키는 필터 (도메인 격리 = 보안 핵심).
+ */
+export function chatMessageFilter(domainId: string, sessionId: string) {
+  return (payload: ChatMessagePayload): boolean =>
+    !!payload && payload.domainId === domainId && payload.sessionId === sessionId
+}

package/server/service/chat-message/chat-message-publish.ts

@@ -0,0 +1,22 @@
+/*
+ * chat-message 방송 publisher — pubsub 의존, 데코레이터 없음.
+ *
+ * 데코레이터 resolver(chat-message-subscription.ts)와 분리한 이유: babel-jest 가 파라미터
+ * 데코레이터(@Root/@Arg)를 파싱 못 해 그 파일을 테스트에서 import 할 수 없다. 이 모듈은
+ * 데코레이터가 없어 통합 테스트가 실제 publish→방송 경로를 직접 구동할 수 있다.
+ */
+import { pubsub } from '@things-factory/shell'
+import { CHAT_MESSAGE_TOPIC, type ChatMessagePayload } from './chat-message-broadcast.js'
+
+/**
+ * ChatMessage 영속 직후 호출 — 같은 세션 구독자에게 방송.
+ * sessionId 없으면 skip. pubsub 미가용/실패해도 본 흐름(영속 완료)을 막지 않는다.
+ */
+export function publishChatMessage(payload: ChatMessagePayload): void {
+  if (!payload.sessionId) return
+  try {
+    pubsub.publish(CHAT_MESSAGE_TOPIC, payload)
+  } catch {
+    /* 방송 생략 — 영속은 이미 끝남 */
+  }
+}

package/server/service/chat-message/chat-message-subscription.ts

@@ -0,0 +1,41 @@
+/*
+ * BoardChatMessageSubscription (Phase Board-AI C4 — 그룹챗 메시지 실시간 방송).
+ *
+ * ChatMessage(사용자 / AI / system) 가 영속될 때마다 같은 세션 구독자에게 방송 →
+ * 그룹챗의 척추. 클라이언트(board-ai-chat)가 구독해 원격 메시지를 transcript 에 append.
+ * 자기 발신 에코는 클라이언트가 message.id 로 dedup (mutation 응답으로 이미 렌더).
+ *
+ * patch spine(board-patch-subscription.ts)과 동일 패턴 — PubSub + graphql-ws, domain 격리.
+ * 차이: 필터 키가 board 가 아닌 sessionId (채팅은 ChatSession 단위).
+ * 순수 로직(토픽/필터)은 chat-message-broadcast.ts (테스트 가능). 여기엔 pubsub 의존만.
+ */
+import { Resolver, Subscription, Root, Arg } from 'type-graphql'
+import { filter, pipe } from 'graphql-yoga'
+import { pubsub } from '@things-factory/shell'
+import { ChatMessage } from './chat-message.js'
+import { CHAT_MESSAGE_TOPIC, chatMessageFilter, type ChatMessagePayload } from './chat-message-broadcast.js'
+import { assertDomainSubscribeAllowed } from '../subscribe-auth.js'
+
+// publishChatMessage 는 데코레이터 없는 chat-message-publish.ts 에 분리 (테스트 import 가능).
+export { publishChatMessage } from './chat-message-publish.js'
+export { CHAT_MESSAGE_TOPIC, chatMessageFilter } from './chat-message-broadcast.js'
+export type { ChatMessagePayload } from './chat-message-broadcast.js'
+
+@Resolver(ChatMessage)
+export class BoardChatMessageSubscription {
+  @Subscription({
+    description:
+      'Subscribes to chat messages (user / assistant / system) of a session for real-time group chat.',
+    subscribe: async ({ args, context }) => {
+      const { domain, user } = context.state
+      const { sessionId } = args
+
+      await assertDomainSubscribeAllowed(domain, user, (d, u) => process.superUserGranted(d, u))
+
+      return pipe(pubsub.subscribe(CHAT_MESSAGE_TOPIC), filter(chatMessageFilter(domain.id, sessionId)))
+    }
+  })
+  chatMessageActivity(@Root() payload: ChatMessagePayload, @Arg('sessionId') sessionId: string): ChatMessage {
+    return payload.message
+  }
+}

package/server/service/chat-message/chat-message.ts

@@ -0,0 +1,169 @@
+/**
+ * ChatMessage — ChatSession 의 한 메시지.
+ *
+ * role: 'user' | 'assistant' | 'system'
+ * 'system' 은 사용자 직접 편집/import 진행 등 시스템이 자동 생성하는 컨텍스트 메시지.
+ *
+ * relatedPatchId / relatedImportSessionId 로 메시지가 트리거한 패치·임포트와 연결.
+ */
+import {
+  Column,
+  CreateDateColumn,
+  DeleteDateColumn,
+  Entity,
+  Index,
+  ManyToOne,
+  PrimaryGeneratedColumn,
+  RelationId,
+  UpdateDateColumn
+} from 'typeorm'
+import { Field, ID, ObjectType } from 'type-graphql'
+import { GraphQLJSON } from 'graphql-scalars'
+
+import { User } from '@things-factory/auth-base'
+import { config } from '@things-factory/env'
+
+import { ChatSession } from '../chat-session/chat-session.js'
+
+const ORMCONFIG = config.get('ormconfig', {})
+const DATABASE_TYPE = ORMCONFIG.type
+
+@Entity()
+@Index('ix_chat_message_1', (message: ChatMessage) => [message.session, message.createdAt])
+@ObjectType({ description: 'A single chat message in a ChatSession.' })
+export class ChatMessage {
+  @PrimaryGeneratedColumn('uuid')
+  @Field(type => ID, { nullable: true })
+  readonly id?: string
+
+  @ManyToOne(type => ChatSession, session => session.messages, { onDelete: 'CASCADE' })
+  session?: ChatSession
+
+  @RelationId((message: ChatMessage) => message.session)
+  sessionId?: string
+
+  @Column({ type: 'varchar', length: 16 })
+  @Field({ description: "'user' | 'assistant' | 'system'" })
+  role!: string
+
+  @Column({
+    type:
+      DATABASE_TYPE == 'mysql' || DATABASE_TYPE == 'mariadb'
+        ? 'longtext'
+        : DATABASE_TYPE == 'oracle'
+          ? 'clob'
+          : DATABASE_TYPE == 'mssql'
+            ? 'nvarchar'
+            : 'text',
+    length: DATABASE_TYPE == 'mssql' ? 'MAX' : undefined
+  })
+  @Field({ description: 'Message content' })
+  content!: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'PatchEntry.id this message triggered (if any).' })
+  relatedPatchId?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'ImportSession.id this message triggered (if any).' })
+  relatedImportSessionId?: string
+
+  /**
+   * AI 가 응답을 만드는 동안 호출한 도구 trace — JSON-stringified.
+   *
+   * 컬럼은 string (PatchEntry.ops 와 동일 패턴), GraphQL 노출은 toolUsagesJson getter
+   * 로 parse 된 객체. UI 의 fold-able 박스 ("AI 가 이런 도구를 사용했습니다") 가
+   * 페이지 reload / loadHistory 후에도 살아있도록 영속.
+   *
+   * 형태: ToolUsage[] (assistant.ts 의 시간순 trace, summarizeToolResult 로 압축).
+   * null 이면 도구 호출 없었던 메시지 (text-only 응답).
+   */
+  @Column({
+    type:
+      DATABASE_TYPE == 'mysql' || DATABASE_TYPE == 'mariadb'
+        ? 'longtext'
+        : DATABASE_TYPE == 'oracle'
+          ? 'clob'
+          : DATABASE_TYPE == 'mssql'
+            ? 'nvarchar'
+            : 'text',
+    length: DATABASE_TYPE == 'mssql' ? 'MAX' : undefined,
+    nullable: true
+  })
+  toolUsages?: string
+
+  /** GraphQL 노출용 — JSON 배열로 parse. */
+  @Field(() => GraphQLJSON, {
+    nullable: true,
+    description:
+      'Tool usage trace — array of {name, arguments, result, kind}. Only on assistant messages.'
+  })
+  get toolUsagesJson(): any {
+    if (!this.toolUsages) return null
+    try {
+      return JSON.parse(this.toolUsages)
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * 메시지를 일으킨 사용자.
+   *   - role='user' → 보낸 사용자
+   *   - role='assistant' → 그 응답을 트리거한 사용자 (직전 user 메시지의 작성자)
+   *   - role='system' → 시스템 액션을 일으킨 사용자 (예: 직접 편집한 사용자)
+   *
+   * nullable — legacy 메시지 (이 필드 추가 이전에 작성) 는 null. 또한 ad-hoc 모드 / 시스템
+   * 자동 메시지 중 사용자 컨텍스트가 없는 경우도 null 가능.
+   */
+  @ManyToOne(type => User, { nullable: true })
+  @Field(type => User, { nullable: true, description: 'User who triggered this message.' })
+  creator?: User
+
+  @RelationId((message: ChatMessage) => message.creator)
+  creatorId?: string
+
+  @ManyToOne(type => User, { nullable: true })
+  @Field(type => User, { nullable: true, description: 'Last user to update this message (for future edit support).' })
+  updater?: User
+
+  @RelationId((message: ChatMessage) => message.updater)
+  updaterId?: string
+
+  /**
+   * 부모 메시지 — 이 메시지가 "응답하는 대상" / "이어가는 메시지" 의 id.
+   *
+   * 의미 (role 별):
+   *   - 'user' → 직전 in-session 메시지 (보통 assistant 또는 system). 첫 turn 은 null.
+   *   - 'assistant' → 이 응답이 답하는 user 메시지. (regenerate 로 같은 user 메시지를 부모로
+   *     하는 형제 assistant 메시지가 생기면 자연스럽게 branching tree 가 됨)
+   *   - 'system' → 직전 in-session 메시지 (timeline 연속성 유지).
+   *
+   * 이 한 컬럼으로 향후 어떤 흐름이든 표현 가능 — linear chain / branching (regenerate) /
+   * tree (replies-to-specific-message) 등. UI/쿼리는 점진 도입.
+   *
+   * onDelete: 'SET NULL' — 부모 메시지가 삭제돼도 child 는 남되 dangling 마킹.
+   */
+  @ManyToOne(type => ChatMessage, { nullable: true, onDelete: 'SET NULL' })
+  parentMessage?: ChatMessage
+
+  @RelationId((message: ChatMessage) => message.parentMessage)
+  @Field({
+    nullable: true,
+    description:
+      'Id of the message this one is in-response-to / continues. Enables linear / branching / tree structures.'
+  })
+  parentMessageId?: string
+
+  @CreateDateColumn()
+  @Field({ nullable: true, description: 'Creation timestamp.' })
+  createdAt?: Date
+
+  @UpdateDateColumn()
+  @Field({ nullable: true, description: 'Last update timestamp (relevant once message editing is supported).' })
+  updatedAt?: Date
+
+  @DeleteDateColumn()
+  @Field({ nullable: true, description: 'Soft delete timestamp.' })
+  deletedAt?: Date
+}

package/server/service/chat-message/index.ts

@@ -0,0 +1,12 @@
+import { ChatMessage } from './chat-message.js'
+
+export { ChatMessage }
+export {
+  BoardChatMessageSubscription,
+  publishChatMessage,
+  CHAT_MESSAGE_TOPIC,
+  chatMessageFilter
+} from './chat-message-subscription.js'
+export type { ChatMessagePayload } from './chat-message-subscription.js'
+
+export const entities = [ChatMessage]

package/server/service/chat-session/chat-session.ts

@@ -0,0 +1,130 @@
+/**
+ * ChatSession — Board 와 결합되는 AI 협력 세션.
+ *
+ * 한 보드에 여러 세션 가능 — DB 레벨 unique 제약 없음.
+ *
+ * 향후 폭증할 세션 분화 차원 (예: thread / 사용자별 / 컨텍스트별 design vs ops /
+ * archived / forked from clone / agent별) 을 미리 차단하지 않기 위해 구조 자체는 1:N
+ * 으로 열어둠. 단일 세션 정책 (현재 UX) 은 app 레벨 idempotent 로직 — `startBoardAISession`
+ * 이 boardId 매칭 시 기존 세션 반환, `chatSessionByBoard` 가 첫 매칭 반환.
+ *
+ * 미래에 다중 세션 활성화 시 discriminator 컬럼 (kind / name / threadId / creatorId 등)
+ * 을 그때 추가. 마이그레이션 부담 최소화 — 현재는 unique 만 풀어 자리 마련.
+ *
+ * board-service 의 Board 가 owning side 가 될 예정 (ChatSession FK).
+ */
+import {
+  Column,
+  CreateDateColumn,
+  DeleteDateColumn,
+  Entity,
+  Index,
+  ManyToOne,
+  OneToMany,
+  PrimaryGeneratedColumn,
+  RelationId,
+  UpdateDateColumn
+} from 'typeorm'
+import { Field, ID, ObjectType } from 'type-graphql'
+
+import { Domain } from '@things-factory/shell'
+import { User } from '@things-factory/auth-base'
+import { config } from '@things-factory/env'
+
+import { ChatMessage } from '../chat-message/chat-message.js'
+import { PatchEntry } from '../patch-entry/patch-entry.js'
+
+const ORMCONFIG = config.get('ormconfig', {})
+const DATABASE_TYPE = ORMCONFIG.type
+
+@Entity()
+// 인덱스는 조회 성능용으로 유지 (chatSessionByBoard 가 [domain, boardId] 로 자주 쿼리).
+// unique 제약은 의도적으로 제거 — 한 보드에 여러 세션을 미래에 허용하기 위함.
+@Index('ix_chat_session_1', (session: ChatSession) => [session.domain, session.boardId])
+@ObjectType({
+  description: 'AI 협력 세션 — Board 와 결합. 한 보드에 여러 세션 가능 (thread / 사용자별 / 컨텍스트별 등 미래 확장).'
+})
+export class ChatSession {
+  @PrimaryGeneratedColumn('uuid')
+  @Field(type => ID, { nullable: true })
+  readonly id?: string
+
+  @ManyToOne(type => Domain)
+  @Field(type => Domain, { nullable: true })
+  domain?: Domain
+
+  @RelationId((session: ChatSession) => session.domain)
+  domainId?: string
+
+  /** Board.id 와 연결. Board 가 owning side 가 될 예정. 1:N — 한 보드에 여러 세션 가능. */
+  @Column({ nullable: true })
+  @Field({
+    nullable: true,
+    description:
+      'Connected Board id. Multiple sessions per board allowed (future: threads / per-user / contexts).'
+  })
+  boardId?: string
+
+  /**
+   * 세션의 사용자 정의 이름 (탭 레이블 / 세션 식별 표시용).
+   *
+   * nullable — 미설정 시 UI 가 fallback 라벨 ("세션 N" 또는 createdAt 기반) 사용. 사용자가
+   * 다중 세션 운영 시 의미 부여 (예: "초기 설계", "운영 시뮬레이션", "사용자A 의 사적 세션").
+   */
+  @Column({ nullable: true, length: 200 })
+  @Field({ nullable: true, description: 'User-given name of this session (tab label / identification).' })
+  name?: string
+
+  @ManyToOne(type => User)
+  @Field(type => User, { nullable: true, description: 'User who created this session.' })
+  creator?: User
+
+  @RelationId((session: ChatSession) => session.creator)
+  creatorId?: string
+
+  @ManyToOne(type => User)
+  @Field(type => User, { nullable: true, description: 'User who last updated this session.' })
+  updater?: User
+
+  @RelationId((session: ChatSession) => session.updater)
+  updaterId?: string
+
+  /** 토큰 절감용 — 오래된 메시지를 LLM 으로 압축한 요약. Phase 2 에서 작성. */
+  @Column({
+    nullable: true,
+    type:
+      DATABASE_TYPE == 'mysql' || DATABASE_TYPE == 'mariadb'
+        ? 'longtext'
+        : DATABASE_TYPE == 'oracle'
+          ? 'clob'
+          : DATABASE_TYPE == 'mssql'
+            ? 'nvarchar'
+            : 'text',
+    length: DATABASE_TYPE == 'mssql' ? 'MAX' : undefined
+  })
+  @Field({ nullable: true, description: 'Compressed summary of older messages (for token saving).' })
+  lastSummary?: string
+
+  /** 사용 모델 식별 — 'anthropic:claude-sonnet-4-6' 등 */
+  @Column({ nullable: true })
+  @Field({ nullable: true })
+  aiClientId?: string
+
+  @CreateDateColumn()
+  @Field({ nullable: true })
+  createdAt?: Date
+
+  @UpdateDateColumn()
+  @Field({ nullable: true })
+  updatedAt?: Date
+
+  @DeleteDateColumn()
+  deletedAt?: Date
+
+  // ── 관계 (TypeORM 만, GraphQL 노출은 별도 query 통해 페이징) ──
+  @OneToMany(type => ChatMessage, message => message.session)
+  messages?: ChatMessage[]
+
+  @OneToMany(type => PatchEntry, patch => patch.session)
+  patches?: PatchEntry[]
+}

package/server/service/chat-session/index.ts

@@ -0,0 +1,5 @@
+import { ChatSession } from './chat-session.js'
+
+export { ChatSession }
+
+export const entities = [ChatSession]

package/server/service/chat-session-participant/chat-session-participant.ts

@@ -0,0 +1,110 @@
+/**
+ * ChatSessionParticipant — 채팅 세션의 참여 사용자.
+ *
+ * 한 ChatSession 에 여러 사용자가 참여할 수 있고, 각자 role (owner / member / viewer 등)
+ * 을 가짐. 다자간 채팅 / 권한 분화 / "내 세션 목록" / 멤버 표시 등의 기반.
+ *
+ * 현재 visibility 정책 (도메인 내 모두 공개) 은 그대로 유지 — 본 엔티티는 영속/추적
+ * 데이터 만들고, "참여자만 접근" 같은 enforcement 는 정책 굳을 때 별도 phase 에서 도입.
+ *
+ * 자동 참여 vs 명시적 초대 정책도 미정 — 일단 세션 creator 만 자동 'owner' 로 등록.
+ */
+import {
+  Column,
+  CreateDateColumn,
+  DeleteDateColumn,
+  Entity,
+  Index,
+  ManyToOne,
+  PrimaryGeneratedColumn,
+  RelationId,
+  UpdateDateColumn
+} from 'typeorm'
+import { Field, ID, ObjectType } from 'type-graphql'
+
+import { Domain } from '@things-factory/shell'
+import { User } from '@things-factory/auth-base'
+
+import { ChatSession } from '../chat-session/chat-session.js'
+
+@Entity('chat_session_participants')
+@Index('ix_chat_session_participant_0', ['domain', 'session', 'user'], {
+  unique: true,
+  where: '"deleted_at" IS NULL'
+})
+@Index('ix_chat_session_participant_1', ['domain', 'user'], {
+  where: '"deleted_at" IS NULL'
+})
+@ObjectType({
+  description:
+    'Participant of a ChatSession — links a User to a session with a role. Foundation for multi-user chat / per-user filtering / member display.'
+})
+export class ChatSessionParticipant {
+  @PrimaryGeneratedColumn('uuid')
+  @Field(type => ID, { description: 'Unique participant id.' })
+  readonly id?: string
+
+  @ManyToOne(type => Domain)
+  @Field(type => Domain, { nullable: true, description: 'Domain to which this participant belongs.' })
+  domain?: Domain
+
+  @RelationId((p: ChatSessionParticipant) => p.domain)
+  domainId?: string
+
+  @ManyToOne(type => ChatSession, { onDelete: 'CASCADE' })
+  @Field(type => ChatSession, { nullable: true, description: 'The ChatSession this participation belongs to.' })
+  session?: ChatSession
+
+  @RelationId((p: ChatSessionParticipant) => p.session)
+  sessionId?: string
+
+  @ManyToOne(type => User)
+  @Field(type => User, { nullable: true, description: 'The user participating in the session.' })
+  user?: User
+
+  @RelationId((p: ChatSessionParticipant) => p.user)
+  userId?: string
+
+  /**
+   * 참여자의 역할.
+   *   - 'owner': 세션 만든 사람. rename / delete 권한.
+   *   - 'member': 일반 참여자. 메시지 송수신.
+   *   - 'viewer': 읽기 전용 (미래 권한 정책 활성화 시).
+   *
+   * 시작은 'owner' / 'member' 둘로 충분. 더 세분화 필요해지면 enum 확장.
+   */
+  @Column({ type: 'varchar', length: 16, default: 'member' })
+  @Field({ description: 'Role of this participant: owner | member | viewer.' })
+  role!: string
+
+  /** 마지막 활동 시각 — presence indicator. nullable. */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Last seen / activity timestamp (presence indicator).' })
+  lastSeenAt?: Date
+
+  @ManyToOne(type => User)
+  @Field(type => User, { nullable: true, description: 'User who created this participant record (typically session owner who invited).' })
+  creator?: User
+
+  @RelationId((p: ChatSessionParticipant) => p.creator)
+  creatorId?: string
+
+  @ManyToOne(type => User)
+  @Field(type => User, { nullable: true, description: 'Last user to update this participant record (e.g., role change).' })
+  updater?: User
+
+  @RelationId((p: ChatSessionParticipant) => p.updater)
+  updaterId?: string
+
+  @CreateDateColumn()
+  @Field({ nullable: true, description: 'Joined-at timestamp.' })
+  createdAt?: Date
+
+  @UpdateDateColumn()
+  @Field({ nullable: true, description: 'Last update timestamp (role change / lastSeenAt bump).' })
+  updatedAt?: Date
+
+  @DeleteDateColumn()
+  @Field({ nullable: true, description: 'Soft delete (= left session) timestamp.' })
+  deletedAt?: Date
+}

package/server/service/chat-session-participant/index.ts

@@ -0,0 +1,6 @@
+import { ChatSessionParticipant } from './chat-session-participant.js'
+
+export { ChatSessionParticipant }
+export { isOnline, PRESENCE_TTL_MS } from './presence.js'
+
+export const entities = [ChatSessionParticipant]

package/server/service/chat-session-participant/invite-notification.test.ts

@@ -0,0 +1,30 @@
+import { buildInviteNotification } from './invite-notification'
+
+describe('buildInviteNotification — 협업 초대 알림 payload', () => {
+  test('받는 사람 없으면 null', () => {
+    expect(buildInviteNotification([], 'board-1', { name: 'Kim' })).toBeNull()
+    expect(buildInviteNotification(undefined as any, 'board-1', { name: 'Kim' })).toBeNull()
+  })
+
+  test('정상 — receivers / type / mode 고정', () => {
+    const p = buildInviteNotification(['u1', 'u2'], 'board-9', { name: 'Kim' })!
+    expect(p).not.toBeNull()
+    expect(p.receivers).toEqual(['u1', 'u2'])
+    expect(p.type).toBe('board-collab-invite')
+    expect(p.subject).toBe('info')
+    expect(p.mode).toBe('background')
+    expect(p.title).toBeTruthy()
+  })
+
+  test('inviter 이름 우선, 없으면 email, 둘 다 없으면 someone', () => {
+    expect(buildInviteNotification(['u1'], 'b', { name: 'Kim', email: 'k@x.io' })!.body).toContain('Kim')
+    expect(buildInviteNotification(['u1'], 'b', { email: 'k@x.io' })!.body).toContain('k@x.io')
+    expect(buildInviteNotification(['u1'], 'b', {})!.body).toContain('someone')
+    expect(buildInviteNotification(['u1'], 'b', null)!.body).toContain('someone')
+  })
+
+  test('boardId 있으면 모델러 링크, 없으면 url 생략', () => {
+    expect(buildInviteNotification(['u1'], 'board-42', { name: 'Kim' })!.url).toBe('board-modeller/board-42')
+    expect(buildInviteNotification(['u1'], undefined, { name: 'Kim' })!.url).toBeUndefined()
+  })
+})