643 lines
35 KiB
Markdown
643 lines
35 KiB
Markdown
# افزودن پیشوند «آقای/خانم» به نام مشتریان
|
||
|
||
## چرا؟
|
||
|
||
فیلد `Customer.name_family` (همان «نام» مشتری) سال‌ها بدون پیشوند وارد شده:
|
||
`محمد یاوری`، `مریم احمدی`. برای پیامک و گزارش‌ها بهتر است نام با پیشوند
|
||
محترمانه بیاید: `آقای محمد یاوری`، `خانم مریم احمدی`.
|
||
|
||
اما این کار **فقط** وقتی مجاز است که جنسیتِ اولین کلمهٔ نام با اطمینان قابل
|
||
تعیین باشد. فایل `iranianNamesDataset.json` (حدود ۲۰ هزار نام، `M`/`F`) همین
|
||
مرجع است.
|
||
|
||
> **قاعدهٔ بنیادین:** اگر کوچک‌ترین ابهامی در تشخیص جنسیت باشد، **هیچ تغییری
|
||
> اعمال نمی‌شود.** حدس جنسیت، تطبیق تقریبی (fuzzy) و انتخاب تصادفی ممنوع است.
|
||
|
||
مسیرهای اصلی:
|
||
|
||
| جزء | مسیر |
|
||
|---|---|
|
||
| منطق تصمیم (بدون Django) | `admin_panel/name_fix.py` |
|
||
| دستور اجرا | `admin_panel/management/commands/fix_customer_names.py` |
|
||
| مدل وضعیت job | `CustomerNameFixJob` در `admin_panel/models/system.py` |
|
||
| مهاجرت | `admin_panel/migrations/0072_customernamefixjob.py` |
|
||
| تست‌ها | `tests/test_customer_name_fix.py` |
|
||
| فایل داده | `iranianNamesDataset.json` در ریشهٔ پروژه (`/app/iranianNamesDataset.json` در کانتینر) |
|
||
|
||
---
|
||
|
||
## سریع‌ترین مسیر روی Production (خلاصهٔ اجرایی)
|
||
|
||
روی VPS، `python` میزبان وجود ندارد؛ همه‌چیز داخل کانتینر `web` اجرا می‌شود:
|
||
|
||
```bash
|
||
cd /path/to/khatibi
|
||
|
||
# ۱) تأیید وجود فایل داده داخل ایمیج (پیش‌نیاز قطعی این دستور)
|
||
docker compose exec web ls -l /app/iranianNamesDataset.json
|
||
docker compose exec web sha256sum /app/iranianNamesDataset.json
|
||
|
||
# ۲) اعمال migration (فقط این دستور به جدول CustomerNameFixJob نیاز دارد)
|
||
docker compose run --rm migrate
|
||
|
||
# ۳) بکاپ دیتابیس
|
||
docker compose exec web python -c "
|
||
import sqlite3, pathlib, datetime
|
||
src = pathlib.Path('/app/sqlite/db.sqlite3')
|
||
dst = src.parent / f'db_backup_{datetime.datetime.now():%Y%m%d_%H%M%S}.sqlite3'
|
||
s = sqlite3.connect(f'file:{src}?mode=ro', uri=True, timeout=30); d = sqlite3.connect(dst)
|
||
s.backup(d, pages=250, sleep=0.05); d.close(); s.close(); print('backup:', dst)"
|
||
|
||
# ۴) شبیه‌سازی روی دیتابیس واقعی — هیچ نوشتنی ندارد
|
||
docker compose exec web python manage.py fix_customer_names --dry-run --batch-size 200 --samples 5
|
||
|
||
# ۵) اجرای واقعی (هر دو فلگ لازم است)
|
||
docker compose exec web python manage.py fix_customer_names --apply --confirm-production --batch-size 200
|
||
```
|
||
|
||
**چرا این ترتیب؟**
|
||
|
||
| مرحله | چرا |
|
||
|---|---|
|
||
| ۱ | دستور مسیر پیش‌فرض را از `settings.BASE_DIR` می‌سازد. اگر فایل داخل ایمیج نباشد، دستور با «فایل داده پیدا نشد» رد می‌شود. |
|
||
| ۲ | `fix_customer_names` پیش از هر نوشتن، وجود جدول `admin_panel_customernamefixjob` را چک می‌کند و بدون آن خطا می‌دهد. (روی این پروژه `entrypoint.sh` و سرویس `migrate` هم خودشان اجرا می‌کنند، ولی صریح زدن ضرری ندارد.) |
|
||
| ۳ | دستور Undo ندارد؛ برگشت فقط با بکاپ ممکن است. |
|
||
| ۴ | پیش‌فرض بدون نوشتن است؛ اعداد (خصوصاً تعداد قابل‌اصلاح و نام‌های مبهم) را می‌بینی. |
|
||
| ۵ | نوشتن نیازمند تأیید صریح اپراتور است، نه حدس از `DEBUG` یا نام محیط. |
|
||
|
||
### ✅ فایل JSON داخل ایمیج کپی می‌شود (تضمین‌شده)
|
||
|
||
`Dockerfile` حالا **صریحاً** این فایل را کپی می‌کند (خط ۶۳):
|
||
|
||
```dockerfile
|
||
COPY --chown=django:django iranianNamesDataset.json /app/iranianNamesDataset.json
|
||
```
|
||
|
||
یعنی مسیر پیش‌فرض دستور (`settings.BASE_DIR` = `/app`) همیشه داخل ایمیج
|
||
موجود است و به `COPY . .` یا محتوای `.dockerignore` وابسته نیست.
|
||
|
||
**عواقب این انتخاب:**
|
||
|
||
- اگر فایل در build context نباشد، **build شکست می‌خورد** (fail-fast) — این
|
||
رفتار مطلوب است: خطا همان‌جا در CI دیده می‌شود، نه بعداً روی سرور با
|
||
«فایل داده پیدا نشد».
|
||
- روی سرورهای میزبان (VPS/CI) باید فایل در build context حاضر باشد. اگر
|
||
Coolify/CI ایمیج را از **گیت** می‌سازد، فایل باید commit شده باشد (الان
|
||
`git status` آن را `??` نشان می‌دهد، یعنی هنوز track نشده).
|
||
|
||
برای تست سریع بدون commit و بدون rebuild:
|
||
|
||
```bash
|
||
# الف) کپی دستی داخل کانتینر در حال اجرا (تا بازسازی بعدی کانتینر پایدار است)
|
||
docker compose cp iranianNamesDataset.json web:/app/iranianNamesDataset.json
|
||
|
||
# ب) bind-mount از میزبان (فایل هرجا باشد، با هر rebuild هم می‌ماند)
|
||
# docker-compose.override.yml
|
||
# services:
|
||
# web:
|
||
# volumes:
|
||
# - ./iranianNamesDataset.json:/app/iranianNamesDataset.json:ro
|
||
docker compose exec web python manage.py fix_customer_names --dry-run \
|
||
--json-path /app/iranianNamesDataset.json
|
||
```
|
||
|
||
برای تأیید اینکه ایمیج ساخته‌شده واقعاً فایل را دارد:
|
||
|
||
```bash
|
||
docker compose exec web ls -l /app/iranianNamesDataset.json
|
||
docker compose exec web sha256sum /app/iranianNamesDataset.json # باید با hash گزارش دستور یکی باشد
|
||
```
|
||
|
||
> چون jobها با **SHA-256 فایل** شناسایی می‌شوند، فایل باید بایت‌به‌بایت همان
|
||
> چیزی باشد که dry-run دید. اگر فایل را عوض کردی، ادامهٔ job قدیمی رد می‌شود و
|
||
> باید `--new-job` بدهی.
|
||
|
||
### اگر وسط کار قطع شد
|
||
|
||
```bash
|
||
# الف) ادامهٔ خودکار: فقط همان دستور را دوباره بزن.
|
||
# خودش آخرین job ناتمام با همان hash و همان نسخهٔ الگوریتم را پیدا و ادامه می‌دهد.
|
||
docker compose exec web python manage.py fix_customer_names --apply --confirm-production --batch-size 200
|
||
|
||
# ب) ادامهٔ صریح یک job مشخص
|
||
docker compose exec web python manage.py fix_customer_names --apply --confirm-production --resume 3
|
||
|
||
# ج) اگر شمارهٔ job را نمی‌دانی:
|
||
docker compose exec web python manage.py shell -c "
|
||
from admin_panel.models import CustomerNameFixJob as J
|
||
print(list(J.objects.values('id','status','last_processed_pk','initial_max_pk','stats')))"
|
||
```
|
||
|
||
> اگر job قبلی `completed` باشد، اجرای دوباره **خطا می‌دهد** و خودکار job جدید
|
||
> نمی‌سازد (تا داده دوباره دست نخورد). برای اجرای عمدی از صفر: `--new-job`.
|
||
|
||
### بررسی نتیجه
|
||
|
||
```bash
|
||
docker compose exec web python manage.py shell -c "
|
||
from admin_panel.models import Customer
|
||
print('آقای:', Customer.objects.filter(name_family__startswith='آقای ').count())
|
||
print('خانم:', Customer.objects.filter(name_family__startswith='خانم ').count())"
|
||
```
|
||
|
||
---
|
||
|
||
|
||
**فقط** فیلد `name_family` مشتریان واجد شرایط. هیچ فیلدی به مدل مشتری اضافه
|
||
نشده، **هیچ جنسیتی ذخیره نمی‌شود**، و تلفن/آدرس/یادداشت/وضعیت حساب
|
||
دست‌نخورده می‌مانند. جدول `PhoneNumber` هم لمس نمی‌شود.
|
||
|
||
## الگوریتم تصمیم (به همین ترتیب)
|
||
|
||
| # | بررسی | نتیجه |
|
||
|---|---|---|
|
||
| ۱ | نام خالی / فقط فاصله / `NULL` | بدون تغییر |
|
||
| ۲ | اولین کلمه `آقا`، `آقای` یا `خانم` | بدون تغییر (پیشوند تکرار نمی‌شود) |
|
||
| ۳ | نام **تک‌کلمه‌ای** | بدون تغییر (ممکن است فقط فامیل باشد) |
|
||
| ۴ | اولین کلمه در فایل پیدا نشود | بدون تغییر |
|
||
| ۵ | جنسیت اولین کلمه مبهم/نامعتبر باشد | بدون تغییر |
|
||
| ۶ | وگرنه | افزودن قطعی پیشوند |
|
||
|
||
جست‌وجو **فقط** روی اولین کلمه انجام می‌شود؛ از فامیل و کلمات بعدی برای حدس
|
||
استفاده نمی‌شود.
|
||
|
||
### نمونه‌های رفتاری
|
||
|
||
| مقدار فعلی | نتیجه |
|
||
|---|---|
|
||
| `محمد یاوری` | `آقای محمد یاوری` |
|
||
| `مریم احمدی` | `خانم مریم احمدی` |
|
||
| `یاوری` | بدون تغییر — تک‌کلمه‌ای |
|
||
| `محمد` | بدون تغییر — تک‌کلمه‌ای |
|
||
| `آقا محمد یاوری` | بدون تغییر |
|
||
| `آقای محمد یاوری` | بدون تغییر |
|
||
| `خانم مریم احمدی` | بدون تغییر |
|
||
| `نام ناشناخته احمدی` | بدون تغییر — ناشناخته |
|
||
| `آرش محمدی` | بدون تغییر — جنسیت متناقض در فایل |
|
||
| ` محمد یاوری ` | `آقای محمد یاوری` (فاصله‌های سر/ته فقط در این حالت حذف می‌شوند) |
|
||
| ` نام ناشناخته احمدی ` | بدون تغییر، **با حفظ فاصله‌های اصلی** |
|
||
|
||
نکته: حذف فاصله‌های سر/ته به‌تنهایی هیچ‌وقت باعث تغییر نمی‌شود؛ فقط وقتی
|
||
تصمیم قطعی به افزودن پیشوند گرفته شد، خروجی از نام `strip()`شده ساخته می‌شود.
|
||
فاصله‌های **داخلی** دست‌نخورده می‌مانند (`محمد یاوری` → `آقای محمد یاوری`).
|
||
|
||
### نرمال‌سازی (فقط برای کلید جست‌وجو)
|
||
|
||
`NFC` + حذف فاصلهٔ سر/ته + یکسان‌سازی `ي→ی` و `ك→ک`. مقدارِ ذخیره‌شدهٔ مشتری
|
||
حرف‌به‌حرف همان مقدار اصلی است (`علي رضایی` → `آقای علي رضایی`).
|
||
|
||
### برخورد با نام‌های تکراری و متناقض
|
||
|
||
یک نام فقط وقتی قابل استفاده است که **همهٔ** رکوردهای همان کلید نرمال‌شده
|
||
جنسیت معتبر (`M`/`F`) و **یکسان** داشته باشند:
|
||
|
||
| وضعیت در فایل | تصمیم |
|
||
|---|---|
|
||
| چند رکورد، همه `M` یا همه `F` | قابل استفاده |
|
||
| همان نام هم `M` هم `F` | **مبهم** ⇒ بدون تغییر |
|
||
| جنسیت ناشناخته (`D`، `MF`، `FF`، خالی) | **غیرقابل استفاده** ⇒ بدون تغییر |
|
||
| رکورد ناقص/`Names` غیر رشته/نام خالی | رد می‌شود؛ کل آن نام کنار گذاشته می‌شود |
|
||
| یکی‌شدن دو کلید با جنسیت متناقض پس از نرمال‌سازی | **مبهم** ⇒ بدون تغییر |
|
||
|
||
«اولین رکورد» یا «پرتکرارترین جنسیت» بدون دلیل معتبر انتخاب نمی‌شود؛ تناقض
|
||
یعنی نام کنار گذاشته می‌شود.
|
||
|
||
وضعیت فایل دادهٔ فعلی پروژه:
|
||
|
||
```
|
||
SHA-256: f5953a216a0b71e59e20249f5bfa6a380a2c3179c6b15e4f0e60616b94948114
|
||
رکورد کل: 19881 | کلید قابل‌استفاده: 19870 | کلید غیرقابل‌استفاده: 5
|
||
جنسیت نامعتبر: 5 (فروزان/فروزن/فروزنده = D، گوهربانو = FF، مهروز = MF)
|
||
نام تکراری: 6، همه هم‌جنسیت (بدون تناقض)
|
||
```
|
||
|
||
## گزینه‌های دستور
|
||
|
||
| گزینه | پیش‌فرض | کار |
|
||
|---|---|---|
|
||
| `--json-path` | `iranianNamesDataset.json` در ریشهٔ پروژه | مسیر فایل داده |
|
||
| `--batch-size` | `200` | تعداد مشتری در هر batch |
|
||
| `--dry-run` | خاموش (اما **رفتار پیش‌فرض همین است**) | گزارش بدون هیچ نوشتنی؛ همراه `--apply` ناسازگار است |
|
||
| `--apply` | خاموش | نوشتن واقعی؛ بدون آن اجرا فقط گزارش است |
|
||
| `--confirm-production` | خاموش | تأیید صریح اپراتور؛ همراه `--apply` **الزامی** |
|
||
| `--resume <JOB_ID>` | — | ادامهٔ یک job مشخص |
|
||
| `--new-job` | خاموش | شروع عمدی job جدید، حتی اگر job تکمیل‌شده‌ای برای همین فایل باشد |
|
||
| `--samples` | `5` | تعداد نمونهٔ «قبل/بعد» در گزارش |
|
||
|
||
**پیش‌فرض دستور بدون نوشتن است.** هیچ‌کدام از این‌ها تغییر نمی‌دهند: نام مشتری،
|
||
رکورد job، ساختار دیتابیس، فایل JSON. حتی migration هم خودکار اجرا نمی‌شود.
|
||
|
||
## اجرای محلی (توسعه)
|
||
|
||
### ۱) اول همیشه شبیه‌سازی
|
||
|
||
از WSL:
|
||
|
||
```bash
|
||
cd /mnt/d/projects/khatibi
|
||
.venv/Scripts/python.exe manage.py fix_customer_names --dry-run --samples 5
|
||
```
|
||
|
||
از Windows (PowerShell / CMD):
|
||
|
||
```bat
|
||
cd D:\projects\khatibi
|
||
.venv\Scripts\python.exe manage.py fix_customer_names --dry-run --samples 5
|
||
```
|
||
|
||
خروجی نمونه (دادهٔ واقعی همین پروژه، ۱۰٬۴۲۶ مشتری):
|
||
|
||
```
|
||
مقصد دیتابیس: alias=default engine=django.db.backends.sqlite3
|
||
NAME: D:\Projects\khatibi\data9\kt.sqlite3
|
||
(فقط نام/مسیر دیتابیس چاپ می‌شود؛ credential چاپ نمی‌شود.)
|
||
اعتبارسنجی فایل داده
|
||
مسیر: D:\Projects\khatibi\iranianNamesDataset.json
|
||
SHA-256: f5953a21…
|
||
رکورد کل: 19881 | کلید قابل‌استفاده: 19870 | کلید غیرقابل‌استفاده: 5
|
||
ردشده → malformed: 0 | نام خالی: 0 | جنسیت نامعتبر: 5
|
||
نام تکراری: 6 (هم‌جنسیت: 6 | متناقض: 0)
|
||
گزارش dry-run — هیچ تغییری نوشته نشد
|
||
مشتریان بررسی‌شده: 10426
|
||
قابل اصلاح / اصلاح‌شده: 7303
|
||
بدون تغییر: 3123
|
||
تک‌کلمه‌ای: 1576 | دارای پیشوند: 89 | خالی/نامعتبر: 0
|
||
ناشناخته در JSON: 1457 | جنسیت مبهم/نامعتبر: 1
|
||
batchهای تکمیل‌شده: 53
|
||
نمونهٔ تغییرات (قبل → بعد):
|
||
«مجتبی سالاری» → «آقای مجتبی سالاری»
|
||
«مرتضی محمد باقری » → «آقای مرتضی محمد باقری»
|
||
«محمد فصاحت » → «آقای محمد فصاحت»
|
||
برای اجرای واقعی: --apply --confirm-production
|
||
```
|
||
|
||
### ۲) اجرای واقعی (فقط روی مقصد دلخواه)
|
||
|
||
```bash
|
||
.venv/Scripts/python.exe manage.py fix_customer_names --apply --confirm-production
|
||
```
|
||
|
||
بدون `--confirm-production`:
|
||
|
||
```
|
||
CommandError: برای نوشتن واقعی، هم --apply و هم --confirm-production لازم است.
|
||
```
|
||
|
||
## اجرا روی سرور Production
|
||
|
||
**پیش‌نیاز: migration باید اعمال شده باشد.** روی این پروژه migration سرویس وب
|
||
خودکار اجرا می‌شود (`entrypoint.sh` و سرویس `migrate` در `docker-compose.yml`)،
|
||
ولی برای اطمینان:
|
||
|
||
```bash
|
||
docker compose run --rm migrate # یا: python manage.py migrate
|
||
```
|
||
|
||
اگر جدول job نباشد، دستور **پیش از هر تغییری** خطا می‌دهد و هیچ نامی را
|
||
تغییر نمی‌دهد:
|
||
|
||
```
|
||
CommandError: جدول «admin_panel_customernamefixjob» وجود ندارد.
|
||
ابتدا migration را اعمال کن: python manage.py migrate
|
||
```
|
||
|
||
### ترتیب دقیق اجرا
|
||
|
||
خلاصهٔ اجرایی و کامل این ترتیب در بخش
|
||
**«سریع‌ترین مسیر روی Production»** بالای همین سند آمده؛ این همان نسخهٔ
|
||
جزئی‌تر با تأکید بر فایل داده:
|
||
|
||
```bash
|
||
# ۰) فایل داده داخل کانتینر — تأیید وجود و هش
|
||
docker compose exec web ls -l /app/iranianNamesDataset.json
|
||
docker compose exec web sha256sum /app/iranianNamesDataset.json
|
||
|
||
# ۱) اعمال migration (لازم؛ جدول CustomerNameFixJob را می‌سازد)
|
||
docker compose run --rm migrate
|
||
|
||
# ۲) بکاپ دیتابیس (بخش «بکاپ پیش از اجرای واقعی» را ببین)
|
||
docker compose exec web python manage.py sqlite_db_backup # نیازمند env های S3
|
||
# اگر S3 تنظیم نیست، اسنیپت WAL-safe بخش «سریع‌ترین مسیر» را بزن.
|
||
|
||
# ۳) شبیه‌سازی روی دیتابیس واقعی — هیچ نوشتنی ندارد
|
||
docker compose exec web python manage.py fix_customer_names --dry-run --batch-size 200 --samples 5
|
||
|
||
# ۴) اگر اعداد منطقی بود: اجرای واقعی
|
||
docker compose exec web python manage.py fix_customer_names --apply --confirm-production --batch-size 200
|
||
|
||
# ۵) بررسی خلاصه و وضعیت job
|
||
docker compose exec web python manage.py shell -c "from admin_panel.models import CustomerNameFixJob as J; print(list(J.objects.values('id','status','source_hash','last_processed_pk','initial_max_pk','stats')))"
|
||
```
|
||
|
||
> **چرا `docker compose exec web` و نه `python manage.py`؟** روی VPS پایتون
|
||
> پروژه فقط داخل کانتینر است و دیتابیس هم در ولوم `/app/sqlite` همان کانتینر
|
||
> قرار دارد. اجرای `python manage.py` روی میزبان یا به دیتابیس اشتباه وصل
|
||
> می‌شود یا اصلاً وجود ندارد.
|
||
|
||
|
||
### اطمینان از انتخاب دیتابیس درست
|
||
|
||
دستور از تنظیمات فعال Django (`DJANGO_SETTINGS_MODULE`) استفاده می‌کند و هیچ
|
||
مسیر SQLite ای هاردکد نشده است. پیش از هر کاری، alias + engine + مسیر دیتابیس
|
||
را چاپ می‌کند (بدون credential):
|
||
|
||
```
|
||
مقصد دیتابیس: alias=default engine=django.db.backends.sqlite3
|
||
NAME: /app/sqlite/db.sqlite3
|
||
توجه: ماژول تنظیمات production فعال است.
|
||
```
|
||
|
||
- روی سرور، `DJANGO_SETTINGS_MODULE=khatibi.production_settings` و
|
||
`NAME=/app/sqlite/db.sqlite3` (ولوم `khatibi-sqlite-db` در کانتینر) است.
|
||
- در توسعه، `khatibi.settings` و `data9/kt.sqlite3`.
|
||
- اگر مسیر چاپ‌شده همان چیزی نیست که انتظار داری، **همان‌جا `Ctrl+C` بزن**؛
|
||
هیچ داده‌ای تا آن لحظه نوشته نشده است.
|
||
- تشخیص production بر پایهٔ نام ماژول تنظیمات است، نه `DEBUG`. (در این پروژه
|
||
`production_settings.py` مقدار `DEBUG=True` دارد؛ پس اتکا به `DEBUG` غلط بود و
|
||
عمداً از آن استفاده نشده.)
|
||
|
||
## بکاپ پیش از اجرای واقعی
|
||
|
||
دستور آمادهٔ همین پروژه روی سرور (لینوکس/کانتینر): `sqlite_db_backup` — از متد
|
||
بومی SQLite (`Connection.backup`) با اتصال `mode=ro` استفاده می‌کند و بنابراین با
|
||
حالت WAL سازگار است. دو شرط دارد: فقط روی لینوکس اجرا می‌شود (`fcntl`) و
|
||
متغیرهای S3 را لازم دارد (`S3_ACCESS_KEY`, `S3_SECRET_KEY`, `S3_ENDPOINT`,
|
||
`S3_BUCKET`).
|
||
|
||
```bash
|
||
# داخل کانتینر (لینوکس) — نتیجه در S3 ذخیره و اعتبارسنجی می‌شود
|
||
docker compose exec web python manage.py sqlite_db_backup
|
||
```
|
||
|
||
اگر S3 در دسترس نیست یا روی ویندوز/WSL کار می‌کنی، همین بکاپ WAL-safe را
|
||
مستقیم بگیر (همه‌جا کار می‌کند و به env نیاز ندارد):
|
||
|
||
```bash
|
||
# WSL
|
||
.venv/Scripts/python.exe - <<'PY'
|
||
import sqlite3, pathlib, datetime
|
||
src = pathlib.Path('data9/kt.sqlite3')
|
||
dst = src.parent / f"db_backup_{datetime.datetime.now():%Y%m%d_%H%M%S}.sqlite3"
|
||
s = sqlite3.connect(f"file:{src}?mode=ro", uri=True, timeout=30)
|
||
d = sqlite3.connect(dst)
|
||
s.backup(d, pages=250, sleep=0.05) # کپی سطح C، سازگار با WAL
|
||
d.close(); s.close()
|
||
print("backup:", dst, dst.stat().st_size, "bytes")
|
||
PY
|
||
```
|
||
|
||
> **کپی سادهٔ فایل SQLite در حین اجرای برنامه بکاپ معتبر نیست.** دیتابیس در حالت
|
||
> `WAL` اجرا می‌شود (`entrypoint.sh`)؛ اگر فقط `db.sqlite3` را `cp` کنی،
|
||
> تراکنش‌های موجود در `db.sqlite3-wal` از دست می‌روند و ممکن است فایل خراب
|
||
> بازیابی شود. اگر دستی بکاپ می‌گیری، باید **هر سه فایل** (`db.sqlite3`،
|
||
> `-wal`، `-shm`) در لحظهٔ بدون نوشتن کپی شوند — و بهترین راه همان
|
||
> `sqlite3.Connection.backup` بالا است.
|
||
|
||
نکات مکمل:
|
||
|
||
- فضای دیسک: قبل از بکاپ حداقل ~۱.۵ برابر حجم دیتابیس خالی باشد
|
||
(دیتابیس فعلی ≈۷۹ مگابایت).
|
||
- وضعیت WAL: `PRAGMA journal_mode;` باید `wal` برگرداند.
|
||
- دسترسی فایل: کاربر اجراکنندهٔ کانتینر باید روی `/app/sqlite` و روی فایل JSON
|
||
دسترسی خواندن/نوشتن داشته باشد.
|
||
- فایل `iranianNamesDataset.json` **هرگز** تغییر داده، بازنویسی یا حذف نمی‌شود؛
|
||
دستور فقط آن را می‌خواند.
|
||
|
||
## ادامهٔ job پس از crash / قطع برق
|
||
|
||
هر batch شامل سه چیز است که **در یک تراکنش اتمیک** ثبت می‌شوند:
|
||
|
||
1. تغییرات `name_family` مشتریان واجد شرایط همان batch،
|
||
2. `last_processed_pk` (checkpoint)،
|
||
3. `heartbeat_at` و آمار تجمیعی.
|
||
|
||
پس یا کل batch ثبت شده یا هیچ‌کدام. دامنهٔ job در لحظهٔ آغاز با بزرگ‌ترین
|
||
primary key مشتریان قفل می‌شود (`initial_max_pk`)؛ مشتریان جدیدتر وارد دامنه
|
||
نمی‌شوند.
|
||
|
||
### گزینه‌های ادامه
|
||
|
||
| وضعیت | رفتار پیش‌فرض | راه‌حل |
|
||
|---|---|---|
|
||
| job ناتمام با همان فایل و همان نسخهٔ الگوریتم | **خودکار ادامه می‌یابد** | فقط همان دستور `--apply --confirm-production` را دوباره بزن |
|
||
| می‌خواهی صریحاً همان job را ادامه دهی | — | `--apply --confirm-production --resume <JOB_ID>` |
|
||
| job قبلی `completed` است | خطا؛ خودکار job جدید نمی‌سازد | `--apply --confirm-production --new-job` |
|
||
| فایل عوض شده (hash متفاوت) | **توقف، بدون هیچ تغییری** | `--new-job` با فایل جدید |
|
||
| نسخهٔ الگوریتم عوض شده | **توقف** | `--new-job` |
|
||
|
||
پیام خطاهای مربوطه:
|
||
|
||
```
|
||
CommandError: hash فایل ورودی با job#3 نمی‌خواند؛ ادامه رد شد و هیچ تغییری اعمال نمی‌شود.
|
||
CommandError: job#3 قبلاً تکمیل شده است؛ برای اجرای دوباره --new-job بده.
|
||
CommandError: job#3 همین حالا در حال اجراست (heartbeat تازه). اجرای هم‌زمان مجاز نیست.
|
||
```
|
||
|
||
### دستورهای دقیق ادامه / شروع مجدد
|
||
|
||
```bash
|
||
# ادامهٔ خودکار آخرین job ناتمامِ همین فایل (ساده‌ترین راه)
|
||
python manage.py fix_customer_names --apply --confirm-production
|
||
|
||
# ادامهٔ صریح یک job مشخص
|
||
python manage.py fix_customer_names --apply --confirm-production --resume 3
|
||
|
||
# شروع عمدی job جدید (پس از تکمیل job قبلی یا با فایل جدید)
|
||
python manage.py fix_customer_names --apply --confirm-production --new-job
|
||
|
||
# شروع job جدید با فایل دیگر و حجم batch کوچک‌تر (ساعات پرترافیک)
|
||
python manage.py fix_customer_names --apply --confirm-production --new-job \
|
||
--json-path /app/data/iranianNamesDataset_v2.json --batch-size 50
|
||
```
|
||
|
||
اجرای دوبارهٔ بی‌خطر: با `--new-job` روی دادهٔ اصلاح‌شده، `changed = 0` می‌شود،
|
||
چون نام‌های دارای پیشوند دیگر رد می‌شوند.
|
||
|
||
## قفل و اجرای هم‌زمان
|
||
|
||
- جلوگیری از اجرای هم‌زمان با **heartbeat** انجام می‌شود، نه `select_for_update()`.
|
||
(روی SQLite قفل ردیفی واقعی وجود ندارد؛ اتکا به `select_for_update` گمراه‌کننده بود.)
|
||
- هر batch مقدار `heartbeat_at` را به‌روز می‌کند. jobی که `status=running` دارد و
|
||
heartbeat آن تازه است (< `LOCK_TTL = 15 دقیقه`)، اجرای دوم را مسدود می‌کند.
|
||
- اگر سرور وسط کار خاموش شود، heartbeat کهنه می‌ماند و اجرای بعدی قفل را
|
||
**به‌صورت کنترل‌شده آزاد می‌کند** و به‌عنوان `failed` علامت می‌زند:
|
||
|
||
```
|
||
job#1 ناتمام رها شده بود و اکنون به‌عنوان failed آزاد شد.
|
||
```
|
||
|
||
پس از آن، همان دستور از `last_processed_pk` ادامه می‌دهد. قفل، دائمی نمی‌شود.
|
||
|
||
## SQLite، قفل دیتابیس و بار روی سایت
|
||
|
||
- batchهای کوچک (`--batch-size 200`) با تراکنش‌های کوتاه؛ هیچ تراکنش واحدی روی
|
||
۱۰٬۴۲۶ مشتری ساخته نمی‌شود.
|
||
- خطای `database is locked`: بازآزمایی حداکثر `4` بار با backoff نمایی
|
||
(۰.۵s، ۱s، ۲s) به‌همراه jitter. **retry نامحدود وجود ندارد.**
|
||
- خطاهای غیرقابل‌بازیابی فوراً بالا می‌آیند؛ batch جاری rollback می‌شود،
|
||
checkpoint جلو نمی‌رود و job با `failed` ثبت می‌شود.
|
||
- `PRAGMA busy_timeout=30000` موجود (در `admin_panel/signals.py`) دست‌نخورده است.
|
||
`journal_mode=WAL` و `synchronous=FULL` هم تغییر داده نشده‌اند.
|
||
- **محدودیت باقی‌مانده:** SQLite در هر لحظه فقط یک نویسنده دارد. بهتر است دستور
|
||
را در ساعات کم‌ترافیک اجرا کنی؛ اگر web/worker هم‌زمان بنویسند، ممکن است
|
||
چند batch با backoff کندتر شوند (نه خطا). سایت متوقف نمی‌شود.
|
||
|
||
|
||
## مدل وضعیت job
|
||
|
||
`CustomerNameFixJob` — **فقط** وضعیت و checkpoint. هیچ اطلاعاتی از جنسیت یا هویت
|
||
مشتری در آن ذخیره نمی‌شود.
|
||
|
||
| فیلد | معنا |
|
||
|---|---|
|
||
| `source_hash` | SHA-256 فایل ورودی؛ مبنای تشخیص «همان فایل» |
|
||
| `algorithm_version` | نسخهٔ الگوریتم تصمیم (`ALGORITHM_VERSION`) |
|
||
| `status` | `running` / `paused` / `completed` / `failed` |
|
||
| `batch_size` | اندازهٔ batch هنگام آغاز |
|
||
| `initial_max_pk` | سقف دامنه (بیشترین pk مشتریان در آغاز) |
|
||
| `last_processed_pk` | checkpoint؛ آخرین pk پردازش‌شده |
|
||
| `stats` | آمار تجمیعی (JSON) |
|
||
| `note` | توضیح وضعیت/خطا |
|
||
| `started_at` / `updated_at` / `finished_at` / `heartbeat_at` | زمان‌ها |
|
||
|
||
شرط خواندن هر batch: `last_processed_pk < pk <= initial_max_pk`، مرتب بر اساس
|
||
`pk`. هیچ‌وقت از offset یا شمارهٔ ردیف استفاده نمی‌شود (offset با افزودن/حذف
|
||
رکورد جابه‌جا می‌شود و باعث پرش/تکرار می‌شود).
|
||
|
||
## بکاپ/بازیابی خودکار نیست
|
||
|
||
دستور بکاپ نمی‌گیرد و تغییرات را «undo» نمی‌کند. برای برگشت، بکاپِ قبل از اجرا
|
||
را بازیابی کن:
|
||
|
||
```bash
|
||
# ۱) توقف سرویس‌هایی که می‌نویسند
|
||
docker compose stop web worker scheduler delivery
|
||
|
||
# ۲) جایگزینی فایل دیتابیس در ولوم، با پاک کردن WAL/SHM قدیمی
|
||
docker run --rm \
|
||
-v khatibi-sqlite-db:/data \
|
||
-v "$(pwd)":/backup \
|
||
alpine sh -c "cp /backup/db_backup_YYYYmmdd_HHMMSS.sqlite3 /data/db.sqlite3 \
|
||
&& rm -f /data/db.sqlite3-wal /data/db.sqlite3-shm"
|
||
|
||
# ۳) بالا آوردن دوباره (سرویس migrate اول اجرا می‌شود)
|
||
docker compose start migrate web worker scheduler delivery
|
||
```
|
||
|
||
اگر از `sqlite_db_backup` استفاده کرده‌ای، فایل بکاپ در S3 است؛ اول آن را با
|
||
`aws s3 cp`/کلاینت S3 دانلود کن و بعد مراحل بالا را اجرا کن.
|
||
|
||
## خطاهای رایج و اقدام درست
|
||
|
||
| خطا | معنا | اقدام |
|
||
|---|---|---|
|
||
| `فایل داده پیدا نشد: …` | مسیر `--json-path` غلط | مسیر را با `ls` تأیید کن |
|
||
| `JSON نامعتبر است: …` | فایل خراب است | هیچ تغییری اعمال نشد؛ فایل درست را بگذار |
|
||
| `کلید «RECORDS» در فایل JSON وجود ندارد` | ساختار فایل عوض شده | فایل را اصلاح کن — **هیچ نامی تغییر نمی‌کند** |
|
||
| `جدول … وجود ندارد` | migration اعمال نشده | `python manage.py migrate` |
|
||
| `hash فایل ورودی … نمی‌خواند` | فایل عوض شده | یا فایل قبلی را برگردان، یا `--new-job` |
|
||
| `همین حالا در حال اجراست` | یک اجرای دیگر فعال است | صبر کن یا `--resume` همان job را بده |
|
||
| `database is locked` (پس از ۴ تلاش) | فشار نوشتن هم‌زمان | دوباره اجرا کن؛ از checkpoint ادامه می‌دهد |
|
||
| `برای نوشتن واقعی، هم --apply و هم --confirm-production لازم است` | تأیید ناقص | هر دو گزینه را بده |
|
||
|
||
## بررسی صحت داده (SQL، پیش از/پس از اجرا)
|
||
|
||
```sql
|
||
-- وضعیت jobها
|
||
SELECT id, status, source_hash, last_processed_pk, initial_max_pk,
|
||
started_at, finished_at
|
||
FROM admin_panel_customernamefixjob ORDER BY id;
|
||
|
||
-- مشتریانی که پیشوند ندارند ولی نامشان چندکلمه‌ای است (کاندید بالقوه)
|
||
SELECT COUNT(*) FROM admin_panel_customer
|
||
WHERE TRIM(name_family) LIKE '% %'
|
||
AND name_family NOT LIKE 'آقا %'
|
||
AND name_family NOT LIKE 'آقای %'
|
||
AND name_family NOT LIKE 'خانم %';
|
||
|
||
-- تعدادی که پیشوند گرفته‌اند (نتیجهٔ اجرای واقعی)
|
||
SELECT COUNT(*) FROM admin_panel_customer WHERE name_family LIKE 'آقای %';
|
||
SELECT COUNT(*) FROM admin_panel_customer WHERE name_family LIKE 'خانم %';
|
||
```
|
||
|
||
## تست‌ها
|
||
|
||
```bash
|
||
.venv/Scripts/python.exe manage.py test tests.test_customer_name_fix # ۳۰ تست
|
||
.venv/Scripts/python.exe manage.py test tests # کل مجموعه
|
||
.venv/Scripts/python.exe manage.py makemigrations --check --dry-run # باید «No changes detected» بدهد
|
||
```
|
||
|
||
تست‌ها فقط روی دیتابیس تستی Django (SQLite درون‌حافظه) و با فایل JSON ساختگیِ
|
||
موقت اجرا می‌شوند؛ نه به `data9/kt.sqlite3` دست می‌زنند و نه به فایل دادهٔ واقعی.
|
||
|
||
## نکته‌ها و محدودیت‌ها
|
||
|
||
- **نام تک‌کلمه‌ای هیچ‌وقت تغییر نمی‌کند** — حتی اگر در فایل با جنسیت قطعی
|
||
باشد؛ چون ممکن است فقط فامیل باشد.
|
||
- **حرف اضافه/کم کردن ممنوع است:** نه fuzzy matching، نه حذف حروف، نه حدس از
|
||
فامیل، نه انتخاب تصادفی جنسیت.
|
||
- نام‌های دارای پیشوند **دوباره** پیشوند نمی‌گیرند (idempotent).
|
||
- دستور `save()` کامل صدا نمی‌زند؛ روی `Customer` سیگنال و منطق اجباری در
|
||
`save()` وجود ندارد، پس `bulk_update(['name_family'])` امن است و فقط همان
|
||
یک ستون را می‌نویسد (فیلدهای `auto_now_add` مثل `create_date` لمس نمی‌شوند).
|
||
- منطق روی `name_family` اجرا می‌شود، نه `name` — این نام واقعی فیلد در این
|
||
پروژه است.
|
||
- ۵ نام موجود در فایل جنسیت نامعتبر دارند (`D`/`FF`/`MF`) و عمداً کنار گذاشته
|
||
می‌شوند؛ مشتریانی با آن نام‌ها بدون پیشوند می‌مانند.
|
||
- نام‌هایی که در فایل نیستند (۱۴۵۷ مورد در دادهٔ فعلی) پیشوند نمی‌گیرند. اگر
|
||
بعداً فایل کامل‌تری آمد، با `--json-path` فایل جدید و `--new-job` می‌توان
|
||
دور تازه‌ای اجرا کرد.
|
||
- برای تغییر قواعد تصمیم یا نرمال‌سازی، `ALGORITHM_VERSION` در
|
||
`admin_panel/name_fix.py` را بالا ببر تا jobهای قدیمی ناخواسته ادامه داده
|
||
نشوند.
|
||
- کنسول ویندوز: متن فارسی در خروجی ممکن است `charmap` خطا بدهد؛ مثل بقیهٔ
|
||
سرویس‌های پروژه از `python -X utf8 manage.py …` استفاده کن.
|
||
|
||
|
||
## چک‌لیست سریع (کپی/پیست)
|
||
|
||
```bash
|
||
# ── توسعه (WSL) ──────────────────────────────────────────────
|
||
.venv/Scripts/python.exe manage.py test tests.test_customer_name_fix
|
||
.venv/Scripts/python.exe manage.py fix_customer_names --dry-run --samples 5
|
||
|
||
# ── Production ───────────────────────────────────────────────
|
||
docker compose run --rm migrate # ۱) مهاجرت
|
||
docker compose exec web python manage.py sqlite_db_backup # ۲) بکاپ
|
||
docker compose exec web python manage.py fix_customer_names --dry-run --samples 10
|
||
docker compose exec web python manage.py fix_customer_names --apply --confirm-production
|
||
docker compose exec web python manage.py fix_customer_names --apply --confirm-production --resume <JOB_ID>
|
||
```
|
||
|
||
گزارش نهایی یک اجرای واقعی:
|
||
|
||
```
|
||
گزارش اجرای واقعی job#1 (completed)
|
||
مشتریان بررسی‌شده: 10426
|
||
قابل اصلاح / اصلاح‌شده: 7303
|
||
بدون تغییر: 3123
|
||
تک‌کلمه‌ای: 1576 | دارای پیشوند: 89 | خالی/نامعتبر: 0
|
||
ناشناخته در JSON: 1457 | جنسیت مبهم/نامعتبر: 1
|
||
batchهای تکمیل‌شده: 53
|
||
شناسهٔ job: 1 | شروع: … | پایان: …
|
||
نمونهٔ تغییرات (قبل → بعد):
|
||
«مجتبی سالاری» → «آقای مجتبی سالاری»
|
||
```
|
||
|
||
### تعریف کلیدهای آماری
|
||
|
||
| کلید | معنا |
|
||
|---|---|
|
||
| `scanned` | کل مشتریان بررسی‌شده در دامنهٔ job |
|
||
| `changed` | نام‌هایی که پیشوند گرفتند (یا در dry-run، می‌گیرند) |
|
||
| `unchanged` | `scanned - changed` |
|
||
| `single_word` | تک‌کلمه‌ای ⇒ دست‌نخورده |
|
||
| `has_prefix` | از قبل `آقا`/`آقای`/`خانم` ⇒ دست‌نخورده |
|
||
| `empty_invalid` | خالی/فقط فاصله ⇒ دست‌نخورده |
|
||
| `unknown_name` | اولین کلمه در فایل نیست ⇒ دست‌نخورده |
|
||
| `ambiguous_gender` | جنسیت متناقض/نامعتبر ⇒ دست‌نخورده |
|
||
| `batches` | تعداد batchهای commitشده |
|
||
|
||
|