Distribution¶

Цөм (энэ репо) бизнес апп агуулдаггүй. Бүтээгдэхүүн бол distribution: өөрийн репо, өөрийн main.go, өөрийн модулиуд, брэнд, домэйн — доороо энэ цөмтэй. Энэ баримт тэр хоёрын хоорондох гэрээг тайлбарлана. 2026-09-13-нд энэ репогийн .github/workflows/, backend/pkg/nexus, backend/testdata/canary, frontend/lib/brand*.ts ба snapshot distribution-уудын (одоо platform-gerege-nexus, petronet-gerege-nexus) core-sync.yml, deploy/sync-core.sh, core/SNAPSHOT, deploy/Dockerfile-аас уншиж бичсэн; жагсаалтыг 2026-10-02-нд шинэчилсэн.

Баримтын төв · Модуль бичих · Архитектур

Distribution гэж юу вэ¶

Нэг бинарь = цөм + distribution-ий модулиуд. Distribution-ий main.go модулиудаа бүтээж (nexus.Register), host.Run-ийг дуудна; route, эрх, цэс, schema, тайлан, AI tool бүгд pkg/nexus-ийн гэрээгээр орно (Модуль бичих). Бүрхүүл (frontend/), миграц (backend/db/migrations), каталог (catalog/) нь цөмийнх; distribution зөвхөн өөрийн манифест, chronicle, брэндээ нэмнэ.

Цөмийг авах хоёр хэлбэр бий, мөн тэд өөр өөр дүрэмтэй:

Хэлбэр	Цөм хаанаас	Хувилбарыг юу тогтоох	Одоо хэн
Go dependency	`go.mod`-ийн `require …/backend vX.Y.Z`	`backend/vX.Y.Z` tag	`e-property-mn`, `e-notary-mn`, `power-grid-mn`, `work-gerege-nexus`, `app-gerege-nexus`, `appstore-gerege-nexus`, `kiosk-gerege-nexus`, `digital-nomads`
Snapshot	репо доторх `core/` (`go.mod`-ийн `replace => ./core/backend`)	`core/SNAPSHOT`-ийн commit	`platform-gerege-nexus`, `petronet-gerege-nexus`, `gerege-contract-gerege-nexus`

Downstream биш болсон: eid-mongolia-mn — 2026-09-27-нд fork болж цөмийг дагахаа больсон (core-sync-гүй); eid-gerege-nexus — GitHub дээр байхгүй. Release-ийн мэдэгдэл, CI, залгаасны дүрмүүд тэднийг тооцохгүй.

Snapshot хэлбэр нь distribution цөмийн файлд залгаас (жишээ нь өөрийн консол, миграц, routes.txt-ийн мөрүүд) хийх шаардлагатай үед л зөвтгөгдөнө; бусад тохиолдолд Go dependency хэлбэр.

Snapshot-ийн бүтэц¶

<distribution>/
  main.go            host.Run — модулиуд зөвхөн энд
  modules/           өөрийн апп-ууд
  catalog/           өөрийн manifest, chronicle — образ барихад цөмийнхтэй нийлнэ
  brand/             copy.json, theme.css — frontend контейнерт /brand болж холбогдоно
  core/
    SNAPSHOT         ref: <nexus-gerege-private-ийн бүтэн commit sha>
    backend/ frontend/ catalog/ brand/    цөмийн хуулбар (+ залгаас)
  deploy/sync-core.sh
  .github/workflows/core-sync.yml

core/SNAPSHOT бол энэ distribution цөмийн аль commit дээр байгааг хэлэх ганц үнэн.

Sync хэрхэн өдөөгдөж байсан (2026-09-30-нд хасагдсан)¶

