PRD: Tùy chọn sản phẩm & sinh biến thể
| Module | Sản phẩm (CORE-05) | PRD ID | PRD-OPT-002 |
| Trạng thái | Shipped | Người phụ trách | Product squad |
| Ngày | 2026-06-15 | Phiên bản | v1.0 |
| Packages | @nx/commerce · @nx/core · @nx/search | URD | OPT · VAR |
TL;DR
Biến các trục tùy chọn của một sản phẩm thành những biến thể merchant thực sự bán, trong một thao tác tạo liền mạch. Chủ khai báo các trục (size, mức đá, màu sắc) và đúng những biến thể cần sinh - mỗi biến thể nêu lựa chọn của nó trên từng trục - và hệ thống tạo các tùy chọn, giá trị, mọi biến thể, liên kết, định danh và thuộc tính kho của chúng cùng nhau. Việc sinh là tường minh, không bao giờ bung trọn tổ hợp Descartes: chỉ những biến thể đã khai báo mới tồn tại. Luôn có đúng một biến thể mặc định - cái chủ đánh dấu, hoặc cái khai báo đầu tiên - và lựa chọn của mỗi biến thể được đẩy vào tìm kiếm để tra và lọc theo tùy chọn.
1. Bối cảnh & Vấn đề
Mô hình liên kết tùy chọn (PRD-OPT-001) định nghĩa tổ hợp của một biến thể là gì và giữ nó hợp lệ và duy nhất. Nó không định nghĩa cách một sản phẩm và toàn bộ tập biến thể mang tùy chọn của nó ra đời trong một thao tác duy nhất của chủ.
Không có đường sinh, chủ sẽ phải tạo một sản phẩm trống, rồi thêm từng biến thể, rồi gắn tùy chọn từng liên kết một - nhiều lượt gọi, mỗi lượt là một cơ hội để lại danh mục dở dang: một sản phẩm có trục nhưng không biến thể, một biến thể không có mặc định, một barcode trùng chỉ phát hiện ở lượt gọi thứ ba. Merchant cũng kỳ vọng gõ những biến thể họ bán, chứ không phải để hệ thống nhân mỗi trục thành một ma trận các dòng ảo họ phải cắt tỉa sau.
Đợt này khép lại khoảng trống đó: một yêu cầu tạo duy nhất mang các trục và những biến thể đã khai báo, và hệ thống hiện thực hóa toàn bộ sản phẩm - tùy chọn, giá trị, biến thể, liên kết, định danh, thuộc tính kho, và một mặc định - một cách liền mạch, rồi làm mỗi biến thể có thể tra được theo tùy chọn của nó trong tìm kiếm.
2. Mục tiêu & Không-mục-tiêu
Mục tiêu
- Một thao tác tạo liền mạch nhận trục tùy chọn + biến thể đã khai báo và sinh toàn bộ đồ thị sản phẩm.
- Chỉ sinh tường minh - hệ thống tạo đúng những biến thể đã khai báo, không bao giờ là toàn bộ ma trận tùy chọn.
- Luôn giải quyết đúng một biến thể mặc định - cái được đánh dấu, nếu không thì cái khai báo đầu tiên.
- Mang SKU / barcode của từng biến thể, với tính duy nhất trong-yêu-cầu và theo-merchant.
- Sinh thuộc tính kho chỉ cho các loại biến thể quản lý tồn; loại không quản lý tồn và combo được tạo ở trạng thái không theo dõi.
- Phản chiếu lựa chọn tùy chọn của mỗi biến thể vào tìm kiếm để tra và lọc biến thể theo tùy chọn, được giữ tươi mới khi trục/giá trị/liên kết đổi.
Không-mục-tiêu
- Tự bung trọn tổ hợp Descartes của mọi tùy chọn - là một không-mục-tiêu cố ý trong PRD-OPT-001; chủ chỉ khai báo thứ họ bán.
- Bản thân các quy tắc mô hình liên kết (tính hợp lệ, một-mỗi-trục, tính duy nhất tổ hợp, bắt buộc tùy chọn) - đặc tả trong PRD-OPT-001.
- Định giá và mức tồn - giá nằm trong fares (FAR), tồn nằm trong Kho.
- Nhập danh mục hàng loạt / CSV (URD-PRD-019) - một đợt riêng.
3. Chỉ số Thành công
| Chỉ số | Mục tiêu / tín hiệu |
|---|---|
| Tính liền mạch | Một bước con thất bại (tùy chọn sai, barcode trùng, hai mặc định) không để lại gì được lưu |
| Không biến thể ảo | Số biến thể bằng số đã khai báo - không bao giờ bằng kích thước ma trận tùy chọn |
| Toàn vẹn mặc định | Mọi sản phẩm được sinh có đúng một biến thể mặc định |
| Toàn vẹn barcode | Không hai biến thể chia chung barcode trong một merchant; barcode trùng trong-yêu-cầu bị từ chối |
| Khả năng tìm | Một biến thể được sinh có thể tra và lọc theo từng giá trị tùy chọn của nó |
4. Persona & Tình huống Sử dụng
| Persona | Mục tiêu trong tính năng này |
|---|---|
| Chủ / Quản lý | Tạo một sản phẩm và mọi biến thể thật của nó trong một bước, chọn mặc định |
| Thu ngân | Tra và chọn một biến thể được sinh theo tùy chọn của nó tại điểm bán |
| Tích hợp kênh | Định vị đúng biến thể bằng cách lọc theo facet tùy chọn của nó trong tìm kiếm |
Tình huống chính: chủ tạo một trà sữa với trục Size (S/M/L) và Đá (100/50/0) và khai báo năm biến thể thực sự bán, đánh dấu "M, 100% đá" là mặc định. Hệ thống sinh các trục, giá trị, năm biến thể, liên kết, định danh, và thuộc tính kho của chúng trong một thao tác liền mạch; biến thể được đánh dấu thành mặc định; mỗi biến thể tra được ngay trong tìm kiếm theo size và ice. Khai báo hai mặc định, hoặc hai biến thể cùng barcode, bị từ chối trước khi lưu bất cứ thứ gì.
5. User Story
- Là chủ, tôi khai báo các trục của sản phẩm và đúng những biến thể tôi bán trong một yêu cầu, để danh mục hoàn chỉnh ngay khi được tạo.
- Là chủ, tôi muốn chỉ những biến thể tôi nêu mới tồn tại, để không bao giờ phải xóa những tổ hợp tôi không bán.
- Là chủ, tôi đánh dấu một biến thể là mặc định (hoặc để cái đầu tiên đứng), để POS luôn có lựa chọn hợp lý.
- Là chủ, tôi muốn một barcode trùng bị bắt trước khi lưu bất cứ gì, để không bao giờ xuất một mã đụng độ.
- Là chủ, tôi đổi mặc định sau này mà không dựng lại sản phẩm, để thực đơn có thể tiến hóa.
- Là thu ngân, tôi tìm một biến thể được sinh theo size và đá của nó, để gọi món chỉ vài chạm.
6. Yêu cầu Chức năng
| # | Yêu cầu | URD ref |
|---|---|---|
| FR-1 | Tạo nhận cả các trục tùy chọn và đúng những biến thể cần sinh, mỗi biến thể khai báo lựa chọn của nó trên từng trục | URD-OPT-011 |
| FR-2 | Chỉ những biến thể đã khai báo được sinh - không tự bung trọn ma trận | URD-OPT-012 |
| FR-3 | Trục, giá trị, và mọi biến thể đã khai báo được sinh cùng sản phẩm trong một thao tác liền mạch | URD-OPT-013 |
| FR-4 | Đúng một biến thể mặc định: cái được đánh dấu tường minh, nếu không thì cái khai báo đầu tiên được nâng | URD-OPT-014 |
| FR-5 | Nhiều hơn một mặc định tường minh trong cùng yêu cầu bị từ chối | URD-OPT-015 |
| FR-6 | Mặc định có thể đổi sau khi tạo qua một thao tác nâng chuyên biệt | URD-OPT-016 |
| FR-7 | Mỗi biến thể được sinh có thể mang SKU / barcode riêng; một barcode trùng trong-yêu-cầu hoặc đã dùng trong merchant bị từ chối | URD-OPT-017 · URD-PID-001 |
| FR-8 | Thuộc tính kho chỉ sinh cho loại biến thể quản lý tồn; combo và loại không quản lý tồn được tạo không theo dõi | URD-OPT-018 · URD-VAR-006 |
| FR-9 | Biến thể được sinh và lựa chọn tùy chọn của chúng được phản chiếu vào tìm kiếm và giữ tươi mới khi trục/giá trị/liên kết đổi | URD-OPT-019 |
| FR-10 | Trục và giá trị tùy chọn được chuẩn hóa để cùng một lựa chọn viết khác nhau ánh xạ về một giá trị | URD-OPT-006 |
Toàn văn yêu cầu và tiêu chí chấp nhận nằm trong URD Sản phẩm - OPT. PRD này tham chiếu chúng thay vì nhắc lại. Các yêu cầu mô hình liên kết (URD-OPT-001..010) được đặc tả trong PRD-OPT-001.
7. Yêu cầu Phi chức năng
| Lĩnh vực | Yêu cầu |
|---|---|
| Tính liền mạch | Toàn bộ đồ thị sản phẩm - tùy chọn, giá trị, biến thể, liên kết, định danh, thuộc tính kho, mặc định - là một giao dịch toàn-vẹn-hoặc-không |
| Tenancy & phân quyền | Mọi thao tác giới hạn theo merchant (x-merchant-id) và chặn bởi quyền sản phẩm |
| Chuẩn hóa | Khóa và giá trị tùy chọn được chuẩn hóa (không phân biệt hoa thường) để các lựa chọn tương đương gộp về một |
| Toàn vẹn định danh | Barcode được kiểm tra trùng trong-yêu-cầu và đụng độ merchant hiện hữu trước khi lưu |
| Nhất quán tìm kiếm cuối cùng | Facet tùy chọn phản chiếu được làm tươi bởi một cascade change-data sau commit, không nằm trong đường tới hạn của thao tác tạo |
| i18n | Tên trục đa ngôn ngữ ({ en, vi }); tên hiển thị của một giá trị lùi về giá trị thô khi chưa đặt |
8. UX & Luồng
Bề mặt tạo cho phép chủ định nghĩa các trục và giá trị có thứ tự của chúng, thêm từng biến thể họ bán với lựa chọn trên mỗi trục và một SKU / barcode tùy chọn, và đánh dấu một cái là mặc định. Biến thể được sinh sau đó xuất hiện trong tìm kiếm sản phẩm lọc được theo facet tùy chọn của chúng.
9. Dữ liệu & Miền
| Thực thể | Vai trò trong việc sinh |
|---|---|
ProductOption | Một trục tùy chọn sản phẩm biến đổi theo, sinh từ một trục đã khai báo (tên, khóa, thứ tự) |
ProductOptionValue | Một lựa chọn có thứ tự trên một trục, sinh từ các giá trị đã khai báo của trục |
ProductVariant | Một đơn vị bán được sinh ra; đúng một cái mỗi sản phẩm là mặc định |
ProductVariantOption | Một liên kết của một biến thể tới một cặp (trục, giá trị) - tập liên kết của biến thể là tổ hợp của nó |
Chỉ là khái niệm - schema và bất biến đầy đủ nằm trong mô hình miền commerce. Quan hệ là tham chiếu mềm; toàn vẹn được thực thi trong service sinh, không bởi ràng buộc cơ sở dữ liệu.
10. Phụ thuộc & Giả định
Phụ thuộc vào
- Mô hình liên kết tùy chọn (PRD-OPT-001, URD-OPT-001..010) - việc sinh tạo ra các liên kết mà mô hình này kiểm.
- Biến thể & tạo aggregate (VAR, PRD-PRD-001) - biến thể và bộ fare / định danh của chúng được tạo qua aggregate biến thể.
- Định danh (PID) - SYSTEM / SLUG tự sinh; SKU / BARCODE theo từng biến thể.
- Kho (Kho) - biến thể quản lý tồn sinh ra mục kho ở hạ nguồn.
@nx/search- phản chiếu tùy chọn và facet của mỗi biến thể để tra cứu.
Giả định
- Chủ khai báo những biến thể họ thực sự bán; hệ thống không suy ra toàn bộ ma trận.
- Cài đặt bắt buộc tùy chọn của merchant (từ PRD-OPT-001) được đọc khi sinh và quyết định liệu biến thể không tùy chọn có được phép.
11. Rủi ro & Câu hỏi Mở
| Rủi ro / câu hỏi | Giảm thiểu / trạng thái |
|---|---|
| Đồ thị sản phẩm dở dang khi lỗi (có trục nhưng không biến thể, không mặc định) | Toàn bộ đồ thị là một giao dịch liền mạch - bất kỳ lỗi nào rollback trọn vẹn |
| Hai biến thể đánh dấu mặc định | Từ chối trước khi lưu với lý do rõ ràng, cụ thể |
| Đụng độ barcode phát hiện muộn | Kiểm hai giai đoạn - trùng trong-yêu-cầu, rồi đụng độ merchant hiện hữu - trước khi lưu bất cứ gì |
| Tìm kiếm hiện facet tùy chọn cũ | Facet được làm tươi bởi cascade change-data khi trục, giá trị, và liên kết đổi |
| Chủ kỳ vọng ma trận tự sinh | Không-mục-tiêu cố ý (PRD-OPT-001); chỉ biến thể đã khai báo được sinh |
12. Kế hoạch Phát hành & Tiêu chí Ra mắt
| Khía cạnh | Kế hoạch |
|---|---|
| Phase | P2 - OPT trong danh mục tính năng URD, cùng VAR |
| Triển khai | Mọi merchant; không feature flag |
| Migration | Không - việc sinh chạy trên đường tạo aggregate sản phẩm hiện hữu |
| Tiêu chí ra mắt | Tạo sinh đúng những biến thể đã khai báo một cách liền mạch; luôn giải quyết một mặc định; hai mặc định và barcode trùng bị từ chối; thuộc tính kho chỉ xuất hiện cho loại quản lý tồn; biến thể được sinh lọc được theo facet tùy chọn trong tìm kiếm |
| Giám sát | Tỉ lệ lỗi tạo theo lý do (trùng mặc định, đụng độ barcode), độ trễ làm tươi facet tìm kiếm |
13. FAQ
Hệ thống có sinh mọi tổ hợp size × đá cho tôi không? Không - việc sinh là tường minh. Bạn khai báo những biến thể bạn bán và đúng những cái đó được tạo; không có dòng ảo để cắt tỉa. (Xem PRD-OPT-001 để biết lý do.)
Nếu tôi không đánh dấu một mặc định? Biến thể bạn khai báo đầu tiên được nâng thành mặc định tự động, nên một sản phẩm luôn có một cái.
Tôi có thể đánh dấu hai mặc định không? Không - một yêu cầu với nhiều hơn một mặc định tường minh bị từ chối trước khi lưu bất cứ gì. Đổi mặc định sau bằng thao tác nâng chuyên biệt.
Mọi loại biến thể có được theo dõi tồn không? Không - chỉ loại quản lý tồn sinh thuộc tính kho. Combo và loại không quản lý tồn (ví dụ dịch vụ) được tạo không theo dõi.
Khi nào tôi tìm được một biến thể mới theo tùy chọn của nó? Facet tùy chọn của mỗi biến thể được phản chiếu vào tìm kiếm sau khi tạo và giữ tươi bởi một cascade mỗi khi một trục, giá trị, hoặc liên kết đổi.
Tham chiếu
- URD: Sản phẩm - OPT · VAR · PID
- PRD anh em: Tùy chọn sản phẩm & liên kết biến thể · Danh mục sản phẩm, biến thể & định danh · Hệ thống Fare & Định giá
- Module: Sản phẩm - tổng quan + năng lực
- Lập trình viên: @nx/commerce · @nx/core · @nx/search