type: reform
aspect: naming
title: "Реформа: именование и организация артефактов платформы"
version: 0.1.0
date: 2026-03-30
status: draft
owner: architect

РЕФОРМА: именование и организация артефактов платформы

ЧЕРНОВИК — не применять до финализации

1. МАНИФЕСТ РЕФОРМЫ

Суть

Текущие стандарты именования раздроблены по трём файлам, дублируют друг друга и смешивают несколько аспектов (naming, structure, typology) в одном документе. Реформа:
- объединяет правила именования в единый стандарт по пространствам
- выделяет типологию компонентов в отдельный документ
- вводит паттерн «реформа» в процесс изменений платформы

Методология реформенного документа

Этот документ содержит:
1. Манифест — что и зачем меняем
2. Анализ и томография — проверка перед применением
3. Чеклист миграции — порядок применения
4. Документы реформы — полный контент новых/изменённых файлов (каждый отдельной секцией)
5. Поправки в другие документы — список правок в файлы вне реформы (в конце)

Правило: поправки к документам вне области реформы не вносятся сразу —
они фиксируются в разделе «Поправки» и применяются после финализации реформы.

Архивируем (→ arh/)

Создаём

Обновляем

Не трогаем

• naming-variables.md — покрывает переменные в коде, остаётся
• naming-projects.md — именование проектов, остаётся
• naming-terminology.md — терминология, остаётся
• naming-code-imports.md — импорты в коде, остаётся
• structure-workspace.md — структура папок, остаётся (ссылки только)
• format-file-types.md — типы файлов, остаётся (ссылки только)

2. ТОМОГРАФИЯ И АНАЛИЗ

2.1 Проблемы текущего состояния

Раздробленность: три документа (naming-workspace.md, naming-dataspace.draft.md, naming-database.md) описывают одну тему — именование — но каждый в своём пространстве. Нет единого источника правил.

Смешение аспектов в naming-workspace.md и naming-platform.draft.md:

Неполнота naming-platform.draft.md v0.1.0:
- Отсутствуют роли .data и .cache
- Отсутствует .yml как вариант совместимости
- Отсутствует .credentials.md в конфиденциальных файлах
- Не хватает кодов БД: anl, doc, tsk
- Нет Nginx в разделе $INFRASTRUCTURE
- Нет колонки Status в таблице ролей

Несогласованность:
- Открытые вопросы об _inbox/ и подчёркиваниях — уже закрыты в тексте, но числились открытыми
- README.md в naming/ показывает устаревшую версию naming-workspace.md
- Формула $DATASPACE показывает дефис, примечание говорит "подчёркивания тоже допустимы" — два сигнала

Неоднозначность:
- В ролях нет разделения active / planned — читатель не знает, что работает сейчас
- "Форматы по размеру" в $DATASPACE — таблица называется Format, но описывает WHERE хранить

2.2 Соответствие концепции платформы

2.3 Томография финального результата (5 измерений)

Полнота: все пространства платформы покрыты ($WORKSPACE, $DATASPACE, $BACKUPSPACE, $DATABASE, $INFRASTRUCTURE). Роли файлов полные. Форматы полные. ✅

Согласованность: naming-platform.md не дублирует structure-workspace.md (только ссылается). typology-components.md содержит каталог без дублирования с naming. ✅

Однозначность: одно правило — одно место. Подчёркивания: явно по пространствам. Формула $DATASPACE: дефис стандарт, подчёркивания допустимы — зафиксировано в ОБЩИХ ПРАВИЛАХ, не как примечание. ✅

Применимость: практик может найти: нужна формула имени → naming-platform.md. Нужен тип компонента → typology-components.md. Нужна структура папок → structure-workspace.md. Три ответа, три документа. ✅

Структура: General → per-space specifics. Каждое пространство: формулы → примеры → антипримеры. ✅

3. ЧЕКЛИСТ МИГРАЦИИ

ПОДГОТОВКА
[ ] Утвердить reform-naming-arch.draft.md
[ ] git mv reform-naming-arch.draft.md process-naming-reform.draft.md

