Системийн товч танилцуулга

plan.danda.mn нь байгууллагын үүрэг даалгавар олголт, хэрэгжилт, нотолгооны менежментийг нэгтгэсэн систем.

Яагаад холбох вэ?

Гадаад системээс (ERP/CRM/бот) шууд даалгавар үүсгэж, хуваарилах
Статус + хугацааг бодитоор хянах, SLA автоматаар сануулах
Нотолгоо, хавсралтыг API-аар эсвэл UI дээрээс байршуулж уялдуулах

Гол зарчим

Token, нууц түлхүүрийг зөвхөн орчны хувьсагчаар хадгал
HTTPS + IP allowlist ашиглана
Бүх хүсэлтэд trace ID логлож, token хэвлэхгүй

Нэвтрэх ба аюулгүй байдал

Role: Интеграц хийх хэрэглэгчид API хандалтын эрх (read/write) оноосон байх.
Token авах: plan.danda.mn дээр байгууллагын админ API token/generic access key үүсгэнэ. Token-оо зөвхөн env-д хадгал; commit, лог, чат руу бүү илгээгээрэй.
Base URL: https://plan.danda.mn (API-гийн замыг доорх жишээнээс авна).
IP allowlist: Сүлжээний хамгаалалттай бол интеграцийн серверийн гаралтын IP-г whitelist-д оруул.
HTTPS: Зөвхөн HTTPS ашиглана; HTTP-г бүхэлд нь хаасан байх ёстой.

APP_ENV=production
PLAN_BASE_URL=https://plan.danda.mn
PLAN_API_TOKEN=your-plan-token    # бодит token-оо git, лог, шууд чатанд бүү оруул
PLAN_TIMEOUT=10

API холболтын үндсэн урсгал

Аутентикаци: Бүх хүсэлтэд Authorization: Bearer <token> толгой ашиглана.
Даалгавар үүсгэх: POST /api/v1/tasks (organization/project, name, dueDate, assignee, priority, tags, checklist гэх мэт талбаруудыг API spec-тэй тааруулан бөглөнө).
Статус шинэчлэх: PATCH /api/v1/tasks/{id}/status (new → in_progress → submitted → done). Статус бүрд тэмдэглэл, хугацаа, нотолгооны ID-г хавсаргана.
Нотолгоо/файл: Эхлээд файл байршуулах POST /api/v1/files (multipart), буцаасан fileId-г даалгаварт холбох.
Төлөв лавлах: GET /api/v1/tasks/{id} эсвэл жагсаалт GET /api/v1/tasks?status=pending&assignee=....
Webhook (сонголтоор): Статус өөрчлөгдөхөд дотоод /webhooks/plan гэх мэт хаяг руу POST илгээдэг. Ирсэн гарын үсэг/толь header-ийг шалгаж, 200 буцаах.

СанамжЭндхийн зам, талбаруудыг байгууллагын бодит API spec-тэй тохируулан соль. Token-оо логонд хэвлэхгүй.

Шуурхай жишээ (curl)

Placeholder утгуудыг өөрчлөөд smoke test хийнэ.

BASE_URL="https://plan.danda.mn"
TOKEN="$PLAN_API_TOKEN"

# 1) Даалгаврын жагсаалт
curl -X GET "$BASE_URL/api/v1/tasks?status=pending" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

# 2) Шинэ даалгавар үүсгэх (жишээ талбарууд)
curl -X POST "$BASE_URL/api/v1/tasks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Дотоод аудитын тайлан бэлтгэх",
    "projectId": "PRJ-001",
    "assignee": "user@example.com",
    "dueDate": "2024-12-15T12:00:00Z",
    "priority": "high",
    "tags": ["audit","q4"],
    "checklist": ["Баримт цуглуулах","Ноорог","Эцсийн хувилбар"],
    "description": "Q4 аудитын дотоод тайлан гаргах"
  }'

# 3) Статус шинэчлэх
curl -X PATCH "$BASE_URL/api/v1/tasks/TASK-ID/status" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "status": "submitted", "note": "Нотолгоо хавсаргасан" }'

Амжилтгүй үед зөвхөн статус код, trace ID-г логлож, token-оо хэзээ ч хэвлэхгүй.

Системийг өдөр тутам ашиглах зөвлөмж

Ажиллагааны зарчим

Өгөгдөл гарал бүрт (ERP/CRM/бот) даалгаврын source/идентификаторыг хадгал; trace хийхэд хялбар.
Dashboard → Даалгавар → “+” товчоор гар аргаар үүсгэх, эсвэл API-аар орж ирснийг шалгаж баталгаажуулах.
Автомат дүүргэлт: priority, dueDate, assignee-г гадаад системээс дамжуулж, UI дээр зөвхөн баталгаажуул.

Нотолгоо ба хавсралт

PDF/зураг хавсралтыг API-аар эсвэл UI дээрээс оруулах, файл бүрт төрөл/тайлбар үлдээх.
User-Agent: plan-integration/<version> толгой ашиглаж, өөрчлөлт бүрийн дараа smoke test гүйлгэ.
Интеграцийн token нь зөвхөн machine account дээр; хэрэглэгчийн хувийн токен ашиглахгүй.

Мониторинг ба чанарын хяналт

5xx болон timeout тохиолдлыг тоолж, босго давбал опс сувгаар мэдэгдэл илгээ.
Хэрэгжилтийн SLA: dueDate-д тулгуурлан урьдчилсан анхааруулга (e.g., 24/4 цагийн өмнө) илгээ.
Webhook алдаа гарвал retry/backoff болон dead-letter queue хэрэгжүүл.
Logs: зөвхөн статус код, trace ID хадгал; token, payload-ын нууц өгөгдлийг масклах.

Түгээмэл алдаа, шийдэл

401/403: Token хүчингүй эсвэл эрх хүрэхгүй. Админ-аас шинэ token авч, IP allowlist шалга.
404: API зам/хувилбар буруу (/api/v1/... эсэхийг нягтал).
409: Давхардсан externalId/sourceId. Давтагдашгүй түлхүүр илгээ.
408/504: Timeout. PLAN_TIMEOUT-оо нэмэх, эсвэл payload багасгах.
Webhook 400/500: Хүлээн авах талын гарын үсэг/огноо/nonce шалгалтыг идэвхжүүлж, буцах 200-г баталгаажуул.

QA зөвлөмжШинэ интеграц эсвэл өөрчлөлт бүрд sandbox/QA token ашиглаж, smoke test, дараа нь prod token соль.