@things-factory/ai-assistant 10.1.6

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

@@ -0,0 +1,161 @@
+/*
+ * 세션 목록(받은편지함) 순수 로직 — 리졸버와 분리해 단위 테스트 가능.
+ *
+ * ── 왜 필요한가 ─────────────────────────────────────────────────────────────
+ * 대화가 늘면(가벼운 질문을 승격할 때마다 새 세션) "어디로 갈지"를 목록에서 골라야 하고, 다른 참여자가
+ * 남긴 새 메시지를 알아야 한다. 세션 목록은 **최근 활동순**이어야 하고 **안 읽음**이 보여야 한다.
+ *
+ * ── 집계 쿼리를 쓰지 않는다 ─────────────────────────────────────────────────
+ * 세션마다 메시지를 집계하면(MAX/COUNT + group by) 목록 한 번에 집계가 붙고, 이 프레임워크는 5개 DB
+ * 드라이버를 지원해야 한다. 대신 `ChatSession.lastMessageAt` 을 비정규화해 두고(메시지 저장 시 갱신),
+ * 참여자의 `lastReadAt` 과 **값 비교**로 안 읽음을 판정한다 — 조회 두 번(세션·내 참여자)으로 끝난다.
+ *
+ * ── v1 은 개수가 아니라 "안 읽음 여부" ──────────────────────────────────────
+ * 정확한 미읽음 **개수**는 세션별 count 가 필요하다(목록 N개면 N번). 목록에서는 점 하나로 충분하고,
+ * 숫자가 필요해지면 화면에 보이는 세션에 한해 따로 세면 된다. 처음부터 N번 세지 않는다.
+ */
+
+/** 목록에 필요한 세션 필드(엔티티·typeorm 비의존). */
+export interface InboxSessionRow {
+  id?: string
+  name?: string
+  anchorType?: string
+  anchorId?: string
+  boardId?: string
+  lastMessageAt?: Date | string | null
+  lastMessagePreview?: string | null
+  createdAt?: Date | string | null
+}
+
+/** 내 참여 기록(읽은 지점). */
+export interface MyParticipation {
+  sessionId?: string
+  lastReadAt?: Date | string | null
+  /** 내 목록에서 숨긴 시각 — 이후 새 활동이 생기면 다시 보인다. */
+  hiddenAt?: Date | string | null
+}
+
+export interface InboxEntry extends InboxSessionRow {
+  /** 안 읽은 활동이 있는가 — 목록의 점 표시. */
+  unread: boolean
+  /** 내가 참여자인가 — 아니면 열어볼 수는 있어도 읽음 상태를 갖지 않는다. */
+  participant: boolean
+  /** 내가 숨긴 대화인가 — 목록에서 빠지지만 필터로 볼 수 있다(되돌리기 가능). */
+  hidden?: boolean
+}
+
+function time(v: Date | string | null | undefined): number {
+  if (!v) return 0
+  const t = v instanceof Date ? v.getTime() : Date.parse(v)
+  return Number.isFinite(t) ? t : 0
+}
+
+/**
+ * 세션 + 내 참여 기록 → 목록 항목. **최근 활동순**(활동 없으면 생성순) 내림차순.
+ *
+ * 안 읽음 판정: 세션의 마지막 활동이 내가 읽은 지점보다 **뒤**면 안 읽음.
+ *   · 참여자가 아니면 안 읽음으로 표시하지 않는다(내 것이 아닌 대화에 배지를 띄우지 않는다).
+ *   · 참여자인데 한 번도 읽지 않았고(lastReadAt 없음) 활동이 있으면 안 읽음이다.
+ *   · 활동이 없는 세션(빈 대화)은 안 읽음이 아니다.
+ *
+ * 같은 시각 비교는 **엄격 초과**만 안 읽음으로 본다 — 읽은 직후 같은 밀리초에 저장된 활동을 안 읽음으로
+ * 잡으면 방금 읽은 화면에 배지가 남는다.
+ */
+export function buildInbox(sessions: InboxSessionRow[], mine: MyParticipation[]): InboxEntry[] {
+  const readBy = new Map<string, number>()
+  const isParticipant = new Set<string>()
+  for (const p of mine) {
+    if (!p.sessionId) continue
+    isParticipant.add(p.sessionId)
+    readBy.set(p.sessionId, time(p.lastReadAt))
+  }
+
+  const entries = sessions.map(session => {
+    const id = session.id ?? ''
+    const activity = time(session.lastMessageAt)
+    const participant = isParticipant.has(id)
+    const read = readBy.get(id) ?? 0
+    return {
+      ...session,
+      participant,
+      unread: participant && activity > 0 && activity > read
+    }
+  })
+
+  return entries.sort(
+    (a, b) => (time(b.lastMessageAt) || time(b.createdAt)) - (time(a.lastMessageAt) || time(a.createdAt))
+  )
+}
+
+/**
+ * 숨김 표시·필터.
+ *
+ * 숨김은 **나에게만** 적용되고 되돌릴 수 있다. 숨긴 **뒤에 새 활동이 생기면 다시 보인다** —
+ * 아직 참여 중인 대화에서 조용히 잘려 나가는 것이 목록 한 줄보다 나쁘다.
+ *
+ * `showHidden` 이면 숨긴 것도 함께 돌려주되 표시(hidden)를 남긴다 — 필터를 켠 사용자가 무엇이
+ * 숨겨진 것인지 알아야 되돌릴 수 있다.
+ */
+export function applyHidden(entries: InboxEntry[], hiddenAt: Map<string, Date | string | null | undefined>, showHidden = false): InboxEntry[] {
+  const out: InboxEntry[] = []
+  for (const entry of entries) {
+    const at = hiddenAt.get(entry.id ?? '')
+    /* 숨긴 시각보다 **뒤에** 활동이 있으면 숨김은 풀린 것으로 본다. */
+    const hidden = !!at && time(entry.lastMessageAt) <= time(at)
+    if (hidden && !showHidden) continue
+    out.push(hidden ? { ...entry, hidden: true } : entry)
+  }
+  return out
+}
+
+/**
+ * 검색 — 이름과 마지막 미리보기에 대한 대소문자 무시 부분일치.
+ *
+ * **왜 메모리에서 하는가**: 이 프레임워크는 5개 DB 드라이버를 지원한다. 대소문자 무시 검색은
+ * 드라이버마다 표기가 갈리고(ILIKE=pg 전용, LOWER()+LIKE 는 되지만 정렬·NULL 취급이 또 갈린다),
+ * 목록 경로에 드라이버별 SQL 을 두는 것은 이 프로젝트의 규율에 반한다. 그래서 조회는 앵커로
+ * **상한을 두고** 가져오고(아래 INBOX_SCAN_CAP) 걸러내기·정렬·페이지는 여기서 한다.
+ * 상한을 넘으면 잘렸다는 사실을 그대로 알린다(조용히 일부만 보여주지 않는다).
+ */
+export function searchInbox(entries: InboxEntry[], search?: string): InboxEntry[] {
+  const q = (search ?? '').trim().toLowerCase()
+  if (!q) return entries
+  return entries.filter(e =>
+    `${e.name ?? ''}\n${e.lastMessagePreview ?? ''}`.toLowerCase().includes(q)
+  )
+}
+
+/** 한 번에 훑는 세션 상한 — 이보다 많으면 잘렸다고 알린다(정직). */
+export const INBOX_SCAN_CAP = 500
+
+/** 안 읽은 세션 수 — 도크 버튼 배지(개수가 아니라 **세션 수**). */
+export function countUnreadSessions(entries: InboxEntry[]): number {
+  return entries.filter(e => e.unread).length
+}
+
+/**
+ * 메시지 저장 시 세션에 반영할 활동 값. 미리보기는 짧게 자르고 개행을 없앤다
+ * (목록 한 줄에 들어가야 하고, 컬럼 길이 제한이 있다).
+ */
+export function activityPatch(content: string, at: Date = new Date()): { lastMessageAt: Date; lastMessagePreview: string } {
+  const flat = (content ?? '').replace(/\s+/g, ' ').trim()
+  return { lastMessageAt: at, lastMessagePreview: flat.slice(0, 200) }
+}
+
+/**
+ * 첫 발화로 세션 이름을 만든다.
+ *
+ * `세션 2` 같은 순번은 목록에서 아무것도 알려주지 않는다 — "A-DC 포화 원인" 이어야 돌아갈 대화를 찾는다.
+ * 사용자가 직접 지은 이름은 이 함수로 덮지 않는다(호출부가 이름 없을 때만 부른다).
+ *
+ * 규칙: 한 줄로 눌러 첫 문장 경계(., ?, !, 개행)까지, 최대 40자. 문장 부호로 끝나면 떼어 낸다
+ * (목록 제목에 물음표가 붙으면 길이만 먹는다).
+ */
+export function autoSessionName(content: string, max = 40): string {
+  const flat = (content ?? '').replace(/\s+/g, ' ').trim()
+  if (!flat) return ''
+  const cut = flat.search(/[.?!\n]/)
+  const head = (cut > 0 ? flat.slice(0, cut) : flat).trim()
+  const name = head.length > max ? head.slice(0, max).trim() + '…' : head
+  return name
+}

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

