D28 — Generated Table Map Design Review — Agent Prompt

Date: 2026-05-08 | Rev: 2 (GPT 9 patches applied) Status: PROMPT chờ GPT/User approve trước dispatch Agent target: claude-go (VPS SSH access required) Scope: VPS reverify + design Option C generated map. KHÔNG implement.

Mục tiêu

VPS-focused reverify 3 hardcoded map files (LOCAL_FACT → LIVE_FACT)
Kiểm tra table_registry schema + live fields
Thiết kế Option C generated map mechanism với recommendation
Row-by-row classification toàn bộ 21 table_registry rows
Output: design doc + review report

Hard boundaries

NO_NUXT_CODE_MODIFICATION=true
NO_GENERATED_FILE_CREATION=true
NO_DIRECTUS_MUTATION=true
NO_PG_MUTATION=true
NO_PUBLISH=true
NO_DEPLOY=true
NO_IMPLEMENTATION=true
READ_AND_DESIGN_ONLY=true
DO_NOT_PRINT_SECRETS=true

Quan trọng: Design review ≠ Inventory

Đây là design review, KHÔNG phải inventory. Agent PHẢI:

1. Trình bày options
2. So sánh tradeoff
3. Đề xuất preferred design (recommendation)
4. KHÔNG implement

GPT/User sẽ duyệt hoặc bác recommendation sau.

Phần 1 — VPS-focused reverify (READ-ONLY)

1A. Registry route file

ssh contabo "cat /opt/incomex/web/pages/knowledge/registries/\[entityType\]/index.vue"

Ghi lại: exact tableIdMap content, line numbers, lookup logic, import structure.

1B. Detail sections config

ssh contabo "cat /opt/incomex/web/config/detail-sections.ts"
ssh contabo "grep -rn 'detail-sections' /opt/incomex/web/ --include='*.vue' --include='*.ts' | head -20"

Ghi lại: collectionMap + reverseCollectionMap content, export pattern, consumers.

1C. Relations API mirror

ssh contabo "cat /opt/incomex/web/server/api/discovery/relations.get.ts"

Ghi lại: mirrored map content, tại sao mirror tồn tại, có thể import shared source không.

1D. Build/deploy scripts

ssh contabo "cat /opt/incomex/web/nuxt.config.ts | head -80"
ssh contabo "cat /opt/incomex/web/package.json | jq '.scripts'"
ssh contabo "ls /opt/incomex/web/scripts/ 2>/dev/null"
ssh contabo "cat /opt/incomex/.github/workflows/deploy-vps.yml 2>/dev/null | head -80"

Ghi lại: build command, pre-build hooks, deploy flow, có chỗ chạy script trước build không.

1E. Generated file conventions

ssh contabo "ls /opt/incomex/web/generated/ 2>/dev/null || echo 'NO_GENERATED_DIR'"
ssh contabo "find /opt/incomex/web/ -name '*.generated.*' -o -name 'auto-*' | grep -v node_modules | head -10"

1F. Nuxt import alias

ssh contabo "grep -n 'alias\|resolve\|~/' /opt/incomex/web/nuxt.config.ts | head -15"

Phần 2 — Table registry schema + live fields (NEW in rev2)

2A. Live data query

curl -s "https://directus.incomexsaigoncorp.vn/items/table_registry?fields=id,table_id,name,collection,status,page_url,module,fields&sort=id" \
  -H "Authorization: Bearer $DIRECTUS_ADMIN_TOKEN" | jq '.data'

2B. Schema inspection

curl -s "https://directus.incomexsaigoncorp.vn/fields/table_registry" \
  -H "Authorization: Bearer $DIRECTUS_ADMIN_TOKEN" | jq '.data[] | {field: .field, type: .type}'

Ghi lại: tất cả columns hiện có. Đặc biệt: có field entity_type chưa? Có field nào chứa entity key chưa?

Phần 3 — Row-by-row classification (NEW in rev2)

Classify mỗi row trong 21 table_registry rows:

Row classes

REGISTRY_ENTITY_ROUTE   — /knowledge/registries/{entityType} pattern
NON_REGISTRY_PAGE       — /knowledge/modules, /knowledge/current-tasks, etc.
WORKFLOW_TAB            — /knowledge/workflows/[id]?tab=...
ADMIN_PAGE              — /admin/...
INDEX_PAGE              — /knowledge/registries (no entityType)
UNKNOWN                 — cannot classify

