DM-ARCHITECTURE.md

Версия: 1.0.0
Дата: 2026-02-17
Статус: specification

КОНТЕКСТ

Document Management System для платформы — управление документами проектов с поддержкой:
- Шаблонов документов (4 уровня наследования)
- Автоматической сборки проектной документации
- Версионирования через Git
- Валидации структуры

Эволюция:
1. Level 1: DMS для одного проекта (ЛАН) — ручная работа, тестирование подхода
2. Level 2: DMS для нескольких проектов — универсальные шаблоны, автоматизация
3. Level 3: DMS как продукт платформы — полная автоматизация, CLI

1. ХРАНЕНИЕ ФАЙЛОВ (Storage Layer)

1.1 Стратегия хранения

Тип данных	Где хранится	Версионирование	Пример
Документы	WORKSPACE	Git	.md, .yaml
Код	WORKSPACE	Git	.py, .js, .sh
Данные	DATASPACE	Без Git	.xlsx, .csv
Бинарники	DATASPACE	Без Git	images, pdf
Бэкапы	/mnt/beget-infra	Без Git	.tar.gz

WORKSPACE=/opt/claude-workspace    # Git, код, документы
DATASPACE=/mnt/beget-s3           # S3, бинарные данные

1.2 Компоненты хранения

FileStorage (library/storages/filesystem.py)

Назначение: Абстракция для работы с файлами (WORKSPACE + DATASPACE)

Возможности:
- Чтение/запись файлов
- Проверка существования
- Список файлов (glob patterns)
- Автоматический выбор WORKSPACE vs DATASPACE по типу файла

class FileStorage(BaseStorage):
    def read(self, path: str) -> str
    def write(self, path: str, content: str) -> None
    def exists(self, path: str) -> bool
    def list(self, pattern: str) -> List[str]
    def delete(self, path: str) -> None

Размер: ~200 строк
Оценка создания: 30 минут

GitStorage (library/storages/git.py)

Назначение: Версионирование документов через Git

Возможности:
- Commit изменений
- Просмотр истории
- Diff между версиями
- Restore предыдущих версий
- Tags для релизов

class GitStorage:
    def commit(self, files: List[str], message: str) -> str
    def history(self, file: str) -> List[Commit]
    def diff(self, file: str, version1: str, version2: str) -> str
    def restore(self, file: str, version: str) -> None
    def tag(self, name: str, message: str) -> None

Размер: ~150 строк
Оценка создания: 30 минут

Решение: Использует существующий Git (не создаём свой), обёртка над GitPython или subprocess.

2. СТРУКТУРА ПРОЕКТОВ

2.1 Стандартная структура

projects/org/{project_name}/
├── CLAUDE.md              ← AI-контекст проекта
├── index.yaml             ← Метаданные (id, type, status, tags)
│
├── design/                ← ПРОЕКТИРОВАНИЕ
│   ├── BRIEF.md           ← Краткое описание
│   ├── REQUIREMENTS.md    ← Требования
│   ├── DESIGN.md          ← Дизайн/архитектура
│   └── RESEARCH.md        ← Исследование (опционально)
│
├── management/            ← УПРАВЛЕНИЕ
│   ├── STATUS.md          ← Текущий статус
│   ├── TODO.md            ← Задачи
│   ├── DECISIONS.md       ← Решения
│   ├── CHANGELOG.md       ← История изменений
│   └── TIMELINE.md        ← График (опционально)
│
└── solution/              ← РЕЗУЛЬТАТ
    ├── README.md          ← Описание решения
    ├── code/              ← Код (если применимо)
    ├── config/            ← Конфигурация
    └── docs/              ← Документация решения

2.2 Данные проекта

/mnt/beget-s3/projects/{project_name}/
├── inbox/                 ← Входящие файлы
├── processed/             ← Обработанные данные
├── images/                ← Изображения
├── documents/             ← PDF, DOCX
└── archive/               ← Архив

2.3 Обязательные файлы

3. ШАБЛОНЫ ДОКУМЕНТОВ

3.1 Иерархия шаблонов (4 уровня)

Файл	Обязательный	Создаётся из шаблона
CLAUDE.md	✅ Да	base/CLAUDE.md.tpl
index.yaml	✅ Да	base/index.yaml.tpl
design/BRIEF.md	✅ Да	base/BRIEF.md.tpl
management/STATUS.md	✅ Да	base/STATUS.md.tpl
management/TODO.md	❌ Нет	—
solution/README.md	❌ Нет	Создаётся вручную

