@things-factory/announcement 10.1.250 → 10.1.254

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/announcement",
-  "version": "10.1.250",
+  "version": "10.1.254",
   "main": "dist-server/index.js",
   "browser": "dist-client/index.js",
   "things-factory": true,
@@ -36,18 +36,18 @@
     "@operato/shell": "^10.29.39",
     "@operato/styles": "^10.29.1",
     "@operato/utils": "^10.0.0",
-    "@things-factory/ai-assistant": "^10.1.250",
-    "@things-factory/attachment-base": "^10.1.250",
-    "@things-factory/auth-base": "^10.1.250",
+    "@things-factory/ai-assistant": "^10.1.254",
+    "@things-factory/attachment-base": "^10.1.254",
+    "@things-factory/auth-base": "^10.1.254",
     "@things-factory/env": "^10.1.149",
-    "@things-factory/i18n-base": "^10.1.250",
-    "@things-factory/notification": "^10.1.250",
-    "@things-factory/organization": "^10.1.250",
-    "@things-factory/shell": "^10.1.247",
+    "@things-factory/i18n-base": "^10.1.254",
+    "@things-factory/notification": "^10.1.254",
+    "@things-factory/organization": "^10.1.254",
+    "@things-factory/shell": "^10.1.254",
     "graphql-scalars": "^1.22.0",
     "graphql-tag": "^2.12.6",
     "graphql-upload": "^15.0.2",
     "lit": "^3.1.2"
   },
-  "gitHead": "4fdb6d24ef24f43d9e158d4c6d6396ad3097bb9e"
+  "gitHead": "793e2fd617db5bb917ec892e64956fb690f7e7b0"
 }

package/server/service/announcement/announcement-trigger.ts