СОЗДАНИЕ НОВЫХ ФАЙЛОВ
[ ] naming-platform.md → architect/standards/naming/
[ ] typology-components.md → architect/standards/typology/

АРХИВИРОВАНИЕ
[ ] git mv naming-workspace.md arh/naming-workspace-2026-03-30.md
[ ] git mv naming-dataspace.draft.md arh/naming-dataspace-2026-03-30.md
[ ] git mv naming-database.md arh/naming-database-2026-03-30.md
[ ] rm naming-platform.draft.md (входит в reform, станет naming-platform.md)

ОБНОВЛЕНИЕ
[ ] architect/standards/naming/README.md — актуализировать список
[ ] architect/standards/process/process-platform-change.draft.md — добавить паттерн реформы
[ ] architect/CLAUDE.md — обновить ссылки
[ ] dms.draft.md — обновить ссылки

ФИНАЛИЗАЦИЯ
[ ] git commit: "feat(naming): reform — unified naming-platform.md, add typology-components"
[ ] git mv reform-naming-arch.draft.md arh/reform-naming-arch-2026-03-30.md

4. ДОКУМЕНТ 1: naming-platform.md

Путь: architect/standards/naming/naming-platform.md
Тип: standard | Аспект: naming | Статус: active (после миграции)
Заменяет: naming-workspace.md, naming-dataspace.draft.md, naming-database.md

Содержимое naming-platform.md

type: standard
aspect: naming
title: "Стандарт именования платформы"
version: 1.0.0
date: 2026-03-30
status: active
owner: architect
replaces: naming-workspace.md v3.2.0, naming-dataspace.draft.md v0.1.0, naming-database.md v1.0.0

Стандарт именования платформы

ОБЛАСТЬ ПРИМЕНЕНИЯ

Стандарт описывает правила именования во всех пространствах платформы.

Не описывает:
- Переменные и функции в коде → naming-variables.md
- Структуру папок → structure-workspace.md
- Типы компонентов → typology-components.md
- Типы файлов (11 классов) → format-file-types.md

ОБЩИЕ ПРАВИЛА

Регистр

Формульные документы:   lowercase            (naming-workspace.md)
Сервисные файлы:        UPPERCASE            (README.md, CLAUDE.md, INDEX.md)
Машинные файлы:         lowercase            (index.yaml, .env)

Разделители

Дефис (-)    — стандарт для файлов, папок, компонентов
Точка (.)    — разделитель роли и расширения  (naming-platform.draft.md)
               разделитель типа компонента     (@name.type)

Язык

Подчёркивания

$WORKSPACE

Документы — Формула

[aspect]-[object]-[detail].[role].format

Девять аспектов (фиксированные)

Роли файлов

Формат задачи: [YYYY-MM-DD]-[name].task.yaml

2026-03-30-deploy-worker.task.yaml

find . -name "*.draft.md"    # все черновики
find . -name "*.idea.md"     # все идеи
find . -name "*.task.yaml"   # все задачи
find . -name "*.ai.md"       # все файлы предназначенные для AI-агентов
find . -name "AI.md"         # все определения агентов (корень @name.agent/)

Форматы файлов

Правила именования

Формульные файлы:   lowercase + дефисы
Служебные файлы:    UPPERCASE без подчёркиваний
Машинные файлы:     lowercase

✅ naming-platform.md
✅ structure-workspace.md
✅ CLAUDE.md, INDEX.md, README.md
✅ index.yaml, .env
❌ naming_workspace.md     (подчёркивания запрещены везде и всегда)
❌ NamingWorkspace.md      (camelCase запрещён)
❌ NAMING-WORKSPACE.MD     (UPPERCASE для формульных)

Язык: только латиница — везде в $WORKSPACE без исключений.

Служебные файлы

Универсальные:

Правила размещения:

Шаблон CLAUDE.md:

# [Папка] — [одна строка: что это]

## СОДЕРЖИМОЕ
| Файл / Папка | Назначение |

## НАВИГАЦИЯ
| Задача / тема | Куда идти |

## ВАЖНО   ← только если есть реальные нюансы

