PetroNet SystemDocumentation
Introduction

Тойм

7 min readREADME.mdEdit on GitHub

Монгол Улсын газрын тосны бүтээгдэхүүний импорт, хадгалалт, түгээлт, борлуулалтыг нэг өгөгдлийн урсгалд нэгтгэж, бодит цагт хянах систем. Захиалагч нь Ашигт малтмал, газрын тосны газар (АМГТГ); систем нь одоогийн mpetro-г орлоно.

This page has not been translated yet — it is shown in Mongolian, the language it is written in.

PetroNet System бол нэг програм биш, экосистем: оролцогч тус бүр — жолооч, ШТС, аж ахуйн нэгж, зохицуулагч — өөрийн платформтой бөгөөд тэдгээр нь доор нь нэг өгөгдөл, нэг танилт, нэг аудитын мөрийг хуваалцана. Дөрвүүлээ өөр ажилтай хүнийг нэг дэлгэцэнд шахах нь дөрвүүлээ таагүй байх зам.

01Ямар асуудлыг шийдэж байгаа вэ

200 гаруй аж ахуйн нэгж, 110 гаруй агуулах, 1500 гаруй ШТС ажиллаж байгаа хэрнээ өгөгдөл нь хоорондоо холбогдоогүй хоёр системд, долоо хоногт нэг хоёр удаа гараар орж байна. Улсын хэмжээнд ямар түлш, хаана, хэдэн литр байгааг бодит цагт харах ганц эх сурвалж байхгүй — тиймээс нөөц таамгаар удирдагдаж, хямралын үед тэгш–сондгой дугаар шиг бүдүүлэг хэрэгсэл л үлддэг.

PetroNet дөрвөн зүйлийг нэг системд нэгтгэнэ:

ЮуХаана
1Гинжин мөрдлөг — импортын гэрээ → гааль → чанар → терминал → тээвэр → ШТС-ын сав → хошуу → хэрэглэгч/supply
2ШТС-ын POS — аль ч үйлдвэрлэгчийн түгээгүүр, ATG-д холбогдох драйверын давхарга, офлайнд ажиллана/supply#pos
3Ваучер — бодитоор ирсэн түлшнээс л эрх үүсгэж, ойр байршил ба хэрэгцээгээр хуваарилна/vouchers
4Төрийн хяналт — нөөц, үнэ, чанар, татвар, зөрүүг өөрчлөх боломжгүй аудитын мөр дээр/supply#oversight

Гол архитектурын шийдэл: ваучер = нөөцлөгдсөн литр. Ваучер нь ШТС-ын савд бодитоор орсон, ATG хэмжилтээр баталгаажсан түлшнээс л үүснэ. Ингэснээр амлалт нөөцөөсөө давахгүй, мөн хангалтаа мэдээлээгүй ШТС-д ваучер үүсэхгүй тул дуулгавартай байдал нь шалгагчаар биш дизайнаараа албадагдана.

02Экосистемийн бүрэлдэхүүн

ПлатформХэндЮу
Иргэний платформЖолооч, иргэнОйрын ШТС, түлшний төрөл, нөөцийн түвшин, өдрийн эрх ба ваучер. eID-ээр танина
ААН порталАж ахуйн нэгжАгуулах, ШТС-ын объектын бүртгэл, савны үлдэгдэл, үеийн тайлан ирүүлэх ба засварлах
Зохицуулагчийн Command CenterАМГТГ, хяналтын байгууллагаУлсын өдрийн нэгтгэл, хоногийн нөөц, хамрах хүрээний цоорхой, тулгалтын зөрүү, дохиолол
ШТС-ын POS ба ирмэгийн агентШТСХошуу, сав, ээлж, төлбөр, баримт. Локал сантай — интернэт тасарсан ч борлуулалт зогсохгүй
Дата агуулах ба аналитикШинжээч, удирдлагаӨдөр бүрийн таталт, цэвэрлэгээ, бизнесийн загвар, BI ба прогноз
Консол ба ажиглалтОператорБайгууллага, эрх, аудит — тусдаа нэвтрэлт. Хэмжүүр, дохиолол, нөөцлөлт

