@shanyucoder/flowgrid 0.1.5 → 0.1.9

package/engines/docs/lib/qa-item.mjs

@@ -0,0 +1,91 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import Ajv2020 from 'ajv/dist/2020.js'
+import { parse } from 'yaml'
+
+export const QA_ITEM_SCHEMA_ID = 'flowgrid-qa-item/v1'
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..')
+
+let compiledValidator = null
+
+function loadSchema() {
+  const schemaPath = path.join(packageRoot, 'templates/schemas/qa-item.schema.json')
+  return JSON.parse(readFileSync(schemaPath, 'utf8'))
+}
+
+/**
+ * @param {Date} [date]
+ * @returns {string} YYYYMMDD HH:mm
+ */
+export function formatQaAt(date = new Date()) {
+  const d = date
+  const y = d.getFullYear()
+  const m = String(d.getMonth() + 1).padStart(2, '0')
+  const day = String(d.getDate()).padStart(2, '0')
+  const h = String(d.getHours()).padStart(2, '0')
+  const min = String(d.getMinutes()).padStart(2, '0')
+  return `${y}${m}${day} ${h}:${min}`
+}
+
+/**
+ * @param {string} screen e.g. W-HOTEL-LIST
+ */
+export function suggestQaShort(screen) {
+  const s = String(screen ?? '').trim()
+  if (!s) return 'QA'
+  if (/^W-/i.test(s)) return s.slice(2).toUpperCase()
+  return s.replace(/[^a-zA-Z0-9]+/g, '-').replace(/^-|-$/g, '').toUpperCase()
+}
+
+/**
+ * @param {string} hubRoot
+ * @param {string} shortSlug e.g. HOTEL-LIST
+ * @returns {string} four-digit sequence
+ */
+export function nextQaSequence(hubRoot, shortSlug) {
+  const qaDir = path.join(path.resolve(hubRoot), 'qa')
+  const prefix = `${shortSlug}_`
+  let max = 0
+  const scan = (dir) => {
+    if (!existsSync(dir)) return
+    for (const name of readdirSync(dir)) {
+      if (!name.toLowerCase().startsWith(prefix.toLowerCase())) continue
+      const m = name.match(/_(\d{4})\.ya?ml$/i)
+      if (m) max = Math.max(max, Number.parseInt(m[1], 10))
+    }
+  }
+  scan(qaDir)
+  scan(path.join(qaDir, 'open'))
+  return String(max + 1).padStart(4, '0')
+}
+
+/**
+ * @param {string} hubRoot
+ * @param {string} shortSlug
+ */
+export function nextQaId(hubRoot, shortSlug) {
+  return `${shortSlug}_${nextQaSequence(hubRoot, shortSlug)}`
+}
+
+/**
+ * @param {unknown} doc parsed YAML object
+ * @returns {{ ok: true } | { ok: false, errors: import('ajv').ErrorObject[] }}
+ */
+export function validateQaItem(doc) {
+  if (!compiledValidator) {
+    compiledValidator = new Ajv2020({ allErrors: true }).compile(loadSchema())
+  }
+  const ok = compiledValidator(doc)
+  if (ok) return { ok: true }
+  return { ok: false, errors: compiledValidator.errors ?? [] }
+}
+
+/**
+ * @param {string} filePath
+ */
+export function validateQaItemFile(filePath) {
+  const doc = parse(readFileSync(filePath, 'utf8'))
+  return validateQaItem(doc)
+}

package/engines/docs/lib/render-api-summary-markdown.mjs

