SYNC MODE — Режим синхронизации

design/ARCHITECTURE.md → устарел (написано 2 месяца назад)
solution/mvp/app.py    → изменился (новые модули, БД)
management/CHANGELOG.md → не обновлялся
README.md              → Quick Start не работает

# Структура приложения
tree solution/mvp/ -L 2

# Зависимости
cat solution/mvp/requirements.txt

# БД модели
grep -r "class.*Model" solution/mvp/ --include="*.py"

# API endpoints (если FastAPI)
grep -r "@app\." solution/mvp/ --include="*.py"

# Страницы (если Streamlit)
ls -la solution/mvp/pages/

# Конфигурация
cat solution/mvp/.env.example

# PROJECT.md — scope, технологии
cat design/PROJECT.md

# ARCHITECTURE.md — архитектурные решения
cat design/ARCHITECTURE.md

# MODELS.md — модели данных
cat design/MODELS.md

# API.md — API спецификация
cat design/API.md

# README.md — Quick Start
cat management/README.md

# Sync Audit Report — {project}
**Дата:** 2025-11-10

## ✅ Актуально

### PROJECT.md
- Scope: ✅ Соответствует коду
- Технологии: ✅ Streamlit, SQLAlchemy

### README.md
- Quick Start: ✅ Команды работают

## ⚠️ Частично устарело

### ARCHITECTURE.md
- ADR-001: ✅ Актуален
- ADR-002: ⚠️ Написано "используем SQLite", но код использует PostgreSQL
- Отсутствует: ADR про переход на PostgreSQL

### MODELS.md
- User model: ✅ Соответствует
- Order model: ⚠️ В коде добавлено поле `delivery_address`, в docs нет
- Отсутствует: Product model (есть в коде)

## ❌ Критически устарело

### API.md
- ❌ Документация пустая, но в коде есть 10+ endpoints

### CHANGELOG.md
- ❌ Последняя запись: 2025-09-15
- ❌ Не отражены изменения за 2 месяца

## 📊 Статистика

- Актуальность: 50%
- Требует обновления: 5 документов
- Отсутствует: 2 документа

## 🔄 План действий

1. Добавить ADR-003 про переход на PostgreSQL
2. Обновить MODELS.md (добавить поля, Product model)
3. Создать API.md с документацией endpoints
4. Восстановить CHANGELOG.md за последние 2 месяца
5. Проверить README.md Quick Start

## ⏱️ Время: ~2-3 часа

# SQLAlchemy models
grep -A 20 "class.*Base" solution/mvp/database/models.py

# Или Pydantic models
grep -A 10 "class.*BaseModel" solution/mvp/models.py

# Для SQLAlchemy
from database.models import Base
from sqlalchemy.schema import CreateTable
from sqlalchemy import create_engine

engine = create_engine('sqlite:///:memory:')
Base.metadata.create_all(engine)

for table in Base.metadata.sorted_tables:
    print(CreateTable(table).compile(engine))

# Модели данных: {project}

**Последнее обновление:** 2025-11-10

## Схема БД

```sql
CREATE TABLE users (
    id INTEGER PRIMARY KEY,
    email VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    role VARCHAR(50) DEFAULT 'user',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE orders (
    id INTEGER PRIMARY KEY,
    user_id INTEGER REFERENCES users(id),
    status VARCHAR(50) NOT NULL,
    total DECIMAL(10, 2),
    delivery_address TEXT,  -- ← ДОБАВЛЕНО
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE products (  -- ← НОВАЯ ТАБЛИЦА
    id INTEGER PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    price DECIMAL(10, 2) NOT NULL,
    stock INTEGER DEFAULT 0
);

**4. Git commit:**
```bash
git add design/MODELS.md
git commit -m "docs: синхронизирован MODELS.md с кодом"

# Крупные изменения за последние 2 месяца
git log --since="2 months ago" --oneline solution/

# Посмотреть конкретный commit
git show <commit-hash>

### [ADR-003] Переход с SQLite на PostgreSQL

**Дата:** 2025-10-20
**Статус:** Принято
**Заменяет:** ADR-001 (частично)

