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

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