Codex
1300 lines
45 KiB
TypeScript
1300 lines
45 KiB
TypeScript
import { createHash } from 'node:crypto';
|
|
import type { PoolConnection, ResultSetHeader, RowDataPacket } from 'mysql2/promise';
|
|
import type { ManagementActor } from '../auth/user-management-repository.js';
|
|
import type { MySqlPool } from '../db/mysql.js';
|
|
|
|
export type InventoryPolicyType = 'TRACKED' | 'UNLIMITED';
|
|
export type InventoryOperation =
|
|
| 'CONFIGURE'
|
|
| 'INBOUND'
|
|
| 'ADJUST'
|
|
| 'LOCK'
|
|
| 'RELEASE'
|
|
| 'DEDUCT'
|
|
| 'STOCKTAKE'
|
|
| 'LOSS'
|
|
| 'RETURN';
|
|
|
|
const MAX_QUANTITY = 1_000_000_000;
|
|
const MAX_BATCH_ITEMS = 100;
|
|
const idPattern = /^[1-9]\d{0,19}$/;
|
|
const requestIdPattern = /^[A-Za-z0-9._:-]{1,64}$/;
|
|
const businessTypePattern = /^[A-Z][A-Z0-9_.:-]{0,63}$/;
|
|
|
|
interface InventoryRow extends RowDataPacket {
|
|
id: string;
|
|
tenantId: string;
|
|
storeId: string;
|
|
skuId: string;
|
|
policyType: InventoryPolicyType;
|
|
availableQuantity: number;
|
|
lockedQuantity: number;
|
|
lossQuantity: number;
|
|
lowStockThreshold: number;
|
|
version: number;
|
|
}
|
|
|
|
interface InventoryListRow extends InventoryRow {
|
|
skuCode: string;
|
|
skuName: string;
|
|
productId: string;
|
|
productCode: string;
|
|
productName: string;
|
|
salePriceCents: number;
|
|
}
|
|
|
|
interface CountRow extends RowDataPacket { total: number }
|
|
|
|
interface InventoryRequestRow extends RowDataPacket {
|
|
tenantId: string;
|
|
storeId: string;
|
|
requestId: string;
|
|
operation: InventoryOperation;
|
|
businessType: string;
|
|
businessId: string;
|
|
fingerprint: string;
|
|
itemCount: number;
|
|
}
|
|
|
|
interface ReservationRow extends RowDataPacket {
|
|
inventoryId: string;
|
|
reservedQuantity: number;
|
|
}
|
|
|
|
interface ReservationTotalRow extends RowDataPacket { reservedQuantity: number }
|
|
|
|
interface LedgerRow extends RowDataPacket {
|
|
id: string;
|
|
inventoryId: string;
|
|
storeId: string;
|
|
skuId: string;
|
|
requestId: string;
|
|
businessType: string;
|
|
businessId: string;
|
|
operation: InventoryOperation;
|
|
availableDelta: number;
|
|
lockedDelta: number;
|
|
lossDelta: number;
|
|
availableAfter: number;
|
|
lockedAfter: number;
|
|
lossAfter: number;
|
|
versionAfter: number;
|
|
operatorId: string | null;
|
|
traceId: string;
|
|
reason: string;
|
|
metadata: unknown;
|
|
createdAt: Date;
|
|
}
|
|
|
|
export interface InventoryStock {
|
|
id: string;
|
|
tenantId: string;
|
|
storeId: string;
|
|
skuId: string;
|
|
skuCode: string;
|
|
skuName: string;
|
|
productId: string;
|
|
productCode: string;
|
|
productName: string;
|
|
salePriceCents: number;
|
|
policyType: InventoryPolicyType;
|
|
availableQuantity: number;
|
|
lockedQuantity: number;
|
|
lossQuantity: number;
|
|
lowStockThreshold: number;
|
|
lowStock: boolean;
|
|
version: number;
|
|
}
|
|
|
|
export interface InventoryLedgerEntry {
|
|
id: string;
|
|
inventoryId: string;
|
|
storeId: string;
|
|
skuId: string;
|
|
requestId: string;
|
|
businessType: string;
|
|
businessId: string;
|
|
operation: InventoryOperation;
|
|
availableDelta: number;
|
|
lockedDelta: number;
|
|
lossDelta: number;
|
|
availableAfter: number;
|
|
lockedAfter: number;
|
|
lossAfter: number;
|
|
versionAfter: number;
|
|
operatorId: string | null;
|
|
traceId: string;
|
|
reason: string;
|
|
metadata: Record<string, unknown>;
|
|
createdAt: Date;
|
|
}
|
|
|
|
export interface InventoryPage<T> {
|
|
items: T[];
|
|
total: number;
|
|
page: number;
|
|
pageSize: number;
|
|
}
|
|
|
|
export interface InventoryMutationResult {
|
|
inventoryId: string;
|
|
ledgerId: string;
|
|
storeId: string;
|
|
skuId: string;
|
|
operation: InventoryOperation;
|
|
policyType: InventoryPolicyType;
|
|
availableQuantity: number;
|
|
lockedQuantity: number;
|
|
lossQuantity: number;
|
|
lowStockThreshold: number;
|
|
version: number;
|
|
idempotent: boolean;
|
|
}
|
|
|
|
export interface InventoryListInput {
|
|
storeId: string;
|
|
page: number;
|
|
pageSize: number;
|
|
skuId?: string;
|
|
productId?: string;
|
|
search?: string;
|
|
}
|
|
|
|
export interface InventoryLedgerListInput {
|
|
storeId: string;
|
|
inventoryId: string;
|
|
page: number;
|
|
pageSize: number;
|
|
}
|
|
|
|
interface AdminMutationBase {
|
|
storeId: string;
|
|
skuId: string;
|
|
requestId: string;
|
|
reason: string;
|
|
expectedVersion?: number;
|
|
}
|
|
|
|
export interface ConfigureInventoryPolicyInput extends AdminMutationBase {
|
|
expectedVersion: number;
|
|
policyType: InventoryPolicyType;
|
|
lowStockThreshold: number;
|
|
}
|
|
|
|
export interface InventoryInboundInput extends AdminMutationBase { quantity: number }
|
|
|
|
export interface InventoryAdjustmentInput extends AdminMutationBase {
|
|
availableDelta: number;
|
|
lossDelta: number;
|
|
}
|
|
|
|
export interface InventoryStocktakeInput extends AdminMutationBase {
|
|
expectedVersion: number;
|
|
availableQuantity: number;
|
|
lossQuantity: number;
|
|
}
|
|
|
|
export interface InventoryLossInput extends AdminMutationBase { quantity: number }
|
|
|
|
export interface InventoryBatchItem { skuId: string; quantity: number }
|
|
|
|
export interface InventoryBatchMutationInput {
|
|
tenantId: string;
|
|
storeId: string;
|
|
items: InventoryBatchItem[];
|
|
requestId: string;
|
|
businessType: string;
|
|
businessId: string;
|
|
traceId: string;
|
|
operatorId?: string | null;
|
|
ip?: string;
|
|
userAgent?: string;
|
|
reason?: string;
|
|
metadata?: Record<string, unknown>;
|
|
}
|
|
|
|
interface StockState {
|
|
policyType: InventoryPolicyType;
|
|
availableQuantity: number;
|
|
lockedQuantity: number;
|
|
lossQuantity: number;
|
|
lowStockThreshold: number;
|
|
}
|
|
|
|
interface DeltaState {
|
|
availableDelta: number;
|
|
lockedDelta: number;
|
|
lossDelta: number;
|
|
reservationDelta: number;
|
|
next: StockState;
|
|
}
|
|
|
|
interface MutationIdentity {
|
|
requestId: string;
|
|
businessType: string;
|
|
businessId: string;
|
|
operation: InventoryOperation;
|
|
operatorId: string | null;
|
|
traceId: string;
|
|
reason: string;
|
|
metadata: Record<string, unknown>;
|
|
fingerprint: string;
|
|
}
|
|
|
|
interface AuditIdentity {
|
|
tenantId: string;
|
|
operatorId: string | null;
|
|
traceId: string;
|
|
ip: string;
|
|
userAgent: string;
|
|
}
|
|
|
|
export class InventoryError extends Error {
|
|
constructor(public readonly code: string) { super(code); }
|
|
}
|
|
|
|
export class InventoryService {
|
|
constructor(private readonly pool: MySqlPool) {}
|
|
|
|
async listStocks(
|
|
actor: ManagementActor,
|
|
input: InventoryListInput
|
|
): Promise<InventoryPage<InventoryStock>> {
|
|
this.assertStoreScope(actor, input.storeId, false);
|
|
const page = boundedPage(input.page);
|
|
const pageSize = boundedPageSize(input.pageSize);
|
|
const filters: string[] = ['i.tenant_id = ?', 'i.store_id = ?'];
|
|
const params: Array<string | number> = [actor.tenantId, input.storeId];
|
|
if (input.skuId) {
|
|
assertId(input.skuId, 'INVENTORY_SKU_ID_INVALID');
|
|
filters.push('i.sku_id = ?');
|
|
params.push(input.skuId);
|
|
}
|
|
if (input.productId) {
|
|
assertId(input.productId, 'INVENTORY_PRODUCT_ID_INVALID');
|
|
filters.push('s.product_id = ?');
|
|
params.push(input.productId);
|
|
}
|
|
const search = input.search?.trim();
|
|
if (search) {
|
|
if (search.length > 64) throw new InventoryError('INVENTORY_SEARCH_INVALID');
|
|
filters.push('(s.sku_code LIKE ? OR s.name LIKE ? OR p.product_code LIKE ? OR p.name LIKE ?)');
|
|
const keyword = `%${search}%`;
|
|
params.push(keyword, keyword, keyword, keyword);
|
|
}
|
|
const where = filters.join(' AND ');
|
|
const [countRows] = await this.pool.execute<CountRow[]>(
|
|
`SELECT COUNT(*) AS total
|
|
FROM qipai_product_inventory i
|
|
INNER JOIN qipai_product_skus s
|
|
ON s.tenant_id = i.tenant_id AND s.id = i.sku_id AND s.deleted_at IS NULL
|
|
INNER JOIN qipai_products p
|
|
ON p.tenant_id = s.tenant_id AND p.id = s.product_id AND p.deleted_at IS NULL
|
|
WHERE ${where}`,
|
|
params
|
|
);
|
|
const [rows] = await this.pool.execute<InventoryListRow[]>(
|
|
`SELECT i.id, i.tenant_id AS tenantId, i.store_id AS storeId,
|
|
i.sku_id AS skuId, i.policy_type AS policyType,
|
|
i.available_quantity AS availableQuantity,
|
|
i.locked_quantity AS lockedQuantity, i.loss_quantity AS lossQuantity,
|
|
i.low_stock_threshold AS lowStockThreshold, i.version,
|
|
s.sku_code AS skuCode, s.name AS skuName, s.product_id AS productId,
|
|
s.sale_price_cents AS salePriceCents,
|
|
p.product_code AS productCode, p.name AS productName
|
|
FROM qipai_product_inventory i
|
|
INNER JOIN qipai_product_skus s
|
|
ON s.tenant_id = i.tenant_id AND s.id = i.sku_id AND s.deleted_at IS NULL
|
|
INNER JOIN qipai_products p
|
|
ON p.tenant_id = s.tenant_id AND p.id = s.product_id AND p.deleted_at IS NULL
|
|
WHERE ${where}
|
|
ORDER BY p.sort_order, p.id, s.id
|
|
LIMIT ? OFFSET ?`,
|
|
[...params, pageSize, (page - 1) * pageSize]
|
|
);
|
|
return {
|
|
items: rows.map(mapStock),
|
|
total: Number(countRows[0]?.total ?? 0),
|
|
page,
|
|
pageSize
|
|
};
|
|
}
|
|
|
|
async listLedger(
|
|
actor: ManagementActor,
|
|
input: InventoryLedgerListInput
|
|
): Promise<InventoryPage<InventoryLedgerEntry>> {
|
|
this.assertStoreScope(actor, input.storeId, false);
|
|
assertId(input.inventoryId, 'INVENTORY_ID_INVALID');
|
|
const page = boundedPage(input.page);
|
|
const pageSize = boundedPageSize(input.pageSize);
|
|
const params = [actor.tenantId, input.storeId, input.inventoryId];
|
|
const [countRows] = await this.pool.execute<CountRow[]>(
|
|
`SELECT COUNT(*) AS total FROM qipai_product_inventory_ledger
|
|
WHERE tenant_id = ? AND store_id = ? AND inventory_id = ?`,
|
|
params
|
|
);
|
|
const [rows] = await this.pool.execute<LedgerRow[]>(
|
|
`SELECT id, inventory_id AS inventoryId, store_id AS storeId, sku_id AS skuId,
|
|
request_id AS requestId, business_type AS businessType,
|
|
business_id AS businessId, operation,
|
|
available_delta AS availableDelta, locked_delta AS lockedDelta,
|
|
loss_delta AS lossDelta, available_after AS availableAfter,
|
|
locked_after AS lockedAfter, loss_after AS lossAfter,
|
|
version_after AS versionAfter, operator_id AS operatorId,
|
|
trace_id AS traceId, reason, metadata, created_at AS createdAt
|
|
FROM qipai_product_inventory_ledger
|
|
WHERE tenant_id = ? AND store_id = ? AND inventory_id = ?
|
|
ORDER BY id DESC LIMIT ? OFFSET ?`,
|
|
[...params, pageSize, (page - 1) * pageSize]
|
|
);
|
|
return {
|
|
items: rows.map(mapLedger),
|
|
total: Number(countRows[0]?.total ?? 0),
|
|
page,
|
|
pageSize
|
|
};
|
|
}
|
|
|
|
async configurePolicy(actor: ManagementActor, input: ConfigureInventoryPolicyInput) {
|
|
this.assertStoreScope(actor, input.storeId, true);
|
|
validateAdminBase(input, true);
|
|
const threshold = boundedNonNegative(input.lowStockThreshold, 'INVENTORY_THRESHOLD_INVALID');
|
|
if (!['TRACKED', 'UNLIMITED'].includes(input.policyType)) {
|
|
throw new InventoryError('INVENTORY_POLICY_INVALID');
|
|
}
|
|
const identity = mutationIdentity({
|
|
requestId: input.requestId,
|
|
businessType: 'ADMIN_INVENTORY_POLICY',
|
|
businessId: input.skuId,
|
|
operation: 'CONFIGURE',
|
|
operatorId: actor.userId,
|
|
traceId: actor.traceId,
|
|
reason: input.reason,
|
|
metadata: {},
|
|
payload: {
|
|
storeId: input.storeId, skuId: input.skuId, policyType: input.policyType,
|
|
lowStockThreshold: threshold, expectedVersion: input.expectedVersion
|
|
}
|
|
});
|
|
return this.transaction(async (connection) => {
|
|
const requestExists = await this.registerRequest(
|
|
connection, actor.tenantId, input.storeId, identity, 1
|
|
);
|
|
if (requestExists) {
|
|
const stock = await this.lockStock(
|
|
connection, actor.tenantId, input.storeId, input.skuId
|
|
);
|
|
const duplicate = await this.replayOrConflict(connection, stock, identity);
|
|
if (!duplicate) throw new InventoryError('INVENTORY_IDEMPOTENCY_CONFLICT');
|
|
return duplicate;
|
|
}
|
|
await this.assertSkuManageable(connection, actor.tenantId, input.skuId);
|
|
const created = await this.ensureInventory(
|
|
connection, actor.tenantId, input.storeId, input.skuId, actor.userId
|
|
);
|
|
const stock = await this.lockStock(connection, actor.tenantId, input.storeId, input.skuId);
|
|
if ((created && input.expectedVersion !== 0)
|
|
|| (!created && input.expectedVersion === 0)) {
|
|
throw new InventoryError('INVENTORY_VERSION_CONFLICT');
|
|
}
|
|
if (!created) assertExpectedVersion(stock, input.expectedVersion);
|
|
if (input.policyType !== stock.policyType) {
|
|
await this.assertNoActiveReservations(connection, stock);
|
|
}
|
|
if (input.policyType === 'UNLIMITED'
|
|
&& (number(stock.availableQuantity) !== 0
|
|
|| number(stock.lockedQuantity) !== 0
|
|
|| number(stock.lossQuantity) !== 0)) {
|
|
throw new InventoryError('INVENTORY_POLICY_STOCK_NOT_ZERO');
|
|
}
|
|
const next: StockState = {
|
|
policyType: input.policyType,
|
|
availableQuantity: number(stock.availableQuantity),
|
|
lockedQuantity: number(stock.lockedQuantity),
|
|
lossQuantity: number(stock.lossQuantity),
|
|
lowStockThreshold: input.policyType === 'UNLIMITED' ? 0 : threshold
|
|
};
|
|
return this.persistMutation(connection, stock, identity, {
|
|
availableDelta: 0, lockedDelta: 0, lossDelta: 0, reservationDelta: 0, next
|
|
}, auditFromActor(actor));
|
|
});
|
|
}
|
|
|
|
async inbound(actor: ManagementActor, input: InventoryInboundInput) {
|
|
const quantity = boundedPositive(input.quantity, 'INVENTORY_QUANTITY_INVALID');
|
|
return this.adminMutation(actor, input, 'INBOUND', 'ADMIN_INVENTORY_INBOUND', {
|
|
quantity
|
|
}, (stock) => {
|
|
assertTracked(stock);
|
|
return delta(stock, quantity, 0, 0);
|
|
});
|
|
}
|
|
|
|
async adjust(actor: ManagementActor, input: InventoryAdjustmentInput) {
|
|
const availableDelta = boundedDelta(input.availableDelta, 'INVENTORY_ADJUSTMENT_INVALID');
|
|
const lossDelta = boundedDelta(input.lossDelta, 'INVENTORY_ADJUSTMENT_INVALID');
|
|
if (availableDelta === 0 && lossDelta === 0) {
|
|
throw new InventoryError('INVENTORY_ADJUSTMENT_ZERO');
|
|
}
|
|
return this.adminMutation(actor, input, 'ADJUST', 'ADMIN_INVENTORY_ADJUST', {
|
|
availableDelta, lossDelta
|
|
}, (stock) => {
|
|
assertTracked(stock);
|
|
return delta(stock, availableDelta, 0, lossDelta);
|
|
});
|
|
}
|
|
|
|
async stocktake(actor: ManagementActor, input: InventoryStocktakeInput) {
|
|
assertRequiredExpectedVersion(input.expectedVersion, false);
|
|
const available = boundedNonNegative(
|
|
input.availableQuantity, 'INVENTORY_STOCKTAKE_INVALID'
|
|
);
|
|
const loss = boundedNonNegative(input.lossQuantity, 'INVENTORY_STOCKTAKE_INVALID');
|
|
return this.adminMutation(actor, input, 'STOCKTAKE', 'ADMIN_INVENTORY_STOCKTAKE', {
|
|
availableQuantity: available, lossQuantity: loss
|
|
}, (stock) => {
|
|
assertTracked(stock);
|
|
return delta(
|
|
stock,
|
|
available - number(stock.availableQuantity),
|
|
0,
|
|
loss - number(stock.lossQuantity)
|
|
);
|
|
});
|
|
}
|
|
|
|
async recordLoss(actor: ManagementActor, input: InventoryLossInput) {
|
|
const quantity = boundedPositive(input.quantity, 'INVENTORY_QUANTITY_INVALID');
|
|
return this.adminMutation(actor, input, 'LOSS', 'ADMIN_INVENTORY_LOSS', {
|
|
quantity
|
|
}, (stock) => {
|
|
assertTracked(stock);
|
|
if (number(stock.availableQuantity) < quantity) {
|
|
throw new InventoryError('INVENTORY_INSUFFICIENT_AVAILABLE');
|
|
}
|
|
return delta(stock, -quantity, 0, quantity);
|
|
});
|
|
}
|
|
|
|
async lockMany(input: InventoryBatchMutationInput, connection?: PoolConnection) {
|
|
return this.batchMutation(input, 'LOCK', (stock, quantity) => {
|
|
if (stock.policyType === 'UNLIMITED') return delta(stock, 0, 0, 0, quantity);
|
|
if (number(stock.availableQuantity) < quantity) {
|
|
throw new InventoryError('INVENTORY_INSUFFICIENT_AVAILABLE');
|
|
}
|
|
return delta(stock, -quantity, quantity, 0, quantity);
|
|
}, connection);
|
|
}
|
|
|
|
async releaseMany(input: InventoryBatchMutationInput, connection?: PoolConnection) {
|
|
return this.batchMutation(input, 'RELEASE', (stock, quantity) => {
|
|
if (stock.policyType === 'UNLIMITED') return delta(stock, 0, 0, 0, -quantity);
|
|
if (number(stock.lockedQuantity) < quantity) {
|
|
throw new InventoryError('INVENTORY_INSUFFICIENT_LOCKED');
|
|
}
|
|
return delta(stock, quantity, -quantity, 0, -quantity);
|
|
}, connection);
|
|
}
|
|
|
|
async deductMany(input: InventoryBatchMutationInput, connection?: PoolConnection) {
|
|
return this.batchMutation(input, 'DEDUCT', (stock, quantity) => {
|
|
if (stock.policyType === 'UNLIMITED') return delta(stock, 0, 0, 0, -quantity);
|
|
if (number(stock.lockedQuantity) < quantity) {
|
|
throw new InventoryError('INVENTORY_INSUFFICIENT_LOCKED');
|
|
}
|
|
return delta(stock, 0, -quantity, 0, -quantity);
|
|
}, connection);
|
|
}
|
|
|
|
private async adminMutation(
|
|
actor: ManagementActor,
|
|
input: AdminMutationBase,
|
|
operation: InventoryOperation,
|
|
businessType: string,
|
|
payload: Record<string, unknown>,
|
|
calculate: (stock: InventoryRow) => DeltaState
|
|
) {
|
|
this.assertStoreScope(actor, input.storeId, true);
|
|
validateAdminBase(input);
|
|
const identity = mutationIdentity({
|
|
requestId: input.requestId,
|
|
businessType,
|
|
businessId: input.skuId,
|
|
operation,
|
|
operatorId: actor.userId,
|
|
traceId: actor.traceId,
|
|
reason: input.reason,
|
|
metadata: {},
|
|
payload: {
|
|
storeId: input.storeId, skuId: input.skuId,
|
|
expectedVersion: input.expectedVersion ?? null, ...payload
|
|
}
|
|
});
|
|
return this.transaction(async (connection) => {
|
|
const requestExists = await this.registerRequest(
|
|
connection, actor.tenantId, input.storeId, identity, 1
|
|
);
|
|
if (requestExists) {
|
|
const stock = await this.lockStock(
|
|
connection, actor.tenantId, input.storeId, input.skuId
|
|
);
|
|
const duplicate = await this.replayOrConflict(connection, stock, identity);
|
|
if (!duplicate) throw new InventoryError('INVENTORY_IDEMPOTENCY_CONFLICT');
|
|
return duplicate;
|
|
}
|
|
await this.assertSkuManageable(connection, actor.tenantId, input.skuId);
|
|
const stock = await this.lockStock(connection, actor.tenantId, input.storeId, input.skuId);
|
|
assertExpectedVersion(stock, input.expectedVersion);
|
|
return this.persistMutation(
|
|
connection, stock, identity, calculate(stock), auditFromActor(actor)
|
|
);
|
|
});
|
|
}
|
|
|
|
private async batchMutation(
|
|
input: InventoryBatchMutationInput,
|
|
operation: 'LOCK' | 'RELEASE' | 'DEDUCT',
|
|
calculate: (stock: InventoryRow, quantity: number) => DeltaState,
|
|
externalConnection?: PoolConnection
|
|
) {
|
|
const normalized = normalizeBatch(input);
|
|
const fingerprint = idempotencyFingerprint({
|
|
tenantId: normalized.tenantId,
|
|
storeId: normalized.storeId,
|
|
items: normalized.items,
|
|
businessType: normalized.businessType,
|
|
businessId: normalized.businessId,
|
|
operation,
|
|
reason: normalized.reason,
|
|
metadata: normalized.metadata
|
|
});
|
|
const identity = mutationIdentity({
|
|
requestId: normalized.requestId,
|
|
businessType: normalized.businessType,
|
|
businessId: normalized.businessId,
|
|
operation,
|
|
operatorId: normalized.operatorId,
|
|
traceId: normalized.traceId,
|
|
reason: normalized.reason,
|
|
metadata: normalized.metadata,
|
|
fingerprint
|
|
});
|
|
const work = async (connection: PoolConnection) => {
|
|
const requestExists = await this.registerRequest(
|
|
connection, normalized.tenantId, normalized.storeId,
|
|
identity, normalized.items.length
|
|
);
|
|
const stocks: Array<{ stock: InventoryRow; quantity: number }> = [];
|
|
for (const item of normalized.items) {
|
|
if (operation === 'LOCK' && !requestExists) {
|
|
await this.assertSkuLockable(connection, normalized.tenantId, item.skuId);
|
|
}
|
|
const stock = await this.lockStock(
|
|
connection, normalized.tenantId, normalized.storeId, item.skuId
|
|
);
|
|
stocks.push({ stock, quantity: item.quantity });
|
|
}
|
|
if (requestExists) {
|
|
const duplicates: Array<InventoryMutationResult | null> = [];
|
|
for (const item of stocks) {
|
|
duplicates.push(await this.replayOrConflict(connection, item.stock, identity));
|
|
}
|
|
if (!duplicates.every(Boolean)) {
|
|
throw new InventoryError('INVENTORY_IDEMPOTENCY_CONFLICT');
|
|
}
|
|
return { items: duplicates as InventoryMutationResult[], idempotent: true };
|
|
}
|
|
if (operation !== 'LOCK') {
|
|
await this.assertReservationBalances(
|
|
connection, normalized.tenantId, normalized.storeId,
|
|
normalized.businessType, normalized.businessId, stocks
|
|
);
|
|
}
|
|
const changes = stocks.map(({ stock, quantity }) => ({
|
|
stock, change: calculate(stock, quantity)
|
|
}));
|
|
const audit: AuditIdentity = {
|
|
tenantId: normalized.tenantId,
|
|
operatorId: normalized.operatorId,
|
|
traceId: normalized.traceId,
|
|
ip: normalized.ip,
|
|
userAgent: normalized.userAgent
|
|
};
|
|
const results: InventoryMutationResult[] = [];
|
|
for (const item of changes) {
|
|
results.push(await this.persistMutation(
|
|
connection, item.stock, identity, item.change, audit
|
|
));
|
|
}
|
|
return { items: results, idempotent: false };
|
|
};
|
|
return externalConnection ? work(externalConnection) : this.transaction(work);
|
|
}
|
|
|
|
private async registerRequest(
|
|
connection: PoolConnection,
|
|
tenantId: string,
|
|
storeId: string,
|
|
identity: MutationIdentity,
|
|
itemCount: number
|
|
): Promise<boolean> {
|
|
try {
|
|
await connection.execute<ResultSetHeader>(
|
|
`INSERT INTO qipai_product_inventory_requests
|
|
(tenant_id, store_id, request_id, operation, business_type, business_id,
|
|
fingerprint, item_count, operator_id, trace_id)
|
|
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
|
|
[tenantId, storeId, identity.requestId, identity.operation,
|
|
identity.businessType, identity.businessId, identity.fingerprint,
|
|
itemCount, identity.operatorId, identity.traceId]
|
|
);
|
|
return false;
|
|
} catch (error) {
|
|
if (!isDuplicateEntry(error)) throw error;
|
|
}
|
|
const [rows] = await connection.execute<InventoryRequestRow[]>(
|
|
`SELECT tenant_id AS tenantId, store_id AS storeId, request_id AS requestId,
|
|
operation, business_type AS businessType, business_id AS businessId,
|
|
fingerprint, item_count AS itemCount
|
|
FROM qipai_product_inventory_requests
|
|
WHERE tenant_id = ? AND request_id = ? FOR UPDATE`,
|
|
[tenantId, identity.requestId]
|
|
);
|
|
const request = rows[0];
|
|
if (!request
|
|
|| String(request.storeId) !== storeId
|
|
|| request.requestId !== identity.requestId
|
|
|| request.operation !== identity.operation
|
|
|| request.businessType !== identity.businessType
|
|
|| request.businessId !== identity.businessId
|
|
|| request.fingerprint !== identity.fingerprint
|
|
|| number(request.itemCount) !== itemCount) {
|
|
throw new InventoryError('INVENTORY_IDEMPOTENCY_CONFLICT');
|
|
}
|
|
return true;
|
|
}
|
|
|
|
private async assertSkuLockable(
|
|
connection: PoolConnection,
|
|
tenantId: string,
|
|
skuId: string
|
|
) {
|
|
await this.assertSkuLifecycle(connection, tenantId, skuId, true);
|
|
}
|
|
|
|
private async assertSkuManageable(
|
|
connection: PoolConnection,
|
|
tenantId: string,
|
|
skuId: string
|
|
) {
|
|
await this.assertSkuLifecycle(connection, tenantId, skuId, false);
|
|
}
|
|
|
|
private async assertSkuLifecycle(
|
|
connection: PoolConnection,
|
|
tenantId: string,
|
|
skuId: string,
|
|
requireActive: boolean
|
|
) {
|
|
const unavailableCode = requireActive
|
|
? 'INVENTORY_SKU_NOT_SELLABLE'
|
|
: 'INVENTORY_SKU_NOT_FOUND';
|
|
const [skuRows] = await connection.execute<RowDataPacket[]>(
|
|
`SELECT product_id AS productId
|
|
FROM qipai_product_skus
|
|
WHERE tenant_id = ? AND id = ? LIMIT 1`,
|
|
[tenantId, skuId]
|
|
);
|
|
const productId = skuRows[0]?.productId;
|
|
if (!productId) throw new InventoryError(unavailableCode);
|
|
const [productRows] = await connection.execute<RowDataPacket[]>(
|
|
`SELECT id FROM qipai_products
|
|
WHERE tenant_id = ? AND id = ? AND deleted_at IS NULL
|
|
${requireActive ? "AND status = 'ACTIVE'" : ''}
|
|
FOR SHARE`,
|
|
[tenantId, productId]
|
|
);
|
|
if (!productRows[0]) throw new InventoryError(unavailableCode);
|
|
const [activeSkuRows] = await connection.execute<RowDataPacket[]>(
|
|
`SELECT id FROM qipai_product_skus
|
|
WHERE tenant_id = ? AND product_id = ? AND id = ?
|
|
AND deleted_at IS NULL
|
|
${requireActive ? "AND status = 'ACTIVE'" : ''}
|
|
FOR SHARE`,
|
|
[tenantId, productId, skuId]
|
|
);
|
|
if (!activeSkuRows[0]) throw new InventoryError(unavailableCode);
|
|
}
|
|
|
|
private async assertReservationBalances(
|
|
connection: PoolConnection,
|
|
tenantId: string,
|
|
storeId: string,
|
|
businessType: string,
|
|
businessId: string,
|
|
stocks: Array<{ stock: InventoryRow; quantity: number }>
|
|
) {
|
|
const placeholders = stocks.map(() => '?').join(', ');
|
|
const [rows] = await connection.execute<ReservationRow[]>(
|
|
`SELECT inventory_id AS inventoryId,
|
|
COALESCE(SUM(COALESCE(
|
|
CAST(JSON_UNQUOTE(JSON_EXTRACT(metadata, '$.inventoryReservationDelta'))
|
|
AS SIGNED),
|
|
locked_delta
|
|
)), 0) AS reservedQuantity
|
|
FROM qipai_product_inventory_ledger
|
|
WHERE tenant_id = ? AND store_id = ?
|
|
AND business_type = ? AND business_id = ?
|
|
AND inventory_id IN (${placeholders})
|
|
GROUP BY inventory_id
|
|
FOR SHARE`,
|
|
[tenantId, storeId, businessType, businessId,
|
|
...stocks.map(({ stock }) => stock.id)]
|
|
);
|
|
const balances = new Map(
|
|
rows.map((row) => [String(row.inventoryId), number(row.reservedQuantity)])
|
|
);
|
|
for (const { stock, quantity } of stocks) {
|
|
if ((balances.get(stock.id) ?? 0) < quantity) {
|
|
throw new InventoryError('INVENTORY_INSUFFICIENT_RESERVATION');
|
|
}
|
|
}
|
|
}
|
|
|
|
private async assertNoActiveReservations(
|
|
connection: PoolConnection,
|
|
stock: InventoryRow
|
|
) {
|
|
const [rows] = await connection.execute<ReservationTotalRow[]>(
|
|
`SELECT COALESCE(SUM(COALESCE(
|
|
CAST(JSON_UNQUOTE(JSON_EXTRACT(metadata, '$.inventoryReservationDelta'))
|
|
AS SIGNED),
|
|
locked_delta
|
|
)), 0) AS reservedQuantity
|
|
FROM qipai_product_inventory_ledger
|
|
WHERE tenant_id = ? AND inventory_id = ?
|
|
FOR SHARE`,
|
|
[stock.tenantId, stock.id]
|
|
);
|
|
if (number(rows[0]?.reservedQuantity ?? 0) !== 0) {
|
|
throw new InventoryError('INVENTORY_POLICY_HAS_ACTIVE_RESERVATIONS');
|
|
}
|
|
}
|
|
|
|
private async ensureInventory(
|
|
connection: PoolConnection,
|
|
tenantId: string,
|
|
storeId: string,
|
|
skuId: string,
|
|
operatorId: string
|
|
): Promise<boolean> {
|
|
const [result] = await connection.execute<ResultSetHeader>(
|
|
`INSERT IGNORE INTO qipai_product_inventory
|
|
(tenant_id, store_id, sku_id, policy_type, available_quantity,
|
|
locked_quantity, loss_quantity, low_stock_threshold, version, updated_by)
|
|
SELECT ?, st.id, s.id, s.default_inventory_policy, 0, 0, 0, 0, 1, ?
|
|
FROM qipai_product_skus s
|
|
INNER JOIN qipai_products p
|
|
ON p.tenant_id = s.tenant_id AND p.id = s.product_id AND p.deleted_at IS NULL
|
|
INNER JOIN qipai_stores st
|
|
ON st.tenant_id = ? AND st.id = ? AND st.deleted_at IS NULL
|
|
WHERE s.tenant_id = ? AND s.id = ? AND s.deleted_at IS NULL`,
|
|
[tenantId, operatorId, tenantId, storeId, tenantId, skuId]
|
|
);
|
|
if (result.affectedRows === 0) {
|
|
const [rows] = await connection.execute<RowDataPacket[]>(
|
|
`SELECT id FROM qipai_product_inventory
|
|
WHERE tenant_id = ? AND store_id = ? AND sku_id = ?
|
|
LIMIT 1 FOR UPDATE`,
|
|
[tenantId, storeId, skuId]
|
|
);
|
|
if (!rows[0]) throw new InventoryError('INVENTORY_SKU_OR_STORE_NOT_FOUND');
|
|
}
|
|
return result.affectedRows === 1;
|
|
}
|
|
|
|
private async lockStock(
|
|
connection: PoolConnection,
|
|
tenantId: string,
|
|
storeId: string,
|
|
skuId: string
|
|
): Promise<InventoryRow> {
|
|
const [rows] = await connection.execute<InventoryRow[]>(
|
|
`SELECT id, tenant_id AS tenantId, store_id AS storeId, sku_id AS skuId,
|
|
policy_type AS policyType, available_quantity AS availableQuantity,
|
|
locked_quantity AS lockedQuantity, loss_quantity AS lossQuantity,
|
|
low_stock_threshold AS lowStockThreshold, version
|
|
FROM qipai_product_inventory
|
|
WHERE tenant_id = ? AND store_id = ? AND sku_id = ? FOR UPDATE`,
|
|
[tenantId, storeId, skuId]
|
|
);
|
|
if (!rows[0]) throw new InventoryError('INVENTORY_STOCK_NOT_FOUND');
|
|
return normalizeStockRow(rows[0]);
|
|
}
|
|
|
|
private async replayOrConflict(
|
|
connection: PoolConnection,
|
|
stock: InventoryRow,
|
|
identity: MutationIdentity
|
|
): Promise<InventoryMutationResult | null> {
|
|
const [rows] = await connection.execute<LedgerRow[]>(
|
|
`SELECT id, inventory_id AS inventoryId, store_id AS storeId, sku_id AS skuId,
|
|
request_id AS requestId, business_type AS businessType,
|
|
business_id AS businessId, operation,
|
|
available_delta AS availableDelta, locked_delta AS lockedDelta,
|
|
loss_delta AS lossDelta, available_after AS availableAfter,
|
|
locked_after AS lockedAfter, loss_after AS lossAfter,
|
|
version_after AS versionAfter, operator_id AS operatorId,
|
|
trace_id AS traceId, reason, metadata, created_at AS createdAt
|
|
FROM qipai_product_inventory_ledger
|
|
WHERE tenant_id = ? AND inventory_id = ? AND request_id = ? LIMIT 1`,
|
|
[stock.tenantId, stock.id, identity.requestId]
|
|
);
|
|
const row = rows[0];
|
|
if (!row) return null;
|
|
const metadata = parseMetadata(row.metadata);
|
|
if (metadata.idempotencyFingerprint !== identity.fingerprint) {
|
|
throw new InventoryError('INVENTORY_IDEMPOTENCY_CONFLICT');
|
|
}
|
|
return mutationResult(stock, row, true);
|
|
}
|
|
|
|
private async persistMutation(
|
|
connection: PoolConnection,
|
|
stock: InventoryRow,
|
|
identity: MutationIdentity,
|
|
change: DeltaState,
|
|
audit: AuditIdentity
|
|
): Promise<InventoryMutationResult> {
|
|
validateState(change.next);
|
|
const nextVersion = number(stock.version) + 1;
|
|
const [updated] = await connection.execute<ResultSetHeader>(
|
|
`UPDATE qipai_product_inventory
|
|
SET policy_type = ?, available_quantity = ?, locked_quantity = ?,
|
|
loss_quantity = ?, low_stock_threshold = ?, version = ?, updated_by = ?
|
|
WHERE tenant_id = ? AND id = ? AND version = ?`,
|
|
[change.next.policyType, change.next.availableQuantity, change.next.lockedQuantity,
|
|
change.next.lossQuantity, change.next.lowStockThreshold, nextVersion,
|
|
identity.operatorId, stock.tenantId, stock.id, stock.version]
|
|
);
|
|
if (updated.affectedRows !== 1) throw new InventoryError('INVENTORY_VERSION_CONFLICT');
|
|
const ledgerMetadata = {
|
|
...identity.metadata,
|
|
idempotencyFingerprint: identity.fingerprint,
|
|
inventoryReservationDelta: change.reservationDelta,
|
|
resultPolicyType: change.next.policyType,
|
|
resultLowStockThreshold: change.next.lowStockThreshold
|
|
};
|
|
const [ledger] = await connection.execute<ResultSetHeader>(
|
|
`INSERT INTO qipai_product_inventory_ledger
|
|
(tenant_id, inventory_id, store_id, sku_id, request_id, business_type,
|
|
business_id, operation, available_delta, locked_delta, loss_delta,
|
|
available_after, locked_after, loss_after, version_after, operator_id,
|
|
trace_id, reason, metadata)
|
|
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
|
|
[stock.tenantId, stock.id, stock.storeId, stock.skuId, identity.requestId,
|
|
identity.businessType, identity.businessId, identity.operation,
|
|
change.availableDelta, change.lockedDelta, change.lossDelta,
|
|
change.next.availableQuantity, change.next.lockedQuantity, change.next.lossQuantity,
|
|
nextVersion, identity.operatorId, identity.traceId, identity.reason.slice(0, 512),
|
|
JSON.stringify(ledgerMetadata)]
|
|
);
|
|
await this.audit(connection, audit, stock, identity, change, String(ledger.insertId));
|
|
return {
|
|
inventoryId: String(stock.id),
|
|
ledgerId: String(ledger.insertId),
|
|
storeId: String(stock.storeId),
|
|
skuId: String(stock.skuId),
|
|
operation: identity.operation,
|
|
policyType: change.next.policyType,
|
|
availableQuantity: change.next.availableQuantity,
|
|
lockedQuantity: change.next.lockedQuantity,
|
|
lossQuantity: change.next.lossQuantity,
|
|
lowStockThreshold: change.next.lowStockThreshold,
|
|
version: nextVersion,
|
|
idempotent: false
|
|
};
|
|
}
|
|
|
|
private async audit(
|
|
connection: PoolConnection,
|
|
audit: AuditIdentity,
|
|
stock: InventoryRow,
|
|
identity: MutationIdentity,
|
|
change: DeltaState,
|
|
ledgerId: string
|
|
) {
|
|
await connection.execute(
|
|
`INSERT INTO qipai_audit_logs
|
|
(tenant_id, actor_type, actor_id, action, resource_type, resource_id,
|
|
trace_id, ip, user_agent, metadata)
|
|
VALUES (?, ?, ?, ?, 'PRODUCT_INVENTORY', ?, ?, ?, ?, ?)`,
|
|
[audit.tenantId, audit.operatorId ? 'USER' : 'SYSTEM', audit.operatorId,
|
|
`PRODUCT_INVENTORY_${identity.operation}`, stock.id, audit.traceId,
|
|
audit.ip.slice(0, 64), audit.userAgent.slice(0, 255), JSON.stringify({
|
|
storeId: String(stock.storeId),
|
|
skuId: String(stock.skuId),
|
|
requestId: identity.requestId,
|
|
businessType: identity.businessType,
|
|
businessId: identity.businessId,
|
|
ledgerId,
|
|
availableDelta: change.availableDelta,
|
|
lockedDelta: change.lockedDelta,
|
|
lossDelta: change.lossDelta,
|
|
reservationDelta: change.reservationDelta,
|
|
versionAfter: number(stock.version) + 1
|
|
})]
|
|
);
|
|
}
|
|
|
|
private assertStoreScope(actor: ManagementActor, storeId: string, write: boolean) {
|
|
assertId(storeId, 'INVENTORY_STORE_ID_INVALID');
|
|
if (actor.access.capabilities.includes('tenant.manage')
|
|
|| actor.access.roles.includes('PLATFORM_ADMIN')) return;
|
|
const capability = write ? 'inventory.adjust' : 'inventory.read';
|
|
const hasCapability = actor.access.capabilities.includes(capability)
|
|
|| (!write && actor.access.capabilities.includes('inventory.adjust'));
|
|
if (!hasCapability || !actor.access.storeIds.includes(storeId)) {
|
|
throw new InventoryError('INVENTORY_STORE_SCOPE_FORBIDDEN');
|
|
}
|
|
}
|
|
|
|
private async transaction<T>(work: (connection: PoolConnection) => Promise<T>) {
|
|
const connection = await this.pool.getConnection();
|
|
try {
|
|
await connection.beginTransaction();
|
|
const result = await work(connection);
|
|
await connection.commit();
|
|
return result;
|
|
} catch (error) {
|
|
await connection.rollback();
|
|
throw error;
|
|
} finally {
|
|
connection.release();
|
|
}
|
|
}
|
|
}
|
|
|
|
function normalizeBatch(input: InventoryBatchMutationInput) {
|
|
assertId(input.tenantId, 'INVENTORY_TENANT_ID_INVALID');
|
|
assertId(input.storeId, 'INVENTORY_STORE_ID_INVALID');
|
|
validateRequestId(input.requestId);
|
|
if (!businessTypePattern.test(input.businessType)) {
|
|
throw new InventoryError('INVENTORY_BUSINESS_TYPE_INVALID');
|
|
}
|
|
if (!input.businessId.trim() || input.businessId.length > 128) {
|
|
throw new InventoryError('INVENTORY_BUSINESS_ID_INVALID');
|
|
}
|
|
if (!input.traceId.trim() || input.traceId.length > 128) {
|
|
throw new InventoryError('INVENTORY_TRACE_ID_INVALID');
|
|
}
|
|
if (!input.items.length || input.items.length > MAX_BATCH_ITEMS) {
|
|
throw new InventoryError('INVENTORY_BATCH_INVALID');
|
|
}
|
|
const quantities = new Map<string, number>();
|
|
for (const item of input.items) {
|
|
assertId(item.skuId, 'INVENTORY_SKU_ID_INVALID');
|
|
const quantity = boundedPositive(item.quantity, 'INVENTORY_QUANTITY_INVALID');
|
|
const combined = (quantities.get(item.skuId) ?? 0) + quantity;
|
|
quantities.set(
|
|
item.skuId,
|
|
boundedPositive(combined, 'INVENTORY_QUANTITY_INVALID')
|
|
);
|
|
}
|
|
const items = [...quantities.entries()]
|
|
.map(([skuId, quantity]) => ({ skuId, quantity }))
|
|
.sort((left, right) => compareIds(left.skuId, right.skuId));
|
|
if (input.operatorId != null) assertId(input.operatorId, 'INVENTORY_OPERATOR_ID_INVALID');
|
|
return {
|
|
...input,
|
|
items,
|
|
operatorId: input.operatorId ?? null,
|
|
ip: input.ip ?? '',
|
|
userAgent: input.userAgent ?? '',
|
|
reason: (input.reason ?? '').trim().slice(0, 512),
|
|
metadata: input.metadata ?? {}
|
|
};
|
|
}
|
|
|
|
function validateAdminBase(input: AdminMutationBase, allowCreateVersion = false) {
|
|
assertId(input.storeId, 'INVENTORY_STORE_ID_INVALID');
|
|
assertId(input.skuId, 'INVENTORY_SKU_ID_INVALID');
|
|
validateRequestId(input.requestId);
|
|
if (!input.reason.trim() || input.reason.trim().length > 512) {
|
|
throw new InventoryError('INVENTORY_REASON_INVALID');
|
|
}
|
|
if (input.expectedVersion === undefined) {
|
|
if (allowCreateVersion) throw new InventoryError('INVENTORY_VERSION_INVALID');
|
|
} else if (allowCreateVersion) {
|
|
boundedNonNegative(input.expectedVersion, 'INVENTORY_VERSION_INVALID');
|
|
} else {
|
|
boundedPositive(input.expectedVersion, 'INVENTORY_VERSION_INVALID');
|
|
}
|
|
}
|
|
|
|
function assertRequiredExpectedVersion(value: number | undefined, allowZero: boolean) {
|
|
if (value === undefined) throw new InventoryError('INVENTORY_VERSION_INVALID');
|
|
if (allowZero) boundedNonNegative(value, 'INVENTORY_VERSION_INVALID');
|
|
else boundedPositive(value, 'INVENTORY_VERSION_INVALID');
|
|
}
|
|
|
|
function mutationIdentity(input: {
|
|
requestId: string;
|
|
businessType: string;
|
|
businessId: string;
|
|
operation: InventoryOperation;
|
|
operatorId: string | null;
|
|
traceId: string;
|
|
reason: string;
|
|
metadata: Record<string, unknown>;
|
|
payload?: Record<string, unknown>;
|
|
fingerprint?: string;
|
|
}): MutationIdentity {
|
|
return {
|
|
requestId: input.requestId,
|
|
businessType: input.businessType,
|
|
businessId: input.businessId,
|
|
operation: input.operation,
|
|
operatorId: input.operatorId,
|
|
traceId: input.traceId,
|
|
reason: input.reason.trim(),
|
|
metadata: input.metadata,
|
|
fingerprint: input.fingerprint ?? idempotencyFingerprint({
|
|
businessType: input.businessType,
|
|
businessId: input.businessId,
|
|
operation: input.operation,
|
|
reason: input.reason.trim(),
|
|
payload: input.payload ?? {},
|
|
metadata: input.metadata
|
|
})
|
|
};
|
|
}
|
|
|
|
function idempotencyFingerprint(value: unknown) {
|
|
return createHash('sha256').update(stableJson(value)).digest('hex');
|
|
}
|
|
|
|
function stableJson(value: unknown): string {
|
|
if (value === null || typeof value !== 'object') return JSON.stringify(value);
|
|
if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`;
|
|
const object = value as Record<string, unknown>;
|
|
return `{${Object.keys(object).filter((key) => object[key] !== undefined).sort()
|
|
.map((key) => `${JSON.stringify(key)}:${stableJson(object[key])}`).join(',')}}`;
|
|
}
|
|
|
|
function delta(
|
|
stock: InventoryRow,
|
|
availableDelta: number,
|
|
lockedDelta: number,
|
|
lossDelta: number,
|
|
reservationDelta = 0
|
|
): DeltaState {
|
|
const next = {
|
|
policyType: stock.policyType,
|
|
availableQuantity: number(stock.availableQuantity) + availableDelta,
|
|
lockedQuantity: number(stock.lockedQuantity) + lockedDelta,
|
|
lossQuantity: number(stock.lossQuantity) + lossDelta,
|
|
lowStockThreshold: number(stock.lowStockThreshold)
|
|
};
|
|
validateState(next);
|
|
return { availableDelta, lockedDelta, lossDelta, reservationDelta, next };
|
|
}
|
|
|
|
function validateState(state: StockState) {
|
|
for (const value of [
|
|
state.availableQuantity, state.lockedQuantity, state.lossQuantity, state.lowStockThreshold
|
|
]) boundedNonNegative(value, 'INVENTORY_QUANTITY_OUT_OF_RANGE');
|
|
if (state.policyType === 'UNLIMITED'
|
|
&& (state.availableQuantity !== 0 || state.lockedQuantity !== 0
|
|
|| state.lossQuantity !== 0 || state.lowStockThreshold !== 0)) {
|
|
throw new InventoryError('INVENTORY_UNLIMITED_STATE_INVALID');
|
|
}
|
|
}
|
|
|
|
function assertTracked(stock: InventoryRow) {
|
|
if (stock.policyType !== 'TRACKED') {
|
|
throw new InventoryError('INVENTORY_UNLIMITED_MUTATION_FORBIDDEN');
|
|
}
|
|
}
|
|
|
|
function assertExpectedVersion(stock: InventoryRow, expected?: number) {
|
|
if (expected !== undefined && number(stock.version) !== expected) {
|
|
throw new InventoryError('INVENTORY_VERSION_CONFLICT');
|
|
}
|
|
}
|
|
|
|
function mutationResult(
|
|
stock: InventoryRow,
|
|
row: LedgerRow,
|
|
idempotent: boolean
|
|
): InventoryMutationResult {
|
|
const metadata = parseMetadata(row.metadata);
|
|
const policyType = metadata.resultPolicyType === 'TRACKED'
|
|
|| metadata.resultPolicyType === 'UNLIMITED'
|
|
? metadata.resultPolicyType
|
|
: stock.policyType;
|
|
const lowStockThreshold = typeof metadata.resultLowStockThreshold === 'number'
|
|
&& Number.isSafeInteger(metadata.resultLowStockThreshold)
|
|
&& metadata.resultLowStockThreshold >= 0
|
|
? metadata.resultLowStockThreshold
|
|
: number(stock.lowStockThreshold);
|
|
return {
|
|
inventoryId: String(row.inventoryId),
|
|
ledgerId: String(row.id),
|
|
storeId: String(row.storeId),
|
|
skuId: String(row.skuId),
|
|
operation: row.operation,
|
|
policyType,
|
|
availableQuantity: number(row.availableAfter),
|
|
lockedQuantity: number(row.lockedAfter),
|
|
lossQuantity: number(row.lossAfter),
|
|
lowStockThreshold,
|
|
version: number(row.versionAfter),
|
|
idempotent
|
|
};
|
|
}
|
|
|
|
function mapStock(row: InventoryListRow): InventoryStock {
|
|
const policyType = row.policyType;
|
|
const availableQuantity = number(row.availableQuantity);
|
|
const threshold = number(row.lowStockThreshold);
|
|
return {
|
|
id: String(row.id),
|
|
tenantId: String(row.tenantId),
|
|
storeId: String(row.storeId),
|
|
skuId: String(row.skuId),
|
|
skuCode: row.skuCode,
|
|
skuName: row.skuName,
|
|
productId: String(row.productId),
|
|
productCode: row.productCode,
|
|
productName: row.productName,
|
|
salePriceCents: number(row.salePriceCents),
|
|
policyType,
|
|
availableQuantity,
|
|
lockedQuantity: number(row.lockedQuantity),
|
|
lossQuantity: number(row.lossQuantity),
|
|
lowStockThreshold: threshold,
|
|
lowStock: policyType === 'TRACKED' && availableQuantity <= threshold,
|
|
version: number(row.version)
|
|
};
|
|
}
|
|
|
|
function mapLedger(row: LedgerRow): InventoryLedgerEntry {
|
|
return {
|
|
id: String(row.id),
|
|
inventoryId: String(row.inventoryId),
|
|
storeId: String(row.storeId),
|
|
skuId: String(row.skuId),
|
|
requestId: row.requestId,
|
|
businessType: row.businessType,
|
|
businessId: row.businessId,
|
|
operation: row.operation,
|
|
availableDelta: number(row.availableDelta),
|
|
lockedDelta: number(row.lockedDelta),
|
|
lossDelta: number(row.lossDelta),
|
|
availableAfter: number(row.availableAfter),
|
|
lockedAfter: number(row.lockedAfter),
|
|
lossAfter: number(row.lossAfter),
|
|
versionAfter: number(row.versionAfter),
|
|
operatorId: row.operatorId === null ? null : String(row.operatorId),
|
|
traceId: row.traceId,
|
|
reason: row.reason,
|
|
metadata: parseMetadata(row.metadata),
|
|
createdAt: row.createdAt
|
|
};
|
|
}
|
|
|
|
function normalizeStockRow(row: InventoryRow): InventoryRow {
|
|
return {
|
|
...row,
|
|
id: String(row.id),
|
|
tenantId: String(row.tenantId),
|
|
storeId: String(row.storeId),
|
|
skuId: String(row.skuId),
|
|
availableQuantity: number(row.availableQuantity),
|
|
lockedQuantity: number(row.lockedQuantity),
|
|
lossQuantity: number(row.lossQuantity),
|
|
lowStockThreshold: number(row.lowStockThreshold),
|
|
version: number(row.version)
|
|
};
|
|
}
|
|
|
|
function parseMetadata(value: unknown): Record<string, unknown> {
|
|
if (!value) return {};
|
|
if (typeof value === 'object' && !Buffer.isBuffer(value)) {
|
|
return value as Record<string, unknown>;
|
|
}
|
|
try {
|
|
const parsed = JSON.parse(Buffer.isBuffer(value) ? value.toString('utf8') : String(value));
|
|
return parsed && typeof parsed === 'object' ? parsed as Record<string, unknown> : {};
|
|
} catch {
|
|
return {};
|
|
}
|
|
}
|
|
|
|
function isDuplicateEntry(error: unknown) {
|
|
return Boolean(error && typeof error === 'object'
|
|
&& Reflect.get(error, 'code') === 'ER_DUP_ENTRY');
|
|
}
|
|
|
|
function auditFromActor(actor: ManagementActor): AuditIdentity {
|
|
return {
|
|
tenantId: actor.tenantId,
|
|
operatorId: actor.userId,
|
|
traceId: actor.traceId,
|
|
ip: actor.ip,
|
|
userAgent: actor.userAgent
|
|
};
|
|
}
|
|
|
|
function compareIds(left: string, right: string) {
|
|
const leftId = BigInt(left);
|
|
const rightId = BigInt(right);
|
|
return leftId < rightId ? -1 : leftId > rightId ? 1 : 0;
|
|
}
|
|
|
|
function assertId(value: string, code: string) {
|
|
if (!idPattern.test(value)) throw new InventoryError(code);
|
|
}
|
|
|
|
function validateRequestId(value: string) {
|
|
if (!requestIdPattern.test(value)) throw new InventoryError('INVENTORY_REQUEST_ID_INVALID');
|
|
}
|
|
|
|
function boundedPage(value: number) {
|
|
if (!Number.isSafeInteger(value) || value < 1 || value > 1_000_000) {
|
|
throw new InventoryError('INVENTORY_PAGE_INVALID');
|
|
}
|
|
return value;
|
|
}
|
|
|
|
function boundedPageSize(value: number) {
|
|
if (!Number.isSafeInteger(value) || value < 1 || value > 100) {
|
|
throw new InventoryError('INVENTORY_PAGE_SIZE_INVALID');
|
|
}
|
|
return value;
|
|
}
|
|
|
|
function boundedPositive(value: number, code: string) {
|
|
const parsed = boundedNonNegative(value, code);
|
|
if (parsed === 0) throw new InventoryError(code);
|
|
return parsed;
|
|
}
|
|
|
|
function boundedNonNegative(value: number, code: string) {
|
|
if (!Number.isSafeInteger(value) || value < 0 || value > MAX_QUANTITY) {
|
|
throw new InventoryError(code);
|
|
}
|
|
return value;
|
|
}
|
|
|
|
function boundedDelta(value: number, code: string) {
|
|
if (!Number.isSafeInteger(value) || value < -MAX_QUANTITY || value > MAX_QUANTITY) {
|
|
throw new InventoryError(code);
|
|
}
|
|
return value;
|
|
}
|
|
|
|
function number(value: unknown) { return Number(value); }
|