PRD: Quản lý asset & media
| Module | Nền tảng (CORE-16) | PRD ID | PRD-AST-001 |
| Status | Shipped | Owner | Phát Nguyễn |
| Date | 2026-06-15 | Version | v1.0 |
| Năng lực | Lưu trữ media · dữ liệu tham chiếu | URD | AST · MTL · BNK |
TL;DR
Một cách dùng chung cho mọi service của BANA để lưu, định địa chỉ và phục vụ media nhị phân - ảnh sản phẩm, logo organizer, tài liệu - trên object storage: một upload đã xác thực đặt mỗi tệp dưới một tên duy nhất, an toàn URL và ghi một bản ghi media bền vững (tọa độ lưu trữ, kiểu nội dung, dung lượng, dấu vân toàn vẹn, kèm một ràng buộc tùy chọn tới thực thể nó thuộc về), nên mọi object tìm được theo chủ của nó và stream inline hoặc tải về theo tên. Cùng backbone đó còn phục vụ một bundle bản địa hóa dùng chung và một registry ngân hàng Việt Nam chỉ đọc kèm logo, để storefront và back office hiển thị lựa chọn ngân hàng và bản dịch từ cùng một nguồn.
1. Bối cảnh & Vấn đề
Mỗi module sản phẩm đều cần đính kèm media - ảnh cho product và variant, logo cho organizer, tài liệu hỗ trợ cho ledger và ticket - còn storefront cần logo ngân hàng và một bundle bản dịch dùng chung. Không có backbone dùng chung, mỗi service sẽ tự dựng đường upload riêng, cách đặt tên object riêng, và cách riêng để nhớ tệp nào thuộc bản ghi nào, còn dữ liệu tham chiếu ngân hàng thì bị copy-paste cho đến khi lệch nhau.
Khoảng trống có hai phần. Thứ nhất, một primitive lưu và truy lại: đặt một tệp nhị phân xuống, lấy lại một link ổn định, và giữ một bản ghi bền vững gắn object với thực thể nó minh họa - để catalogue tìm được "ảnh cho variant này" mà không phải quét toàn bộ lưu trữ. Thứ hai, media tham chiếu dùng chung: một bundle bản địa hóa và một registry ngân hàng Việt Nam (kèm logo) mà cả nền tảng cùng đọc, thay vì mỗi app mang một bản sao riêng.
PRD này đặc tả backbone đó: upload đã xác thực lên object storage với một bản ghi media cho mỗi object, ràng buộc chủ sở hữu và một API truy vấn bản ghi media, phục vụ và liệt kê công khai, bundle bản địa hóa, và registry ngân hàng cùng các endpoint logo.
2. Mục tiêu & Ngoài mục tiêu
Mục tiêu
- Một upload multipart đã xác thực lên một bucket lưu trữ đã cấu hình, gán cho mỗi tệp một object name duy nhất, an toàn URL, và trả về một link có thể định địa chỉ (
AST). - Một bản ghi media cho mỗi object đã lưu, ghi lại tọa độ lưu trữ, kiểu nội dung, dung lượng, dấu vân toàn vẹn, metadata, và storage type của nó (
MTL). - Ràng buộc chủ sở hữu ngay lúc upload - một object có thể mang owner type / owner id / variant để tìm được theo thực thể nó thuộc về (
MTL). - Phục vụ công khai: stream một object inline theo tên, tải về dạng attachment, và liệt kê một bucket theo prefix; kèm thao tác delete xóa cả object lẫn bản ghi media cùng lúc (
AST). - Một bundle bản địa hóa dùng chung, phục vụ inline và tải về được từ bucket đã cấu hình (
AST). - Một registry ngân hàng Việt Nam chỉ đọc dạng dữ liệu có cấu trúc - mỗi entry kèm tên, cờ năng lực, và một logo URL tuyệt đối - cùng một endpoint ảnh logo theo từng ngân hàng (
BNK). - Định địa chỉ an toàn: object name / độ sâu thư mục được kiểm tra, tên tệp logo nghiêm ngặt, header phản hồi nằm trong danh sách trắng, và tắt content-type sniffing trên mọi stream (
AST,BNK).
Ngoài mục tiêu
- Biến đổi ảnh, tạo thumbnail, hoặc resize động - object được phục vụ đúng như đã lưu.
- Cô lập bucket theo từng merchant hoặc lưu trữ giới hạn theo tenant - một bucket cấu hình duy nhất phục vụ service chủ.
- Một UI duyệt thư viện media có quản lý - PRD này cung cấp bề mặt API, không phải màn hình gallery.
- Soạn hoặc sửa registry ngân hàng - đây là dữ liệu tham chiếu chỉ đọc đóng gói cùng service.
- Pipeline thông báo real-time (ACT, WSS) - đặc tả trong PRD-ACT-001.
3. Chỉ số thành công
| Chỉ số | Mục tiêu / tín hiệu |
|---|---|
| Toàn vẹn upload | Mọi object lưu thành công đều có một bản ghi media khớp với dung lượng, kiểu nội dung, và dấu vân toàn vẹn của nó |
| Khả năng tìm | Một object upload kèm ràng buộc chủ sở hữu lấy được theo type + id của chủ đó |
| An toàn đặt tên | Không object name nào trùng hoặc mang đường dẫn không an toàn; mọi stream đều tắt content-type sniffing |
| Tái dùng tham chiếu | Storefront và back office hiển thị lựa chọn và logo ngân hàng từ một registry duy nhất, không phải bản sao cục bộ |
| Toàn vẹn dọn dẹp | Xóa một object không để lại bản ghi media mồ côi cho bucket + object đó |
4. Nhân vật & Tình huống
| Nhân vật | Mục tiêu trong tính năng |
|---|---|
| Owner / Manager | Đính một ảnh vào product hoặc một logo vào organizer và hiển thị nó ở mọi nơi thực thể đó xuất hiện |
| Service tạo sự kiện | Upload một object, ràng buộc nó với một bản ghi, và về sau truy lại media của bản ghi qua bản ghi media |
| Storefront / client | Stream một ảnh theo tên, hiển thị lựa chọn và logo ngân hàng, và tải bundle bản dịch dùng chung |
| Người vận hành nền tảng | Tin rằng object name an toàn và thao tác delete dọn cả lưu trữ lẫn metadata |
Tình huống cốt lõi: một manager thêm một ảnh khi sửa một variant. Client upload tệp kèm owner type và owner id của variant; service lưu nó dưới một tên duy nhất, trả về link, và ghi một bản ghi media lưu lại object và ràng buộc của nó. Bất cứ đâu variant đó xuất hiện về sau, media của nó được truy lại qua bản ghi. Tách biệt với luồng đó, màn hình checkout lấy registry ngân hàng một lần và hiển thị mỗi nhà cung cấp kèm logo URL tuyệt đối.
5. User Stories
- Là một manager, tôi đính một ảnh vào một product và nó xuất hiện ở mọi nơi product hiện ra, để catalogue trông hoàn chỉnh.
- Là một service tạo sự kiện, tôi ràng buộc một object đã upload với bản ghi nó minh họa, để về sau tìm được media của bản ghi mà không phải quét toàn bộ lưu trữ.
- Là một client, tôi stream một ảnh theo object name và tải một tài liệu dạng attachment, để media cứ thế hoạt động trong UI.
- Là một client, tôi đọc một registry ngân hàng kèm logo URL tuyệt đối, để hiển thị lựa chọn thanh toán mà không phải tự nối đường dẫn.
- Là một người vận hành, tôi xóa một object và yên tâm rằng bản ghi media của nó cũng được dọn, để không còn gì bị bỏ sót.
- Là một client, tôi tải một bundle bản địa hóa dùng chung, để mọi bề mặt dịch từ cùng một nguồn.
6. Yêu cầu chức năng
| # | Yêu cầu | URD ref |
|---|---|---|
| FR-1 | Upload multipart đã xác thực lưu một hoặc nhiều tệp trong bucket đã cấu hình, mỗi cái dưới một object name duy nhất an toàn URL, trả về object name và link định địa chỉ của nó | URD-AST-001 |
| FR-2 | Một upload có thể mang một folder path (được kiểm tra, tối đa hai cấp) và một ràng buộc chủ sở hữu (owner type / owner id / variant) | URD-AST-002 · URD-MTL-002 |
| FR-3 | Sau khi lưu thành công, một bản ghi media được tạo cho mỗi object, lưu bucket, object name, link, kiểu nội dung, dung lượng, dấu vân toàn vẹn, metadata, storage type, và cờ sync | URD-MTL-001 |
| FR-4 | Một object đã lưu stream inline theo object name; đường dẫn object lồng tối đa hai cấp thư mục được hỗ trợ | URD-AST-003 |
| FR-5 | Một object đã lưu tải về dạng attachment theo object name | URD-AST-004 |
| FR-6 | Một thao tác delete đã xác thực xóa object khỏi lưu trữ và dọn các bản ghi media của nó cho bucket + object đó | URD-AST-005 · URD-MTL-004 |
| FR-7 | Một thao tác list đã xác thực trả về các object của một bucket, lọc theo prefix tên, độ sâu, và một giới hạn số kết quả | URD-AST-006 |
| FR-8 | Một bundle bản địa hóa dùng chung phục vụ inline và tải về được dạng attachment từ bucket đã cấu hình | URD-AST-007 |
| FR-9 | Bản ghi media được cung cấp dưới dạng một tài nguyên quản lý tạo/đọc/cập nhật/xóa đầy đủ (list, get-by-id, get-one, count, create, update, delete), đã xác thực | URD-MTL-003 |
| FR-10 | Registry ngân hàng Việt Nam phục vụ dạng dữ liệu có cấu trúc - mỗi entry với tên ngắn, tên đầy đủ, cờ năng lực (VietQR, disburse, NAPAS), và một logo URL tuyệt đối | URD-BNK-001..002 |
| FR-11 | Mỗi logo ngân hàng phục vụ dạng ảnh theo một tên tệp logo nghiêm ngặt theo từng ngân hàng, kiểm tra theo mẫu đó, với caching immutable lâu dài | URD-BNK-003 |
| FR-12 | Object name, folder path, và tên tệp logo đều được kiểm tra; chỉ các header metadata trong danh sách trắng được phản chiếu và content-type sniffing bị tắt trên mọi stream | URD-AST-008 · URD-BNK-004 |
Toàn văn yêu cầu và tiêu chí chấp nhận nằm trong Platform URD - AST · MTL · BNK. PRD này tham chiếu chúng thay vì lặp lại.
7. Yêu cầu phi chức năng
| Lĩnh vực | Yêu cầu |
|---|---|
| An toàn đặt tên | Object name là duy nhất và an toàn URL; độ sâu thư mục bị giới hạn và mọi segment đường dẫn được kiểm tra trước khi lưu hoặc lấy |
| Vệ sinh header | Chỉ các header metadata trong danh sách trắng được phản chiếu lên phản hồi; content-type sniffing luôn bị tắt; giá trị header bị loại bỏ ký tự xuống dòng |
| Trừu tượng lưu trữ | Lưu trữ được truy cập qua một lớp trừu tượng lưu trữ duy nhất, cấu hình từ môi trường (endpoint, access key, secret key, bucket) |
| Khả năng phục hồi | Một bản ghi media ghi lỗi không làm mất object đã lưu - object được báo cáo kèm lỗi bản ghi media theo từng tệp; việc dọn bản ghi media khi delete chạy theo cơ chế best-effort và được log |
| Caching | Registry ngân hàng cache được; logo ngân hàng phục vụ immutable với cache lifetime dài |
| Xác thực | Upload, delete, list, và API quản lý bản ghi media đều cần xác thực; đọc object, bundle bản địa hóa, và registry / logo ngân hàng là đọc công khai |
| i18n | Tên hiển thị ngân hàng và bundle bản địa hóa dùng chung là nguồn bản địa hóa; entry ngân hàng mang cả tên ngắn lẫn tên đầy đủ |
8. UX & Luồng
Bề mặt upload nhận một hoặc nhiều tệp kèm một folder path tùy chọn và một ràng buộc chủ sở hữu, trả về object name, link, và bản ghi media (hoặc lỗi bản ghi media) của mỗi object. Thao tác đọc stream theo tên inline hoặc dạng download; một bucket liệt kê được theo prefix. Registry ngân hàng và logo theo từng ngân hàng được lấy thẳng vào UI.
9. Dữ liệu & Miền
| Thực thể | Vai trò |
|---|---|
| Bản ghi media | Bản ghi bền vững của một object đã lưu - bucket, object name, link, kiểu nội dung, dung lượng, dấu vân toàn vẹn, metadata, storage type, cờ sync - cùng một ràng buộc chủ sở hữu tùy chọn (owner type, owner id, variant) |
| Stored object | Tệp nhị phân trong bucket đã cấu hình, định địa chỉ theo object name và truy cập qua link của nó |
| Bank registry entry | Một bản ghi tham chiếu chỉ đọc - tên ngắn, tên đầy đủ, cờ năng lực (VietQR, disburse, NAPAS), và một logo - đóng gói cùng service |
Chỉ mang tính khái niệm - toàn bộ schema và bất biến nằm trong asset domain model. Quan hệ chủ sở hữu là soft reference phân giải theo type + id, không phải khóa ngoại database.
10. Phụ thuộc & Giả định
Phụ thuộc vào
- Object storage - một endpoint, access key, secret key, và một bucket mặc định được cấu hình trong môi trường.
- Lõi nền tảng - sở hữu định nghĩa bản ghi media, registry owner-type, và các environment key dùng chung.
- Một public base URL đã cấu hình - dùng để chuyển các đường dẫn logo ngân hàng tương đối thành URL tuyệt đối cho client.
Giả định
- Service tạo sự kiện biết owner type / owner id của bản ghi mà nó đang đính media.
- Bundle bản địa hóa và các asset logo ngân hàng Việt Nam có sẵn trong bucket đã cấu hình / đóng gói cùng service.
- Một bucket cấu hình duy nhất là đủ cho service chủ; việc cô lập đa bucket / theo từng tenant nằm ngoài phạm vi ở đây.
11. Rủi ro & Câu hỏi mở
| Rủi ro / câu hỏi | Giảm thiểu / trạng thái |
|---|---|
| Object đã lưu nhưng bản ghi media ghi lỗi | Object không bị mất - được trả về kèm lỗi bản ghi media theo từng tệp và được log để đối soát |
| Object name không an toàn hoặc trùng | Tên được tạo duy nhất và an toàn URL; độ sâu thư mục bị giới hạn và segment được kiểm tra; thao tác đọc từ chối đường dẫn không hợp lệ |
| Ủy quyền quản lý bản ghi media hiện còn dễ dãi | Follow-up đã biết - việc siết API bản ghi media về đúng tập permission của nó đang được theo dõi (URD-CON-005) |
| Path traversal qua logo ngân hàng | Tên tệp logo phải khớp một mẫu nghiêm ngặt theo từng ngân hàng; bất cứ gì khác bị từ chối trước khi truy cập đĩa |
| Registry ngân hàng lệch nhau giữa các app | Một registry chỉ đọc duy nhất phục vụ từ một nguồn; các app ngừng mang bản sao cục bộ |
12. Kế hoạch phát hành & Tiêu chí ra mắt
| Khía cạnh | Kế hoạch |
|---|---|
| Phase | P2 - AST, MTL, BNK trong URD feature catalog |
| Rollout | Được mount bởi các service chủ cần media; không feature flag |
| Migration | Không - kho bản ghi media và các asset ngân hàng đóng gói ship cùng service |
| Tiêu chí ra mắt | Upload lưu object kèm một bản ghi media và ràng buộc tùy chọn; object stream inline và tải theo tên; delete dọn cả lưu trữ lẫn bản ghi media; registry ngân hàng trả về entry kèm logo URL tuyệt đối và logo phục vụ dạng ảnh |
| Giám sát | Tỷ lệ lỗi upload, tỷ lệ bản ghi media ghi lỗi, độ nhất quán giữa object và bản ghi, hành vi cache hit của registry / logo |
13. FAQ
Tệp upload đi đâu? Vào bucket lưu trữ đã cấu hình, mỗi cái dưới một tên duy nhất, an toàn URL, kèm một link định địa chỉ trả về cho caller.
Làm sao tìm media cho một product hoặc variant cụ thể? Ràng buộc object lúc upload với owner type và owner id của nó; bản ghi media khi đó giúp tìm được nó theo thực thể đó qua API truy vấn.
Nếu không ghi được bản ghi media sau khi tệp đã lưu thì sao? Object không bị mất - kết quả upload đánh dấu tệp đó kèm một lỗi bản ghi media để đối soát; các tệp khác trong cùng upload không bị ảnh hưởng.
Object upload có công khai không? Đọc object, bundle bản địa hóa, và registry / logo ngân hàng là công khai; upload, delete, list, và API quản lý bản ghi media đều cần xác thực.
Tôi có sửa được registry ngân hàng không? Không - đây là dữ liệu tham chiếu chỉ đọc đóng gói cùng service, mỗi entry được chiếu kèm một logo URL tuyệt đối để client dùng trực tiếp.
Xóa một object có để lại bản ghi của nó không? Không - một thao tác delete xóa object khỏi lưu trữ và dọn các bản ghi media của nó cho bucket + object đó.
Trang liên quan
- URD: Platform - AST · MTL · BNK
- PRD anh em: Activity notifications & realtime push
- Module: Nền tảng - URD
- Developer: @nx/asset · storage · meta-links · @nx/core