261 lines
6.8 KiB
Markdown
261 lines
6.8 KiB
Markdown
# База знаний проекта
|
||
|
||
## Назначение шаблона
|
||
|
||
Это шаблон проекта для быстрого старта новых проектов с:
|
||
- Next.js фронтендом (App Router)
|
||
- Express.js бэкендом
|
||
- TypeScript
|
||
- Tailwind CSS
|
||
- Модульной архитектурой
|
||
|
||
## Архитектура системы
|
||
|
||
### Frontend (Next.js)
|
||
|
||
**Структура:**
|
||
```
|
||
frontend/
|
||
app/ # Next.js App Router страницы
|
||
page.tsx # Главная страница
|
||
layout.tsx # Общий layout
|
||
components/ # React компоненты
|
||
lib/ # Утилиты и типы
|
||
docs/ # Документация фронтенда
|
||
```
|
||
|
||
**Технологии:**
|
||
- Next.js 15.3.3 с App Router
|
||
- React 19
|
||
- TypeScript 5
|
||
- Tailwind CSS 4
|
||
- Статический экспорт (`output: 'export'`)
|
||
|
||
### Backend (Express)
|
||
|
||
**Структура:**
|
||
```
|
||
backend/
|
||
server.js # Основной файл сервера
|
||
routes/ # API маршруты (создавать по мере необходимости)
|
||
```
|
||
|
||
**Технологии:**
|
||
- Express.js 5
|
||
- body-parser для обработки запросов
|
||
|
||
## Типы данных
|
||
|
||
Все типы должны быть определены явно. Используй интерфейсы для сложных структур:
|
||
|
||
```typescript
|
||
// Пример: frontend/lib/types.ts
|
||
export interface ApiResponse<T> {
|
||
success: boolean;
|
||
data?: T;
|
||
error?: string;
|
||
}
|
||
|
||
export interface User {
|
||
id: string;
|
||
name: string;
|
||
email: string;
|
||
}
|
||
```
|
||
|
||
## API интеграция
|
||
|
||
### Определение URL
|
||
|
||
Фронтенд автоматически определяет URL API:
|
||
```typescript
|
||
const isLocalhost = typeof window !== 'undefined' && window.location.hostname === 'localhost';
|
||
const apiUrl = isLocalhost
|
||
? 'http://localhost:3001/api'
|
||
: 'https://your-api-domain.com/api';
|
||
```
|
||
|
||
### Пример запроса
|
||
|
||
```typescript
|
||
async function fetchData() {
|
||
try {
|
||
const response = await fetch(`${apiUrl}/endpoint`, {
|
||
method: 'POST',
|
||
headers: { 'Content-Type': 'application/json' },
|
||
body: JSON.stringify({ data: 'value' }),
|
||
});
|
||
|
||
if (!response.ok) {
|
||
throw new Error('Server error');
|
||
}
|
||
|
||
const result = await response.json();
|
||
return result;
|
||
} catch (err) {
|
||
console.error('API Error:', err);
|
||
throw err;
|
||
}
|
||
}
|
||
```
|
||
|
||
## Добавление новых функций
|
||
|
||
### Frontend компонент
|
||
|
||
1. Создать компонент в `frontend/components/`:
|
||
```typescript
|
||
// components/MyComponent.tsx
|
||
export default function MyComponent() {
|
||
return <div>Content</div>;
|
||
}
|
||
```
|
||
|
||
2. Использовать в странице:
|
||
```typescript
|
||
// app/page.tsx
|
||
import MyComponent from '@/components/MyComponent';
|
||
```
|
||
|
||
### Backend endpoint
|
||
|
||
1. Добавить маршрут в `backend/server.js` или создать отдельный файл в `backend/routes/`:
|
||
|
||
```javascript
|
||
// backend/server.js
|
||
app.post('/api/my-endpoint', (req, res) => {
|
||
try {
|
||
const { data } = req.body;
|
||
// Обработка данных
|
||
res.json({ success: true, result: data });
|
||
} catch (err) {
|
||
res.status(500).json({ success: false, error: err.message });
|
||
}
|
||
});
|
||
```
|
||
|
||
## Окружение разработки
|
||
|
||
### Платформы
|
||
- **Разработка**: Windows с PowerShell
|
||
- **Хостинг**: Ubuntu Linux
|
||
|
||
### Особенности разработки на Windows
|
||
- PowerShell не поддерживает оператор `&&` для цепочки команд
|
||
- Используйте `;` или выполняйте команды отдельно
|
||
- Пути в Git и конфигах всегда используют `/`, даже на Windows
|
||
- При работе через SSH используйте Linux команды
|
||
|
||
### Локальная разработка (Windows + PowerShell)
|
||
```powershell
|
||
# Frontend - один терминал
|
||
cd frontend
|
||
npm install
|
||
npm run dev
|
||
|
||
# Backend - отдельный терминал
|
||
cd backend
|
||
npm install
|
||
node server.js
|
||
```
|
||
|
||
## Деплой
|
||
|
||
### Сервер
|
||
- **ОС**: Ubuntu Linux
|
||
- **IP**: (настройте под себя)
|
||
- **Пользователь**: (настройте под себя)
|
||
- **Путь**: ~/projects/<project-name>
|
||
- **Управление процессами**: PM2
|
||
|
||
### Процессы PM2
|
||
- `<app-name>-frontend` - Next.js приложение (статические файлы через serve или nginx)
|
||
- `<app-name>-backend` - Express сервер
|
||
|
||
### Команды деплоя
|
||
**С локального Windows (PowerShell):**
|
||
```powershell
|
||
# Отправить изменения
|
||
git push origin dev
|
||
|
||
# Подключиться и обновить сервер (Ubuntu команды через SSH)
|
||
ssh user@server-ip "cd ~/projects/<project-name> && git pull origin dev && cd frontend && npm run build && pm2 restart <app-name>-frontend <app-name>-backend"
|
||
```
|
||
|
||
**Или на сервере напрямую (Ubuntu):**
|
||
```bash
|
||
cd ~/projects/<project-name>
|
||
git pull origin dev
|
||
cd frontend && npm run build
|
||
pm2 restart <app-name>-frontend <app-name>-backend
|
||
```
|
||
|
||
### Настройка PM2
|
||
|
||
Создайте `ecosystem.config.js` в корне проекта:
|
||
|
||
```javascript
|
||
module.exports = {
|
||
apps: [
|
||
{
|
||
name: 'my-app-frontend',
|
||
script: 'serve',
|
||
args: '-s frontend/out -p 3000',
|
||
cwd: './',
|
||
env: {
|
||
NODE_ENV: 'production'
|
||
}
|
||
},
|
||
{
|
||
name: 'my-app-backend',
|
||
script: 'server.js',
|
||
cwd: './backend',
|
||
env: {
|
||
NODE_ENV: 'production',
|
||
PORT: 3001
|
||
}
|
||
}
|
||
]
|
||
};
|
||
```
|
||
|
||
Запуск: `pm2 start ecosystem.config.js`
|
||
|
||
## Обработка ошибок
|
||
|
||
### API запросы
|
||
```typescript
|
||
try {
|
||
const response = await fetch(apiUrl, { method: 'POST', body: formData });
|
||
if (!response.ok) {
|
||
throw new Error(`HTTP error! status: ${response.status}`);
|
||
}
|
||
const data = await response.json();
|
||
return data;
|
||
} catch (err) {
|
||
console.error('API Error:', err);
|
||
// Показать сообщение пользователю
|
||
throw err;
|
||
}
|
||
```
|
||
|
||
### Backend
|
||
```javascript
|
||
app.post('/api/endpoint', (req, res) => {
|
||
try {
|
||
// Обработка
|
||
res.json({ success: true, data: result });
|
||
} catch (err) {
|
||
console.error('Error:', err);
|
||
res.status(500).json({ success: false, error: err.message });
|
||
}
|
||
});
|
||
```
|
||
|
||
## Известные особенности
|
||
|
||
1. **Статический экспорт**: Next.js собирается в статические файлы, нет серверного рендеринга
|
||
2. **CORS**: Настроен для разработки, адаптируйте под продакшн
|
||
3. **Порты**: Frontend 3000, Backend 3001 по умолчанию
|
||
|