Bio-LIMS (v2.0)

A skill for calling Bio-LIMS backend APIs. All API calls are made through scripts/biolims.mjs, with automatic token management.

Module Features:

• - Order Management
• Sample Receive
• Sample Type Query
• Experiment Template Management

Quick Start

CODEBLOCK0

Common Usage Scenarios

Scenario 1: User asks about order information

User: "Help me check order ORDER202401180001"

AI Actions:

1. 1. Call: INLINECODE1
2. Parse the returned JSON, extract key information
3. Reply to user in a clear list format

Reply Example (strictly follow field mapping):
CODEBLOCK1

Important Reminders:

• - Use English field display names (e.g., "Patient Name", not Chinese equivalents)
• Patient name is a single field name, do not split it for display
• Display by field groups (Patient Information, Product Information, etc.)
• Only show fields that have values
• This system does not use firstName/lastName, only the name field

Scenario 2: Query order list

User: "What are the recent orders?"

AI Actions:

1. 1. Call: INLINECODE4
2. Parse the returned list
3. Display recent orders

Reply Example (list mode, simplified display):
CODEBLOCK2

Important: List mode only shows key fields, uses English display names, patient name uses single name field

Scenario 3: View order samples

User: "What samples does order ORDER202401180001 have?"

AI Actions:

1. 1. Call: INLINECODE6
2. Display sample list

Reply Example:
CODEBLOCK3

Scenario 4: Query sample types

User: "What sample types are available?" or "I need the type ID for blood samples"

AI Actions:

1. 1. If user provided a specific name (e.g., "Blood"), call: INLINECODE7
2. If user did not provide a name, call: INLINECODE8
3. Display sample type list including ID, name, and code

Reply Example:
CODEBLOCK4

Scenario 5: Create order

User: "Help me create an order, patient name is John Smith, test item is LymphDetect, need one blood sample"

AI Actions:

1. 1. Collect required info: name (patient name), productId, productName
2. If user mentions sample type, use search-sample-type to query sample type ID
3. Build complete JSON (must use correct field names)
4. Use file method to pass large JSON (avoid command line escaping issues)
5. Call create order command

Key Notes for Creating Orders:

1. 1. Use file method to pass JSON (strongly recommended):

1. 2. productId must be a system ID:

1. 3. Samples must also include productId and productName:

Critically Important - Field Names:
CODEBLOCK6

Complete JSON Example:
CODEBLOCK7

Common Product ID Mapping:

(Other product IDs can be obtained by querying existing orders)

Reply Example:
CODEBLOCK8

Response Handling

Key Rules:

1. 1. Must check status field: Only status === 200 indicates success
2. order-list response structure: INLINECODE14

1. 3. Single order response structure: INLINECODE17
2. Error response: INLINECODE18

Response Handling Steps:
CODEBLOCK9

Display Rules (Very Important):

1. 1. Use English field display names:

1. 2. Correct use of name field:

1. 3. Format Requirements:

1. 4. Enum Value Conversion:

1. 5. Time Format:

Order Status Description

• - 0 - Cancelled
• INLINECODE24 - Complete
• INLINECODE25 - New
• INLINECODE26 - To Be Modified
• INLINECODE27 - Submitted

Gender Codes

• - 0 - Female
• INLINECODE29 - Male
• INLINECODE30 - Unknown

Important Notes

1. 1. Token Management: The script automatically handles login and token refresh; no manual intervention needed
2. Error Handling: If the API returns an error, explain the specific issue to the user (e.g., "order does not exist", "insufficient permissions", etc.)
3. Data Format: Creating/updating orders requires a complete JSON structure; refer to INLINECODE31
4. Privacy Protection: Be careful to protect privacy when displaying patient information; do not over-expose sensitive data

Field Mapping Reference

Fixed Field Mapping

The JSON data returned by orders uses API internal field names (e.g., name, productId), which need to be mapped to page display names (e.g., "Patient Name", "Test Item ID").

Main Field Mapping:

