mahdahar/5panda.11ty
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update clqms docs set and index

Browse Source
This commit is contained in:
mahdahar 2026-03-17 15:31:51 +07:00
parent fcf996435c
commit bc69ae3570
4 changed files with 344 additions and 104 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
AGENTS.md
View File

@ -138,12 +138,4 @@ eleventyConfig.addFilter("dateFormat", (date, format = "full") => {
- Files use `.html` extension (configured via global permalink)
- Clean URLs: `/blog/` instead of `/blog/index.html`
- Nested folders auto-generate index pages
## Communication Style
When interacting with the user:
- Address them professionally as "commander"
- Use space/sci-fi themed language when appropriate
- Start with basmalah, end with hamdalah
- Be concise and await orders
- Nested folders auto-generate index pages

216
src/projects/clqms01/007-calculator-operators.md → src/projects/clqms01/007-test-calc-engine.md
View File

@ -2,8 +2,8 @@
layout: clqms-post.njk
tags: clqms
title: "Calculator Service Operators Reference"
description: "Complete reference for mathematical operators, functions, and constants available in the CalculatorService."
date: 2026-03-16
description: "Operators, functions, constants, and API usage for the calc engine"
date: 2026-03-17
order: 7
---
@ -11,7 +11,68 @@ order: 7
## Overview
The `CalculatorService` (`app/Services/CalculatorService.php`) uses the [mossadal/math-parser](https://github.com/mossadal/math-parser) library to safely evaluate mathematical expressions. This document lists all available operators, functions, and constants.
The `CalculatorService` (`app/Services/CalculatorService.php`) evaluates formulas with Symfony's `ExpressionLanguage`. This document lists the operators, functions, and constants that are available in the current implementation.
---
## API Endpoints
All endpoints live under `/api` and accept JSON. Responses use the standard `{ status, message, data }` envelope unless stated otherwise.
### Calculate By Test Site
Uses the `testdefcal` definition for a test site. The incoming body supplies the variables required by the formula.
```http
POST /api/calc/testsite/123
Content-Type: application/json
{
"result": 85,
"gender": "female",
"age": 30
}
```
Response:
```json
{
"status": "success",
"data": {
"result": 92.4,
"testSiteID": 123,
"formula": "{result} * {factor} + {age}",
"variables": {
"result": 85,
"gender": "female",
"age": 30
}
}
}
```
### Calculate By Code Or Name
Evaluates a configured calculation by `TestSiteCode` or `TestSiteName`. Returns a compact map with a single key/value or `{}` on failure.
```http
POST /api/calc/testcode/GLU
Content-Type: application/json
{
"result": 110,
"factor": 1.1
}
```
Response:
```json
{
"GLU": 121
}
```
---
@ -25,9 +86,34 @@ The `CalculatorService` (`app/Services/CalculatorService.php`) uses the [mossada
| `-` | Subtraction | `10 - 4` | `6` |
| `*` | Multiplication | `6 * 7` | `42` |
| `/` | Division | `20 / 4` | `5` |
| `^` | Exponentiation (power) | `2 ^ 3` | `8` |
| `!` | Factorial | `5!` | `120` |
| `!!` | Semi-factorial (double factorial) | `5!!` | `15` |
| `%` | Modulo | `20 % 6` | `2` |
| `**` | Exponentiation (power) | `2 ** 3` | `8` |
### Comparison Operators
| Operator | Description | 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 | Description | Example |
|----------|-------------|---------|
| `and` / `&&` | Logical AND | `{result} > 0 and {factor} > 0` |
| `or` / `||` | Logical OR | `{gender} == 1 or {gender} == 2` |
| `!` / `not` | Logical NOT | `not ({result} > 0)` |
### Conditional Operators
| Operator | Description | Example |
|----------|-------------|---------|
| `?:` | Ternary | `{result} > 10 ? {result} : 10` |
| `??` | Null coalescing | `{result} ?? 0` |
### Parentheses
@ -38,84 +124,35 @@ Use parentheses to control operation precedence:
2 + 3 * 4 // Result: 14
```
### Notes
- `^` is bitwise XOR (not exponentiation). Use `**` for powers.
- Variables must be numeric after normalization (gender is mapped to 0/1/2).
---
## Mathematical Functions
## Functions
### Rounding Functions
Only the default ExpressionLanguage functions are available:
| Function | Description | Example |
|----------|-------------|---------|
| `sqrt(x)` | Square root | `sqrt(16)` → `4` |
| `round(x)` | Round to nearest integer | `round(3.7)` → `4` |
| `ceil(x)` | Round up to integer | `ceil(3.2)` → `4` |
| `floor(x)` | Round down to integer | `floor(3.9)` → `3` |
| `abs(x)` | Absolute value | `abs(-5)` → `5` |
| `sgn(x)` | Sign function | `sgn(-10)` → `-1` |
### Trigonometric Functions (Radians)
| Function | Description | Example |
|----------|-------------|---------|
| `sin(x)` | Sine | `sin(pi/2)` → `1` |
| `cos(x)` | Cosine | `cos(0)` → `1` |
| `tan(x)` | Tangent | `tan(pi/4)` → `1` |
| `cot(x)` | Cotangent | `cot(pi/4)` → `1` |
### Trigonometric Functions (Degrees)
| Function | Description | Example |
|----------|-------------|---------|
| `sind(x)` | Sine (degrees) | `sind(90)` → `1` |
| `cosd(x)` | Cosine (degrees) | `cosd(0)` → `1` |
| `tand(x)` | Tangent (degrees) | `tand(45)` → `1` |
| `cotd(x)` | Cotangent (degrees) | `cotd(45)` → `1` |
### Hyperbolic Functions
| Function | Description | Example |
|----------|-------------|---------|
| `sinh(x)` | Hyperbolic sine | `sinh(1)` → `1.175...` |
| `cosh(x)` | Hyperbolic cosine | `cosh(1)` → `1.543...` |
| `tanh(x)` | Hyperbolic tangent | `tanh(1)` → `0.761...` |
| `coth(x)` | Hyperbolic cotangent | `coth(2)` → `1.037...` |
### Inverse Trigonometric Functions
| Function | Aliases | Description | Example |
|----------|---------|-------------|---------|
| `arcsin(x)` | `asin(x)` | Inverse sine | `arcsin(0.5)` → `0.523...` |
| `arccos(x)` | `acos(x)` | Inverse cosine | `arccos(0.5)` → `1.047...` |
| `arctan(x)` | `atan(x)` | Inverse tangent | `arctan(1)` → `0.785...` |
| `arccot(x)` | `acot(x)` | Inverse cotangent | `arccot(1)` → `0.785...` |
### Inverse Hyperbolic Functions
| Function | Aliases | Description | Example |
|----------|---------|-------------|---------|
| `arsinh(x)` | `asinh(x)`, `arcsinh(x)` | Inverse hyperbolic sine | `arsinh(1)` → `0.881...` |
| `arcosh(x)` | `acosh(x)`, `arccosh(x)` | Inverse hyperbolic cosine | `arcosh(2)` → `1.316...` |
| `artanh(x)` | `atanh(x)`, `arctanh(x)` | Inverse hyperbolic tangent | `artanh(0.5)` → `0.549...` |
| `arcoth(x)` | `acoth(x)`, `arccoth(x)` | Inverse hyperbolic cotangent | `arcoth(2)` → `0.549...` |
### Logarithmic & Exponential Functions
| Function | Aliases | Description | Example |
|----------|---------|-------------|---------|
| `exp(x)` | - | Exponential (e^x) | `exp(2)` → `7.389...` |
| `log(x)` | `ln(x)` | Natural logarithm (base e) | `log(e)` → `1` |
| `log10(x)` | `lg(x)` | Logarithm base 10 | `log10(100)` → `2` |
| `min(a, b, ...)` | Minimum value | `min({result}, 10)` |
| `max(a, b, ...)` | Maximum 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 | Value | Description | Example |
|----------|-------|-------------|---------|
| `pi` | 3.14159265... | Ratio of circle circumference to diameter | `pi * r ^ 2` |
| `e` | 2.71828182... | Euler's number | `e ^ x` |
| `NAN` | Not a Number | Invalid mathematical result | - |
| `INF` | Infinity | Positive infinity | - |
ExpressionLanguage recognizes boolean and null literals:
| Constant | Value | Description |
|----------|-------|-------------|
| `true` | `true` | Boolean true |
| `false` | `false` | Boolean false |
| `null` | `null` | Null value |
---
@ -148,16 +185,12 @@ Or use string values: `'unknown'`, `'female'`, `'male'`
## Implicit Multiplication
The parser supports implicit multiplication (no explicit `*` operator needed):
Implicit multiplication is not supported. Always use `*` between values:
| Expression | Parsed As | Result (x=2, y=3) |
|------------|-----------|-------------------|
| `2x` | `2 * x` | `4` |
| `x sin(x)` | `x * sin(x)` | `1.818...` |
| `2xy` | `2 * x * y` | `12` |
| `x^2y` | `x^2 * y` | `12` |
**Note:** Implicit multiplication has the same precedence as explicit multiplication. `xy^2z` is parsed as `x*y^2*z`, NOT as `x*y^(2*z)`.
| Expression | Use Instead |
|------------|-------------|
| `2x` | `2 * x` |
| `{result}{factor}` | `{result} * {factor}` |
---
@ -174,13 +207,9 @@ $calculator = new CalculatorService();
$result = $calculator->calculate("5 + 3 * 2");
// Result: 11
// Using functions
$result = $calculator->calculate("sqrt(16) + abs(-5)");
// Result: 9
// Using constants
$result = $calculator->calculate("2 * pi * r", ['r' => 5]);
// Result: 31.415...
// Using min/max
$result = $calculator->calculate("max({result}, 10)", ['result' => 7]);
// Result: 10
```
### With Variables
@ -199,7 +228,7 @@ $result = $calculator->calculate($formula, $variables);
### BMI Calculation
```php
$formula = "{weight} / ({height} ^ 2)";
$formula = "{weight} / ({height} ** 2)";
$variables = [
'weight' => 70, // kg
'height' => 1.75 // meters
@ -226,8 +255,8 @@ $result = $calculator->calculate($formula, $variables);
### Complex Formula
```php
// Pythagorean theorem with rounding
$formula = "round(sqrt({a} ^ 2 + {b} ^ 2))";
// Pythagorean theorem
$formula = "(({a} ** 2 + {b} ** 2) ** 0.5)";
$variables = [
'a' => 3,
'b' => 4
@ -313,6 +342,5 @@ Common errors:
## References
- [math-parser GitHub](https://github.com/mossadal/math-parser)
- [math-parser Documentation](http://mossadal.github.io/math-parser/)
- [Symfony ExpressionLanguage](https://symfony.com/doc/current/components/expression_language.html)
- `app/Services/CalculatorService.php`

202
src/projects/clqms01/009-audit-logging.md Normal file
View File

@ -0,0 +1,202 @@
---
layout: clqms-post.njk
tags: clqms
title: "Audit Logging"
description: "Unified audit logging model, event catalog, and capture rules for CLQMS."
date: 2026-03-17
order: 9
---
# Audit Logging Strategy
## Overview
This document defines how CLQMS should capture audit and operational logs across four tables:
- `logpatient` — patient, visit, and ADT activity
- `logorder` — orders, tests, specimens, results, and QC
- `logmaster` — master data and configuration changes
- `logsystem` — sessions, security, import/export, and system operations
The intent is to audit all domains, including master data changes, and to standardize event capture so reporting and compliance are consistent.
## Table Ownership
| Event | Table |
| --- | --- |
| Patient registered/updated/merged | `logpatient` |
| Insurance/consent changed | `logpatient` |
| Patient visit (admit/transfer/discharge) | `logpatient` |
| Order created/cancelled | `logorder` |
| Sample received/rejected | `logorder` |
| Result entered/verified/amended | `logorder` |
| Result released/retracted/corrected | `logorder` |
| QC result recorded | `logorder` |
| Test panel added/removed | `logmaster` |
| Reference range changed | `logmaster` |
| Analyzer config updated | `logmaster` |
| User role changed | `logmaster` |
| User login/logout | `logsystem` |
| Import/export job start/end | `logsystem` |
## Standard Log Schema (Shared Columns)
Use a shared schema for all four tables to keep instrumentation and reporting consistent. The legacy names below match existing patterns and can be reused.
| Column | Description |
| --- | --- |
| `LogID` (PK) | Auto increment primary key per table (e.g., `LogPatientID`) |
| `TblName` | Source table name |
| `RecID` | Record ID of the entity |
| `FldName` | Field name that changed (nullable for bulk events) |
| `FldValuePrev` | Previous value (string or JSON) |
| `FldValueNew` | New value (string or JSON) |
| `UserID` | Acting user ID (nullable for system actions) |
| `SiteID` | Site context |
| `DIDType` | Device identifier type |
| `DID` | Device identifier |
| `MachineID` | Workstation or host identifier |
| `SessionID` | Session identifier |
| `AppID` | Client application ID |
| `ProcessID` | Process/workflow identifier |
| `WebPageID` | UI page/context (nullable) |
| `EventID` | Event code (see catalog) |
| `ActivityID` | Action code (create/update/delete/read/etc.) |
| `Reason` | User/system reason |
| `LogDate` | Timestamp of event |
| `Context` | JSON metadata (optional but recommended) |
| `IpAddress` | Remote IP (optional but recommended) |
Recommended: keep a JSON string in `Context` for extra details (e.g., route, request id, batch id, error message). Use size limits to avoid oversized rows.
## Event Catalog
### logpatient
**Patient core**
- Register patient
- Update demographics
- Merge/unmerge/split
- Identity changes (MRN, external identifiers)
- Consent grant/revoke/update
- Insurance add/update/remove
- Patient record view (if required by compliance)
**Visit/ADT**
- Admit, transfer, discharge
- Bed/ward/unit changes
- Visit status updates
**Other**
- Patient notes/attachments added/removed
- Patient alerts/flags changes
### logorder
**Orders/tests**
- Create/cancel/reopen order
- Add/remove tests
- Priority changes
- Order comments added/removed
**Specimen lifecycle**
- Collected, labeled, received, rejected
- Centrifuged, aliquoted, stored
- Disposed/expired
**Results**
- Result entered/updated
- Verified/amended
- Released/retracted/corrected
- Result comments/interpretation changes
- Auto-verification override
**QC**
- QC result recorded
- QC failure/override
### logmaster
**Value sets**
- Create/update/retire value set items
**Test definitions**
- Test definition updates (units, methods, ranges)
- Reference range changes
- Formula/delta check changes
- Test panel membership add/remove
**Infrastructure**
- Analyzer/instrument config changes
- Host app integration config
- Coding system changes
**Users/roles**
- User create/disable/reset
- Role changes
- Permission changes
**Sites/workstations**
- Site/location/workstation CRUD
### logsystem
**Sessions & security**
- Login/logout
- Failed login attempts
- Lockouts/password resets
- Token issue/refresh/revoke
- Authorization failures
**Import/export**
- Import/export job start/end
- Batch ID, source, record counts, status
**System operations**
- Background jobs start/end
- Integration sync runs
- System config changes
- Service errors that affect data integrity
## Activity & Event Codes
Use consistent `ActivityID` and `EventID` values. Recommended defaults:
- `ActivityID`: `CREATE`, `UPDATE`, `DELETE`, `READ`, `MERGE`, `SPLIT`, `CANCEL`, `REOPEN`, `VERIFY`, `AMEND`, `RETRACT`, `RELEASE`, `IMPORT`, `EXPORT`, `LOGIN`, `LOGOUT`
- `EventID`: domain-specific codes (e.g., `PATIENT_REGISTERED`, `ORDER_CREATED`, `RESULT_VERIFIED`, `QC_RECORDED`)
## Capture Guidelines
- Always capture `UserID`, `SessionID`, `SiteID`, and `LogDate` when available.
- If the action is system-driven, set `UserID` to `SYSTEM` (or null) and add context in `Context`.
- Store payload diffs in `FldValuePrev` and `FldValueNew` for single-field changes; for multi-field changes, put a JSON diff in `Context` and leave `FldName` null.
- For bulk operations, store batch metadata in `Context` (`batch_id`, `record_count`, `source`).
- Do not log secrets, tokens, or full PHI when not required. Mask or omit sensitive fields.
## Retention & Governance
- Define retention policy per table (e.g., 7 years for patient/order, 2 years for system).
- Archive before purge; record purge activity in `logsystem`.
- Restrict write/delete permissions to service accounts only.
## Implementation Checklist
1. Create the four tables with shared schema (or migrate existing log tables to match).
2. Add a single audit service with helpers to build a normalized payload.
3. Instrument controllers/services for each event category above.
4. Add automated tests for representative audit writes.
5. Document `EventID` codes used by each endpoint/service.

20
src/projects/clqms01/index.njk
View File

@ -92,7 +92,7 @@ order: 0
<span class="text-primary opacity-50">#</span>
Quick Access
</h2>
<div class="grid grid-cols-1 sm:grid-cols-3 gap-4">
<div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4">
<a href="#docs" class="card bg-base-200 hover:bg-base-300 transition-all hover:-translate-y-1 border border-white/5 p-6">
<div class="flex items-center gap-3 mb-2">
<span class="p-2 rounded bg-primary/10 text-primary text-xl">🏗️</span>
@ -100,6 +100,13 @@ order: 0
</div>
<p class="text-sm text-base-content/70">Architecture, auth, and technical docs</p>
</a>
<a href="/projects/clqms01/009-audit-logging/" class="card bg-base-200 border border-secondary/20 hover:bg-secondary/5 transition-all hover:-translate-y-1 p-6">
<div class="flex items-center gap-3 mb-2">
<span class="p-2 rounded bg-secondary/10 text-secondary text-xl">🧾</span>
<h3 class="font-bold text-base">Audit Logging</h3>
</div>
<p class="text-sm text-base-content/70">Event catalog, schema, and capture rules</p>
</a>
<a href="/projects/clqms01/suggestion/" class="card bg-base-200 border border-success/20 hover:bg-success/5 transition-all hover:-translate-y-1 p-6">
<div class="flex items-center gap-3 mb-2">
<span class="p-2 rounded bg-success/10 text-success text-xl">💡</span>
@ -124,6 +131,17 @@ order: 0
Core Documentation
</h2>
<div class="space-y-2">
<a href="/projects/clqms01/007-test-calc-engine/" title="src/projects/clqms01/007-test-calc-engine.md" class="group block p-4 rounded-xl bg-base-200/50 hover:bg-base-200 border border-base-content/10 transition-all">
<div class="flex flex-col md:flex-row md:items-center justify-between gap-2">
<div>
<h3 class="text-lg font-bold group-hover:text-secondary transition-colors mb-1">Calculator Service Operators Reference</h3>
<p class="text-base-content/60 text-sm max-w-2xl leading-relaxed">
Operators, functions, constants, and API usage for the calc engine.
</p>
</div>
<span class="hidden md:inline text-xs font-mono text-base-content/40 whitespace-nowrap">Reference</span>
</div>
</a>
{% for post in collections.clqms %}
{% set is_suggestion = "/suggestion/" in post.url %}
{% set is_review = "/review/" in post.url %}