107 lines
3.9 KiB
Markdown
107 lines
3.9 KiB
Markdown
# سامانه استعلام کد ملی
|
|
|
|
API با Hono + Zod + OpenAPI + MySQL + Docker
|
|
|
|
## نصب و اجرا (Local)
|
|
|
|
```bash
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
سرور روی پورت پیش‌فرض `20205` اجرا می‌شود (قابل تغییر با `PORT`).
|
|
|
|
## اجرای Docker
|
|
|
|
```bash
|
|
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 ثبت می‌شود؛ اگر وجود نداشته باشد ساخته می‌شود.
|
|
|
|
مثال:
|
|
```bash
|
|
curl --location 'http://localhost:20205/check_user' \
|
|
--header 'Authorization: Bearer admin-token' \
|
|
--header 'Content-Type: application/json' \
|
|
--data '{
|
|
"number": "09372281182",
|
|
"national": "1274467144",
|
|
"host": "golak"
|
|
}'
|
|
```
|
|
پاسخ:
|
|
```json
|
|
{ "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.
|
|
|
|
## تست سریع
|
|
|
|
```bash
|
|
curl --location 'http://localhost:20205/check_user' \
|
|
--header 'Authorization: Bearer admin-token' \
|
|
--header 'Content-Type: application/json' \
|
|
--data '{
|
|
"number": "09372281182",
|
|
"national": "1274467144",
|
|
"host": "golak"
|
|
}'
|
|
```
|