Документ Формата

## Кратко Для Сайта
`uossv` — это человеко-ориентированный плоский текстовый формат для строковых данных, где важны не столбцы как в `.tsv`, а короткие записи, которые можно быстро набрать вручную и при этом стабильно разобрать скриптом.

Формат использует не табы, а нечетные группы пробелов: `3` пробела служат обычным разделителем полей, `5`, `7`, `9+` пробелов задают более глубокие группы. В текущем репозитории он применяется как `.uossv`: строки могут быть неполными, порядок редких полей может отличаться, а завершенные или неактивные записи переносятся вниз файла.

Что можно вынести на сайт без сильной переработки:
- хранение задач и доступов в обычных `.txt` файлах
- быстрый ручной ввод коротких строк
- постепенное расширение строки тегами вида `slug=...` или `expires=...`
- предсказуемый экспорт в `.csv` или `.tsv`

## Преамбула
`plan.txt` и `password.txt` остаются файлами `.txt` для повседневной работы. По своей структуре они ближе всего к `Unordered Odd Space Separated Values`, далее `.uossv`: это плоский формат, где каждая строка может содержать разное количество полей, а средняя часть строки не обязана быть жестко табличной.

Связанные названия форматов:
- `.tsv` — `Tab Separated Values`, один таб как структурный разделитель
- `.ossv` — `Odd Space Separated Values`, нечетные группы пробелов как разделители
- `.uossv` — неупорядоченный вариант `.ossv` для плоских строк с разной полнотой
- короткие варианты `.osv` и `.uosv` допустимы как алиасы, но в документе основными считаются `.ossv` и `.uossv`

Главное отличие `.tsv` от `.ossv` в семействе разделителей. `.tsv` использует только один таб. `.ossv` допускает `1`, `3`, `5`, `7`, `9+` пробелов. В этом репозитории рабочие файлы ведут себя как `.uossv`, хотя физически остаются `.txt`.

## Политика Именования
В документации лучше держать одно основное имя формата, а не несколько равных названий в одной строке.

Рекомендуемая схема:
- формат хранения: `.txt`
- семейство форматов: `.ossv`
- текущий рабочий профиль строк: `.uossv`
- короткие алиасы: `.osv` и `.uosv`

Не стоит показывать `.txt`, `.osv`, `.uosv`, `.ossv` и `.uossv` как пять равных имен одного и того же файла. Это делает формат менее понятным.

## Назначение
`plan.txt` и `password.txt` — компактные плоские текстовые таблицы. Их сначала редактирует человек, а потом при необходимости разбирает скрипт. Первая строка — это строка-инструкция формата, вторая строка пустая, дальше идут данные.

## Рабочий Профиль
- пустые строки игнорируются
- первая строка читается как инструкция формата
- файлы считаются `.txt`, но по поведению соответствуют профилю `.uossv`
- базовый разделитель данных — `3` пробела
- группы из `5`, `7`, `9+` пробелов считаются более глубокими уровнями, а не пустыми ячейками
- разбор идет от самых широких групп к узким: `9+`, затем `7`, затем `5`, затем `3`
- одинарные пробелы внутри значений не разделяют поле
- каждая строка независима и может не содержать часть необязательных полей
- короткие строки остаются позиционными и без ключей
- расширенные строки живут в том же файле, но редкие поля записываются как теги `name=value`
- если в строке появился первый тег, все последующие редкие поля лучше тоже писать тегами
- завершенные и неактивные строки держатся в нижнем блоке и сохраняют внутренний порядок

## Строка-Инструкция
Заголовок файла — это одна строка с `#` в начале. Она должна читаться как правило для человека, а не как блок настроек для запуска. Части строки разделяются `3` пробелами.

Для рабочих файлов сама строка-инструкция держится на английском: так она короче, ровнее звучит в заголовке и лучше совпадает с тегами вроде `slug=...` или `expires=...`.