@@ -0,0 +1,135 @@
+/**
+ * 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
+
+  /**
+   * 이 참여자가 **읽은 지점**. 세션의 마지막 활동 시각과 비교해 안 읽음을 판정한다.
+   *
+   * `lastSeenAt`(접속 표시)과 다른 개념이다 — 창을 열어 두고 화면을 안 볼 수 있고, 접속이 끊긴 뒤에도
+   * 읽은 지점은 남는다. 두 값을 섞어 쓰면 "봤는데 안 읽음" 또는 그 반대가 된다.
+   * nullable — 한 번도 읽지 않은 참여자(초대 직후)는 세션의 모든 활동이 안 읽음이다.
+   */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Point up to which this participant has read the session. Distinct from lastSeenAt (presence): a window can be open without being read, and the read point survives disconnection. Null means nothing read yet.' })
+  lastReadAt?: Date
+
+  /**
+   * 이 사용자가 **자기 목록에서 숨긴 시각**. 숨김은 **나에게만** 적용된다 — 남의 목록·대화 내용은 그대로다.
+   *
+   * 왜 삭제와 나누는가: 협의는 여럿의 기록이므로 지우는 것은 **만든 사람**만 할 수 있다(되돌릴 수 없다).
+   * 그 권한이 없는 사람에게도 "내 목록을 정리할" 방법은 있어야 하고, 그것이 숨김이다.
+   *
+   * 숨긴 **뒤에 새 활동이 생기면 다시 나타난다** — 아직 참여자인 대화에서 조용히 잘려 나가는 것이
+   * 목록이 한 줄 늘어나는 것보다 나쁘다. 완전히 빠지려면 대화에서 나가야 한다(별개 기능).
+   * nullable — 값이 없으면 숨기지 않은 상태.
+   */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'When this user hid the session from their own list. Per-user only; the session and other participants are unaffected. Activity newer than this timestamp makes it reappear.' })
+  hiddenAt?: 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()
+  })
+})

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

