OmniRoute/docs/i18n/km/CONTRIBUTING.md

Contributing to OmniRoute (ខ្មែរ)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

សូមអរគុណចំពោះចំណាប់អារម្មណ៍របស់អ្នកក្នុងការចូលរួមចំណែក! មគ្គុទ្ទេសក៍នេះគ្របដណ្តប់លើអ្វីៗទាំងអស់ដែលអ្នកត្រូវការ ដើម្បីចាប់ផ្តើម។

សម្រាប់លំហូរការងារផ្លូវការតាមការផ្លាស់ប្តូរនីមួយៗ សូមចាប់ផ្តើមជាមួយ គន្លងស្តង់ដារសម្រាប់ការចូលរួមចំណែក។ វាផ្គូផ្គងការផ្លាស់ប្តូរលើ provider, routing, UI/UX, i18n, CLI, មូលដ្ឋានទិន្នន័យ និង build/deploy ទៅនឹងកិច្ចសន្យា ការធ្វើតេស្តជាក់លាក់ វិសាលភាព CI និងជំហានផ្ទៀងផ្ទាត់របស់វា។

---

ការរៀបចំបរិស្ថានអភិវឌ្ឍន៍

តម្រូវការជាមុន

• Node.js >=22.22.3 <23 ឬ >=24.0.0 <27 (បានណែនាំ៖ 24 LTS)
• npm 10+

អ្នកប្រើ npm v11+ (Node 24+): បន្ទាប់ពី npm install សូមផ្ទៀងផ្ទាត់ថាម៉ូឌុល native ត្រូវបានដំឡើង៖ node -e "require('better-sqlite3')"។ ប្រសិនបើវាបរាជ័យដោយមាន MODULE_NOT_FOUND សូមដំណើរការ npm approve-scripts better-sqlite3 && npm install។ សូមមើល ការដោះស្រាយបញ្ហា។

• Git

Clone និងដំឡើង

git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute
npm install

អថេរបរិស្ថាន

# បង្កើត .env របស់អ្នកពីគំរូ
cp .env.example .env

# បង្កើតតម្លៃសម្ងាត់ដែលត្រូវការ
echo "JWT_SECRET=$(openssl rand -base64 48)" >> .env
echo "API_KEY_SECRET=$(openssl rand -hex 32)" >> .env

អថេរសំខាន់ៗសម្រាប់ការអភិវឌ្ឍ៖

អថេរ	តម្លៃលំនាំដើមសម្រាប់ការអភិវឌ្ឍ	ការពិពណ៌នា
PORT	20128	ច្រកម៉ាស៊ីនមេ
NEXT_PUBLIC_BASE_URL	http://localhost:20128	URL មូលដ្ឋានសម្រាប់ frontend
JWT_SECRET	(បង្កើតខាងលើ)	តម្លៃសម្ងាត់សម្រាប់ចុះហត្ថលេខា JWT
INITIAL_PASSWORD	CHANGEME	ពាក្យសម្ងាត់សម្រាប់ការចូលលើកដំបូង
APP_LOG_LEVEL	info	កម្រិតលម្អិតនៃកំណត់ហេតុ

ការកំណត់ Dashboard

Dashboard ផ្តល់កុងតាក់ UI សម្រាប់មុខងារដែលអាចកំណត់រចនាសម្ព័ន្ធតាមរយៈអថេរបរិស្ថានផងដែរ៖

ទីតាំងការកំណត់	កុងតាក់	ការពិពណ៌នា
Settings → Advanced	របៀបបំបាត់កំហុស	បើកកំណត់ហេតុសំណើសម្រាប់បំបាត់កំហុស (UI)
Settings → General	ភាពមើលឃើញនៃរបារចំហៀង	បង្ហាញ/លាក់ផ្នែកនៃរបារចំហៀង

ការកំណត់ទាំងនេះត្រូវបានរក្សាទុកក្នុងមូលដ្ឋានទិន្នន័យ ហើយនៅតែមានបន្ទាប់ពីការចាប់ផ្តើមឡើងវិញ ដោយជំនួសតម្លៃលំនាំដើមរបស់អថេរបរិស្ថាន នៅពេលត្រូវបានកំណត់។

ដំណើរការក្នុងម៉ាស៊ីនផ្ទាល់

# របៀបអភិវឌ្ឍន៍ (ផ្ទុកឡើងវិញភ្លាមៗ)
npm run dev

