arch-filesystem-structure.md

type: standard
layer: arch
object: filesystem
aspect: structure
form: text
title: "Файловая система платформы"
status: superseded
superseded_by: arch-platform-structure.md
version: 1.0.0
date: 2026-04-11
knowledge_level: У1
parent: arch-document-format.md

Файловая система платформы

Стандарт описывает физическую организацию файлов платформы: два пространства хранения, белый и чёрный списки, шестислойную структуру $WORKSPACE, правила слоёв, именование модулей.

1. ДВА ПРОСТРАНСТВА

Платформа использует два пространства хранения:

Переменная	Путь	Хранение	Что лежит
`$WORKSPACE`	`/opt/claude-workspace`	Git	Код, документы, конфигурация
`$DATASPACE`	`/mnt/beget-s3`	S3	Таблицы, медиа, PDF, дампы БД

Правило разграничения:
- Файл создаётся руками или агентом как текст → $WORKSPACE
- Файл является результатом компиляции, рендеринга, форматирования → $DATASPACE

WORKSPACE=/opt/claude-workspace     # исходники (git)
DATASPACE=/mnt/beget-s3            # данные, медиа (S3)
BACKUPSPACE=$DATASPACE/backup      # бэкапы (папка или другой сервер)
DATABASE=postgresql://...           # строка подключения к БД

Правило: меняем только переменную — скрипты не трогаем.

2. ЧТО ХРАНИТСЯ В $WORKSPACE

КОД:           .py .js .ts .tsx .jsx .php .go .sh .bat .ps1
ДОКУМЕНТАЦИЯ:  .md .txt .rst
КОНФИГУРАЦИЯ:  .yaml .yml .json .toml .ini .conf .xml .env.example
WEB:           .html .css .scss .less
ШАБЛОНЫ:       .twig .tpl .j2
SQL:           .sql (схемы и миграции)
СПЕЦИАЛЬНЫЕ:   .gitignore .gitkeep .editorconfig Dockerfile Makefile LICENSE

ГРАФИКА:   .svg .ico .jpg .jpeg .png .gif .webp
ШРИФТЫ:    .woff2 .ttf .otf .eot
МЕДИА:     .mp4 .avi .mov .mp3 .wav
ДОКУМЕНТЫ: .pdf .docx .doc .rtf
ДАННЫЕ:    .xlsx .xls .ods .csv (> 100 KB)
БД:        .db .sqlite
СЕКРЕТЫ:   .env .key .pem
ВРЕМЕННЫЕ: .pyc .log .tmp .cache
ЗАВИСИМ.:  venv/ node_modules/ __pycache__/

Исключение для .csv: файлы < 100 KB (fixtures, тесты) допускаются в git.

3. СТРУКТУРА $WORKSPACE

6-слойная структура $WORKSPACE, дерево папок, именование модулей, служебные файлы →
arch-workspace-structure.md

4. СТРУКТУРА $DATASPACE

$DATASPACE зеркалит $WORKSPACE — те же проекты, другой носитель:

$DATASPACE/
├── projects/
│   ├── org/{project}/     ← данные клиентских проектов (медиа, дампы, CSV)
│   └── sys/{project}/     ← данные системных проектов
├── backup/                ← бэкапы git + БД
│   ├── git/               ← архивы репозитория
│   └── db/                ← дампы БД по проектам
├── media/                 ← общие медиа-файлы
└── archive/               ← устаревшие данные

Правило: путь в $DATASPACE = тот же относительный путь что в $WORKSPACE.

5. .GITIGNORE

Минимальный шаблон для любого компонента платформы:

# Зависимости
node_modules/
venv/
__pycache__/
*.pyc
.env

# Временные
*.log
*.tmp
*.cache

# Секреты
*.key
*.pem
.credentials.md

# Данные (→ $DATASPACE)
*.jpg
*.jpeg
*.png
*.gif
*.webp
*.svg
*.pdf
*.docx
*.xlsx
*.mp4
*.mp3

# Базы данных
*.db
*.sqlite

# Сборка
dist/
build/
*.min.js

Pre-commit hook — аудит запрещённых файлов

#!/bin/bash
# .git/hooks/pre-commit
forbidden=$(git diff --cached --name-only | grep -E '\.(jpg|jpeg|png|gif|webp|pdf|env|key|pem)$')
if [ -n "$forbidden" ]; then
  echo "❌ СТОП: запрещённые файлы в коммите:"
  echo "$forbidden"
  exit 1
fi