Рекомендуемый порядок фраз:
- `write ... first`
- `keep ... next`
- `add extra fields only as tags like ...`
- `keep ... near the end`
- `keep ... only as the last value`
- `move final rows to the bottom`
- `export order ...`

Внутри строки-инструкции:
- лучше использовать обычные слова и короткие правила, а не плотную схему из `key=value`
- `name=value` допустим только как пример тега внутри самой инструкции
- запятые нужны только в части с порядком экспорта
- формулировки могут быть человеческими, но порядок смысловых блоков должен оставаться стабильным

## plan.txt
Строка-инструкция в [plan.txt](/home/konstantin/Documents/profile-sample/plan.txt) означает следующее:
- сначала пишется `[id] задача`, например `[11] описание хранения задач и сравнения форматов`
- затем при наличии идут `проект` и `клиент`
- редкие поля записываются тегами вида `slug=...`, `category=...`, `due=...`, `price=...`
- время остается ближе к правому краю строки в человекочитаемом виде, например `140 минут`
- `СДЕЛАНО` и `НЕАКТИВНО` допустимы только как последнее обычное значение
- нижний блок файла отведен под завершенные или неактивные строки
- часть `порядок экспорта ...` задает целевую колонночную схему для `.csv` или `.tsv`

Основные формы строк:
- `[2] черновая задача без уточнений`
- `[9] условный робот для служебной операции   240 минут`
- `[9] условный робот для служебной операции   project-eta.example   ООО Клиент Пример Зета   240 минут`
- `[31] карточка проекта   project-alpha.example   ООО Клиент Пример Альфа   slug=client-portfolio   parent=portfolio   category=портфель   status=in-progress   url=/plan/item.php?slug=client-portfolio   start=2026-03-01   due=2026-04-01   effective=860   average=960   120 минут`

Соответствие тегов колонкам экспорта:
- `project -> project_slug`, `client -> client`, `task -> task`
- `title= -> title`, `slug= -> slug`, `parent= -> parent_slug`, `customer= -> customer_key`, `sort= -> sort_order`
- `desc= -> description`, `category= -> category`, `status= -> status`, `vis= -> visibility`, `hidden= -> admin_hidden`
- `code= -> access_code`, `url= -> url`, `start= -> start_at`, `due= -> due_at`
- `work-start= -> work_start_at`, `work-end= -> work_end_at`, `effective= -> effective_minutes`, `average= -> average_minutes`
- `price= -> price`, `info= -> information`, `published= -> published_at`

## password.txt
Строка-инструкция в [password.txt](/home/konstantin/Documents/profile-sample/password.txt) означает следующее:
- сначала записывается либо один `endpoint`, либо пара `label   secret`
- если в строке два секрета, используется блок на `5` пробелах
- `note` остается основным читаемым полем в середине строки
- редкие поля записываются тегами вида `login=...`, `email=...`, `expires=...`, `info=...`
- `endpoint` держится ближе к правому краю как главное целевое поле
- `ИСТЕК` и `НЕАКТИВНО` допустимы только как последнее обычное значение
- нижний блок файла отведен под истекшие или неактивные строки
- часть `порядок экспорта ...` задает целевую колонночную схему для `.csv` или `.tsv`

Основные формы строк:
- `billing.project-beta.example`
- `admin-user-01   PassPlaceholder01!   panel.project-alpha.example`
- `admin-user-01   PassPlaceholder01!   панель примера   panel.project-alpha.example`
- `hosting-main     HostPlaceholder02!   DbPlaceholder02!     хостинг и база примера   cp.project-alpha.example`
- `vpn-user-08   VpnPlaceholder08!   удаленный доступ примера   expires=2026-04-01   vpn.office-example.local`
- `archive-user-77   OldPlaceholder77!   старый тестовый доступ   ftp.project-theta.example   ИСТЕК`

