Writing a constitution file

[Xpystum]

Greetings, colleagues. Someone with more experience could tell me if this file would be relevant for the constitution, or if there's anything else I should pay attention to?

1. Is it possible to create a hybrid language? How might this affect code generation?
2. If I provide a link to good practices, will I not have to spend a lot of tokens in this case? (https://github.com/alexeymezenin/laravel-best-practices)

Project Constitution (Конституция проекта)

Backend API Project (Проект Backend API): This is a backend-only project without frontend. All functionality is exposed via REST API. (Это проект только бэкенда без фронтовой части. Вся функциональность предоставляется через REST API.)

1. Architectural Principles (Архитектурные принципы)

• Clean Architecture (обязательный стиль)
• Not pure DDD: we use principles, but without strict adherence to all DDD nuances/layers (Не чистый DDD: используем принципы, но без строгого следования всем тонкостям/слоям DDD)
• CQRS: separation of commands and queries (разделение команд и запросов)
  • Example (Пример): UserQueryRepository, UserCommandRepository
• Repository Pattern is mandatory (обязателен)
• All dependencies through abstractions (interface) (Все зависимости через абстракции)
• Dependency Injection is mandatory (обязателен)
• Service Locator is prohibited (запрещён) (app()->make(), resolve())
• Service + modular style: functionality is organized into reusable services and modules with clear boundaries and contracts (Сервисный + модульный стиль: функциональность оформляется в переиспользуемые сервисы и модули с чёткими границами и контрактами)
• API-First approach (API-первый подход): all business logic is exposed through RESTful API endpoints (вся бизнес-логика предоставляется через RESTful API endpoints)

2. Technical Constraints (Технические ограничения)

• Backend API only (Только Backend API) - no frontend, no views, no Blade templates (без фронтенда, без представлений, без Blade шаблонов)
• PHP 8.4, Laravel 12
• RoadRunner + Laravel Octane (mandatory | обязательно)
• REST API (preparing for future gRPC | подготовка к будущему gRPC)
• PostgreSQL
• Redis (cache and queues | кэш и очереди)
• RabbitMQ (message queues | очереди сообщений)
• Mandatory tools (Обязательные инструменты): Larastan (PHPStan for Laravel), Laravel Pint
• API Documentation (Документация API): OpenAPI 3 + @rakutentech/laravel-request-docs
• API versioning strategy (Стратегия версионирования API): URI versioning (/api/v1/, /api/v2/)

3. Code Quality and Standards (Качество кода и стандарты)

• SOLID, DRY, KISS
• PSR-12
• Naming: camelCase
• Value Object should be used where it makes sense (использовать там, где есть смысл)
• DTO pattern is mandatory for transport objects (обязателен для транспортных объектов)
• PHPDoc is mandatory for documentation (обязателен для документации)
• Service approach (reusable services) and modular style for clear separation of responsibilities and reusability (Сервисный подход и модульный стиль для чёткого разделения ответственности и повторного использования)

4. Testing (Тестирование)

• PHPUnit
• TDD is mandatory (обязателен)
• Test pattern: AAA (Arrange, Act, Assert) (Паттерн тестов)
• Minimum unit test coverage: 60% (Минимальный coverage unit тестов)
• API testing (Тестирование API): feature tests for all endpoints (функциональные тесты для всех endpoints)

5. Git and Commits (Git и коммиты)

Commit Format (Формат коммита)

<type>(<ticket-id>): <description>

Refs: <ticket-list>

Types (Типы)

• feat - new feature (новая функциональность)
• fix - bug fix (исправление ошибки)
• docs - documentation (документация)
• refactor - code refactoring (рефакторинг кода)
• test - tests (тесты)
• chore - maintenance tasks (вспомогательные задачи)

Ticket ID

• Only M24-XXXX format (Только формат M24-XXXX)

6. Security & Privacy (Безопасность и конфиденциальность)

OWASP Top 10 (mandatory practices | обязательные практики)

1. Broken Access Control (Нарушение контроля доступа)
2. Cryptographic Failures (Криптографические сбои)
3. Injection (Инъекции)
4. Insecure Design (Небезопасный дизайн)
5. Security Misconfiguration (Неправильная конфигурация безопасности)
6. Vulnerable and Outdated Components (Уязвимые и устаревшие компоненты)
7. Identification and Authentication Failures (Сбои идентификации и аутентификации)
8. Software and Data Integrity Failures (Нарушение целостности ПО и данных)
9. Security Logging and Monitoring Failures (Сбои логирования и мониторинга безопасности)
10. Server-Side Request Forgery (SSRF) (Подделка запросов на стороне сервера)

API Security (Безопасность API)

• API authentication (Аутентификация API): JWT tokens or OAuth 2.0 (JWT токены или OAuth 2.0)
• Rate limiting (Ограничение частоты запросов): throttling middleware mandatory (middleware throttling обязателен)
• Input validation (Валидация входных данных): all API requests must be validated (все API запросы должны быть валидированы)
• CORS policy (Политика CORS): strictly configured, no wildcard in production (строго настроена, без wildcard в продакшене)
• API keys rotation (Ротация API ключей): regular rotation policy (политика регулярной ротации)

Compliance (Соответствие нормативным требованиям)

• GDPR (General Data Protection Regulation) (Общий регламент по защите данных)
  • Right to access (Право на доступ к данным)
  • Right to erasure (Право на удаление данных) - "right to be forgotten" ("право быть забытым")
  • Data portability (Переносимость данных)
  • Consent management (Управление согласием на обработку данных)
  • Data breach notification (Уведомление о нарушении безопасности данных) - within 72 hours (в течение 72 часов)
  • Privacy by design (Конфиденциальность по умолчанию)
  • Data minimization (Минимизация данных)
• PCI DSS (Payment Card Industry Data Security Standard) - if handling payment data (если обрабатываются платежные данные)
  • Secure storage of cardholder data (Безопасное хранение данных держателей карт)
  • Encryption of transmission (Шифрование передачи данных)
  • Regular security testing (Регулярное тестирование безопасности)
• SOC 2 (Service Organization Control 2) - for service providers (для сервис-провайдеров)
  • Security (Безопасность)
  • Availability (Доступность)
  • Processing integrity (Целостность обработки)
  • Confidentiality (Конфиденциальность)
  • Privacy (Приватность)
• ISO/IEC 27001 - Information Security Management (Управление информационной безопасностью)
  • Risk assessment (Оценка рисков)
  • Security controls implementation (Внедрение средств контроля безопасности)
  • Continuous improvement (Непрерывное улучшение)
• Data retention policy (Политика хранения данных): defined retention periods for all data types (определённые сроки хранения для всех типов данных)
• Audit logging (Логирование аудита): all critical operations must be logged with user identification (все критические операции должны логироваться с идентификацией пользователя)
• Personal data handling (Обработка персональных данных):
  • Data classification (Классификация данных): PII (Personally Identifiable Information) must be marked and protected (Персонально идентифицируемая информация должна быть помечена и защищена)
  • Encryption at rest (Шифрование в состоянии покоя): all sensitive data must be encrypted (все чувствительные данные должны быть зашифрованы)
  • Encryption in transit (Шифрование при передаче): TLS 1.3+ only (только TLS 1.3+)
  • Data anonymization (Анонимизация данных): for analytics and reporting (для аналитики и отчётности)

7. Octane + RoadRunner Rules (Правила Octane + RoadRunner)

• No global state (Нет глобального состояния)
• Singleton prohibited for request-state (Запрет singleton для request-state)
• Reset state after each request (Сброс состояния после каждого запроса): Octane::terminate/flush
• Thread-safe code (no race conditions) (Thread-safe код без race conditions)
• DI instead of resolve()/app() (DI вместо resolve()/app())
• Control cache and sessions (don't persist state between requests) (Контроль кэша и сессий - не сохранять состояние между запросами)

8. Logging (Логирование)

• Current (Сейчас): standard Laravel log (стандарт��ый Laravel log)
• Future (В будущем): ELK Stack (Kibana + Elasticsearch + Logstash)
• API request/response logging (Логирование запросов/ответов API): all API calls must be logged (все API вызовы должны логироваться)
• Security events logging (Логирование событий безопасности): authentication failures, authorization failures, suspicious activities (неудачные аутентификации, отказы в авторизации, подозрительная активность)
• PII masking in logs (Маскирование персональных данных в логах): sensitive data must never appear in plain text in logs (чувствительные данные никогда не должны появляться в открытом виде в логах)

9. Transactions (Транзакции)

• Only through DB::transaction() (Только через DB::transaction())
• API idempotency (Идемпотентность API): POST, PUT, DELETE operations should be idempotent where possible (операции POST, PUT, DELETE должны быть идемпотентными где возможно)

10. PR Checks (mandatory | обязательные) (Проверки при PR)

• Larastan (PHPStan for Laravel) - static analysis (статический анализ)
• Laravel Pint - formatting/linting (форматирование/линт)
• PHPUnit - tests, unit coverage ≥ 60% (тесты, unit coverage ≥ 60%)
• API documentation updated (Документация API обновлена): OpenAPI spec must be updated for new/changed endpoints (спецификация OpenAPI должна быть обновлена для новых/изменённых endpoints)
• Merge is blocked if any check fails (Merge блокируется, если любая из проверок не пройдена)

11. API Design Principles (Принципы проектирования API)

• RESTful conventions (Соглашения RESTful): proper use of HTTP methods (правильное использование HTTP методов)
  • GET - retrieve resources (получение ресурсов)
  • POST - create resources (создание ресурсов)
  • PUT/PATCH - update resources (обновление ресурсов)
  • DELETE - delete resources (удаление ресурсов)
• HTTP status codes (HTTP коды состояния): proper status codes for all responses (правильные коды состояния для всех ответов)
  • 2xx - success (успех)
  • 4xx - client errors (ошибки клиента)
  • 5xx - server errors (ошибки сервера)
• Consistent response format (Единообразный формат ответов): all API responses follow the same structure (все API ответы следуют одной структуре)
• Error handling (Обработка ошибок): detailed error messages with error codes (детальные сообщения об ошибках с кодами ошибок)
• Pagination (Пагинация): all list endpoints must support pagination (все endpoints со списками должны поддерживать пагинацию)
• Filtering and sorting (Фильтрация и сортировка): support query parameters for filtering and sorting (поддержка query параметров для фильтрации и сортировки)
• API versioning (Версионирование API): breaking changes require new API version (критические изменения требуют новой версии API)