سامانه استعلام کد ملی

API با Hono + Zod + OpenAPI + MySQL + Docker

نصب و اجرا (Local)

npm install
npm run dev

سرور روی پورت پیش‌فرض 20205 اجرا می‌شود (قابل تغییر با PORT).

اجرای Docker

docker compose up -d --build

Environmentهای مهم (در docker-compose قابل تنظیم):

• PORT (پیش‌فرض: 20205)
• DB_NAME, DB_USER, DB_PASS, DB_HOST, DB_PORT
• JIBIT_API_KEY, JIBIT_SECRET_KEY

استفاده

• احراز هویت با هدر Authorization الزامی است (Bearer token).
• اگر در body فیلد host ارسال شود، درخواست‌ها به نام کاربر همان host ثبت می‌شود؛ اگر وجود نداشته باشد ساخته می‌شود.

مثال:

curl --location 'http://localhost:20205/check_user' \
--header 'Authorization: Bearer admin-token' \
--header 'Content-Type: application/json' \
--data '{
  "number": "09372281182",
  "national": "1274467144",
  "host": "golak"
}'

پاسخ:

{ "matched": true | false }

نکات:

• اگر رکورد قبلاً برای همان host (کاربر) ثبت شده باشد، از کش persons بازمی‌گردد.
• اگر نبود، از سرویس جیبیت استعلام می‌شود؛ در صورت 401/403 ابتدا refresh سپس generate token و مجدد تلاش می‌شود.
• ارورهای جیبیت به صورت { error, code, status } پاس داده می‌شوند.

مستندات (OpenAPI)

Swagger UI: http://localhost:20205/ OpenAPI JSON: http://localhost:20205/doc

محل کدها و روتر

• نقطه شروع سرور: src/index.ts
• روترها: src/routes/user.routes.ts
• کنترلر استعلام: src/controllers/user.controller.ts
• سرویس توکن جیبیت: src/services/jibit.service.ts
• مدل‌ها (Sequelize):
  • کاربران: src/models/User.model.ts
  • افراد (persons): src/models/Person.model.ts
  • کارت‌ها: src/models/Card.model.ts
  • لاگ‌ها: src/models/Log.model.ts
• تنظیمات دیتابیس: src/config/database.ts

دیتابیس و جداول

• users: مدیریت کاربران سیستم و hostها
  • id, username, domain, host, token, isAdmin, queryCount, timestamps
• persons: کش نتایج استعلام برای هر کاربر (host)
  • id, national, number, matched, userId, timestamps
  • ایندکس یکتا: (national, number, userId)
• tokens: نگهداری access/refresh توکن جیبیت
  • id, accessToken, refreshToken, timestamps
• logs: لاگ همه درخواست‌ها
  • type (incoming|outgoing), method, path, headers, body, response, status, durationMs, ip, userId, targetUrl, timestamps
  • محدودیت سقف 85,000 رکورد (قدیمی‌ها پاک می‌شوند)

تنظیمات محیطی

• PORT: پورت سرویس (پیش‌فرض 20205)
• DB_*: تنظیمات اتصال MySQL
• JIBIT_API_KEY, JIBIT_SECRET_KEY: کلیدهای سرویس جیبیت

رفتارهای کلیدی

• Authorization: کاربر درخواست‌کننده از روی توکن یافت می‌شود.
• host در body: کاربر هدف بر اساس host ساخته/یافته می‌شود و استعلام به نام او ثبت می‌گردد.
• persons: کش به ازای هر کاربر جداست؛ تداخل بین hostها وجود ندارد.
• روی خطای یکتا/اعتبار هنگام ذخیره Person، نتیجه از رکورد موجود خوانده و بازگردانده می‌شود، بدون خطای Validation.

تست سریع

curl --location 'http://localhost:20205/check_user' \
--header 'Authorization: Bearer admin-token' \
--header 'Content-Type: application/json' \
--data '{
  "number": "09372281182",
  "national": "1274467144",
  "host": "golak"
}'