# ការបង្កើតសម្រាប់ production
npm run build    # next build → .build/next/ បន្ទាប់មក assembleStandalone → dist/
npm run start

# ចងក្រងតែ backend/API យ៉ាងរហ័ស សម្រាប់ការផ្លាស់ប្តូររបស់អ្នកចូលរួមចំណែក
npm run build:contributor

# ការបង្កើតសម្រាប់ release (បង្កើតឡើងវិញពីស្អាត + សញ្ញាផ្ទៀងផ្ទាត់ HEAD — តម្រូវសម្រាប់ deploy)
npm run build:release   # rm -rf .build dist && build + សរសេរ dist/BUILD_SHA

# ការកំណត់រចនាសម្ព័ន្ធច្រកដែលប្រើជាទូទៅ
PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev

ការបង្កើតសម្រាប់អ្នកចូលរួមចំណែកអនុវត្តការផ្ទៀងផ្ទាត់តែការចងក្រងប៉ុណ្ណោះ៖ វាមិនរៀបចំ កញ្ចប់ចែកចាយ standalone ឬបង្កើតធនធានសម្រាប់ការវេចខ្ចប់ native ដែលជាជម្រើសទេ។ សូមប្រើការបង្កើតសម្រាប់ production ធម្មតា នៅពេល អ្នកត្រូវការផ្ទៀងផ្ទាត់កញ្ចប់ដែលអាចចែកចាយបាន។

ប្លង់លទ្ធផលនៃការបង្កើត

ថតឯកសារ	មាតិកា	ត្រូវបានតាមដាន
src/	កូដប្រភពកម្មវិធី (TypeScript / TSX)	បាទ/ចាស
.build/	ឯកសារអន្តរកាល — លទ្ធផល next build (ត្រូវបានមិនអើពើដោយ git, distDir = .build/next)	ទេ
dist/	កញ្ចប់ដែលអាចចែកចាយបាន — រៀបចំដោយ assembleStandalone (ត្រូវបានមិនអើពើដោយ git)	ទេ

ដំណើរការបង្កើតជាដំណើរការតែមួយជុំ៖

npm run build
  └─ next build → .build/next/standalone  (លទ្ធផលរបស់ Next.js)
  └─ assembleStandalone()                 (ចម្លង standalone + static + public + ធនធាន native)
       └─ លទ្ធផល៖ dist/                   (server.js, .next/static/, public/, node_modules/)

npm run build:release ក៏សម្អាតថតទាំងពីរជាមុន ហើយសរសេរ dist/BUILD_SHA (= git rev-parse --short HEAD) ជាសញ្ញាផ្ទៀងផ្ទាត់សុចរិតភាពសម្រាប់ deploy។

npm run build:contributor ប្រើប្រូហ្វាល់បង្កើតសម្រាប់តែ backend។ វាជំនួសឯកសារ UI របស់ dashboard ជាបណ្តោះអាសន្ន ខណៈពេលកំពុងបង្កើត រក្សាទុក API route handlers និងស្តារឯកសារដើម បន្ទាប់ពីការបង្កើត។ សូមប្រើ npm run build សម្រាប់ការផ្លាស់ប្តូរដែលប៉ះពាល់ដល់ UI របស់ dashboard ឬសម្រាប់ ការផ្ទៀងផ្ទាត់ release ពេញលេញ។ ប្រូហ្វាល់សម្រាប់អ្នកចូលរួមចំណែកមិនមែនជាការជំនួសការបង្កើតសម្រាប់ release ទេ។

កំណត់សម្គាល់អំពីការដាក់ពង្រាយលើ VPS: ថត image នៅម៉ាស៊ីនពីចម្ងាយ /usr/lib/node_modules/omniroute/app/ មិនមានការផ្លាស់ប្តូរទេ។ ជំនាញ deploy ប្រើ rsync ដើម្បីធ្វើសមកាលកម្មមាតិកានៃ dist/ ទៅក្នុងថតនោះ។ មានតែផ្លូវលទ្ធផលនៃការបង្កើតនៅក្នុង repository ប៉ុណ្ណោះដែលបានផ្លាស់ប្តូរ (app/ → dist/)។

URL លំនាំដើម៖

• Dashboard: http://localhost:20128/dashboard
• API: http://localhost:20128/v1

---

លំហូរការងារ Git

