commit f50df9d6ada712e36f6b5a78359ae66a10cc4c29
Author: mobinesaghi <mmoobbiinn1383@gmail.com>
Date:   Tue Oct 21 18:47:36 2025 +0330

    first commit

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b5e5d85
--- /dev/null
+++ b/README.md
@@ -0,0 +1,106 @@
+# سامانه استعلام کد ملی
+
+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"
+}'
+```