Проектные:

Конфиденциальные (всегда в .gitignore):

Отчёты и логи:

❌ MIGRATION_COMPLETE_REPORT.md   (отдельный файл-отчёт)
✅ LOG.md                         (запись о миграции внутри)
✅ LOG-migration.md               (отдельный лог если большой)

$DATASPACE

Файлы данных — Формула

Датированные файлы (прайсы, выгрузки, отчёты):

{source}-{YYYY-MM-DD}.{ext}
{source}-{YYYY-MM-DD}-{suffix}.{ext}

✅ jf-2026-03-30.xlsx
✅ ozon-2026-03-30-orders.csv
✅ 1c-2026-03-30-export.xml
✅ jf_2026-03-30.xlsx          (подчёркивание допустимо — конвенция Python/1С)
❌ MASTER_PRICE_LIST (1).xlsx  (пробелы, скобки, UPPERCASE)
❌ 16.10 Прайс Maxsem.xlsx     (кириллица, пробелы)
❌ new-prices.xlsx             (нет даты — неясно когда актуально)

Файлы без временного контекста (справочники, медиа):

{entity}-{detail}.{ext}       — справочники
{article}-{view}.{ext}        — медиа товаров

✅ categories-mapping.csv
✅ 12345-front.jpg
❌ photo1.jpg                  (неинформативно)

Где хранить по размеру

Папки DATASPACE

$DATASPACE/
├── projects/              ← данные проектов (зеркало $WORKSPACE/projects/)
│   ├── my/
│   │   └── {project}/
│   │       ├── inbox/
│   │       ├── media/     ← медиа проекта (физически здесь; может быть примонтирован диск)
│   │       │   ├── images/
│   │       │   ├── video/
│   │       │   └── documents/
│   │       └── archive/
│   └── org/
│       └── {project}/
│           ├── inbox/
│           ├── prices/
│           ├── products/
│           ├── exports/
│           ├── media/     ← медиа проекта (физически здесь; может быть примонтирован диск)
│           │   ├── images/
│           │   ├── video/
│           │   └── documents/
│           └── archive/
├── releases/              ← сборки компонентов для деплоя (.zip, .tar.gz)
│   ├── connectors/
│   ├── extensions/
│   └── applications/
└── archive/               ← архивные данные

Что куда:

Медиа-стратегия проекта — фиксируется в index.yaml:

# projects/org/lideravto/index.yaml
media_storage: dataspace    # папка media/ в $DATASPACE (по умолчанию)
# media_storage: mounted     # media/ — точка монтирования отдельного S3/диска
# media_storage: cdn         # внешний CDN (Cloudflare, CloudFront)

Путь media/ в проекте всегда один и тот же. Отличается только то, что за ним стоит физически.

Стандартная структура проекта в projects/:

projects/org/{project}/
├── inbox/           ← входящие необработанные файлы
├── prices/          ← прайс-листы поставщиков
│   └── {supplier}/  ← по поставщику: jf/, maxsem/
├── products/        ← данные номенклатуры
│   └── 1c/          ← выгрузки из 1С
├── exports/         ← выгрузки для внешних систем
└── archive/
    └── {YYYY-MM}/   ← архив по месяцу

Обязательные: inbox/, archive/
Рекомендуемые: prices/, products/, exports/

Жизненный цикл файла в projects/:

inbox/  →  {тематическая}/  →  archive/{YYYY-MM}/

Зеркальность с $WORKSPACE:

$WORKSPACE/projects/my/{project}/          ← личные: код, доки
$DATASPACE/projects/my/{project}/          ← личные: данные, выгрузки
$DATASPACE/projects/my/{project}/media/    ← медиа (физически здесь или примонтировано)

$WORKSPACE/projects/org/{project}/         ← общественные/бизнес: код
$DATASPACE/projects/org/{project}/         ← данные, выгрузки
$DATASPACE/projects/org/{project}/media/   ← медиа (физически здесь или примонтировано)

Правило: media/ — всегда папка внутри проекта в $DATASPACE. Код обращается по одному пути независимо от физического хранилища за ним.