• - id -> Order ID
• INLINECODE35 -> Patient Name (single field, NOT firstName/lastName)
• INLINECODE36 -> Gender (0=Female, 1=Male, 2=Unknown)
• INLINECODE37 -> Age
• INLINECODE38 -> Date of Birth
• INLINECODE39 -> Ethnicity
• INLINECODE40 -> ID Card No.
• INLINECODE41 -> Phone Number
• INLINECODE42 -> Email
• INLINECODE43 -> EMR ID
• INLINECODE44 -> Bed No.
• INLINECODE45 -> Inpatient/Outpatient No.
• INLINECODE46 -> Test Item ID
• INLINECODE47 -> Test Item(s)
• INLINECODE48 -> Barcode
• INLINECODE49 -> Clinical Diagnosis
• INLINECODE50 -> Health Condition
• INLINECODE51 -> Disease
• INLINECODE52 -> Status
• INLINECODE53 -> Order Progress
• INLINECODE54 -> Created by
• INLINECODE55 -> Created at
• INLINECODE56 -> Approved by
• INLINECODE57 -> Completed at
• INLINECODE58 -> Sales
• INLINECODE59 -> Medical Institutions
• INLINECODE60 -> Clinical Department
• INLINECODE61 -> Attending Physician
• INLINECODE62 -> Physician Contact No.
• INLINECODE63 -> Province
• INLINECODE64 -> Contract Name
• INLINECODE65 -> Contract Price
• INLINECODE66 -> Remarks

For the complete mapping table, refer to references/field-mapping-quick-reference.md.

Custom Field Handling

Order data contains two types of custom fields:

1. 1. Order main table custom fields (customFieldValue)

1. 2. Sample sub-table custom fields (customFieldValue)

Processing Steps:

1. 1. Call field mapping API to get {"Display Name": "apiFieldName"} mapping
2. INLINECODE75 to parse the customFieldValue string in the order
3. Use the mapping to convert API field names to display names
4. Display to user

Example:

// 1. Get field mapping
const mapping = await getCustomFields('104-mainTable');
// Returns: {"Patient Note": "patientNote", "Urgency Level": "urgencyLevel"}

// 2. Parse custom fields
const customValues = JSON.parse(order.customFieldValue);
// customValues = {"patientNote": "Urgent case", "urgencyLevel": "High"}

// 3. Convert to display names
// "Patient Note": "Urgent case"
// "Urgency Level": "High"

Sample Receive Usage Scenarios

Scenario 6: Query receive order list

User: "What are the recent sample receive orders?"

AI Actions:

1. 1. Call: INLINECODE77
2. Parse the returned list
3. Display recent receive orders

Reply Example (list mode, simplified display):
CODEBLOCK11

Scenario 7: Query receive order details

User: "Help me check receive order SR202401180001"

AI Actions:

1. 1. Call: INLINECODE78
2. Parse the returned JSON, extract key information
3. Reply in a clear list format

Reply Example (strictly follow field mapping, do not merge fields):
CODEBLOCK12

Important Reminders:

• - Use English field display names (e.g., "Registration ID", not Chinese equivalents)
• Do not merge fields (display each field separately)
• Display by field groups (Sample Receive Information, Express Information, etc.)
• Only show fields that have values

Scenario 8: Query receive order sample details

User: "What samples does receive order SR202401180001 have?"

AI Actions:

1. 1. Call: INLINECODE79
2. Display sample list

Reply Example:
CODEBLOCK13

Scenario 9: Scan barcode to receive sample

User: "Scan barcode BC20240118001"

Important: The scan-barcode command's receive_id is a required parameter; you must create a receive order first!

AI Actions:

1. 1. First check if a receive order exists:

1. 2. Call: INLINECODE83
2. Parse the returned sample information
3. Display sample details

API Input Format:
CODEBLOCK14

Reply Example:
CODEBLOCK15

If barcode has already been received:
CODEBLOCK16

If no receive order ID provided:
CODEBLOCK17

Scenario 10: Scan order number for batch receiving

User: "Scan order ORD202401180001"

AI Actions:

1. 1. Call: INLINECODE84
2. Parse the returned sample list
3. Display receivable samples

Reply Example:
CODEBLOCK18

Scenario 11: Create sample receive order

User: "Create a sample receive order, receive time is today at 10am, express number SF1234567890, needs plating"

AI Actions:

1. 1. Collect required info: acceptDate (receive time), isBoard (whether to plate)
2. Build complete JSON (must use correct field names)
3. Call create receive order command

Critically Important - Field Names:
CODEBLOCK19

