Kit.Db/docs/tz.md

ТЗ — Формирование проекта для БД

Общее описание

На основании файловой структуры (см. architecture.md) формируется проект для конкретной базы данных. Каждый проект — автономная единица с собственными настройками, исходниками и документацией.

---

Шаблон структуры

Kit.Db/
│
├── rules/                          # Правила для LLM по движкам
│   ├── common/                     #   Общие правила для всех СУБД
│   │   └── ...
│   ├── pg/                         #   Правила PostgreSQL
│   │   └── db-project-rule.md
│   └── sqlite/                     #   Правила SQLite
│       └── db-project-rule.md
│
├── skills/                         # LLM промпты (описания таблиц, функций)
│   └── ...
│
└── projects/                       # Проекты БД
    │
    ├── pg/                         # ── PostgreSQL проекты ──
    │   │
    │   └── kit_auth_pg/            # Проект: БД авторизации
    │       │
    │       ├── readme.md           # Описание БД
    │       │
    │       ├── settings/           # Настройки подключения
    │       │   └── connection.json
    │       │
    │       ├── auth/               # Модуль: авторизация
    │       │   ├── tables/         #   DDL таблиц
    │       │   │   ├── user.psql
    │       │   │   ├── cabinet.psql
    │       │   │   └── user_cabinet.psql
    │       │   │
    │       │   ├── functions/      #   SQL функции
    │       │   │   ├── user_select_by_ids/
    │       │   │   │   └── user_select_by_ids.psql
    │       │   │   └── user_create/
    │       │   │       └── user_create.psql
    │       │   │
    │       │   ├── scripts/        #   Произвольные скрипты
    │       │   │   └── seed_roles.sql
    │       │   │
    │       │   ├── init/           #   Инициализация
    │       │   │   └── create_schema.psql
    │       │   │
    │       │   ├── deploy/         #   Миграции
    │       │   │   ├── 2026-07-08_user-select-by-ids.sql
    │       │   │   └── 2026-07-09-user-seed-merge.sql
    │       │   │
    │       │   ├── auth.psql       #   Точка входа модуля
    │       │   └── auth.post-deploy.psql
    │       │
    │       └── _docs/              # Документация проекта
    │           ├── diagrams/
    │           ├── openapi.yaml
    │           └── architecture.md
    │
    └── sl3/                        # ── SQLite проекты ──
        │
        └── kit_example_sl3/        # Проект: пример
            │
            ├── readme.md
            ├── settings/
            │   └── connection.json
            │
            ├── main/               # Модуль: основной
            │   ├── tables/
            │   ├── scripts/
            │   ├── init/
            │   ├── deploy/
            │   └── main.sql
            │
            └── _docs/
                ├── diagrams/
                ├── openapi.yaml
                └── architecture.md

---

Структура проекта

Каждый проект БД создаётся по пути:

projects/{engine}/{project_name}/

Где:

• {engine} — тип СУБД (pg, sqlite, mysql, mssql и т.д.)
• {project_name} — имя проекта в формате имя_БД_движок (например kit_auth_pg)

---

Обязательные компоненты проекта

1. readme.md

Описание проекта:

• Назначение БД
• Движок и версия
• Краткое описание модулей
• Связи с другими БД (если есть)

2. settings/

Папка с настройками подключения:

• connection.json — параметры подключения к БД (хост, порт, БД, пользователь)

Пример connection.json:

{
  "host": "localhost",
  "port": 5432,
  "database": "kit_auth",
  "username": "postgres",
  "password": ""
}

3. Модули (auth/, payments/, и т.д.)

Каждый модуль содержит:

• tables/ — DDL-скрипты таблиц
• functions/ — SQL-функции и хранимые процедуры
• scripts/ — SQL-скрипты (миграции, seed-данные, утилиты)
• init/ — скрипты инициализации (создание схемы, начальные данные)
• deploy/ — инфраструктура развёртывания (docker-compose, bat, sh)
• {module}.psql — главный файл модуля (точка входа)

4. _docs/

Документация проекта:

• diagrams/ — диаграммы (ER, зависимости, потоки)
• openapi.yaml — OpenAPI спецификация (если БД предоставляет API)
• architecture.md — описание архитектуры конкретной БД

---

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

• Папки — в нижнем регистре, через подчёркивание: kit_auth_pg
• SQL-файлы — в нижнем регистре: create_users_table.sql
• Функции — по шаблону: {module}_{action}.sql (например auth_get_user_by_id.sql)
• Таблицы — по шаблону: {module}_{entity}.sql (например auth_users.sql)

---

Правила (rules/)

При формировании проекта LLM использует правила из:

• rules/common/ — общие правила для всех СУБД
• rules/{engine}/ — правила для конкретного движка

Правила определяют:

• Стиль написания SQL
• Шаблоны описания таблиц и функций
• Формат комментариев
• Стандарты именования

---

Skills

При формировании проекта LLM использует промпты из skills/ для:

• Генерации описаний таблиц
• Генерации описаний функций
• Формирования документации
• Создания диаграмм

---

Порядок создания проекта

1. Создать папку проекта projects/{engine}/{project_name}/
2. Создать readme.md с описанием
3. Создать settings/connection.json
4. Для каждого модуля БД создать папку модуля с подпапками (tables, functions, scripts, init, deploy)
5. Создать _docs/ с диаграммами и спецификацией
6. Заполнить SQL-файлы на основании требований
7. Проверить структуру на соответствие шаблону