s_skaidocsTài liệu

Quy ước đặc tả Lingo cho Skai

Bản thiết kế v0.1 · chưa thay đổi theme engine.

Ưu tiên dùng lại

Dùng upper/lower/length, set/elif, toán tử và helper asset()/form() hiện có. Không bổ sung upcase/downcase/size, assign/elsif hoặc tag form trùng chức năng. Có sẵn trong thư viện và được bật trong runtime là hai trạng thái khác nhau.

Một tham số filter

Giữ giao diện FilterFunction(in, param) của Lingo. Nhiều tùy chọn được truyền bằng một list hoặc object context; không thêm cú pháp nhiều tham số Liquid. Object phải do resolver cấp hoặc từ cấu hình đã validate, không dùng literal object chưa được parser hỗ trợ.

ĐỀ XUẤT
{{ text|replace:["old", "new"] }}
{{ image_url|img_tag:image_options }}

Phạm vi và dữ liệu

Không cho template đọc database, file hoặc network tùy ý. Resolver cấp DTO public đúng workspace/application/store. Query phân trang phải giới hạn từ nguồn; filter danh sách chỉ xử lý dữ liệu đã cấp.

Tiền tệ

Money DTO dùng amount_minor nguyên và currency rõ ràng. Không giả định mọi currency chia 100, không đổi tỷ giá và không tính tổng checkout trong template. Backend quyết định giá; filter chỉ hiển thị.

Lỗi & bảo mật

Với API mới: sai kiểu/tham số trả lỗi cấu trúc; không âm thầm ép kiểu. Với API sẵn có: giữ hành vi Lingo. SafeHTML chỉ dùng cho helper sinh HTML có escape và URL allowlist; không thêm safe tùy tiện.

Những điểm cần chốt trước code

  • Options DTO cho ảnh, script, pagination.
  • Định dạng tiền theo locale và currency; policy số âm.
  • Auth route khách hàng tách tài khoản quản trị.
  • Giới hạn map/sort/uniq và render.
  • Trạng thái escape của capture và hợp đồng query paginate.

Các ví dụ “Đang phát triển” là đề xuất. Kiểm tra render trang tài liệu không chứng minh các ví dụ đó chạy được.