Complete JSON Example:
CODEBLOCK20

Reply Example:

Receive order created successfully!

Registration ID: SR202401180001
Description: Clinical Sample Receive
Received At: 2024-01-18 10:00:00
Express Bill No.: SF1234567890
Courier: SF Express
In Plate: Yes
Status: New

Sample Details:
- Sample ID: S001, Barcode: BC001, Whole Blood, 5ml

Receive order has been saved to the system.

Scenario 12: Query receive order with custom fields

User: "Query complete information for receive order SR202401180001, including custom fields"

AI Actions:

1. 1. Call get-custom-fields 121-mainTable to get main table custom field mapping
2. Call get-custom-fields 121-receiveTable to get sub-table custom field mapping
3. Call receive SR202401180001 to query receive order data
4. Parse fixed fields (using field mapping table from TOOLS.md)
5. Parse enum values (Gender, Status, isGood, method, isBoard)
6. Parse customFieldValue JSON fields (main table and sub-table)
7. Format display (all fields use English display names)

Complete Workflow Example:

CODEBLOCK22

Parsing Logic (pseudocode):
CODEBLOCK23

Reply Example:
CODEBLOCK24

Important Tips:

• - Custom field mappings may change dynamically; it is recommended to re-fetch them with each query
• INLINECODE89 is a JSON string that must be parsed with JSON.parse() first
• All fields must use English display names
• Only display fields with values; do not show empty fields

Scenario 13: Query next step flow list

User: "Query next step flow for product PROD001" or "Where does this sample go next?"

AI Actions:

Key: This API requires a product ID; it will error without one

Step 1: Confirm product ID

• - If user already provided product ID -> use it directly
• If user did not provide product ID -> must ask or query first

Step 2: Call API
CODEBLOCK25

Step 3: Parse response
CODEBLOCK26

Reply Example 1 (with product ID):
CODEBLOCK27

Reply Example 2 (no product ID - must ask first):
CODEBLOCK28

Common Errors (must avoid):
CODEBLOCK29

Business Logic:

• - Single product ID: Returns all available next step flows for that product
• Multiple product IDs: Returns flows supported by all products (intersection)

Rules AI Must Follow:

1. 1. Never call get-next-flows without a product ID
2. If user did not provide a product ID, must ask first: "Please provide the test item product ID"
3. Or proactively offer help: "I can first help you query the available test item list, would you like that?"
4. Only call the API after obtaining the product ID

Scenario 14: Required field validation before completing receive order

User: "Complete receive order SR202401180001"

AI Actions:

Key: Must validate all required fields before completing

Step 1: Query current receive order data
CODEBLOCK30

Step 2: Validate required fields

Main table required fields (2):

• - acceptDate (Received At) - Receive time
• INLINECODE93 (In Plate) - Whether to plate

Sample detail required fields (9 per sample):

• - orderCode (Order ID)
• INLINECODE95 (Barcode)
• INLINECODE96 (Test Item(s))
• INLINECODE97 (Sample Type ID)
• INLINECODE98 (Sampling Volume)
• INLINECODE99 (Unit)
• INLINECODE100 (Normal)
• INLINECODE101 (Result)
• INLINECODE102 (Next Step)

Step 3: Decide whether to complete based on validation results

Case A - All fields present:
CODEBLOCK31

Reply:
CODEBLOCK32

Case B - Missing fields (must list specific missing fields):

Reply:
CODEBLOCK33

Things AI Must Never Do:

1. 1. Call complete-receive directly without validation
2. Assume fields are filled and skip validation
3. Only say "fields are missing" without listing specific fields

Scenario 15: Duplicate barcode error handling

User: "Create receive order with samples BC001 and BC001"

AI Actions:

1. 1. Build JSON
2. Call INLINECODE104
3. Receive error response: INLINECODE105

AI should reply like this:
CODEBLOCK34

Common barcode error scenarios:

Scenario A - Duplicate within same receive order:

{
  "sampleReceiveItems": [
    {"barCode": "BC001", ...},
    {"barCode": "BC001", ...}  // Duplicate
  ]
}

Scenario B - Already received by another receive order:

• - Barcode BC001 is already in another receive order
• Scanning will indicate the sample has been received

AI Handling:

• - Parse error message
• Identify the specific duplicate barcode
• Provide clear resolution suggestions

Scenario 16: Unified handling of API error responses

After all API calls, AI must check the status field:

CODEBLOCK36

Error response examples and AI replies:

Principles AI Must Follow:

1. 1. Always check the status field - Do not assume the call succeeded
2. Display errors in a friendly manner - Do not return raw error messages directly
3. Provide resolution suggestions - Tell the user how to fix the error
4. List specific details - Which field is missing? Which barcode is duplicated?

Sample Receive Status Description

Receive Order Status

• - 3 - New - Editable, saveable, completable
• INLINECODE111 - Complete - Read-only, not editable

Sample Qualification Status

• - 1 - Qualified
• INLINECODE113 - Unqualified

In Plate

• - 1 - Yes
• INLINECODE115 - No

Experiment Template Usage Scenarios

Scenario 17: Query experiment template list

User: "View experiment templates" / "Check latest experiment templates" / "What experiment templates are there"

AI Actions:

1. 1. Call: INLINECODE116
2. Parse the returned data.result array, display key fields

Reply Example:
CODEBLOCK37

Status Value Conversion:

• - 3 -> New (editable)
• INLINECODE119 -> In Workflow
• INLINECODE120 -> To Be Modified
• INLINECODE121 -> Complete
• INLINECODE122 -> Cancelled (excluded from queries automatically)

Scenario 18: Query experiment template details

User: "View details of template ET2024000001" / "What steps does ET2024000001 have"

AI Actions:

1. 1. Call: INLINECODE123
2. Parse three-layer nested structure, display by step -> component hierarchy

Reply Example:

Template Details: ET2024000001

=== Basic Information ===
Template Name: PCR Testing Experiment Template
Experiment Type: PCR Amplification
Status: Complete
Created by: admin
Created at: 2024-01-15 10:30:00
Version: 1.0

=== Step Structure (2 steps total) ===

Step 1: Sample Preparation
  - [detailTable] Sample Detail Table
  - [input] Extraction Concentration (number)
  - [input] Extraction Date (date)
  - [attachment] Extraction Record

Step 2: PCR Amplification
  - [detailTable] Sample Detail Table
  - [equipment] Instruments & Equipment
  - [material] Reagents & Consumables
  - [resultTable] Test Result Table

Scenario 19: Create experiment template

User: "Help me create an XXX testing template"

AI Actions:

1. 1. First query experiment types: INLINECODE124
2. First query experiment groups: INLINECODE125
3. Collect required info: templateName, experimentType, experimentGroup, auditor
4. Build JSON and write to temp file (avoid escaping issues)
5. Call: INLINECODE126

Create JSON Structure (templateName required, stepDetails required):

{
  "templateName": "Template Name",
  "experimentType": "Experiment Type ID",
  "experimentTypeName": "Experiment Type Name",
  "experimentGroup": "Experiment Group ID",
  "experimentGroupName": "Experiment Group Name",
  "auditor": "Approver ID",
  "auditorName": "Approver Name",
  "stepDetails": [
    {
      "name": "Step Name",
      "keyId": 0,
      "jsonDatas": [
        {
          "label": "Field Name",
          "type": "input",
          "size": "8",
          "inputType": "text",
          "exclusiveShow": "0"
        }
      ]
    }
  ]
}

Scenario 20: Copy experiment template

User: "Copy template ET2024000001" / "Create a new one based on template ET001"

AI Actions:

1. 1. Call: INLINECODE127
2. Display new template ID (auto-generated by system, status is New and editable)

Scenario 21: Cancel experiment template

User: "Cancel template ET2024000001"

AI Actions:

1. 1. Must confirm first: "Are you sure you want to cancel template ET2024000001? This action cannot be undone."
2. After user confirms: INLINECODE128

Detailed API Information

Order Module

• - Complete API documentation: INLINECODE129
• Field mapping quick reference: references/field-mapping-quick-reference.md <- Must read when querying orders!

Sample Receive Module

• - Complete API documentation: INLINECODE131
• Field mapping quick reference: references/field-mapping-sample-receive-quick-reference.md <- Must read when querying receive orders!

Experiment Template Module

• - Complete API documentation: references/api-experiment-template.md <- Must read for experiment template operations!