From afa595634eb6147f61fd15550b57e092dfa299f6 Mon Sep 17 00:00:00 2001
From: mobinesaghi <mmoobbiinn1383@gmail.com>
Date: Tue, 21 Oct 2025 18:54:45 +0330
Subject: [PATCH] feat: identity verification

---
 README.md | 105 +++++++++++++++++++++++-------------------------------
 1 file changed, 45 insertions(+), 60 deletions(-)

diff --git a/README.md b/README.md
index b5e5d85..ab3ee63 100644
--- a/README.md
+++ b/README.md
@@ -4,28 +4,56 @@ 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
 ```
 
-سرور روی پورت پیش‌فرض `20205` اجرا می‌شود (قابل تغییر با `PORT`).
+سرور: `http://localhost:20205`
+- پنل ادمین: `/`
+- Swagger: `/swagger`
+- OpenAPI: `/doc`
 
 ## اجرای Docker
 
+1) `.env` را در ریشه پروژه قرار دهید (از بخش بالا)
+
+2) اجرا:
 ```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
+- سرویس اپ: `http://localhost:${PORT}` (پیش‌فرض 20205)
+- سرویس MySQL داخل کانتینر `mysql` (پورت میزبان 3307)
 
 ## استفاده
 
 - احراز هویت با هدر Authorization الزامی است (Bearer token).
-- اگر در body فیلد `host` ارسال شود، درخواست‌ها به نام کاربر همان host ثبت می‌شود؛ اگر وجود نداشته باشد ساخته می‌شود.
+- اگر در body فیلد `host` ارسال شود، کاربر مربوط به host ساخته/یافته شده و استعلام به نام او ثبت می‌شود.
 
 مثال:
 ```bash
@@ -43,64 +71,21 @@ curl --location 'http://localhost:20205/check_user' \
 { "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/index.ts` (پنل ادمین `/` و Swagger در `/swagger`)
 - روترها: `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`
+- مدل‌ها (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)
 
-- 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"
-}'
-```
+## نکات
+- اگر رکورد برای همان host موجود باشد، از کش `persons` بازگردانده می‌شود.
+- در خطای 401/403 جیبیت: ابتدا refresh، درصورت شکست generate مجدد.
+- روی خطای یکتا/اعتبار در ذخیره `Person`، به‌جای خطا، رکورد موجود خوانده و نتیجه بازگردانده می‌شود.