diff --git a/analysis/cleanup-worklog-2026-04-29.md b/analysis/cleanup-worklog-2026-04-29.md
index c19b9ee..c749a8b 100644
--- a/analysis/cleanup-worklog-2026-04-29.md
+++ b/analysis/cleanup-worklog-2026-04-29.md
@@ -312,3 +312,94 @@
- сделать второй проход по прикладным файлам
- удалить комментарии в формате рассуждений там, где они явно не нужны для понимания текущей логики
- отдельно обработать `v1/Application.cfc` как специальный случай
+
+## Обновление: второй проход по комментариям-рассуждениям
+
+Дата фиксации: 2026-04-29 20:45:13 +0400.
+
+### Что сделано
+
+Во втором проходе очищались не version-header блоки, а именно комментарии в стиле внутренних сомнений, оценок и рассуждений автора.
+
+Обработаны файлы:
+- `v1/lib/field_set.cfm`
+- `v1/lib/order_build.cfm`
+- `v1/resources/svc_default.cfc`
+- `v1/lib/rest_api_helper.cfc`
+
+Удалялись в первую очередь такие типы комментариев:
+- сомнения автора в корректности подхода
+- эмоциональные оценки вроде "некрасиво"
+- внутренние заметки вида "не уверен", "не нравится", "странно"
+- краткие следы от отладочных/временных рассуждений
+
+### Что не удалялось
+
+- технические комментарии, поясняющие назначение параметров и смысл структуры данных
+- комментарии, нужные для понимания формата вызова или ограничений API
+- комментарии, которые пока относятся к будущему этапу перевода, а не удаления
+
+### Проверка
+
+После второго прохода измененные файлы проверены на ошибки.
+Результат:
+- синтаксических ошибок не обнаружено
+
+### Промежуточный вывод
+
+Эта стратегия работает лучше, чем агрессивная массовая чистка: можно постепенно отделять лишние авторские рассуждения от реально полезных технических пояснений.
+
+### Следующий шаг
+
+- перевести оставшиеся английские комментарии в уже обработанных небольших файлах
+- отдельно обработать `v1/lib/TokenGenerator.cfc`, где комментарии почти полностью англоязычные
+- затем перейти к следующей группе прикладных файлов
+
+## Обновление: дополнительные commented-out блоки и перевод комментариев
+
+Дата фиксации: 2026-04-29 20:48:58 +0400.
+
+### Что сделано перед переводом
+
+Перед этапом перевода был выполнен еще один безопасный шаг:
+- удалены крупные закомментированные legacy-блоки в `v1/lib/rest_api_helper.cfc`
+- удален закомментированный альтернативный блок base64url-преобразования в `v1/lib/TokenGenerator.cfc`
+
+Причина:
+- переводить комментарии вокруг уже неиспользуемого мертвого кода не имеет смысла
+- сначала убирается то, что точно не участвует в runtime
+
+### Что переведено на русский
+
+Перевод выполнен в следующих файлах:
+- `v1/lib/TokenGenerator.cfc`
+- `v1/lib/field.cfm`
+- `v1/lib/order_build.cfm`
+- `v1/lib/filter_build.cfm`
+- `v1/lib/rest_api_helper.cfc`
+
+Переводились:
+- `hint`-описания функций и компонентов
+- английские технические комментарии
+- внутренние пояснения о поведении генератора токенов и helper-логики
+
+Что сознательно не переводилось:
+- runtime-сообщения ошибок и исключений
+- публичные текстовые значения, которые могут участвовать в API-контракте
+
+### Проверка
+
+После удаления закомментированных блоков и после перевода комментариев проверены измененные файлы.
+Результат:
+- синтаксических ошибок не обнаружено
+
+### Промежуточный вывод
+
+На этом этапе уже очищен и приведен к более однородному виду значимый кусок вспомогательного слоя `v1/lib`.
+Это хорошая база перед переходом к более рискованным файлам уровня `Application.cfc` и крупных `resources/*.cfc`.
+
+### Следующий шаг
+
+- посмотреть текущее diff-состояние cleanup-ветки
+- зафиксировать сделанные этапы в коммитах
+- затем перейти к следующей группе файлов, начиная с наиболее контролируемых resource-компонентов
diff --git a/v1/lib/TokenGenerator.cfc b/v1/lib/TokenGenerator.cfc
index 7f9e74a..c3c883c 100644
--- a/v1/lib/TokenGenerator.cfc
+++ b/v1/lib/TokenGenerator.cfc
@@ -1,19 +1,18 @@
component /*https://www.bennadel.com/blog/2976-trying-to-generate-cryptographically-strong-random-tokens-in-coldfusion.htm*/
output = false
- hint = "I generate random tokens using Java's SecureRandom class."
+ hint = "Генерирует случайные токены с помощью Java SecureRandom."
{
/**
- * I initialize the token generator.
+ * Инициализирует генератор токенов.
*
* @output false
*/
public any function init() {
- // I am the generator implementation used to generate the random token data.
- // --
- // NOTE: The SHA1PRNG is not the default in all implementations of the JVM. As
- // such, we're defining the algorithm explicitly to keep this code consistent.
+ // Реализация генератора, используемая для построения случайных токенов.
+ // SHA1PRNG не является алгоритмом по умолчанию во всех реализациях JVM,
+ // поэтому он задается явно для предсказуемого поведения.
generator = createObject( "java", "java.security.SecureRandom" )
.getInstance(
javaCast( "string", "SHA1PRNG" ),
@@ -21,22 +20,14 @@ component /*https://www.bennadel.com/blog/2976-trying-to-generate-cryptographica
)
;
- // Now that we've initialized the random generator, we have to generate a random
- // byte of data. This will ensure that the random generator is self-seeded using
- // a shared seed generator.
- // --
- // CAUTION: Since the underlying seed generator reads from sources of entropy,
- // this may hang until enough entropy has been collected. This is another good
- // reason to do it during initialization time rather than at first-use time.
+ // После инициализации нужно сгенерировать случайный байт,
+ // чтобы генератор сам засеялся через общий источник seed.
+ // Это может блокироваться до накопления достаточной энтропии,
+ // поэтому операция выполняется при инициализации, а не при первом использовании.
generator.nextBytes( charsetDecode( " ", "utf-8" ) );
- // I hold the future date at which time the generator should be reseeded in order
- // to keep it unpredictable.
- // --
- // NOTE: This doesn't affect the randomness of the values. But, the thinking
- // is that the longer the generator is producing values using the same seed,
- // the more likely an attacker is to be able to determine the original seed by
- // passively observing generated values.
+ // Момент следующего пересева генератора.
+ // Это снижает риск слишком долгой работы с одним и тем же seed.
reseedAt = getNextReseedAt();
return( this );
@@ -44,34 +35,23 @@ component /*https://www.bennadel.com/blog/2976-trying-to-generate-cryptographica
}
- // ---
- // PUBLIC METHODS.
- // ---
+ // Публичные методы.
/**
- * I generate "cryptographically strong" random token strings that are based on the
- * given number of random bytes. The random bytes are subsequently encoded using a
- * base64url character-set so that they are URL-safe and can be used in a variety of
- * contexts. And, since base65url is a case-sensitive schema, the tokens will
- * naturally be case-sensitive.
+ * Генерирует криптографически стойкий токен из заданного числа случайных байтов.
+ * Байт-массив кодируется в форму, пригодную для использования в URL.
*
- * @byteCount I am the number of random bytes used to generate the token.
+ * @byteCount Количество случайных байтов для генерации токена.
* @output false
*/
public string function nextToken( numeric byteCount = 32 ) {
- // Check to see if the generator needs to be reseeded (using a double-check
- // locking approach to reduce the bottleneck).
+ // Проверяем, нужен ли пересев генератора.
if ( now() >= reseedAt ) {
- // Synchronize the reseeding.
- // --
- // NOTE: From what I have read, I DON'T BELIEVE that .generateSeed() will
- // ever hang with the SHA1PRNG algorithm. However, it is unclear to me. As
- // such, I'm using [throwOnTimeout = false] so that parallel threads won't
- // error if the lock cannot be obtained in a timely manner and will just
- // fall through to using the generator with the pre-seeding state.
+ // Пересев выполняется под lock, чтобы уменьшить гонки между потоками.
+ // Если lock не получен вовремя, поток продолжает работу с текущим состоянием генератора.
lock
name = "TokenGenerator.reseedCheck"
type = "exclusive"
@@ -79,27 +59,21 @@ component /*https://www.bennadel.com/blog/2976-trying-to-generate-cryptographica
throwOnTimeout = false
{
- // Perform double-check - generator may have already been reseeded by
- // a parallel request.
+ // Повторная проверка внутри lock: другой поток мог уже обновить seed.
if ( now() >= reseedAt ) {
reseedAt = getNextReseedAt();
- // NOTE: Once the generator was seeded internally, this re-seeding
- // will only ever "add to" the existing seed. As such, this is still
- // building on top of the original randomness and calling this, on
- // interval, this will never reduce randomness.
+ // Новый seed добавляется к уже существующему внутреннему состоянию генератора.
generator.setSeed( generator.generateSeed( javaCast( "int", 32 ) ) );
}
- } // END: Lock.
+ }
}
- // Create the byte buffer into which the random bytes will be written. Since
- // there's no "correct" way to generate a byte array in ColdFusion, we can
- // generate a string of the desired length and then decode it into bytes.
+ // Создаем буфер байтов, в который будут записаны случайные значения.
var byteBuffer = charsetDecode( repeatString( " ", byteCount ), "utf-8" );
generator.nextBytes( byteBuffer );
@@ -109,27 +83,18 @@ component /*https://www.bennadel.com/blog/2976-trying-to-generate-cryptographica
}
- // ---
- // PRIVATE METHODS.
- // ---
+ // Приватные методы.
/**
- * I encode the given byte array using the base64url character-set.
+ * Кодирует массив байтов в строку токена.
*
- * @bytes I am the byte array being encoded.
+ * @bytes Кодируемый массив байтов.
* @output false
*/
private string function encodeBytes( required binary bytes ) {
var token = binaryEncode( bytes, "base64" ); // *** вот поэтому длина отличается от заявленной
-
- // Replace the characters that are not allowed in the base64url format. The
- // characters [+, /, =] are removed for URL-based base64 values because they
- // have significant meaning in the context of URL paths and query-strings.
- /*token = replace( token, "+", "-", "all" );
- token = replace( token, "/", "_", "all" );
- token = replace( token, "=", "", "all" ); */
// мы хотим убрать все спецсимволы, потому что мы используем токен в качестве псевдослучайного суффикса
token = replace( token, "+", "a", "all" );
@@ -142,7 +107,7 @@ component /*https://www.bennadel.com/blog/2976-trying-to-generate-cryptographica
/**
- * I calculate the next date of reseeding.
+ * Вычисляет время следующего пересева генератора.
*
* @output false
*/
diff --git a/v1/lib/field_set.cfm b/v1/lib/field_set.cfm
index a678dc0..5c3f1d8 100644
--- a/v1/lib/field_set.cfm
+++ b/v1/lib/field_set.cfm
@@ -1,7 +1,7 @@
-
+
-
+
@@ -19,11 +19,9 @@
-
-
@@ -52,7 +50,7 @@
-
+
diff --git a/v1/lib/order_build.cfm b/v1/lib/order_build.cfm
index 7d95daa..3bd8348 100644
--- a/v1/lib/order_build.cfm
+++ b/v1/lib/order_build.cfm
@@ -1,5 +1,5 @@
-
+
@@ -9,7 +9,7 @@
-
+
diff --git a/v1/lib/rest_api_helper.cfc b/v1/lib/rest_api_helper.cfc
index d9f2446..440688d 100644
--- a/v1/lib/rest_api_helper.cfc
+++ b/v1/lib/rest_api_helper.cfc
@@ -1,18 +1,17 @@
+ hint="Статические вспомогательные методы для ReST API">
+ hint="Заменяет пустое поле на null">
-
-
+
@@ -23,7 +22,7 @@
+ hint="Возвращает аргумент без изменений">
@@ -33,7 +32,7 @@
access="public"
returntype="any"
output="false"
- hint="put data into struct, replace empty fields with null">
+ hint="Записывает данные в структуру, заменяя пустые поля на null">
@@ -65,9 +64,7 @@
-
-
@@ -78,13 +75,10 @@
+ hint="Разбирает и собирает параметры фильтра из URL. Операторы задаются в filter_build">
-
-
-
-
+
@@ -93,7 +87,7 @@
-
+
@@ -134,12 +128,10 @@
-
-
+ hint="Разбирает и собирает параметры фильтра; операторы задаются в filter_build">
-
+
@@ -147,7 +139,7 @@
-
+
@@ -189,7 +181,7 @@
+ hint="Разбирает и собирает параметр сортировки">
@@ -203,7 +195,7 @@
-
+
@@ -223,7 +215,7 @@
+ hint="Разбирает и собирает параметр сортировки в числовой нотации">
@@ -237,7 +229,7 @@
-
+
@@ -252,35 +244,9 @@
-
-
-
-
-
+
+ hint="Преобразует query в массив структур. Имена ключей приводятся к нижнему регистру, пустые поля считаются null">
@@ -308,7 +274,7 @@
access="public"
returntype="any"
output="false"
- hint="convert snake style name to camel style name">
+ hint="Преобразует имя в стиле snake_case в camelCase">
@@ -318,7 +284,7 @@
access="public"
returntype="any"
output="false"
- hint="convert camel style name to snake style name">
+ hint="Преобразует имя в стиле camelCase в snake_case">
@@ -327,7 +293,7 @@
access="public"
returntype="any"
output="true"
- hint="formats Exception for display">
+ hint="Форматирует сообщение для вывода">
@@ -342,7 +308,7 @@
access="public"
returntype="any"
output="true"
- hint="formats Exception for display">
+ hint="Форматирует исключение для вывода">
@@ -357,7 +323,7 @@
access="public"
returntype="any"
output="true"
- hint="formats Bad Request Exception">
+ hint="Форматирует ошибку Bad Request">
@@ -366,41 +332,6 @@
-
-
+ hint="Проверяет поле структуры, если оно существует">
diff --git a/v1/resources/svc_default.cfc b/v1/resources/svc_default.cfc
index 1845324..02af28e 100644
--- a/v1/resources/svc_default.cfc
+++ b/v1/resources/svc_default.cfc
@@ -30,7 +30,6 @@
-