Saltar a contenido

Дотоод хөгжүүлэлтийн заавар

Gerege Nexus (gerege-systems/nexus-gerege-private, Go module github.com/gerege-systems/nexus-gerege-private/backend) нь хувийн төсөл. Энэ заавар нь эрх бүхий хөгжүүлэлтийн багт зориулагдсан.

Монгол  ·  English

Хариуцагчид

Төслийг дараах баг хөгжүүлж, хариуцан ажиллуулна:

Хөгжүүлэлтийн ажлын дараалал

1. Алдаа мэдээлэх

Алдаа мэдээлэхийн өмнө нээлттэй issue-үүдийг шалгаж, давхардал үүсгэхээс сэргийлнэ үү. Мэдээлэлдээ дараахыг заавал оруулна:

  • Алдааг давтан гаргах тодорхой алхмууд.
  • Ажиллаж буй орчин (Go хувилбар, Node.js хувилбар, үйлдлийн систем, PostgreSQL хувилбар).
  • Хүлээгдэж буй ба бодит үр дүн, боломжтой бол лог.

2. Шинэ боломж санал болгох

Санал болгож буй боломжийн хэрэглээний тохиолдол, шийдэх гэж буй асуудал, төсөөлж буй шийдлээ тодорхой бичнэ үү.

3. Pull request илгээх

  1. Салбар үүсгэх — git checkout -b feature/amazing-feature.
  2. Код бичих хэв маягийг мөрдөх:
  3. Backend: Go 1.26+, gofmt форматлалт, slog бүтэцтэй логлолт, алдааг тодорхой шалгах.
  4. Frontend: Next.js 16 App Router, TypeScript strict горим, Tailwind CSS.
  5. Тест бичих — backend-д нэмэгдсэн логик бүрт *_test.go тест дагалдана.
  6. Шалгалтуудыг ажиллуулах:
# Backend: формат, статик шинжилгээ, тест
cd backend
gofmt -l .
go vet ./...
go test -race ./...
golangci-lint run

# Frontend: төрлийн шалгалт ба build
cd ../frontend
npx tsc --noEmit
npm run build
  1. Commit бичлэг — Conventional Commits хэлбэрийг баримтална:
  2. feat: add invoice management module
  3. fix: resolve stock level calculation rounding
  4. docs: update module authoring guide
  5. PR нээх — main салбар руу чиглүүлнэ. CI дээрх lint, тест, frontend build, аюулгүй байдлын шалгалт бүгд ногоон байх шаардлагатай.

Шинэ бизнес модуль нэмэх

Бизнес модуль энэ репод биш, distribution репод амьдарна — backend/internal/apps нь угсрах цэг бөгөөд зориуд хоосон.

  1. Distribution репод (modules/<module_name>/) пакет үүсгэж backend/pkg/nexus-ийн nexus.Module интерфейсийг хэрэгжүүлнэ.
  2. Конструктороос нь nexus.Register(m) дуудна; өөрийн schema бол nexus.Migrations(id, fs) (public.goose_db_version_<slug> хүснэгтэд ажиллана). Distribution-ий main.go модулиа бүтээгээд host.Run-ийг дуудна.
  3. catalog/manifests/<slug>.json манифест (pkg/catalog Manifest-тэй яг таарах — алдаатай манифесттэй сервер асахгүй), catalog/chronicle/<slug>.json, мөн distribution-ий catalog/apps.json-д бүртгэнэ. Бинарь тээж буй модулиа каталог нэрлээгүй бол суулгац татгалзана.
  4. Дэлгэц нь цөмийн бүрхүүлд frontend/app/module/<slug>/ дор; аппын толийг тэр route-ийн layout.tsx-ээс бүртгэнэ (Орчуулга).

Дэлгэрэнгүйг Модуль бичих, цөмтэй гэрээг Distribution-оос үзнэ үү.

backend/pkg/nexus-д хүрэх PR

Энэ пакет бол экосистемийн гэрээ: distribution repo бүр түүн рүү компилл хийж, tag-аар түгжинэ. Тиймээс:

  • CODEOWNERS-ийн review заавал (.github/CODEOWNERS).
  • Экспортолсон гадаргуу өөрчлөгдвөл go test ./pkg/nexus -update ажиллуулж, testdata/api.txt-ийн diff-ийг PR-даа оруулна. Тэр diff нь гэрээ юу авч, юу алдсаныг review-д яг хэлнэ.
  • Эвдэх өөрчлөлт бол deprecation → нэг major цикл. Дүрмийг Модуль бичих-ийн «Хувилбарын амлалт» хэсгээс үзнэ үү.

Харагдацыг тохируулах (theme)