Цөм notify-downstream.yml-ээр snapshot distribution-уудад «core-updated» дохио илгээдэг байв. Ганц хэрэглэгч нь eid-mongolia-mn байсан бөгөөд тэр 2026-09-27-нд fork болж sync-ийн машинаа бүхэлд нь устгасан (GitLab trigger 400 буцааж эхэлсэн), тиймээс workflow хасагдсан. Tag-аар түгжих distribution (e-property-mn г.м.) дохио хэрэггүй: core.lock + go.mod-ийг шинэ tag руу шилжүүлнэ.

Хувилбарыг түгжих — одоогийн байдал ба дүрэм¶

Одоо хоёр механизм хоёр өөр зүйлийг гэрээлж байна, үүнийг шууд хэлье:

release.yml ба distribution-ci.yml нь tag-аар ажилладаг. distribution-ci.yml-ийн «The core is taken by tag» алхам go.mod цөмийг replace хийсэн бол, эсвэл цөм pseudo-version (vX.Y.Z-…) дээр байвал CI-г унагана. Бусад replace-ийг зөвшөөрнө: цөмийн eID PDF гарын үсэг (eid-mongolia-sdk-go/pades) distribution бүрийн go.mod-д replace github.com/digitorus/pdf => github.com/craftzbay/pdf v0.1.3-eid.2-ийг шаардана (хамаарлын replace дамждаггүй; байхгүй бол rdr.Resolve undefined). Tag нь backend/vX.Y.Z хэлбэртэй (Go submodule tag); одоогийн хамгийн сүүлийнх нь backend/v1.20.0.

Дүрэм: distribution нь tag-ийг дагана. Go dependency хэлбэр үүнийг distribution-ci.yml-ээр аль хэдийн хангана. Snapshot хэлбэр main-ий SHA-г дагах нь өнөөдрийн бодит зан — өөрчлөх хүртэл: (1) prod руу гарах sync-ийг tag-ийн commit руу workflow_dispatch ref=backend/vX.Y.Z-ээр хийх, (2) PLATFORM_VERSION-ийг тэр tag-тай тэнцүү барих, (3) main-ий автомат sync-ийг staging эсвэл review-д ашиглах. Tag тавихад CHANGELOG-д ## [X.Y.Z] гарчиг байх ёстой — release.yml тэмдэглэлээ түүнээс авдаг. Түүнээс өмнө node scripts/changelog.mjs collect-ээр changelog.d/-ийн фрагментуудыг feature PR-ийн сүүлийн commit болгон нэгтгэнэ — тусдаа release PR нээхгүй (журам, Release ба deploy).

PlatformVersion ба module tag хоёр өөр тоо (release.yml хоёуланг нь хэвлэдэг, тулгадаггүй): tag нь SDK-ийн амлалт, PlatformVersion нь манифестын "platform": ">=1.1.0"-ийг шалгах утга. version.go-ийн "1.1.0" нь placeholder бөгөөд release build -ldflags -X …/config.PlatformVersion=…-ээр дардаг (цөмийн deploy/Dockerfile, distribution-ий deploy/Dockerfile). -X буруу замыг нэрлэвэл линкер чимээгүй орхиж, образ манифестуудаа татгалзана.

Distribution-ий release ба deploy¶

Цөмийн Release ба deploy дүрэм distribution бүрт адилхан хүчинтэй (2026-10-22-нд 40–50 минутын deploy-оос сургамж авсан):

