TcmDecoctionPieceDimensionalQualityChecker
Tcm Decoction Piece Dimensional
TCM Traditional Chinese Medicine Herbal Botanical BHP Chinese Pharmacopoeia CSV→JSON URS & FS
Open selectionTCM Decoction Piece Dimensional Quality Checker — Control of Yinpian Dimensional Characteristics in TCM
ℹ️ Utility checks physical cutting parameters of herbal raw materials according to ChP 2020 (Chapter 0213) and traditional Paozhi standards:
• Average slice/segment thickness (depends on cut type)
• Size variability coefficient (CV ≤ 15-20%)
• Fine fraction/dust content (Fines ≤ 2-5%)
• Oversized fraction content (Oversized ≤ 5%)
• Batch uniformity index (Uniformity Index ≥ 0.85)
⚠️ CRITICAL: Yinpian geometry is a PHARMACOKINETIC PARAMETER!
Particle size determines water contact area and diffusion rate of active substances.
Non-standard cutting makes reproduction of decoction therapeutic effect impossible, even if raw material chemical composition is ideal.
Usage:
TcmDecoctionPieceDimensionalQualityChecker.exe → demo mode (console output)
TcmDecoctionPieceDimensionalQualityChecker.exe input.csv output.json → evaluate your data
Input format:
BatchNumber,HerbName,CutType,AvgThickness_mm,ThicknessStdDev_mm,FinesPercent,OversizedPercent,UniformityIndex,MoisturePercent
Example:
TCM-ANGELICA-2026-DIM-001,Angelica_sinensis,Slice,2.8,0.4,3.5,2.0,0.92,11.0
Supported cutting types (Paozhi):
• Slice (Pian 片) — Thin transverse/longitudinal slices (1-4 mm). For roots, rhizomes.
• Segment (Duan 段) — Segments/sections (10-15 mm). For stems, herbs, long roots.
• Block (Kuai 块) — Cubes/blocks (8-12 mm). For dense tubers, fruits.
• Filament (Si 丝) — Thin shreds/filaments (2-3 mm). For leaves, bark, peels.
— WHY IS THIS NEEDED?
In Western herbal medicine, raw materials are often used as powder or standardized extract. In TCM, patient or practitioner PREPARES decoction themselves from whole/cut pieces.
• Pieces too thick → water does not penetrate inside during boiling time → under-extraction.
• Pieces too thin/small → rapid starch/mucilage extraction → viscous, turbid decoction, destruction of thermolabile substances.
• High variability (different sizes in one pack) → unpredictable concentration of actives in each dose.
• Excess fines → mass loss, decoction contamination with suspension, adulteration risk.
⚠️ CRITICAL:
• Compliance with thickness range for each raw material type is mandatory
• CV ≤ 20% guarantees extraction uniformity of entire batch
• Fines ≤ 5% prevents losses and ensures decoction clarity
• Oversized ≤ 5% excludes presence of unextractable fragments
• Uniformity Index ≥ 0.85 confirms cutting equipment performance quality
Key features:
• Adaptive limits for 4 main TCM cutting types
• Calculation of coefficient of variation (CV) as cutting precision measure
• Control of both distribution boundaries (fines + oversized)
• Uniformity index assessment for detecting fraction mixing
• Link between physical parameters and final decoction quality
Critical parameters:
• Slice thickness: 1-4 mm
• Segment length: 10-15 mm
• Block size: 8-12 mm
• Filament width: 2-3 mm
• CV (variability): ≤ 15-20%
• Fines: ≤ 2-5%
• Oversized: ≤ 5%
• Uniformity Index: ≥ 0.85
💡 Usage tips:
1. Measurements performed by caliper, sieve analysis or optical systems (Image Analysis)
2. Measure at least 50 individual fragments from representative sample for CV calculation
3. Fines content determined by sieving through monograph-specified sieve (usually 2-3 mm)
4. Moisture affects brittleness: overdried raw material produces more fines during transport
5. If Uniformity Index is low, check cutting machine knives and feed mode
⚠️ Note: This quality parameter is UNIQUE to TCM and absent in Ph.Eur./BHP. Western pharmacopoeia standardizes particle size only for POWDERS. For Yinpian (decoction pieces), size is a TECHNOLOGICAL PARAMETER OF PATIENT DRUG PREPARATION. Without size control, it is impossible to guarantee that patient receives the same dose studied in clinical trials of traditional formulas.
ℹ️ Utility checks physical cutting parameters of herbal raw materials according to ChP 2020 (Chapter 0213) and traditional Paozhi standards:
• Average slice/segment thickness (depends on cut type)
• Size variability coefficient (CV ≤ 15-20%)
• Fine fraction/dust content (Fines ≤ 2-5%)
• Oversized fraction content (Oversized ≤ 5%)
• Batch uniformity index (Uniformity Index ≥ 0.85)
⚠️ CRITICAL: Yinpian geometry is a PHARMACOKINETIC PARAMETER!
Particle size determines water contact area and diffusion rate of active substances.
Non-standard cutting makes reproduction of decoction therapeutic effect impossible, even if raw material chemical composition is ideal.
Usage:
TcmDecoctionPieceDimensionalQualityChecker.exe → demo mode (console output)
TcmDecoctionPieceDimensionalQualityChecker.exe input.csv output.json → evaluate your data
Input format:
BatchNumber,HerbName,CutType,AvgThickness_mm,ThicknessStdDev_mm,FinesPercent,OversizedPercent,UniformityIndex,MoisturePercent
Example:
TCM-ANGELICA-2026-DIM-001,Angelica_sinensis,Slice,2.8,0.4,3.5,2.0,0.92,11.0
Supported cutting types (Paozhi):
• Slice (Pian 片) — Thin transverse/longitudinal slices (1-4 mm). For roots, rhizomes.
• Segment (Duan 段) — Segments/sections (10-15 mm). For stems, herbs, long roots.
• Block (Kuai 块) — Cubes/blocks (8-12 mm). For dense tubers, fruits.
• Filament (Si 丝) — Thin shreds/filaments (2-3 mm). For leaves, bark, peels.
— WHY IS THIS NEEDED?
In Western herbal medicine, raw materials are often used as powder or standardized extract. In TCM, patient or practitioner PREPARES decoction themselves from whole/cut pieces.
• Pieces too thick → water does not penetrate inside during boiling time → under-extraction.
• Pieces too thin/small → rapid starch/mucilage extraction → viscous, turbid decoction, destruction of thermolabile substances.
• High variability (different sizes in one pack) → unpredictable concentration of actives in each dose.
• Excess fines → mass loss, decoction contamination with suspension, adulteration risk.
⚠️ CRITICAL:
• Compliance with thickness range for each raw material type is mandatory
• CV ≤ 20% guarantees extraction uniformity of entire batch
• Fines ≤ 5% prevents losses and ensures decoction clarity
• Oversized ≤ 5% excludes presence of unextractable fragments
• Uniformity Index ≥ 0.85 confirms cutting equipment performance quality
Key features:
• Adaptive limits for 4 main TCM cutting types
• Calculation of coefficient of variation (CV) as cutting precision measure
• Control of both distribution boundaries (fines + oversized)
• Uniformity index assessment for detecting fraction mixing
• Link between physical parameters and final decoction quality
Critical parameters:
• Slice thickness: 1-4 mm
• Segment length: 10-15 mm
• Block size: 8-12 mm
• Filament width: 2-3 mm
• CV (variability): ≤ 15-20%
• Fines: ≤ 2-5%
• Oversized: ≤ 5%
• Uniformity Index: ≥ 0.85
💡 Usage tips:
1. Measurements performed by caliper, sieve analysis or optical systems (Image Analysis)
2. Measure at least 50 individual fragments from representative sample for CV calculation
3. Fines content determined by sieving through monograph-specified sieve (usually 2-3 mm)
4. Moisture affects brittleness: overdried raw material produces more fines during transport
5. If Uniformity Index is low, check cutting machine knives and feed mode
⚠️ Note: This quality parameter is UNIQUE to TCM and absent in Ph.Eur./BHP. Western pharmacopoeia standardizes particle size only for POWDERS. For Yinpian (decoction pieces), size is a TECHNOLOGICAL PARAMETER OF PATIENT DRUG PREPARATION. Without size control, it is impossible to guarantee that patient receives the same dose studied in clinical trials of traditional formulas.
input.csv
BatchNumber,HerbName,CutType,AvgThickness_mm,ThicknessStdDev_mm,FinesPercent,OversizedPercent,UniformityIndex,MoisturePercent TCM-ANGELICA-2026-DIM-001,Angelica_sinensis,Slice,2.8,0.4,3.5,2.0,0.92,11.0 TCM-ASTRAGALUS-2026-DIM-002,Astragalus_membranaceus,Slice,3.2,0.5,4.0,3.5,0.88,10.5 TCM-LICORICE-FAIL-2026-003,Glycyrrhiza_uralensis,Segment,18.0,4.5,8.0,12.0,0.72,12.0 TCM-BUPLEURUM-2026-DIM-004,Bupleurum_chinense,Filament,2.5,0.3,2.0,1.5,0.95,9.5
TcmDecoctionPieceDimensionalQualityChecker — URS & FS
TCM Decoction Piece Dimensional Quality Checker
TCM Decoction Piece Dimensional Quality Checker
1. Назначение документа
Документ описывает пользовательские требования (URS) и функциональную спецификацию (FS) для утилиты TcmDecoctionPieceDimensionalQualityChecker. Утилита предназначена для детерминированной проверки данных input.csv, формирования структурированного результата output.json и поддержки прослеживаемого QA/QC review.
Документ является проектной URS/FS-основой для CSV/CSA, IQ/OQ/PQ и дальнейшей валидации в контексте конкретной лабораторной процедуры.
2. Исходное описание утилиты
TCM Decoction Piece Dimensional Quality Checker — Контроль размерных характеристик饮片 (Yinpian) в ТКМ
ℹ️ Утилита проверяет физические параметры нарезки лекарственного сырья согласно ChP 2020 (Глава 0213) и традиционным стандартам Paozhi:
• Средняя толщина/длина среза (согласно типу нарезки)
• Коэффициент вариации размеров (CV ≤ 15-20%)
• Содержание мелкой фракции/крошки (Fines ≤ 2-5%)
• Содержание крупной фракции/переростка (Oversized ≤ 5%)
• Индекс однородности партии (Uniformity Index ≥ 0.85)
⚠️ КРИТИЧНО: Геометрия饮片 — это ФАРМАКОКИНЕТИЧЕСКИЙ ПАРАМЕТР!
Размер частиц определяет площадь контакта с водой и скорость диффузии активных веществ.
Нестандартная нарезка делает невозможным воспроизведение терапевтического эффекта отвара, даже если химсостав сырья идеален.
Использование:
TcmDecoctionPieceDimensionalQualityChecker.exe → демо-режим (вывод в консоль)
TcmDecoctionPieceDimensionalQualityChecker.exe input.csv output.json → оценка ваших данных
Формат input.csv:
BatchNumber,HerbName,CutType,AvgThickness_mm,ThicknessStdDev_mm,FinesPercent,OversizedPercent,UniformityIndex,MoisturePercent
Пример:
TCM-ANGELICA-2026-DIM-001,Angelica_sinensis,Slice,2.8,0.4,3.5,2.0,0.92,11.0
Поддерживаемые типы нарезки (Paozhi):
• Slice (Pian 片) — Тонкие поперечные/продольные срезы (1-4 мм). Для корней, корневищ.
• Segment (Duan 段) — Отрезки/сегменты (10-15 мм). Для стеблей, трав, длинных корней.
• Block (Kuai 块) — Кубики/блоки (8-12 мм). Для плотных клубней, плодов.
• Filament (Si 丝) — Тонкая соломка/нити (2-3 мм). Для листьев, коры, кожур.
— ЗАЧЕМ ЭТО НУЖНО?
В западной фитотерапии сырье часто используется в виде порошка или стандартизированного экстракта. В ТКМ пациент или врач САМИ готовят отвар из цельных/резаных кусочков.
• Если кусочки слишком толстые → вода не проникает внутрь за время варки → недоэкстракция.
• Если кусочки слишком тонкие/мелкие → быстрая экстракция крахмала/слизи → вязкий, мутный отвар, разрушение термолабильных веществ.
• Высокая вариабельность (разные размеры в одной пачке) → непредсказуемая концентрация действующих веществ в каждой дозе.
• Избыток крошки (Fines) → потеря массы, загрязнение отвара взвесью, риск подмены.
⚠️ КРИТИЧЕСКИ ВАЖНО:
• Соблюдение диапазона толщины для каждого вида сырья обязательно
• CV ≤ 20% гарантирует однородность экстракции всей партии
• Fines ≤ 5% предотвращает потери и обеспечивает чистоту отвара
• Oversized ≤ 5% исключает наличие недовариваемых фрагментов
• Uniformity Index ≥ 0.85 подтверждает качество работы режущего оборудования
Ключевые особенности утилиты:
• Адаптивные лимиты для 4 основных типов нарезки ТКМ
• Расчёт коэффициента вариации (CV) как меры точности нарезки
• Контроль обеих границ распределения (мелочь + переросток)
• Оценка индекса однородности для выявления смешения фракций
• Связь физических параметров с качеством конечного отвара
Критические параметры:
• Толщина Slice: 1-4 мм
• Длина Segment: 10-15 мм
• Размер Block: 8-12 мм
• Ширина Filament: 2-3 мм
• CV (вариабельность): ≤ 15-20%
• Fines (крошка): ≤ 2-5%
• Oversized (переросток): ≤ 5%
• Uniformity Index: ≥ 0.85
💡 Советы по использованию:
1. Измерения проводятся штангенциркулем, ситовым анализом или оптическими системами (Image Analysis)
2. Для расчёта CV измерьте минимум 50 отдельных фрагментов из представительной пробы
3. Содержание крошки определяется просеиванием через сито, указанное в монографии (обычно 2-3 мм)
4. Влажность влияет на хрупкость: пересушенное сырьё даёт больше крошки при транспортировке
5. При низком Uniformity Index проверьте ножи режущей машины и режим подачи сырья
⚠️ Особенность: Этот параметр качества УНИКАЛЕН для ТКМ и отсутствует в Ph.Eur./BHP. Западная фармакопея нормирует размер частиц только для ПОРОШКОВ. Для饮片 (декоктных кусочков) размер является ТЕХНОЛОГИЧЕСКИМ ПАРАМЕТРОМ ПРИГОТОВЛЕНИЯ ЛЕКАРСТВА ПАЦИЕНТОМ. Без контроля размеров невозможно гарантировать, что пациент получит ту же дозу, которая была изучена в клинических испытаниях традиционных рецептов.
3. URS — пользовательские требования
3.1 Цель и область применения
Система должна принимать табличные результаты лабораторного контроля, выполнять проверку по заранее заданным критериям и возвращать понятный статус по каждой серии/записи: Pass, Review или Fail.
3.2 Нормативная / методическая база
В исходном описании и правилах утилиты используются следующие ориентиры: ChP 2020, ChP, USP, EP, Ph.Eur, Ph.Eur., BHP, WHO. Финальные лимиты должны быть подтверждены утверждённой спецификацией, монографией, SOP или протоколом трансфера метода.
3.3 Ключевые QC-проверки
- Средняя толщина/длина среза (согласно типу нарезки)
- Коэффициент вариации размеров (CV ≤ 15-20%)
- Содержание мелкой фракции/крошки (Fines ≤ 2-5%)
- Содержание крупной фракции/переростка (Oversized ≤ 5%)
- Индекс однородности партии (Uniformity Index ≥ 0.85)
- Slice (Pian 片) — Тонкие поперечные/продольные срезы (1-4 мм). Для корней, корневищ.
- Segment (Duan 段) — Отрезки/сегменты (10-15 мм). Для стеблей, трав, длинных корней.
- Block (Kuai 块) — Кубики/блоки (8-12 мм). Для плотных клубней, плодов.
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 Поток обработки
- Проверить наличие и кодировку
input.csv. - Проверить заголовки, обязательные поля и типы данных.
- Нормализовать числовые и булевы значения без изменения исходного следа.
- Выбрать набор правил по категории продукта/типа, если он предусмотрен.
- Сравнить значения с лимитами и вычислить derived metrics.
- Сформировать запись результата по каждой строке.
- Сохранить
output.jsonс общей сводкой, findings и traceability.
4.2 CSV-схема
| № | Поле CSV | Тип | Обяз. | Назначение |
|---|---|---|---|---|
| 1 | BatchNumber | string | Да | Идентификатор серии / лота для прослеживаемости. |
| 2 | HerbName | string | Да | Идентичность продукта, препарата или образца. |
| 3 | CutType | string | Да | Классификация для выбора адаптивных лимитов или набора правил. |
| 4 | AvgThickness_mm | decimal | Да | Входной атрибут для детерминированной оценки правил и прослеживаемости результата. |
| 5 | ThicknessStdDev_mm | decimal | Да | Входной атрибут для детерминированной оценки правил и прослеживаемости результата. |
| 6 | FinesPercent | decimal | Да | Измеренный аналитический результат для сравнения с критерием приемлемости. |
| 7 | OversizedPercent | decimal | Да | Измеренный аналитический результат для сравнения с критерием приемлемости. |
| 8 | UniformityIndex | decimal | Да | Классификация для выбора адаптивных лимитов или набора правил. |
| 9 | MoisturePercent | decimal | Да | Измеренный аналитический результат для сравнения с критерием приемлемости. |
4.3 Пример входных данных
| BatchNumber | HerbName | CutType | AvgThickness_mm | ThicknessStdDev_mm | FinesPercent | OversizedPercent | UniformityIndex | MoisturePercent |
|---|---|---|---|---|---|---|---|---|
| TCM-ANGELICA-2026-DIM-001 | Angelica_sinensis | Slice | 2.8 | 0.4 | 3.5 | 2.0 | 0.92 | 11.0 |
| TCM-ASTRAGALUS-2026-DIM-002 | Astragalus_membranaceus | Slice | 3.2 | 0.5 | 4.0 | 3.5 | 0.88 | 10.5 |
| TCM-LICORICE-FAIL-2026-003 | Glycyrrhiza_uralensis | Segment | 18.0 | 4.5 | 8.0 | 12.0 | 0.72 | 12.0 |
| TCM-BUPLEURUM-2026-DIM-004 | Bupleurum_chinense | Filament | 2.5 | 0.3 | 2.0 | 1.5 | 0.95 | 9.5 |
4.4 Выходной JSON
{
"utility": "TcmDecoctionPieceDimensionalQualityChecker",
"runId": "urn:fuzkk:run:example",
"sourceFile": "input.csv",
"recordsProcessed": 4,
"overallStatus": "Pass / Review / Fail",
"records": [
{
"recordId": "TCM-ANGELICA-2026-DIM-001",
"status": "Pass / Review / Fail",
"criticalFindings": [],
"warnings": [],
"evaluatedRules": [
"Configured acceptance criteria from the utility rule set"
],
"inputTrace": {
"BatchNumber": "TCM-ANGELICA-2026-DIM-001",
"HerbName": "Angelica_sinensis",
"CutType": "Slice",
"AvgThickness_mm": "2.8",
"ThicknessStdDev_mm": "0.4",
"FinesPercent": "3.5",
"OversizedPercent": "2.0",
"UniformityIndex": "0.92"
}
}
],
"dataIntegrity": {
"deterministicEvaluation": true,
"sourceRowTraceability": true,
"manualOverrideAllowed": false
}
}
5. Трассировка URS → FS → тесты
| URS | FS-механизм | Проверка |
|---|---|---|
| Загрузка корректного input.csv | CSV parser + schema validator | OQ: валидный/невалидный CSV |
| Детерминированная оценка лимитов | Rule engine с фиксированной конфигурацией | OQ: граничные значения и known expected results |
| Статусы Pass/Review/Fail | Status aggregator по findings | OQ/PQ: образцы с проходными и провальными сериями |
| Прослеживаемость к исходной строке | inputTrace + recordId | PQ: сверка output.json с исходным CSV |
| Поддержка QA review | структурированные findings и warnings | PQ: review сценарии и deviation handling |
6. CSV/CSA и валидационный подход
IQ
- проверка версии утилиты;
- проверка расположения исполняемого файла;
- проверка шаблона CSV;
- контроль прав доступа.
OQ
- проверка обязательных полей;
- проверка типов данных;
- проверка граничных значений;
- проверка zero-tolerance правил.
PQ
- прогоны на реальных/репрезентативных данных;
- сверка с ручным расчётом;
- подтверждение QA review workflow.
Change control
- версионирование лимитов;
- impact assessment при изменении правил;
- регрессия после обновления.
1. Document purpose
This document defines user requirements (URS) and functional specification (FS) for TcmDecoctionPieceDimensionalQualityChecker. The utility is intended to evaluate input.csv data deterministically, generate structured output.json output and support traceable QA/QC review.
This document is a project-level URS/FS baseline for CSV/CSA, IQ/OQ/PQ and further validation under an approved laboratory procedure.
2. Source utility description
TCM Decoction Piece Dimensional Quality Checker — Control of Yinpian Dimensional Characteristics in TCM
ℹ️ Utility checks physical cutting parameters of herbal raw materials according to ChP 2020 (Chapter 0213) and traditional Paozhi standards:
• Average slice/segment thickness (depends on cut type)
• Size variability coefficient (CV ≤ 15-20%)
• Fine fraction/dust content (Fines ≤ 2-5%)
• Oversized fraction content (Oversized ≤ 5%)
• Batch uniformity index (Uniformity Index ≥ 0.85)
⚠️ CRITICAL: Yinpian geometry is a PHARMACOKINETIC PARAMETER!
Particle size determines water contact area and diffusion rate of active substances.
Non-standard cutting makes reproduction of decoction therapeutic effect impossible, even if raw material chemical composition is ideal.
Usage:
TcmDecoctionPieceDimensionalQualityChecker.exe → demo mode (console output)
TcmDecoctionPieceDimensionalQualityChecker.exe input.csv output.json → evaluate your data
Input format:
BatchNumber,HerbName,CutType,AvgThickness_mm,ThicknessStdDev_mm,FinesPercent,OversizedPercent,UniformityIndex,MoisturePercent
Example:
TCM-ANGELICA-2026-DIM-001,Angelica_sinensis,Slice,2.8,0.4,3.5,2.0,0.92,11.0
Supported cutting types (Paozhi):
• Slice (Pian 片) — Thin transverse/longitudinal slices (1-4 mm). For roots, rhizomes.
• Segment (Duan 段) — Segments/sections (10-15 mm). For stems, herbs, long roots.
• Block (Kuai 块) — Cubes/blocks (8-12 mm). For dense tubers, fruits.
• Filament (Si 丝) — Thin shreds/filaments (2-3 mm). For leaves, bark, peels.
— WHY IS THIS NEEDED?
In Western herbal medicine, raw materials are often used as powder or standardized extract. In TCM, patient or practitioner PREPARES decoction themselves from whole/cut pieces.
• Pieces too thick → water does not penetrate inside during boiling time → under-extraction.
• Pieces too thin/small → rapid starch/mucilage extraction → viscous, turbid decoction, destruction of thermolabile substances.
• High variability (different sizes in one pack) → unpredictable concentration of actives in each dose.
• Excess fines → mass loss, decoction contamination with suspension, adulteration risk.
⚠️ CRITICAL:
• Compliance with thickness range for each raw material type is mandatory
• CV ≤ 20% guarantees extraction uniformity of entire batch
• Fines ≤ 5% prevents losses and ensures decoction clarity
• Oversized ≤ 5% excludes presence of unextractable fragments
• Uniformity Index ≥ 0.85 confirms cutting equipment performance quality
Key features:
• Adaptive limits for 4 main TCM cutting types
• Calculation of coefficient of variation (CV) as cutting precision measure
• Control of both distribution boundaries (fines + oversized)
• Uniformity index assessment for detecting fraction mixing
• Link between physical parameters and final decoction quality
Critical parameters:
• Slice thickness: 1-4 mm
• Segment length: 10-15 mm
• Block size: 8-12 mm
• Filament width: 2-3 mm
• CV (variability): ≤ 15-20%
• Fines: ≤ 2-5%
• Oversized: ≤ 5%
• Uniformity Index: ≥ 0.85
💡 Usage tips:
1. Measurements performed by caliper, sieve analysis or optical systems (Image Analysis)
2. Measure at least 50 individual fragments from representative sample for CV calculation
3. Fines content determined by sieving through monograph-specified sieve (usually 2-3 mm)
4. Moisture affects brittleness: overdried raw material produces more fines during transport
5. If Uniformity Index is low, check cutting machine knives and feed mode
⚠️ Note: This quality parameter is UNIQUE to TCM and absent in Ph.Eur./BHP. Western pharmacopoeia standardizes particle size only for POWDERS. For Yinpian (decoction pieces), size is a TECHNOLOGICAL PARAMETER OF PATIENT DRUG PREPARATION. Without size control, it is impossible to guarantee that patient receives the same dose studied in clinical trials of traditional formulas.
3. URS — user requirements
3.1 Intended use and scope
The system shall accept tabular laboratory QC results, evaluate them against configured acceptance criteria and return a clear status for each batch or record: Pass, Review or Fail.
3.2 Regulatory / methodological basis
The source description and utility rules refer to the following framework: ChP 2020, ChP, USP, EP, Ph.Eur, Ph.Eur., BHP, WHO. Final acceptance limits shall be confirmed by the approved specification, pharmacopoeial monograph, SOP or method-transfer protocol.
3.3 Key QC checks
- Average slice/segment thickness (depends on cut type)
- Size variability coefficient (CV ≤ 15-20%)
- Fine fraction/dust content (Fines ≤ 2-5%)
- Oversized fraction content (Oversized ≤ 5%)
- Batch uniformity index (Uniformity Index ≥ 0.85)
- Slice (Pian 片) — Thin transverse/longitudinal slices (1-4 mm). For roots, rhizomes.
- Segment (Duan 段) — Segments/sections (10-15 mm). For stems, herbs, long roots.
- Block (Kuai 块) — Cubes/blocks (8-12 mm). For dense tubers, fruits.
3.4 Users
- QC analyst — prepares and loads
input.csv. - QA/QC reviewer — reviews output, findings and deviations.
- CSV/validation specialist — confirms fitness for intended use.
- System owner — controls versioning, access and change management.
3.5 Data and data-integrity requirements
- each CSV row shall be traceable to a batch, sample or analytical measurement;
- source values shall not be modified by the utility;
- calculations shall be reproducible on repeated execution;
- each deviation shall be captured as a structured finding with field and rule references;
- manual override of the final status outside QA process is not allowed.
4. FS — functional specification
4.1 Processing flow
- Verify presence and encoding of
input.csv. - Validate headers, mandatory fields and data types.
- Normalize numeric and boolean values while preserving the source trace.
- Select an adaptive rule set by product/category type, where applicable.
- Compare values with limits and compute derived metrics.
- Create a result record for each input row.
- Write
output.jsonwith summary, findings and traceability.
4.2 CSV schema
| # | CSV field | Type | Req. | Purpose |
|---|---|---|---|---|
| 1 | BatchNumber | string | Yes | Batch / lot identifier used for traceability. |
| 2 | HerbName | string | Yes | Product, preparation or sample identity. |
| 3 | CutType | string | Yes | Classification used to select adaptive limits or rule set. |
| 4 | AvgThickness_mm | decimal | Yes | Input attribute required for deterministic rule evaluation and output traceability. |
| 5 | ThicknessStdDev_mm | decimal | Yes | Input attribute required for deterministic rule evaluation and output traceability. |
| 6 | FinesPercent | decimal | Yes | Measured analytical result compared with the configured acceptance criterion. |
| 7 | OversizedPercent | decimal | Yes | Measured analytical result compared with the configured acceptance criterion. |
| 8 | UniformityIndex | decimal | Yes | Classification used to select adaptive limits or rule set. |
| 9 | MoisturePercent | decimal | Yes | Measured analytical result compared with the configured acceptance criterion. |
4.3 Input data example
| BatchNumber | HerbName | CutType | AvgThickness_mm | ThicknessStdDev_mm | FinesPercent | OversizedPercent | UniformityIndex | MoisturePercent |
|---|---|---|---|---|---|---|---|---|
| TCM-ANGELICA-2026-DIM-001 | Angelica_sinensis | Slice | 2.8 | 0.4 | 3.5 | 2.0 | 0.92 | 11.0 |
| TCM-ASTRAGALUS-2026-DIM-002 | Astragalus_membranaceus | Slice | 3.2 | 0.5 | 4.0 | 3.5 | 0.88 | 10.5 |
| TCM-LICORICE-FAIL-2026-003 | Glycyrrhiza_uralensis | Segment | 18.0 | 4.5 | 8.0 | 12.0 | 0.72 | 12.0 |
| TCM-BUPLEURUM-2026-DIM-004 | Bupleurum_chinense | Filament | 2.5 | 0.3 | 2.0 | 1.5 | 0.95 | 9.5 |
4.4 Output JSON
{
"utility": "TcmDecoctionPieceDimensionalQualityChecker",
"runId": "urn:fuzkk:run:example",
"sourceFile": "input.csv",
"recordsProcessed": 4,
"overallStatus": "Pass / Review / Fail",
"records": [
{
"recordId": "TCM-ANGELICA-2026-DIM-001",
"status": "Pass / Review / Fail",
"criticalFindings": [],
"warnings": [],
"evaluatedRules": [
"Configured acceptance criteria from the utility rule set"
],
"inputTrace": {
"BatchNumber": "TCM-ANGELICA-2026-DIM-001",
"HerbName": "Angelica_sinensis",
"CutType": "Slice",
"AvgThickness_mm": "2.8",
"ThicknessStdDev_mm": "0.4",
"FinesPercent": "3.5",
"OversizedPercent": "2.0",
"UniformityIndex": "0.92"
}
}
],
"dataIntegrity": {
"deterministicEvaluation": true,
"sourceRowTraceability": true,
"manualOverrideAllowed": false
}
}
5. Traceability URS → FS → tests
| URS | FS mechanism | Test evidence |
|---|---|---|
| Load valid input.csv | CSV parser + schema validator | OQ: valid/invalid CSV cases |
| Deterministic limit evaluation | Rule engine with fixed configuration | OQ: boundary values and known expected results |
| Pass/Review/Fail statuses | Status aggregator based on findings | OQ/PQ: passing and failing representative batches |
| Traceability to source row | inputTrace + recordId | PQ: output.json reconciliation to source CSV |
| QA review support | structured findings and warnings | PQ: review and deviation-handling scenarios |
6. CSV/CSA and validation approach
IQ
- utility version check;
- executable location check;
- CSV template check;
- access-right verification.
OQ
- mandatory field checks;
- data type checks;
- boundary-value checks;
- zero-tolerance rule checks.
PQ
- runs on real or representative data;
- comparison with manual calculation;
- confirmation of QA review workflow.
Change control
- rule and limit versioning;
- impact assessment for rule changes;
- regression after updates.
Included in packages
Traditional Chinese Medicine (TCM) QC Suite
QC utility package for TCM: botanical identity, fingerprint consistency, marker compounds, decoction pieces, Paozhi processing, pesticides, mycotoxins, heavy metals, sulfur fumigation, microbial limits and adulteration screening.
Open