$BACKUPSPACE

Структура

$BACKUPSPACE/{server}/backup/
├── L0-SECRETS/          ← SSH ключи, credentials
├── L1-SYSTEM/           ← системные файлы
├── L2-DOCKER/           ← Docker volumes
├── L3-WORKSPACE/        ← исходный код (git bundle)
│   └── git-bundle/
├── L4-CLAUDE/           ← Claude конфиги и память
│   ├── claude-md/
│   └── settings/
├── L5-STATE/            ← состояние (опционально)
├── golden/              ← эталонные ручные копии
├── postgres/            ← дампы PostgreSQL
└── restic/              ← Restic repository

Формулы именования

{type}-{source}-{YYYYMMDD}-{HHMM}.{ext}

Расписание

$DATABASE

Формула таблицы

{type}_{level}_{entity}[_{instance}]

crm_app_users          ← CRM, приложение, пользователи
crm_prj_clients        ← CRM, проект, клиенты
pir_prj_orders_retail  ← Пиротехника, заказы, розница

Коды типов

Уровни данных

Колонки

snake_case, единственное число
✅ first_name, order_id, created_at
❌ FirstName, orderId, createdAt

Системные поля в каждой таблице:

Имена баз данных

{system}_{base}

dev_main      ← основная БД dev-pro
prd_main      ← продакшен
dev_archive   ← архивные данные

$INFRASTRUCTURE

S3 бакеты

{org}-{purpose}

beget-s3      ← данные проектов ($DATASPACE)
beget-infra   ← бэкапы ($BACKUPSPACE)

DNS и субдомены

{service}.{domain}

docs.0kt.ru      ← документация
api.0kt.ru       ← API
admin.0kt.ru     ← администрирование

Docker образы

{type}-{name}:{version}

nginx-proxy:1.2.0
mcrm-app:2.1.0
nocodb:latest

Docker контейнеры

Nginx конфиги

{домен}              ← crm.0kt.ru
api.{домен}          ← api.crm.0kt.ru
{тип}.{домен}        ← piro.0kt.ru

Git ветки

main              ← основная
feature/{name}    ← новая функциональность
fix/{name}        ← исправление
release/{version} ← релиз

v{major}.{minor}.{patch}   ← теги релизов

Переменные окружения

UPPER_SNAKE_CASE

APP_*        ← настройки приложения
DB_*         ← база данных
S3_*         ← объектное хранилище
TG_*         ← Telegram
OZON_*       ← Ozon API

Systemd сервисы

{type}.service           ← mcrm.service
{type}-worker.service    ← mcrm-worker.service
{type}-{task}.timer      ← pir-sync.timer

Redis ключи

{namespace}:{entity}:{id}:{field}

user:123:session
cache:products:list
lock:import:ozon
queue:tasks:pending

Типы компонентов и сервисов: → typology-components.md, typology-service-types.md

CHANGELOG

2026-03-30 — v1.0.0

• Создан на основе reform-naming-arch как объединение трёх стандартов
• Добавлен раздел $INFRASTRUCTURE: Nginx конфиги
• Роли: добавлены .draft, .idea, .task, .ai, .tpl, .spec, .data, .cache; добавлена колонка Статус
• Форматы: добавлен .yml как вариант совместимости
• Конфиденциальные: добавлен .credentials.md
• БД коды: полный список — crm, mrk, pir, lid, ozn, anl, doc, tsk, sys (anl/doc/tsk — новые)
• Язык: только латиница везде в $WORKSPACE без исключений
• $DATASPACE: media/ — папка внутри проекта, не отдельная зона
• Обоснования: HTML-комментарии к каждому разделу

Версия: 1.0.0
Статус: active
Владелец: architect
Заменяет: naming-workspace.md v3.2.0, naming-dataspace.draft.md v0.1.0, naming-database.md v1.0.0

5. ДОКУМЕНТ 2: typology-components.md

Путь: architect/standards/typology/typology-components.md
Тип: standard | Аспект: typology | Статус: active (после миграции)
Извлечено из: naming-workspace.md v3.2.0