Release нь feature PR дотор. Тусдаа release PR нээхгүй: хувилбар, changelog, цөмийн шинэчлэл нь тухайн өөрчлөлтийн PR-ийн сүүлийн commit. Merge хийхийн өмнө main дээр rebase хийнэ. Жижиг засваруудыг нэг release-д цуглуулна.
Цөм шинэчлэх нь нэг commit: go.mod/go.sum-ийн …/backend vX.Y.Z, core.lock (ref=backend/vX.Y.Z, sha= нь tag-ийн commit), deploy/Dockerfile-ийн ARG VERSION, README-ийн хувилбар — бүгд хамт, тэр хувилбарыг шаарддаг кодын өөрчлөлттэйгөө нэг PR-д. eID PDF-ийн replace github.com/digitorus/pdf => github.com/craftzbay/pdf v0.1.3-eid.2-ийг мартахгүй. Олон хувилбараар үсрэхээс (жишээ нь 1.35 → 1.45) өмнө go build ./... && go test ./...-ийг шинэ цөм дээр ажиллуулна; цөмийн migration бүр prod өгөгдлийн сан дээр ажиллана гэдгийг санана.
Өөр session ажиллаж буй ажлын хуулбарт хүрэхгүй. Commit хийгээгүй өөрчлөлттэй checkout-д файл зөөх, rebase хийхгүй — тусдаа worktree дээр ажиллана, эсвэл тэр session-д даалгана.
Deploy-ийн дараа шалга: prod контейнерийн image merge commit-ийн SHA эсэх, гол хуудсууд хариулж байгаа эсэх. Deploy унавал log-ийг уншиж шалтгааныг засна; гараар давтан ажиллуулахгүй.
Хэрэглэгчид бодит хугацаа хэл: PR-ийн CI ~10–12 мин, merge-ээс prod хэдэн минут.

Цөмийн өөрчлөлтүүдээс distribution-д хамаатай нь: хүний хуудсууд app/my/... (/me/... нь цөмийн next.config-оор /my/... руу 307); нэршил — зурган гарын үсэг «Цахим гарын үсэг», eID-ийнх «Тоон гарын үсэг».

Өмнөх цөм рүү буцаах¶

Go dependency: go get github.com/gerege-systems/nexus-gerege-private/backend@vX.Y.Z (өмнөх tag) → go mod tidy → push. Энгийн.
Snapshot: sync-core.sh буцах чиглэлд sync хийхгүй. Distribution репод sync commit-ыг git revert хийнэ — тэр нь core/ ба SNAPSHOT-ийг хамт буцаана. Анхаар: core-sync.yml-ийн 6 цагийн cron дараагийн тикэд main-ийг дахин авчирна. Буцаасан бол тэр workflow-г (gh workflow disable core-sync.yml) засвар цөмд орох хүртэл унтраа.
Аль ч хэлбэрт schema буцахгүй (доор).

Миграцын дүрэм¶

Цөмийн миграц backend/db/migrations, нэг public.goose_db_version хүснэгт. Файл бүр -- +goose Down-тэй боловч deploy нь migration-ийг буцаах гэж оролддоггүй (Ажиллагаа); prod-д миграц зөвхөн урагшаа. Тиймээс кодыг буцаахад schema шинэ хэвээр үлдэнэ.
Үүнээс гарах дүрэм: цөмийн schema өөрчлөлт expand/contract, нэг release зайтай. Эхний release нэмнэ (шинэ багана/хүснэгт, хуучин нь хэвээр, код хоёуланг даана); хуучныг устгах нь дараагийн release-д. Ингэснээр нэг хувилбар буцаасан distribution ажилласаар байна.
Дугаар давхцахыг numbering_test.go барина. Distribution-ий залгаасанд зориулж зориуд алгассан дугаар retiredMigrationNumbers-д шалтгаантай бичигдэнэ (00113 — салсан eid-mongolia-mn-ий CA консолын залгаас байсан; дугаар дахин ашиглагдахгүй).
Distribution-ий модулийн миграц цөмийн хавтсанд орохгүй: модуль nexus.Migrations(id, fs)-ээр өгч, суулгах үед public.goose_db_version_<slug> гэсэн өөрийн хүснэгтэд ажиллана (internal/workspace/appinstall/migrate.go). Модулийн 00001 цөмийн 00001-тэй мөргөлдөхгүй.

SDK гэрээ ба юу эвдэх өөрчлөлт вэ¶