⚠️ កុំ commit ដោយផ្ទាល់ទៅ main ឱ្យសោះ។ ត្រូវប្រើ feature branches ជានិច្ច។

មូលដ្ឋាន PR៖ កំណត់គោលដៅទៅកាន់ branch release/vX.Y.Z ដែលកំពុងសកម្ម (មិនមែន main)។ សូមមើល docs/ops/BRANCHING_MODEL.md សម្រាប់ម៉ូដែល release-per-branch + tag-at-ship។

# បង្កើត branch ពីចំណុចចុងក្រោយនៃ release ដែលកំពុងសកម្ម (ឧទាហរណ៍៖ release/v3.8.49)
git fetch origin
git checkout -b feat/your-feature-name origin/release/v3.8.49
# ... ធ្វើការផ្លាស់ប្ដូរ ...
git commit -m "feat: describe your change"
git push -u origin feat/your-feature-name
# បើក Pull Request ដោយកំណត់ base = release/v3.8.49

ការដាក់ឈ្មោះ Branch

បុព្វបទ	គោលបំណង
feat/	មុខងារថ្មី
fix/	ការកែកំហុស
refactor/	ការរៀបចំរចនាសម្ព័ន្ធកូដឡើងវិញ
docs/	ការផ្លាស់ប្ដូរឯកសារ
test/	ការបន្ថែម/កែតម្រូវតេស្ត
chore/	ឧបករណ៍, CI, dependencies

សារ Commit

អនុវត្តតាម Conventional Commits៖

feat: add circuit breaker for provider calls
fix: resolve JWT secret validation edge case
docs: update SECURITY.md with PII protection
test: add observability unit tests
refactor(db): consolidate rate limit tables

Scopes (v3.8)៖ db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills, cloud-agent, guardrails, compression, auto-combo, resilience, providers, executors, translator, domain, authz។

---

ការដំណើរការតេស្ត

# តេស្តទាំងអស់ (unit + vitest + ecosystem + e2e)
npm run test:all

# ឯកសារតេស្តតែមួយ (កម្មវិធីដំណើរការតេស្តដើមរបស់ Node.js — តេស្តភាគច្រើនប្រើវា)
node --import tsx/esm --test tests/unit/your-file.test.ts

# តែ unit tests ដែលរងផលប៉ះពាល់ដោយការផ្លាស់ប្ដូររបស់អ្នកប៉ុណ្ណោះ (ប្រើ TIA selector ដូចគ្នានឹង CI gate, #8084)
npm run test:scoped            # ការផ្លាស់ប្ដូរនៅក្នុង commit ចុងក្រោយ (ឬ working tree)
npm run test:scoped:staged     # តែការផ្លាស់ប្ដូរដែលបាន staged — ដំណើរការល្អជាមួយ pre-commit
npm run test:scoped:full       # បង្កើតផែនទី import-graph ឡើងវិញជាមុន (បន្ទាប់ពីបន្ថែម/ផ្លាស់ទីឯកសារ)
# Exit 1 + "run the full suite" មានន័យថា hub file មួយ (tsconfig, package.json, …) ឬ
# source ដែលមិនបានផ្គូផ្គងត្រូវបានផ្លាស់ប្ដូរ — selector បរាជ័យដោយសុវត្ថិភាព ហើយវាមិនដែលរំលងដោយស្ងៀមស្ងាត់ឡើយ។

# Vitest (MCP server, autoCombo, cache)
npm run test:vitest

# តេស្ត E2E (តម្រូវឱ្យមាន Playwright)
npm run test:e2e

# E2E របស់ protocol clients (MCP transports, A2A)
npm run test:protocols:e2e

# តេស្តភាពត្រូវគ្នានៃ ecosystem
npm run test:ecosystem

# Coverage gate៖ 60% សម្រាប់ statements/lines/functions/branches
npm run test:coverage
npm run coverage:report

# ពិនិត្យ lint + format
npm run lint
npm run check

# ការធ្វើ combo smoke ជាមួយ upstream ពិតដែលមាន gate (តម្រូវឱ្យចូលប្រើ VPS + មាន credits ពិតរបស់ provider)
# វាហៅទៅកាន់ providers ពិត — ចំណាយបន្តិចបន្តួច។ មិនដែលដំណើរការនៅក្នុង CI ឡើយ។ រំលងដោយត្រឹមត្រូវបើគ្មាន gate។
# តម្រូវការ៖ សិទ្ធិចូលប្រើ ssh root@192.168.0.15 (ទាញប្រភព DB snapshot ដែលបានតែអានពី VPS)។
RUN_COMBO_LIVE=1 npm run test:combo:live

