Kiến trúc và luồng xử lý

1. Giao diện gửi Excel, template, loại POSM, số dòng, định dạng, cách xuất. src/web_app.py · PAGE (JS) → api_generate()
2. Đọc Excel: header 2 dòng, cột Ngang/Dọc theo loại POSM, dữ liệu từ dòng 3, lọc dòng thiếu hoặc ngoài khoảng validation. src/excel_parser.py · parse_excel()
3. Tạo job: width_mm = width × mm_per_unit, tên file theo shop, size và chiến dịch; gắn nhãn catalog source_artboard (chỉ để tham khảo). src/job_builder.py · build_manifest() → src/naming.py · build_output_name()
4. Ghi data/output/jobs.json kèm cấu hình export (scale, lề tên, ngưỡng méo, định dạng). src/job_builder.py · write_manifest_with_config()
5. Chọn backend: file .ai hoặc TIFF thì dùng Illustrator; .svg thì dùng exporter Python. src/service.py · export_jobs() / resolve_export_backend()
6. Gọi Illustrator chạy JSX. Trên Mac dùng osascript … do javascript, đợi chạy xong mới trả về. src/runner.py · launch_illustrator_script() → run_jsx_on_mac()
7. JSX mở template, xử lý từng job: chọn mẫu, tạo document mới, copy, resize, thêm lề tên, xuất TIFF, ghi resize_log.txt. illustrator/resize_posm.jsx · processJobs() → exportJobBlankDoc()
8. Flask đọc log (chỉ nhận log mới hơn lúc bấm), ghép với jobs, trả bảng kết quả cho giao diện. src/resize_log.py · parse_resize_log() → web_app._collect_export_result()

r_item = W / H        r_job = Ngang / Dọc
méo %  = (max(r_item/r_job, r_job/r_item) − 1) × 100
score  = méo × 1000 − diện tích × 1e-9

Khi template có nhiều artboard, resolveJobArtboard() chọn artboard theo kích thước thật (exact rồi gần tỉ lệ); ứng viên = object trên artboard đó cộng thư viện ngoài artboard.

{
  "template": ".../Banner thường POSM tháng 9 đợt 2.ai",
  "export_format": "tif", "export_layout": "per_job",
  "export_scale": 0.1, "label_strip_mm": 2.0, "max_distortion_pct": 5.0,
  "mm_per_unit": 1000, "filename_display_multiplier": 100,
  "jobs": [{
    "row_number": 3, "shop_name": "LC HNI 01 Lê Văn Hiến, P. Đông Ngạc",
    "width": 4.5, "height": 0.7, "width_mm": 4500.0, "height_mm": 700.0,
    "output_name": "LC HNI 01 … - 450 x 70 - LC Tiêm chủng tháng 9",
    "source_artboard": "500x70", "match_reason": "near"   ← nhãn catalog, JSX không dùng
  }],
  "skipped_rows": [{ "row_number": 4, "reason": "Thiếu kích thước Ngang/Dọc" }]
}

INFO | <tên file> | pick BT-10.tif 2000x80 r=25.00 | job r=21.67 | méo 15.4% | 11 mẫu
WARN | <tên file> | méo 15.4% > 5% — thư viện không có mẫu gần tỉ lệ, cần kiểm tra / bổ sung mẫu
OK   | <tên file> | source BT-10.tif | méo 15.4% | items 1 | scale 1:10 | artboard 130.2x6.0cm | fitX 0.650 fitY 0.750
ERR  | <tên file> | <lỗi>          ·  ERR | FATAL | <lỗi toàn cục>
Success: 5 | Failed: 0 | Warn (méo): 2

parse_resize_log_text() gom theo tên file và trả về status ok | warn | error, mẫu dùng và % méo. api_generate ghép thêm dòng Excel, tên shop, size cm, và trả skipped_rows. Nếu log cũ hơn lúc bấm (Windows chạy bất đồng bộ), giao diện báo "đang chạy, xem log".

Giao diện: 3 bước (Chọn file, Tuỳ chọn xuất, Xuất file), cài đặt Illustrator thu gọn có pill trạng thái, bảng kết quả với chip tổng, nút "Mở thư mục kết quả" (POST /api/open-output). Hỗ trợ sáng/tối. App mở vào giao diện chính kể cả khi chưa có key; mục Key kích hoạt (đầu trang khi chưa kích hoạt, thu gọn cuối trang khi đã kích hoạt) để nhập, đổi, gia hạn key và copy Machine ID. Chỉ /api/generate và /api/export bị chặn (403 + license_required) khi chưa có key hợp lệ (LICENSED_PATHS trong web_app.py).

POSM1.<base64url payload>.<HMAC-SHA256>
payload = {v, sub: khách, iat, exp, lifetime?, mid?}

# Local (build & test): http://localhost:8800  admin / Password@123
cd deploy/local && docker compose up -d --build
docker compose --profile test run --rm --build test

# VPS (deploy)
cd deploy/vps && cp .env.example .env              # điền DOMAIN, LICENSE_SECRET, hash, FLASK_SECRET_KEY, MONGO_PASSWORD
docker compose run --rm --no-deps license-server python -m license_server.hash_password
docker compose up -d --build                          # Caddy tự lấy HTTPS cho DOMAIN
docker compose exec -T mongo sh -c 'mongodump -u "$MONGO_INITDB_ROOT_USERNAME" -p "$MONGO_INITDB_ROOT_PASSWORD" --authenticationDatabase admin --db posm_license --archive --gzip' > backup.archive.gz

Hướng dẫn đầy đủ: docs/LICENSE_SERVER.md.

• Banner trong template là TIF gộp lớp, nên chỉ kéo được cả tấm. Tỉ lệ nằm giữa hai mẫu xa nhau sẽ méo: 1300×60 méo 15.4% (thiếu mẫu tỉ lệ ~21.7), 930×70 méo 6.3%.
• Mẫu trong file cao ×80, trong khi khách mô tả ×70, nên mẫu được chọn khác với ví dụ của khách. Cần khách xác nhận file mẫu.
• Hai mẫu cùng tên BT-06 (650×60 và 900×80), log chỉ hiện tên nên dễ nhầm.
• template_variants (×70) trong config chỉ còn là nhãn, có thể dọn.
• Windows: runner có thể trả về trước khi Illustrator xong, khi đó giao diện không có bảng kết quả, phải xem log.
• Khoá đăng nhập lưu trong bộ nhớ, 1 worker gunicorn; restart là reset.

.venv/bin/python -m pytest -q          # 50 passed, 4 skipped
tests/test_license_gate.py             # vào UI không cần key, Export bị chặn tới khi kích hoạt
tests/test_resize_log.py               # parse OK/WARN/ERR/FATAL, log cũ bị bỏ qua
tests/test_license_server.py           # login, khoá, CSRF, tạo key → verify_token, huỷ = chỉ theo dõi
tests/test_export_formats.py           # manifest có max_distortion_pct

Đã chạy thật: export 5 dòng qua /api/generate với Illustrator (3 OK, 2 WARN, dòng 4 bỏ qua); Docker image license_server tạo key qua HTTP, kích hoạt app desktop bằng key đó thành công; dữ liệu SQLite còn sau restart container.