Содержимое typology-components.md

type: standard
aspect: typology
title: "Типология компонентов платформы"
version: 1.0.0
date: 2026-03-30
status: active
owner: architect
source: naming-workspace.md v3.2.0 (extracted)

Типология компонентов платформы

ОБЛАСТЬ ПРИМЕНЕНИЯ

Стандарт описывает типы компонентов платформы: что существует, как классифицируется, как обозначается.

Не описывает:
- Как называть компоненты → naming-platform.md
- Как устроена папочная структура → structure-workspace.md

КОНЦЕПЦИЯ

INSTANCE → COMPONENT → SERVICE

@ ПАПКИ — ДВА РЕЖИМА

@name          — категория / классификатор (без точки)
  projects/org/@biz-lideravto/
  @templates/@org/
  @templates/@mkt/           ← категория внутри категории — допустимо

@name.type     — компонент платформы (с точкой)
  infra/@md-viewer.service/
  system/@projector.agent/
  library/@utils.lib/

@name.qualifier.type   — компонент с уточнением (квалификаторы слева)
  @lider.drupal.web/         ← Drupal веб-приложение lider
  @ozon.import.connector/    ← коннектор импорта Ozon
  @admin.auth.service/       ← сервис авторизации admin
  Правило: тип — крайний правый; квалификаторы добавляются левее типа.

Отличие .name/ от @name.type/:
- .queue/, .monitor/, .claude/ — встроены в workspace, не деплоятся отдельно
- @name.type/ — деплоится и управляется как независимая единица

Специальные префиксы папок — только два: . и @. Подчёркивания не используются.

ТИПЫ КОМПОНЕНТОВ

Инфраструктура

Приложения

AI и данные

Интеграции и инструменты

СТРУКТУРА КОМПОНЕНТА

Стандартные подпапки @name.type/:

@name.type/
├── CLAUDE.md        ← навигатор (если есть нюансы)
├── index.yaml       ← зависимости компонента
├── scripts/         ← скрипты
├── config/          ← конфиги
├── docs/            ← документация
└── src/             ← исходный код (если есть)

Структура компонента-агента:

system/@projector.agent/
├── AI.md            ← определение агента: роль, правила, протоколы
├── CLAUDE.md        ← навигатор папки (короткий)
└── index.yaml       ← зависимости

КАРТА ИНСТАНСОВ PLATFORM 2.0

Instance: mama           ← закрыт, источник истины
└── @mama.registry

Instance: papa           ← единственный публичный вход
└── @papa.gateway

Instance: projector      ← управление проектами
├── @projector.agent
└── @scheduler.service

Instance: worker         ← production окружение
├── @app.service
├── @postgres.db
└── @redis.cache

Instance: llm            ← языковые модели
└── @ollama.model

Instance: backup         ← резервное хранилище
└── @backup.storage

Instance: data           ← MDM / каталоги
└── @catalog.data

Instance: knowledge      ← база знаний / wiki
└── @wiki.knowledge

CHANGELOG

2026-03-30 — v1.0.0

• Создан: извлечён из naming-workspace.md v3.2.0 (Части 3 и частично 4)
• Добавлены обоснования HTML-комментариями
• Уточнена семантика @ двух режимов и .vs@ различие

Версия: 1.0.0
Статус: active
Владелец: architect
Источник: naming-workspace.md v3.2.0

6. ДОКУМЕНТ 3: process-platform-change.md — дополнение

Путь: architect/standards/process/process-platform-change.draft.md
Изменение: добавить секцию РЕФОРМА после секции СТАДИИ

Добавить секцию:

РЕФОРМА — особый тип изменения

Когда использовать реформу (а не обычный .draft):
- Изменение затрагивает 3+ файлов
- Файлы логически связаны (одна область: именование, структура, процесс)
- Нужно обсудить изменения как единое целое до применения

Структура реформенного документа:

## 1. МАНИФЕСТ
- Цель и обоснование
- Архивируем: список файлов → arh/
- Создаём: новые файлы
- Обновляем: изменения в существующих
- Не трогаем

