PRD: Địa điểm kho
| Module | Kho (CORE-06) | PRD ID | PRD-LOC-001 |
| Status | Shipped | Owner | Inventory squad |
| Date | 2026-05-21 | Version | v1.0 |
| Packages | @nx/core · apps/bo · apps/admin-ui-kit | URD | LOC |
TL;DR
Cung cấp cho merchant một bề mặt back-office để xem và quản lý các địa điểm kho - liệt kê mọi kho, tạo kho mới, sửa chúng, và chọn cái nào là mặc định - thay vì bị kẹt với một địa điểm tự tạo duy nhất. Một bộ chọn kho dùng lại được cho phép các màn hình back-office khác chọn hoặc tạo một địa điểm ngay tại chỗ. Kết quả: merchant cuối cùng có thể tổ chức tồn qua nhiều kho thông qua UI, không chỉ trong mô hình dữ liệu.
1. Bối cảnh & Vấn đề
Mô hình dữ liệu kho đã hỗ trợ địa điểm: một địa điểm mặc định được tự tạo cho mỗi merchant khi commerce init, mỗi địa điểm mang một tên i18n, một cờ mặc định, dữ liệu địa chỉ/GPS, và một định danh hệ thống (LOC_YYYYMMDD_id). Các endpoint tạo/liệt kê/cập nhật đã tồn tại. Cái còn thiếu là một bề mặt back-office để sử dụng chúng: merchant không thể xem các địa điểm của mình, tạo thêm địa điểm, hay đổi cái nào là mặc định thông qua UI.
Cho đến khi bề mặt đó tồn tại, việc tổ chức đa kho là vô hình với merchant dù backend đã hỗ trợ - một điểm chặn với các merchant lớn cần nhiều hơn một khu lưu trữ, và với bất kỳ màn hình back-office nào cần chọn hoặc tạo một địa điểm ngay tại chỗ.
2. Goals & Non-Goals
Goals
- Thêm một khu quản lý Địa điểm vào back-office (mục sidebar + route).
- Liệt kê các địa điểm kho cho merchant đang hoạt động, lọc được theo trạng thái.
- Tạo một địa điểm qua một form: tên i18n, công tắc mặc định, các trường địa chỉ/GPS.
- Sửa một địa điểm đang tồn tại, bao gồm chuyển cái nào là mặc định.
- Cung cấp một bộ chọn kho dùng lại được (input cơ sở + dialog tạo tại chỗ) cho các màn hình back-office khác, ship trong cả
apps/bovàapps/admin-ui-kit.
Non-Goals
- Thay đổi backend cho location model hoặc aggregate - các endpoint tạo/liệt kê/cập nhật đã tồn tại; đây là một increment UI.
- UX quản lý phân cấp địa điểm vượt khỏi những gì form phơi bày (URD-LOC-004).
- Màn hình inventory item, tồn, hay tracking - các tính năng riêng (ITM · STK · TRK).
- Đấu nối kênh bán ↔ địa điểm (thuộc về phần commerce allocation).
3. Success Metrics
| Metric | Mục tiêu / tín hiệu |
|---|---|
| Tự phục vụ | Merchant có thể tạo và sửa địa điểm mà không cần can thiệp backend/hỗ trợ |
| Toàn vẹn mặc định | Đúng một địa điểm mặc định cho mỗi merchant sau bất kỳ chỉnh sửa nào; đặt mặc định mới sẽ xóa cái trước |
| Dùng lại | Bộ chọn kho được các màn hình back-office khác (cần chọn/tạo một địa điểm) tiếp nhận |
| Độ phủ | Mọi địa điểm đang tồn tại (kể cả mặc định tự tạo) đều hiển thị và sửa được trong danh sách |
4. Personas & Use Cases
| Persona | Mục tiêu trong tính năng này |
|---|---|
| Chủ / Quản lý | Xem mọi kho, thêm kho mới, đặt mặc định, giữ địa chỉ/GPS chính xác |
| Người dùng back-office (màn hình khác) | Chọn một địa điểm đang có - hoặc tạo tại chỗ - mà không rời màn hình hiện tại |
Core scenarios: mở khu Địa điểm → xem danh sách cho merchant đang hoạt động → tạo một địa điểm mới với tên i18n và công tắc mặc định → sửa một địa điểm và chuyển mặc định → từ một màn hình khác, dùng bộ chọn kho để chọn hoặc tạo-tại-chỗ một địa điểm.
5. User Stories
- Là một chủ, tôi muốn thấy mọi địa điểm kho trong một danh sách, để biết những kho nào tồn tại và cái nào là mặc định.
- Là một chủ, tôi muốn tạo một địa điểm với tên i18n và dữ liệu địa chỉ/GPS, để tổ chức tồn qua nhiều kho.
- Là một chủ, tôi muốn sửa một địa điểm và chuyển mặc định, để đúng kho được dùng làm mặc định ở mọi nơi.
- Là một chủ, tôi muốn lọc địa điểm theo trạng thái, để tập trung vào các kho đang hoạt động.
- Là một người dùng back-office, tôi muốn chọn hoặc tạo-tại-chỗ một địa điểm từ bên trong một màn hình khác, để không phải gián đoạn luồng làm việc để thiết lập một địa điểm.
6. Functional Requirements
| # | Yêu cầu | URD ref |
|---|---|---|
| FR-1 | Khu quản lý Địa điểm trong back-office (mục sidebar + route liệt kê/tạo/sửa) | URD-LOC-009 |
| FR-2 | Liệt kê các địa điểm kho cho merchant đang hoạt động, lọc được theo trạng thái | URD-LOC-009 · URD-LOC-010 |
| FR-3 | Tạo một địa điểm với tên i18n | URD-LOC-001 |
| FR-4 | Tạo/sửa thu thập dữ liệu địa chỉ và địa lý (GPS) | URD-LOC-005 |
| FR-5 | Công tắc mặc định: đúng một mặc định cho mỗi merchant; đặt mặc định mới sẽ xóa cái trước | URD-LOC-003 |
| FR-6 | Sửa một địa điểm đang tồn tại, bao gồm chuyển mặc định | URD-LOC-001 · URD-LOC-003 |
| FR-7 | Mọi màn hình hoạt động trong merchant đang hoạt động (cô lập theo từng merchant) | URD-LOC-010 |
| FR-8 | Bộ chọn kho dùng lại được (input cơ sở + dialog tạo tại chỗ) cho các màn hình back-office khác | URD-LOC-001 |
| FR-9 | Phơi bày các trường do backend cưỡng chế ở chế độ chỉ-đọc: định danh hệ thống, vòng đời, soft-delete | URD-LOC-006..008 |
Toàn văn yêu cầu và tiêu chí chấp nhận nằm trong Inventory URD. PRD này tham chiếu chúng thay vì lặp lại.
7. Non-Functional Requirements
| Lĩnh vực | Yêu cầu |
|---|---|
| Tenancy & authz | Mọi màn hình địa điểm hoạt động trong merchant đang hoạt động (x-merchant-id); được kiểm soát bởi permission của inventory |
| Toàn vẹn dữ liệu | Công tắc mặc định loại trừ lẫn nhau theo từng merchant - UI không bao giờ để lại không hoặc hai mặc định |
| Dùng lại | Bộ chọn kho ship một lần và được tiêu thụ bởi cả apps/bo và apps/admin-ui-kit |
| Nhất quán | Các trường hệ thống chỉ-đọc (định danh, vòng đời, soft-delete) được phơi bày nhưng không sửa được trong UI |
| i18n | Tên địa điểm song ngữ ({ en, vi }); mọi nhãn UI được bản địa hóa |
8. UX & Flows
Màn hình chính (trong apps/bo): Danh sách Địa điểm, tạo, và sửa, dựng trên một form địa điểm dùng chung và một công tắc địa-điểm-mặc-định. Bộ chọn kho dùng lại được (input cơ sở + dialog tạo tại chỗ) ship trong cả apps/bo và apps/admin-ui-kit để các màn hình khác có thể chọn hoặc tạo-tại-chỗ một địa điểm.
9. Data & Domain
| Entity | Vai trò |
|---|---|
InventoryLocation | Bản ghi kho/khu lưu trữ - tên i18n, cờ mặc định, địa chỉ/GPS, định danh hệ thống, vòng đời, soft-delete |
| Cờ mặc định | Tối đa một địa điểm gắn cờ mặc định cho mỗi merchant; form trỏ lại nó khi chuyển |
Chỉ là khái niệm - toàn bộ schema và bất biến trong inventory domain model.
10. Dependencies & Assumptions
Phụ thuộc vào
- Location API (URD-LOC-001..010) - các endpoint tạo/liệt kê/cập nhật mà UI này điều khiển đã tồn tại trong backend.
- Commerce / Merchant - địa điểm thuộc về một merchant; merchant đang hoạt động định phạm vi mọi màn hình.
@nx/core- chuỗi locale back-office và đấu nối app dùng chung.
Giả định
- Mỗi merchant đã có địa điểm mặc định tự tạo (URD-LOC-002) hiển thị trong danh sách.
- Vòng đời, định danh hệ thống, và soft-delete được backend cưỡng chế; UI chỉ phơi bày chúng.
11. Risks & Open Questions
| Rủi ro / câu hỏi | Giảm thiểu / trạng thái |
|---|---|
| Công tắc mặc định có thể tạm thời để lại không hoặc hai mặc định | Backend cưỡng chế đúng một mặc định; đặt mặc định mới sẽ xóa cái trước |
| UX phân cấp không được phơi bày vượt khỏi form | Ngoài phạm vi increment này; URD-LOC-004 theo dõi riêng |
| Bộ chọn kho bị trùng lặp qua các bề mặt | Ship một lần, dùng lại trong cả apps/bo và apps/admin-ui-kit |
| Sửa một địa điểm đã soft-delete / archived | Vòng đời chỉ-đọc được phơi bày; các trạng thái cuối không sửa được |
12. Release Plan & Launch Criteria
| Khía cạnh | Kế hoạch |
|---|---|
| Phase | P1 (nền tảng) - xem URD feature catalog |
| Rollout | Tất cả merchant; không feature flag; phát hành front-end back-office một-pha |
| Migration | Không - increment UI trên một Location API đang tồn tại; không thay đổi backend/model |
| Launch criteria | Liệt kê/tạo/sửa được kiểm chứng end-to-end; công tắc mặc định trỏ lại đúng; bộ chọn kho hoạt động trong cả hai app |
| Monitoring | Khối lượng tạo/sửa địa điểm theo từng merchant; kiểm tra toàn-vẹn-mặc-định (một mặc định cho mỗi merchant) |
13. FAQ
Cái này có thay đổi backend của địa điểm không? Không - các endpoint tạo/liệt kê/cập nhật đã tồn tại. Increment này chỉ thêm UI back-office trên API đó.
Địa điểm mặc định được xử lý thế nào? Đúng một mặc định cho mỗi merchant; đặt mặc định mới qua form sửa sẽ xóa cái trước. Backend cưỡng chế bất biến này.
Tôi có thể dựng phân cấp địa điểm ở đây không? Chỉ những gì form phơi bày. UX quản lý phân cấp đầy đủ (URD-LOC-004) ngoài phạm vi increment này.
Bộ chọn kho có thể dùng ở đâu? Bất kỳ màn hình back-office nào cần chọn hoặc tạo-tại-chỗ một địa điểm - nó ship trong cả apps/bo và apps/admin-ui-kit.
Tôi có thể sửa định danh hệ thống hay vòng đời không? Không - định danh (LOC_YYYYMMDD_id), vòng đời, và soft-delete do backend cưỡng chế và phơi bày chỉ-đọc.
References
- URD: Kho - Địa điểm (LOC)
- Liên quan: Mục kho · Mức tồn · Audit trail biến động
- Module: Kho - tổng quan + truy vết
- Developer: @nx/inventory · domain model