Эдгээрийн доор нэг Go бинарь, нэг өгөгдлийн сан, нэг танилт байна: экосистем нь олон сервер гэсэн үг биш, олон ажлын орон зай гэсэн үг. Гадагшаа нь ГЕГ, ХУР, e-Barimt, eID болон ATG/IoT төхөөрөмжүүдтэй холбогдоно.

03Энэ репо юу вэ

Gerege Nexus-ийн цөм (gerege-systems/nexus) дээрх distribution. Цөмийг энд хуулж хадгалдаггүй: core.lock нь тагийг (backend/v1.96.0) ба түүний commit-ыг тогтоож, go.mod мөн тэр хувилбарыг шаардана. deploy/prepare-core.sh тэр тагийг .build/core-д татаж, deploy/brand-frontend.sh-ээр PetroNet-ийн дэлгэцүүдийг (brand/frontend, deploy/core-frontend.patch) цөмийн frontend дээр давхарлана. Шатахууны бизнес логик modules/petro/-д.

Цөмийг шинэчлэх нь core.lock, go.mod ба deploy/Dockerfile-ийн ARG VERSION-ийг нэг PR-аар солих.

2026-09-14 хүртэл PetroNet public open-gerege-nexus цөм дээр ажиллаж байсан — тэр түүх gerege-systems/petronet-gerege-nexus-old-д.

04Модулиуд

io.gerege.nexus.petro (modules/petro/) нь бүх байгууллагад default сууна — main.go-гийн DefaultApps. ШТС ба агуулахын бүртгэл, түлшний төрөл ба нөөц, хил–бааз–цистерн–ШТС-ын гинжин мөрдлөг, 15 °C-ийн залруулга, тайлангийн үе ба хяналтын workflow, иргэний өдрийн эрх ба ваучер, зохицуулагчийн нэгтгэлийг нэг module migration history-тэй авч явна (modules/petro/migrations/). Каталог, manifest, chronicle нь catalog/-д байна.

05Юу нь ялгаатай вэ

