1. Назначение документа

Документ описывает пользовательские требования (URS) и функциональную спецификацию (FS) для утилиты TcmAristolochicAcidsAndPAsQualityChecker. Утилита предназначена для детерминированной проверки данных input.csv, формирования структурированного результата output.json и поддержки прослеживаемого QA/QC review.

Документ является проектной URS/FS-основой для CSV/CSA, IQ/OQ/PQ и дальнейшей валидации в контексте конкретной лабораторной процедуры.

2. Исходное описание утилиты

3. URS — пользовательские требования

3.1 Цель и область применения

Система должна принимать табличные результаты лабораторного контроля, выполнять проверку по заранее заданным критериям и возвращать понятный статус по каждой серии/записи: Pass, Review или Fail.

3.2 Нормативная / методическая база

В исходном описании и правилах утилиты используются следующие ориентиры: ChP, EP, ICH, EMA, FDA. Финальные лимиты должны быть подтверждены утверждённой спецификацией, монографией, SOP или протоколом трансфера метода.

3.3 Ключевые QC-проверки

• Zero Tolerance: АК запрещены в ЕС, США и Китае. Любое обнаружение выше LOD = отказ.
• AA-I и AA-II: Наиболее токсичные варианты; приоритетные маркеры.
• Species Confirmation: ⛔ Подтверждение вида Aristolochia = автоматический запрет независимо от уровня АК.
• LOD Requirement: Метод должен обеспечивать LOD ≤10 ppb для достоверного подтверждения отсутствия.
• EMA Limit: 0.007 мкг/кг массы тела в сутки (для взрослых при пожизненном приеме).
• Batch-Level Conversion: Лимит в продукте рассчитывается из суточной дозы и массы тела пациента.
• Marker Panel: Сенкиркин, ретрозин, монкроталин, сенкиркин, эхимидин.
• PA-Producing Species: Детекция видов Senecio, Crotalaria, Heliotropium, Symphytum.

3.4 Пользователи

• QC analyst — подготовка и загрузка input.csv.
• QA/QC reviewer — проверка результата и отклонений.
• CSV/validation specialist — подтверждение пригодности утилиты.
• System owner — управление версией, доступом и изменениями.

3.5 Требования к данным и Data Integrity

• каждая строка CSV должна быть прослеживаемой к серии, образцу или измерению;
• исходные значения не должны изменяться утилитой;
• расчёты должны быть воспроизводимыми при повторном запуске;
• любое отклонение должно сохраняться как структурированное finding с указанием поля и правила;
• ручное изменение итогового статуса вне QA-процесса не допускается.

4. FS — функциональная спецификация

4.1 Поток обработки

1. Проверить наличие и кодировку input.csv.
2. Проверить заголовки, обязательные поля и типы данных.
3. Нормализовать числовые и булевы значения без изменения исходного следа.
4. Выбрать набор правил по категории продукта/типа, если он предусмотрен.
5. Сравнить значения с лимитами и вычислить derived metrics.
6. Сформировать запись результата по каждой строке.
7. Сохранить output.json с общей сводкой, findings и traceability.

4.2 CSV-схема

4.3 Пример входных данных

4.4 Выходной JSON

{
  "utility": "TcmAristolochicAcidsAndPAsQualityChecker",
  "runId": "urn:fuzkk:run:example",
  "sourceFile": "input.csv",
  "recordsProcessed": 3,
  "overallStatus": "Pass / Review / Fail",
  "records": [
    {
      "recordId": "TCM-AA-2026-001",
      "status": "Pass / Review / Fail",
      "criticalFindings": [],
      "warnings": [],
      "evaluatedRules": [
        "Configured acceptance criteria from the utility rule set"
      ],
      "inputTrace": {
        "SampleID": "TCM-AA-2026-001",
        "HerbName": "Fang_Ji",
        "LatinName": "Stephania_tetrandra",
        "PartUsed": "Root",
        "AnalyticalMethod": "LC_MS_MS",
        "LOD_AA_ppb": "2.0",
        "LOD_PA_ppb": "3.0",
        "AA_I_ppb": "0"
      }
    }
  ],
  "dataIntegrity": {
    "deterministicEvaluation": true,
    "sourceRowTraceability": true,
    "manualOverrideAllowed": false
  }
}

5. Трассировка URS → FS → тесты

6. CSV/CSA и валидационный подход