**Контекст:**
SQLite не подходит для production:
- Проблемы с concurrent writes
- Нет поддержки репликации
- Ограничения на размер БД

**Решение:**
Мигрировать на **PostgreSQL**.

**Обоснование:**
- Production-ready СУБД
- Поддержка concurrent connections
- Поддержка репликации
- Больше типов данных

**Последствия:**

✅ Плюсы:
- Стабильность
- Масштабируемость
- Полноценная СУБД

⚠️ Минусы:
- Нужен отдельный сервер/контейнер
- Сложнее локальная разработка
- Миграция данных

**Миграция:**
1. Запустить PostgreSQL в Docker
2. Экспортировать данные из SQLite
3. Обновить connection string
4. Применить миграции Alembic

**Связанные ADR:**
- ADR-001 (заменён для production)

## Архитектура: Production

git add design/ARCHITECTURE.md
git commit -m "docs: добавлен ADR-003, обновлена схема архитектуры"

# Автогенерация через OpenAPI
curl http://localhost:8000/openapi.json > /tmp/openapi.json

# API: {project}

**Внутренние endpoints (не public API)**

## GET /api/orders

**Описание:** Получить список заказов пользователя

**Query Parameters:**
- `user_id` (int, required)
- `status` (string, optional) — фильтр по статусу

**Response:**
```json
{
  "orders": [
    {
      "id": 1,
      "status": "completed",
      "total": 299.99,
      "created_at": "2025-11-10T10:00:00Z"
    }
  ]
}

---

### ПРОЦЕДУРА: Восстановление CHANGELOG.md

**Шаги:**

**1. Извлечь изменения из git:**

```bash
# Список commits за период
git log --since="2025-09-15" --pretty=format:"%h %ad %s" --date=short solution/

# Changelog: {project}

## [1.2.0] - 2025-11-10

### Добавлено
- Интеграция с PostgreSQL вместо SQLite
- Страница Products для управления товарами
- Экспорт заказов в Excel
- Поле `delivery_address` в Order

### Изменено
- Улучшена производительность загрузки Orders (индекс по status)
- Обновлён UI страницы Orders (добавлены фильтры)

### Исправлено
- Ошибка при создании заказа с пустым total
- Проблема с encoding в Excel экспорте

## [1.1.0] - 2025-10-20

### Добавлено
- Фильтры в таблице заказов
- Пагинация (100 записей на страницу)

### Исправлено
- Ошибка авторизации при expired токене

## [1.0.0] - 2025-09-15

### Добавлено
- Первый релиз MVP
- Авторизация пользователей
- CRUD для Orders
- Базовая аналитика

git add management/CHANGELOG.md
git commit -m "docs: восстановлен CHANGELOG за последние 2 месяца"

# Тестовая директория
cd /tmp/
mkdir test-quickstart
cd test-quickstart

# Из README.md:
git clone ...
cd project/solution/mvp/
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
streamlit run app.py

❌ Ошибка: requirements.txt отсутствует в repo
❌ Ошибка: streamlit выдаёт ModuleNotFoundError: No module named 'psycopg2'
⚠️ Предупреждение: .env.example не упомянут в Quick Start

# Quick Start

## Требования

- Python 3.11+
- PostgreSQL 14+ (или Docker)

## Установка

1. Клонировать репозиторий:
   ```bash
   git clone {url}
   cd {project}/solution/mvp/
   ```

2. Создать виртуальное окружение:
   ```bash
   python -m venv venv
   source venv/bin/activate  # Linux/Mac
   # ИЛИ
   venv\Scripts\activate  # Windows
   ```

3. Установить зависимости:
   ```bash
   pip install -r requirements.txt
   ```

4. Настроить переменные окружения:
   ```bash
   cp .env.example .env
   # Отредактировать .env
   ```

5. Запустить PostgreSQL (если нет):
   ```bash
   docker run -d \
     --name postgres \
     -e POSTGRES_PASSWORD=password \
     -p 5432:5432 \
     postgres:14
   ```

6. Применить миграции:
   ```bash
   alembic upgrade head
   ```