Output table (bắt buộc)

id | table_id | collection | status | page_url | derived_entity_type | row_class | in_tableIdMap | in_collectionMap | notes

derived_entity_type = entityType hiện tại trong tableIdMap, hoặc derive từ page_url nếu không có trong map.

Phần 4 — Design Option C generated map

4.1 entityType derivation — DATA PROBLEM, không chỉ code problem

entityType hiện CHỈ tồn tại trong hardcoded map, không có trong table_registry schema.

Agent PHẢI trình bày options + recommend:

Option E1 — Derive từ hardcoded map hiện tại (seed)

Lấy 18 entries từ tableIdMap hiện tại làm seed
Cho rows thiếu (event_outbox): derive từ page_url hoặc convention
Generated script hardcode mapping rules
Ưu/nhược?

Option E2 — Derive từ page_url

Parse last segment of page_url
/knowledge/registries/system_issue → system_issue
Fail cho non-registry routes (8/21)
Ưu/nhược?

Option E3 — Thêm explicit entity_type column vào table_registry

ALTER TABLE hoặc Directus field add
Backfill từ current hardcoded map
Generated script reads column directly
Cleanest long-term nhưng cần schema migration
Ưu/nhược?

Option E4 — Dùng tableIdMap làm seed, store mapping logic trong generation script

Script chứa convention rules: tbl_xxx → xxx hoặc table-specific overrides
Không cần schema change
Convention logic centralized trong 1 script
Ưu/nhược?

Option E5 — Route key = normalized page_url token

Không cần entityType concept
Route resolution trực tiếp bằng page_url lookup
Fundamental redesign
Ưu/nhược?

Agent PHẢI recommend Phase 1 migration-safe strategy + ghi rõ nếu cần schema cleanup pack riêng.

4.2 Generation script design

Script location (đề xuất + lý do)
Language: TypeScript vs bash+jq (đề xuất + lý do)
Input: Directus API query
Output: path, format, 1 file hay nhiều file

4.3 Output format

3 maps cần generate:

Map	Thay thế	Consumer
tableIdMap	`[entityType]/index.vue:39`	Client/SSR page
collectionMap	`detail-sections.ts:227`	Client/SSR config
reverseCollectionMap	`detail-sections.ts:252`	Client/SSR config

QUAN TRỌNG — Client/server import safety (rev2 addition):

Generated module PHẢI là pure static data:

Không chứa env vars
Không chứa secrets
Không chứa browser-only hoặc server-only code
Không chứa runtime API calls
Chỉ export const với plain objects

Nếu relations.get.ts (server-side) cần import cùng module với Nuxt page (client/SSR) → verify import hoạt động cả 2 contexts. Nếu không → thiết kế tách output.