@@ -0,0 +1,28 @@
+import { renderBackendSpecMarkdown } from '../../openapi/lib/render-backend-spec-markdown.mjs'
+
+/**
+ * Reader-facing API summary for VitePress (SSOT contract remains 01 YAML).
+ * @param {Record<string, unknown>} backendSpec Parsed 01-backend-spec.yaml
+ * @param {{ pageId?: string, title?: string, backendRelPath?: string }} meta
+ */
+export function renderApiSummaryMarkdown(backendSpec, meta = {}) {
+  const pageId = meta.pageId ?? backendSpec.feature?.id ?? '—'
+  const title = meta.title ?? backendSpec.feature?.title ?? 'Backend API'
+  const body = renderBackendSpecMarkdown(backendSpec, {
+    specFile: meta.backendRelPath ?? 'api/<seq>/01-backend-spec.yaml',
+    slug: title,
+  })
+  const header = [
+    `> **Page ID:** \`${pageId}\` · Tóm tắt đọc trên site. **SSOT codegen:** \`01-backend-spec.yaml\` — sửa qua \`/api-update\`, không edit file này tay.`,
+    '',
+    `- **Spec nghiệp vụ:** [spec.md](./spec.md) · **Data model:** [data-model.md](./data-model.md) · SSOT file: \`${meta.backendRelPath ?? '01-backend-spec.yaml'}\``,
+    '',
+  ].join('\n')
+  const lines = body.split('\n')
+  const h1 = lines.findIndex((l) => l.startsWith('# '))
+  if (h1 >= 0) {
+    lines.splice(h1 + 1, 0, '', ...header.trimEnd().split('\n'), '')
+    return lines.join('\n').endsWith('\n') ? lines.join('\n') : `${lines.join('\n')}\n`
+  }
+  return `${header}\n${body}`
+}

package/engines/docs/lib/render-bundle-markdown.mjs

@@ -3,6 +3,9 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises'
 import path from 'node:path'
 import { parse } from 'yaml'
 import { renderSpecMarkdown } from './render-spec-markdown.mjs'
+import { renderDataModelMarkdown } from './render-data-model-markdown.mjs'
+import { renderApiSummaryMarkdown } from './render-api-summary-markdown.mjs'
+import { resolveBackendSpecForBundle } from '../../spec/lib/audit-db-tables.mjs'
 
 /**
  * Flatten bundle → spec shape (tests / fallback). Prefer ir/spec.yaml for site MD.
@@ -67,6 +70,22 @@ export function irGeneratedMarkdownPath(bundleFile) {
   return path.join(dir, 'ir', 'generated', 'spec.md')
 }
 
+/** Reviewer-facing DB tables — `…/<leaf>/ir/generated/data-model.md` */
+export function irGeneratedDataModelPath(bundleFile) {
+  const dir = path.dirname(path.resolve(bundleFile))
+  return path.join(dir, 'ir', 'generated', 'data-model.md')
+}
+
+/** API summary for readers — `…/<leaf>/ir/generated/api.md` */
+export function irGeneratedApiPath(bundleFile) {
+  const dir = path.dirname(path.resolve(bundleFile))
+  return path.join(dir, 'ir', 'generated', 'api.md')
+}
+
+export function designIrPathForBundle(bundleFile) {
+  return path.join(path.dirname(path.resolve(bundleFile)), 'ir', 'design.yaml')
+}
+
 export function irSpecPathForBundle(bundleFile) {
   return path.join(path.dirname(path.resolve(bundleFile)), 'ir', 'spec.yaml')
 }