7. Запустить приложение:
   ```bash
   streamlit run app.py
   ```

8. Открыть: http://localhost:8501

## Первый вход

Логин: `admin@example.com`
Пароль: `admin`

git add management/README.md
git commit -m "docs: исправлен Quick Start (добавлены недостающие шаги)"

#!/bin/bash

PROJECT_PATH="/opt/claude-workspace/projects/{project}"
REPORT_PATH="$PROJECT_PATH/management/sync-audit-$(date +%Y%m%d).md"

echo "# Sync Audit Report" > $REPORT_PATH
echo "**Дата:** $(date +%Y-%m-%d)" >> $REPORT_PATH
echo "" >> $REPORT_PATH

# 1. Проверка актуальности документов
echo "## Актуальность документов" >> $REPORT_PATH

for doc in PROJECT.md ARCHITECTURE.md MODELS.md API.md README.md CHANGELOG.md; do
  doc_path="$PROJECT_PATH/design/$doc"

  if [ ! -f "$doc_path" ]; then
    doc_path="$PROJECT_PATH/management/$doc"
  fi

  if [ -f "$doc_path" ]; then
    last_modified=$(git log -1 --format="%ad" --date=short -- "$doc_path")
    echo "- $doc: последнее изменение $last_modified" >> $REPORT_PATH
  else
    echo "- $doc: ❌ отсутствует" >> $REPORT_PATH
  fi
done

# 2. Сравнение code vs docs
echo "" >> $REPORT_PATH
echo "## Code vs Docs" >> $REPORT_PATH

# Проверка моделей
echo "### Database Models" >> $REPORT_PATH
echo "\`\`\`" >> $REPORT_PATH
grep -h "class.*Base" $PROJECT_PATH/solution/*/database/models.py | sed 's/class //' | sed 's/(.*://' >> $REPORT_PATH
echo "\`\`\`" >> $REPORT_PATH

# Проверка API endpoints
if [ -d "$PROJECT_PATH/solution/backend" ]; then
  echo "### API Endpoints" >> $REPORT_PATH
  echo "\`\`\`" >> $REPORT_PATH
  grep -rh "@app\." $PROJECT_PATH/solution/backend/ --include="*.py" | head -20 >> $REPORT_PATH
  echo "\`\`\`" >> $REPORT_PATH
fi

echo "" >> $REPORT_PATH
echo "---" >> $REPORT_PATH
echo "Полный отчёт сохранён: $REPORT_PATH" >> $REPORT_PATH

# Показать отчёт
cat $REPORT_PATH

cd /opt/claude-workspace/projects/{project}/
./infrastructure/scripts/sync_audit.sh

# Каждый понедельник в 9:00
0 9 * * 1 cd /opt/claude-workspace/projects/{project} && ./infrastructure/scripts/sync_audit.sh

scope: project
mode: sync

loaded_files:
  - design/*
  - management/README.md
  - management/CHANGELOG.md
  - solution/mvp/**/*.py (для анализа)

cascade_enabled: true

actions_allowed:
  - read_docs: true
  - write_docs: true
  - read_code: true (для сравнения)
  - write_code: false
  - run_commands: false
  - git_operations: true

sync_rules:
  auto_update_changelog: false  # Требует ручного подтверждения
  auto_generate_models_md: true  # Можно автоматом
  auto_generate_api_md: true     # Можно автоматом

journaling: true

📅 Ежедневно (автоматически):
- Обновление CHANGELOG.md (если были commits)

📅 Еженедельно (manual):
- Проверка актуальности README.md
- Аудит MODELS.md

📅 Ежемесячно (manual):
- Полный sync audit
- Проверка всех ADR
- Обновление ROADMAP.md

📅 Перед релизом (обязательно):
- Полная синхронизация всех документов
- Проверка Quick Start
- Обновление версий

sync_metrics:
  timestamp: 2025-11-10

  documents:
    total: 8
    actual: 4
    outdated: 3
    missing: 1

  actuality_score: 50%  # 4/8

  sync_effort:
    estimated_hours: 2-3
    priority: medium

  next_sync: 2025-11-17  # через неделю