@cendo/database-schemas 2.1.8 → 2.2.0

package/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(git push:*)"
+    ]
+  }
+}

package/CLAUDE.md

@@ -119,6 +119,8 @@ index.js              # Exports path to schemas/ directory
 
 ## Schema Catalog
 
+> Field-level descriptions are documented as JSDoc comments directly in each schema file.
+
 ### Orders & Fulfillment
 - **Order** — Main order entity (order_id, type, shop, fulfillment_status, validation_status, amount, shipping_address). Compound indexes on (order_id, type), (shipping_address.username), (shipping_address.email), (logistic_data.tracking_number), (fulfillments.number)
 - **OrderItem** — Line items in orders (order, sku_id, product_name, quantity, fulfillment_sku, customize_id, mockup, design). Compound indexes on (order, sku_id) and (order, sync_id)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cendo/database-schemas",
-  "version": "2.1.8",
+  "version": "2.2.0",
   "description": "",
   "main": "index.js",
   "keywords": [],

package/schemas/CarrierSetting.js

@@ -1,28 +1,37 @@
 const {Schema} = require('mongoose')
 
 
+/**
+ * CarrierSetting — Key-value settings per shipping carrier.
+ * Stores carrier-specific configuration (e.g., API credentials, routing rules).
+ */
 const CarrierSetting = new Schema({
+    /** Reference to the ShippingCarrier */
     shipping_carrier: {
         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 CarrierSetting = new Schema({
 
 
 module.exports = CarrierSetting
-

package/schemas/FulfillmentStore.js

@@ -1,12 +1,18 @@
 const {Schema} = require('mongoose')
 
 
+/**
+ * FulfillmentStore — Fulfillment provider/warehouse configuration.
+ * Stores API credentials and identifiers for connecting to fulfillment providers.
+ */
 const FulfillmentStore = new Schema({
+    /** Display name of the fulfillment provider */
     name: {
         type: String,
         trim: true,
     },
 
+    /** Provider status: 'active' | 'inactive' */
     status: {
         type: String,
         enum: ['active', 'inactive'],
@@ -14,31 +20,37 @@ const FulfillmentStore = new Schema({
         index: true,
     },
 
+    /** API authentication key for the provider */
     api_key: {
         type: String,
         trim: true,
     },
 
+    /** Base URL of the provider's API */
     api_url: {
         type: String,
         trim: true,
     },
 
+    /** Store/account ID on the provider's system */
     store_id: {
         type: String,
         trim: true,
     },
 
+    /** Team ID on the provider's system */
     team_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/ImportFile.js

@@ -1,17 +1,24 @@
 const {Schema} = require('mongoose')
 
 
+/**
+ * ImportFile — Bulk import file tracking.
+ * A container for imported rows from a CSV/Excel upload.
+ */
 const ImportFile = new Schema({
+    /** Original filename of the imported file */
     name: {
         type: String,
         trim: true,
     },
 
+    /** Last modification timestamp */
     updated_at: {
         type: Date,
         default: Date.now
     },
 
+    /** Creation timestamp */
     created_at: {
         type: Date,
         default: Date.now
@@ -19,4 +26,3 @@ const ImportFile = new Schema({
 })
 
 module.exports = ImportFile
-

package/schemas/ImportRow.js

@@ -1,29 +1,38 @@
 const {Schema} = require('mongoose')
 
 
+/**
+ * ImportRow — Individual rows from a bulk import.
+ * Auto-deleted after 12 months via TTL index.
+ */
 const ImportRow = new Schema({
+    /** Reference to the parent ImportFile */
     file: {
         type: Schema.Types.ObjectId,
         index: true,
         required: true
     },
 
+    /** Row/line number in the import file */
     line: {
         type: Number,
         required: true
     },
 
+    /** Deduplication key for this row */
     unique_id: {
         type: String,
         required: true,
         trim: true,
     },
 
+    /** Raw row data from the import file */
     data: {
         type: Schema.Types.Mixed,
         default: {}
     },
 
+    /** Processing status: 'pending' | 'completed' | 'failed' | 'cancelled' */
     status: {
         type: String,
         default: 'pending',
@@ -31,10 +40,12 @@ const ImportRow = new Schema({
         index: true
     },
 
+    /** Last modification timestamp */
     updated_at: {
         type: Date,
     },
 
+    /** Creation timestamp (TTL: 12 months) */
     created_at: {
         type: Date,
         default: Date.now

package/schemas/Label.js

@@ -1,60 +1,75 @@
 const {Schema} = require('mongoose')
 
 
+/**
+ * Label — Shipping label records.
+ * Tracks label generation, storage, and push status to the source platform.
+ */
 const Label = new Schema({
+    /** Reference to the Order */
     order: {
         type: Schema.Types.ObjectId,
         ref: 'Order',
         index: true,
     },
 
+    /** External order ID for lookup */
     order_id: {
         type: String,
         trim: true,
         index: true,
     },
 
+    /** Tracking number printed on the label */
     tracking_number: {
         type: String,
         trim: true,
         index: true,
     },
 
+    /** Carrier name/code for this label */
     carrier: {
         type: String,
         trim: true,
     },
 
+    /** Public URL to download/view the label */
     url: {
         type: String,
         trim: true,
     },
 
+    /** Internal file storage path for the label */
     path_file: {
         type: String,
         trim: true,
     },
 
+    /** Label status (e.g., 'created', 'printed') */
     status: {
         type: String,
         trim: true,
         index: true,
     },
 
+    /** Whether this label has been pushed to the source platform */
     is_pushed: {
         type: Boolean,
         default: false,
     },
 
+    /** Timestamp when the label was pushed to the platform */
     pushed_at: {
         type: Date,
     },
 
+    /** Last modification timestamp */
     updated_at: {
         type: Date,
         default: Date.now
     },
 
+    /** Creation timestamp */
     created_at: {
         type: Date,
         default: Date.now,

package/schemas/Media.js

@@ -2,23 +2,31 @@ const {Schema} = require('mongoose')
 const DimensionObject = require('./types/DimensionObject')
 
 
+/**
+ * Media — Design/mockup files.
+ * Tracks file processing status and storage location for print-ready designs and mockups.
+ */
 const Media = new Schema({
+    /** Public URL of the media file */
     url: {
         type: String,
         trim: true,
     },
 
+    /** Internal file storage path */
     path_file: {
         type: String,
         trim: true,
     },
 
+    /** Media type (default 'design') — e.g., 'design', 'mockup' */
     type: {
         type: String,
         trim: true,
         default: 'design'
     },
 
+    /** Storage location: 'external' | 'internal' */
     location: {
         type: String,
         default: 'external',
@@ -26,15 +34,18 @@ const Media = new Schema({
         index: true,
     },
 
+    /** MIME type of the file (e.g., 'image/png') */
     mimetype: {
         type: String,
         trim: true,
     },
 
+    /** File size in bytes */
     size: {
         type: Number,
     },
 
+    /** Processing status: 'pending' | 'completed' | 'failed' */
     status: {
         type: String,
         trim: true,
@@ -42,26 +53,31 @@ const Media = new Schema({
         enum: ['pending', 'completed', 'failed'],
     },
 
+    /** Image dimensions in pixels (embedded) */
     dimension: {
         type: DimensionObject
     },
 
+    /** Number of processing attempts */
     process_attempts: {
         type: Number,
         default: 0,
         index: true
     },
 
+    /** Error details if processing failed */
     error_message: {
         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/Order.js

@@ -5,13 +5,19 @@ const AttachmentObject = require('./types/AttachmentObject')
 const FulfillmentObject = require('./types/FulfillmentObject')
 
 
+/**
+ * Order — Main order entity.
+ * Tracks e-commerce orders from multiple sales channels (TikTok, Shopify, etc.).
+ */
 const Order = new Schema({
+    /** Display name of the order (e.g., "#1001") */
     name: {
         type: String,
         trim: true,
         index: true,
     },
 
+    /** External order ID from the source platform */
     order_id: {
         type: String,
         trim: true,
@@ -19,6 +25,7 @@ const Order = new Schema({
         required: true
     },
 
+    /** Sales channel type, default 'tiktok' */
     type: {
         type: String,
         trim: true,
@@ -26,46 +33,62 @@ const Order = new Schema({
         index: true,
     },
 
+    /** Reference to the Shop this order belongs to */
     shop: {
         type: Schema.Types.ObjectId,
         index: true,
     },
 
+    /** Type of shop at the time of order creation */
+    shop_type: {
+        type: String,
+        trim: true,
+        index: true,
+    },
+
+    /** Reference to the FulfillmentStore handling this order */
     fulfillment_store: {
         type: Schema.Types.ObjectId,
         index: true,
     },
 
+    /** Reference to the current OrderFulfillment record */
     fulfillment: {
         type: Schema.Types.ObjectId,
         index: true,
     },
 
+    /** Recipient's shipping address (embedded) */
     shipping_address: {
         type: ShippingAddress,
     },
 
+    /** Internal note visible to staff */
     note: {
         type: String,
         trim: true,
     },
 
+    /** Note from the customer or source platform */
     external_note: {
         type: String,
         trim: true,
     },
 
+    /** Payment method used (e.g., 'cod', 'online') */
     payment_method: {
         type: String,
         trim: true,
     },
 
+    /** Order status on the source platform */
     platform_status: {
         type: String,
         trim: true,
         index: true,
     },
 
+    /** Fulfillment progress: 'unfulfilled' | 'processing' | 'fulfilled' | 'cancelled' */
     fulfillment_status: {
         type: String,
         default: 'unfulfilled',
@@ -73,6 +96,7 @@ const Order = new Schema({
         index: true
     },
 
+    /** Approval status: 'pending' | 'approved' | 'rejected' */
     validation_status: {
         type: String,
         default: 'pending',
@@ -80,141 +104,168 @@ const Order = new Schema({
         index: true
     },
 
+    /** Total item quantity in this order */
     quantity: {
         type: Number,
         default: 1,
     },
 
+    /** Order total amount with currency (embedded) */
     amount: {
         type: MoneyObject,
     },
 
+    /** Special instructions for fulfillment */
     fulfillment_note: {
         type: String,
         trim: true,
     },
 
+    /** Timestamp when the order was created on the source platform */
     order_created_at: {
         type: Date,
         index: true,
         default: Date.now,
     },
 
+    /** Last time this order was synced from the source platform */
     last_synced_at: {
         type: Date,
         default: Date.now,
         index: true
     },
 
+    /** How many times this order has been synced */
     sync_count: {
         type: Number,
         default: 0,
     },
 
+    /** Error message from the last failed sync attempt */
     last_sync_error: {
         type: String,
         trim: true,
     },
 
+    /** Mapped order ID in the Nhanh.vn system */
     nhanh_id: {
         type: String,
         trim: true,
     },
 
+    /** List of validation steps that have passed */
     valid_steps: {
         type: [String],
         default: [],
         index: true
     },
 
+    /** Number of attempts to map SKU for this order */
     map_sku_attempts: {
         type: Number,
         default: 0,
         index: true
     },
 
+    /** Reference to the most recent shipping Label */
     last_label: {
         type: Schema.Types.ObjectId,
         index: true,
     },
 
+    /** Flexible metadata from the source platform */
     metadata: {
         type: Schema.Types.Mixed,
         default: {}
     },
 
+    /** Logistics/carrier data (tracking info, carrier responses) */
     logistic_data: {
         type: Schema.Types.Mixed,
         default: {}
     },
 
+    /** Storage location identifier for the shipping label file */
     label_location: {
         type: String,
         trim: true,
     },
 
+    /** Attached images (e.g., customer-uploaded design files) */
     attachments: {
         type: [AttachmentObject],
         default: []
     },
 
+    /** Categorization tags for filtering and grouping */
     tags: {
         type: [String],
         default: [],
         index: true
     },
 
+    /** Number of attempts to push this order to a shipping carrier */
     push_to_carrier_attempts: {
         type: Number,
         default: 0,
         index: true
     },
 
+    /** Reference to the ShippingCarrier assigned to this order */
     shipping_carrier: {
         type: Schema.Types.ObjectId,
         index: true
     },
 
+    /** List of fulfillment number + production status pairs (embedded) */
     fulfillments: {
         type: [FulfillmentObject],
         default: []
     },
 
+    /** External sync identifier for deduplication */
     sync_id: {
         type: String,
         trim: true,
     },
 
+    /** Mapped order ID in the Pancake system */
     pancake_system_id: {
         type: String,
         trim: true,
     },
 
+    /** Whether this order was imported from a legacy system */
     is_legacy: {
         type: Boolean,
     },
 
+    /** Whether this order comes from a marketplace channel */
     is_marketplace: {
         type: Boolean,
         default: false,
         index: true
     },
 
+    /** Estimated delivery date from the carrier */
     estimate_delivery_date: {
         type: Date,
         index: true,
     },
 
+    /** Timestamp when this order was pushed to the carrier */
     pushed_at: {
         type: Date,
         index: true
     },
 
+    /** Last modification timestamp */
     updated_at: {
         type: Date,
         default: Date.now
     },
 
+    /** Creation timestamp */
     created_at: {
         type: Date,
         default: Date.now,
@@ -244,4 +295,3 @@ Order.index({
 })
 
 module.exports = Order
-