architect/templates/
├── base/                  ← Level 0: Универсальные шаблоны
│   ├── CLAUDE.md.tpl
│   ├── index.yaml.tpl
│   ├── BRIEF.md.tpl
│   ├── STATUS.md.tpl
│   └── ...
│
├── domain/                ← Level 1: Домен-специфичные
│   ├── IT.yaml
│   ├── BUSINESS.yaml
│   └── ECOMMERCE.yaml
│
├── class/                 ← Level 2: Класс проекта
│   ├── A.yaml             ← Большие проекты
│   ├── B.yaml             ← Средние проекты
│   └── C.yaml             ← Малые проекты
│
└── solution/              ← Level 3: Решение-специфичные
    ├── CSCART.yaml
    ├── DRUPAL.yaml
    └── FASTAPI.yaml

3.2 Сборка документа с наследованием

base/CLAUDE.md.tpl                 ← Базовая структура
  + domain/ECOMMERCE.yaml          ← Секции для e-commerce
  + class/A.yaml                   ← Секции для больших проектов
  + solution/CSCART.yaml           ← Секции для CS-Cart
  = projects/org/lan/CLAUDE.md     ← Итоговый документ

Механизм наследования:
- extends: — наследование от родителя
- includes: — включение фрагментов
- sections: — добавление/переопределение секций
- variables: — переменные для подстановки

3.3 Формат шаблона

# {project_name} — {project_title}

**Тип:** {project_type}
**Статус:** {status}
**Дата создания:** {created_date}

---

## Что это

{brief_description}

---

{%sections%}

extends: base
sections:
  - name: "Интеграции"
    content: |
      ## Интеграции
      - Маркетплейсы (OZON, WB)
      - Платёжные системы
      - CRM

Сборка: DM объединяет базовый шаблон + секции из domain/class/solution.

4. ROADMAP СОЗДАНИЯ (снизу вверх)

L3: Инфраструктура (Foundation)

Порядок 1: FileStorage

Файл: library/storages/filesystem.py
Размер: ~200 строк
Оценка: 30 минут

Что создаёт:
- Класс FileStorage(BaseStorage)
- Методы: read, write, exists, list, delete
- Логика выбора WORKSPACE vs DATASPACE

Порядок 2: GitStorage

Файл: library/storages/git.py
Размер: ~150 строк
Оценка: 30 минут

Что создаёт:
- Класс GitStorage
- Методы: commit, history, diff, restore, tag
- Обёртка над Git CLI или GitPython

L4: Document Management

Порядок 3: Templates Registry

Файл: system/dm/templates.py
Размер: ~150 строк
Оценка: 30 минут

Что создаёт:
- Класс TemplateRegistry
- Поиск шаблонов (base/domain/class/solution)
- Загрузка YAML/templates
- Валидация шаблонов

Порядок 4: Document Assembly

Файл: system/dm/assembly.py
Размер: ~200 строк
Оценка: 45 минут

Что создаёт:
- Класс DocumentAssembler
- Сборка с наследованием (extends/includes)
- Подстановка переменных
- Объединение секций

Порядок 5: Validation

Файл: system/dm/validation.py
Размер: ~100 строк
Оценка: 20 минут

Что создаёт:
- Класс ProjectValidator
- Проверка обязательных файлов
- Валидация структуры папок
- Проверка форматов (YAML, MD)

L5: Project Management

Порядок 6: Lifecycle

Файл: system/pm/lifecycle.py
Размер: ~300 строк
Оценка: 60 минут

Что создаёт:
- Класс ProjectLifecycle
- 15 фаз проекта
- Переходы между фазами
- Проверка gate перед переходом

Порядок 7: Gates

Файл: system/pm/gates.py
Размер: ~150 строк
Оценка: 30 минут

Что создаёт:
- Класс StageGate
- Критерии прохождения фаз
- Чеклисты для каждой фазы
- Валидация готовности

Порядок 8: CLI

Файл: system/pm/cli.py
Размер: ~200 строк
Оценка: 40 минут

Что создаёт:
- CLI команды: create, status, next, validate
- Интеграция с DM
- Вывод статуса проекта

Общая оценка

5. ЭВОЛЮЦИЯ DMS

Level 1: Для одного проекта (ЛАН)

Уровень	Компоненты	Время
L3 Infrastructure	FileStorage + GitStorage	60 мин
L4 Document Management	Templates + Assembly + Validation	95 мин
L5 Project Management	Lifecycle + Gates + CLI	130 мин
ИТОГО	8 компонентов	~5 часов

Цель: Проверить подход на реальном проекте