@@ -0,0 +1,48 @@
+/**
+ * 협업 초대 알림 — 순수 payload 빌더.
+ *
+ * 부수효과(실제 발송)는 resolver 의 thin caller 가 `context.state.notify` 로 수행.
+ * 여기엔 "무엇을 보낼지"(payload) 결정 로직만 둔다 — DB·pubsub·notify 의존 없이 테스트 가능.
+ * (patch spine 의 board-patch-broadcast.ts 와 동일한 순수/부수효과 분리 컨벤션.)
+ */
+
+/** notification-middleware 의 notifier 가 받는 인자 형태 (필요한 키만). */
+export interface InviteNotification {
+  receivers: string[]
+  type: string
+  subject: string
+  title: string
+  body: string
+  url?: string
+  mode: 'background' | 'foreground'
+}
+
+/** 초대자 식별용 — User 엔티티에서 쓰는 필드만 (duck-typed). */
+export interface Inviter {
+  name?: string | null
+  email?: string | null
+}
+
+/**
+ * 초대된 사용자들에게 보낼 협업 초대 알림 payload 를 만든다.
+ * 받는 사람이 없으면 null (= 보낼 것 없음).
+ */
+export function buildInviteNotification(
+  userIds: string[],
+  boardId: string | undefined,
+  inviter: Inviter | undefined | null
+): InviteNotification | null {
+  if (!Array.isArray(userIds) || userIds.length === 0) return null
+
+  const who = inviter?.name || inviter?.email || 'someone'
+  return {
+    receivers: userIds,
+    type: 'board-collab-invite',
+    subject: 'info',
+    title: 'Board collaboration invite',
+    body: `${who} invited you to collaborate on a board.`,
+    // board 가 연결돼 있으면 모델러로 바로 가는 링크. 없으면 링크 생략.
+    url: boardId ? `board-modeller/${boardId}` : undefined,
+    mode: 'background'
+  }
+}

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

