architect/standards/6-naming/naming-database.md

type: standard
aspect: naming
title: "Стандарт именования таблиц"
version: 1.0.0
date: 2026-02-19
status: active

Стандарт именования таблиц

Версия: 2.0.0
Дата: 2025-12-23
Статус: active

Принцип

Все проекты создаются в общей базе данных. Каждая таблица имеет два префикса:

{тип}_{уровень}_{сущность}

Где:
  тип     = 3 буквы, код типа проекта (crm, mrk, pir...)
  уровень = app | sol | prj | usr
  сущность = имя таблицы (snake_case)

Примеры:

crm_app_users        ← CRM, приложение, пользователи
crm_prj_clients      ← CRM, проект, клиенты
pir_prj_orders       ← Пиротехника, проект, заказы
mrk_sol_campaigns    ← Маркетинг, решение, кампании

Общая база данных

Все проекты платформы хранятся в одной базе NocoDB. Разделение — через префиксы.

┌─────────────────────────────────────────────────────────────────┐
│                    ОБЩАЯ БАЗА ДАННЫХ                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  crm_app_users          ← Пользователи CRM                     │
│  crm_prj_clients        ← Клиенты (проект)                      │
│  crm_prj_orders         ← Заказы (проект)                       │
│                                                                 │
│  mrk_app_settings       ← Настройки маркетинга                  │
│  mrk_sol_campaigns      ← Кампании (решение)                    │
│  mrk_prj_leads          ← Лиды (проект)                         │
│                                                                 │
│  pir_prj_products       ← Товары пиротехники                    │
│  pir_prj_categories     ← Категории пиротехники                 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Типы проектов (первый префикс)

3-буквенный код типа проекта:

Код Тип Описание
crm CRM Управление клиентами
mrk Marketing Маркетинг, рассылки
pir Pirotehnika Пиротехника (бизнес)
lid LiderAvto Автозапчасти (бизнес)
ozn Ozon Интеграция с Ozon
anl Analytics Аналитика
doc Documents Документы
tsk Tasks Задачи
sys System Системные

Новый тип: Добавить в этот реестр при создании нового проекта.

Уровни данных (второй префикс)

Код Уровень Владелец Что хранится
app Application Приложение Пользователи, настройки, логи
sol Solution Решение Справочники, шаблоны, конфиги
prj Project Проект Бизнес-данные: клиенты, заказы
usr User Пользователь Персональные настройки 
┌─────────────────────────────────────────────────────────────────┐
│                      УРОВНИ ДАННЫХ                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  {тип}_app_*    Приложение     Общие для типа проекта          │
│       ↓                                                         │
│  {тип}_sol_*    Решение        Справочники, конфигурация       │
│       ↓                                                         │
│  {тип}_prj_*    Проект         Бизнес-данные клиента           │
│       ↓                                                         │
│  {тип}_usr_*    Пользователь   Персональные данные              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Формат имени таблицы

Стандартный формат (всегда)

{тип}_{уровень}_{сущность}

Примеры:
  crm_app_users           ← CRM, приложение, пользователи
  crm_sol_funnel_stages   ← CRM, решение, этапы воронки
  crm_prj_clients         ← CRM, проект, клиенты
  crm_usr_preferences     ← CRM, пользователь, настройки

  pir_prj_products        ← Пиротехника, проект, товары
  pir_prj_orders          ← Пиротехника, проект, заказы

  mrk_sol_templates       ← Маркетинг, решение, шаблоны
  mrk_prj_campaigns       ← Маркетинг, проект, кампании

Мульти-инстанс (несколько проектов одного типа)

Если нужно несколько инстансов одного типа — добавляем суффикс:

{тип}_{уровень}_{сущность}_{инстанс}

Примеры:
  crm_prj_clients_spb      ← Клиенты CRM для СПб
  crm_prj_clients_msk      ← Клиенты CRM для Москвы
  pir_prj_orders_retail    ← Заказы розница
  pir_prj_orders_opt       ← Заказы опт

Таблицы по уровням

APP (Приложение)

Общие для типа проекта: пользователи, настройки, логи.

Таблица Назначение
crm_app_users Пользователи CRM
crm_app_roles Роли и права
crm_app_sessions Сессии авторизации
crm_app_settings Настройки приложения
crm_app_logs Логи действий
sys_app_integrations Интеграции (системные)

SOL (Решение)

Справочники и конфигурация для типа бизнеса.

Таблица Назначение
crm_sol_funnel_stages Этапы воронки
crm_sol_segments Правила сегментов
crm_sol_scenarios Сценарии обзвона
mrk_sol_templates Шаблоны рассылок
pir_sol_categories Категории пиротехники

PRJ (Проект)

Бизнес-данные конкретного проекта/клиента.

Таблица Назначение
crm_prj_clients Клиенты
crm_prj_orders Заказы
crm_prj_tasks Задачи
crm_prj_messages Сообщения
mrk_prj_campaigns Кампании
pir_prj_products Товары пиротехники

USR (Пользователь)

Персональные данные пользователя системы.

Таблица Назначение
crm_usr_preferences Настройки UI
crm_usr_favorites Избранное
crm_usr_history История действий
crm_usr_filters Сохранённые фильтры

Система наименований (полная)

Иерархия сущностей

