Ревью проекта перед публикацией на GitHub¶
Дата: Март 2025
Цель: Подготовка к замене текущего репозитория. Проект должен быть полным и профессиональным.
Статус: Исправления применены (март 2025).
1. AI-паттерны и артефакты¶
Эмодзи в коде (src/)¶
Эмодзи в логах, комментариях, HTML-генерации — ~200+ вхождений в 25+ файлах:
| Файл | Примеры |
|---|---|
routes_config.cpp |
✅, 🔒, 📊, 🎯 |
routes_ota.cpp |
🚀, 📱, 🌐, 📁 |
routes_calibration.cpp |
✅, ❌, ⚠️ |
logger.cpp, main.cpp |
В logInfo/logSuccess |
jxct_ui_system.h |
UI_ICON_* — константы для веб-UI |
Рекомендация: Эмодзи в logInfo/logSuccess — убрать или заменить на текстовые метки. UI_ICON_* в веб-интерфейсе — оставить (это UI-элементы). Комментарии вида // ✅ CSRF защита — убрать декоративные.
Шаблонные фразы¶
«Важно», «критично», «рекомендуется», «обязательно» — в docs/, habr_article/. Заменить на нейтральные: «следует», «желательно», «требуется».
Избыточные комментарии¶
// ======= ВАЛИДАЦИЯ =======— декоративные разделители// 🚨 ПРИОРИТЕТ 1 (КРИТИЧНО)вscripts/asm_humidity_correction.py// ✅ Конфигурация успешно импортирована— дублирует сообщение пользователю
2. Несоответствие API в документации¶
Фактический API (include/jxct_strings.h): API_ROOT = "/api/v1"
| Документ | Указано | Нужно |
|---|---|---|
docs/manuals/API.md |
Примеры: /api/sensor |
/api/v1/sensor |
docs/manuals/TECHNICAL_DOCS.md |
/api/v3.13.2/* |
/api/v1/* |
docs/manuals/VERSION_MANAGEMENT.md |
/api/sensor |
/api/v1/sensor |
habr_article/article.md |
/api/v3.13.2/* |
/api/v1/* |
habr_article/article.md |
.../temperature/add |
.../temperature (как в коде) |
Тесты: test/integration/test_web_api_integration.cpp использует /api/sensor/data — такого маршрута нет в коде. Проверить: mock или устаревший тест.
3. Версии¶
| Место | Значение | Действие |
|---|---|---|
include/version.h |
3.13.2 | OK |
VERSION |
3.13.2 | OK |
docs/manuals/API.md |
Пример JSON: "version": "3.10.0" |
Заменить на 3.13.2 |
docs/manuals/CONFIG_MANAGEMENT.md |
3.10.0 | Обновить |
docs/manuals/USER_GUIDE.md |
3.10.0 | Обновить |
4. Безопасность¶
| Файл | Проблема |
|---|---|
docs/manuals/CONFIG_MANAGEMENT.md |
"password":"secret123", "api_key":"ABCD1234EFGH5678" в примере JSON |
5. Структура и артефакты¶
Удалить¶
| Файл/папка | Причина |
|---|---|
site/asm_corrections.cpp |
C++ в папке MkDocs, не компилируется, артефакт |
Битые ссылки¶
| Ссылка | Файл | Решение |
|---|---|---|
docs/dev/reports/ |
test_reports/MASTER_TEST_SUMMARY.md |
Папка не существует. Указать test_reports/ или убрать ссылку |
Пути к скриптам¶
| Документ | Указано | Реально |
|---|---|---|
docs/CONTRIBUTING.md |
scripts/analyze_technical_debt.py |
scripts/audit/analyze_technical_debt.py |
6. .gitignore¶
Текущее состояние:
- test_reports/*.json, *.md, *.txt — игнорируются
- !test_reports/README.md — но README.md в test_reports/ отсутствует
- site/ — не в .gitignore (публикуется на GitHub Pages?)
Рекомендация: Решить: site/ в репо (для Pages) или генерировать в CI. Если в репо — оставить. Добавить test_reports/README.md с пояснением структуры.
7. Чего не хватает для профессионального репо¶
| Элемент | Статус |
|---|---|
CONTRIBUTING.md в корне |
Есть docs/CONTRIBUTING.md. GitHub ожидает корневой — добавить симлинк или копию |
SECURITY.md |
Нет. Рекомендуется для приёма отчётов об уязвимостях |
test_reports/README.md |
Нет. Создать с пояснением (JSON — артефакты CI) |
CODE_OF_CONDUCT.md |
Опционально |
8. site/ — сгенерированная документация¶
site/— MkDocs + Doxygen (~3700 файлов)- Содержит устаревшие данные:
/api/v3.13.2/,/api/sensorв HTML - После правок в
docs/manuals/*.mdнужно пересобрать:mkdocs build && doxygen Doxyfile
9. Чек-лист перед push¶
Критично¶
- Привести все пути API к
/api/v1в docs, habr_article - Убрать
secret123,ABCD1234EFGH5678из CONFIG_MANAGEMENT.md - Исправить путь
analyze_technical_debt.pyв CONTRIBUTING - Удалить
site/asm_corrections.cpp - Обновить версию в примерах (3.10.0 → 3.13.2)
Желательно¶
- Исправить ссылку на
docs/dev/reports/в MASTER_TEST_SUMMARY - Создать
test_reports/README.md - Добавить
CONTRIBUTING.mdв корень (или симлинк) - Пересобрать site/ после правок в docs
Опционально¶
- Убрать эмодзи из C++ логов
- Добавить SECURITY.md
- Заменить шаблонные фразы в документации
10. Итог¶
Проект рабочий и структурирован. Основные задачи перед публикацией:
- Унификация API — везде
/api/v1 - Безопасность — убрать примеры с паролями
- Консистентность — версии, пути к скриптам, битые ссылки
- Чистота — удалить артефакты, убрать AI-паттерны по возможности
После исправлений — пересобрать документацию и проверить, что pio run, pio test, python -m pytest test/ проходят.