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

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"
}'

3.9 KiB Raw Blame History