Экспортын гадаргуу backend/pkg/nexus/testdata/api.txt golden файлд. Өөрчлөх бол go test ./pkg/nexus -update, diff нь PR-д орно (Модуль бичих).
Эвдэх өөрчлөлт: экспортолсон зүйлийг хасах/нэрлэх, signature солих, экспортолсон interface-д метод нэмэх (distribution-ий төрөл түүнийг хэрэгжүүлдэг). Нэмэх (шинэ функц, шинэ struct талбар) эвддэггүй.
Гадаад хамаарал гэрээнд ил: api.txt chi.Router (Module.RegisterRoutes, ConsoleApp.RegisterConsoleRoutes) ба pgx.Tx, pgx.Rows, pgx.Row, pgx.TxOptions-ийг (nexus.DB) нэрлэдэг. Тиймээс github.com/go-chi/chi/v5 эсвэл github.com/jackc/pgx/v5-ийн major солих нь SDK-ийн эвдэх өөрчлөлт.
Signature өөрчлөгдөөгүй ч зан өөрчлөгдөж болно — тэрийг backend/testdata/canary барина: Register, AccessPolicy, Provide/Capability, Migrations, RegisterReport, AssistantTool-ийг бодитоор ашигладаг жижиг distribution; downstream.yml PR бүрд build+test хийнэ. Санаатай өөрчлөлт бол canary-г тэр PR-д засаж, caller юу хийхийг тайлбарт бичнэ.
Модулийн DB тест: backend/pkg/nexustest — dbguard-тай ижил холболт (AsTenant/AsPerson/AsPlatform), тестийн хэрэглэгч/байгууллага, модулийн router-ийг gate-тэй нь mount хийх (Модуль бичих).
PlatformVersion-ийг өсгөх нь манифестын platform хязгаарт нөлөөлнө; tag-тай тэнцүүлэх албагүй.
1.15.0-д tenant* → workspace* нэршлийг v1 дотор гаргасан (Go v2 модулийн зам бүх import-ыг солих байсан тул) — major-ын оронд CHANGELOG-ийн ⚠️ тэмдэглэл.

Брэнд ба харагдац¶

Бүгд орчны хувьсагч ба /brand хавтас; цөмийн код засахгүй.

Хувьсагч	Юу
`BRAND_NAME`, `BRAND_SHORT_NAME`, `BRAND_DESCRIPTION`	Нэр (толь бичгийн `{brand}`), товч нэр, тайлбар
`BRAND_LOGO_URL`, `BRAND_ICON_URL`, `BRAND_MASKABLE_ICON_URL`	Лого, PWA icon — `/зам` эсвэл `http(s)://` л
`BRAND_THEME_COLOR`	PWA manifest ба `<meta name="theme-color">`-ийн hex өнгө; нүүр хуудас ба апп дэлгэцийн accent (`components/BrandAccent`). Бүрхүүлийн бусад токенд хүрэхгүй
`BRAND_DOCS_URL`	Нүүр хуудасны цэс ба footer-ийн «Баримт бичиг» холбоос. Хоосон бол холбоос огт гарахгүй (платформын гарын авлага хаалттай репо)
`BRAND_COPY_FILE`	`/brand/copy.json` — i18n түлхүүрийг хэл тус бүрээр дарна (`brand/README.md`)
`LANDING_SECTIONS`	Нүүр хуудасны хэсгүүд, дарааллаар (`frontend/lib/landing.ts`)
`LANDING_MEDIA_FILE`	`/brand/landing/media.json` — нүүр хуудасны зургууд (hero утас, showcase дэлгэц, картын зураг, хаалтын туузны дэвсгэр). `brand/` доторх зураг, фонт `/brand/…` хаягаар үйлчлэгдэнэ (`brand/README.md`)
`BRAND_THEME_STYLE`	`data-style`: `nova vega maia lyra mira luma sera rhea nexus` (анхдагч `nexus`)
`BRAND_THEME_DEPTH`	`data-depth`: `flat soft raised deep` (анхдагч `soft`)
`BRAND_THEME_RADIUS`	`full` бол `data-radius="full"` (pill), бусад үед тавигдахгүй
`BRAND_THEME_ACCENT`	`data-accent`: `blue violet emerald rose cobalt teal neutral`; хоосон бол CSS-ийн accent
`BRAND_THEME_CSS_FILE` / `BRAND_THEME_CSS`	«Get code»-ийн `:root`/`.dark` блок — файл (`/brand/theme.css`) эсвэл шууд мөр

