Inventory enhancements

microservices/InventoryApi/DOCUMENTS.md

@@ -3,6 +3,29 @@
 This service stores one MongoDB document per inventory item record.
 
 Inbound JSON documents
+- CreateItemDefinitionRequest (`POST /api/inventory/item-definitions`)
+  ```json
+  {
+    "itemKey": "wood",
+    "displayName": "Wood",
+    "stackable": true,
+    "maxStackSize": 20,
+    "category": "resource",
+    "equipSlot": null
+  }
+  ```
+
+- UpdateItemDefinitionRequest (`PUT /api/inventory/item-definitions/{itemKey}`)
+  ```json
+  {
+    "displayName": "Wood",
+    "stackable": true,
+    "maxStackSize": 20,
+    "category": "resource",
+    "equipSlot": null
+  }
+  ```
+
 - GrantInventoryItemRequest (`POST /api/inventory/by-owner/{ownerType}/{ownerId}/grant`)
   ```json
   {
@@ -63,6 +86,20 @@ Inbound JSON documents
   Only valid for items currently equipped by a character.
 
 Stored documents (MongoDB)
+- ItemDefinition
+  ```json
+  {
+    "itemKey": "wood",
+    "displayName": "Wood",
+    "stackable": true,
+    "maxStackSize": 20,
+    "category": "resource",
+    "equipSlot": null,
+    "createdUtc": "string (ISO-8601 datetime)",
+    "updatedUtc": "string (ISO-8601 datetime)"
+  }
+  ```
+
 - InventoryItem
   ```json
   {
@@ -112,6 +149,19 @@ Location stack example:
 ```
 
 Outbound JSON documents
+- ItemDefinitionResponse
+  ```json
+  {
+    "itemKey": "wood",
+    "displayName": "Wood",
+    "stackable": true,
+    "maxStackSize": 20,
+    "category": "resource",
+    "equipSlot": null,
+    "updatedUtc": "string (ISO-8601 datetime)"
+  }
+  ```
+
 - InventoryItemResponse
   ```json
   {
@@ -160,10 +210,12 @@ Outbound JSON documents
   ```
 
 Validation rules
+- `itemKey` must map to an existing item definition before item instances can be created
 - `ownerType` must be a supported container type
 - `ownerId` must map to an existing owning entity where applicable
 - non-`SUPER` callers may only access owned character items unless explicit gameplay rules allow a world container read/write
 - `quantity` must be greater than `0`
+- non-stackable item definitions must have `maxStackSize = 1`
 - non-stackable items must have `quantity = 1`
 - equipped items must have `slot = null`
 - unequipped bag items must have `equippedSlot = null`
@@ -172,11 +224,11 @@ Validation rules
 - equipment occupancy must be unique for `(ownerType, ownerId, equippedSlot)` where `equippedSlot != null`
 
 Recommended indexes
-- unique on `id`
+- unique on `itemKey` for item definitions
 - index on `(ownerType, ownerId)`
 - unique on `(ownerType, ownerId, slot)` for bag slots
 - unique on `(ownerType, ownerId, equippedSlot)` for equipped slots
-- index on `itemKey`
+- index on `itemKey` for inventory items
 
 Behavior rules
 - moving a full non-stackable item should update its owner and slot in place
@@ -184,3 +236,4 @@ Behavior rules
 - moving into a compatible stack should merge quantities and delete or reduce the source record
 - cross-owner transfer should be transactional when it mutates multiple records
 - auctions should reference `itemId` values directly instead of copying item state into the auction document
+- the service does not auto-seed item definitions; `ItemDefinitions` must be populated explicitly