@cendo/database-schemas 2.1.5 → 2.1.6

package/CLAUDE.md

@@ -0,0 +1,184 @@
+# @cendo/database-schemas
+
+Shared Mongoose schema definitions for Cendo microservices. This package is the single source of truth for all MongoDB data models — services import schemas from here to ensure consistency.
+
+## Usage
+
+This package is used via the **schemis** library — it does not work standalone.
+
+### Database Connection Setup
+
+```js
+// src/connections/database.js
+const {createConnection, createStore} = require('schemis')
+const schemas = require('@cendo/database-schemas')
+
+const uri = process.env.MONGODB_URI || 'mongodb://localhost:27017/dev'
+const connection = createConnection(uri)
+
+const store = createStore({
+    connection,
+    schemas
+})
+
+module.exports = store
+```
+
+### Using Models in Actions
+
+```js
+const {getModel} = require('../../connections/database')
+
+const Product = getModel('Product')
+
+// Standard Mongoose operations
+const product = await Product.findOne({_id: productId}).lean()
+await Product.updateOne({_id: productId}, {$set: {status: 'active', updated_at: Date.now()}})
+```
+
+### Populate with Explicit Model
+
+```js
+const {getModel} = require('../../connections/database')
+
+const Shop = getModel('Shop')
+const FulfillmentStore = getModel('FulfillmentStore')
+const ShippingCarrier = getModel('ShippingCarrier')
+
+const shop = await Shop
+    .findOne({_id: id})
+    .populate({path: 'fulfillment_store', model: FulfillmentStore, select: {name: 1, status: 1}})
+    .populate({path: 'default_carrier', model: ShippingCarrier, select: {name: 1, code: 1, status: 1}})
+    .lean()
+```
+
+### Search with Pagination
+
+```js
+const Product = getModel('Product')
+
+const _fetch = Product
+    .find(query)
+    .sort(sort)
+    .skip(skip)
+    .limit(limit)
+    .lean()
+
+const _fetchTotal = Product.countDocuments(query)
+
+const [items, total] = await Promise.all([_fetch, _fetchTotal])
+```
+
+### Transactions
+
+```js
+const Order = getModel('Order')
+const OrderHistory = getModel('OrderHistory')
+
+const session = await Order.startSession()
+await session.withTransaction(async () => {
+    await Order.updateOne({_id: order._id}, {
+        $set: {validation_status, updated_at: Date.now()}
+    }, {session})
+
+    await OrderHistory.create([{
+        order: order._id,
+        action: 'validation_updated',
+        description: `Updated order validation status to ${validation_status}.`,
+    }], {session, ordered: true})
+})
+await session.endSession()
+```
+
+### Aggregation
+
+```js
+const Order = getModel('Order')
+
+const rows = await Order.aggregate([
+    {$match: query},
+    {$project: {tags: 1}},
+    {$unwind: {path: '$tags'}},
+    {$group: {_id: '$tags', count: {$sum: 1}}},
+    {$sort: {count: 1}}
+])
+```
+
+## Dependencies
+
+- **mongoose** `^9` (peer dependency)
+- **schemis** — used by consumers to create database store and register models from schemas
+
+## Directory Structure
+
+```
+schemas/              # Main schema files (19 schemas)
+schemas/types/        # Embedded sub-document types (ShippingAddress, MoneyObject, etc.)
+index.js              # Exports path to schemas/ directory
+```
+
+## Schema Catalog
+
+### 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)
+- **OrderFulfillment** — Fulfillment/shipment records (order, fulfillment_store, number, production_status, tracking, items). Index on (tracking.tracking_number)
+- **OrderHistory** — Order action history (order, action, description, meta)
+- **OrderLog** — Order event logging (order, level, label, message, meta). TTL: 90 days
+
+### Products
+- **Product** — Product/SKU catalog (shop, name, sku_id, seller_sku, fulfillment_sku, customize_sku, status). Full-text index on name/sku_id/fulfillment_sku/customize_sku
+
+### Shops & Settings
+- **Shop** — Store/shop configuration (shop_id, type, status, fulfillment_store, default_carrier, nhanh_id)
+- **ShopSetting** — Shop-level key-value settings (shop, key, value as Mixed)
+- **CarrierSetting** — Carrier-specific key-value settings (shipping_carrier, key, value as Mixed)
+
+### Fulfillment & Shipping
+- **FulfillmentStore** — Fulfillment provider/warehouse (name, status, api_key, api_url, store_id, team_id)
+- **ShippingCarrier** — Carrier master data (name, code, status)
+- **Label** — Shipping label records (order, order_id, tracking_number, carrier, url, path_file, status, is_pushed)
+
+### Media
+- **Media** — Design/mockup files (url, path_file, type, location, mimetype, size, dimension, status, process_attempts)
+
+### Import
+- **ImportFile** — Bulk import file tracking (name)
+- **ImportRow** — Individual import rows (file, line, unique_id, data as Mixed, status). TTL: 12 months. Compound index on (file, line)
+
+### Source Data
+- **SourceOrder** — Source system order data (type defaults to 'shopify', id, name, financial_status, fulfillment_status)
+- **SourceItem** — Source system line items (order, id, product_name, variant_name, sku, quantity, customize_properties, customize_item, mockup_url, design_url)
+
+### Events & Logging
+- **WebhookEvent** — Webhook event queue (topic, type, status, payload as Mixed, is_test). TTL: 7 days
+- **TestResponse** — Test/webhook response logging (url, code, message, data as Mixed)
+
+## Common Embedded Types
+
+Used as sub-documents across schemas (all with `{ _id: false }`):
+
+| Type | Fields | Used In |
+|------|--------|---------|
+| **ShippingAddress** | username, name, address1, address2, city, zip, province, district, commune, country, phone, phone_plain_text, email | Order |
+| **MoneyObject** | amount, currency (default: 'VND') | Order |
+| **AttachmentObject** | type (enum: 'image'), url | Order |
+| **FulfillmentObject** | number, production_status | Order |
+| **DimensionObject** | width, height | Media |
+| **TrackingObject** | tracking_number, tracking_url, carrier | OrderFulfillment |
+
+## Conventions
+
+- Each schema file exports a Mongoose Schema (not a Model) — consumers register models themselves
+- All text fields use `trim: true`
+- Timestamps: schemas use `created_at` / `updated_at` fields (not Mongoose timestamps option), defaulting to `Date.now`
+- Status fields use string enums (e.g., `'active'|'inactive'`, `'pending'|'completed'|'failed'`)
+- Embedded types in `schemas/types/` have `{ _id: false }`
+- TTL indexes for ephemeral data (OrderLog: 90 days, WebhookEvent: 7 days, ImportRow: 12 months)
+- Text index on Product (name, sku_id, fulfillment_sku, customize_sku)
+- `Schema.Types.Mixed` used for flexible metadata fields (logistic_data, metadata, payload, data)
+- ObjectId references are used without `ref` in most schemas (except Label which refs 'Order')
+- Attempt counters track retry logic: `map_sku_attempts`, `push_to_carrier_attempts`, `sync_media_attempts`, `process_attempts`
+- Multi-platform integration fields: `nhanh_id`, `pancake_system_id`, `platform_status`
+- Default currency is VND (Vietnamese Dong)
+- Default shop type is 'tiktok'

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@cendo/database-schemas",
-  "version": "2.1.5",
+  "version": "2.1.6",
   "description": "",
   "main": "index.js",
   "keywords": [],
   "author": "",
   "license": "ISC",
   "peerDependencies": {
-    "mongoose": "^9"
+    "mongoose": "^9",
+    "schemis": "^2.0.2"
   },
   "devDependencies": {
     "mongoose": "^9"