@things-factory/ai-assistant 10.1.221 → 10.1.222

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/ai-assistant",
-  "version": "10.1.221",
+  "version": "10.1.222",
   "main": "dist-server/index.js",
   "things-factory": true,
   "author": "heartyoh",
@@ -55,5 +55,5 @@
     "copyfiles": "^2.4.1",
     "rimraf": "^5.0.0"
   },
-  "gitHead": "90e211d7a2c99216e017bd19a62e1703b20f2710"
+  "gitHead": "afdd6a9b1c8b440e39d4fec48bfbad1a0c02fccc"
 }

package/server/service/data-read/read-target.ts

@@ -46,6 +46,12 @@ export interface ReadColumn {
    * currencies are never added into one number.
    */
   currency?: string
+  /**
+   * The i18n prefix that names this column's codes - `<words><code>` (`announcement.category.` reads `HR` as
+   * `announcement.category.HR`). The rows keep the code, so a filter or a card's match means the same in every
+   * language; the model is given the words (`legendOf`) and a table or chart shows them (`wordOf`).
+   */
+  words?: string
 }
 
 export interface ReadScreen {
@@ -307,8 +313,55 @@ export function filtersOf(target: ReadTarget, criteria: Record<string, unknown>)
 
 export const valueAt = (row: any, path: string) => path.split('.').reduce((at, part) => (at === null || at === undefined ? undefined : at[part]), row)
 
-/** One row as the columns say - a number column as a number, a missing value as null. */
-export function rowOf(target: Pick<ReadTarget, 'columns'>, item: any): Record<string, string | number | null> {
+/**
+ * A date column's moment as people read it - `YYYY-MM-DD HH:mm` in the domain's time zone. A day (`YYYY-MM-DD`) or
+ * month stays as it is; anything that is not a moment is left alone. Still ordered as text, so a card's comparison
+ * with a day keeps working.
+ */
+export function localDateTime(value: string, timeZone?: string): string {
+  if (!/^\d{4}-\d{2}-\d{2}T/.test(value)) return value
+  const moment = new Date(value)
+  if (Number.isNaN(moment.getTime())) return value
+  try {
+    const parts = Object.fromEntries(
+      new Intl.DateTimeFormat('en-CA', { timeZone: timeZone || undefined, year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', hourCycle: 'h23' })
+        .formatToParts(moment)
+        .map(part => [part.type, part.value])
+    )
+    return `${parts.year}-${parts.month}-${parts.day} ${parts.hour}:${parts.minute}`
+  } catch {
+    return value
+  }
+}
+
+/** How the reader's words are asked - `(key, fallback)`, the fallback when the key has no word. */
+export type SayWord = (key: string | undefined, fallback: string) => string
+
+/** The word a coded value is read as, in the reader's language - the value itself when its column has no words. */
+export function wordOf(column: Pick<ReadColumn, 'words'> | undefined, value: unknown, say: SayWord): unknown {
+  if (!column?.words || value === null || value === undefined || value === '') return value
+  return say(`${column.words}${value}`, String(value))
+}
+
+/** The words of the coded values the rows hold, column by column - what the model reads the codes by. */
+export function legendOf(columns: readonly Pick<ReadColumn, 'name' | 'words'>[], rows: Record<string, any>[], say: SayWord): Record<string, Record<string, string>> {
+  const legend: Record<string, Record<string, string>> = {}
+  for (const column of columns) {
+    if (!column.words) continue
+    for (const row of rows) {
+      const code = row[column.name]
+      if (code === null || code === undefined || code === '') continue
+      ;(legend[column.name] ??= {})[String(code)] = String(wordOf(column, code, say))
+    }
+  }
+  return legend
+}
+
+/** What shapes a row besides its columns - the domain's time zone, for a moment. */
+export type RowOptions = { timeZone?: string }
+
+/** One row as the columns say - a number column as a number, a moment in the domain's time zone, a missing value as null. */
+export function rowOf(target: Pick<ReadTarget, 'columns'>, item: any, options: RowOptions = {}): Record<string, string | number | null> {
   return Object.fromEntries([
     /* The id names the record to the model - for one record's detail, a change, or its screen. */
     ...(item?.id ? [['id', String(item.id)] as [string, string]] : []),
@@ -319,7 +372,7 @@ export function rowOf(target: Pick<ReadTarget, 'columns'>, item: any): Record<st
         const number = Number(raw)
         return [column.name, Number.isFinite(number) ? number : null]
       }
-      return [column.name, String(raw)]
+      return [column.name, column.type === 'date' ? localDateTime(String(raw), options.timeZone) : String(raw)]
     })
   ])
 }
@@ -328,7 +381,13 @@ export function rowOf(target: Pick<ReadTarget, 'columns'>, item: any): Record<st
  * Reads the rows through the application's query, page by page, up to MAX_READ_ROWS. `complete` is false when the
  * list holds more - a sum of the rows read is then not the sum of the list, and is never said as one.
  */
-export async function readRows(target: ReadTarget, filters: ReadFilter[], run: GraphqlRunner, search?: string): Promise<{ rows: Record<string, any>[]; total: number; complete: boolean }> {
+export async function readRows(
+  target: ReadTarget,
+  filters: ReadFilter[],
+  run: GraphqlRunner,
+  search?: string,
+  options: RowOptions = {}
+): Promise<{ rows: Record<string, any>[]; total: number; complete: boolean }> {
   const rows: Record<string, any>[] = []
   let total = 0
   for (let page = 1; rows.length < MAX_READ_ROWS; page++) {
@@ -342,7 +401,7 @@ export async function readRows(target: ReadTarget, filters: ReadFilter[], run: G
     const read = target.rowsOf(answer.data)
     total = Number(read?.total) || 0
     const items = read?.rows ?? []
-    rows.push(...items.slice(0, MAX_READ_ROWS - rows.length).map(item => rowOf(target, item)))
+    rows.push(...items.slice(0, MAX_READ_ROWS - rows.length).map(item => rowOf(target, item, options)))
     if (items.length < READ_PAGE || rows.length >= total) break
   }
   return { rows, total, complete: rows.length >= total }

package/server/service/data-read/read-tools.ts

@@ -22,6 +22,7 @@ import {
   type DetailArg,
   type DetailRead,
   groupsOf,
+  legendOf,
   queryToolName,
   readCategoryName,
   readCriteria,
@@ -30,6 +31,7 @@ import {
   screenAddress,
   screenToolName,
   sumsOf,
+  wordOf,
   type ReadCriterion,
   type ReadTarget
 } from './read-target.js'
@@ -62,7 +64,9 @@ export async function queryRecords(target: ReadTarget, args: any, context: any,
   }
   let read
   try {
-    read = await readRows(target, filtersOf(target, criteria), run, typeof criteria.text === 'string' && target.search ? criteria.text : undefined)
+    read = await readRows(target, filtersOf(target, criteria), run, typeof criteria.text === 'string' && target.search ? criteria.text : undefined, {
+      timeZone: context?.state?.domain?.timezone
+    })
   } catch (error: any) {
     return { rejected: true, error: 'query-failed', message: `the list could not be read: ${error?.message ?? error}` }
   }
@@ -72,6 +76,8 @@ export async function queryRecords(target: ReadTarget, args: any, context: any,
   const groups = groupBy ? groupsOf(target, rows, groupBy) : undefined
   const words = wordsOf(context)
   const label = words(target.labelKey, target.key)
+  /* The rows keep their codes - a condition names them; the person is told the words (ADR-0163, 2026-10-26). */
+  const legend = legendOf(target.columns, rows, words)
 
   const said = {
     target: target.key,
@@ -82,7 +88,8 @@ export async function queryRecords(target: ReadTarget, args: any, context: any,
     sums,
     ...(groupBy ? (groups ? { groupBy, groups: groups.slice(0, 50), ...(groups.length > 50 ? { moreGroups: groups.length - 50 } : {}) } : { groupBy, groupRefused: 'no such column' }) : {}),
     rows: rows.slice(0, ROWS_FOR_MODEL),
-    ...(rows.length > ROWS_FOR_MODEL ? { rowsNotShown: rows.length - ROWS_FOR_MODEL } : {})
+    ...(rows.length > ROWS_FOR_MODEL ? { rowsNotShown: rows.length - ROWS_FOR_MODEL } : {}),
+    ...(Object.keys(legend).length ? { legend, legendNote: 'a coded value is said by its word in legend, never by its code' } : {})
   }
   const incomplete = complete
     ? ''
@@ -97,6 +104,8 @@ export async function queryRecords(target: ReadTarget, args: any, context: any,
 
   /* The workspace is built here from the rows as read - the model never copies the table. */
   const columns = target.columns.map(column => ({ name: column.name, label: words(column.labelKey, column.name), type: column.type }))
+  const shownRows = rows.map(row => Object.fromEntries(Object.entries(row).map(([name, value]) => [name, wordOf(target.columns.find(one => one.name === name), value, words)])))
+  const groupColumn = target.columns.find(one => one.name === groupBy)
   const totalColumns = target.columns.filter(one => one.total)
   /* A sum per currency is one figure and one group column per currency it holds - 「계약금액 (USD)」. */
   const sumColumns = totalColumns.flatMap(column => {
@@ -122,11 +131,11 @@ export async function queryRecords(target: ReadTarget, args: any, context: any,
               kind: 'table',
               caption: words(target.columns.find(one => one.name === groupBy)?.labelKey, groupBy!),
               columns: [{ name: 'key', label: words(target.columns.find(one => one.name === groupBy)?.labelKey, groupBy!), type: 'string' }, { name: 'count', label: words('ai-assistant.read.count', 'rows'), type: 'number' }, ...sumColumns.map(column => ({ name: column.name, label: column.label, type: 'number' }))],
-              rows: groups.map(group => ({ key: group.key, count: group.count, ...Object.fromEntries(sumColumns.map(column => [column.name, column.of(group.sums)])) }))
+              rows: groups.map(group => ({ key: wordOf(groupColumn, group.key, words), count: group.count, ...Object.fromEntries(sumColumns.map(column => [column.name, column.of(group.sums)])) }))
             }
           ]
         : []),
-      { kind: 'table', caption: label, columns, rows }
+      { kind: 'table', caption: label, columns, rows: shownRows }
     ]
   })
   return {

package/server/service/data-read/read-words.test.ts

@@ -0,0 +1,92 @@
+/*
+ * What people read off a list (ADR-0163, 2026-10-26: answers and cards showed EVENT, unread and 2026-10-26T09:09:03Z):
+ * a moment in the domain's time zone, and a coded value by its word - the rows keep the code, so a condition means the
+ * same in every language.
+ */
+import { listReadTarget } from './list-read'
+import { clearReadTargets, legendOf, localDateTime, rowOf, wordOf } from './read-target'
+import { queryRecords } from './read-tools'
+
+const WORDS: Record<string, string> = { 'notice.kind.HR': '인사', 'notice.kind.EVENT': '행사', 'notice.state.unread': '안 읽음' }
+const say = (key: string | undefined, fallback: string) => (key && WORDS[key]) || fallback
+
+describe('a moment', () => {
+  it('★ is said in the domain\'s time zone, to the minute', () => {
+    expect(localDateTime('2026-10-26T09:09:03.235Z', 'Asia/Seoul')).toBe('2026-10-26 18:09')
+    /* Past midnight there, it is the next day. */
+    expect(localDateTime('2026-10-26T20:00:00Z', 'Asia/Seoul')).toBe('2026-10-27 05:00')
+    expect(localDateTime('2026-10-26T20:00:00Z', 'UTC')).toBe('2026-10-26 20:00')
+  })
+
+  it('★ a day, a month or anything else stays as it is', () => {
+    expect(localDateTime('2026-10-26', 'Asia/Seoul')).toBe('2026-10-26')
+    expect(localDateTime('2026-10', 'Asia/Seoul')).toBe('2026-10')
+    expect(localDateTime('2026-10-26Tnot', 'Asia/Seoul')).toBe('2026-10-26Tnot')
+  })
+
+  it('★ a row reads its date columns so, and leaves the other columns alone', () => {
+    const columns = [
+      { name: 'at', type: 'date' as const },
+      { name: 'note', type: 'string' as const }
+    ]
+    expect(rowOf({ columns }, { id: 'a', at: '2026-10-26T09:09:03.235Z', note: '2026-10-26T09:09:03.235Z' }, { timeZone: 'Asia/Seoul' })).toEqual({
+      id: 'a',
+      at: '2026-10-26 18:09',
+      note: '2026-10-26T09:09:03.235Z'
+    })
+  })
+})
+
+describe('a coded value', () => {
+  const kind = { name: 'kind', words: 'notice.kind.' }
+  it('★ is read by its word, the code itself when there is none', () => {
+    expect(wordOf(kind, 'HR', say)).toBe('인사')
+    expect(wordOf(kind, 'SYSTEM', say)).toBe('SYSTEM')
+    expect(wordOf({ name: 'title' }, 'HR', say)).toBe('HR')
+    expect(wordOf(kind, null, say)).toBeNull()
+  })
+
+  it('★ the legend names the codes the rows hold, column by column', () => {
+    expect(legendOf([kind, { name: 'title' }], [{ kind: 'HR', title: 'a' }, { kind: 'EVENT', title: 'b' }, { kind: null }], say)).toEqual({ kind: { HR: '인사', EVENT: '행사' } })
+  })
+})
+
+describe('the read tool', () => {
+  const target = listReadTarget({
+    key: 'test.notices',
+    title: 'title.notices',
+    name: 'notices',
+    listQuery: 'notices',
+    selection: 'id title kind state publishedAt',
+    columns: [
+      { name: 'title', type: 'string' },
+      { name: 'kind', type: 'string', words: 'notice.kind.' },
+      { name: 'state', type: 'string', words: 'notice.state.' },
+      { name: 'publishedAt', type: 'date' }
+    ],
+    status: { field: 'state', values: ['unread', 'read'] }
+  })
+  const items = Array.from({ length: 3 }, (_, i) => ({ id: `n${i}`, title: `t${i}`, kind: i ? 'EVENT' : 'HR', state: 'unread', publishedAt: '2026-10-26T09:09:03.235Z' }))
+  const calls: any[] = []
+  const run = async (_document: string, variables: any) => (calls.push(variables), { data: { notices: { items, total: items.length } } })
+  /* Not this machine's zone - a read that forgot the domain's zone would read the machine's instead. */
+  const context = { t: (key: string) => WORDS[key] ?? key, state: { domain: { timezone: 'UTC' } } }
+
+  beforeEach(() => {
+    clearReadTargets()
+    calls.length = 0
+  })
+
+  it('★ gives the model the codes, their words and the moments in the domain\'s time - and its condition names the code', async () => {
+    const result: any = await queryRecords(target, { status: 'unread' }, context, run)
+    expect(calls[0].filters).toEqual([{ name: 'state', operator: 'eq', value: 'unread' }])
+    expect(result.rows[0]).toMatchObject({ kind: 'HR', state: 'unread', publishedAt: '2026-10-26 09:09' })
+    expect(result.legend).toEqual({ kind: { HR: '인사', EVENT: '행사' }, state: { unread: '안 읽음' } })
+  })
+
+  it('★ the 작업판 table shows the words', async () => {
+    const result: any = await queryRecords(target, { show: 'workspace' }, context, run)
+    const table = result.forScreen.workspace.blocks.find((one: any) => one.kind === 'table')
+    expect(table.rows[0]).toMatchObject({ kind: '인사', state: '안 읽음', publishedAt: '2026-10-26 09:09' })
+  })
+})