@cendo/database-schemas 2.1.9 → 2.2.0

package/schemas/OrderFulfillment.js

@@ -2,96 +2,121 @@ const {Schema} = require('mongoose')
 const TrackingObject = require('./types/TrackingObject')
 
 
+/**
+ * Item — Embedded sub-document for items in a fulfillment shipment.
+ */
 const Item = new Schema({
     _id: false,
 
+    /** Item ID from the fulfillment provider */
     external_id: {
         type: String,
         trim: true,
     },
 
+    /** SKU code in the fulfillment system */
     sku: {
         type: String,
         trim: true,
     },
 
+    /** Variant code in the fulfillment system */
     variant_code: {
         type: String,
         trim: true,
     },
 
+    /** Quantity of this item in the shipment */
     quantity: {
         type: Number,
     }
 })
 
+/**
+ * OrderFulfillment — Fulfillment/shipment records.
+ * Tracks production and shipping for orders sent to a fulfillment provider.
+ */
 const OrderFulfillment = new Schema({
+    /** Reference to the Shop */
     shop: {
         type: Schema.Types.ObjectId,
         index: true,
     },
 
+    /** Reference to the parent Order */
     order: {
         type: Schema.Types.ObjectId,
         index: true,
         required: true,
     },
 
+    /** Reference to the FulfillmentStore handling this shipment */
     fulfillment_store: {
         type: Schema.Types.ObjectId,
     },
 
+    /** Fulfillment/shipment number from the provider */
     number: {
         type: String,
         trim: true,
         index: true,
     },
 
+    /** Fulfillment ID from the provider's system */
     external_id: {
         type: String,
         trim: true,
     },
 
+    /** Current production status from the provider (e.g., 'in_production', 'shipped') */
     production_status: {
         type: String,
         trim: true,
         index: true,
     },
 
+    /** Shipping tracking information (embedded) */
     tracking: {
         type: TrackingObject,
     },
 
+    /** List of items included in this shipment (embedded) */
     items: {
         type: [Item],
         index: true,
     },
 
+    /** Whether tracking info has been imported back to the source platform */
     tracking_imported: {
         type: Boolean,
         default: false,
     },
 
+    /** Timestamp when tracking was requested from the carrier */
     request_tracking_at: {
         type: Date,
     },
 
+    /** Timestamp when this fulfillment was pushed to the provider */
     pushed_at: {
         type: Date,
         default: Date.now,
     },
 
+    /** Last sync timestamp from the fulfillment provider */
     synced_at: {
         type: Date,
         default: Date.now,
         index: true,
     },
 
+    /** Last modification timestamp */
     updated_at: {
         type: Date,
         default: Date.now
     },
 
+    /** Creation timestamp */
     created_at: {
         type: Date,
         default: Date.now,

package/schemas/OrderHistory.js

@@ -1,28 +1,36 @@
 const {Schema} = require('mongoose')
 
 
+/**
+ * OrderHistory — Audit log of actions performed on an order.
+ */
 const OrderHistory = new Schema({
+    /** Reference to the Order */
     order: {
         type: Schema.Types.ObjectId,
         index: true,
         required: true,
     },
 
+    /** Action identifier (e.g., 'validation_updated', 'fulfillment_created') */
     action: {
         type: String,
         trim: true,
         index: true,
     },
 
+    /** Human-readable description of the action */
     description: {
         type: String,
         trim: true,
     },
 
+    /** Additional context data for the action */
     meta: {
         type: Schema.Types.Mixed,
     },
 
+    /** Timestamp of the action */
     created_at: {
         type: Date,
         default: Date.now,
@@ -31,4 +39,3 @@ const OrderHistory = new Schema({
 })
 
 module.exports = OrderHistory
-

package/schemas/OrderItem.js

@@ -1,99 +1,122 @@
 const {Schema} = require('mongoose')
 
 
+/**
+ * OrderItem — Line items within an order.
+ * Each record represents a product/SKU purchased in an order.
+ */
 const OrderItem = new Schema({
+    /** Reference to the parent Order */
     order: {
         type: Schema.Types.ObjectId,
         required: true,
         index: true,
     },
 
+    /** Line item ID from the source platform */
     external_id: {
         type: String,
         trim: true,
         index: true,
     },
 
+    /** Internal SKU identifier */
     sku_id: {
         type: String,
         trim: true,
         index: true,
     },
 
+    /** Seller's own SKU code */
     seller_sku: {
         type: String,
         trim: true,
     },
 
+    /** Product display name */
     product_name: {
         type: String,
         trim: true,
     },
 
+    /** Variant description (e.g., size, color) */
     variant_name: {
         type: String,
         trim: true,
     },
 
+    /** Quantity ordered */
     quantity: {
         type: Number,
         default: 1,
     },
 
+    /** Internal note for this line item */
     note: {
         type: String,
         trim: true,
     },
 
+    /** Customer note or personalization text from platform */
     external_note: {
         type: String,
         trim: true,
     },
 
+    /** Engraving/personalization text for custom products */
     engrave_text: {
         type: String,
         trim: true,
     },
 
+    /** SKU code used by the fulfillment provider */
     fulfillment_sku: {
         type: String,
         trim: true,
     },
 
+    /** Customization/personalization job ID */
     customize_id: {
         type: String,
         trim: true,
     },
 
+    /** Number of attempts to sync mockup/design media */
     sync_media_attempts: {
         type: Number,
         default: 0,
     },
 
+    /** Last time media sync was attempted */
     last_sync_media_at: {
         type: Date,
     },
 
+    /** Reference to the Media record for the product mockup image */
     mockup: {
         type: Schema.Types.ObjectId,
         // ref: 'Media'
     },
 
+    /** Reference to the Media record for the print-ready design file */
     design: {
         type: Schema.Types.ObjectId,
         // ref: 'Media'
     },
 
+    /** External sync identifier for deduplication */
     sync_id: {
         type: String,
         trim: true,
     },
 
+    /** Last modification timestamp */
     updated_at: {
         type: Date,
         default: Date.now
     },
 
+    /** Creation timestamp */
     created_at: {
         type: Date,
         default: Date.now,

package/schemas/OrderLog.js

@@ -1,13 +1,19 @@
 const {Schema} = require('mongoose')
 
 
+/**
+ * OrderLog — Operational event logging for orders.
+ * Auto-deleted after 90 days via TTL index.
+ */
 const OrderLog = new Schema({
+    /** Reference to the Order */
     order: {
         type: Schema.Types.ObjectId,
         index: true,
         required: true,
     },
 
+    /** Log level: 'info' | 'warning' | 'error' */
     level: {
         type: String,
         trim: true,
@@ -15,21 +21,25 @@ const OrderLog = new Schema({
         enum: ['info', 'warning', 'error']
     },
 
+    /** Log category/source label */
     label: {
         type: String,
         trim: true,
         default: '',
     },
 
+    /** Log message content */
     message: {
         type: String,
         trim: true,
     },
 
+    /** Structured data associated with the log entry */
     meta: {
         type: Schema.Types.Mixed,
     },
 
+    /** Timestamp (TTL: 90 days) */
     created_at: {
         type: Date,
         default: Date.now,
@@ -39,4 +49,3 @@ const OrderLog = new Schema({
 })
 
 module.exports = OrderLog
-

package/schemas/Product.js

@@ -1,44 +1,66 @@
 const {Schema} = require('mongoose')
 
 
+/**
+ * Product — Product/SKU catalog.
+ * Maps seller SKUs to fulfillment SKUs and customization configs.
+ */
 const Product = new Schema({
+    /** Reference to the Shop this product belongs to */
     shop: {
         type: Schema.Types.ObjectId,
         index: true,
     },
 
+    /** Product display name */
     name: {
         type: String,
         trim: true,
     },
 
+    /** Primary SKU identifier */
     sku_id: {
         type: String,
         trim: true,
         index: true,
     },
 
+    /** Seller's own SKU code */
     seller_sku: {
         type: String,
         trim: true,
         index: true,
     },
 
+    /** SKU code used by the fulfillment provider */
     fulfillment_sku: {
         type: String,
         trim: true,
     },
 
+    /** URL to the customization/personalization tool */
     customize_url: {
         type: String,
         trim: true,
     },
 
+    /** SKU code in the customization system */
     customize_sku: {
         type: String,
         trim: true,
     },
 
+    /** Reference to the Media record for the product mockup image */
+    mockup: {
+        type: Schema.Types.ObjectId,
+    },
+
+    /** Reference to the Media record for the print-ready design file */
+    design: {
+        type: Schema.Types.ObjectId,
+    },
+
+    /** Product status (default 'active') */
     status: {
         type: String,
         trim: true,
@@ -46,11 +68,13 @@ const Product = new Schema({
         index: true
     },
 
+    /** Last modification timestamp */
     updated_at: {
         type: Date,
         default: Date.now
     },
 
+    /** Creation timestamp */
     created_at: {
         type: Date,
         default: Date.now,

package/schemas/ShippingCarrier.js

@@ -1,13 +1,18 @@
 const {Schema} = require('mongoose')
 
 
+/**
+ * ShippingCarrier — Shipping carrier master data.
+ */
 const ShippingCarrier = new Schema({
+    /** Display name of the carrier */
     name: {
         type: String,
         trim: true,
         required: true,
     },
 
+    /** Unique carrier code */
     code: {
         type: String,
         trim: true,
@@ -15,6 +20,7 @@ const ShippingCarrier = new Schema({
         index: true,
     },
 
+    /** Carrier status: 'active' | 'inactive' */
     status: {
         type: String,
         enum: ['active', 'inactive'],
@@ -22,11 +28,13 @@ const ShippingCarrier = new Schema({
         index: true,
     },
 
+    /** Last modification timestamp */
     updated_at: {
         type: Date,
         default: Date.now
     },
 
+    /** Creation timestamp */
     created_at: {
         type: Date,
         default: Date.now,

package/schemas/Shop.js

@@ -1,12 +1,18 @@
 const {Schema} = require('mongoose')
 
 
+/**
+ * Shop — Store/shop configuration.
+ * Represents a sales channel connected to the system.
+ */
 const Shop = new Schema({
+    /** Display name of the shop */
     name: {
         type: String,
         trim: true,
     },
 
+    /** Platform type (default 'tiktok') */
     type: {
         type: String,
         trim: true,
@@ -14,12 +20,14 @@ const Shop = new Schema({
         index: true,
     },
 
+    /** External shop/store ID on the platform */
     shop_id: {
         type: String,
         trim: true,
         index: true,
     },
 
+    /** Shop status (default 'active') */
     status: {
         type: String,
         trim: true,
@@ -27,30 +35,36 @@ const Shop = new Schema({
         index: true,
     },
 
+    /** Default FulfillmentStore assigned to this shop */
     fulfillment_store: {
         type: Schema.Types.ObjectId,
     },
 
+    /** Mapped shop ID in the Nhanh.vn system */
     nhanh_id: {
         type: String,
         trim: true,
         index: true,
     },
 
+    /** UI display color for the shop */
     color: {
         type: String,
         trim: true,
     },
 
+    /** Default ShippingCarrier for this shop */
     default_carrier: {
         type: Schema.Types.ObjectId,
     },
 
+    /** Last modification timestamp */
     updated_at: {
         type: Date,
         default: Date.now
     },
 
+    /** Creation timestamp */
     created_at: {
         type: Date,
         default: Date.now,
@@ -60,4 +74,3 @@ const Shop = new Schema({
 
 
 module.exports = Shop
-

package/schemas/ShopSetting.js

@@ -1,28 +1,37 @@
 const {Schema} = require('mongoose')
 
 
+/**
+ * ShopSetting — Key-value settings per shop.
+ * Stores dynamic configuration for a specific shop.
+ */
 const ShopSetting = new Schema({
+    /** Reference to the Shop */
     shop: {
         type: Schema.Types.ObjectId,
         required: true,
         index: true,
     },
 
+    /** Setting key name */
     key: {
         type: String,
         trim: true,
         index: true,
     },
 
+    /** Setting value (any type) */
     value: {
         type: Schema.Types.Mixed,
     },
 
+    /** Last modification timestamp */
     updated_at: {
         type: Date,
         default: Date.now
     },
 
+    /** Creation timestamp */
     created_at: {
         type: Date,
         default: Date.now,
@@ -32,4 +41,3 @@ const ShopSetting = new Schema({
 
 
 module.exports = ShopSetting
-

package/schemas/SourceItem.js

@@ -1,13 +1,19 @@
 const {Schema} = require('mongoose')
 
 
+/**
+ * SourceItem — Raw line item data from the source platform.
+ * Includes customization/personalization details for print-on-demand products.
+ */
 const SourceItem = new Schema({
+    /** Reference to the parent SourceOrder */
     order: {
         type: Schema.Types.ObjectId,
         required: true,
         index: true,
     },
 
+    /** Line item ID on the source platform */
     id: {
         type: String,
         trim: true,
@@ -15,61 +21,73 @@ const SourceItem = new Schema({
         required: true,
     },
 
+    /** Product name from the source platform */
     product_name: {
         type: String,
         trim: true,
     },
 
+    /** Variant name from the source platform */
     variant_name: {
         type: String,
         trim: true,
     },
 
+    /** SKU from the source platform */
     sku: {
         type: String,
         trim: true,
     },
 
+    /** Quantity ordered */
     quantity: {
         type: Number,
         default: 1,
     },
 
+    /** Raw line item properties/attributes from the platform */
     properties: {
         type: [Schema.Types.Mixed],
         default: []
     },
 
+    /** Parsed customization properties */
     customize_properties: {
         type: Schema.Types.Mixed,
         default: {}
     },
 
+    /** Customization job ID extracted from properties */
     customize_id: {
         type: String,
         trim: true,
     },
 
-    customize_item: {//Link to order item that was built design
+    /** Reference to the linked OrderItem for design processing */
+    customize_item: {
         type: Schema.Types.ObjectId,
         index: true,
     },
 
+    /** URL to the mockup image from the customization system */
     mockup_url: {
         type: String,
         trim: true,
     },
 
+    /** URL to the print-ready design file from the customization system */
     design_url: {
         type: String,
         trim: true,
     },
 
+    /** Last modification timestamp */
     updated_at: {
         type: Date,
         default: Date.now
     },
 
+    /** Creation timestamp */
     created_at: {
         type: Date,
         default: Date.now,