Add hardware health and uptime reports

System/check-hardware-health.md

@@ -0,0 +1,52 @@
+# check-hardware-health.sh
+
+Проверява SMART състоянието и типа на физическите дискове, както и температурите на наличните хардуерни датчици. Проблемите се маркират с червен текст в терминала и с червен статус в HTML отчета.
+
+## Какво прави
+
+Скриптът показва времето от последното стартиране на системата, открива дисковете чрез `lsblk`, определя типа им по интерфейса и rotational флага (например PATA, SATA HDD/SSD и NVMe SSD), след което чете SMART данните чрез `smartctl`. При неуспешен SMART self-assessment или отчетен NVMe critical warning дискът се маркира като проблемен. Температурите се събират чрез `sensors -j`; за всеки датчик се използват предоставените от него прагове, а ако липсват — предпазни прагове по тип компонент. SMART температурата също се включва, когато е налична. При системи с батерия се показват зарядът, състоянието, циклите и здравето, изчислено от пълния спрямо проектния капацитет, когато тези стойности са налични.
+
+Отчетът се показва в терминала и може да се запише като TXT, HTML или JSON. За терминалния изход се използва ANSI червено, когато stdout е терминал и `NO_COLOR` не е зададен; TXT файлът съдържа ясни статуси, HTML отчетът оцветява проблемните редове в червено, а JSON файлът съдържа структурираните данни от проверката.
+
+При стартиране чрез `sudo` интерактивният път по подразбиране сочи към home директорията на извикалия потребител. Записаният файл получава неговите UID/GID, така че да остане достъпен за него след приключване на скрипта.
+
+## Изисквания
+
+- Linux, Bash, Python 3 и `lsblk` (задължителни)
+- `smartmontools` (`smartctl`) — незадължителен; без него SMART е „непроверено“
+- `lm-sensors` (`sensors`) — незадължителен; без него температурите от тези датчици не са налични
+- SMART достъпът до някои устройства може да изисква root права или подходящи права за `/dev`.
+- При стартиране без root права скриптът предупреждава, че SMART данните може да са непълни, и иска потвърждение преди проверките.
+
+## Употреба
+
+```bash
+./System/check-hardware-health.sh [OPTIONS]
+```
+
+| Опция | Описание |
+|-------|----------|
+| `-o`, `--output PATH` | Записва директно във файл; без тази опция предлага интерактивен запис |
+| `-f`, `--format FORMAT` | Формат `txt`, `html` или `json` |
+| `--force` | Позволява презапис на съществуващ файл без потвърждение |
+| `-h`, `--help` | Показва помощта и приключва |
+
+## Примери
+
+```bash
+# Проверява устройствата и предлага интерактивно записване
+./System/check-hardware-health.sh
+
+# Записва HTML отчет
+./System/check-hardware-health.sh --output "$HOME/hardware-health.html"
+
+# Записва HTML отчет и разрешава презапис
+./System/check-hardware-health.sh --output /tmp/hardware-health.html --format html --force
+
+# Записва структуриран JSON отчет; форматът се разпознава и по разширението
+./System/check-hardware-health.sh --output "$HOME/hardware-health.json"
+```
+
+## Ограничения
+
+Показват се само датчици, SMART атрибути и батерийни полета, предоставени от kernel, драйвера и устройството. Липсващ резултат не доказва, че компонентът е изправен. Батерийното здраве се оценява спрямо капацитетите full/design: под 80% е предупреждение, под 60% е критично; някои драйвери не предоставят цикли или капацитети. Прагът за температурно предупреждение обичайно идва от `sensors`; при липса на праг се използват 60 C за дискове, 85 C за CPU/GPU и 80 C за други компоненти. Това са общи предпазни стойности, не заместител на спецификацията на производителя. „PATA“ се разпознава само когато устройството е представено с традиционно `/dev/hd*` име без transport метаданни; при двусмислени данни отчетът използва обобщения тип от `lsblk`.