arc/docs/barcode_label_studio/BARCODE_LABEL_STUDIO.md

استودیوی طراحی و چاپ برچسب بارکد حسابیکس

وضعیت سند: زنده (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

{
  "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 (چینش روی کاغذ)

{
  "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

{
  "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

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

طراحی

• مدل جداول
• schema label_design_v1
• قرارداد API
• تصمیم موتور رندر
• seed افزونه و permissions
• لیست preset

پیاده‌سازی

• Migration جداول
• ORM + service + validator
• API router + dependency افزونه
• Seed marketplace
• مدل‌های Dart + service کلاینت
• LabelPdfRenderer از JSON
• BarcodeLabelPluginGate
• صفحه لیست طرح‌ها (CRUD ساده بدون canvas کامل)
• 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

طراحی

• چیدمان استودیو
• قواعد اسکیل/zoom/snap
• موس و کیبورد
• Undo command list
• ساختار فایل‌ها
• قوانین validation استودیو

پیاده‌سازی

• Shell استودیو + route + منو
• Canvas + grid + zoom/pan (InteractiveViewer، مختصات mm)
• Toolbox + ایجاد المان‌ها (کلیک ابزار)
• Selection + drag move + snap به grid
• Resize handles / rotate handle
• Inspector + binding picker + symbology
• Layers panel
• Shortcuts پایه + Undo/Redo (Ctrl+Z/Y)
• History undo/redo
• Preview PDF از همان renderer فاز A
• ذخیره / publish از استودیو
• نشانگر تغییرات ذخیره‌نشده (dirty)
• Unsaved changes guard روی خروج route
• خط‌کش 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

طراحی

• نقاط ورود کالا
• دیالوگ job چاپ
• اکسل و سریال
• سیاست هم‌زیستی با چاپ ساده

پیاده‌سازی

• LabelPrintJobDialog + اتصال renderer
• اتصال products_page bulk actions (منوی چاپ حرفه‌ای)
• چاپ از فرم کالا (اختیاری باقی‌مانده)
• صفحه/دیالوگ اکسل
• صفحه/دیالوگ سریال
• resolve default template در UI
• پیام‌ها و 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

طراحی

• قرارداد چاپ سیستم
• مدل پروفایل رولی

پیاده‌سازی

• دکمه Print با layoutPdf روی ویندوز/اندروید (و راهنمای وب)
• اسپایک پکیج رولی و ADR (adr_roll_printer.md — بدون dependency جدید)
• CRUD پروفایل چاپگر (barcode-labels/printers + API settings)
• ارسال job به پروفایل (pdf_spooler کامل؛ ZPL TCP آزمایشی)
• دکمه چاپ با طرح داخل فرم تک‌کالا
• مستند کاربر: محدودیت پلتفرم‌ها (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

پس از هر تست/تکمیل، چک‌لیست و لاگ همین سند را به‌روز کنید.