Seller Commerce OS

Seller Commerce OS gom Publisher, Vendor và Agency thành một mô hình Seller thống nhất. Một tài khoản không cần chọn vai trò cứng; họ bật capability theo nhu cầu kinh doanh.

Capability Model

Capability	Ý nghĩa
can_buy	Mua guest post, dịch vụ, sản phẩm, affiliate traffic
can_sell_products	Bán sản phẩm vật lý hoặc phi vật lý
can_sell_inventory	Bán website/media inventory/guest post slot
can_sell_services	Bán dịch vụ SEO, creative, video, ads, AI agent
can_manage_storefronts	Quản lý storefront marketplace, MatchingVietnam hoặc WordPress domain riêng

type cũ vẫn giữ để tương thích dữ liệu, nhưng UI và logic dài hạn ưu tiên capability.

Product Seller Verification

MCV chỉ bật can_sell_products cho người dùng đang thật sự sở hữu, sản xuất, phân phối được uỷ quyền, đang có tồn kho, hoặc trực tiếp cung cấp dịch vụ/sản phẩm số. Hệ thống không chấp nhận tài khoản chỉ đóng vai trò môi giới sản phẩm.

Trước khi đăng sản phẩm tại /seller/products, Seller phải gửi hồ sơ xác minh:

Trường	Mục đích
Quan hệ với sản phẩm	Xác định Seller là nhà sản xuất, chủ thương hiệu, nhà phân phối được uỷ quyền, chủ tồn kho hoặc nhà cung cấp dịch vụ trực tiếp
Nhóm sản phẩm dự kiến bán	Giúp admin hiểu phạm vi hàng hoá/dịch vụ cần duyệt
Loại bằng chứng	Đăng ký kinh doanh, giấy uỷ quyền, hoá đơn nhập hàng, ảnh tồn kho, giấy phép dịch vụ hoặc tài liệu tương đương
File bằng chứng	Tài liệu thật để admin đối chiếu
Cam kết không môi giới	Seller xác nhận họ có quyền bán và chịu trách nhiệm sau bán

Admin duyệt hồ sơ ở /admin/seller-product-verifications. Khi duyệt, hệ thống bật can_sell_products và Seller mới được tạo sản phẩm. Khi từ chối, quyền bán sản phẩm bị tắt nhưng Seller vẫn có thể cập nhật storefront hoặc gửi hồ sơ mới.

Logic kiểm tra nên ưu tiên bằng chứng có thể đối chiếu:

• tên pháp nhân/cá nhân trên hồ sơ khớp với profile Seller,
• sản phẩm/ngành hàng trong bằng chứng khớp với nhóm sản phẩm đăng bán,
• giấy uỷ quyền còn hiệu lực nếu Seller là distributor,
• hoá đơn/ảnh tồn kho thể hiện Seller đang có hàng hoặc quyền kiểm soát hàng,
• dịch vụ số/phần mềm cần mô tả cơ chế cấp quyền, bảo hành và hỗ trợ sau bán.

Product Catalog Direction

MatchingVietnam đang có module đăng bán sản phẩm. Business OS tận dụng module này theo hướng:

1. Port field-set và workflow vendor product từ Botble Ecommerce/Marketplace sang Business OS.
2. Business OS là nơi Seller tạo, sửa, xoá, duyệt và vận hành catalog.
3. MatchingVietnam tiếp tục là public storefront + SEO, không còn là vendor dashboard chính.
4. MatchingVietnam nhận dữ liệu publish/sync để hiển thị storefront.
5. Inquiry/order từ MatchingVietnam đồng bộ ngược về Seller inbox trong Business OS.

Catalog cần hỗ trợ:

• physical product,
• digital product,
• service package,
• media inventory,
• affiliate offer.

Seller Feature Structure

Seller workspace được quy hoạch thành ba nhóm chính.

Nhóm	Route	Vai trò
Sản phẩm bán	/seller/products	Đăng và quản lý sản phẩm vật lý, sản phẩm điện tử và dịch vụ
Kênh bán hàng	/seller/storefronts	Quản lý MCV marketplace storefront, MatchingVietnam storefront, WordPress domain riêng và portfolio
Danh sách đơn	/seller/orders	Inbox đơn bán đồng bộ từ các kênh storefront

1. Sản phẩm bán

Form sản phẩm của Business OS bám theo cách thiết lập của MatchingVietnam/Botble Ecommerce:

• Basic: name, description, content, image, SKU, barcode, brand.
• Pricing: price, sale price, cost per item, currency.
• Inventory: stock status, quantity, MOQ, maximum order quantity, storehouse management.
• Shipping: weight, length, wide, height cho sản phẩm vật lý.
• Digital delivery: eSIM QR, software invite, license, external access link, usage instructions, warranty.
• Service delivery: deliverables, turnaround, support terms.
• Publishing: draft, pending review, active, paused và publish targets.

Route vận hành hiện tại:

Route	Vai trò
/seller/products	Listing, filter theo loại sản phẩm, search SKU/brand/name
/seller/products/create	Tạo sản phẩm mới
/seller/products/{product}/edit	Sửa sản phẩm hiện có
PUT /seller/products/{product}	Cập nhật sản phẩm
DELETE /seller/products/{product}	Xoá sản phẩm khỏi Seller catalog

