5panda.11ty/src/projects/clqms01/007-test-calc-engine.md

layout, tags, title, description, date, order

layout	tags	title	description	date	order
clqms-post.njk	clqms	Calculator Service Operators Reference	Concept, API contracts, and simplified operator reference for the calc engine	2026-03-17	7

Calculator Service: Concept and API Contract

Concept

CalculatorService evaluates formulas for test results using runtime variables.

Use it when you need to:

• transform a raw result into a calculated result,
• apply factors or demographic values (age, gender),
• reuse formula logic from test configuration.

Two API patterns are used in practice:

1. By Test Site ID - uses the calculation definition configured for that test site.
2. By Test Code/Name - resolves by test code or test name and returns a compact result map.

Responses normally follow { status, message, data }, except the compact test-code endpoint, which returns a key/value map.

---

Example API Contract

1) Calculate by Test Site

POST /api/calc/testsite/{testSiteID}
Content-Type: application/json

Purpose: Evaluate the configured formula for a specific test site.

Request example:

{
  "result": 85,
  "gender": "female",
  "age": 30
}

Success response example:

{
  "status": "success",
  "data": {
    "result": 92.4,
    "testSiteID": 123,
    "formula": "{result} * {factor} + {age}",
    "variables": {
      "result": 85,
      "gender": "female",
      "age": 30
    }
  }
}

Error response example:

{
  "status": "error",
  "message": "Missing variable: factor",
  "data": null
}

2) Calculate by Test Code or Name

POST /api/calc/testcode/{testCodeOrName}
Content-Type: application/json

Purpose: Evaluate a calculation by test code/name and return a compact map.

Request example:

{
  "result": 110,
  "factor": 1.1
}

Success response example:

{
  "GLU": 121
}

Error response example:

{}

---

Formula Reference (Simplified)

Arithmetic Operators

Operator	Meaning	Example
+	Add	5 + 3
-	Subtract	10 - 4
*	Multiply	6 * 7
/	Divide	20 / 4
%	Modulo	20 % 6
**	Power	2 ** 3

Comparison Operators

Operator	Meaning	Example
==	Equal	{result} == 10
!=	Not equal	{result} != 10
<	Less than	{result} < 10
<=	Less than or equal	{result} <= 10
>	Greater than	{result} > 10
>=	Greater than or equal	{result} >= 10

Logical Operators

Operator	Meaning	Example
&& (and)	Logical AND	{result} > 0 && {factor} > 0
|| (or)	Logical OR	{gender} == 1 || {gender} == 2
! (not)	Logical NOT	!({result} > 0)

Conditional Operators

Operator	Meaning	Example
?:	Ternary	{result} > 10 ? {result} : 10
??	Null fallback	{result} ?? 0

Functions

Function	Meaning	Example
min(a, b, ...)	Lowest value	min({result}, 10)
max(a, b, ...)	Highest value	max({result}, 10)
constant(name)	PHP constant by name	constant("PHP_INT_MAX")
enum(name)	PHP enum case by name	enum("App\\Enum\\Status::Active")

Constants

Constant	Meaning
true	Boolean true
false	Boolean false
null	Null

Variables Commonly Used

Variable	Type	Meaning
{result}	Float	Input result value
{factor}	Float	Multiplier (default usually 1)
{gender}	Integer	0 unknown, 1 female, 2 male
{age}	Float	Patient age
{ref_low}	Float	Reference low
{ref_high}	Float	Reference high

Gender can be passed as either numeric values (0, 1, 2) or strings ("unknown", "female", "male") and is normalized.

Formula Notes

• Use parentheses for precedence: (2 + 3) * 4.
• Use ** for exponentiation; ^ is XOR.
• Implicit multiplication is not supported (2x is invalid, use 2 * x).

---

Quick Usage Examples

{result} * {factor} + 10
{weight} / ({height} ** 2)
{result} * (1 + 0.1 * {gender})

---

Validation and Errors

Validate formulas before saving.

Typical error cases:

• invalid syntax,
• missing variable,
• non-numeric value after normalization,
• division by zero.

Recommended flow: validate formula -> save formula -> evaluate with guarded error handling.