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

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

На основании файловой структуры (см. 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`:

```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. Проверить структуру на соответствие шаблону