┌─────────────────────────────────────────────────────────────────┐
│                    ИЕРАРХИЯ НАИМЕНОВАНИЙ                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  СИСТЕМА      → Платформа целиком (dev-pro, production)        │
│      ↓                                                          │
│  СЕРВЕР       → Физический/виртуальный сервер                  │
│      ↓                                                          │
│  БАЗА         → База данных NocoDB                             │
│      ↓                                                          │
│  ТИП          → Тип проекта (crm, mrk, pir)                    │
│      ↓                                                          │
│  УРОВЕНЬ      → app / sol / prj / usr                          │
│      ↓                                                          │
│  ИНСТАНС      → Конкретный экземпляр (spb, msk, retail)        │
│      ↓                                                          │
│  ТАБЛИЦА      → Таблица с данными                              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Системы

Система Код Назначение
dev-pro dev Основная рабочая среда
production prd Продакшен (когда будет)
staging stg Тестирование
local loc Локальная разработка

По умолчанию: dev (dev-pro)

Серверы

Сервер Код IP Назначение
dev-pro dp1 91.218.142.168 Основной
(резерв) dp2 — Резервный

Формат hostname: {система}-{номер} → dev-pro-1

Базы данных

База Код Назначение
main main Основная (все проекты)
archive arch Архивные данные
analytics anlt Аналитика (отдельно)

По умолчанию: main — все новые проекты создаются здесь.

Формат: {система}_{база} → dev_main, prd_main

Инстансы (экземпляры проектов)

Когда нужно несколько экземпляров одного типа:

Инстанс Код Пример
По умолчанию (без суффикса) crm_prj_clients
По городу spb, msk crm_prj_clients_spb
По типу retail, opt pir_prj_orders_retail
По клиенту acme, beta crm_prj_clients_acme

Полная схема именования

ПОЛНЫЙ ПУТЬ К ТАБЛИЦЕ:

{система}.{база}.{тип}_{уровень}_{сущность}[_{инстанс}]

Примеры:
  dev.main.crm_prj_clients           ← CRM клиенты (основной инстанс)
  dev.main.crm_prj_clients_spb       ← CRM клиенты СПб
  dev.main.pir_prj_orders            ← Пиротехника заказы
  prd.main.crm_prj_clients           ← Продакшен CRM клиенты

Конфигурация по умолчанию

# Дефолты для новых проектов
defaults:
  system: dev          # dev-pro
  database: main       # основная база
  instance: null       # без суффикса инстанса

# Результат: {тип}_{уровень}_{сущность}
# Пример: crm_prj_clients

Docker-контейнеры

Контейнер Формат имени Пример
База данных {тип}-db nocodb-db, pirofey-db
Приложение {тип}-app mcrm-app, seller1-app
Сервис {тип}-{сервис} mcrm-whatsapp, pir-sync

Systemd-сервисы

Сервис Формат имени Пример
Приложение {тип}.service mcrm.service
Воркер {тип}-worker.service mcrm-worker.service
Cron-задача {тип}-{задача}.timer pir-sync.timer

Nginx-конфиги

Конфиг Формат имени Пример
Сайт {домен} crm.0kt.ru
API api.{домен} api.crm.0kt.ru
Субдомен {тип}.{домен} piro.0kt.ru

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

1. Сущности (entity)

snake_case, единственное число для простых, множественное для коллекций

✅ Правильно:
   prj_clients
   prj_order_items
   app_user_role

❌ Неправильно:
   prj_Client
   prj_orderItems
   app_userRole

2. Связующие таблицы

{level}_{entity1}_{entity2}

Примеры:
   prj_client_tags        ← связь клиентов и тегов
   app_user_roles         ← связь пользователей и ролей

3. Системные поля

Каждая таблица содержит:

Поле Тип Назначение
id UUID/INT Первичный ключ
created_at TIMESTAMP Дата создания
updated_at TIMESTAMP Дата обновления
created_by UUID Кто создал (app_users.id)

Миграция существующих таблиц

Текущие таблицы → Новые имена

Старое имя Новое имя Уровень
Clients prj_clients Project
Tasks prj_tasks Project
Orders prj_orders Project
Messages prj_messages Project
Users app_users App
Settings app_settings App

Скрипт миграции

-- Переименование таблиц в NocoDB
ALTER TABLE "Clients" RENAME TO "prj_clients";
ALTER TABLE "Tasks" RENAME TO "prj_tasks";
ALTER TABLE "Orders" RENAME TO "prj_orders";

Мульти-тенант

Для нескольких проектов в одной БД используем полный формат:

prj_{solution}_{project}_{entity}

Примеры (решение piro, два проекта):
  prj_piro_salut_clients      ← Клиенты "Салюты СПб"
  prj_piro_moscow_clients     ← Клиенты "Пиро Москва"

Или отдельные базы/схемы:

База: mcrm_salut
  prj_clients
  prj_orders

База: mcrm_moscow
  prj_clients
  prj_orders

Конфигурация в YAML

Solution config

# solutions/piro-crm/config.yaml
database:
  prefix:
    app: app_
    solution: sol_
    project: prj_
    user: usr_

Entity config

# solutions/piro-crm/entities/client.yaml
entity: client
table: clients          # Итоговое имя: prj_clients
level: project          # Определяет префикс

Визуализация

NocoDB Base: mcrm_production
├── app_users
├── app_roles
├── app_settings
├── app_logs
│
├── sol_funnel_stages
├── sol_segments
├── sol_categories
│
├── prj_clients          ← Основные бизнес-данные
├── prj_orders
├── prj_tasks
├── prj_messages
│
└── usr_preferences

Проверка соответствия

# Скрипт проверки именования таблиц
python3 system/scripts/check_table_names.py

# Вывод:
# ✅ prj_clients - OK
# ✅ app_users - OK
# ❌ Clients - должно быть prj_clients
# ❌ UserSettings - должно быть usr_settings

Ссылки

Версия: 1.0.0