Agent PHẢI verify: pure static export importable từ cả pages/*.vue (client/SSR) VÀ server/api/*.ts (server-only)?

4.4 Build-time credentials (rev2 addition)

Generation script cần đọc table_registry từ Directus API.

Agent PHẢI thiết kế + recommend:

Option C1 — Public Access đọc table_registry

Cần thêm Directus read permission cho Public Access trên table_registry
Ưu: không cần secret khi build
Nhược: expose table_registry metadata publicly
Verify: Public Access hiện có permission trên table_registry không?

Option C2 — Build token (env secret)

Dùng admin hoặc agent token lưu trong GCP Secret Manager / VPS .env
Script đọc token từ env, KHÔNG bundle vào client
Generated output = pure static data (token không còn trong output)
Ưu: không expose table_registry publicly
Nhược: cần manage build secret

Option C3 — VPS-only generation (SSH + local Directus)

Script chạy trên VPS, query Directus local (localhost hoặc Docker network)
Không cần external secret
Generated file commit hoặc deploy artifact
Ưu: simplest security
Nhược: generation chỉ trên VPS

Agent PHẢI recommend + KHÔNG in secret values ra report.

4.5 Build/deploy timing

Options:

A. prebuild script ("prebuild": "tsx scripts/generate-table-maps.ts")
B. GitHub Actions step trước nuxt build
C. Commit generated file (manual run + git add)
D. Deploy hook trên VPS
E. VPS script chạy trước build trên VPS

Agent PHẢI recommend + lý do.

4.6 Status/draft handling (rev2 addition)

Default recommendation cần cân nhắc:

status=active hoặc status=published → include trong production map
status=draft → exclude từ production map

Nhưng tbl_event_outbox đang draft và cần smoke. Agent PHẢI đề xuất safe sequence:

Options:

Include-draft flag: npm run generate:table-maps -- --include-draft
Preview/development map variant
Publish tbl_event_outbox trước generate (nhưng cần route smoke trước publish — chicken-egg)
Explicit force_include list trong script config

Agent PHẢI recommend cách giải quyết chicken-egg: cần route smoke → cần map → cần generate → draft included hay published first?

4.7 Drift verification (rev2 addition)

Agent PHẢI thiết kế cụ thể:

generate mode:  writes artifact file(s)
verify mode:    --check flag, exits nonzero if generated ≠ current file
header:         includes source row count + content hash
CI integration: deploy workflow runs verify --check, FAIL = block deploy
manual edit:    detected by hash mismatch in header vs actual content

Recommend: nên check gì ở CI? Check gì ở deploy? Check gì ở post-deploy?

4.8 Rollback

Nếu generated map gây lỗi:

Git revert generated file commit
Hoặc: script --restore từ backup
Cần backup strategy?

Report format (rev2 — expanded)

# D28 — Generated Table Map Design Review Report

## VPS reverify
tableIdMap_vps_entries=?
tableIdMap_vps_matches_local=YES|NO|PARTIAL (compare with Agent inventory LOCAL_FACT)
collectionMap_vps_content=? (summary, not full dump)
relations_mirror_vps_content=? (summary)
build_command=?
pre_build_hooks=?
deploy_flow=?
generated_dir_exists=YES|NO
import_alias_pattern=?

## Table registry schema
table_registry_columns=[list]
entity_type_column_exists=YES|NO
relevant_columns_for_design=[list]

## Row classification (full table — 21 rows)
(table per Phần 3)
registry_entity_route_count=?
non_registry_page_count=?
workflow_tab_count=?
admin_page_count=?
index_page_count=?

## Design recommendations
entity_type_strategy_recommended=E1|E2|E3|E4|E5
entity_type_strategy_rationale=?
script_location_recommended=?
script_language_recommended=TS|BASH
output_path_recommended=?
output_format_recommended=SINGLE_FILE|MULTI_FILE
client_server_import_safe=YES|NO|NEEDS_SPLIT
credential_strategy_recommended=PUBLIC_READ|BUILD_TOKEN|VPS_ENV_SECRET
build_timing_recommended=PREBUILD|GH_ACTION|COMMIT_GENERATED|DEPLOY_HOOK|VPS_SCRIPT
draft_handling_strategy_recommended=?
draft_chicken_egg_solution=?
drift_verification_design=?
rollback_design=?

## Blockers
phase_status=PASS|BLOCKED|NEEDS_MORE_DATA
vps_reverify_status=PASS|FAIL|PARTIAL
table_registry_schema_status=PASS|FAIL|PARTIAL
route_row_classification_complete=PASS|FAIL
generated_module_import_safe=PASS|FAIL|NEEDS_REVIEW
blockers=[list if any]

## Next
recommended_next_pack=D28_GENERATED_MAP_IMPLEMENTATION_PROMPT|D28_TABLE_REGISTRY_SCHEMA_EXTENSION|BLOCKED|REVISION_REQUIRED

Expected outputs

Doc	Path
Design	`knowledge/dev/laws/dieu28-trien-khai/design/d28-generated-table-map-design.md`
Report	`knowledge/dev/laws/dieu28-trien-khai/reports/d28-generated-table-map-design-review-report.md`

Hard boundary final check

no_nuxt_edit=true
no_file_creation_on_vps=true
no_directus_mutation=true
no_pg_mutation=true
no_publish=true
no_deploy=true
no_implementation=true
no_secret_in_report=true
design_and_read_only=true

D28 Generated Table Map Design Review | Agent Prompt rev2 | READ + DESIGN + RECOMMEND | 2026-05-08