@@ -0,0 +1,39 @@
+/**
+ * presence.isOnline — 단위 테스트. lastSeenAt 기반 online 판정(시각 주입, 순수).
+ */
+import { isOnline, PRESENCE_TTL_MS } from './presence'
+
+const NOW = 1_000_000_000_000 // 고정 기준 시각(ms)
+
+describe('isOnline', () => {
+  it('ttl 이내 → online', () => {
+    expect(isOnline(new Date(NOW - 10_000), NOW)).toBe(true)
+  })
+
+  it('ttl 경계 — 정확히 ttl 은 online, 초과는 offline', () => {
+    expect(isOnline(new Date(NOW - PRESENCE_TTL_MS), NOW)).toBe(true)
+    expect(isOnline(new Date(NOW - PRESENCE_TTL_MS - 1), NOW)).toBe(false)
+  })
+
+  it('lastSeenAt 없음 → offline', () => {
+    expect(isOnline(null, NOW)).toBe(false)
+    expect(isOnline(undefined, NOW)).toBe(false)
+  })
+
+  it('잘못된 값 → offline', () => {
+    expect(isOnline('not-a-date', NOW)).toBe(false)
+  })
+
+  it('ISO 문자열도 수용', () => {
+    expect(isOnline(new Date(NOW - 5_000).toISOString(), NOW)).toBe(true)
+  })
+
+  it('미래 시각(클럭 스큐) → online 으로 관대', () => {
+    expect(isOnline(new Date(NOW + 60_000), NOW)).toBe(true)
+  })
+
+  it('커스텀 ttl', () => {
+    expect(isOnline(new Date(NOW - 20_000), NOW, 10_000)).toBe(false)
+    expect(isOnline(new Date(NOW - 5_000), NOW, 10_000)).toBe(true)
+  })
+})

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

@@ -0,0 +1,21 @@
+/*
+ * presence — lastSeenAt 기반 online 판정 (Phase Board-AI C4). 순수·결정적 → 테스트 가능.
+ * 클라이언트가 주기적 heartbeat(touchPresence)로 lastSeenAt 을 갱신하고, roster 는
+ * 이 판정으로 online/offline 표시. 시각(now)을 주입받아 시간 의존성을 제거.
+ */
+
+/** online 으로 간주할 기본 유예(ms) — heartbeat 주기의 ~2.5배 권장(주기 30s → 75s). */
+export const PRESENCE_TTL_MS = 75_000
+
+/** lastSeenAt 이 now 기준 ttl 이내면 online. lastSeenAt 없으면 offline. */
+export function isOnline(
+  lastSeenAt: Date | string | null | undefined,
+  now: number,
+  ttlMs: number = PRESENCE_TTL_MS
+): boolean {
+  if (!lastSeenAt) return false
+  const t = lastSeenAt instanceof Date ? lastSeenAt.getTime() : new Date(lastSeenAt).getTime()
+  if (!Number.isFinite(t)) return false
+  const age = now - t
+  return age >= 0 ? age <= ttlMs : true // 미래 시각(클럭 스큐)은 online 으로 관대 처리
+}