92 lines
2.9 KiB
Markdown
92 lines
2.9 KiB
Markdown
# سامانه استعلام کد ملی
|
|
|
|
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 در حال اجرا):
|
|
```bash
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
سرور: `http://localhost:20205`
|
|
- پنل ادمین: `/`
|
|
- Swagger: `/swagger`
|
|
- OpenAPI: `/doc`
|
|
|
|
## اجرای Docker
|
|
|
|
1) `.env` را در ریشه پروژه قرار دهید (از بخش بالا)
|
|
|
|
2) اجرا:
|
|
```bash
|
|
docker compose up -d --build
|
|
```
|
|
- سرویس اپ: `http://localhost:${PORT}` (پیش‌فرض 20205)
|
|
- سرویس MySQL داخل کانتینر `mysql` (پورت میزبان 3307)
|
|
|
|
## استفاده
|
|
|
|
- احراز هویت با هدر 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 }
|
|
```
|
|
|
|
## محل کدها و روتر
|
|
- نقطه شروع سرور: `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`، به‌جای خطا، رکورد موجود خوانده و نتیجه بازگردانده می‌شود.
|