## 2. АНАЛИЗ И ТОМОГРАФИЯ
- Проблемы текущего состояния
- Соответствие концепции платформы
- Томография финального результата (5 измерений)

## 3. ЧЕКЛИСТ МИГРАЦИИ
[ ] пункты

## 4. ДОКУМЕНТ 1: name.md
[полный контент нового файла]

## 5. ДОКУМЕНТ N: ...

Именование: reform-{area}.draft.md

reform-naming-arch.draft.md
reform-agent-system.draft.md

После применения: реформенный документ → arh/reform-{area}-YYYY-MM-DD.md

Правило: один реформенный документ — одна связанная область. Не смешивать несвязанные реформы.

7. ПОПРАВКИ В ДРУГИЕ ДОКУМЕНТЫ

PRINCIPLES.md — Принцип 8 (Жизненный цикл)

Файл: architect/concept/PRINCIPLES.md
Статус поправки: согласована (К-1)

Что изменить: Принцип 8 показывает library/_draft/ и library/_beta/ как этапы жизненного цикла компонентов библиотеки. Эта конвенция заменена.

Заменить на:

Жизненный цикл компонентов:

git branch feature/name   →   index.yaml: status: beta   →   status: stable
(в разработке)                 (тестирование)                  (продакшен)

Жизненный цикл документов:

name.idea.md  →  name.draft.md  →  name.md  →  arh/name-YYYY-MM-DD.md

Обоснование: _draft/ папки нарушают запрет underscore в $WORKSPACE и дублируют то, что git branches уже решают лучше. Статус компонента — в метаданных (index.yaml), не в файловой системе.

format-document.md — убрать .ai.md

Файл: architect/standards/format/format-document.md
Статус поправки: согласована (В-5)

Что изменить: в разделе "Расширения Markdown" строку:

.ai.md   - AI-агент (промпт для Claude)

Заменить на:

AI.md         — Определение агента: роль, правила, протоколы (только в @name.agent/)
name.ai.md    — Документ / код предназначенный для чтения AI-агентом (.ai — роль)

Различие:
- AI.md — UPPERCASE, служебный файл в корне @name.agent/, аналог CLAUDE.md. Одно на компонент.
- name.ai.md — lowercase, роль .ai в формуле [aspect]-[object].[role].format. Инструкция или промпт для AI.

typology-document-types.md — убрать устаревшие форматы имён

Файл: architect/standards/typology/typology-document-types.md
Статус поправки: согласована (В-6)

Что изменить:
- Стандарт → UPPER_CASE.md → исправить на kebab-case.md
- AI-агент → kebab-case.ai.md → исправить на AI.md (только в @name.agent/)

naming-platform.md — добавить ссылку на typology-service-types.md

Файл: внутри реформы — раздел $INFRASTRUCTURE
Статус поправки: согласована (М-9)

Что добавить: в конец раздела $INFRASTRUCTURE строку:

**Типы сервисов Docker:** → [typology-service-types.md](../typology/typology-service-types.md)

Обоснование: раздел описывает именование Docker-образов и контейнеров, но типы сервисов (что такое .app, .service, .agent) описаны в typology-service-types.md. Без ссылки читатель не знает куда идти за классификацией.

8. ОТКРЫТЫЕ ВОПРОСЫ

• [ ] Где хранить реформенные документы в процессе разработки? Сейчас — рядом с основными файлами. Возможно нужна папка architect/management/reforms/?
• [ ] Нужен ли .reform как роль файла (аналог .draft)? Или reform-* как префикс имени достаточно?
• [ ] typology-components.md — в typology/ или рядом с naming в naming/?

CHANGELOG

2026-03-30 — v0.1.0

• Создан реформенный черновик
• Томография naming-platform.draft.md: 14 проблем выявлено, все закрыты
• naming-platform.md: чистое именование без structure/typology
• typology-components.md: каталог компонентов, карта инстансов, @ режимы
• process-platform-change.md: добавлен паттерн реформы

Версия: 0.1.0 (черновик)
Статус: draft
Владелец: architect