zhangwenrui/material_manage_system

Fork 0

文睿张 31aae223c2 Initial commit

2026-09-15 16:08:18 +08:00

15 KiB

Raw Blame History

Warehouse Material Management System - API Specification

Base URL: /api

1. Material APIs

GET /materials

List all materials with optional filtering.

Query Parameters:

Parameter	Type	Required	Description
search	string	No	Search by material code or name
category	string	No	Filter by category

Response Body:

{
  "code": 0,
  "data": [
    {
      "id": 1,
      "material_code": "M001",
      "name": "Steel Plate",
      "spec": "10mm x 2000mm x 6000mm",
      "category": "Raw Material",
      "unit": "pcs",
      "warning_stock": 100,
      "created_at": "2026-01-01T08:00:00Z",
      "updated_at": "2026-01-01T08:00:00Z"
    }
  ],
  "message": "success"
}

HTTP Status Codes:

200 OK - Success

GET /materials/:id

Get a single material by ID.

Path Parameters:

Parameter	Type	Required	Description
id	integer	Yes	Material ID

Response Body:

{
  "code": 0,
  "data": {
    "id": 1,
    "material_code": "M001",
    "name": "Steel Plate",
    "spec": "10mm x 2000mm x 6000mm",
    "category": "Raw Material",
    "unit": "pcs",
    "warning_stock": 100,
    "created_at": "2026-01-01T08:00:00Z",
    "updated_at": "2026-01-01T08:00:00Z"
  },
  "message": "success"
}

HTTP Status Codes:

200 OK - Success
404 Not Found - Material not found

POST /materials

Create a new material.

Request Body:

{
  "material_code": "M001",
  "name": "Steel Plate",
  "spec": "10mm x 2000mm x 6000mm",
  "category": "Raw Material",
  "unit": "pcs",
  "warning_stock": 100
}

Field	Type	Required	Description
material_code	string	Yes	Unique material code
name	string	Yes	Material name
spec	string	No	Specification
category	string	No	Material category
unit	string	No	Unit of measure (default: pcs)
warning_stock	integer	No	Warning stock threshold (default: 0)

Response Body:

{
  "code": 0,
  "data": {
    "id": 1,
    "material_code": "M001",
    "name": "Steel Plate",
    "spec": "10mm x 2000mm x 6000mm",
    "category": "Raw Material",
    "unit": "pcs",
    "warning_stock": 100,
    "created_at": "2026-01-01T08:00:00Z",
    "updated_at": "2026-01-01T08:00:00Z"
  },
  "message": "Material created successfully"
}

HTTP Status Codes:

201 Created - Material created successfully
400 Bad Request - Invalid request body or material code already exists

PUT /materials/:id

Update an existing material.

Path Parameters:

Parameter	Type	Required	Description
id	integer	Yes	Material ID

Request Body:

{
  "material_code": "M001",
  "name": "Steel Plate",
  "spec": "12mm x 2000mm x 6000mm",
  "category": "Raw Material",
  "unit": "pcs",
  "warning_stock": 150
}

All fields are optional. Only provided fields will be updated.

Response Body:

{
  "code": 0,
  "data": {
    "id": 1,
    "material_code": "M001",
    "name": "Steel Plate",
    "spec": "12mm x 2000mm x 6000mm",
    "category": "Raw Material",
    "unit": "pcs",
    "warning_stock": 150,
    "created_at": "2026-01-01T08:00:00Z",
    "updated_at": "2026-01-02T10:00:00Z"
  },
  "message": "Material updated successfully"
}

HTTP Status Codes:

200 OK - Material updated successfully
400 Bad Request - Invalid request body
404 Not Found - Material not found

DELETE /materials/:id

Delete a material.

Path Parameters:

Parameter	Type	Required	Description
id	integer	Yes	Material ID

Response Body:

{
  "code": 0,
  "data": null,
  "message": "Material deleted successfully"
}

HTTP Status Codes:

200 OK - Material deleted successfully
404 Not Found - Material not found

2. Inbound APIs

GET /inbound

List all inbound orders.

Query Parameters:

Parameter	Type	Required	Description
search	string	No	Search by handler or supplier

Response Body:

{
  "code": 0,
  "data": [
    {
      "id": 1,
      "handler": "John Doe",
      "supplier": "ABC Steel Co.",
      "status": "completed",
      "created_at": "2026-01-01T08:00:00Z",
      "updated_at": "2026-01-01T08:00:00Z"
    }
  ],
  "message": "success"
}

HTTP Status Codes:

200 OK - Success