@@ -0,0 +1,123 @@
+/*
+ * 계기 (ADR-0163 decision 7, the least of it) - a module tells of a fact of its own as an announcement: a company rule
+ * adopted, a training scheduled. The module names the trigger and gives the words and the record; the application says,
+ * once at boot, how an announcement of that trigger goes out (its kind, its weight, who reads it, draft or out at once).
+ * A trigger with no rule writes nothing - an application that has not decided tells nobody.
+ *
+ * The announcement keeps its trigger and record (`trigger`, `sourceKind`, `sourceId`), so the record finds the
+ * announcements of it and their readings - the reading is kept here once, never again by the module.
+ */
+import { EntityManager, In } from 'typeorm'
+
+import { logger } from '@things-factory/env'
+import { getRepository } from '@things-factory/shell'
+
+import { Announcement, AnnouncementAudience, AnnouncementImportance, AnnouncementReceipt, AnnouncementStatus } from './announcement'
+import { ANNOUNCEMENT_CATEGORIES, rankOf } from './announcement-rules'
+import { sendOut, tellWhenCommitted } from './announcement-service'
+
+export interface AnnouncementTrigger {
+  /** `compliance.regulation-adopted` - the module's name, a dot, the fact. */
+  name: string
+  description: string
+}
+
+export interface AnnouncementTriggerRule {
+  category?: (typeof ANNOUNCEMENT_CATEGORIES)[number]
+  importance?: AnnouncementImportance | 'NORMAL' | 'IMPORTANT' | 'URGENT'
+  requiresAcknowledgement?: boolean
+  popup?: boolean
+  sendEmail?: boolean
+  /** Who reads it when the trigger names nobody: the whole domain, or nobody (the trigger must name them). */
+  audience?: 'DOMAIN' | 'GIVEN'
+  /** Out at once; otherwise written as a draft for its writer to look over and send (ADR-0187 정한 것 2). */
+  publish?: boolean
+}
+
+export interface AnnouncementOfTrigger {
+  trigger: string
+  sourceKind: string
+  sourceId: string
+  title: string
+  body?: string
+  links?: { label: string; url: string }[]
+  audiences?: { scope: 'DOMAIN' | 'DEPARTMENT' | 'ROLE' | 'USER'; targetId: string; targetName?: string }[]
+  /** The day by which the readers are asked to acknowledge it, where the rule asks for that. */
+  acknowledgeBy?: Date | null
+}
+
+const TRIGGERS = new Map<string, AnnouncementTrigger>()
+const RULES = new Map<string, AnnouncementTriggerRule>()
+
+/** What a module calls at load to declare a trigger of its own. */
+export function registerAnnouncementTrigger(trigger: AnnouncementTrigger): void {
+  TRIGGERS.set(trigger.name, trigger)
+}
+
+/** What an application calls at boot: how announcements of a trigger go out. */
+export function configureAnnouncementTrigger(name: string, rule: AnnouncementTriggerRule): void {
+  RULES.set(name, rule)
+}
+
+export function announcementTriggers(): (AnnouncementTrigger & { rule?: AnnouncementTriggerRule })[] {
+  return [...TRIGGERS.values()].map(one => ({ ...one, rule: RULES.get(one.name) }))
+}
+
+/**
+ * Writes the announcement of a trigger in the request's transaction, its writer the request's person. Answers it, or
+ * nothing where the application set no rule for the trigger.
+ */
+export async function announce(context: any, of: AnnouncementOfTrigger): Promise<Announcement | null> {
+  const { domain, user, tx } = context.state as { domain: any; user: any; tx: EntityManager }
+  if (!TRIGGERS.has(of.trigger)) throw new Error(`announcement trigger '${of.trigger}' is not registered`)
+  const rule = RULES.get(of.trigger)
+  if (!rule) {
+    logger.info(`[Announcement] ${domain?.subdomain}: no rule for '${of.trigger}' - nothing written`)
+    return null
+  }
+  const importance = (rule.importance as AnnouncementImportance) ?? AnnouncementImportance.NORMAL
+  const requiresAcknowledgement = !!rule.requiresAcknowledgement
+  const repository = getRepository(Announcement, tx)
+  const saved = await repository.save({
+    domain,
+    title: of.title.trim().slice(0, 200),
+    body: of.body ?? null,
+    category: rule.category ?? 'GENERAL',
+    importance,
+    pinned: false,
+    rank: rankOf({ pinned: false, importance }),
+    requiresAcknowledgement,
+    acknowledgeBy: requiresAcknowledgement ? (of.acknowledgeBy ?? null) : null,
+    popup: !!rule.popup,
+    sendEmail: !!rule.sendEmail,
+    links: (of.links ?? []).slice(0, 10),
+    trigger: of.trigger,
+    sourceKind: of.sourceKind,
+    sourceId: of.sourceId,
+    status: AnnouncementStatus.DRAFT,
+    version: 1,
+    creator: user,
+    updater: user
+  } as any)
+  const audiences = of.audiences?.length ? of.audiences : rule.audience === 'GIVEN' ? [] : [{ scope: 'DOMAIN' as const, targetId: domain.id, targetName: domain.name }]
+  for (const target of audiences)
+    await getRepository(AnnouncementAudience, tx).save({ domain, announcement: { id: saved.id }, scope: target.scope, targetId: target.targetId, targetName: target.targetName?.slice(0, 100), creator: user, updater: user } as any)
+  if (!rule.publish || !audiences.length) return saved
+  const receivers = await sendOut(saved, domain, user, tx)
+  const fresh = (await repository.findOneBy({ id: saved.id }))!
+  await tellWhenCommitted(context, fresh, 'published', receivers, true)
+  return fresh
+}
+
+/** The announcements of a record, newest first - drafts too, the record's keepers read where it stands. */
+export async function announcementsOfSource(domain: { id: string }, sourceKind: string, sourceIds: string[], tx?: EntityManager): Promise<Announcement[]> {
+  if (!sourceIds.length) return []
+  return await getRepository(Announcement, tx).find({ where: { domain: { id: domain.id }, sourceKind, sourceId: In(sourceIds) } as any, order: { createdAt: 'DESC' } as any })
+}
+
+/** A person's readings of announcements, by announcement. */
+export async function receiptsOf(announcementIds: string[], userId: string, tx?: EntityManager): Promise<Map<string, AnnouncementReceipt>> {
+  if (!announcementIds.length) return new Map()
+  const rows = await getRepository(AnnouncementReceipt, tx).find({ where: { announcement: { id: In(announcementIds) }, user: { id: userId } } as any })
+  return new Map(rows.map(one => [one.announcementId!, one]))
+}

package/server/service/announcement/announcement.ts