@@ -77,13 +96,69 @@ export function irSpecPathForBundle(bundleFile) {
 export async function writeBundleMarkdownFile(bundleFile, context = {}) {
   const specFile = irSpecPathForBundle(bundleFile)
   if (!existsSync(specFile)) return null
-  return writeIrSpecMarkdownFile(specFile, irGeneratedMarkdownPath(bundleFile), context)
+  const specOut = await writeIrSpecMarkdownFile(specFile, irGeneratedMarkdownPath(bundleFile), context)
+  await writeDataModelMarkdownFile(bundleFile)
+  await writeApiMarkdownFile(bundleFile)
+  return specOut
+}
+
+export async function writeApiMarkdownFile(bundleFile) {
+  const resolved = path.resolve(bundleFile)
+  const backendPath = resolveBackendSpecForBundle(resolved, null)
+  if (!backendPath || !existsSync(backendPath)) return null
+  const backendSpec = parse(await readFile(backendPath, 'utf8')) ?? {}
+  const specFile = irSpecPathForBundle(bundleFile)
+  const spec = existsSync(specFile) ? parse(await readFile(specFile, 'utf8')) ?? {} : {}
+  const pageId = spec['page-id'] ?? spec.id
+  const markdown = renderApiSummaryMarkdown(backendSpec, {
+    pageId,
+    title: spec.title ?? backendSpec.feature?.title,
+    backendRelPath: path.relative(path.dirname(resolved), backendPath).split(path.sep).join('/'),
+  })
+  const out = irGeneratedApiPath(bundleFile)
+  await mkdir(path.dirname(out), { recursive: true })
+  await writeFile(out, markdown, 'utf8')
+  return out
+}
+
+export async function writeDataModelMarkdownFile(bundleFile) {
+  const designFile = designIrPathForBundle(bundleFile)
+  if (!existsSync(designFile)) return null
+  const design = parse(await readFile(designFile, 'utf8')) ?? {}
+  const specFile = irSpecPathForBundle(bundleFile)
+  const spec = existsSync(specFile) ? parse(await readFile(specFile, 'utf8')) ?? {} : {}
+  const markdown = renderDataModelMarkdown({
+    pageId: spec.id ?? design.id,
+    title: spec.title ?? design.title,
+    design,
+    spec,
+  })
+  const out = irGeneratedDataModelPath(bundleFile)
+  await mkdir(path.dirname(out), { recursive: true })
+  await writeFile(out, markdown, 'utf8')
+  return out
+}
+
+export function mergeDesignIntoSpecForRender(spec, design) {
+  if (!design || typeof design !== 'object') return spec
+  const out = { ...spec }
+  if (design.ui?.list) {
+    out.ui = { ...(out.ui ?? {}), list: { ...(out.ui?.list ?? {}), ...design.ui.list } }
+  }
+  if (design.sections && !out.sections) out.sections = design.sections
+  if (design.actions && !out.actions) out.actions = design.actions
+  if (design.stateMatrix && !out.stateMatrix) out.stateMatrix = design.stateMatrix
+  if (design.nav && !out.nav) out.nav = design.nav
+  return out
 }
 
 export async function writeIrSpecMarkdownFile(specFile, mdOut, context = {}) {
   const spec = parse(await readFile(specFile, 'utf8')) ?? {}
+  const designFile = path.join(path.dirname(specFile), 'design.yaml')
+  const design = existsSync(designFile) ? parse(await readFile(designFile, 'utf8')) ?? {} : {}
+  const specShape = mergeDesignIntoSpecForRender(spec, design)
   const projectRoot = context.projectRoot ?? process.cwd()
-  const markdown = renderIrSpecMarkdown(spec, {
+  const markdown = renderIrSpecMarkdown(specShape, {
     testcases: [],
     output: { specFile: path.basename(mdOut), testcasesDir: 'testcases' },
     devAppBaseUrl: context.devAppBaseUrl ?? '',

package/engines/docs/lib/render-data-model-markdown.mjs

@@ -0,0 +1,171 @@
+import { renderTable } from './markdown-table.mjs'
+import { collectDesignDbBindings } from '../../spec/lib/audit-db-tables.mjs'
+
+function roleLabel(role) {
+  const map = {
+    read: 'Chỉ đọc',
+    write: 'Chỉ ghi',
+    'read-write': 'Đọc & ghi',
+    join: 'Join / lookup',
+    aggregate: 'Tổng hợp (read)',
+  }
+  return map[role] || role || '—'
+}
+
+function groupBindingsByTable(bindings) {
+  const byTable = new Map()
+  for (const b of bindings) {
+    if (!b.schema || !b.field) continue
+    if (!byTable.has(b.schema)) byTable.set(b.schema, [])
+    byTable.get(b.schema).push(b)
+  }
+  return byTable
+}
+
+function tableOverviewRows(design, tableNames) {
+  const meta = design.dataModel?.tables
+  const byName = new Map()
+  if (Array.isArray(meta)) {
+    for (const t of meta) {
+      if (t?.schema) byName.set(String(t.schema), t)
+    }
+  }
+  return tableNames.map((schema) => {
+    const m = byName.get(schema) ?? {}
+    return [
+      `\`${schema}\``,
+      roleLabel(m.roleOnScreen),
+      m.summary || m.purpose || '—',
+      m.erdEntity ? `\`${m.erdEntity}\`` : '—',
+    ]
+  })
+}
+
+/**
+ * Human-readable DB view for reviewers (multi-table safe). SSOT remains bundle / ir/design.yaml + 01.
+ * @param {{
+ *   pageId?: string,
+ *   title?: string,
+ *   design?: Record<string, unknown>,
+ *   spec?: Record<string, unknown>,
+ * }} input
+ */
+export function renderDataModelMarkdown(input = {}) {
+  const design = input.design ?? {}
+  const spec = input.spec ?? {}
+  const pageId = input.pageId ?? design.id ?? '—'
+  const title = input.title ?? design.title ?? pageId
+  const bundleShape = { design, spec: { entities: design.entities ?? spec.entities, ui: design.ui ?? spec.ui } }
+  const { bindings, tables } = collectDesignDbBindings(bundleShape)
+  const fullBindings = bindings.filter((b) => b.schema && b.field)
+  const byTable = groupBindingsByTable(fullBindings)
+  const tableNames = tables.length ? tables : [...byTable.keys()]
+
+  const parts = [
+    `# Data model — ${title}`,
+    '',
+    `> **Page ID:** \`${pageId}\` · Đọc cùng [spec.md](./spec.md) trên VitePress (sidebar **Data model**). SSOT ghi: bundle + \`ir/design.yaml\` · BE: \`api/*/01-backend-spec.yaml\`.`,
+    '',
+  ]
+
+  if (design.dataModel?.erdRef || design.dataModel?.notes) {
+    parts.push('## Ghi chú & ERD', '')
+    if (design.dataModel.erdRef) {
+      parts.push(`- **ERD (Phase 0):** ${design.dataModel.erdRef}`)
+    }
+    if (design.dataModel.notes) {
+      parts.push('', String(design.dataModel.notes), '')
+    }
+    parts.push('')
+  }
+
+  const entities = design.entities ?? spec.entities
+  if (Array.isArray(entities) && entities.length) {
+    parts.push('## Entity trên màn (spec.entities)', '')
+    for (const e of entities) {
+      if (typeof e === 'string') {
+        parts.push(`- **${e}**`)
+        continue
+      }
+      const name = e.name ?? e.table ?? 'Entity'
+      parts.push(`- **${name}**${e.description ? ` — ${e.description}` : ''}`)
+      if (e.relatesTo) parts.push(`  - Quan hệ: ${e.relatesTo}`)
+    }
+    parts.push('')
+  }
+
+  if (Array.isArray(design.relationships) && design.relationships.length) {
+    parts.push('## Quan hệ (relationships)', '')
+    for (const r of design.relationships) {
+      parts.push(`- ${typeof r === 'string' ? r : formatRecord(r)}`)
+    }
+    parts.push('')
+  }
+
+  if (tableNames.length) {
+    parts.push('## Tổng quan bảng (multi-table)', '')
+    parts.push(
+      renderTable(
+        ['Bảng (schema)', 'Vai trò trên màn', 'Mô tả review', 'Entity ER (nếu có)'],
+        tableOverviewRows(design, tableNames),
+      ),
+      '',
+    )
+  }
+
+  if (!fullBindings.length) {
+    parts.push(
+      '_Chưa có `design.sections[].db` / list column `db` — bổ sung trên bundle rồi chạy `flowgrid split`._',
+      '',
+    )
+    return parts.join('\n')
+  }
+
+  for (const schema of tableNames) {
+    const rows = (byTable.get(schema) ?? []).map((b) => {
+      const enumStr =
+        b.enumMapping && typeof b.enumMapping === 'object'
+          ? Object.entries(b.enumMapping)
+              .map(([k, v]) => `\`${k}\` → ${v}`)
+              .join('<br>')
+          : '—'
+      return [
+        b.label || '—',
+        b.bindField ? `\`${b.bindField}\`` : '—',
+        `\`${b.field}\``,
+        b.required ? 'Có' : 'Không',
+        b.path?.includes('list') ? 'List' : 'Form / section',
+        enumStr,
+      ]
+    })
+    if (!rows.length) continue
+    parts.push(`## Bảng \`${schema}\``, '')
+    parts.push(
+      renderTable(
+        ['Nhãn UI', 'bind.field (API/payload)', 'Cột DB', 'Bắt buộc?', 'Nguồn UI', 'enumMapping'],
+        rows,
+      ),
+      '',
+    )
+  }
+
+  parts.push(
+    '## Backend codegen',
+    '',
+    '- Map `db.schema` ↔ `01-backend-spec.yaml` → `modules[].entities[].table` (hoặc `name`).',
+    '- Map `db.field` ↔ `entities[].fields[].name`; quan hệ ORM theo ERD + `entity-relationship.md` extract.',
+    '- `bind.field` ↔ request/response DTO trên endpoint (`executionContract.apiRef`).',
+    '',
+  )
+
+  return `${parts.join('\n').trim()}\n`
+}
+
+function formatRecord(obj) {
+  if (obj == null) return ''
+  if (typeof obj !== 'object') return String(obj)
+  return Object.entries(obj)
+    .filter(([, v]) => v != null && v !== '')
+    .map(([k, v]) => `${k}: ${v}`)
+    .join('; ')
+}

package/engines/docs/lib/render-design-tables.mjs

@@ -120,6 +120,95 @@ export function collectFormFields(nodes = []) {
 /**
  * Bảng Từ Điển Dữ Liệu & Quy Tắc Kiểm Tra Hợp Lệ (Data Dictionary Table 6 cột)
  */
+/**
+ * Bảng cột danh sách (list / admin-crud) — từ spec.ui.list, không chỉ form sections.
+ * @param {{ columns?: unknown[], filters?: unknown[], pagination?: unknown }} listUi
+ */
+/**
+ * @param {{ filters?: unknown[], pagination?: unknown }} listUi
+ */
+export function renderListFiltersTable(listUi = {}) {
+  const filters = listUi?.filters
+  if (!Array.isArray(filters) || !filters.length) return ''
+
+  const rows = filters.map((f) => {
+    if (!f || typeof f !== 'object') return null
+    return [
+      f.label || f.name || '—',
+      f.name != null ? `\`${f.name}\`` : '—',
+      f.type || '—',
+      f.widget || '—',
+      f.meaning || '—',
+      f.purpose || '—',
+      f.placeholder || '—',
+    ]
+  }).filter(Boolean)
+
+  if (!rows.length) return ''
+
+  return renderTable(
+    ['Nhãn', 'Tên filter', 'Kiểu', 'Widget', 'Ý nghĩa', 'Mục đích', 'Placeholder'],
+    rows,
+  )
+}
+
+export function renderListPaginationBlock(listUi = {}) {
+  const p = listUi?.pagination
+  if (!p || typeof p !== 'object') return ''
+  const bits = []
+  if (p.enabled === false) return '_Phân trang: tắt trên màn này._\n'
+  if (p.pageSize != null) bits.push(`Kích thước trang mặc định: **${p.pageSize}**`)
+  if (p.pageSizeOptions?.length) {
+    bits.push(`Tùy chọn: ${p.pageSizeOptions.map((n) => `\`${n}\``).join(', ')}`)
+  }
+  if (p.showTotal != null) bits.push(`Hiển thị tổng số bản ghi: ${p.showTotal ? 'Có' : 'Không'}`)
+  if (p.infiniteScroll) bits.push('Chế độ: infinite scroll')
+  if (!bits.length) {
+    return '_Phân trang: bật (chi tiết kỹ thuật trên bundle / design actions)._ \n'
+  }
+  return bits.map((b) => `- ${b}`).join('\n') + '\n'
+}
+
+export function renderListColumnsTable(listUi = {}) {
+  const columns = listUi?.columns
+  if (!Array.isArray(columns) || !columns.length) return ''
+
+  const rows = columns.map((col) => {
+    if (!col || typeof col !== 'object') return null
+    const db = col.db
+    let dbCell = '—'
+    if (db && typeof db === 'object') {
+      if (db.schema && db.field) dbCell = `\`${db.schema}.${db.field}\``
+      else if (db.schema) dbCell = `\`${db.schema}\` (thiếu field)`
+      else if (db.field) dbCell = `\`${db.field}\` (thiếu schema)`
+    }
+    return [
+      col.title || col.label || '—',
+      col.key != null ? `\`${col.key}\`` : '—',
+      col.meaning || '—',
+      col.purpose || '—',
+      [col.widget, col.render].filter(Boolean).join(' / ') || '—',
+      col.sortable ? 'Có' : 'Không',
+      dbCell,
+    ]
+  }).filter(Boolean)
+
+  if (!rows.length) return ''
+
+  return renderTable(
+    [
+      'Nhãn cột',
+      'Key',
+      'Ý nghĩa nghiệp vụ',
+      'Mục đích UI',
+      'Widget / render',
+      'Sort',
+      'DB (schema.field)',
+    ],
+    rows,
+  )
+}
+
 export function renderValidationDictionaryTable(sections = []) {
   const fields = collectFormFields(sections)
   if (!fields.length) return ''
@@ -685,11 +774,4 @@ function formatApi(action) {
   if (action.api) return String(action.api)
   if (Array.isArray(action.apiRefs)) return action.apiRefs.join(', ')
   return ''
-}
-
-export {
-  renderValidationDictionaryTable,
-  renderStateMatrixTable,
-  renderActionFlowsDetailed,
-  renderCustomWidgetSpecs
 }

package/engines/docs/lib/render-qa-list.mjs

@@ -4,10 +4,23 @@ import { parse } from 'yaml'
 
 export const QA_LIST_FILE = 'qa/index.md'
 
-function listOpenYaml(openDir) {
+function listQaYamlFiles(qaDir) {
+  if (!existsSync(qaDir)) return []
+  const out = []
+  for (const name of readdirSync(qaDir)) {
+    if (!/\.ya?ml$/i.test(name)) continue
+    if (name === 'index.yaml') continue
+    out.push(path.join(qaDir, name))
+  }
+  return out.sort()
+}
+
+function listLegacyOpenYaml(qaDir) {
+  const openDir = path.join(qaDir, 'open')
   if (!existsSync(openDir)) return []
   return readdirSync(openDir)
-    .filter((n) => /^QA-.*\.ya?ml$/i.test(n))
+    .filter((n) => /\.ya?ml$/i.test(n))
+    .map((n) => path.join(openDir, n))
     .sort()
 }
 
@@ -16,41 +29,126 @@ function oneLine(text) {
   return String(text).trim().split(/\n/)[0].trim()
 }
 
+function escapeCell(s) {
+  return String(s ?? '')
+    .replace(/\|/g, '\\|')
+    .replace(/\n/g, ' ')
+    .trim()
+}
+
+function lastUpdate(doc) {
+  const updates = Array.isArray(doc?.updates) ? doc.updates : []
+  if (updates.length) return updates[updates.length - 1]
+  return null
+}
+
+function summaryFromDoc(doc) {
+  const last = lastUpdate(doc)
+  if (last?.text) return oneLine(last.text)
+  if (doc?.question) return oneLine(doc.question)
+  if (doc?.resolution?.summary) return oneLine(doc.resolution.summary)
+  return oneLine(doc?.kind) || '—'
+}
+
+function lastAt(doc) {
+  const last = lastUpdate(doc)
+  if (last?.at) return String(last.at)
+  if (doc?.resolution?.decidedAt) return String(doc.resolution.decidedAt)
+  return '—'
+}
+
+function isOpen(doc) {
+  if (doc?.status === 'closed') return false
+  if (doc?.status === 'open') return true
+  if (doc?.resolution) return false
+  return true
+}
+
 /**
- * Always write qa/index.md (empty body when no qa/open files).
+ * @param {string} full — absolute path to yaml
+ * @param {string} linkName — basename for markdown link
+ */
+function catalogRow(full, linkName) {
+  let id = linkName.replace(/\.ya?ml$/i, '')
+  let screen = ''
+  let kind = ''
+  let summary = ''
+  let lastAtStr = '—'
+  let state = 'open'
+  try {
+    const doc = parse(readFileSync(full, 'utf8')) ?? {}
+    if (doc.id) id = String(doc.id)
+    if (doc.screen) screen = String(doc.screen)
+    if (doc.kind) kind = String(doc.kind)
+    summary = summaryFromDoc(doc)
+    lastAtStr = lastAt(doc)
+    state = isOpen(doc) ? 'open' : 'closed'
+  } catch {
+    /* still list */
+  }
+
+  const relLink = full.includes(`${path.sep}open${path.sep}`)
+    ? `open/${linkName}`
+    : linkName
+
+  return {
+    id,
+    link: `[${id}](${relLink})`,
+    state,
+    screen: screen || '—',
+    lastAt: lastAtStr,
+    summary: summary || kind || '—',
+    sortKey: `${lastAtStr}\t${id}`,
+  }
+}
+
+/**
+ * Always write qa/index.md — catalog table only (SSOT = per-id YAML files).
  */
 export function writeQaList(root = process.cwd()) {
   const hub = path.resolve(root)
   const qaDir = path.join(hub, 'qa')
-  const openDir = path.join(qaDir, 'open')
   mkdirSync(qaDir, { recursive: true })
 
-  const lines = ['# QA', '', '_Sinh bởi `flowgrid render`. Đóng bằng `/qa-resolve`._', '']
-  const files = listOpenYaml(openDir)
-  if (!files.length) {
-    lines.push('_Không có câu hỏi mở._', '')
+  const seen = new Set()
+  const rows = []
+  for (const full of [...listQaYamlFiles(qaDir), ...listLegacyOpenYaml(qaDir)]) {
+    const name = path.basename(full)
+    if (seen.has(name)) continue
+    seen.add(name)
+    rows.push(catalogRow(full, name))
+  }
+  rows.sort((a, b) => a.sortKey.localeCompare(b.sortKey))
+
+  const lines = [
+    '# QA — catalog',
+    '',
+    '_Sinh bởi `flowgrid render` — **chỉ trạng thái + link**. Nội dung SSOT: một file YAML / mã QA._',
+    '',
+    'Workflow: [qa-team.md](../workflows/qa-team.md) · `/qa-resolve` · `/qa-review`',
+    '',
+    '| Mã | Status | Screen | Cập nhật cuối | Tóm tắt |',
+    '| --- | --- | --- | --- | --- |',
+  ]
+
+  if (!rows.length) {
+    lines.push('| _—_ | _empty_ | — | — | Không có QA file |', '')
   } else {
-    for (const name of files) {
-      const full = path.join(openDir, name)
-      let id = name.replace(/\.ya?ml$/i, '')
-      let kind = ''
-      let question = ''
-      try {
-        const doc = parse(readFileSync(full, 'utf8')) ?? {}
-        if (doc.id) id = String(doc.id)
-        if (doc.kind) kind = String(doc.kind)
-        question = oneLine(doc.question)
-      } catch {
-        /* list the file anyway */
-      }
-      const bits = [`[${id}](open/${name})`]
-      if (kind) bits.push(kind)
-      if (question) bits.push(question)
-      lines.push(`- ${bits.join(' — ')}`)
+    for (const r of rows) {
+      lines.push(
+        `| ${r.link} | ${escapeCell(r.state)} | ${escapeCell(r.screen)} | ${escapeCell(r.lastAt)} | ${escapeCell(r.summary)} |`,
+      )
     }
     lines.push('')
   }
 
+  lines.push(
+    '## Đọc timeline',
+    '',
+    'Mở file YAML — đọc `updates[]` từ trên xuống (append-only). Không copy full log vào index.',
+    '',
+  )
+
   const out = path.join(hub, ...QA_LIST_FILE.split('/'))
   writeFileSync(out, lines.join('\n'))
   return out