UI бүхэлдээ @gerege-systems/ui дээр суурилсан бөгөөд токены ганц эх сурвалж нь сангийн theme.css. Хуучин --gerege-* нэрс нь тэдгээрийн alias (frontend/app/globals.css). Тиймээс суулгац бүр харагдацаа ui.gecore.mn/#theme дээр тохируулаад Get code-оор авсан зүйлээ л өгнө:

  1. Тэнд нэрлэсэн <html> атрибутууд → BRAND_THEME_STYLE, BRAND_THEME_DEPTH, BRAND_THEME_RADIUS, BRAND_THEME_ACCENT орчны хувьсагч.
  2. Хэвлэсэн :root / .dark блок → ./brand/theme.css файлд, BRAND_THEME_CSS_FILE=/brand/theme.css (эсвэл нэг-хоёр мөр бол BRAND_THEME_CSS дотор шууд).

Цөмийн код засах шаардлагагүй; блок нь <body>-ийн төгсгөлд орж сангийн болон цөмийн токенуудыг дарна. Цөмийн өөрийн харагдац ч яг ийм блокоор бичигдсэн (globals.css, «Theme editor» хэсэг; style nexus, depth soft, Gerege цэнхэр). Хэрэглэгч Тохиргоо → Харагдац дээр accent сонгосон үед л data-accent тавигдаж тухайн хөтөч дээр суулгацын өнгийг дарна; «Суулгацын өнгө» сонголт буцаана.

BRAND_THEME_COLOR нь эдгээрээс тусдаа: PWA manifest ба <meta name="theme-color">-ийн hex өнгө (хөтчийн хэрэгслийн мөр, суулгасан аппын цонх). UI-ийн токенд нөлөөлөхгүй тул accent-тайгаа ойролцоо өнгө өг. Distribution-ий бүрэн жагсаалтыг Distribution-оос.

Release ба deploy

Цорын ганц суулгац (nexus.gerege.net) нь main-аас автоматаар гардаг: main-д push хийсэн CI амжилттай дуусмагц deploy-dev.yml self-hosted core-dev runner дээр тэр commit-ийн SHA-тай image-уудыг GHCR-аас татаж гаргана. Host-ын compose файл, нууцууд proxmox-gerege-net (stack/nexus) репод. Хурдан, найдвартай байлгах дүрэм:

  1. Release нь feature PR дотор. Тусдаа release/vX.Y.Z PR нээхгүй. Feature PR-ийн сүүлийн commit нь: node scripts/changelog.mjs collect, backend/internal/kernel/config/version.go-ийн PlatformVersion, CHANGELOG.md-д ## [X.Y.Z] - YYYY-MM-DD. Merge хийсний дараа merge commit дээр annotated tag backend/vX.Y.Z тавина (release.yml GitHub release гаргана). Тусдаа release PR нь CI → main CI → deploy-г хоёр дахин ажиллуулж 40–50 минут болгодог байв.
  2. Merge хийхийн өмнө main дээр rebase. ci.yml-ийн «Already tested» нь merge commit-ийн tree нь CI давсан PR-ийн head-тэй яг ижил үед Lint, Test, Frontend Build-ийг дахин ажиллуулахгүй (зөвхөн image build) — хоцорсон branch-ийн merge бүх CI-г дахин ажиллуулж ~10 минут нэмнэ.
  3. Жижиг засварыг нэг release-д цуглуул. Засвар бүрд хувилбар гаргахгүй.
  4. Deploy унавал шалтгааныг хар, давтан бүү ажиллуул. Deploy нь зөвхөн main-ийн push-ийн CI амжилттай дууссан үед эхэлнэ; унавал run-ийн логийг (docker compose logs хэвлэгддэг) уншиж шалтгааныг зас.
  5. Merge-ийн дараа core-dev deploy амжилттай болсныг шалга: gh run list --workflow deploy-dev.yml --limit 1 нь merge commit-ийн SHA дээр success байх ёстой.

Хүлээгдэх хугацаа: PR-ийн CI ~10–12 мин, merge-ээс nexus.gerege.net ~3–5 мин (тестүүдийг алгассан үед), хоцорсон branch бол ~12 мин.

Баримт бичиг ба орчуулга

  • Үндсэн хэл нь монгол. Орчуулгууд docs/ дор _AR, _EN, _ES, _FR, _RU, _ZH дагавартай (README зургаан хэлээр; DEVELOPMENT, SECURITY зөвхөн _EN). Монгол эх өөрчлөгдвөл орчуулгууд ижил бүтэцтэй байх ёстой.
  • Баримт бичигт emoji ашиглахгүй. Дүрс шаардлагатай бол docs/assets/icons/ дахь Flaticon дүрсийг ашиглаж, ATTRIBUTION.md-д эх сурвалжийг нэмнэ.
  • Орчуулга нэмэх журмыг docs/README.md-ээс үзнэ үү.