first commit

docs/08_DOMAIN_MODEL.md

@@ -0,0 +1,195 @@
+# Domain Model
+
+## Abordagem de modelação
+O domínio deve ser modelado em torno do fluxo operacional do negócio e não apenas em torno de produtos abstratos. A unidade principal de controlo é a encomenda ao fornecedor, a receção, a unidade de inventário e o ciclo de venda/envio.
+
+## Entidades principais
+
+### User
+Representa o utilizador autenticado da aplicação.
+Na V1 pode existir apenas um utilizador administrador, mas a modelação deve admitir crescimento futuro.
+
+### Supplier
+Representa um fornecedor de roupa.
+
+Campos indicativos:
+- id
+- name
+- contact_name
+- email
+- phone
+- notes
+- created_at
+- updated_at
+
+### PurchaseOrder
+Representa uma encomenda feita a um fornecedor.
+
+Campos indicativos:
+- id
+- supplier_id
+- external_reference
+- status
+- ordered_at
+- expected_at
+- notes
+- created_at
+- updated_at
+
+### PurchaseOrderItem
+Representa uma linha da encomenda, com artigo, variante e quantidade.
+
+Campos indicativos:
+- id
+- purchase_order_id
+- product_model_id
+- variant_label
+- size
+- color
+- sku_supplier
+- quantity_ordered
+- unit_cost
+- notes
+
+### Receipt
+Representa um evento de receção de mercadoria relativo a uma encomenda.
+
+Campos indicativos:
+- id
+- purchase_order_id
+- receipt_date
+- status
+- notes
+- created_by
+- created_at
+
+### ReceiptItem
+Representa a quantidade recebida de cada linha da encomenda.
+
+Campos indicativos:
+- id
+- receipt_id
+- purchase_order_item_id
+- quantity_received
+- quantity_rejected
+- discrepancy_note
+
+### ProductModel
+Representa o artigo ou modelo comercial.
+
+Campos indicativos:
+- id
+- name
+- brand
+- category
+- default_size
+- default_color
+- internal_sku
+- supplier_sku
+- notes
+- created_at
+- updated_at
+
+### InventoryUnit
+Representa uma unidade concreta ou unidade lógica rastreável no inventário.
+
+Campos indicativos:
+- id
+- product_model_id
+- purchase_order_id
+- receipt_item_id
+- inventory_status
+- condition
+- storage_location
+- cost_price
+- ready_for_listing_at
+- created_at
+- updated_at
+
+Nota:
+A V1 deve favorecer rastreabilidade por unidade sempre que possível. Caso existam cenários de stock agregado, essa decisão deve ser explícita e documentada.
+
+### Listing
+Representa um anúncio publicado ou preparado para publicação.
+
+Campos indicativos:
+- id
+- inventory_unit_id
+- platform
+- external_reference
+- listing_status
+- listed_price
+- listed_at
+- url
+- notes
+
+### Customer
+Representa o comprador associado a uma venda.
+
+Campos indicativos:
+- id
+- name
+- platform_username
+- shipping_name
+- shipping_address
+- phone
+- email
+- notes
+
+### Sale
+Representa a venda de uma unidade ou artigo.
+
+Campos indicativos:
+- id
+- inventory_unit_id
+- customer_id
+- sale_channel
+- sale_status
+- sale_price
+- sold_at
+- notes
+- created_at
+
+### Shipment
+Representa o envio associado a uma venda.
+
+Campos indicativos:
+- id
+- sale_id
+- shipment_status
+- shipped_at
+- tracking_code
+- carrier
+- label_reference
+- notes
+
+### StatusHistory
+Representa o histórico de transições de estado relevantes.
+
+Campos indicativos:
+- id
+- entity_type
+- entity_id
+- from_status
+- to_status
+- changed_by
+- changed_at
+- note
+
+## Relações principais
+- Um User pode criar Receipts e alterar estados
+- Um Supplier pode ter muitas PurchaseOrders
+- Uma PurchaseOrder tem muitos PurchaseOrderItems
+- Uma PurchaseOrder pode ter muitas Receipts
+- Uma Receipt tem muitos ReceiptItems
+- Um ProductModel pode existir em muitos PurchaseOrderItems
+- Um InventoryUnit resulta de receção e registo
+- Um InventoryUnit pode originar um Listing
+- Um InventoryUnit pode estar associado a uma Sale
+- Uma Sale pode gerar um Shipment
+- As entidades críticas podem gerar StatusHistory
+
+## Observações de implementação
+- O modelo de dados deve ser implementado em PostgreSQL
+- O acesso à base de dados deve ser feito através de Prisma ORM
+- As regras de domínio não devem ficar dispersas em componentes de interface