Identity_verification--jibit-/README.md

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

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

نصب و اجرا (Local)

1. ساخت فایل‌های env

• فایل نمونه (پیشنهادی): .env.example

PORT=20205
DB_NAME=Identity_verification
DB_USER=root
DB_PASS=change_me
DB_HOST=localhost
DB_PORT=3306
JIBIT_API_KEY=change_me
JIBIT_SECRET_KEY=change_me

• فایل اصلی: .env (مقادیر واقعی خودتان را جایگزین کنید)

PORT=20205
DB_NAME=Identity_verification
DB_USER=root
DB_PASS=changeme
DB_HOST=localhost
DB_PORT=3306
JIBIT_API_KEY=your_key
JIBIT_SECRET_KEY=your_secret

2. اجرای پروژه (نیازمند MySQL در حال اجرا):

npm install
npm run dev

سرور: http://localhost:20205

• پنل ادمین: /
• Swagger: /swagger
• OpenAPI: /doc

اجرای Docker

1. .env را در ریشه پروژه قرار دهید (از بخش بالا)

2. اجرا:

docker compose up -d --build

• سرویس اپ: http://localhost:${PORT} (پیش‌فرض 20205)
• سرویس MySQL داخل کانتینر mysql (پورت میزبان 3307)

استفاده

• احراز هویت با هدر 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 }

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

• نقطه شروع سرور: src/index.ts (پنل ادمین / و Swagger در /swagger)
• روترها: src/routes/user.routes.ts
• کنترلر استعلام: src/controllers/user.controller.ts
• سرویس توکن جیبیت: src/services/jibit.service.ts
• مدل‌ها (Sequelize): src/models/*
• تنظیمات دیتابیس: src/config/database.ts

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

• users: id, username, domain, host, token, isAdmin, queryCount, timestamps
• persons: id, national, number, matched, userId, timestamps (unique: national+number+userId)
• tokens: id, accessToken, refreshToken, timestamps
• logs: type(incoming|outgoing), method, path, headers, body, response, status, durationMs, ip, userId, targetUrl, timestamps (سقف 85,000)

نکات

• اگر رکورد برای همان host موجود باشد، از کش persons بازگردانده می‌شود.
• در خطای 401/403 جیبیت: ابتدا refresh، درصورت شکست generate مجدد.
• روی خطای یکتا/اعتبار در ذخیره Person، به‌جای خطا، رکورد موجود خوانده و نتیجه بازگردانده می‌شود.