@@ -35,6 +35,7 @@ registerEnumType(AnnouncementImportance, { name: 'AnnouncementImportance', descr
 
 @Entity()
 @Index('ix_announcement_0', (one: Announcement) => [one.domain, one.status, one.startsAt])
+@Index('ix_announcement_1', (one: Announcement) => [one.domain, one.sourceKind, one.sourceId])
 @ObjectType({ description: 'An announcement of a domain - written once, addressed to an audience, read and acknowledged by each of its people.' })
 export class Announcement {
   @PrimaryGeneratedColumn('uuid')
@@ -111,6 +112,18 @@ export class Announcement {
   @Field(type => GraphQLJSON, { nullable: true, description: 'Screens it points to - [{ label, url }], a screen of the application or an https address.' })
   links?: { label: string; url: string }[]
 
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'The trigger that wrote it (ADR-0163 decision 7) - `compliance.regulation-adopted`; empty for one a person wrote.' })
+  trigger?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'The kind of record it tells of - `RegulationVersion`; set by its trigger.' })
+  sourceKind?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'The record it tells of; set by its trigger.' })
+  sourceId?: string
+
   @Column('int', { default: 1 })
   @Field(type => Int, { description: 'The version - one more each time it is changed after it was published.' })
   version: number

package/server/service/index.ts

@@ -2,6 +2,7 @@
 export * from './announcement/announcement'
 export * from './announcement/announcement-rules'
 export { ANNOUNCEMENT_REF_TYPE, visibleAnnouncement } from './announcement/announcement-service'
+export * from './announcement/announcement-trigger'
 
 /* IMPORT ENTITIES AND RESOLVERS */
 import { entities as AnnouncementEntities, resolvers as AnnouncementResolvers } from './announcement'

package/test/announcement-persistence.test.ts

@@ -36,6 +36,7 @@ function loadCompiled(modulePath: string): any {
 }
 
 const service = loadCompiled('service/announcement/announcement-service')
+const triggers = loadCompiled('service/announcement/announcement-trigger')
 const { AnnouncementResolver } = loadCompiled('service/announcement/announcement-resolver')
 const { Announcement, AnnouncementAudience, AnnouncementReceipt, AnnouncementRevision } = loadCompiled('service/announcement/announcement')
 
@@ -269,3 +270,28 @@ describe("the reader's list - what the screen and the assistant read", () => {
     await expect(list('part', [{ name: 'readerState', operator: 'eq', value: 'lost' }])).rejects.toThrow()
   })
 })
+
+describe('계기 (ADR-0163 decision 7)', () => {
+  const words = { sourceKind: 'RegulationVersion', sourceId: '11111111-1111-1111-1111-111111111111', title: '취업규칙 제2판', body: '시행일 2026-12-01' }
+  const txContextOf = (who: string) => ({ state: { domain, user: people[who], tx: dataSource.manager } })
+
+  it('★ a trigger the application set no rule for writes nothing', async () => {
+    triggers.registerAnnouncementTrigger({ name: 'test.unruled', description: 'no rule' })
+    expect(await triggers.announce(txContextOf('writer'), { trigger: 'test.unruled', ...words })).toBeNull()
+    expect(await dataSource.getRepository(Announcement).count()).toBe(0)
+  })
+
+  it('★ writes a draft of its record to the whole domain by the rule, found again by its record', async () => {
+    triggers.registerAnnouncementTrigger({ name: 'test.adopted', description: 'adopted' })
+    triggers.configureAnnouncementTrigger('test.adopted', { category: 'HR', importance: 'IMPORTANT', requiresAcknowledgement: true, popup: true })
+    const one = await triggers.announce(txContextOf('writer'), { trigger: 'test.adopted', ...words })
+    expect(one).toMatchObject({ status: 'DRAFT', category: 'HR', importance: 'IMPORTANT', requiresAcknowledgement: true, popup: true, trigger: 'test.adopted', sourceKind: 'RegulationVersion' })
+    expect((await service.audiencesOf(one.id)).map((target: any) => [target.scope, target.targetId])).toEqual([['DOMAIN', domain.id]])
+    expect(told).toHaveLength(0)
+    expect((await triggers.announcementsOfSource(domain, 'RegulationVersion', [words.sourceId])).map((found: any) => found.id)).toEqual([one.id])
+  })
+
+  it('a trigger nobody registered is a mistake of the module, not a quiet nothing', async () => {
+    await expect(triggers.announce(txContextOf('writer'), { trigger: 'test.unknown', ...words })).rejects.toThrow(/not registered/)
+  })
+})