GET /inbound/:id

Get a single inbound order with its items.

Path Parameters:

Parameter	Type	Required	Description
id	integer	Yes	Inbound order ID

Response Body:

{
  "code": 0,
  "data": {
    "id": 1,
    "handler": "John Doe",
    "supplier": "ABC Steel Co.",
    "status": "completed",
    "created_at": "2026-01-01T08:00:00Z",
    "updated_at": "2026-01-01T08:00:00Z",
    "items": [
      {
        "id": 1,
        "material_id": 1,
        "material_code": "M001",
        "material_name": "Steel Plate",
        "quantity": 500
      }
    ]
  },
  "message": "success"
}

HTTP Status Codes:

200 OK - Success
404 Not Found - Inbound order not found

POST /inbound

Create a new inbound order.

Request Body:

{
  "handler": "John Doe",
  "supplier": "ABC Steel Co.",
  "items": [
    { "material_id": 1, "quantity": 500 },
    { "material_id": 2, "quantity": 200 }
  ]
}

Field	Type	Required	Description
handler	string	Yes	Handler name
supplier	string	Yes	Supplier name
items	array	Yes	List of inbound items

Items Array Structure:

Field	Type	Required	Description
material_id	integer	Yes	Material ID
quantity	integer	Yes	Inbound quantity (> 0)

Response Body:

{
  "code": 0,
  "data": {
    "id": 1,
    "handler": "John Doe",
    "supplier": "ABC Steel Co.",
    "status": "completed",
    "created_at": "2026-01-01T08:00:00Z",
    "updated_at": "2026-01-01T08:00:00Z",
    "items": [
      {
        "id": 1,
        "material_id": 1,
        "material_code": "M001",
        "material_name": "Steel Plate",
        "quantity": 500
      }
    ]
  },
  "message": "Inbound order created successfully"
}

HTTP Status Codes:

201 Created - Inbound order created successfully
400 Bad Request - Invalid request body or material not found

GET /inbound/materials/:materialId

Get inbound records for a specific material.

Path Parameters:

Parameter	Type	Required	Description
materialId	integer	Yes	Material ID

Response Body:

{
  "code": 0,
  "data": [
    {
      "id": 1,
      "inbound_id": 1,
      "handler": "John Doe",
      "supplier": "ABC Steel Co.",
      "quantity": 500,
      "created_at": "2026-01-01T08:00:00Z"
    }
  ],
  "message": "success"
}

HTTP Status Codes:

200 OK - Success
404 Not Found - Material not found

3. Outbound APIs

GET /outbound

List all outbound orders.

Query Parameters:

Parameter	Type	Required	Description
search	string	No	Search by handler or receiver

Response Body:

{
  "code": 0,
  "data": [
    {
      "id": 1,
      "handler": "Jane Smith",
      "receiver": "XYZ Factory",
      "status": "completed",
      "created_at": "2026-01-01T08:00:00Z",
      "updated_at": "2026-01-01T08:00:00Z"
    }
  ],
  "message": "success"
}

HTTP Status Codes:

200 OK - Success

GET /outbound/:id

Get a single outbound order with its items.

Path Parameters:

Parameter	Type	Required	Description
id	integer	Yes	Outbound order ID

Response Body:

{
  "code": 0,
  "data": {
    "id": 1,
    "handler": "Jane Smith",
    "receiver": "XYZ Factory",
    "status": "completed",
    "created_at": "2026-01-01T08:00:00Z",
    "updated_at": "2026-01-01T08:00:00Z",
    "items": [
      {
        "id": 1,
        "material_id": 1,
        "material_code": "M001",
        "material_name": "Steel Plate",
        "quantity": 100
      }
    ]
  },
  "message": "success"
}

HTTP Status Codes:

200 OK - Success
404 Not Found - Outbound order not found

POST /outbound

Create a new outbound order.

Request Body:

{
  "handler": "Jane Smith",
  "receiver": "XYZ Factory",
  "items": [
    { "material_id": 1, "quantity": 100 },
    { "material_id": 2, "quantity": 50 }
  ]
}

Field	Type	Required	Description
handler	string	Yes	Handler name
receiver	string	Yes	Receiver name
items	array	Yes	List of outbound items

Items Array Structure:

Field	Type	Required	Description
material_id	integer	Yes	Material ID
quantity	integer	Yes	Outbound quantity (> 0)

Response Body:

{
  "code": 0,
  "data": {
    "id": 1,
    "handler": "Jane Smith",
    "receiver": "XYZ Factory",
    "status": "completed",
    "created_at": "2026-01-01T08:00:00Z",
    "updated_at": "2026-01-01T08:00:00Z",
    "items": [
      {
        "id": 1,
        "material_id": 1,
        "material_code": "M001",
        "material_name": "Steel Plate",
        "quantity": 100
      }
    ]
  },
  "message": "Outbound order created successfully"
}

HTTP Status Codes:

201 Created - Outbound order created successfully
400 Bad Request - Invalid request body, material not found, or insufficient stock

GET /outbound/materials/:materialId

Get outbound records for a specific material.

Path Parameters:

Parameter	Type	Required	Description
materialId	integer	Yes	Material ID

Response Body:

{
  "code": 0,
  "data": [
    {
      "id": 1,
      "outbound_id": 1,
      "handler": "Jane Smith",
      "receiver": "XYZ Factory",
      "quantity": 100,
      "created_at": "2026-01-01T08:00:00Z"
    }
  ],
  "message": "success"
}

HTTP Status Codes:

200 OK - Success
404 Not Found - Material not found

4. Stock APIs

GET /stock

List all stock information with material details.

Response Body:

{
  "code": 0,
  "data": [
    {
      "material_id": 1,
      "material_code": "M001",
      "name": "Steel Plate",
      "spec": "10mm x 2000mm x 6000mm",
      "category": "Raw Material",
      "unit": "pcs",
      "current_stock": 500,
      "warning_stock": 100
    }
  ],
  "message": "success"
}

HTTP Status Codes:

200 OK - Success

GET /stock/:materialId

Get stock information for a single material.

Path Parameters:

Parameter	Type	Required	Description
materialId	integer	Yes	Material ID

Response Body:

{
  "code": 0,
  "data": {
    "material_id": 1,
    "material_code": "M001",
    "name": "Steel Plate",
    "spec": "10mm x 2000mm x 6000mm",
    "category": "Raw Material",
    "unit": "pcs",
    "current_stock": 500,
    "warning_stock": 100
  },
  "message": "success"
}

HTTP Status Codes:

200 OK - Success
404 Not Found - Material not found

GET /stock/warning

List materials where current stock is below warning stock threshold.

Response Body:

{
  "code": 0,
  "data": [
    {
      "material_id": 2,
      "material_code": "M002",
      "name": "Aluminum Rod",
      "spec": "20mm x 3000mm",
      "category": "Raw Material",
      "unit": "pcs",
      "current_stock": 30,
      "warning_stock": 100
    }
  ],
  "message": "success"
}

HTTP Status Codes:

200 OK - Success

GET /stock/logs/:materialId

Get stock change logs for a specific material.

Path Parameters:

Parameter	Type	Required	Description
materialId	integer	Yes	Material ID

Response Body:

{
  "code": 0,
  "data": [
    {
      "id": 1,
      "material_id": 1,
      "change_type": "inbound",
      "quantity": 500,
      "balance": 500,
      "reference_id": 1,
      "reference_type": "inbound",
      "created_at": "2026-01-01T08:00:00Z"
    },
    {
      "id": 2,
      "material_id": 1,
      "change_type": "outbound",
      "quantity": 100,
      "balance": 400,
      "reference_id": 1,
      "reference_type": "outbound",
      "created_at": "2026-01-01T10:00:00Z"
    }
  ],
  "message": "success"
}

HTTP Status Codes:

200 OK - Success
404 Not Found - Material not found

Common Response Structure

All API responses follow this structure:

{
  "code": 0,
  "data": {},
  "message": "success"
}

Field	Type	Description
code	integer	Status code (0 = success, non-zero = error)
data	object	Response data (null for delete operations)
message	string	Human-readable message

HTTP Status Code Summary

Status Code	Description
200 OK	Request succeeded
201 Created	Resource created successfully
400 Bad Request	Invalid request body or parameters
404 Not Found	Resource not found
500 Internal Server Error	Server-side error

15 KiB Raw Blame History

Warehouse Material Management System - API Specification

1. Material APIs

GET /materials

GET /materials/:id

POST /materials

PUT /materials/:id

DELETE /materials/:id

2. Inbound APIs

GET /inbound

GET /inbound/:id

POST /inbound

GET /inbound/materials/:materialId

3. Outbound APIs

GET /outbound

GET /outbound/:id

POST /outbound

GET /outbound/materials/:materialId

4. Stock APIs

GET /stock

GET /stock/:materialId

GET /stock/warning

GET /stock/logs/:materialId

Common Response Structure

HTTP Status Code Summary

15 KiB

Raw Blame History