Соответствие тегов колонкам экспорта:
- `label -> label`, первый секрет -> `secret_1`, второй секрет в пакете -> `secret_2`
- `note -> note`, `client -> client`, `project -> project`, `category -> category`, `type -> type`, `location -> location`
- `login= -> login`, `email= -> email`, `role= -> role`, `url= -> url`, `expires= -> expires`, `info= -> information`
- правый `endpoint -> endpoint`, терминальное значение -> `final`

## Форм-Факторы И Риски
Поддерживаемые формы в `plan.txt`:
- короткая черновая строка
- строка только с оценкой времени
- строка с проектом и клиентом
- расширенная строка с тегами
- завершенная или неактивная строка внизу файла

Поддерживаемые формы в `password.txt`:
- строка только с endpoint
- строка с label и одним secret
- строка с label и двумя secret внутри группы
- строка с тегами доступа
- истекшая или неактивная строка внизу файла

Основные риски:
- слишком много нетегированных полей делает строку неоднозначной
- тег `status=` можно перепутать с терминальным состоянием строки
- повтор одного и того же тега в строке ломает экспорт
- повтор `slug=` мешает древовидным связям через `parent=`
- табличные редакторы импортируют первую строку как данные, если ее не пропустить вручную
- обычные DSV-инструменты могут схлопывать или пересчитывать повторные пробелы не так, как ожидается

Принятые ограничения:
- без тегов остаются только самые частые поля середины строки
- терминальное состояние хранится отдельным последним значением
- каждый тег допустим не более одного раза в строке
- `slug=` должен быть уникальным, если строка участвует в иерархии
- при важности табличной совместимости лучше экспортировать в `.csv` или `.tsv`

## Профили Сортировки
- `source` — сохранять строки в исходном порядке
- `grouped` — переносить завершенные или неактивные строки вниз стабильной группировкой
- `preferred` — нормализовать строку по схеме `левая часть -> обычная середина -> теги -> правая часть -> терминальное значение`, не меняя сами значения

## Профиль `sep=1` Для Экспорта
`.ossv` может использовать `1` пробел как структурный разделитель только там, где каждое поле уже сведено к одному токену или к строгому ASCII-значению. Это подходит для компактных экспортов и примеров, но не для текущих рабочих файлов.

Нельзя безопасно ожидать, что один и тот же файл корректно прочтется и как `sep=1`, и как `sep=3`. Если инструменту указать разделитель в один пробел, строка вида `[31] карточка проекта   project-alpha.example   slug=client-portfolio   120 минут` потеряет смысл рабочего профиля `sep=3`.

## Табличные Редакторы
Excel, Google Sheets, OpenOffice Calc и LibreOffice Calc по умолчанию не считают `#` комментарием при импорте разделенного текста. На практике первая строка попадет в таблицу как обычная строка данных, если не пропустить ее вручную.

Для работы через таблицы:
1. хранить исходные данные в нативном `.uossv`
2. пропускать первую строку-инструкцию при прямом импорте
3. экспортировать в `.tsv` или `.csv`, когда важнее совместимость с табличными инструментами

## Алгоритм Разбора
1. прочитать первую строку как инструкцию формата
2. разделить ее на смысловые блоки по `3` пробелам и распознать устойчивые английские фразы
3. пропустить пустую вторую строку
4. разбирать строку данных от широких групп пробелов к узким
5. снять справа терминальное состояние, если оно есть
6. определить левую форму строки: `[id] задача`, `endpoint`, `label   secret` или `label     secret1   secret2`
7. распределить нетегированные средние поля в стандартные слоты
8. разобрать все оставшиеся поля вида `name=value` как теги
9. при необходимости собрать выход в порядке, указанном в части `порядок экспорта ...`

## Правило Обновления
- если меняется грамматика строк, сначала обновляется первая строка файла, затем этот документ
- строки данных должны оставаться короткими и удобными для ручного ввода
- новые поля добавляются только тогда, когда они действительно улучшают ручную работу или экспорт