# Phase-3 VPS live smoke — scripts ជា Node ESM ធម្មតា ដែលហៅទៅកាន់ live .15 server ដោយផ្ទាល់។
# តម្រូវការ៖ សិទ្ធិចូលប្រើ ssh root@192.168.0.15 (combos ត្រូវបានបង្កើត/លុបតាមរយៈ SSH sqlite)។
# វាហៅទៅកាន់ providers ពិត (ចំណាយតិចតួច)។ បង្កើត/លុបតែ combos ដែលមានឈ្មោះ __live_test__* ប៉ុណ្ណោះ។ មិនដែលដំណើរការនៅក្នុង CI ឡើយ។
# REQUIRE_API_KEY=false នៅលើ .15 ដូច្នេះមិនត្រូវការ API key ទេ ប៉ុន្តែគោរព COMBO_LIVE_BASE_URL / COMBO_LIVE_API_KEY ប្រសិនបើបានកំណត់។
npm run test:combo:live:vps              # 7 HTTP scenarios (priority/round-robin/weighted/cost/fusion/auto + health)
npm run test:combo:live:vps:failover     # បន្ថែម cross-provider failover scenario ពិតមួយ (សរុប 8)

កំណត់ចំណាំអំពី coverage៖

• npm run test:coverage វាស់ source coverage សម្រាប់ unit test suite ចម្បង មិនរាប់បញ្ចូល tests/** និងរាប់បញ្ចូល open-sse/**
• Pull requests ត្រូវរក្សា coverage gate ឱ្យនៅ 60%+ សម្រាប់ statements/lines/functions/branches
• ប្រសិនបើ PR ផ្លាស់ប្ដូរ production code នៅក្នុង src/, open-sse/, electron/, ឬ bin/ វាត្រូវបន្ថែម ឬធ្វើបច្ចុប្បន្នភាព automated tests នៅក្នុង PR ដូចគ្នា
• npm run coverage:report បង្ហាញរបាយការណ៍លម្អិតតាមឯកសារនីមួយៗពីការដំណើរការ coverage ចុងក្រោយ
• npm run test:coverage:legacy រក្សាទុករង្វាស់ចាស់សម្រាប់ការប្រៀបធៀបប្រវត្តិសាស្ត្រ
• សូមមើល docs/ops/COVERAGE_PLAN.md សម្រាប់ផែនការកែលម្អ coverage ជាដំណាក់កាល

តម្រូវការរបស់ Pull Request

មុនពេលបើក PR សូមប្រើ Contribution Golden Path ដើម្បីដំណើរការ focused loop សម្រាប់ អ្វីដែលអ្នកបានផ្លាស់ប្ដូរ។ unit suite ពេញលេញ (4 CI shards), Vitest, coverage gate 60%+ និង production build គឺជាការទទួលខុសត្រូវរបស់ CI — ការដំណើរការពួកវានៅ local មិនផ្ដល់ព័ត៌មានបន្ថែមដែលការត្រួតពិនិត្យ PR មិនបានផ្ដល់ឱ្យអ្នករួចហើយទេ ហើយនៅលើម៉ាស៊ីនតូចៗ វាអាចប្រើធនធាន host រហូតដល់អតិបរមា (#8084)៖

• ដំណើរការឯកសារតេស្តដែលគ្របដណ្ដប់ការផ្លាស់ប្ដូររបស់អ្នក៖ node --import tsx/esm --test tests/unit/<file>.test.ts
• ដំណើរការ npm run lint
• បន្ថែម ឬធ្វើបច្ចុប្បន្នភាព automated tests នៅក្នុង PR ដូចគ្នា រាល់ពេល production code ផ្លាស់ប្ដូរ
• រាយបញ្ចូលឯកសារតេស្តដែលបានផ្លាស់ប្ដូរ ឬបន្ថែមនៅក្នុងការពិពណ៌នា PR នៅពេល production code បានផ្លាស់ប្ដូរ
• ពិនិត្យលទ្ធផល SonarQube នៅលើ PR នៅពេល project secrets ត្រូវបានកំណត់នៅក្នុង CI

ស្ថានភាពតេស្តបច្ចុប្បន្ន៖ 122 ឯកសារ unit test ដែលគ្របដណ្ដប់លើ៖

• Provider translators និងការបម្លែង format
• Rate limiting, circuit breaker និង resilience
• Semantic cache, idempotency និង progress tracking
• ប្រតិបត្តិការ database និង schema (21 DB modules)
• OAuth flows និង authentication
• ការផ្ទៀងផ្ទាត់ API endpoint (Zod v4)
• ឧបករណ៍ MCP server និងការអនុវត្ត scope
• ប្រព័ន្ធ Memory និង Skills

---

រចនាប័ទ្មកូដ

• ESLint — ដំណើរការ npm run lint មុនពេល commit
• Prettier — ត្រូវបានធ្វើទ្រង់ទ្រាយដោយស្វ័យប្រវត្តិតាមរយៈ lint-staged នៅពេល commit (ចន្លោះ 2, សញ្ញា semicolon, សញ្ញាសម្រង់ទ្វេ, ទទឹង 100 តួអក្សរ, សញ្ញាក្បៀសនៅខាងចុងតាម es5)
• TypeScript — កូដទាំងអស់ក្នុង src/ ប្រើ .ts/.tsx; open-sse/ ប្រើ .ts/.js; សរសេរឯកសារពន្យល់ដោយប្រើ TSDoc (@param, @returns, @throws)
• ហាមប្រើ eval() — ESLint អនុវត្តច្បាប់ no-eval, no-implied-eval, no-new-func
• ការផ្ទៀងផ្ទាត់ដោយ Zod — ប្រើ schema របស់ Zod v4 សម្រាប់ការផ្ទៀងផ្ទាត់ input របស់ API ទាំងអស់
• ការដាក់ឈ្មោះ: ឯកសារ = camelCase/kebab-case, component = PascalCase, constant = UPPER_SNAKE

ការដោះស្រាយកំហុស / ប្លុក catch ទទេ

កុំទុក catch ដោយគ្មានការពន្យល់។ ចាត់ថ្នាក់វាទៅក្នុងក្រុមមួយក្នុងចំណោមពីរ (ដើម្បីអនុវត្ត ច្បាប់តឹងរ៉ឹង «មិនត្រូវលេបកំហុសដោយស្ងៀមស្ងាត់នៅក្នុង SSE stream ឡើយ»)៖

• ដោយចេតនា (ការសម្អាត/telemetry បែបប្រឹងប្រែងឱ្យអស់ពីលទ្ធភាពរបស់យើងផ្ទាល់) — ការបរាជ័យនៅទីនេះត្រូវបានរំពឹងទុក និង មិនបង្កគ្រោះថ្នាក់ឡើយ; បន្ថែម comment មួយបន្ទាត់ដែលពន្យល់ពីហេតុផល ដោយមិនចាំបាច់ logging (ការធ្វើ logging រាល់ request គឺជា ទិន្នន័យរំខានដែលអនុសញ្ញានេះចង់ជៀសវាង)។

  } catch {} // ការបិទ controller ដែលបានបិទរួចហើយ បន្ទាប់ពី client ផ្ដាច់ការតភ្ជាប់ គឺជាអ្វីដែលបានរំពឹងទុក
  

• គួរធ្វើ log (កូដខាងក្រៅ/កូដដែល caller ផ្ដល់ឱ្យ ឬការលេបកំហុសធ្វើឱ្យលំហូរនៃការគ្រប់គ្រងផ្លាស់ប្ដូរ) — រក្សា catch ទុក (កុំឱ្យវាបង្អាក់ stream) ប៉ុន្តែបញ្ចេញ console.debug/warn ដែលមានបរិបទ ដើម្បីឱ្យ អាចស្វែងរកការបរាជ័យបាន។

  } catch (e) {
    console.debug("[STREAM] onFailure callback error:", e);
  }
  

សូមមើល open-sse/utils/stream.ts និង open-sse/utils/streamHandler.ts សម្រាប់ឧទាហរណ៍ដែលបានអនុវត្ត។

---

រចនាសម្ព័ន្ធគម្រោង

src/                        # TypeScript (.ts / .tsx)
├── app/                    # Next.js 16 App Router
│   ├── (dashboard)/        # ទំព័រ dashboard (23 ផ្នែក)
│   ├── api/                # route របស់ API (51 ថត)
│   └── login/              # ទំព័រផ្ទៀងផ្ទាត់អត្តសញ្ញាណ (.tsx)
├── domain/                 # ម៉ាស៊ីនគោលការណ៍ (policyEngine, comboResolver, costRules ជាដើម)
├── lib/                    # តក្កវិជ្ជាអាជីវកម្មស្នូល (.ts)
│   ├── a2a/                # server សម្រាប់ protocol Agent-to-Agent v0.3
│   ├── acp/                # បញ្ជីឈ្មោះ Agent Communication Protocol
│   ├── compliance/         # ម៉ាស៊ីនគោលការណ៍អនុលោមភាព
│   ├── db/                 # module ដែន SQLite + migration ចំនួន 130
│   ├── memory/             # អង្គចងចាំការសន្ទនាអចិន្ត្រៃយ៍
│   ├── oauth/              # provider, service និង utility របស់ OAuth
│   ├── skills/             # framework ជំនាញដែលអាចពង្រីកបាន
│   ├── usage/              # ការតាមដានការប្រើប្រាស់ និងការគណនាចំណាយ
│   └── localDb.ts          # ស្រទាប់ re-export ប៉ុណ្ណោះ — កុំបន្ថែមតក្កវិជ្ជានៅទីនេះ
├── middleware/              # middleware សម្រាប់ request (promptInjectionGuard)
├── mitm/                   # proxy MITM (វិញ្ញាបនបត្រ, DNS, ការកំណត់ route ទៅគោលដៅ)
├── shared/
│   ├── components/         # component របស់ React (.tsx)
│   ├── constants/          # និយមន័យ provider (329), scope របស់ MCP, យុទ្ធសាស្ត្រកំណត់ route ចំនួន 19
│   ├── utils/              # circuit breaker, sanitizer, helper សម្រាប់ការផ្ទៀងផ្ទាត់អត្តសញ្ញាណ
│   └── validation/         # schema របស់ Zod v4
└── sse/                    # pipeline proxy របស់ SSE

open-sse/                   # workspace របស់ @omniroute/open-sse
├── executors/              # module អនុវត្ត executor ចំនួន 89
├── handlers/               # request handler ចំនួន 11 (chat, responses, embeddings, images ជាដើម)
├── mcp-server/             # server MCP (tool ដាច់ដោយឡែកចំនួន 110, transport ចំនួន 3, scope ចំនួន 33)
├── services/               # service កម្រិតកំពូលចំនួន 178 (combo, autoCombo, rateLimitManager ជាដើម)
├── translator/             # ឧបករណ៍បកប្រែទ្រង់ទ្រាយ (OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama)
├── transformer/            # transformer សម្រាប់ Responses API
└── utils/                  # module utility ចំនួន 22 (stream, TLS, proxy, logging)

electron/                   # កម្មវិធី desktop Electron (ឆ្លងវេទិកា)

tests/
├── unit/                   # ឧបករណ៍ដំណើរការ test របស់ Node.js (ឯកសារ test ចំនួន 1,574)
├── integration/            # test សមាហរណកម្ម
├── e2e/                    # test របស់ Playwright
├── security/               # test សុវត្ថិភាព
├── translator/             # test ជាក់លាក់សម្រាប់ translator
└── load/                   # test បន្ទុក

docs/
├── adr/                     # កំណត់ត្រាសេចក្ដីសម្រេចផ្នែកស្ថាបត្យកម្ម
├── architecture/            # ស្ថាបត្យកម្មប្រព័ន្ធ និងភាពធន់
├── comparison/              # OmniRoute ប្រៀបធៀបនឹងជម្រើសផ្សេងៗ
├── compression/             # មគ្គុទ្ទេសក៍ និងច្បាប់នៃការបង្ហាប់
├── dev/                     # មគ្គុទ្ទេសក៍អភិវឌ្ឍន៍
├── diagrams/                # ដ្យាក្រាមស្ថាបត្យកម្ម
├── frameworks/              # MCP, A2A, OpenCode, Memory, Skills
├── guides/                  # មគ្គុទ្ទេសក៍អ្នកប្រើប្រាស់, Docker, ការដំឡើង, ការដោះស្រាយបញ្ហា
├── i18n/                    # ការបកប្រែ README ជាភាសាអន្តរជាតិ
├── marketing/               # សម្ភារៈទីផ្សារ
├── ops/                     # ការដាក់ឱ្យប្រើប្រាស់, proxy, coverage, ការចេញផ្សាយ
├── providers/               # ឯកសារជាក់លាក់សម្រាប់ provider
├── reference/               # ឯកសារយោង API, env vars, ឧបករណ៍ CLI, កម្រិតប្រើប្រាស់ឥតគិតថ្លៃ
├── releases/                # កំណត់សម្គាល់ការចេញផ្សាយ
├── routing/                 # ម៉ាស៊ីន auto-combo, ការចាក់ឡើងវិញនូវការវែកញែក
├── screenshots/             # screenshot របស់ dashboard
├── security/                # របាំងការពារ, អនុលោមភាព, ការលាក់បាំង, token
└── specs/                   # លក្ខណៈបច្ចេកទេសនៃការរចនា

---

ការបន្ថែមអ្នកផ្តល់សេវាថ្មី

ជំហានទី 1៖ ចុះឈ្មោះថេររបស់អ្នកផ្តល់សេវា

បន្ថែមទៅក្នុង src/shared/constants/providers.ts — ត្រូវបានផ្ទៀងផ្ទាត់ដោយ Zod នៅពេលផ្ទុកម៉ូឌុល។

ជំហានទី 2៖ បន្ថែម Executor (ប្រសិនបើត្រូវការឡូជីខលផ្ទាល់ខ្លួន)

បង្កើត executor នៅក្នុង open-sse/executors/your-provider.ts ដោយពង្រីកពី executor មូលដ្ឋាន។

ជំហានទី 3៖ បន្ថែម Translator (ប្រសិនបើមិនមែនជាទម្រង់ OpenAI)

បង្កើត translator សម្រាប់ request/response នៅក្នុង open-sse/translator/។

ជំហានទី 4៖ បន្ថែមការកំណត់រចនាសម្ព័ន្ធ OAuth (ប្រសិនបើផ្អែកលើ OAuth)

បន្ថែមព័ត៌មានសម្ងាត់ OAuth នៅក្នុង src/lib/oauth/constants/oauth.ts និងសេវាកម្មនៅក្នុង src/lib/oauth/services/។

ប្រសិនបើអ្នកផ្តល់សេវាខាងដើមចែកចាយ OAuth client_id/secret សាធារណៈ ឬ Firebase Web API key នៅក្នុង CLI / browser bundle សាធារណៈរបស់ខ្លួន កុំ បង្កប់វាជា string literal។ ប្រើ resolvePublicCred() ពី open-sse/utils/publicCreds.ts ហើយបន្ថែមធាតុ byte ដែលបានបិទបាំងទៅក្នុង EMBEDDED_DEFAULTS។ លំហូរការងារចាំបាច់ពេញលេញត្រូវបានចងក្រងជាឯកសារនៅក្នុង docs/security/PUBLIC_CREDS.md។

នៅខាងក្នុង handlers/executors សារកំហុសដែលទៅដល់ម៉ាស៊ីនភ្ញៀវត្រូវតែឆ្លងកាត់ buildErrorBody() / sanitizeErrorMessage() ពី open-sse/utils/error.ts — កុំដាក់ err.stack ឬ err.message ដើមនៅក្នុង Response body។ សូមមើល docs/security/ERROR_SANITIZATION.md។

ជំហានទី 5៖ ចុះឈ្មោះម៉ូដែល

បន្ថែមនិយមន័យម៉ូដែលនៅក្នុង open-sse/config/providerRegistry.ts។

ជំហានទី 6៖ បន្ថែមតេស្ត

សរសេរ unit tests នៅក្នុង tests/unit/ ដែលយ៉ាងហោចណាស់គ្របដណ្តប់លើ៖

• ការចុះឈ្មោះអ្នកផ្តល់សេវា
• ការបម្លែង request/response
• ការដោះស្រាយកំហុស

---

បញ្ជីត្រួតពិនិត្យ Pull Request

• តេស្តឆ្លងកាត់ (npm test)
• ការត្រួតពិនិត្យ Lint ឆ្លងកាត់ (npm run lint)
• ការ build ជោគជ័យ (npm run build)
• បានបន្ថែម TypeScript types សម្រាប់ functions និង interfaces សាធារណៈថ្មី
• គ្មានព័ត៌មានសម្ងាត់ ឬតម្លៃ fallback ដែលបាន hardcode
• ព័ត៌មានសម្ងាត់សាធារណៈពីប្រភពខាងដើមត្រូវបានបង្កប់តាមរយៈ resolvePublicCred() (សូមមើល docs/security/PUBLIC_CREDS.md) មិនត្រូវបង្កប់ជា literals ឡើយ
• Error responses ឆ្លងកាត់ buildErrorBody() / sanitizeErrorMessage() — គ្មាន stack traces ដើមនៅក្នុង response bodies (សូមមើល docs/security/ERROR_SANITIZATION.md)
• Shell commands (exec / spawn) បញ្ជូនតម្លៃ runtime តាមរយៈ env មិនមែនតាមរយៈ string interpolation
• Inputs ទាំងអស់ត្រូវបានផ្ទៀងផ្ទាត់ដោយប្រើ Zod schemas
• បានបន្ថែម fragment នៃ changelog នៅក្រោម changelog.d/{features|fixes|maintenance}/<PR>-<slug>.md សម្រាប់ការផ្លាស់ប្តូរដែលអ្នកប្រើប្រាស់អាចមើលឃើញ (សូមមើល changelog.d/README.md) — កុំ កែសម្រួល CHANGELOG.md ដោយផ្ទាល់; fragments ត្រូវបានប្រមូលបញ្ចូលគ្នានៅពេលចេញ release ហើយមិនដែលប៉ះទង្គិចគ្នារវាង PRs ឡើយ
• ឯកសារត្រូវបានធ្វើបច្ចុប្បន្នភាព (ប្រសិនបើអាចអនុវត្តបាន)
• មិនមាន CodeQL / Secret-Scanning alerts ថ្មីត្រូវបានបើក ឬ alerts នីមួយៗត្រូវបានបដិសេធដោយមានយុត្តិកម្មបច្ចេកទេសយោងទៅឯកសារ docs/security/ ដែលពាក់ព័ន្ធ
• Routes ដែលបង្កើត child processes (/api/mcp/, /api/cli-tools/runtime/) ត្រូវបានចាត់ថ្នាក់ជា isLocalOnlyPath() នៅក្នុង src/server/authz/routeGuard.ts — សូមមើល ច្បាប់តឹងរ៉ឹង #15
• គ្មាន trailers Co-Authored-By នៅក្នុង commit messages — commits ត្រូវតែបង្ហាញតែក្រោម Git identity របស់ម្ចាស់ repository ប៉ុណ្ណោះ (ច្បាប់តឹងរ៉ឹង #16)

---

ការចេញផ្សាយ

ការចេញផ្សាយត្រូវបានគ្រប់គ្រងតាមរយៈ workflow /generate-release។ នៅពេល GitHub Release ថ្មីត្រូវបានបង្កើត package នឹងត្រូវបាន បោះពុម្ពផ្សាយទៅ npm ដោយស្វ័យប្រវត្តិ តាមរយៈ GitHub Actions។

សម្រាប់ការដាក់ឱ្យដំណើរការលើ VPS សូមប្រើ npm run build:release (មិនមែន npm run build ទេ) — វាធ្វើការស្ថាបនាឡើងវិញពីសូន្យ រៀបចំ bundle ទៅក្នុង dist/ និងសរសេរ sentinel dist/BUILD_SHA។ បន្ទាប់មក ប្រើ skills /deploy-vps-*-cc ដែលប្រើ rsync ដើម្បីធ្វើសមកាលកម្ម dist/ ទៅកាន់ថត app/ នៅលើម៉ាស៊ីនពីចម្ងាយ។

---

ការទទួលជំនួយ

• ស្ថាបត្យកម្ម៖ សូមមើល docs/architecture/ARCHITECTURE.md
• ឯកសារយោង API៖ សូមមើល docs/reference/API_REFERENCE.md
• ឯកសារសុវត្ថិភាព៖ docs/security/CLI_TOKEN.md, docs/security/ROUTE_GUARD_TIERS.md, docs/security/ERROR_SANITIZATION.md, docs/security/PUBLIC_CREDS.md
• ឯកសារប្រតិបត្តិការ៖ docs/ops/SQLITE_RUNTIME.md
• បញ្ហា៖ github.com/diegosouzapw/OmniRoute/issues
• ADRs៖ សូមមើល docs/adr/ សម្រាប់កំណត់ត្រាសេចក្ដីសម្រេចផ្នែកស្ថាបត្យកម្ម