НэвтрэлтБие даасан — өөрийн нууц үг, өөрийн OIDC issuer (SSO_ISSUER=https://petronet.mn), eID Mongolia
Домэйнpetronet.mn, www.petronet.mn (→ 308)
СерверProxmox core-dev pool-ийн core-app-02 (10.130.0.21), бусад үйлчилгээтэй хуваалцана
Портуудbackend 8220, web 3220 — гадагшаа edge core-nginx-01-ээр л

Стек нь (/opt/petronet) erdenebatt/proxmox-gerege-net-ийн stack/petronet-д: өөрийн Postgres 16, Redis, OSRM, Prometheus ба exporter-ууд. setup.sh нь хостыг бэлдэнэ (лавлах, OSRM-ийн граф, нөөцлөлтийн cron). TLS ба *.petronet.mn-ийн vhost-ууд edge дээр.

06Байрлуулалт

Хост дээр гараар юу ч солихгүй — прод руу ганц зам:

text
commit → PR → main → CI (ci.yml) ✓ → образ ghcr.io/…/{backend,frontend}:<sha>  → Deploy (deploy.yml, runner [self-hosted, core-dev])  → deploy@10.130.0.21: brand/copy.json → docker compose pull && up -d  → эрүүл мэнд: 8220, 3220, https://petronet.mn

Дэлгэрэнгүй: CLAUDE.md, docs/DEPLOYMENT.md.

CI нь backend ба web хоёр образыг нэг commit-оос хамт барьдаг тул Fuel module-ийн API, газрын зураг, операторын дэлгэц нэг revision-оор гарна.

07Нэрнүүд

НэрЮуАрд нь
petronet.mnПлатформ — frontend ба /api/v1/*Next.js + Go
admin.petronet.mnОператорын консол — /api/platform/v1/*Мөн тэр хоёр, CONTROL_PLANE_HOST
developer.petronet.mnХөгжүүлэгчийн портал — OAuth клиент, scope, түлхүүр (цөмийн /dev)Мөн тэр хоёр, DEVELOPER_HOST
monitoring.petronet.mn/ — ажиглалтын нүүр; /monitoring — цөмийн мониторингийн аппМөн тэр хоёр, MONITOR_HOST
reports.petronet.mnДата агуулах ба тайлан (цөмийн /dwh)Мөн тэр хоёр, REPORTS_HOST
backups.petronet.mnНөөцлөлтийн аппМөн тэр хоёр, BACKUPS_HOST
docs.petronet.mnPetroNet System-ийн ажиллагааны баримтЦөмийн docs апп, DOCS_HOST

Бүгд нэг frontend ба API — хост бүр зөвхөн аль аппыг нээхийг сонгоно.

Эдгээрээс гадна төхөөрөмжийн дөрвөн шугам байна — desktop. / mobile. / kiosk. / pos.petronet.mn. Тэдгээр нь өөр үйлчилгээ БИШ: яг ижил frontend ба API, зөвхөн өөр origin дээр, native клиент бүрийн webview доторх дуудлага same-origin байхын тулд — Байрлуулалт § Төхөөрөмжийн шугамууд.

08Native клиентүүд

native-apps/ дотор дөрвөн клиент, хоёр шугам: macOS ба Windows нь PetroNetDesktop (desktop.petronet.mn), iOS/iPadOS ба Android нь PetroNetMobile (mobile.petronet.mn). Аппын нэр нь платформыг биш ТӨХӨӨРӨМЖИЙН ШУГАМЫГ нэрлэдэг: хүн ширээн дээрх Mac, Windows хоёртой ижил байдлаар харьцдаг тул тэд нэг апп.

Гурван зарчим: клиентэд secret байхгүй (бүх дуудлага өөрийн web backend-ийн нийтийн /api/… route-уудаар — хөтөчтэй яг ижил зам); identity нь session биш snapshot (Keychain / Android Keystore); харагдах нэр нь PetroNet. Өнгө нь brand/frontend/src/app/petronet.css-ээс — хөтөч дээрх PetroNet ба гар дээрх PetroNet нэг бүтээгдэхүүн шиг уншигдана.

Эх нь Gerege Nexus-ийн native-apps/; энд ирэхдээ нэр, bundle ID, шугамын хаяг, палитр солигдсон ч бүтэц, гэрээ, урсгал нь ЭХ ХЭВЭЭР — цөмийн засварыг буулгах нь механик ажил хэвээр байхын тулд. Дэлгэрэнгүй: native-apps/README.md.

09Операторын консол

admin.petronet.mn — тенантын лавлах биш, платформын өөрийн консол: тусдаа нэвтрэлт, тусдаа cookie, тусдаа audit, тусдаа DB role. Хаягийн нэршил нь цөмийн admin.<домэйн>.

Эхний операторыг доорх шидтэн үүсгэнэ (нууц үг + authenticator). Хоёр дахийг консол өөрөө үүсгэнэ.

Шидтэн өнгөрсөн бол — түүний токен байгууллага үүсмэгц үхдэг — эхний оператор нь shell-ээс:

bash
ssh deploy@10.130.0.21 -t \  'cd /opt/petronet && docker compose exec backend /app/operator-bootstrap \     -email та@жишээ.mn -name "Таны нэр"'

Нууц үгийг хоёр удаа асууж (≥12), TOTP-ийн түлхүүр ба otpauth:// хаягийг нэг удаа үзүүлнэ. Authenticator-т нэмээд кодоор баталгаажуулна. Нууц үгийг flag эсвэл env-д бүү дамжуул: shell-ийн түүх, процессын жагсаалтад үлдэнэ.

Консол зөвхөн CONTROL_PLANE_ALLOWED_CIDRS (150.228.176.233/32)-аас нээгдэнэ; түүн дээр хаягийн хаалга (CONTROL_PLANE_HOST), нууц үг, ба authenticator-ийн код.

Ажиглалт

monitoring.petronet.mn/ — ажиглалтын нүүр: нийтийн гурван самбар руу заана (шатахууны урсгал, API, дэд бүтэц; grafana.gerege.net дээр). /monitoring — цөмийн мониторингийн апп, консолын session-оор, стекийн өөрийн Prometheus-аас (PROMETHEUS_URL) уншина.

Хэмжүүр

Стекийн Prometheus (stack/petronet/prometheus.yml, 15 сек, 15 хоног / 2GB) гурван зорилттой: энэ бүтээгдэхүүний API, postgres-exporter (9188), ба node-exporter. Нийтийн самбарууд мөн эдгээрийг уншина.

Баримт бичиг

docs/ — платформын баримт, PetroNet System-ийн нэр, хаягаар брэндлэгдсэн, дээр нь docs/DEPLOYMENT.md: зөвхөн энэ суулгацын тухай. docs.petronet.mn нь цөмийн docs апп: deploy/brand-frontend.sh нь docs/mkdocs/pages.mjs-д жагссан хуудсуудыг тэр апп руу байрлуулна — жагссан файл алга бол build унана. Баримт өөрчлөгдвөл ердийн deploy.

Нууцууд

Нууцууд репод байхгүй: хостын /opt/petronet/.env (сангийн нууц үг, шифрлэлтийн түлхүүрүүд, eID-ийн relying-party хос) ба backup.env (restic ба Garage-ийн түлхүүр). eID-ийн mTLS клиентийн түлхүүр хост дээр үүссэн, /opt/petronet/eid-client-д.

Нөөцлөлт

/usr/local/bin/pg-backup — өдөр бүр 03:15-д cron-оор (setup.sh тавина). pg_dumpall авч restic-ээр Garage руу шифрлэн илгээж, backup_last_success_timestamp_seconds-ийг бичнэ — хуучирвал BackupStale дохио өгнө.

10Эхний байгууллага, эхний админ

Цөмийн эхний ачааллын шидтэн (/setup). Байгууллагагүй үед л зэвсэглэдэг: токен нь ачаалах үед санах ойд үүсч, лог руу нэг удаа бичигдэж, байгууллага үүсмэгц устдаг.

bash
cd /opt/petronet && docker compose logs backend 2>&1 | grep -i "setup token"

Дараа нь https://petronet.mn/setup дээр тэр токеноор орж байгууллага, админаа үүсгэнэ. Сүүлийн алхам нь операторын консолын эхний бүртгэл — алгасаж болно. Байгууллага үүссэний дараа энэ зам 404 болно.

11Өөрийн модуль нэмэх

modules/<нэр>/ үүсгээд main.go-гийн Options.Modules callback дотор Fuel module-ийн хажууд бүртгэнэ. Түвшин 2-ын бүтэцтэй тул дараагийн module нэмэхэд platform core-ийг fork хийх шаардлагагүй.

Өөрийн хүснэгттэй бол modules/<нэр>/migrations/00001_<нэр>.sql гэж бичээд конструктораасаа бүртгэнэ:

go
//go:embed migrations/*.sqlvar migrations embed.FS func New(p nexus.Platform) *Module {    m := &Module{...}    nexus.Register(m)    nexus.Migrations(m.ID(), schema()) // fs.Sub(migrations, "migrations")    return m}

Каталог: catalog/apps.json, catalog/manifests/<slug>.json, ба хувилбарын түүхээ catalog/chronicle/<slug>.json-д. Образ нь энэ репогийн каталогийг цөмийнхтэй нийлүүлдэг — бинарь дотор байгаа аппыг каталог нэрлээгүй бол систем асахаас татгалзана.

Дэлгэрэнгүй заавар: docs/MODULES.md.

Was this page helpful?Your answer helps improve the docs.
    DEV · Хөгжүүлэлтийн орчин