Алхам: ui.gecore.mn/#theme дээр харагдацаа тохируулж Get code дар → нэрлэсэн <html> атрибутуудыг BRAND_THEME_*-д, CSS блокийг brand/theme.css-д хийж BRAND_THEME_CSS_FILE=/brand/theme.css. Блок <body>-ийн төгсгөлд layer-гүй <style> болж орох тул сангийн болон цөмийн токеныг дарна (frontend/lib/brandTheme.ts). Зөвшөөрөгдөөгүй утга чимээгүй хаягдана. Хэрэглэгч Тохиргоо → Харагдац дээр accent сонгосон үед л тэр хөтөч дээр deployment-ийн accent дарагдана. Бүгд асах үед нэг удаа уншигдана — өөрчлөлт контейнер дахин асахад.

Native клиентийн орчуулга¶

Native бүрхүүл {brand}-ийг ажиллах үед задалж чаддаггүй — нэр нь экспортын мөчид шатна. Брэнд бүр өөрийн нэрээр экспортлох ёстой:

BRAND_NAME="<брэнд>" native-apps/sync-i18n.sh [<цөмийн checkout>]

Скрипт цөмийн frontend/scripts/export-native-auth-i18n.mjs-ийг түр хавтаст ажиллуулж generated-i18n/*.json, Android auth.xml, iOS Login.xcstrings-ийг шинэчилнэ, «Nexus Template» үлдвэл унана. Snapshot sync native-apps/-ийг авчрахгүй тул native клиентийн мөр цөмийн auth толь өөрчлөгдөхөд тусдаа шинэчлэгдэнэ (Орчуулга).

Шинэ distribution үүсгэх¶

gerege-systems/<нэр> private репо; main.go нь host.Run, модулиуд modules/-д.
Хэлбэрээ сонго. Анхдагч нь Go dependency: go get …/backend@<сүүлийн tag>, цөмийг replace хийхгүй (дээрх digitorus/pdf-ийн replace л заавал). Цөмд залгаас зайлшгүй бол л snapshot (core/, core/SNAPSHOT, deploy/sync-core.sh, core-sync.yml-ийг petronet-gerege-nexus-ээс хуулж).
CI: distribution-ci.yml@main ба distribution-security.yml@main-ийг дууд (сүүлийнх нь долоо хоногийн cron-той), PRIVATE_NEXUS_TOKEN secret (цөм дээр contents:read).
Snapshot бол: upstream-аас sync-ээ өөрөө хуваариар тат (цөм дохио илгээхгүй).
Образ: PlatformVersion-ийг -ldflags -X-ээр дар; цөмийн catalog/-ийг өөрийн catalog/apps.json, manifests, chronicle-тай нийлүүл.
Модуль бүр nexus.Register; өөрийн schema бол nexus.Migrations; манифест catalog/manifests/<slug>.json, chronicle catalog/chronicle/<slug>.json.
Брэнд: BRAND_*, brand/copy.json, «Get code» → brand/theme.css.
Native клиент гаргах бол BRAND_NAME-тэй native-apps/sync-i18n.sh.
Миграцын дугаар цөмийнхтэй давхцах залгаас хийвэл цөмийн numbering_test.go-ийн retiredMigrationNumbers-д бүртгүүл.
Модуль өөрийн дэлгэцтэй бол (nexus.PageServer, MODULES) ingress /r/-ийг /api/-тай адил API руу, add_header X-Frame-Options-гүй дамжуулна; консолын host дээр /r/cp/.
Цөмийн зан засах шаардлагатай бол эхлээд цөмд засаж push хийнэ — core/-д шууд засвар дараагийн sync-д зөрчил болно.