Watch
1
0
Fork
You've already forked arc
0
forked from hesabix/arc
arc/docs/barcode_label_studio/BARCODE_LABEL_STUDIO.md

785 lines
31 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# استودیوی طراحی و چاپ برچسب بارکد حسابیکس
> **وضعیت سند:** زنده (Living Document) — پس از هر مرحله طراحی/پیاده‌سازی به‌روز می‌شود.
> **تاریخ ایجاد:** ۲۰۲۶-۰۸-۰۶
> **آخرین به‌روزرسانی:** ۲۰۲۶-۰۸-۰۶
> **کد افزونه:** `barcode_label_studio`
> **دسته marketplace:** `product_management`
---
## ۰) فهرست پیشرفت کلی
| فاز | عنوان | طراحی | پیاده‌سازی | تست/پذیرش |
|-----|--------|:-----:|:----------:|:---------:|
| — | سناریوی محصول و قواعد کسب‌وکار | ✅ | — | — |
| A | ستون فقرات (مدل، API، رندر PDF، گیت افزونه) | ✅ | ✅ | ❌ |
| B | استودیو WYSIWYG (canvas، DnD، کیبورد، اسکیل) | ✅ | ✅ | ❌ |
| C | اتصال عملیات (کالاها، چاپ گروهی، اکسل، سریال) | ✅ | ✅ | ❌ |
| D | چاپ پیشرفته سیستم و رولی | ✅ | ✅ | ❌ |
**راهنمای علائم:** ✅ انجام شده · 🟡 در حال انجام · ❌ نشده · — موضوعیت ندارد
جزئیات چک‌لیست هر فاز در بخش همان فاز آمده است.
---
## ۱) خلاصه اجرایی
افزونهٔ **طراحی و چاپ برچسب بارکد** یک محصول کامل داخل حسابیکس است که:
1. محیط **استودیوی حرفه‌ای** با موس و کیبورد برای طراحی برچسب دارد.
2. امکان تعریف **چند طرح** برای هر کسب‌وکار، انتخاب **طرح پیش‌فرض**، و **انتخاب طرح موقع چاپ** را می‌دهد.
3. با بخش **کالاها و خدمات** هماهنگ است.
4. خروجی استاندارد همه پلتفرم‌ها **PDF با مختصات میلی‌متر واقعی** است.
5. چاپ مستقیم سیستم/رولی لایهٔ جدا (فاز D) است و شرط تکمیل فازهای A–C نیست.
چاپ سادهٔ فعلی کالاها (Code128/QR، ذخیره PDF) به‌عنوان قابلیت **هستهٔ رایگان** باقی می‌ماند. امکانات استودیو، چندطرح، اکسل سریالی و چاپ پیشرفته پشت لایسنس افزونه قرار می‌گیرند.
---
## ۲) وضعیت فعلی حسابیکس (مبنای کار)
### موجود
| بخش | مسیر/نکته |
|-----|-----------|
| چاپ برچسب ساده کالا | `hesabixUI/.../product_label_print_dialog.dart` — کلاینت PDF، بدون قالب ذخیره‌شونده |
| ورود از کالاها | `products_page.dart` — چاپ بارکد عمومی و برچسب واحد یونیک |
| مدل بارکد کالا | `general_barcodes` + بارکد/سریال `product_instances` |
| الگوی افزونه | `marketplace_plugins_seed.py` + `BusinessPlugin` + `*PluginGate` |
| الگوی قالب چاپ | `report_templates` (draft/publish/default/version) — نزدیک‌ترین آنالوگ |
| الگوی canvas | `workflow_canvas.dart` — InteractiveViewer، zoom، undo، shortcuts |
| اکسل کالا | `product_import_dialog.dart` + API openpyxl |
| پکیج‌ها | `pdf`, `barcode`, `printing`, `desktop_drop`, `file_picker` |
### شکاف‌ها
- هیچ طرح ذخیره‌شونده برای بارکد کالا وجود ندارد.
- استودیوی آزاد با مختصات mm وجود ندارد.
- دیالوگ چاپ سیستم / چاپگر رولی برای لیبل وجود ندارد.
- انواع بارکد محدود به Code128 و QR است.
---
## ۳) سناریوی محصول (کامل)
### ۳.۱ اهداف
- طراحی برچسب با Drag & Drop، موس، کیبورد، zoom، snap، undo/redo.
- اسکیل واقعی میلی‌متر؛ خروجی قابل اسکن.
- چند طرح per business + پیش‌فرض + انتخاب موقع چاپ.
- اتصال به لیست کالا / واحد یونیک / اکسل / چاپ سریالی و تعدادی.
- پشتیبانی symbology: Code128, Code39, Code93, EAN8, EAN13, CodaBar, DataMatrix, QR.
- چند متن، چند بارکد، چند تصویر در یک برچسب؛ چینش سطر/ستون روی کاغذ.
- سازگاری با چاپگرهای لیزری/رنگی/سوزنی از مسیر PDF+درایور OS؛ رولی در فاز D.
### ۳.۲ غیرهدف‌ها (عمداً خارج)
- جایگزینی کامل موتور قالب فاکتور (`report_templates` عمومی).
- وعدهٔ چاپ مستقیم USB/raw روی وب.
- ادیتور موبایل گوشی کوچک به‌عنوان تجربهٔ اصلی طراحی (اندروید برای چاپ و ویرایش سبک).
### ۳.۳ پرسونا و جریان‌ها
**طراح عملیات:** استودیو → ساخت/ویرایش طرح → Publish → Set default.
**اپراتور چاپ:** کالاها → انتخاب → طرح (پیش‌فرض یا دستی) → تعداد → پیش‌نمایش → PDF/چاپ.
**مدیر:** خرید افزونه از بازار، تعیین دسترسی `design` / `print`.
### ۳.۴ معماری اطلاعات UI
```
بازار افزونه‌ها → barcode_label_studio
منو (پس از فعال‌سازی):
برچسب و بارکد
├─ طرح‌های من
├─ استودیو (new / :id)
├─ چاپ از کالاها (میانبر)
└─ چاپ از اکسل / سریال
کالاها و خدمات:
├─ چاپ با طرح پیش‌فرض
├─ چاپ با انتخاب طرح
└─ از فرم کالا: چاپ این کالا
```
### ۳.۵ استراتژی پلتفرم
| قابلیت | وب | ویندوز | اندروید |
|--------|----|--------|---------|
| استودیو + طرح‌ها + PDF | ✅ | ✅ (بهترین UX) | ✅ (تبلت/landscape) |
| چاپ از کالا / اکسل | ✅ | ✅ | ✅ |
| دیالوگ چاپ سیستم | محدود (مرورگر) | ✅ اولویت | ✅ در حد OS |
| چاپ رولی/خام | ❌ وعده داده نشود | ✅ فاز D | ✅ فاز D |
### ۳.۶ معیار پذیرش محصول کامل
1. ساخت طرح جدید بدون تغییر کد.
2. چند published + یک default پایدار.
3. تعویض طرح موقع چاپ + پیش‌نمایش صحیح.
4. موس + کیبورد + zoom/snap/undo در سطح editor واقعی.
5. مختصات mm و PDF قابل اسکن برای symbologyهای پشتیبانی‌شده.
6. چاپ گروهی از کالا و اکسل با تعداد مشخص.
7. گیت لایسنس روی همه مسیرها.
8. draft / publish / تاریخچه نسخه.
---
## ۴) فاز A — ستون فقرات (طراحی ✅ · پیاده‌سازی ❌)
### ۴.۱ هدف فاز
زیربنای داده، API، گیت افزونه، و **یک موتور رندر PDF واحد از JSON** طوری که preview ≡ چاپ.
### ۴.۲ مدل داده
#### جدول `label_templates`
| ستون | نوع | توضیح |
|------|-----|--------|
| id | PK | |
| business_id | FK businesses | CASCADE |
| name | varchar(160) | |
| description | varchar(512) nullable | |
| status | draft \| published \| archived | index |
| is_default | bool | فقط یکی published per business |
| version | int | bump روی تغییر محتوا |
| schema_version | int | مثلاً 1 |
| design_json | JSON | سند `label_design_v1` |
| sheet_json | JSON | کاغذ مادر، سطر/ستون، حاشیه (ممکن است داخل design هم باشد؛ sheet جدا برای override چاپ) |
| thumbnail_png | bytes/nullable یا file_id | اختیاری |
| created_by | FK users | |
| created_at / updated_at | datetime | |
| published_at | datetime nullable | |
ایندکس یکتا جزئی پیشنهادی: حداکثر یک `is_default=true` برای `(business_id)` بین ردیف‌های `status=published` (در سرویس enforce + در DB در صورت پشتیبانی partial unique).
#### جدول `label_template_revisions`
| ستون | نوع | توضیح |
|------|-----|--------|
| id | PK | |
| template_id | FK | CASCADE |
| version_no | int | |
| design_json | JSON | snapshot |
| sheet_json | JSON | |
| changelog | varchar nullable | |
| created_by | FK users | |
| created_at | datetime | |
#### تنظیمات کسب‌وکار (اختیاری)
- فیلد/ردیف settings: `default_label_template_id` — یا فقط از `is_default` روی جدول طرح‌ها.
#### دارایی تصویر
- ترجیح فاز A: ارجاع `file_storage_id` از ماژول storage با `module_context=barcode_labels`.
- مسیر سریع: data-URI داخل design برای لوگوهای کوچک (سقف حجم در validation).
### ۴.۳ Schema سند طراحی — `label_design_v1`
```json
{
"schema_version": 1,
"canvas": {
"width_mm": 50,
"height_mm": 30,
"grid_mm": 1,
"snap_to_grid": true,
"guides_mm": { "vertical": [], "horizontal": [] },
"dpi": 300
},
"elements": [
{
"id": "el_1",
"type": "text",
"name": "نام کالا",
"x_mm": 2,
"y_mm": 2,
"w_mm": 46,
"h_mm": 6,
"rotation_deg": 0,
"z_index": 1,
"locked": false,
"visible": true,
"props": {
"content_mode": "binding",
"text": "",
"binding": "product.name",
"font_family": "YekanBakhFaNum",
"font_size_pt": 9,
"font_weight": "normal",
"align": "center",
"valign": "middle",
"color": "#000000",
"rtl": true,
"wrap": true
}
},
{
"id": "el_2",
"type": "barcode",
"name": "بارکد اصلی",
"x_mm": 4,
"y_mm": 10,
"w_mm": 42,
"h_mm": 14,
"rotation_deg": 0,
"z_index": 2,
"locked": false,
"visible": true,
"props": {
"symbology": "code128",
"content_mode": "binding",
"value": "",
"binding": "product.general_barcode",
"show_text": true,
"text_size_pt": 7,
"quiet_zone_mm": 1
}
}
]
}
```
#### انواع المان (`type`)
| type | props کلیدی |
|------|-------------|
| `text` | content_mode fixed\|binding، text، binding، font_*، align، color، rtl، wrap |
| `barcode` | symbology: code128\|code39\|code93\|ean8\|ean13\|codabar، value/binding، show_text، quiet_zone |
| `qr` | ecc L\|M\|Q\|H، value/binding، quiet_zone |
| `datamatrix` | value/binding |
| `image` | source: upload\|product.image\|business.logo، file_id یا data_uri، fit contain\|cover\|fill، opacity |
| `shape` | shape rect\|ellipse\|line، stroke، fill، stroke_width_mm |
| `line` | می‌تواند زیرمجموعه shape باشد |
#### Bindingهای استاندارد فاز A
- `product.name`, `product.code`, `product.price`, `product.sale_price`
- `product.general_barcode` (اولین توکن)، `product.general_barcode[n]`
- `instance.serial`, `instance.barcode`
- `warehouse.name`, `business.name`
- `print.counter`, `print.copy_index`
- `fixed` از طریق content_mode
#### `sheet_json` (چینش روی کاغذ)
```json
{
"paper": "A4",
"orientation": "portrait",
"custom_paper_mm": null,
"margin_mm": { "top": 5, "right": 5, "bottom": 5, "left": 5 },
"columns": 3,
"rows": 8,
"gap_mm": { "x": 2, "y": 2 },
"label_from_canvas": true
}
```
### ۴.۴ قرارداد API
Base: `/api/v1/barcode-labels/business/{business_id}`
همه endpointها پشت `require_barcode_label_plugin_active` + permission.
| Method | Path | توضیح |
|--------|------|--------|
| GET | `/templates` | لیست (فیلتر status) |
| POST | `/templates` | ساخت draft |
| GET | `/templates/{id}` | جزئیات + design |
| PUT | `/templates/{id}` | به‌روزرسانی محتوا (version++) |
| POST | `/templates/{id}/publish` | draft→published |
| POST | `/templates/{id}/archive` | archive |
| POST | `/templates/{id}/duplicate` | کپی |
| POST | `/templates/set-default` | `{ template_id }` فقط published |
| GET | `/templates/default` | resolve پیش‌فرض |
| POST | `/templates/{id}/preview` | PDF یک برچسب با sample payload |
| POST | `/print` | job چاپ → PDF |
| GET | `/presets` | گالری preset سیستمی |
| POST | `/templates/from-preset` | ساخت از preset |
#### `POST /print` body
```json
{
"template_id": 12,
"source": "products",
"items": [
{ "product_id": 1, "instance_id": null, "qty": 2, "overrides": {} }
],
"sheet_override": null
}
```
پاسخ: `application/pdf` یا `{ file_token }` مطابق الگوی سایر PDFهای حسابیکس.
### ۴.۵ موتور رندر
- ورودی: `design_json` + `sheet_json` + لیست context آیتم‌ها.
- خروجی: PDF چندصفحه‌ای با کاشی‌کاری لیبل‌ها.
- اعتبارسنجی قبل از رندر: طول EAN، خالی نبودن binding اجباری، المان خارج از canvas، حداقل ارتفاع بارکد.
- کتابخانه پیشنهادی سمت کلاینت فعلی: `pdf` + `barcode`؛ در فاز A تصمیم قطعی:
**تصمیم طراحی فاز A:** رندر **سمت کلاینت** برای preview استودیو و چاپ (هم‌راستا با `ProductLabelPrintDialog` فعلی) + امکان preview سرور اختیاری بعداً. قرارداد JSON واحد است تا بعداً سرور هم همان schema را رندر کند.
فایل‌های هدف پیشنهادی:
```
hesabixAPI/
adapters/db/models/label_template.py
adapters/db/models/label_template_revision.py
migrations/versions/YYYYMMDD_label_templates.py
adapters/api/v1/barcode_labels.py
adapters/api/v1/schema_models/barcode_label.py
app/services/barcode_label_service.py
app/services/barcode_label_design_validator.py
app/core/barcode_label_plugin_dependency.py
adapters/db/seed_data/marketplace_plugins_seed.py # افزودن seed
hesabixUI/hesabix_ui/lib/
services/barcode_label_service.dart
models/barcode_label/
label_design_v1.dart
label_template.dart
label_sheet.dart
widgets/barcode_label/render/label_pdf_renderer.dart
widgets/marketplace/barcode_label_plugin_gate.dart
```
### ۴.۶ افزونه marketplace
```text
code: barcode_label_studio
name: طراحی و چاپ برچسب بارکد
category: product_management
trial_days: 14
trial_allowed: true
plans: monthly / yearly / lifetime (مبالغ در پیاده‌سازی نهایی با محصول)
```
Permissions پیشنهادی:
- `barcode_labels.view`
- `barcode_labels.design`
- `barcode_labels.print`
### ۴.۷ Presetهای سیستمی (حداقل)
| کد | اندازه | کاربرد |
|----|--------|--------|
| `shelf_50x30` | ۵۰×۳۰ mm | قفسه |
| `shelf_40x30` | ۴۰×۳۰ mm | فشرده |
| `price_70x40` | ۷۰×۴۰ mm | برچسب قیمت |
| `a4_grid_code128` | canvas ۵۰×۳۰ روی A4 | ورقی چندتایی |
### ۴.۸ چک‌لیست فاز A
#### طراحی
- [x] مدل جداول
- [x] schema `label_design_v1`
- [x] قرارداد API
- [x] تصمیم موتور رندر
- [x] seed افزونه و permissions
- [x] لیست preset
#### پیاده‌سازی
- [x] Migration جداول
- [x] ORM + service + validator
- [x] API router + dependency افزونه
- [x] Seed marketplace
- [x] مدل‌های Dart + service کلاینت
- [x] `LabelPdfRenderer` از JSON
- [x] `BarcodeLabelPluginGate`
- [x] صفحه لیست طرح‌ها (CRUD ساده بدون canvas کامل)
- [x] i18n FA/EN کلیدهای پایه
#### تست/پذیرش
- [ ] ساخت/ویرایش/publish/default از API
- [ ] رندر PDF از preset با داده نمونه قابل اسکن
- [ ] 403 بدون لایسنس
---
## ۵) فاز B — استودیو WYSIWYG (طراحی ✅ · پیاده‌سازی ❌)
### ۵.۱ هدف فاز
محیط استودیوی حرفه‌ای با موس، کیبورد، مقیاس mm، DnD، لایه‌ها، inspector، پیش‌نمایش PDF.
### ۵.۲ چیدمان صفحه استودیو
مسیر: `barcode-labels/studio/new` و `barcode-labels/studio/:template_id`
```
┌ Header: نام | ذخیره | پیش‌نمایش PDF | انتشار | پیش‌فرض | Undo/Redo | Zoom% | بستن
├──────┬──────────────────────────────┬─────────────┐
│Tool │ Ruler H │ Inspector │
│box ├──────────────────────────────┤ Properties │
│+Layer│ RulerV │ CANVAS │ Binding │
│s │ │ (InteractiveViewer│ Align │
│ │ │ + grid + guides) │ Lock │
└──────┴──────────────────────────────┴─────────────┘
└ Status: X/Y/W/H mm | angle | snap | selection count
```
مرجع تعاملی: `workflow_canvas.dart` + تاریخچه command مانند `workflow_history.dart`.
### ۵.۳ سیستم مختصات و اسکیل
| مفهوم | قاعده |
|--------|--------|
| منبع حقیقت | mm در `design_json` |
| نمایش | `px = mm * (dpi/25.4) * zoom` با dpi منطقی UI جدا از dpi چاپ (مثلاً UI 96 منطقی، چاپ 300) |
| Zoom | 0.25 … 4.0 ؛ Ctrl+Wheel ؛ Ctrl+0 fit ؛ Ctrl+1 صددرصد |
| Grid | 1 / 2 / 5 mm |
| Snap | grid، لبه المان‌ها، راهنماها، مرکز canvas |
| Pan | Space+drag، mid-button، InteractiveViewer |
**قانون طلایی:** هیچ layout چاپی نباید از مختصات پیکسل UI مشتق شود؛ همیشه mm → PDF.
### ۵.۴ تعامل موس
- Drag از toolbox → ایجاد المان در نقطه drop
- Select / multi-select (Ctrl) / marquee
- Move، resize با 8 handle؛ Shift = حفظ نسبت
- Rotate handle (زاویه با Shift قفل ۱۵°)
- Double-click متن → ویرایش inline
- Context menu: کپی، duplicate، قفل، ترتیب لایه، حذف، تبدیل به binding
- Drop فایل تصویر روی canvas
### ۵.۵ میانبرهای کیبورد
| کلید | عمل |
|------|-----|
| Ctrl+Z / Ctrl+Y یا Ctrl+Shift+Z | Undo / Redo (حداقل ۵۰ فرمان) |
| Ctrl+S | ذخیره |
| Ctrl+C / X / V / D | کپی / برش / چسباندن / duplicate |
| Delete | حذف |
| Ctrl+A | انتخاب همه |
| Arrows | ۱ mm |
| Shift+Arrows | ۵ mm |
| Ctrl+Arrows | یک قدم grid |
| Ctrl+] `[` | لایه |
| Ctrl+L | قفل |
| Esc | لغو / deselect |
| V T B Q I | ابزارها |
| Ctrl+P | پیش‌نمایش PDF |
Focus: canvas با `Focus`/`CallbackShortcuts`؛ وقتی Inspector text field فوکوس دارد، فلش‌ها برای متن کار کنند نه جابه‌جایی المان.
### ۵.۶ Command pattern (Undo)
فرمان‌های atomic:
- `AddElement`, `RemoveElements`, `MoveElements`, `ResizeElement`, `RotateElement`
- `UpdateElementProps`, `ReorderZ`, `ToggleLock`, `ToggleVisible`
- `UpdateCanvas`, `UpdateSheet`
هر فرمان: `apply` / `revert` روی `LabelDesignDocument`.
### ۵.۷ Inspector و Toolbox
**Toolbox:** Text, Barcode, QR, DataMatrix, Image, Rect, Line + presets سریع.
**Layers:** لیست z-order، چشم، قفل، rename.
**Inspector:** بسته به type — فونت، symbology، binding picker از کاتالوگ فیلدها، رنگ، fit تصویر.
### ۵.۸ اعتبارسنجی زنده در استودیو
- هشدار زرد: quiet zone کم، فونت خیلی کوچک، بارکد فشرده
- خطای قرمز: EAN نامعتبر در حالت fixed، المان خارج بوم، تداخل اجباری برای publish
- Publish فقط وقتی خطاهای قرمز صفر باشند
### ۵.۹ ساختار فایل UI پیشنهادی
```
lib/pages/business/barcode_labels/
label_templates_page.dart
label_studio_page.dart
label_print_page.dart
lib/widgets/barcode_label/studio/
label_studio_shell.dart
label_canvas.dart
label_canvas_painter.dart
label_element_widget.dart
label_toolbox.dart
label_layers_panel.dart
label_inspector.dart
label_rulers.dart
label_studio_shortcuts.dart
label_studio_history.dart
lib/models/barcode_label/studio/
label_studio_state.dart
label_studio_commands.dart
```
### ۵.۱۰ چک‌لیست فاز B
#### طراحی
- [x] چیدمان استودیو
- [x] قواعد اسکیل/zoom/snap
- [x] موس و کیبورد
- [x] Undo command list
- [x] ساختار فایل‌ها
- [x] قوانین validation استودیو
#### پیاده‌سازی
- [x] Shell استودیو + route + منو
- [x] Canvas + grid + zoom/pan (InteractiveViewer، مختصات mm)
- [x] Toolbox + ایجاد المان‌ها (کلیک ابزار)
- [x] Selection + drag move + snap به grid
- [x] Resize handles / rotate handle
- [x] Inspector + binding picker + symbology
- [x] Layers panel
- [x] Shortcuts پایه + Undo/Redo (Ctrl+Z/Y)
- [x] History undo/redo
- [x] Preview PDF از همان renderer فاز A
- [x] ذخیره / publish از استودیو
- [x] نشانگر تغییرات ذخیره‌نشده (dirty)
- [x] Unsaved changes guard روی خروج route
- [x] خط‌کش mm
#### تست/پذیرش
- [ ] ساخت طرح ۵۰×۳۰ با متن+بارکد+لوگو و چاپ قابل اسکن
- [ ] Undo پس از ۱۰ عمل متوالی درست برمی‌گردد
- [ ] Zoom fit و ۱۰۰٪ مختصات mm را خراب نمی‌کند
---
## ۶) فاز C — اتصال عملیات (طراحی ✅ · پیاده‌سازی ❌)
### ۶.۱ هدف فاز
مصرف واقعی طرح‌ها از کالاها، تعدادی/گروهی، اکسل، سریال؛ جایگزینی تدریجی flow چاپ پیشرفته پشت گیت افزونه.
### ۶.۲ نقاط ورود کالاها
در `products_page.dart` (و فرم کالا):
| ورود | رفتار با افزونه فعال | بدون افزونه |
|------|----------------------|-------------|
| چاپ بارکد عمومی | دیالوگ پیشرفته با انتخاب طرح | دیالوگ ساده فعلی |
| چاپ واحد یونیک | همان | ساده فعلی |
| چاپ از فرم کالا | دیالوگ برای همان کالا | ساده/مخفی پیشرفته |
دیالوگ پیشرفته (`LabelPrintJobDialog`):
1. انتخاب طرح (پیش‌فرض از قبل selected)
2. Thumbnail + نام طرح
3. جدول آیتم‌ها: نام، کد، بارکد، qty
4. Override موقت sheet (اختیاری)
5. پیش‌نمایش صفحه اول
6. خروجی PDF / اشتراک / (فاز D) چاپ
### ۶.۳ منابع داده چاپ
| source | توضیح |
|--------|--------|
| `products` | کالاهای انتخاب‌شده؛ general barcode |
| `instances` | واحدهای یونیک |
| `excel` | ردیف فایل |
| `serial_range` | از–تا + prefix/suffix |
### ۶.۴ اکسل
قالب ستون‌ها (حداقلی):
| ستون | اجباری | توضیح |
|------|--------|--------|
| code | خیر* | match کالا |
| barcode | خیر* | مقدار بارکد |
| name | خیر | override نام |
| qty | بله | تعداد چاپ |
| price | خیر | |
| serial | خیر | |
| custom_1..n | خیر | برای bindingهای سفارشی بعدی |
\* حداقل یکی از code یا barcode لازم است مگر حالت «داده خام».
Flow: دانلود قالب → انتخاب فایل → dry-run → تأیید → ساخت job → PDF.
Shell مشترک: `excel_import_dialog_shell.dart`.
### ۶.۵ چاپ سریالی
- prefix + start + end + pad length + suffix
- qty per value
- پیش‌نمایش ۱۰ مقدار اول
- محدودیت سقف تعداد برچسب در یک job (مثلاً ۱۰٬۰۰۰) با پیام واضح
### ۶.۶ همگام‌سازی با موجودی ساده هسته
- هسته: `ProductLabelPrintDialog` بدون طرح می‌ماند.
- افزونه: مسیر جدید؛ دکمه/منوی «چاپ پیشرفته برچسب» واضح برچسب‌گذاری شود تا کاربر سردرگم نشود.
- اگر default تعریف نشده: اجبار به انتخاب طرح یا پیشنهاد ساخت از preset.
### ۶.۷ چک‌لیست فاز C
#### طراحی
- [x] نقاط ورود کالا
- [x] دیالوگ job چاپ
- [x] اکسل و سریال
- [x] سیاست هم‌زیستی با چاپ ساده
#### پیاده‌سازی
- [x] `LabelPrintJobDialog` + اتصال renderer
- [x] اتصال `products_page` bulk actions (منوی چاپ حرفه‌ای)
- [ ] چاپ از فرم کالا (اختیاری باقی‌مانده)
- [x] صفحه/دیالوگ اکسل
- [x] صفحه/دیالوگ سریال
- [x] resolve default template در UI
- [x] پیام‌ها و empty states وقتی طرحی نیست
#### تست/پذیرش
- [ ] چاپ ۲۰ کالا با qty متفاوت روی A4
- [ ] اکسل dry-run خطاها را نشان می‌دهد
- [ ] بدون افزونه مسیر ساده Intact بماند
---
## ۷) فاز D — چاپ پیشرفته (طراحی ✅ · پیاده‌سازی ✅)
### ۷.۱ اهداف
1. چاپ سیستم از PDF لیبل (`Printing.layoutPdf`)
2. پروفایل چاپگر رولی / حرارتی / Zebra (native)
3. دکمه چاپ با طرح در فرم تک‌کالا
### ۷.۲ چاپ سیستم
- ویندوز/اندروید: دیالوگ OS
- وب: ذخیره PDF + راهنما
### ۷.۳ پروفایل رولی (native-only)
مسیر پایدار: `pdf_spooler` با صفحه به اندازه بوم.
ZPL آزمایشی (TCP بدون پکیج جدید) طبق `design/adr_roll_printer.md`.
### ۷.۴ چک‌لیست فاز D
#### طراحی
- [x] قرارداد چاپ سیستم
- [x] مدل پروفایل رولی
#### پیاده‌سازی
- [x] دکمه Print با `layoutPdf` روی ویندوز/اندروید (و راهنمای وب)
- [x] اسپایک پکیج رولی و ADR (`adr_roll_printer.md` — بدون dependency جدید)
- [x] CRUD پروفایل چاپگر (`barcode-labels/printers` + API settings)
- [x] ارسال job به پروفایل (pdf_spooler کامل؛ ZPL TCP آزمایشی)
- [x] دکمه چاپ با طرح داخل فرم تک‌کالا
- [x] مستند کاربر: محدودیت پلتفرم‌ها (hint وب در UI)
#### تست/پذیرش
- [ ] چاپ ورقی از ویندوز روی لیزری واقعی
- [ ] (اختیاری) یک چاپگر رولی نمونه
---
## ۸) توالی پیاده‌سازی پیشنهادی
```
A1 seed+migration+API CRUD
A2 validator + Dart models
A3 LabelPdfRenderer + preset render
A4 لیست طرح‌ها + set-default + gate
B1 studio shell + canvas mm
B2 elements DnD + inspector
B3 shortcuts + undo
B4 preview/publish integration
C1 print job dialog + products hooks
C2 excel + serial
D1 system print
D2 roll printer profiles + product form button
```
هر زیرمرحله پس از اتمام، چک‌لیست همین سند تیک می‌خورد و در بخش ۹ ثبت می‌شود.
---
## ۹) گزارش پیشرفت اجرا (لاگ)
| تاریخ | رویداد | نتیجه |
|-------|--------|--------|
| ۲۰۲۶-۰۸-۰۶ | نگارش سناریوی کامل در سند اصلی | سناریو ✅ |
| ۲۰۲۶-۰۸-۰۶ | طراحی فاز A–D + فایل‌های design/* | طراحی ✅ |
| ۲۰۲۶-۰۸-۰۶ | پیاده‌سازی A: migration، ORM، API، seed، gate، لیست طرح‌ها، renderer | A عمدتاً ✅ |
| ۲۰۲۶-۰۸-۰۶ | تکمیل B: undo/redo، resize/rotate، rulers، exit guard | B ✅ |
| ۲۰۲۶-۰۸-۰۶ | تکمیل C: LabelPrintJobDialog، اتصال کالاها، اکسل، سریال | C ✅ |
| ۲۰۲۶-۰۸-۰۶ | تکمیل D1: Printing.layoutPdf + hint وب | D جزئی 🟡 (رولی مانده) |
| ۲۰۲۶-۰۸-۰۶ | تکمیل D2: پروفایل رولی/Zebra، roll PDF، دکمه فرم کالا | D ✅ |
---
## ۱۰) تصمیم‌های قفل‌شده
1. افزونه marketplace با کد `barcode_label_studio` — نه قابلیت رایگان هسته برای استودیو.
2. چاپ ساده فعلی کالا باقی می‌ماند.
3. مختصات طراحی و چاپ: **میلی‌متر**.
4. یک schema نسخه دار: `label_design_v1`.
5. چند طرح + یک default + انتخاب موقع چاپ.
6. استودیو روی وب/ویندوز/اندروید؛ چاپ رولی فقط native.
7. رندر فاز A–C: کلاینت PDF از JSON (هم‌خوان با کدبیس فعلی لیبل).
8. الگوی UX canvas نزدیک workflow editor؛ الگوی lifecycle نزدیک report templates.
---
## ۱۱) تصمیم‌های باز (باید قبل/حین پیاده‌سازی بسته شوند)
| # | موضوع | گزینه‌ها | وضعیت |
|---|--------|----------|--------|
| 1 | قیمت پلن‌های افزونه | هم‌تراز HScript / Warranty | باز — محصول |
| 2 | سقف المان/تصویر/برچسب در یک job | پیشنهاد: ۵۰ المان، ۲MB/تصویر، ۱۰k برچسب | پیشنهاد شده |
| 3 | گروه المان (Group) | فاز B یا بعد | بعد از MVP استودیو |
| 4 | رندر سرور WeasyPrint علاوه بر کلاینت | اختیاری آینده | باز |
| 5 | پکیج چاپ رولی نهایی | ADR ثبت شد؛ تأیید سخت‌افزار باز | 🟡 ADR |
---
## ۱۲) ارجاعات کدبیس
- `hesabixUI/hesabix_ui/lib/widgets/product/product_label_print_dialog.dart`
- `hesabixUI/hesabix_ui/lib/pages/business/products_page.dart`
- `hesabixUI/hesabix_ui/lib/widgets/workflow/workflow_canvas.dart`
- `hesabixUI/hesabix_ui/lib/pages/business/report_template_studio_page.dart`
- `hesabixAPI/adapters/db/models/report_template.py`
- `hesabixAPI/adapters/db/seed_data/marketplace_plugins_seed.py`
- `hesabixAPI/app/services/warehouse_postal_label_service.py`
---
## ۱۳) فایل‌های مرتبط این پوشه
| فایل | نقش | وضعیت |
|------|-----|--------|
| `BARCODE_LABEL_STUDIO.md` | سند اصلی زنده (همین فایل) | ✅ |
| `README.md` | فهرست ورود سریع | ✅ |
| `design/label_design_v1.schema.json` | JSON Schema رسمی سند طراحی | ✅ طراحی |
| `design/api_contract.md` | قرارداد API فاز A | ✅ طراحی |
| `design/studio_ux.md` | UX استودیو فاز B | ✅ طراحی |
| `design/print_job_ux.md` | UX چاپ/اکسل/سریال فاز C | ✅ طراحی |
| `design/phase_d_printing.md` | چاپ سیستم و رولی فاز D | ✅ طراحی |
| `design/adr_roll_printer.md` | ADR اسپایک چاپگر رولی | ✅ |
---
## ۱۴) قدم بعدی پیشنهادی
1. اجرای migrationهای `20260806_000001` و `20260806_000002` و فعال‌سازی trial افزونه
2. Smoke تست: preset → استودیو → publish → پروفایل رولی → چاپ از کالاها / فرم کالا
3. (اختیاری) تست سخت‌افزاری Zebra LAN برای تأیید کامل ZPL
پس از هر تست/تکمیل، چک‌لیست و لاگ همین سند را به‌روز کنید.