СИСТЕМНАЯ КОНВЕНЦИЯ: ОБМЕН ФАЙЛАМИ ЧЕРЕЗ S3

Название: S3 папка
Статус: ✅ Активно (с 2025-11-17)
Приоритет: Критично - используется во ВСЕХ проектах
Версия: 1.1

🎯 ГЛАВНОЕ ПРАВИЛО

ВСЕ файлы для пользователя ДОЛЖНЫ размещаться в S3 папке обмена ("S3 папка").

Не отправлять файлы через:
- ❌ Email attachments
- ❌ Telegram
- ❌ Прямые ссылки
- ❌ Временные загрузки

Использовать ТОЛЬКО:
- ✅ S3 папку обмена (описана ниже)

📂 СТАНДАРТНЫЕ ПУТИ

На сервере (где работает Claude Code):

/mnt/beget-s3/nomenclature/incoming/   - Файлы ОТ пользователя
/mnt/beget-s3/nomenclature/outgoing/   - Файлы ДЛЯ пользователя
/mnt/beget-s3/nomenclature/archive/    - Архив обработанных файлов

На компьютере пользователя (Linux):

~/beget-s3/nomenclature/incoming/   - Отправить файлы на сервер
~/beget-s3/nomenclature/outgoing/   - Получить файлы с сервера
~/beget-s3/nomenclature/archive/    - Архив

На компьютере пользователя (Windows):

Z:\nomenclature\incoming\   - Отправить файлы на сервер
Z:\nomenclature\outgoing\   - Получить файлы с сервера
Z:\nomenclature\archive\    - Архив

📋 ПРАВИЛА ДЛЯ ПРОЕКТОВ

1. Размещение файлов для пользователя

Всегда использовать путь:

/mnt/beget-s3/nomenclature/outgoing/

Пример из проекта nomenclature1c:

# ✅ ПРАВИЛЬНО:
cp data/changes_only.xlsx /mnt/beget-s3/nomenclature/outgoing/

# ❌ НЕПРАВИЛЬНО:
cp data/changes_only.xlsx /tmp/   # Пользователь не увидит

2. Сообщение пользователю о готовности файла

Формат сообщения:

Файл готов к скачиванию:
  На Linux: ~/beget-s3/nomenclature/outgoing/{имя_файла}
  На Windows: Z:\nomenclature\outgoing\{имя_файла}

Пример:

Файл готов к скачиванию:
  На Linux: ~/beget-s3/nomenclature/outgoing/changes_only.xlsx
  На Windows: Z:\nomenclature\outgoing\changes_only.xlsx

Размер: 8.8 KB
Содержимое: 66 исправленных записей номенклатуры

3. Получение файлов от пользователя

Проверять папку incoming:

# Проверить наличие новых файлов
ls -lh /mnt/beget-s3/nomenclature/incoming/

# Обработать файл
cp /mnt/beget-s3/nomenclature/incoming/user_file.xlsx data/

# После обработки - переместить в архив
mv /mnt/beget-s3/nomenclature/incoming/user_file.xlsx \
   /mnt/beget-s3/nomenclature/archive/user_file_$(date +%Y%m%d_%H%M%S).xlsx

4. Именование файлов

Соглашения:
- Использовать lowercase и underscores: my_file.xlsx
- Включать дату для архивных копий: report_20251117.xlsx
- Понятные имена: changes_only.xlsx, price_list.xlsx, errors_report.xlsx

🔧 ТЕХНИЧЕСКАЯ ИНФОРМАЦИЯ

Подключение S3

Сервер: Уже настроено и работает
- Mount: /mnt/beget-s3/
- Автозапуск: systemd service beget-s3-mount.service

Клиент: Требует настройки
- Linux инструкция: /opt/claude-workspace/infra/infra-s3-beget/scripts/install.sh
- Windows скрипт: /opt/claude-workspace/infra/infra-s3-beget/scripts/mount_s3_windows.ps1
- Документация: /opt/claude-workspace/infra/infra-s3-beget/QUICK_START.md

S3 Credentials

Хранятся в:
- /opt/claude-workspace/infra/infra-s3-beget/config/.env
- /root/.config/rclone/rclone.conf

Параметры:
- Endpoint: https://s3.ru1.storage.beget.cloud
- Bucket: fe2c1d30dc11-s3-0kt
- Region: ru-1

📚 ПРИМЕРЫ ИСПОЛЬЗОВАНИЯ

Пример 1: Проект nomenclature1c - Отправка исправленных данных

#!/bin/bash
# projects/nomenclature1c/send_results.sh

PROJECT_DIR="/opt/claude-workspace/projects/nomenclature1c"
OUTGOING="/mnt/beget-s3/nomenclature/outgoing"

# Скопировать файл
cp "$PROJECT_DIR/data/changes_only.xlsx" "$OUTGOING/"

# Проверить
ls -lh "$OUTGOING/changes_only.xlsx"

# Сообщить пользователю
echo "Файл готов к скачиванию:"
echo "  На Linux: ~/beget-s3/nomenclature/outgoing/changes_only.xlsx"
echo "  На Windows: Z:\\nomenclature\\outgoing\\changes_only.xlsx"