Что делаем:
1. Создать проект ЛАН ВРУЧНУЮ из шаблонов
2. Пройти фазы 0-2 (Intake → Understanding → Research)
3. Зафиксировать что работает, что нет
4. Доработать шаблоны

Результат:
- Рабочий проект projects/org/lan/
- Протестированные шаблоны
- Понимание какие документы реально нужны

Level 2: Для нескольких проектов

Что делаем:
1. Создать универсальные шаблоны в architect/templates/base/
2. Добавить domain/class/solution шаблоны
3. Реализовать DocumentAssembler для автоматической сборки
4. Создать 2-3 тестовых проекта разных типов

Результат:
- Шаблоны в architect/templates/ (4 уровня)
- Автоматическая сборка документов
- DM может создать проект любого типа

Level 3: Как продукт платформы

Что делаем:
1. Реализовать PM (lifecycle, gates, CLI)
2. Интегрировать DM + PM
3. CLI для работы с проектами
4. Документация для пользователей

Результат:
- system/pm/ — полноценный PM
- system/dm/ — полноценный DM
- CLI команды для создания и управления проектами
- Другие проекты могут использовать

6. ТЕХНИЧЕСКИЕ РЕШЕНИЯ

6.1 FileStorage vs DMS

Решение: FileStorage — отдельный компонент в library/storages/

Обоснование:
- ✅ Переиспользуемый (не только для DM, но и для других компонентов)
- ✅ Уровень L3 (инфраструктура), DM уровень L4
- ✅ Следует паттерну library/storages/ (postgres, cache)

6.2 Git интеграция

Решение: GitStorage как обёртка над существующим Git

Обоснование:
- ✅ Git уже установлен и используется
- ✅ Workspace уже в Git-репозитории
- ✅ Не нужно реализовывать версионирование с нуля
- ✅ GitStorage — тонкая обёртка (150 строк)

Не создаём свой Git, используем существующий.

6.3 Формат шаблонов

Решение: .tpl для базовых шаблонов, .yaml для дополнений

Обоснование:
- ✅ Базовый шаблон — полноценный .md файл с переменными
- ✅ Domain/class/solution — YAML с секциями для добавления
- ✅ Простота редактирования вручную
- ✅ Понятная структура наследования

6.4 Валидация проектов

Решение: ProjectValidator проверяет структуру + обязательные файлы

Обоснование:
- ✅ Гарантирует что проект соответствует стандарту
- ✅ Используется PM для проверки gate
- ✅ Можно запустить вручную для проверки

7. ИНТЕГРАЦИЯ С СУЩЕСТВУЮЩЕЙ ПЛАТФОРМОЙ

7.1 Library структура

library/storages/
├── base.py              ← Существует (BaseRepository)
├── postgres/            ← Существует
├── cache/               ← Существует
├── filesystem.py        ← НОВЫЙ (FileStorage)
└── git.py               ← НОВЫЙ (GitStorage)

7.2 System структура

system/
├── dm/                  ← НОВЫЙ компонент
│   ├── CLAUDE.md
│   ├── index.yaml
│   ├── DM-ARCHITECTURE.md  ← Этот документ
│   ├── templates.py
│   ├── assembly.py
│   └── validation.py
│
└── pm/                  ← НОВЫЙ компонент
    ├── CLAUDE.md
    ├── index.yaml
    ├── WIP.md
    ├── lifecycle.py
    ├── gates.py
    └── cli.py

7.3 Architect структура

architect/templates/
├── base/                ← НОВЫЙ (универсальные шаблоны)
│   ├── CLAUDE.md.tpl
│   ├── index.yaml.tpl
│   ├── BRIEF.md.tpl
│   └── STATUS.md.tpl
│
├── domain/              ← НОВЫЙ (домен-специфичные)
│   ├── IT.yaml
│   └── ECOMMERCE.yaml
│
├── class/               ← НОВЫЙ (классы проектов)
│   ├── A.yaml
│   └── B.yaml
│
└── solution/            ← НОВЫЙ (решения)
    ├── CSCART.yaml
    └── DRUPAL.yaml

8. СЛЕДУЮЩИЕ ШАГИ

Шаг 1: Инфраструктура (60 мин)

Шаг 2: DM базовые компоненты (95 мин)

Шаг 3: Базовые шаблоны (90 мин)

Шаг 4: Тест на ЛАН (120 мин)

Шаг 5: PM компоненты (130 мин)

Шаг 6: Автоматизация (60 мин)

9. КРИТЕРИИ УСПЕХА

Level 1 успешен если:

Level 2 успешен если:

Level 3 успешен если:

СВЯЗИ