Mỗi lần tạo/cập nhật sản phẩm, metadata đánh dấu publish_targets = ["mcv_marketplace", "matchingvietnam"] và sync_status = pending để adapter đồng bộ sang MatchingVietnam public storefront xử lý ở bước sau.

Trong UI Seller, mỗi sản phẩm có:

• nút sửa sản phẩm,
• nút sync thủ công sang MatchingVietnam,
• trạng thái kênh MatchingVietnam (pending, synced, sync_failed),
• link mở public product page khi đã sync thành công,
• thông báo lỗi sync gần nhất để Seller hoặc admin biết cần sửa dữ liệu gì.

MatchingVietnam Outbound Sync

Business OS có command đẩy sản phẩm Seller sang MatchingVietnam:

php artisan market-access:push-matching --limit=50

Chế độ kiểm tra không ghi dữ liệu:

php artisan market-access:push-matching --dry-run --limit=10

Sync một sản phẩm cụ thể:

php artisan market-access:push-matching --product-id=123

Adapter hiện map:

Business OS	MatchingVietnam
business_profiles	mp_stores
market_access_products	ec_products
market_access_category_product	ec_product_category_product
product/store slug	slugs
outbound mapping	external_source_records với source_system=business_os

Adapter chỉ push sản phẩm source_system=business_os có publish_targets chứa matchingvietnam. Sản phẩm import từ MatchingVietnam không bị push ngược để tránh vòng lặp sync.

Currency policy:

• Business OS là nguồn dữ liệu giá gốc của Seller.
• MatchingVietnam/Botble không lưu currency riêng trên từng product, mà render theo currency mặc định toàn storefront.
• Adapter đặt MatchingVietnam target currency theo MCV_MARKET_ACCESS_TARGET_CURRENCY, mặc định VND.
• Khi product trong Business OS dùng currency khác, adapter quy đổi số tiền sang target currency trước khi ghi vào ec_products.price, sale_price và cost_per_item.
• Metadata sản phẩm lưu thêm matchingvietnam_currency để audit lần sync gần nhất.

Scheduler production chạy hai chiều:

Command	Lịch chạy	Vai trò
market-access:sync-matching	Mỗi giờ	Import category, store, product và inquiry từ MatchingVietnam về Business OS
market-access:push-matching --limit=50	Mỗi 10 phút	Publish sản phẩm Seller tạo từ Business OS sang MatchingVietnam

product_type chuẩn hóa thành:

Type	Ví dụ
physical	Hàng hoá, sample, sản phẩm xuất khẩu
digital	eSIM, phần mềm, tài khoản, license, file số
service	Marketing, thuế, pháp lý, thiết kế, video, AI agent

2. Kênh bán hàng

Portfolio không còn là menu riêng. Portfolio là một phần của storefront vì nó phục vụ buyer đánh giá năng lực Seller trước khi mua.

Kênh bán hàng gồm:

• MCV marketplace storefront,
• MatchingVietnam storefront,
• WordPress domain riêng,
• Seller portfolio/case studies.

3. Danh sách đơn

/seller/orders là unified seller order inbox. Trước mắt gom:

• guest post orders,
• service orders.

Các đơn phát sinh từ MatchingVietnam storefront hoặc WordPress storefront sẽ đồng bộ về cùng inbox này qua webhook/API trong phase tiếp theo.

WordPress Storefront Riêng

Seller có thể triển khai website riêng trên domain của họ bằng WordPress. Pattern tham khảo từ pkthientam.com:

• hero có trạng thái hoạt động, CTA và hình ảnh tin cậy,
• trust metrics,
• logo/proof strip,
• about section,
• service/product cards,
• why choose us,
• team/case proof,
• testimonials,
• contact/booking form,
• footer đầy đủ.

WordPress chỉ xử lý SEO, content và conversion. Khi người mua đặt hàng, đăng nhập, thanh toán hoặc cần compliance, flow quay về app.mcv.network.

Operational Flow

sequenceDiagram
    participant Seller
    participant BOS as app.mcv.network
    participant Matching as matchingvietnam.com
    participant WP as WordPress domain
    participant Buyer

    Seller->>BOS: Enable Seller workspace
    Seller->>BOS: Submit product ownership proof
    BOS->>BOS: Admin reviews no-broker evidence
    BOS-->>Seller: Approve can_sell_products
    Seller->>BOS: Configure catalog + storefront profile
    BOS->>Matching: Sync published products
    BOS->>WP: Provide content/CTA/order links
    Buyer->>Matching: Discover product by SEO
    Buyer->>WP: Review branded landing page
    Buyer->>BOS: Login, pay, order, escrow
    BOS->>Seller: Notify order and delivery workflow

Implementation Notes

• seller_storefronts stores storefront type, domain, WordPress admin URL, template reference, status and deployment notes.
• pkthientam.com is stored as the default WordPress template reference because it is a strong trust-first services storefront pattern.
• Marketplace routes such as publisher websites and agency services remain live for compatibility, but menu and account language should gradually move to Seller.