Пример 2: Получение файла от пользователя

#!/bin/bash
# Проверить incoming папку

INCOMING="/mnt/beget-s3/nomenclature/incoming"
ARCHIVE="/mnt/beget-s3/nomenclature/archive"

# Найти новые файлы
NEW_FILES=$(ls -1 "$INCOMING"/*.xlsx 2>/dev/null)

if [ -z "$NEW_FILES" ]; then
    echo "Нет новых файлов от пользователя"
    exit 0
fi

# Обработать каждый файл
for FILE in $NEW_FILES; do
    BASENAME=$(basename "$FILE")
    echo "Обрабатываю: $BASENAME"

    # Ваша обработка здесь
    process_file "$FILE"

    # Переместить в архив
    TIMESTAMP=$(date +%Y%m%d_%H%M%S)
    mv "$FILE" "$ARCHIVE/${BASENAME%.xlsx}_${TIMESTAMP}.xlsx"
done

Пример 3: Генерация отчёта

# projects/analytics/generate_report.py
import pandas as pd
from pathlib import Path

OUTGOING = Path("/mnt/beget-s3/nomenclature/outgoing")

# Создать отчёт
df = pd.DataFrame({"column": ["data"]})
report_file = OUTGOING / "report_20251117.xlsx"

df.to_excel(report_file, index=False)

print(f"Отчёт готов к скачиванию:")
print(f"  На Linux: ~/beget-s3/nomenclature/outgoing/report_20251117.xlsx")
print(f"  На Windows: Z:\\nomenclature\\outgoing\\report_20251117.xlsx")

✅ CHECKLIST ДЛЯ РАЗРАБОТЧИКОВ

При работе над проектом:

[ ] Размещаю файлы для пользователя в /mnt/beget-s3/nomenclature/outgoing/
[ ] Проверяю incoming папку на наличие файлов от пользователя
[ ] Архивирую обработанные файлы
[ ] Сообщаю пути на компьютере пользователя (Linux и Windows)
[ ] Использую понятные имена файлов
[ ] Не отправляю временные файлы в S3

🔄 WORKFLOW ОБМЕНА

┌─────────────────┐
│ Проект          │
│ (nomenclature1c)│
└────────┬────────┘
         │ cp file.xlsx
         ↓
┌─────────────────────────┐
│ S3 outgoing/            │ ← Сервер: /mnt/beget-s3/nomenclature/outgoing/
│ file.xlsx               │
└────────┬────────────────┘
         │ S3 sync
         ↓
┌─────────────────────────┐
│ Компьютер пользователя  │ ← Linux: ~/beget-s3/nomenclature/outgoing/
│ file.xlsx               │ ← Windows: Z:\nomenclature\outgoing\
└─────────────────────────┘

🚨 ВАЖНЫЕ ЗАМЕЧАНИЯ

Синхронизация

Файлы появляются мгновенно на всех подключенных машинах
Не нужно ждать - S3 mount работает в реальном времени
При проблемах с сетью - автопереподключение

Безопасность

Папка доступна только пользователю и серверу
S3 credentials защищены (permissions 600)
Не хранить sensitive данные без шифрования

Ограничения

Для файлов >100 MB лучше использовать прямой SCP/rsync
При большом количестве файлов (>1000) производительность снижается
Требует стабильное интернет соединение

📊 СТАТИСТИКА ИСПОЛЬЗОВАНИЯ

Текущие проекты, использующие S3:

nomenclature1c - Обмен данными номенклатуры
- Файлы: changes_only.xlsx (8.8 KB, 66 записей)
- Статус: ✅ Активно используется

🆘 TROUBLESHOOTING

Проблема: Файл не появляется на компьютере пользователя

Решение:
1. Проверить монтирование на сервере:
bash mountpoint /mnt/beget-s3 # Должно быть: /mnt/beget-s3 is a mountpoint

Проверить файл на сервере:
bash ls -lh /mnt/beget-s3/nomenclature/outgoing/
Попросить пользователя обновить папку:
```bash
# Linux
ls ~/beget-s3/nomenclature/outgoing/

# Windows
dir Z:\nomenclature\outgoing\
```

Проблема: Permission denied

Решение:

# Проверить права
ls -la /mnt/beget-s3/nomenclature/

# Если нужно - исправить
chmod 755 /mnt/beget-s3/nomenclature/outgoing/

📖 ДОПОЛНИТЕЛЬНАЯ ДОКУМЕНТАЦИЯ

Полная инструкция: /opt/claude-workspace/infra/infra-s3-beget/README.md
Быстрый старт: /opt/claude-workspace/infra/infra-s3-beget/QUICK_START.md
Руководство пользователя: /opt/claude-workspace/infra/infra-s3-beget/docs/USER_GUIDE.md
Решение проблем: /opt/claude-workspace/infra/infra-s3-beget/docs/S3_ACCESS_ISSUE.md

Версия: 1.0
Дата: 2025-11-17
Автор: Claude Code
Статус: ✅ Активная конвенция - ОБЯЗАТЕЛЬНА для всех проектов