it-smi
CI / Сборка (push) Canceled after 0s
CI / Деплой на стейджинг (push) Canceled after 0s
CI / Проверка кода (push) Canceled after 0s
CI / Сборка (pull_request) Successful in 1m27s
Стенд master
CI / Деплой на стейджинг (pull_request) Successful in 7s
CI / Проверка кода (pull_request) Successful in 1m14s
CI / Сборка (push) Canceled after 0s
CI / Деплой на стейджинг (push) Canceled after 0s
CI / Проверка кода (push) Canceled after 0s
CI / Сборка (pull_request) Successful in 1m27s
Стенд master
CI / Деплой на стейджинг (pull_request) Successful in 7s
CI / Проверка кода (pull_request) Successful in 1m14s
This commit is contained in:
1 parent
7d5156d92e
commit
24df6221b3
36 files changed
+27
-2089
No files matched your search
@@ -1,4 +0,0 @@
|
|||||||
title: 'GEO Helm'
|
|
||||||
project:
|
|
||||||
org: 'jt4d'
|
|
||||||
repo: 'jt4d'
|
|
||||||
@@ -32,15 +32,6 @@ jobs:
|
|||||||
- name: Check branch name
|
- name: Check branch name
|
||||||
run: yarn lint:branch-name
|
run: yarn lint:branch-name
|
||||||
|
|
||||||
- name: Check branch name characters
|
|
||||||
env:
|
|
||||||
BRANCH: ${{ github.head_ref || github.ref_name }}
|
|
||||||
run: |
|
|
||||||
if ! printf '%s' "$BRANCH" | grep -Eq '^[A-Za-z0-9][A-Za-z0-9.-]*$'; then
|
|
||||||
echo "::error::Недопустимое имя ветки: '$BRANCH'. Разрешены только A-Z a-z 0-9 . -, имя не может быть пустым и начинаться с '-'"
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
|
|
||||||
- name: Check migrations list
|
- name: Check migrations list
|
||||||
run: yarn ts-node tools/buildDataSource.ts --check
|
run: yarn ts-node tools/buildDataSource.ts --check
|
||||||
|
|
||||||
@@ -90,7 +81,7 @@ jobs:
|
|||||||
runs-on: ubuntu-latest
|
runs-on: ubuntu-latest
|
||||||
needs: build
|
needs: build
|
||||||
env:
|
env:
|
||||||
DEPLOY_URL: https://${{ github.head_ref || github.ref_name }}.jt4d.jt4d.ru.net
|
DEPLOY_URL: https://${{ github.head_ref || github.ref_name }}.it-smi.jt4d.ru.net
|
||||||
steps:
|
steps:
|
||||||
- name: Checkout
|
- name: Checkout
|
||||||
uses: actions/checkout@v4
|
uses: actions/checkout@v4
|
||||||
@@ -163,28 +154,3 @@ jobs:
|
|||||||
|
|
||||||
- name: Lint
|
- name: Lint
|
||||||
run: yarn lint:check
|
run: yarn lint:check
|
||||||
|
|
||||||
docs:
|
|
||||||
name: Документация
|
|
||||||
runs-on: ubuntu-latest
|
|
||||||
needs: build
|
|
||||||
container:
|
|
||||||
image: git.jt4d.ru/jt4d/gitea-runner:latest
|
|
||||||
credentials:
|
|
||||||
username: ${{ vars.REGISTRY_USER }}
|
|
||||||
password: ${{ secrets.REGISTRY_PASSWORD }}
|
|
||||||
volumes:
|
|
||||||
- '/usr/local/share/.cache:/usr/local/share/.cache'
|
|
||||||
|
|
||||||
env:
|
|
||||||
YARN_CACHE_FOLDER: /usr/local/share/.cache/yarn
|
|
||||||
|
|
||||||
steps:
|
|
||||||
- name: Checkout
|
|
||||||
uses: actions/checkout@v4
|
|
||||||
|
|
||||||
- name: Build and deploy docs
|
|
||||||
uses: https://git.jt4d.ru/docuservix/docs@next
|
|
||||||
with:
|
|
||||||
prefix: wiki
|
|
||||||
on-broken-links: warn
|
|
||||||
@@ -1,143 +0,0 @@
|
|||||||
name: Production
|
|
||||||
|
|
||||||
on:
|
|
||||||
push:
|
|
||||||
tags:
|
|
||||||
- v*
|
|
||||||
workflow_dispatch:
|
|
||||||
inputs:
|
|
||||||
logLevel:
|
|
||||||
description: 'Log level'
|
|
||||||
required: true
|
|
||||||
default: 'info'
|
|
||||||
type: choice
|
|
||||||
options:
|
|
||||||
- verbose
|
|
||||||
- debug
|
|
||||||
- info
|
|
||||||
- warn
|
|
||||||
|
|
||||||
concurrency:
|
|
||||||
group: production-deploy
|
|
||||||
cancel-in-progress: false
|
|
||||||
|
|
||||||
jobs:
|
|
||||||
build:
|
|
||||||
name: Сборка
|
|
||||||
runs-on: ubuntu-latest
|
|
||||||
outputs:
|
|
||||||
version: ${{ steps.version.outputs.VERSION }}
|
|
||||||
steps:
|
|
||||||
- name: Checkout
|
|
||||||
uses: actions/checkout@v4
|
|
||||||
|
|
||||||
- name: Login to Gitea Registry
|
|
||||||
uses: docker/login-action@v3
|
|
||||||
with:
|
|
||||||
registry: git.jt4d.ru
|
|
||||||
username: ${{ vars.REGISTRY_USER }}
|
|
||||||
password: ${{ secrets.REGISTRY_PASSWORD }}
|
|
||||||
|
|
||||||
- name: Compute version
|
|
||||||
id: version
|
|
||||||
env:
|
|
||||||
REF_NAME: ${{ github.ref_name }}
|
|
||||||
run: |
|
|
||||||
VERSION=$(git describe --tags --exact-match 2>/dev/null \
|
|
||||||
|| echo "$REF_NAME-$(git rev-parse --short HEAD)")
|
|
||||||
# Единственная проверка VERSION в пайплайне: дальше он уходит и в шаги
|
|
||||||
# этого job, и в deploy-production через needs.build.outputs.version.
|
|
||||||
if ! printf '%s' "$VERSION" | grep -Eq '^[A-Za-z0-9][A-Za-z0-9.-]*$'; then
|
|
||||||
echo "::error::Недопустимый VERSION: '$VERSION'. Разрешены только A-Z a-z 0-9 . -, значение не может быть пустым и начинаться с '-'"
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
echo "VERSION=$VERSION" >> $GITHUB_OUTPUT
|
|
||||||
echo "**Версия:** \`$VERSION\`" >> $GITHUB_STEP_SUMMARY
|
|
||||||
|
|
||||||
- name: Install dependencies
|
|
||||||
run: yarn install --frozen-lockfile
|
|
||||||
|
|
||||||
- name: Check migrations list
|
|
||||||
run: yarn ts-node tools/buildDataSource.ts --check
|
|
||||||
|
|
||||||
- name: Build
|
|
||||||
run: yarn build
|
|
||||||
env:
|
|
||||||
APP_VERSION: ${{ steps.version.outputs.VERSION }}
|
|
||||||
|
|
||||||
- name: Check data-source
|
|
||||||
run: yarn ts-node tools/checkDataSource.ts
|
|
||||||
|
|
||||||
- name: Build web docker image
|
|
||||||
uses: docker/build-push-action@v7
|
|
||||||
with:
|
|
||||||
context: apps/web
|
|
||||||
file: apps/web/Dockerfile
|
|
||||||
push: true
|
|
||||||
tags: git.jt4d.ru/${{ github.repository }}/web:${{ steps.version.outputs.VERSION }}
|
|
||||||
cache-from: git.jt4d.ru/${{ github.repository }}/web:master
|
|
||||||
labels: |
|
|
||||||
org.opencontainers.image.ref.name=${{ steps.version.outputs.VERSION }}
|
|
||||||
|
|
||||||
- name: Copy
|
|
||||||
run: cp yarn.lock apps/api/
|
|
||||||
|
|
||||||
- name: Build api docker image
|
|
||||||
uses: docker/build-push-action@v7
|
|
||||||
with:
|
|
||||||
context: apps/api
|
|
||||||
file: apps/api/Dockerfile
|
|
||||||
push: true
|
|
||||||
tags: git.jt4d.ru/${{ github.repository }}/api:${{ steps.version.outputs.VERSION }}
|
|
||||||
cache-from: git.jt4d.ru/${{ github.repository }}/api:master
|
|
||||||
labels: |
|
|
||||||
org.opencontainers.image.ref.name=${{ steps.version.outputs.VERSION }}
|
|
||||||
|
|
||||||
deploy-production:
|
|
||||||
name: Деплой на прод
|
|
||||||
runs-on: ubuntu-latest
|
|
||||||
needs: build
|
|
||||||
steps:
|
|
||||||
- name: Checkout
|
|
||||||
uses: actions/checkout@v4
|
|
||||||
|
|
||||||
- name: Check log level
|
|
||||||
env:
|
|
||||||
LOG_LEVEL: ${{ inputs.logLevel }}
|
|
||||||
run: |
|
|
||||||
# VERSION проверен regexp-ом в job build (шаг Compute version) и приходит
|
|
||||||
# сюда как его output; LOG_LEVEL — свободный ввод, проверяется здесь.
|
|
||||||
case "$LOG_LEVEL" in
|
|
||||||
'' | verbose | debug | info | warn) ;;
|
|
||||||
*)
|
|
||||||
echo "::error::Недопустимый LOG_LEVEL: '$LOG_LEVEL'"
|
|
||||||
exit 1
|
|
||||||
;;
|
|
||||||
esac
|
|
||||||
|
|
||||||
- name: Deploy via SSH
|
|
||||||
uses: jt4d-lab/ssh-action@v1
|
|
||||||
env:
|
|
||||||
VERSION: ${{ needs.build.outputs.version }}
|
|
||||||
LOG_LEVEL: ${{ inputs.logLevel }}
|
|
||||||
with:
|
|
||||||
host: ${{ vars.PROD_HOST }}
|
|
||||||
username: ${{ vars.PROD_USER }}
|
|
||||||
key: ${{ secrets.PROD_SSH_PRIVATE_KEY }}
|
|
||||||
port: ${{ vars.PROD_PORT }}
|
|
||||||
workdir: /srv/jt4d
|
|
||||||
files: docker-compose.production.yml
|
|
||||||
envs: VERSION,LOG_LEVEL
|
|
||||||
script_stop: true
|
|
||||||
script: |
|
|
||||||
mv -f docker-compose.production.yml docker-compose.yml
|
|
||||||
|
|
||||||
docker-compose pull --quiet
|
|
||||||
docker-compose down
|
|
||||||
docker-compose up -d
|
|
||||||
|
|
||||||
# Ожидания готовности нет намеренно
|
|
||||||
echo "Список миграций"
|
|
||||||
docker exec jt4d_api node_modules/.bin/typeorm migration:show -d data-source.js
|
|
||||||
echo "Применение миграций"
|
|
||||||
docker exec jt4d_api node_modules/.bin/typeorm migration:run -t each -d data-source.js
|
|
||||||
@@ -1,4 +1,4 @@
|
|||||||
# JT4D Constitution
|
# it-smi Constitution
|
||||||
|
|
||||||
## Core Principles
|
## Core Principles
|
||||||
|
|
||||||
|
|||||||
@@ -97,8 +97,8 @@ yarn nx run api:db-migrations-list # Перегенерировать спис
|
|||||||
|
|
||||||
Определены в `tsconfig.base.json`:
|
Определены в `tsconfig.base.json`:
|
||||||
|
|
||||||
- `@jt4d-platform/api/*` → `apps/api/src/*`
|
- `@it-smi/api/*` → `apps/api/src/*`
|
||||||
- `@jt4d-platform/web/*` → `apps/web/src/*`
|
- `@it-smi/web/*` → `apps/web/src/*`
|
||||||
|
|
||||||
При переименовании воркспейса правятся и `paths`, и `customConditions`.
|
При переименовании воркспейса правятся и `paths`, и `customConditions`.
|
||||||
|
|
||||||
|
|||||||
@@ -95,7 +95,7 @@ yarn nx affected -t <target> # только по затронутым про
|
|||||||
|
|
||||||
## Новый проект из шаблона
|
## Новый проект из шаблона
|
||||||
|
|
||||||
1. **Переименовать воркспейс.** `package.json` (`@jt4d-platform/*`), `project.json`, `nx.json`,
|
1. **Переименовать воркспейс.** `package.json` (`@it-smi/*`), `project.json`, `nx.json`,
|
||||||
`tsconfig.base.json` (`paths` и `customConditions`), `apps/*/package.json`.
|
`tsconfig.base.json` (`paths` и `customConditions`), `apps/*/package.json`.
|
||||||
2. **Настроить доставку.** Домен и registry в `.gitea/workflows/*.yaml`,
|
2. **Настроить доставку.** Домен и registry в `.gitea/workflows/*.yaml`,
|
||||||
`docker-compose.production.yml`, `docker-compose.staging.yml`, `.docuservix.yml`; домен в
|
`docker-compose.production.yml`, `docker-compose.staging.yml`, `.docuservix.yml`; домен в
|
||||||
|
|||||||
@@ -1,5 +1,5 @@
|
|||||||
{
|
{
|
||||||
"name": "@jt4d-platform/api-e2e",
|
"name": "@it-smi/api-e2e",
|
||||||
"version": "0.0.1",
|
"version": "0.0.1",
|
||||||
"private": true
|
"private": true
|
||||||
}
|
}
|
||||||
@@ -1,7 +1,7 @@
|
|||||||
{
|
{
|
||||||
"extends": "../../tsconfig.base.json",
|
"extends": "../../tsconfig.base.json",
|
||||||
"compilerOptions": {
|
"compilerOptions": {
|
||||||
"outDir": "out-tsc/@jt4d-platform/api-e2e",
|
"outDir": "out-tsc/@it-smi/api-e2e",
|
||||||
"esModuleInterop": true,
|
"esModuleInterop": true,
|
||||||
"noUnusedLocals": false,
|
"noUnusedLocals": false,
|
||||||
"noImplicitAny": false
|
"noImplicitAny": false
|
||||||
|
|||||||
@@ -16,7 +16,7 @@ const nodeExternals = require('webpack-node-externals');
|
|||||||
*/
|
*/
|
||||||
module.exports.DenyExternalsPlugin = class DenyExternalsPlugin {
|
module.exports.DenyExternalsPlugin = class DenyExternalsPlugin {
|
||||||
constructor(skipExternalPackages) {
|
constructor(skipExternalPackages) {
|
||||||
// Массив строк-префиксов, например ['@jt4d-platform/']
|
// Массив строк-префиксов, например ['@it-smi/']
|
||||||
this.skipExternalPackages = skipExternalPackages;
|
this.skipExternalPackages = skipExternalPackages;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|||||||
@@ -1,5 +1,5 @@
|
|||||||
{
|
{
|
||||||
"name": "@jt4d-platform/api",
|
"name": "@it-smi/api",
|
||||||
"version": "0.0.1",
|
"version": "0.0.1",
|
||||||
"private": true,
|
"private": true,
|
||||||
"dependencies": {
|
"dependencies": {
|
||||||
|
|||||||
@@ -18,11 +18,11 @@ export default defineConfig({
|
|||||||
],
|
],
|
||||||
resolve: {
|
resolve: {
|
||||||
alias: {
|
alias: {
|
||||||
'@jt4d-platform/api': resolve(import.meta.dirname, 'src'),
|
'@it-smi/api': resolve(import.meta.dirname, 'src'),
|
||||||
},
|
},
|
||||||
},
|
},
|
||||||
test: {
|
test: {
|
||||||
name: '@jt4d-platform/api',
|
name: '@it-smi/api',
|
||||||
globals: true,
|
globals: true,
|
||||||
environment: 'node',
|
environment: 'node',
|
||||||
include: ['src/**/*.{test,spec}.ts'],
|
include: ['src/**/*.{test,spec}.ts'],
|
||||||
|
|||||||
@@ -25,7 +25,7 @@ function createApiWebpackConfig({ output, nxPlugin, plugins = [] }) {
|
|||||||
},
|
},
|
||||||
resolve: {
|
resolve: {
|
||||||
alias: {
|
alias: {
|
||||||
'@jt4d-platform/api': join(__dirname, 'src'),
|
'@it-smi/api': join(__dirname, 'src'),
|
||||||
},
|
},
|
||||||
extensions: ['.ts', '.tsx', '.js', '.jsx', '.json'],
|
extensions: ['.ts', '.tsx', '.js', '.jsx', '.json'],
|
||||||
},
|
},
|
||||||
@@ -42,7 +42,7 @@ function createApiWebpackConfig({ output, nxPlugin, plugins = [] }) {
|
|||||||
// Обязательно в паре с externalDependencies: 'none'. Без плагина webpack
|
// Обязательно в паре с externalDependencies: 'none'. Без плагина webpack
|
||||||
// вкомпилирует второй экземпляр typeorm, и он перестанет быть тем же
|
// вкомпилирует второй экземпляр typeorm, и он перестанет быть тем же
|
||||||
// модулем, что грузит CLI.
|
// модулем, что грузит CLI.
|
||||||
new DenyExternalsPlugin(['@jt4d-platform/']),
|
new DenyExternalsPlugin(['@it-smi/']),
|
||||||
...plugins,
|
...plugins,
|
||||||
],
|
],
|
||||||
};
|
};
|
||||||
|
|||||||
@@ -1,5 +1,5 @@
|
|||||||
{
|
{
|
||||||
"name": "@jt4d-platform/web",
|
"name": "@it-smi/web",
|
||||||
"version": "0.0.1",
|
"version": "0.0.1",
|
||||||
"private": true,
|
"private": true,
|
||||||
"dependencies": {
|
"dependencies": {
|
||||||
|
|||||||
@@ -19,6 +19,6 @@ describe('App', () => {
|
|||||||
<App />
|
<App />
|
||||||
</BrowserRouter>,
|
</BrowserRouter>,
|
||||||
);
|
);
|
||||||
expect(getAllByText(/Hello @jt4d-platform\/web/i).length > 0).toBeTruthy();
|
expect(getAllByText(/Hello @it-smi\/web/i).length > 0).toBeTruthy();
|
||||||
});
|
});
|
||||||
});
|
});
|
||||||
@@ -5,7 +5,7 @@ import { HealthPage } from '../pages/HealthPage';
|
|||||||
export function App() {
|
export function App() {
|
||||||
return (
|
return (
|
||||||
<div>
|
<div>
|
||||||
<h1 className="text-2xl font-bold">Hello @jt4d-platform/web</h1>
|
<h1 className="text-2xl font-bold">Hello @it-smi/web</h1>
|
||||||
|
|
||||||
<nav role="navigation">
|
<nav role="navigation">
|
||||||
<ul>
|
<ul>
|
||||||
|
|||||||
@@ -34,7 +34,7 @@ export default defineConfig(() => ({
|
|||||||
},
|
},
|
||||||
},
|
},
|
||||||
test: {
|
test: {
|
||||||
name: '@jt4d-platform/web',
|
name: '@it-smi/web',
|
||||||
watch: false,
|
watch: false,
|
||||||
globals: true,
|
globals: true,
|
||||||
environment: 'jsdom',
|
environment: 'jsdom',
|
||||||
|
|||||||
@@ -1,55 +0,0 @@
|
|||||||
services:
|
|
||||||
web:
|
|
||||||
container_name: jt4d_web
|
|
||||||
image: git.jt4d.ru/jt4d/jt4d/web:${VERSION}
|
|
||||||
restart: unless-stopped
|
|
||||||
ports:
|
|
||||||
- '80:80'
|
|
||||||
- '443:443'
|
|
||||||
volumes:
|
|
||||||
- caddy_data:/data
|
|
||||||
- caddy_config:/config
|
|
||||||
|
|
||||||
api:
|
|
||||||
container_name: jt4d_api
|
|
||||||
image: git.jt4d.ru/jt4d/jt4d/api:${VERSION}
|
|
||||||
restart: unless-stopped
|
|
||||||
depends_on:
|
|
||||||
postgres:
|
|
||||||
condition: service_healthy
|
|
||||||
env_file:
|
|
||||||
- .env
|
|
||||||
environment:
|
|
||||||
NODE_ENV: production
|
|
||||||
LOG_LEVEL: ${LOG_LEVEL:-warn}
|
|
||||||
|
|
||||||
POSTGRES_HOST: postgres
|
|
||||||
POSTGRES_PORT: 5432
|
|
||||||
POSTGRES_USER: aigeo_app
|
|
||||||
POSTGRES_PASSWORD: ${POSTGRES_APP_PASSWORD}
|
|
||||||
POSTGRES_DB: aigeo
|
|
||||||
|
|
||||||
postgres:
|
|
||||||
container_name: jt4d_postgres
|
|
||||||
image: postgres:16
|
|
||||||
restart: unless-stopped
|
|
||||||
env_file:
|
|
||||||
- .env
|
|
||||||
environment:
|
|
||||||
POSTGRES_DB: ${POSTGRES_DB:-aigeo}
|
|
||||||
POSTGRES_USER: ${POSTGRES_USER:-postgres}
|
|
||||||
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-postgres}
|
|
||||||
POSTGRES_APP_USER: ${POSTGRES_APP_USER:-aigeo_app}
|
|
||||||
POSTGRES_APP_PASSWORD: ${POSTGRES_APP_PASSWORD:-postgres}
|
|
||||||
volumes:
|
|
||||||
- pg_data:/var/lib/postgresql/data
|
|
||||||
healthcheck:
|
|
||||||
test: ['CMD-SHELL', 'pg_isready -U ${POSTGRES_USER:-postgres}']
|
|
||||||
interval: 5s
|
|
||||||
timeout: 5s
|
|
||||||
retries: 5
|
|
||||||
|
|
||||||
volumes:
|
|
||||||
pg_data:
|
|
||||||
caddy_data:
|
|
||||||
caddy_config:
|
|
||||||
@@ -1,9 +1,9 @@
|
|||||||
services:
|
services:
|
||||||
web:
|
web:
|
||||||
container_name: jt4d_${BRANCH}_web
|
container_name: it-smi_${BRANCH}_web
|
||||||
image: git.jt4d.ru/jt4d/jt4d/web:${BRANCH}
|
image: git.jt4d.ru/public/it-smi/web:${BRANCH}
|
||||||
labels:
|
labels:
|
||||||
caddy: ${BRANCH}.jt4d.jt4d.ru.net
|
caddy: ${BRANCH}.it-smi.jt4d.ru.net
|
||||||
caddy.reverse_proxy: '{{upstreams 80}}'
|
caddy.reverse_proxy: '{{upstreams 80}}'
|
||||||
restart: always
|
restart: always
|
||||||
init: true
|
init: true
|
||||||
@@ -11,8 +11,8 @@ services:
|
|||||||
- 'net'
|
- 'net'
|
||||||
|
|
||||||
api:
|
api:
|
||||||
container_name: jt4d_${BRANCH}_api
|
container_name: it-smi_${BRANCH}_api
|
||||||
image: git.jt4d.ru/jt4d/jt4d/api:${BRANCH}
|
image: git.jt4d.ru/public/it-smi/api:${BRANCH}
|
||||||
environment:
|
environment:
|
||||||
# POSTGRES_* пишет staging-db-postgres в .env каталога деплоя.
|
# POSTGRES_* пишет staging-db-postgres в .env каталога деплоя.
|
||||||
# Синтаксис ${X:-} намеренно необязательный: ${X:?} валит и pull, и down.
|
# Синтаксис ${X:-} намеренно необязательный: ${X:?} валит и pull, и down.
|
||||||
|
|||||||
@@ -1,167 +0,0 @@
|
|||||||
# Слои API
|
|
||||||
|
|
||||||
Модуль — единица организации кода в `apps/api`: внутри него код разложен по слоям, а наружу он
|
|
||||||
поставляет только то, что осознанно экспортирует.
|
|
||||||
|
|
||||||
Слоёв три, и зависимости между ними идут строго в одну сторону:
|
|
||||||
|
|
||||||
```
|
|
||||||
Controller → Service → Data Access Layer
|
|
||||||
```
|
|
||||||
|
|
||||||
Сквозь все три слоя проходят два **контракта данных**:
|
|
||||||
|
|
||||||
- **DTO** — форма данных на границе HTTP: что приходит в запросе и что уходит в ответе.
|
|
||||||
- **Entities** — форма данных на границе БД: из чего состоит таблица.
|
|
||||||
|
|
||||||
Модуль — не слой, а рамка, которая собирает эти части и определяет, что из них видно снаружи.
|
|
||||||
|
|
||||||
## Controllers
|
|
||||||
|
|
||||||
**Тонкий контроллер.**
|
|
||||||
|
|
||||||
Контроллер — точка входа HTTP. Он принимает запрос, объявляет контракт ручки для Swagger, проверяет
|
|
||||||
формат входных данных и делегирует работу сервису. При этом контроллер не принимает доменных
|
|
||||||
решений, не вычисляет и не агрегирует данные: почти всё тело метода занимает объявление API.
|
|
||||||
|
|
||||||
Контроль доступа на этом уровне **декларативный**: `JwtAuthGuard`, `RolesGuard` с `@Roles(...)`,
|
|
||||||
`ProjectAccessGuard` с декоратором роли в проекте. Проверка «пользователь — админ?» или «есть ли
|
|
||||||
доступ к проекту?» читается из декораторов, а не вычисляется в теле метода. Валидация формата
|
|
||||||
подключается пайпом **на конкретный параметр** (`@Body(...)`, `@Query(...)`), а не на весь метод: у
|
|
||||||
проекта нет глобального `ValidationPipe`.
|
|
||||||
|
|
||||||
**Входит:**
|
|
||||||
|
|
||||||
- Контроль доступа на основе декларативных систем (guards, роли, декораторы)
|
|
||||||
- Описание API (Swagger-декораторы, HTTP-статусы ответов)
|
|
||||||
- Проверка формата входных данных (пайпы, DTO)
|
|
||||||
|
|
||||||
**Не входит:**
|
|
||||||
|
|
||||||
- Бизнес-логика
|
|
||||||
- Проверка входных данных на основе бизнес-правил
|
|
||||||
- Транзакции
|
|
||||||
- Запросы к БД
|
|
||||||
|
|
||||||
## Services
|
|
||||||
|
|
||||||
**Бизнес-логика и оркестрация.**
|
|
||||||
|
|
||||||
Сервис — место, где принимаются решения. Здесь проверяются бизнес-правила, бросаются доменные
|
|
||||||
ошибки, оркестрируются вызовы DAL и публичных сервисов других модулей, открываются транзакции и
|
|
||||||
пишутся бизнес-события. Сложный домен делится на вложенные модули — по одному на поддомен (пример —
|
|
||||||
`billing/modules/*`), а не разрастается в один сервис на весь домен.
|
|
||||||
|
|
||||||
В публичный API модуля попадают сервисы, но не обязательно все: `exports` перечисляет их явно.
|
|
||||||
Другие модули импортируют только сервисы, поэтому правило «доступ к данным чужого домена — через его
|
|
||||||
публичный сервис» выполняется именно здесь, на уровне сервисов.
|
|
||||||
|
|
||||||
**Входит:**
|
|
||||||
|
|
||||||
- Бизнес-логика
|
|
||||||
- Оркестрация: вызовы своего DAL и публичных сервисов других модулей
|
|
||||||
- Транзакции (через `DataSource` — единственное исключение из правила «TypeORM только в DAL»)
|
|
||||||
- Контроль доступа на основе сложных бизнес-правил
|
|
||||||
- Проверка входных данных на основе бизнес-правил
|
|
||||||
- Логирование бизнес-событий
|
|
||||||
- Вызовы внешних систем — после коммита транзакции
|
|
||||||
|
|
||||||
**Не входит:**
|
|
||||||
|
|
||||||
- Выполнение запросов к БД
|
|
||||||
- Прямой доступ к репозиториям и `QueryBuilder` TypeORM
|
|
||||||
- HTTP-специфика (объекты `Request`/`Response`, HTTP-статусы)
|
|
||||||
|
|
||||||
## Data Access Layer
|
|
||||||
|
|
||||||
**Абстракция над БД.**
|
|
||||||
|
|
||||||
DAL знает о бизнес-сущностях и предоставляет к ним удобный API. Сервис вызывает осмысленный метод и
|
|
||||||
получает данные, не зная, как именно они достаются. DAL возвращает сущности как есть — отдельного
|
|
||||||
слоя доменных моделей и мапперов в проекте нет.
|
|
||||||
|
|
||||||
Минимум бизнес-логики: решения принимает сервис. Исключение — логика, которую **необходимо выполнять
|
|
||||||
на стороне БД**: агрегаты, массовые `UPDATE`/`upsert`, выборки с блокировкой, оконные функции. Ради
|
|
||||||
них DAL может выполнять чужую таблицу через join вместо похода в чужой сервис.
|
|
||||||
|
|
||||||
DAL — **приватная часть модуля**: он не попадает в `exports` и недоступен другим модулям ни при
|
|
||||||
каких условиях, даже родительскому модулю. Доступ к данным чужого домена — только через публичные
|
|
||||||
сервисы модуля-владельца.
|
|
||||||
|
|
||||||
Высокоуровневый API к данным выглядит так: `findById`, `getActiveProjects`, `softRemoveComment`,
|
|
||||||
`getCommentsWithAuthors` — за именем стоит намерение, а не способ выборки (имена условные, они
|
|
||||||
показывают уровень абстракции, а не конкретный модуль). Методы добавляются по мере необходимости, а
|
|
||||||
не заранее «чтобы было». Метод принимает опциональный `manager?: EntityManager`: открывать
|
|
||||||
транзакцию или нет — решает вызывающий, DAL лишь работает с тем контекстом, который ему передали.
|
|
||||||
|
|
||||||
Транзакции, приватность модуля и логика на стороне БД разобраны подробно в
|
|
||||||
[слое доступа к данным](30-data-access.md).
|
|
||||||
|
|
||||||
**Входит:**
|
|
||||||
|
|
||||||
- Выполнение запросов
|
|
||||||
- Логика, которую необходимо выполнять на стороне БД
|
|
||||||
|
|
||||||
**Не входит:**
|
|
||||||
|
|
||||||
- Бизнес-логика (кроме логики, выполняемой в БД)
|
|
||||||
- Открытие транзакций
|
|
||||||
- Знание о HTTP и о том, кто его вызвал
|
|
||||||
|
|
||||||
## DTO
|
|
||||||
|
|
||||||
**Контракт входа и валидация формата.**
|
|
||||||
|
|
||||||
DTO описывает форму данных на границе HTTP: тело запроса, query-параметры, тело ответа. В нём
|
|
||||||
объявлены поля, Swagger-описание (`@ApiProperty`) и class-validator-декораторы формата. Это описание
|
|
||||||
данных, а не поведение: своих методов у DTO нет, кроме статической фабрики `from` — она переводит в
|
|
||||||
форму ответа то, что вернул сервис, и держит белый список полей рядом с контрактом. Один DTO — один
|
|
||||||
контракт ручки.
|
|
||||||
|
|
||||||
Валидация формата (тип, обязательность, диапазон, формат строки) живёт здесь; проверка на основе
|
|
||||||
бизнес-правил — уже в сервисе. DTO описывает и вход, и выход: response-модели вроде
|
|
||||||
`*-response.dto.ts` кладутся в те же `dto/` и подставляются в `@ApiOkResponse({ type: ... })`.
|
|
||||||
Отдельного слоя ответов нет; часть модулей держит свои read-модели плоскими интерфейсами в
|
|
||||||
`*.types.ts`.
|
|
||||||
|
|
||||||
**Входит:**
|
|
||||||
|
|
||||||
- Форма входных и выходных данных
|
|
||||||
- Валидация формата
|
|
||||||
- Swagger-описание полей
|
|
||||||
- Перевод данных в форму ответа — статическая фабрика `from` у response-моделей
|
|
||||||
|
|
||||||
**Не входит:**
|
|
||||||
|
|
||||||
- Бизнес-логика
|
|
||||||
- Обращения к БД
|
|
||||||
- Решения на основе бизнес-правил
|
|
||||||
- Собственные методы, кроме `from`: входной DTO заполняет `ValidationPipe`, а не код самого DTO, а
|
|
||||||
считать и решать, что отдавать, — дело сервиса
|
|
||||||
|
|
||||||
## Entities
|
|
||||||
|
|
||||||
**Схема таблицы, а не модель поведения.**
|
|
||||||
|
|
||||||
TypeORM-сущность описывает таблицу: колонки, типы, связи, индексы и имя таблицы. Имя таблицы —
|
|
||||||
константа `*_TABLE_NAME`, объявленная рядом с сущностью и используемая в коде приложения. Сущность
|
|
||||||
содержит только поля и связи — `Active Record` не используется, методов сохранения или поиска на ней
|
|
||||||
нет.
|
|
||||||
|
|
||||||
Бизнес-логики и валидации в сущности тоже нет: и то, и другое живёт в сервисе, а структура таблицы —
|
|
||||||
здесь. Соглашения об именовании, расположении и связях описаны в
|
|
||||||
[сущностях, таблицах и колонках](10-persistence.md).
|
|
||||||
|
|
||||||
**Входит:**
|
|
||||||
|
|
||||||
- Схема таблицы: колонки и типы
|
|
||||||
- Связи и правила `onDelete`
|
|
||||||
- Индексы
|
|
||||||
- Имя таблицы
|
|
||||||
|
|
||||||
**Не входит:**
|
|
||||||
|
|
||||||
- Бизнес-логика
|
|
||||||
- Методы `save`/`find` и любой доступ к данным
|
|
||||||
- Валидация входных данных
|
|
||||||
- Правила доступа
|
|
||||||
@@ -1,224 +0,0 @@
|
|||||||
# Слои web
|
|
||||||
|
|
||||||
`apps/web` — React-приложение. Его код разложен по слоям, и зависимости между слоями идут строго в
|
|
||||||
одну сторону:
|
|
||||||
|
|
||||||
```
|
|
||||||
app → pages → @modules → common
|
|
||||||
```
|
|
||||||
|
|
||||||
Слой слева знает о слоях справа и пользуется ими. Обратное запрещено: `common` не знает, где
|
|
||||||
применён и по чьей воле вызван, а `pages` не знает о `app`.
|
|
||||||
|
|
||||||
Слой — это директория: имя слоя и есть имя директории. Одни слои существуют в проекте в одном
|
|
||||||
экземпляре, других — столько, сколько модулей.
|
|
||||||
|
|
||||||
```
|
|
||||||
src/
|
|
||||||
├── app/
|
|
||||||
├── pages/
|
|
||||||
├── modules/
|
|
||||||
│ └── <домен>/
|
|
||||||
│ ├── widgets/
|
|
||||||
│ ├── entities/
|
|
||||||
│ └── modules/
|
|
||||||
└── common/
|
|
||||||
```
|
|
||||||
|
|
||||||
`@modules` — служебная метка места слоёв модулей в общей схеме, а не имя директории. Слои модулей
|
|
||||||
(`widgets`, `entities`) повторяются в каждом модуле на любой глубине; принадлежность к слою модуля
|
|
||||||
задаёт первое имя на пути от корня модуля.
|
|
||||||
|
|
||||||
**Модуль** — не слой, а рамка. `modules/<домен>` собирает свои `widgets` и `entities` и определяет,
|
|
||||||
что из них видно снаружи, — тем же способом, каким это делает модуль в
|
|
||||||
[слоях API](01-api-layers.md). Поддомен — такая же рамка, вложенная внутрь модуля.
|
|
||||||
|
|
||||||
## app
|
|
||||||
|
|
||||||
**Точка входа и оболочка.**
|
|
||||||
|
|
||||||
`app` — внешний край приложения. Он монтирует React, объявляет маршруты и их защиту, держит
|
|
||||||
глобальные провайдеры и рисует оболочку: шапку, подвал, лейауты, общие для целой группы страниц.
|
|
||||||
|
|
||||||
Сюда попадает всё, что относится к приложению целиком, а не к отдельному экрану: например, баннер
|
|
||||||
согласия на cookie. `app` — единственный слой, который видит приложение снизу доверху, и его самого
|
|
||||||
не импортирует никто.
|
|
||||||
|
|
||||||
**Входит:**
|
|
||||||
|
|
||||||
- Точка входа приложения
|
|
||||||
- Маршруты и их защита
|
|
||||||
- Глобальные провайдеры
|
|
||||||
- Оболочка и лейауты страниц
|
|
||||||
- Элементы, относящиеся к приложению целиком
|
|
||||||
|
|
||||||
**Не входит:**
|
|
||||||
|
|
||||||
- Конкретные страницы и их содержимое
|
|
||||||
- Доменные данные и сценарии
|
|
||||||
- Формы, модалки и прочие блоки интерфейса
|
|
||||||
|
|
||||||
## pages
|
|
||||||
|
|
||||||
**Общий вид страницы и расстановка блоков.**
|
|
||||||
|
|
||||||
`pages` отвечает за то, как страница выглядит целиком, и объявляет **хлебные крошки**. Страница
|
|
||||||
решает, какие виджеты на ней стоят, в каком они порядке и как расположены, — и задаёт каждому
|
|
||||||
начальные данные: идентификатор из маршрута, стартовое значение фильтра, активную вкладку.
|
|
||||||
|
|
||||||
Собственное состояние страницы допустимо ровно одно — то, которым страница **связывает виджеты**
|
|
||||||
между собой. Виджеты друг о друге не знают, поэтому место их встречи — страница. Всё, что является
|
|
||||||
бизнес-логикой или передачей сообщений между виджетами, странице не принадлежит.
|
|
||||||
|
|
||||||
**Входит:**
|
|
||||||
|
|
||||||
- Композиция виджетов и их расположение на странице
|
|
||||||
- Хлебные крошки
|
|
||||||
- Начальные данные виджетов
|
|
||||||
- Состояние страницы как связь между виджетами
|
|
||||||
|
|
||||||
**Не входит:**
|
|
||||||
|
|
||||||
- Бизнес-логика
|
|
||||||
- Собственное отображение доменных данных — это дело виджетов
|
|
||||||
- Передача сообщений между виджетами
|
|
||||||
- Работа с API
|
|
||||||
|
|
||||||
## @modules: widgets
|
|
||||||
|
|
||||||
**Самостоятельный блок интерфейса.**
|
|
||||||
|
|
||||||
Виджет сам добывает свои данные и сам держит своё состояние: открытие модалок, активную вкладку,
|
|
||||||
раскрытые строки, значения полей формы. Наружу он поставляет готовый блок, а внутрь принимает только
|
|
||||||
параметры — идентификаторы и начальные значения, — поэтому страница может поставить виджет, ничего
|
|
||||||
не зная о том, что внутри.
|
|
||||||
|
|
||||||
Один виджет — один законченный участок работы: форма входа модуля `auth` проверяет поле, держит
|
|
||||||
ошибку и статус отправки, а страница передаёт ей только различающиеся тексты.
|
|
||||||
|
|
||||||
Виджет собирается из `entities` и `common` и о других виджетах на странице не знает: связать два
|
|
||||||
виджета — задача `pages`. Слои выше модуля — `pages` и `app` — виджету недоступны.
|
|
||||||
|
|
||||||
**Входит:**
|
|
||||||
|
|
||||||
- Загрузка своих данных
|
|
||||||
- Своё состояние: модалки, вкладки, раскрытия, промежуточные значения форм
|
|
||||||
- Композиция `entities` и `common`
|
|
||||||
- Действия пользователя в границах блока
|
|
||||||
|
|
||||||
**Не входит:**
|
|
||||||
|
|
||||||
- Хлебные крошки и общая раскладка страницы
|
|
||||||
- Знание о других виджетах
|
|
||||||
- Доменные правила
|
|
||||||
|
|
||||||
## @modules: entities
|
|
||||||
|
|
||||||
**Показ доменной сущности.**
|
|
||||||
|
|
||||||
Entity отвечает за то, как выглядит одна доменная сущность или одно значение: `TokenValue`
|
|
||||||
показывает значение токенов, `SummaryRow` — строку сводки. Данные приходят пропсами; entity ничего
|
|
||||||
не загружает и ничего не меняет. Она отвечает только за вид и форматирование того, что ей передали:
|
|
||||||
числа, даты, статусы.
|
|
||||||
|
|
||||||
**Входит:**
|
|
||||||
|
|
||||||
- Показ одной доменной сущности или значения
|
|
||||||
- Форматирование значения: числа, даты, статусы
|
|
||||||
- Локальное состояние отображения
|
|
||||||
|
|
||||||
**Не входит:**
|
|
||||||
|
|
||||||
- Загрузка данных
|
|
||||||
- Действия над сущностью: создание, изменение, удаление
|
|
||||||
- Композиция нескольких сущностей
|
|
||||||
- Знание о странице и о том, где entity показана
|
|
||||||
|
|
||||||
## common
|
|
||||||
|
|
||||||
**Общий слой.**
|
|
||||||
|
|
||||||
`common` — фундамент: UI-примитивы (кнопка, диалог, таблица), вызовы API, типы, утилиты
|
|
||||||
форматирования, переводы. Всё это переиспользуется слоями выше и не принадлежит ни одному сценарию.
|
|
||||||
|
|
||||||
Слой ничего не знает о том, где и для чего его применили. Примитив интерфейса не подписывается на
|
|
||||||
домен, а модуль API не решает, что показать пользователю при ошибке: решение принимает тот, кто его
|
|
||||||
вызвал.
|
|
||||||
|
|
||||||
`common` — нижний слой: его берут все, он не берёт никого.
|
|
||||||
|
|
||||||
**Входит:**
|
|
||||||
|
|
||||||
- UI-примитивы
|
|
||||||
- Вызовы API
|
|
||||||
- Типы и утилиты
|
|
||||||
- Переводы
|
|
||||||
- Форматирование значений
|
|
||||||
|
|
||||||
**Не входит:**
|
|
||||||
|
|
||||||
- Знание о том, где и в каком сценарии он применён
|
|
||||||
- Композиция доменного интерфейса
|
|
||||||
- Решения о том, что показать и что сделать при ошибке
|
|
||||||
|
|
||||||
## Баррели: публичный API границы
|
|
||||||
|
|
||||||
Граница — модуль, слой, сложный компонент из нескольких файлов — объявляет публичный API через
|
|
||||||
`index.ts` и только через него отдаёт содержимое наружу. Импорт внутреннего файла в обход барреля
|
|
||||||
запрещён.
|
|
||||||
|
|
||||||
```ts
|
|
||||||
// apps/web/src/common/index.ts
|
|
||||||
export * from './lib';
|
|
||||||
export * from './ui';
|
|
||||||
|
|
||||||
// apps/web/src/common/lib/index.ts
|
|
||||||
export { applyTheme, getTheme, subscribeToTheme, toggleTheme, type Theme } from './theme';
|
|
||||||
export { cn } from './utils';
|
|
||||||
```
|
|
||||||
|
|
||||||
Правила барреля:
|
|
||||||
|
|
||||||
- Только явный список именованных реэкспортов. `export *` допустим лишь от вложенной директории, у
|
|
||||||
которой уже есть собственный `index.ts`.
|
|
||||||
- Никакого исполняемого кода: ни импортов стилей, ни инициализации, ни оборачивания компонентов.
|
|
||||||
- Импорт из своего или вышестоящего барреля запрещён; внутри директории файлы импортируют друг друга
|
|
||||||
относительными путями.
|
|
||||||
|
|
||||||
Межграничный импорт идёт через алиас `@jt4d-platform/web/*`, который объявлен в `tsconfig.base.json`
|
|
||||||
и разрешается в `vite.config.ts` через `resolve.alias`:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
import { Button, usePageBreadcrumbs } from '@jt4d-platform/web/common';
|
|
||||||
import { AuthForm } from '@jt4d-platform/web/modules/auth';
|
|
||||||
import { HealthPage } from '@jt4d-platform/web/pages';
|
|
||||||
```
|
|
||||||
|
|
||||||
Обход барреля ловится линтером правилом `weld/no-barrel-bypass` из `eslint-plugin-weld`; оно
|
|
||||||
включено в `apps/web/eslint.config.mjs`.
|
|
||||||
|
|
||||||
## Приватность частей директории
|
|
||||||
|
|
||||||
Часть директории объявляется приватной явно, а не договорённостью на словах:
|
|
||||||
|
|
||||||
- публичный API директории — её баррель: файл, который баррель не реэкспортирует, наружу не
|
|
||||||
отдаётся;
|
|
||||||
- приватная группа файлов лежит в каталоге с точным именем `internal` вместе со всем содержимым;
|
|
||||||
- приватное доступно только содержимому непосредственного родителя;
|
|
||||||
- владелец может опубликовать часть реализации через свой баррель, но путь приватной директории от
|
|
||||||
этого не открывается.
|
|
||||||
|
|
||||||
Пример — хук формы входа: `modules/auth/widgets/auth-form/useAuthForm.ts`. Он используется
|
|
||||||
компонентом `AuthForm.tsx` из той же директории и не попадает в баррель виджета.
|
|
||||||
|
|
||||||
## Модули и видимость
|
|
||||||
|
|
||||||
Модули верхнего уровня лежат в `src/modules/<домен>`, вложенные — в контейнере `modules/` внутри
|
|
||||||
родительского модуля. Контейнер слоем не является и собственного публичного API не имеет.
|
|
||||||
|
|
||||||
Видимость определяется положением в дереве: модулю доступны его предки, братья, братья предков и
|
|
||||||
непосредственные дочерние модули. Доступ к «племянникам» запрещён: он раскрывает внутреннюю
|
|
||||||
структуру ветки. Дублирование логики между модулями не допускается — общая часть переносится в
|
|
||||||
`common` или в модуль, доступный по дереву.
|
|
||||||
|
|
||||||
Пример: `modules/auth` отдаёт наружу только `AuthForm`, страницы берут его из барреля модуля.
|
|
||||||
@@ -1,99 +0,0 @@
|
|||||||
# Сущности, таблицы и колонки
|
|
||||||
|
|
||||||
## Расположение сущностей
|
|
||||||
|
|
||||||
Все TypeORM-сущности модуля лежат в подпапке `entities/` в корне модуля:
|
|
||||||
|
|
||||||
```
|
|
||||||
apps/api/src/contests/
|
|
||||||
├── dto/
|
|
||||||
├── entities/
|
|
||||||
│ └── contest.entity.ts
|
|
||||||
├── contests.controller.ts
|
|
||||||
├── contests.module.ts
|
|
||||||
└── contests.service.ts
|
|
||||||
```
|
|
||||||
|
|
||||||
- Правило без исключений: даже если сущность в модуле одна, она всё равно в `entities/`. Иначе при
|
|
||||||
добавлении второй сущности пришлось бы переносить первую и править все её импорты.
|
|
||||||
- Имя файла — `<сущность>.entity.ts` в kebab-case (`project-member.entity.ts`).
|
|
||||||
- Один файл — одна сущность.
|
|
||||||
|
|
||||||
## Имя таблицы — единая точка правды
|
|
||||||
|
|
||||||
Рядом с сущностью, в том же файле, объявляется экспортируемая константа с именем таблицы, и
|
|
||||||
`@Entity` использует её:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
export const CONTESTS_TABLE_NAME = 'contests';
|
|
||||||
|
|
||||||
@Entity({ name: CONTESTS_TABLE_NAME })
|
|
||||||
export class Contest {
|
|
||||||
// ...
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
- Константа именуется `<СУЩНОСТЬ>_TABLE_NAME` в SCREAMING_SNAKE_CASE.
|
|
||||||
- Значение — `snake_case`, множественное число (`contests`, `project_members`).
|
|
||||||
- `@Entity()` без явного `name` не используется: имя таблицы не должно выводиться из имени класса —
|
|
||||||
переименование класса тогда молча меняет схему.
|
|
||||||
|
|
||||||
Константа — единая точка правды об имени таблицы для кода приложения: `@Entity`, DAL, raw-SQL,
|
|
||||||
алиасы `createQueryBuilder`, утилиты очистки в тестах. Строковый литерал с именем таблицы за
|
|
||||||
пределами объявления константы в коде приложения не пишется.
|
|
||||||
|
|
||||||
### Миграции константу не используют
|
|
||||||
|
|
||||||
Миграция — снимок схемы на момент, когда её написали, и она обязана оставаться рабочей независимо от
|
|
||||||
того, что стало с кодом дальше. Поэтому **в миграции имя таблицы пишется строковым литералом**.
|
|
||||||
|
|
||||||
Пример из репозитория: коммит `b710c1b9` удалил модуль подписок вместе с файлом
|
|
||||||
`subscriptions/subscription-plan.entity.ts` — а миграции `1774000000000-add-subscription-plans.ts` и
|
|
||||||
`1788825600000-drop-subscriptions-and-metrics-limits.ts` никуда не делись и по-прежнему создают и
|
|
||||||
удаляют таблицу `subscription_plans`. Импортируй они константу из удалённого файла — сборка встала
|
|
||||||
бы целиком: миграции попадают в бандл `data-source.js` статическими импортами.
|
|
||||||
|
|
||||||
Обратная сторона того же правила: значение константы менять **можно**, миграции на него не смотрят.
|
|
||||||
Переименование таблицы — это новое значение константы плюс миграция с двумя литералами:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
await queryRunner.renameTable('contests', 'brand_contests');
|
|
||||||
```
|
|
||||||
|
|
||||||
## Имена колонок
|
|
||||||
|
|
||||||
Колонки — `camelCase` (`logoId`, `totalBudget`, `createdAt`), в отличие от `snake_case` у таблиц.
|
|
||||||
Это не разнобой, а следствие дефолтной стратегии именования TypeORM: имя колонки выводится из имени
|
|
||||||
свойства как есть, и в `@Column()` его не дублируют. С таблицей так нельзя — её имя выводилось бы из
|
|
||||||
имени класса, — поэтому она и задаётся явно.
|
|
||||||
|
|
||||||
Практическое следствие: Postgres приводит неэкранированный идентификатор к нижнему регистру, так что
|
|
||||||
в raw-SQL такая колонка пишется только в двойных кавычках:
|
|
||||||
|
|
||||||
```sql
|
|
||||||
ALTER TABLE "contests" DROP COLUMN IF EXISTS "totalBudget";
|
|
||||||
```
|
|
||||||
|
|
||||||
## Nullable-колонки — явный `type`
|
|
||||||
|
|
||||||
Если тип свойства — объединение с `null`, тип колонки задаётся в декораторе явно:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
@Column({ type: 'varchar', nullable: true })
|
|
||||||
banReason: string | null;
|
|
||||||
|
|
||||||
@Column({ type: 'timestamp', nullable: true })
|
|
||||||
emailVerificationTokenExpires: Date | null;
|
|
||||||
```
|
|
||||||
|
|
||||||
Без `type` TypeORM выводит тип колонки из метаданных декоратора (`design:type`), а для объединения
|
|
||||||
`string | null` TypeScript отдаёт `Object` — вывести из него тип колонки нельзя, и приложение падает
|
|
||||||
на старте с `ColumnTypeUndefinedError` ещё до первого запроса. Ошибка вылезает только при реальном
|
|
||||||
поднятии контекста: юнит-тесты сервиса метаданные сущностей не строят и остаются зелёными.
|
|
||||||
|
|
||||||
Само объявление `string | null` при этом предпочтительнее, чем `string` у nullable-колонки: тип
|
|
||||||
сущности должен отражать то, что лежит в базе, иначе «пустое» значение приходится проверять вопреки
|
|
||||||
типу. Схему явный `type` не меняет — `varchar` без длины это то же `character varying`, что и в
|
|
||||||
миграции, — так что переход на `| null` у уже существующей колонки миграции не требует.
|
|
||||||
|
|
||||||
Как писать сами миграции — [Написание миграций](20-migrations.md).
|
|
||||||
@@ -1,131 +0,0 @@
|
|||||||
# Написание миграций
|
|
||||||
|
|
||||||
Здесь — как **писать** миграцию. Про то, как список миграций собирается, как они применяются на
|
|
||||||
деплое и какие есть команды, см. [Миграции базы данных](../90-deploy/10-migrations.md).
|
|
||||||
|
|
||||||
## DDL пишется через API TypeORM, а не строкой SQL
|
|
||||||
|
|
||||||
Схема меняется методами `QueryRunner` с объектами `Table` / `TableColumn`. Строка SQL в
|
|
||||||
`queryRunner.query()` — крайняя мера, а не способ по умолчанию.
|
|
||||||
|
|
||||||
```ts
|
|
||||||
import { MigrationInterface, QueryRunner, Table } from 'typeorm';
|
|
||||||
|
|
||||||
export class AddContests1790000000000 implements MigrationInterface {
|
|
||||||
name = 'AddContests1790000000000';
|
|
||||||
|
|
||||||
public async up(queryRunner: QueryRunner): Promise<void> {
|
|
||||||
await queryRunner.createTable(
|
|
||||||
new Table({
|
|
||||||
name: 'contests',
|
|
||||||
columns: [
|
|
||||||
{
|
|
||||||
name: 'id',
|
|
||||||
type: 'int',
|
|
||||||
isPrimary: true,
|
|
||||||
isGenerated: true,
|
|
||||||
generationStrategy: 'increment',
|
|
||||||
},
|
|
||||||
{ name: 'title', type: 'varchar', length: '255', isUnique: true },
|
|
||||||
{ name: 'logoId', type: 'varchar', length: '64', isNullable: true },
|
|
||||||
{ name: 'description', type: 'text' },
|
|
||||||
{ name: 'totalBudget', type: 'int' },
|
|
||||||
{ name: 'createdAt', type: 'timestamp', default: 'now()' },
|
|
||||||
{ name: 'updatedAt', type: 'timestamp', default: 'now()' },
|
|
||||||
],
|
|
||||||
}),
|
|
||||||
);
|
|
||||||
}
|
|
||||||
|
|
||||||
public async down(queryRunner: QueryRunner): Promise<void> {
|
|
||||||
await queryRunner.dropTable('contests');
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
У `createTable` есть второй аргумент `ifNotExist`, и ставить его в `true` не надо: он глушит ровно
|
|
||||||
ту ошибку, ради которой существует [проверка перед коммитом](#проверка-перед-коммитом) — если `down`
|
|
||||||
отработал не полностью и оставил таблицу, повторный `up` с `ifNotExist: true` пройдёт мимо дефекта
|
|
||||||
молча. Дважды одна и та же миграция не применяется и без флага, за этим следит таблица `migrations`.
|
|
||||||
|
|
||||||
Имя таблицы — строковый литерал: константа `*_TABLE_NAME` из файла сущности в миграциях не
|
|
||||||
используется, см.
|
|
||||||
[Миграции константу не используют](10-persistence.md#миграции-константу-не-используют).
|
|
||||||
|
|
||||||
### `migration:generate` — это черновик
|
|
||||||
|
|
||||||
`typeorm migration:generate` (запуск — в
|
|
||||||
[Как добавить миграцию](../90-deploy/10-migrations.md#как-добавить-миграцию)) всегда выдаёт тело из
|
|
||||||
строк `queryRunner.query(...)`, иначе он не умеет. Генератор полезен тем, что показывает полный
|
|
||||||
список расхождений схемы с сущностями — руками их легко не заметить. Но сгенерированный файл
|
|
||||||
дописывается до конца: DDL переписывается на методы `QueryRunner`, строкой SQL остаётся только то,
|
|
||||||
что под них не подходит.
|
|
||||||
|
|
||||||
### Когда допустим `queryRunner.query()`
|
|
||||||
|
|
||||||
Там, где API TypeORM нужную конструкцию не выражает. Типичные случаи: частичные и функциональные
|
|
||||||
индексы (`WHERE`, `lower(...)`), `ALTER COLUMN TYPE ... USING`, `CREATE INDEX CONCURRENTLY`,
|
|
||||||
`CREATE EXTENSION`, любые запросы к данным. В таком месте ставится комментарий, почему используется
|
|
||||||
строка SQL.
|
|
||||||
|
|
||||||
## `down` пишется всегда
|
|
||||||
|
|
||||||
Обратный метод обязателен для каждой миграции: `db-revert` — штатная команда проекта, и откат должен
|
|
||||||
работать не только на бумаге.
|
|
||||||
|
|
||||||
Если операция необратима по природе (удаление колонки с данными, добавление значения в enum-тип), у
|
|
||||||
`down` есть два варианта: упасть с ошибкой либо откатить схему с потерей данных. Что из этого
|
|
||||||
уместно, решается при написании конкретной миграции и фиксируется комментарием.
|
|
||||||
|
|
||||||
Первый вариант — откат запрещён:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
export class DropContestDescription1790000001000 implements MigrationInterface {
|
|
||||||
name = 'DropContestDescription1790000001000';
|
|
||||||
|
|
||||||
public async up(queryRunner: QueryRunner): Promise<void> {
|
|
||||||
await queryRunner.dropColumn('contests', 'description');
|
|
||||||
}
|
|
||||||
|
|
||||||
public async down(): Promise<void> {
|
|
||||||
// откат невозможен: значения удалённой колонки восстановить неоткуда
|
|
||||||
throw new Error('DropContestDescription1790000001000 необратима');
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Второй — та же миграция, но откат разрешён с потерей данных:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
public async down(queryRunner: QueryRunner): Promise<void> {
|
|
||||||
// колонка возвращается пустой: прежние значения теряются
|
|
||||||
await queryRunner.addColumn(
|
|
||||||
'contests',
|
|
||||||
new TableColumn({ name: 'description', type: 'text', isNullable: true }),
|
|
||||||
);
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Проверка перед коммитом
|
|
||||||
|
|
||||||
Миграция считается проверенной, только если на локальной БД прошёл полный цикл:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
yarn nx run api:db-migrate # накатить
|
|
||||||
yarn nx run api:db-revert # откатить
|
|
||||||
yarn nx run api:db-migrate # накатить снова
|
|
||||||
```
|
|
||||||
|
|
||||||
Все три шага должны отработать без ошибок. Второй накат ловит самый частый дефект — `down`, который
|
|
||||||
отработал не полностью и оставил в базе объект, на который потом спотыкается `up`.
|
|
||||||
|
|
||||||
Исключение — миграция, `down` которой намеренно падает: для неё проверяется только накат.
|
|
||||||
|
|
||||||
## Data-миграции — отдельным файлом
|
|
||||||
|
|
||||||
Изменение схемы и перенос/заполнение данных не смешиваются в одной миграции. Причина: миграция схемы
|
|
||||||
откатывается механически, а data-миграция часто необратима в принципе; в одном файле необратимой
|
|
||||||
становится вся пара.
|
|
||||||
|
|
||||||
Порядок для задачи «добавить колонку и заполнить её»: сначала миграция схемы, затем отдельной
|
|
||||||
миграцией — бэкфилл данных.
|
|
||||||
@@ -1,188 +0,0 @@
|
|||||||
# Слой доступа к данным (DAL)
|
|
||||||
|
|
||||||
## Зачем
|
|
||||||
|
|
||||||
Цель — не абстракция «на случай смены СУБД», а независимость бизнес-кода **от методов работы с
|
|
||||||
базой**. Сервис не должен знать, что данные достаются через `Repository.findOne`, `save` или
|
|
||||||
`QueryBuilder`: он вызывает осмысленный метод и получает данные. Тогда изменение способа выборки —
|
|
||||||
добавление join'а, замена двух запросов одним, кэш — остаётся внутри одного файла и не требует
|
|
||||||
трогать бизнес-логику.
|
|
||||||
|
|
||||||
## Как устроено
|
|
||||||
|
|
||||||
DAL — это обычный Nest-провайдер, технически такой же сервис, но с суффиксом `Dal`:
|
|
||||||
|
|
||||||
```
|
|
||||||
apps/api/src/contests/
|
|
||||||
├── entities/
|
|
||||||
│ └── contest.entity.ts
|
|
||||||
├── contests.dal.ts
|
|
||||||
├── contests.service.ts
|
|
||||||
├── contests.controller.ts
|
|
||||||
└── contests.module.ts
|
|
||||||
```
|
|
||||||
|
|
||||||
```ts
|
|
||||||
@Injectable()
|
|
||||||
export class ContestsDal {
|
|
||||||
constructor(
|
|
||||||
@InjectRepository(Contest)
|
|
||||||
private readonly repository: Repository<Contest>,
|
|
||||||
) {}
|
|
||||||
|
|
||||||
public findById(id: number): Promise<Contest | null> {
|
|
||||||
return this.repository.findOne({ where: { id } });
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
- `@InjectRepository`, `Repository`, `DataSource`, `QueryBuilder` и любые прочие API TypeORM
|
|
||||||
допустимы **только внутри DAL**. Сервисы, контроллеры, guard'ы и интерцепторы к ним не обращаются.
|
|
||||||
- **Active Record не используется**: сущность содержит только поля и связи, никаких методов
|
|
||||||
сохранения/поиска на ней не появляется.
|
|
||||||
- **Мапперы не нужны.** DAL возвращает сущности как есть; отдельный слой доменных моделей не
|
|
||||||
вводится.
|
|
||||||
- Методы добавляются **по мере необходимости** — под конкретный запрос вызывающего кода. Заранее,
|
|
||||||
«чтобы было», API не пишется.
|
|
||||||
- Типы TypeORM в сигнатурах (`FindOptionsWhere`, `FindManyOptions` и подобные) — допустимое зло:
|
|
||||||
ради них не городится собственный язык запросов.
|
|
||||||
|
|
||||||
## Бизнес-логики в DAL нет
|
|
||||||
|
|
||||||
DAL отвечает за «достать и положить», решения принимает сервис.
|
|
||||||
|
|
||||||
Единственное исключение — логика, которую **необходимо выполнять на стороне БД**: агрегаты, массовые
|
|
||||||
`UPDATE`, `upsert`, выборки с блокировками, оконные функции. Абстрагироваться от них без потери
|
|
||||||
смысла (и производительности) нельзя, поэтому такая логика живёт в DAL.
|
|
||||||
|
|
||||||
## DAL — приватная часть модуля
|
|
||||||
|
|
||||||
DAL не попадает в `exports` модуля и **недоступен другим модулям ни при каких условиях**.
|
|
||||||
`TypeOrmModule.forFeature([...])` регистрируется в модуле-владельце и наружу не реэкспортируется.
|
|
||||||
|
|
||||||
Доступ к данным чужого модуля — только через его **публичные сервисы**.
|
|
||||||
|
|
||||||
Исключение — тот самый случай, когда бизнес-логика реализована в DAL (выполняется в БД). Тогда
|
|
||||||
детали схемы одного модуля могут протечь в другой: например, запрос с join'ом на чужую таблицу
|
|
||||||
вместо похода в чужой сервис. Это допустимо, но нежелательно — так делают, когда обход через
|
|
||||||
публичный сервис обходится дорого (N+1, выборка заведомо лишних данных), а не по умолчанию.
|
|
||||||
|
|
||||||
## Транзакции
|
|
||||||
|
|
||||||
Транзакцию открывает **сервис — владелец сценария**, а не DAL: одна транзакция накрывает вызовы
|
|
||||||
нескольких DAL, и ни один из них не знает о соседях.
|
|
||||||
|
|
||||||
Ради этого сервису разрешено внедрять `DataSource` — **зафиксированное исключение** из правила «API
|
|
||||||
TypeORM только внутри DAL». Исключение узкое: `DataSource` в сервисе используется **исключительно**
|
|
||||||
ради `dataSource.transaction(...)`. Репозитории и `QueryBuilder` из него не берутся — вся работа с
|
|
||||||
данными остаётся в DAL, а `manager` передаётся в его методы параметром.
|
|
||||||
|
|
||||||
Так устроено создание пользователя: владелец сценария `UsersService`
|
|
||||||
(`apps/api/src/users/users.service.ts`) открывает транзакцию, а участвует в ней чужой модуль —
|
|
||||||
`BillingAccountService` → `AccountsService` → `AccountsDal` (`apps/api/src/billing/`).
|
|
||||||
|
|
||||||
Дальше — схематичные примеры на вымышленном модуле конкурсов: такого кода в репозитории нет, он
|
|
||||||
показывает форму записи, а не место. Сервис-владелец сценария:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
@Injectable()
|
|
||||||
export class ContestsService {
|
|
||||||
constructor(
|
|
||||||
private readonly contests: ContestsDal,
|
|
||||||
private readonly reviews: ReviewsDal,
|
|
||||||
// Исключение: `DataSource` здесь нужен только ради `transaction`.
|
|
||||||
@InjectDataSource()
|
|
||||||
private readonly dataSource: DataSource,
|
|
||||||
) {}
|
|
||||||
|
|
||||||
public launch(input: LaunchContestInput): Promise<Contest> {
|
|
||||||
return this.dataSource.transaction(async (manager) => {
|
|
||||||
await this.reviews.closeOpen(input.contestId, manager);
|
|
||||||
|
|
||||||
return this.contests.markLaunched(input.contestId, manager);
|
|
||||||
});
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
DAL принимает `manager` опциональным параметром и по нему выбирает репозиторий:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
@Injectable()
|
|
||||||
export class ContestsDal {
|
|
||||||
constructor(
|
|
||||||
@InjectRepository(Contest)
|
|
||||||
private readonly contests: Repository<Contest>,
|
|
||||||
) {}
|
|
||||||
|
|
||||||
public findById(id: number, manager?: EntityManager): Promise<Contest | null> {
|
|
||||||
return this.repository(manager).findOne({ where: { id } });
|
|
||||||
}
|
|
||||||
|
|
||||||
private repository(manager?: EntityManager): Repository<Contest> {
|
|
||||||
return manager?.getRepository(Contest) ?? this.contests;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Параметр опционален у любого метода — и у чтения, и у записи. Выполнять операцию в транзакции или
|
|
||||||
нет — ответственность вызывающей стороны: метод работает с тем `manager`, который ему передали, а
|
|
||||||
без него — вне транзакции. Так один и тот же `AccountsDal.findRegionByCode` читает справочник
|
|
||||||
регионов и в транзакции создания пользователя (из `AccountsService.create`), и без неё — на
|
|
||||||
стартовой проверке `BillingModule`. Выборка с блокировкой (`SELECT ... FOR UPDATE`) устроена так же:
|
|
||||||
блокировка держится только внутри транзакции, и открыть её — забота вызывающего.
|
|
||||||
|
|
||||||
Публичный метод сервиса, который может участвовать в чужой транзакции, тоже принимает
|
|
||||||
`manager?: EntityManager` и пробрасывает его дальше. Контекст передаётся явно, `AsyncLocalStorage`
|
|
||||||
не вводится.
|
|
||||||
|
|
||||||
Внешние вызовы — HTTP, SMTP, очереди — внутрь транзакции не заводятся: письмо верификации
|
|
||||||
`AuthService.registration` отправляет **после** возврата из `UsersService.createUser`, то есть после
|
|
||||||
коммита. Иначе транзакция держит соединение с базой на время сетевого таймаута, а откат письмо уже
|
|
||||||
не отзовёт.
|
|
||||||
|
|
||||||
### Модуль без своего DAL
|
|
||||||
|
|
||||||
Пока модуль на DAL не переведён (сегодня это `users`), внутри `dataSource.transaction(...)` все
|
|
||||||
операции с его сущностями идут через `manager.getRepository(...)` **прямо в сервисе**. Внедрённый
|
|
||||||
`this.userRepository` работает вне транзакции — он берёт собственное соединение, и откат его записи
|
|
||||||
не отменит.
|
|
||||||
|
|
||||||
```ts
|
|
||||||
// Сервис модуля без DAL, которому нужна транзакция:
|
|
||||||
return this.dataSource.transaction(async (manager) => {
|
|
||||||
// Именно `manager.getRepository`, а не внедрённый `this.userRepository`.
|
|
||||||
const users = manager.getRepository(User);
|
|
||||||
// Только анкетные поля: `create(dto)` перенёс бы на сущность любую пришедшую колонку и связь.
|
|
||||||
const user = users.create({
|
|
||||||
email: dto.email,
|
|
||||||
password: dto.password,
|
|
||||||
firstName: dto.firstName,
|
|
||||||
lastName: dto.lastName,
|
|
||||||
});
|
|
||||||
|
|
||||||
// Чужая операция вызывается тем же `manager`: аккаунт и строка пользователя пишутся одной
|
|
||||||
// транзакцией. Регион резолвит сам биллинг — `users` про его конфигурацию не знает.
|
|
||||||
const account = await this.billingAccount.create({ name: user.email }, manager);
|
|
||||||
|
|
||||||
user.billingAccountId = account.id;
|
|
||||||
|
|
||||||
return users.save(user);
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
Строка собирается из явного перечня анкетных полей, а не из `dto` целиком: у
|
|
||||||
`POST /auth/registration` валидирующего пайпа нет, поэтому в воронку уезжает сырое тело анонимного
|
|
||||||
запроса, а `create(dto)` (typeorm 0.3.x) перенёс бы на сущность и служебные колонки (`id`,
|
|
||||||
`emailVerified`, `banned`, `refreshToken`), и связь `roles`. Перечень — основная защита воронки,
|
|
||||||
поэтому расширяется осознанно (докблок `UsersService.createWithBillingAccount`).
|
|
||||||
|
|
||||||
Аккаунт заводится **до** вставки пользователя, чтобы строка сразу писалась со ссылкой
|
|
||||||
`users.billingAccountId`, а не догонялась вторым `save`. Такой порядок возможен потому, что
|
|
||||||
`billing_accounts` на `users` не ссылается.
|
|
||||||
|
|
||||||
Вне транзакции тот же сервис пишет через внедрённый `this.userRepository` — так устроены одиночные
|
|
||||||
записи вроде `UsersService.setUserEmailVerified` и `saveRefreshToken`, где менять нечего, кроме
|
|
||||||
одной строки `users`.
|
|
||||||
|
|
||||||
Оговорка временная: с появлением `users.dal.ts` этот код уезжает в DAL по общему правилу.
|
|
||||||
@@ -1,31 +0,0 @@
|
|||||||
# Тесты
|
|
||||||
|
|
||||||
## Расположение и имя
|
|
||||||
|
|
||||||
Юнит-тест лежит **рядом с тестируемым файлом**, отдельной папки под тесты нет:
|
|
||||||
|
|
||||||
```
|
|
||||||
apps/api/src/contests/
|
|
||||||
├── contests.service.ts
|
|
||||||
└── contests.service.test.ts
|
|
||||||
```
|
|
||||||
|
|
||||||
Расширение — `.test.ts` (`.test.tsx` для React-компонентов).
|
|
||||||
|
|
||||||
В репозитории встречается и `.spec.ts` — vitest подхватывает оба паттерна.
|
|
||||||
|
|
||||||
## DAL тестами не покрывается
|
|
||||||
|
|
||||||
Юнит-тест DAL с замоканным репозиторием проверял бы сам себя: что `findOne` вызван с теми
|
|
||||||
аргументами, с которыми его вызвали. Такие тесты не пишутся.
|
|
||||||
|
|
||||||
Логика, ради которой стоит писать тест, живёт в сервисе — там она и тестируется, с замоканным DAL.
|
|
||||||
Исключение — [БД-логика внутри DAL](30-data-access.md#бизнес-логики-в-dal-нет): её корректность
|
|
||||||
проверяется на реальной базе, а не моками.
|
|
||||||
|
|
||||||
## Запуск
|
|
||||||
|
|
||||||
```bash
|
|
||||||
yarn nx run api:test
|
|
||||||
yarn nx run web:test
|
|
||||||
```
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
label: 'Разработка'
|
|
||||||
@@ -1,75 +0,0 @@
|
|||||||
# Введение
|
|
||||||
|
|
||||||
## Зачем нужно логирование
|
|
||||||
|
|
||||||
### Цель
|
|
||||||
|
|
||||||
Логирование — это ключевой инструмент диагностики и анализа поведения системы. Оно фиксирует
|
|
||||||
**действия, ошибки и события**, позволяя:
|
|
||||||
|
|
||||||
- анализировать поведение приложения;
|
|
||||||
- находить причины ошибок и сбоев;
|
|
||||||
- отслеживать бизнес-процессы (например, запуск аудита бренда или генерацию JSON-LD);
|
|
||||||
- проводить аудит действий пользователей;
|
|
||||||
- контролировать производительность и стабильность работы.
|
|
||||||
|
|
||||||
Хорошее логирование даёт **контекст и доказательства** — кто, когда и что сделал, с каким
|
|
||||||
результатом.
|
|
||||||
|
|
||||||
### Основные задачи логирования
|
|
||||||
|
|
||||||
Логирование решает как **технические**, так и **организационные** задачи.
|
|
||||||
|
|
||||||
**Технические:**
|
|
||||||
|
|
||||||
- **Диагностика:** восстановление хода событий при сбое.
|
|
||||||
- **Аналитика:** понимание того, как система используется.
|
|
||||||
- **Поддержка:** ускорение поиска причин ошибок в эксплуатации.
|
|
||||||
|
|
||||||
**Организационные:**
|
|
||||||
|
|
||||||
- **Аудит:** фиксация действий пользователей и администраторов.
|
|
||||||
- **Безопасность:** выявление попыток несанкционированного доступа.
|
|
||||||
|
|
||||||
## Уровни логирования
|
|
||||||
|
|
||||||
В системе используется библиотека **Pino**, интегрированная через `nestjs-pino`. Она поддерживает
|
|
||||||
стандартные уровни логирования, отражающие важность события.
|
|
||||||
|
|
||||||
| Уровень | Метод | Когда использовать | Пример |
|
|
||||||
| --------- | --------- | --------------------------------------------------- | -------------------------------- |
|
|
||||||
| **TRACE** | `trace()` | Максимальная детализация, пошаговая трассировка | Проверка цепочки вызовов |
|
|
||||||
| **DEBUG** | `debug()` | Отладочная информация о логике работы | Вывод промежуточных данных |
|
|
||||||
| **INFO** | `log()` | Обычные события нормальной работы | Бренд создан |
|
|
||||||
| **WARN** | `warn()` | Нежелательные, но некритичные ситуации | Отказ в доступе |
|
|
||||||
| **ERROR** | `error()` | Ошибки, требующие внимания и реакции | Исключение при сохранении |
|
|
||||||
| **FATAL** | `fatal()` | Критические сбои, приводящие к остановке приложения | Потеря соединения с базой данных |
|
|
||||||
|
|
||||||
> 💡 Все уровни логов фиксируются одинаково по структуре данных — различается только их
|
|
||||||
> **важность**.
|
|
||||||
|
|
||||||
## Различие между dev и prod
|
|
||||||
|
|
||||||
Логирование настроено так, чтобы быть **удобным в разработке** и **эффективным в продакшене**.
|
|
||||||
|
|
||||||
| Среда | Формат | Уровень по умолчанию | Особенности |
|
|
||||||
| --------------- | ----------------- | -------------------- | --------------------------------------------------------------------- |
|
|
||||||
| **Development** | человеко-читаемый | `debug` | Цвета, отступы, подробные данные — удобно для чтения в консоли. |
|
|
||||||
| **Production** | JSON | `info` | Машиночитаемый формат для централизованной агрегации и анализа логов. |
|
|
||||||
|
|
||||||
> Состав данных в логе всегда одинаков — меняется только способ отображения. Уровень логирования
|
|
||||||
> можно переопределить через переменные окружения.
|
|
||||||
|
|
||||||
Таким образом:
|
|
||||||
|
|
||||||
- в **разработке** акцент на удобство восприятия и диагностику;
|
|
||||||
- в **продакшене** — на структурированные данные и интеграцию с системами мониторинга (например,
|
|
||||||
Loki или ELK).
|
|
||||||
|
|
||||||
## Где живёт настройка
|
|
||||||
|
|
||||||
- `apps/api/src/logger/base.ts` — единственный экземпляр pino, выбор уровня и формата вывода;
|
|
||||||
- `apps/api/src/logger/logger.class.ts` — класс `Logger`, через который логирует код приложения;
|
|
||||||
- `apps/api/src/logger/logger.module.ts` — модуль `LocalLoggerModule`: HTTP-логи (`pino-http`) в
|
|
||||||
`forRoot()` и подмена логгера Nest в `setup()`;
|
|
||||||
- `apps/api/src/logger/testing/` — логгер для тестов, `LocalLoggerModule.forTesting()`.
|
|
||||||
@@ -1,103 +0,0 @@
|
|||||||
# Подключение и использование
|
|
||||||
|
|
||||||
## Получение логгера
|
|
||||||
|
|
||||||
Логгер внедряется в любой сервис, контроллер или компонент через **dependency injection**. После
|
|
||||||
внедрения требуется указать **контекст**, чтобы логи было проще анализировать.
|
|
||||||
|
|
||||||
```ts
|
|
||||||
@Injectable()
|
|
||||||
export class BrandService {
|
|
||||||
constructor(private readonly logger: Logger) {
|
|
||||||
this.logger.setContext('Brands');
|
|
||||||
}
|
|
||||||
|
|
||||||
async createBrand(data: CreateBrandDto) {
|
|
||||||
this.logger.log('Brand created', { brand: 42, user: data.ownerId });
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Модуль, в котором объявлен сервис, должен импортировать `LocalLoggerModule.forRoot()` (он помечен
|
|
||||||
`global: true`, поэтому достаточно один раз в `AppModule`).
|
|
||||||
|
|
||||||
## Контекст логгера
|
|
||||||
|
|
||||||
Контекст указывает, **к какому модулю или бизнес-процессу относится лог**. Он помогает группировать
|
|
||||||
события и быстрее понимать источник при анализе системы.
|
|
||||||
|
|
||||||
Контекст задаётся вручную при инициализации логгера:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
constructor(private readonly logger: Logger) {
|
|
||||||
this.logger.setContext('Evaluation');
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Вне DI (в `main.ts`, в bootstrap-сценариях) логгер создаётся с контекстом в конструкторе:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
const logger = new Logger('Bootstrap');
|
|
||||||
```
|
|
||||||
|
|
||||||
## Правила именования контекста
|
|
||||||
|
|
||||||
Хорошие контексты делают логи самодокументируемыми. Чтобы они оставались единообразными, следуйте
|
|
||||||
правилам:
|
|
||||||
|
|
||||||
1. **Основой контекста является название модуля**, отражающее область бизнес-логики. Примеры:
|
|
||||||
- `Brands` — работа с карточками брендов;
|
|
||||||
- `JsonLd` — генерация структурированных данных;
|
|
||||||
- `Users` — работа с пользователями.
|
|
||||||
|
|
||||||
2. **При необходимости уточнения** добавляется второй уровень через двоеточие:
|
|
||||||
- `Brands:Passport` — паспорт бренда;
|
|
||||||
- `Audit:History` — журнал изменений.
|
|
||||||
|
|
||||||
3. **Технические роли** (`Service`, `Controller` и т. п.) в названии **не используются**, так как
|
|
||||||
контекст должен отражать **бизнес-смысл**, а не структуру кода.
|
|
||||||
|
|
||||||
> 💬 Контекст — часть “языка логирования” проекта. Он должен быть **стабильным, понятным и
|
|
||||||
> единообразным** во всех модулях.
|
|
||||||
|
|
||||||
## Контекст запроса
|
|
||||||
|
|
||||||
При логировании внутри HTTP-запроса `pino-http` автоматически добавляет поля:
|
|
||||||
|
|
||||||
- `reqId` — идентификатор запроса;
|
|
||||||
- `url` — метод и адрес текущего запроса.
|
|
||||||
|
|
||||||
Это позволяет связывать бизнес-события с конкретными запросами и упрощает анализ логов. Ручные логи
|
|
||||||
внутри запроса достаточно писать через инжектированный `Logger` — связывать их с запросом вручную не
|
|
||||||
нужно, но и `reqId` в `details` дублировать не следует.
|
|
||||||
|
|
||||||
## Переменные окружения
|
|
||||||
|
|
||||||
Настройки логирования задаются через `.env` или переменные окружения.
|
|
||||||
|
|
||||||
| Переменная | Назначение | Пример значения |
|
|
||||||
| ------------ | ------------------------------------------------- | -------------------------------- |
|
|
||||||
| `LOG_LEVEL` | Минимальный уровень логирования. | `debug`, `info`, `warn`, `error` |
|
|
||||||
| `LOG_PRETTY` | Включает человеко-читаемый формат (обычно в dev). | `true` |
|
|
||||||
|
|
||||||
Если переменные не заданы, применяются значения по умолчанию:
|
|
||||||
|
|
||||||
| Окружение | Значения по умолчанию |
|
|
||||||
| --------- | ------------------------------------ |
|
|
||||||
| **dev** | `LOG_LEVEL=debug`, `LOG_PRETTY=true` |
|
|
||||||
| **prod** | `LOG_LEVEL=info`, `LOG_PRETTY=false` |
|
|
||||||
|
|
||||||
Прод определяется как `NODE_ENV=production` (в образе api это значение выставлено в `Dockerfile`)
|
|
||||||
или явным `LOG_PRETTY=false`. Образ api ставит только production-зависимости, а `pino-pretty` —
|
|
||||||
dev-зависимость: если запустить контейнер без `NODE_ENV=production`, воркер pretty-транспорта не
|
|
||||||
найдётся.
|
|
||||||
|
|
||||||
> 🔧 Уровень логирования можно переопределить без релиза — через переменные окружения при запуске
|
|
||||||
> приложения.
|
|
||||||
|
|
||||||
## Чек-лист перед ревью
|
|
||||||
|
|
||||||
- [ ] Логгер подключён через dependency injection.
|
|
||||||
- [ ] Контекст задан явно через `setContext()`.
|
|
||||||
- [ ] Уровень логирования соответствует окружению.
|
|
||||||
- [ ] Логи не содержат чувствительных данных.
|
|
||||||
@@ -1,68 +0,0 @@
|
|||||||
# Автоматическое логирование
|
|
||||||
|
|
||||||
Автоматическое логирование фиксирует системные события **без участия разработчика**. Оно
|
|
||||||
обеспечивает единый формат сообщений и полное покрытие ключевых операций платформы.
|
|
||||||
|
|
||||||
> 💡 Автоматические логи всегда присутствуют и формируются системой независимо от действий
|
|
||||||
> разработчика.
|
|
||||||
|
|
||||||
## HTTP-запросы
|
|
||||||
|
|
||||||
### Общие принципы
|
|
||||||
|
|
||||||
- Каждый HTTP-запрос логируется **после завершения обработки**.
|
|
||||||
- Лог формирует middleware `pino-http`, который подключается в `LocalLoggerModule.forRoot()`
|
|
||||||
(`apps/api/src/logger/logger.module.ts`).
|
|
||||||
- Разработчику не нужно добавлять логи вручную — они создаются автоматически.
|
|
||||||
|
|
||||||
Каждая запись содержит:
|
|
||||||
|
|
||||||
- HTTP-метод (`GET`, `POST`, `PATCH` и т. д.);
|
|
||||||
- путь запроса (`/api/...`);
|
|
||||||
- код ответа (`200`, `403`, `500` и т. д.);
|
|
||||||
- время выполнения в миллисекундах (`responseTime`);
|
|
||||||
- идентификатор запроса (`reqId`);
|
|
||||||
- контекст `HTTP` — по нему HTTP-логи отличаются от логов приложения.
|
|
||||||
|
|
||||||
### Уровни логирования
|
|
||||||
|
|
||||||
| Категория ответа | Пример кода | Уровень |
|
|
||||||
| ---------------- | ----------- | -------- |
|
|
||||||
| Успешный ответ | `2xx` | `info` |
|
|
||||||
| Ошибка клиента | `4xx` | `info` |
|
|
||||||
| Ошибка сервера | `5xx` | `error` |
|
|
||||||
| Редирект | `3xx` | `silent` |
|
|
||||||
|
|
||||||
> Уровень `warn` для HTTP-логов не используется — это предотвращает появление ложных предупреждений
|
|
||||||
> при корректных отказах.
|
|
||||||
|
|
||||||
### Что не попадает в HTTP-логи
|
|
||||||
|
|
||||||
Middleware смонтирован на `/api/*`, поэтому есть два исключения:
|
|
||||||
|
|
||||||
- запрос ровно на `/api` (без слеша после префикса) — шаблон `/api/*` его не матчит;
|
|
||||||
- всё, что обслуживает Swagger: `SwaggerModule.setup` регистрирует свои обработчики на Express
|
|
||||||
раньше middleware `pino-http`, поэтому `/api/docs` и его статика в лог не попадают.
|
|
||||||
|
|
||||||
Всё остальное, включая 404 по неизвестным путям, логируется.
|
|
||||||
|
|
||||||
### Задачи HTTP-логов
|
|
||||||
|
|
||||||
- Отслеживание активности API.
|
|
||||||
- Измерение времени обработки запросов.
|
|
||||||
- Анализ причин ошибок и неудачных вызовов.
|
|
||||||
- Связь действий пользователей с конкретными маршрутами.
|
|
||||||
|
|
||||||
## Проверки доступа и исключения
|
|
||||||
|
|
||||||
Логирование проверок доступа (RBAC) и необработанных исключений появится вместе с модулями, которые
|
|
||||||
эти события порождают. До этого момента такие события в лог не попадают, и ручные логи в местах
|
|
||||||
отказа — единственный способ их зафиксировать.
|
|
||||||
|
|
||||||
## Рекомендации
|
|
||||||
|
|
||||||
- Не дублируйте автоматические логи вручную.
|
|
||||||
- Если требуется зафиксировать **дополнительный** контекст, добавляйте отдельный лог рядом с
|
|
||||||
бизнес-событием — но не повторяйте уже зарегистрированные HTTP-запросы.
|
|
||||||
- При анализе проблем **начинайте с автоматических логов** — они формируются всегда и имеют единый
|
|
||||||
формат.
|
|
||||||
@@ -1,143 +0,0 @@
|
|||||||
# Ручное логирование и бизнес-события
|
|
||||||
|
|
||||||
Автоматическое логирование фиксирует системные события (HTTP-запросы, ошибки), но не отражает
|
|
||||||
**внутреннюю бизнес-логику** приложения.
|
|
||||||
|
|
||||||
Ручное логирование используется для фиксации действий и изменений, важных **с точки зрения
|
|
||||||
продукта** — того, что видит или делает пользователь.
|
|
||||||
|
|
||||||
## Назначение
|
|
||||||
|
|
||||||
Ручные логи применяются для описания событий, которые отражают состояние системы и бизнес-процессы:
|
|
||||||
|
|
||||||
- создание, изменение и удаление сущностей;
|
|
||||||
- начало и завершение процессов;
|
|
||||||
- изменение статуса или состояния;
|
|
||||||
- ошибки бизнес-операций;
|
|
||||||
- любые другие действия, значимые для анализа и аудита.
|
|
||||||
|
|
||||||
> Такое логирование помогает понять, **что происходило внутри системы**, даже без включённой отладки
|
|
||||||
> или доступа к базе данных.
|
|
||||||
|
|
||||||
## Правила оформления логов
|
|
||||||
|
|
||||||
### Общие принципы
|
|
||||||
|
|
||||||
Сообщения должны быть:
|
|
||||||
|
|
||||||
- **краткими** — не длиннее одной фразы;
|
|
||||||
- **человеко-читаемыми** — понятными без знания кода;
|
|
||||||
- **однозначными** — описывать факт, а не процесс;
|
|
||||||
- **на английском**, **в прошедшем времени**, **без артиклей и пунктуации**.
|
|
||||||
|
|
||||||
Если операция завершилась неудачей, сообщение должно оканчиваться на `failed`.
|
|
||||||
|
|
||||||
Логирование выполняется **после завершения** операции — независимо от результата.
|
|
||||||
|
|
||||||
### Примеры сообщений
|
|
||||||
|
|
||||||
**Успешные операции:**
|
|
||||||
|
|
||||||
- `Brand created`
|
|
||||||
- `Passport filled`
|
|
||||||
- `JsonLd generated`
|
|
||||||
- `Audit completed`
|
|
||||||
|
|
||||||
**Ошибки и неудачи:**
|
|
||||||
|
|
||||||
- `Brand update failed`
|
|
||||||
- `File upload failed`
|
|
||||||
- `JsonLd generation failed`
|
|
||||||
|
|
||||||
**Неправильные формулировки:**
|
|
||||||
|
|
||||||
- `Creating brand...` — отражает процесс, а не факт.
|
|
||||||
- `Brand ${id} created` — содержит шаблон и динамику.
|
|
||||||
- `Brand created successfully!` — избыточно и разговорно.
|
|
||||||
|
|
||||||
### Дополнительные данные
|
|
||||||
|
|
||||||
Контекст события передаётся отдельным объектом (`details`). Включайте только данные, которые
|
|
||||||
действительно помогают при анализе.
|
|
||||||
|
|
||||||
**Рекомендации:**
|
|
||||||
|
|
||||||
- Всегда указывайте **идентификаторы** (`brand`, `audit`, `user` и т. д.).
|
|
||||||
- В идентификаторах избегайте суфиксов `id` (пример: `brand` вместо `brandId`).
|
|
||||||
- Добавляйте **причину** (`reason`) при ошибках или отказах.
|
|
||||||
- Указывайте **новое состояние** (`status`, `result`) при изменениях.
|
|
||||||
- Не включайте чувствительные данные — токены, e-mail, пароли, персональные сведения.
|
|
||||||
|
|
||||||
`details` передаются вторым аргументом на всех уровнях: `trace`, `debug`, `log`, `warn`, `error`,
|
|
||||||
`fatal`. Логгер сам раскладывает объект в поля JSON-записи, поэтому сериализовать его в строку не
|
|
||||||
нужно — наоборот, строка в `details` попадёт в лог как текст и потеряет структуру.
|
|
||||||
|
|
||||||
**Пример:**
|
|
||||||
|
|
||||||
```ts
|
|
||||||
logger.log('Brand created', { brand: 42, user: 7 });
|
|
||||||
logger.error('Brand update failed', { brand: 42, reason: 'invalid_status' });
|
|
||||||
```
|
|
||||||
|
|
||||||
Ошибку со стеком можно передать третьим аргументом — тогда он попадёт в лог как `trace`:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
logger.error('JsonLd generation failed', error.stack, { brand: 42 });
|
|
||||||
```
|
|
||||||
|
|
||||||
### Как объект попадает в запись
|
|
||||||
|
|
||||||
Сигнатура `LoggerService` в Nest описывает `error(message, stack, context)`, а
|
|
||||||
`log(message, ...optionalParams)` — без отдельного места под объект. Наш `Logger`
|
|
||||||
(`logger.class.ts`) приводит вызов к форме pino: `logger[level](details, message)`. Поэтому:
|
|
||||||
|
|
||||||
- `details` — обычный объект, не JSON-строка;
|
|
||||||
- для `error()` второй аргумент со строковым стеком уезжает в поле `trace`, а объект `details` можно
|
|
||||||
передать вторым или третьим аргументом.
|
|
||||||
|
|
||||||
## Бизнес-события
|
|
||||||
|
|
||||||
### Что считается бизнес-событием
|
|
||||||
|
|
||||||
Бизнес-события описывают **действия и изменения на уровне предметной области**, например:
|
|
||||||
|
|
||||||
- `Brand created` — бренд заведён;
|
|
||||||
- `Passport filled` — паспорт бренда заполнен;
|
|
||||||
- `JsonLd exported` — структурированные данные выгружены;
|
|
||||||
- `Audit completed` — NAP-аудит завершён.
|
|
||||||
|
|
||||||
> Все бизнес-события логируются на уровне `info` (`logger.log()`), а ошибки бизнес-операций — на
|
|
||||||
> уровне `error`.
|
|
||||||
|
|
||||||
### Длительные процессы
|
|
||||||
|
|
||||||
Для долгих операций допускается логирование **двух фаз**:
|
|
||||||
|
|
||||||
- начало — `<Action> started`;
|
|
||||||
- завершение — `<Action>` (применяются обычные правила оформления сообщений).
|
|
||||||
|
|
||||||
**Пример:**
|
|
||||||
|
|
||||||
```ts
|
|
||||||
logger.log('JsonLd export started', { brand: 3 });
|
|
||||||
logger.log('JsonLd exported', { brand: 3, durationMs: 14250 });
|
|
||||||
logger.error('JsonLd export failed', { brand: 3, reason: 'timeout' });
|
|
||||||
```
|
|
||||||
|
|
||||||
Такой подход позволяет отслеживать прогресс и измерять длительность операций.
|
|
||||||
|
|
||||||
### Зачем нужны бизнес-события
|
|
||||||
|
|
||||||
- Повышают прозрачность бизнес-процессов.
|
|
||||||
- Используются при анализе и аудите.
|
|
||||||
- Позволяют отследить жизненный цикл сущностей — от создания до завершения.
|
|
||||||
- Упрощают поиск причин ошибок на уровне сценариев пользователей.
|
|
||||||
|
|
||||||
## Чек-лист перед ревью
|
|
||||||
|
|
||||||
- [ ] Контекст логгера задан.
|
|
||||||
- [ ] Сообщение короткое, на английском и в прошедшем времени.
|
|
||||||
- [ ] В `details` указаны идентификаторы и причина (если применимо).
|
|
||||||
- [ ] Уровень логирования выбран корректно (`info` или `error`).
|
|
||||||
- [ ] Лог не дублирует автоматические записи (HTTP).
|
|
||||||
- [ ] Отсутствуют конфиденциальные данные.
|
|
||||||
@@ -1,159 +0,0 @@
|
|||||||
# Тестирование логирования
|
|
||||||
|
|
||||||
## Подключение
|
|
||||||
|
|
||||||
Для тестов следует подключать специальный модуль — **`LocalLoggerModule.forTesting()`**. Он
|
|
||||||
сохраняет логи в памяти и предоставляет к ним доступ через `TestingLogger`.
|
|
||||||
|
|
||||||
Это позволяет:
|
|
||||||
|
|
||||||
- перехватывать все вызовы логгера внутри тестируемого кода;
|
|
||||||
- сохранять их в память вместо вывода в консоль;
|
|
||||||
- проверять, какие именно логи были собраны за время теста.
|
|
||||||
|
|
||||||
Пример подключения через NestJS `TestingModule`:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
let logger: TestingLogger;
|
|
||||||
|
|
||||||
beforeEach(async () => {
|
|
||||||
const module = await Test.createTestingModule({
|
|
||||||
imports: [LocalLoggerModule.forTesting()],
|
|
||||||
}).compile();
|
|
||||||
|
|
||||||
logger = module.get(TestingLogger);
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
После такого подключения любые вызовы вида:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
this.logger.log('Brand created');
|
|
||||||
this.logger.error('Brand update failed');
|
|
||||||
```
|
|
||||||
|
|
||||||
будут сохранены внутри `TestingLogger`, и вы сможете проверить их в тестах при помощи матчеров:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
logger.withMessage('Brand created').withLevel('info').toBeLoggedOnce();
|
|
||||||
logger.withMessage('Brand update failed').withLevel('error').toBeLogged();
|
|
||||||
```
|
|
||||||
|
|
||||||
## Цепочка фильтров
|
|
||||||
|
|
||||||
Методы фильтрации (`withMessage`, `withLevel`, `withContext`, `withDetails`) можно вызывать
|
|
||||||
цепочкой, для более точного сопоставления логов:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
logger
|
|
||||||
.withMessage('Brand created')
|
|
||||||
.withLevel('info')
|
|
||||||
.withContext('Brands')
|
|
||||||
.withDetails({ user: 5 })
|
|
||||||
.toBeLoggedOnce();
|
|
||||||
```
|
|
||||||
|
|
||||||
Метод `withDetails` поддерживает частичное сравнение объекта, а также может проверять поля `level`,
|
|
||||||
`context` и `message`:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
logger
|
|
||||||
.withMessage('Brand created')
|
|
||||||
.withDetails({
|
|
||||||
level: 'info',
|
|
||||||
context: 'Brands',
|
|
||||||
user: 5,
|
|
||||||
})
|
|
||||||
.toBeLoggedOnce();
|
|
||||||
```
|
|
||||||
|
|
||||||
Если нужны только поля из фильтра и ничего лишнего в `details`, к цепочке добавляется
|
|
||||||
`strictDetails()`.
|
|
||||||
|
|
||||||
### Просмотр найденных записей
|
|
||||||
|
|
||||||
Если нужно отладить фильтр и просмотреть, какие записи были найдены по текущему фильтру, можно
|
|
||||||
использовать метод `showLogs()`:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
logger.withLevel('error').showLogs().toBeLogged();
|
|
||||||
```
|
|
||||||
|
|
||||||
### Методы проверки
|
|
||||||
|
|
||||||
| Метод | Описание |
|
|
||||||
| -------------------- | --------------------------------------------------------- |
|
|
||||||
| `toBeLogged()` | Проверяет, что хотя бы одна запись соответствует фильтру. |
|
|
||||||
| `toBeNotLogged()` | Проверяет, что таких записей нет. |
|
|
||||||
| `toBeLoggedOnce()` | Проверяет, что запись встречается ровно один раз. |
|
|
||||||
| `toBeLoggedTimes(n)` | Проверяет, что запись встречается `n` раз. |
|
|
||||||
|
|
||||||
Все методы выбрасывают ошибку, если условие не выполняется.
|
|
||||||
|
|
||||||
> **Важно:** Методы проверки **обязательно** должны вызываться, иначе проверки так и не будет.
|
|
||||||
|
|
||||||
### Группирование проверок
|
|
||||||
|
|
||||||
Если в тесте нужно проверить несколько событий с общим набором полей, можно использовать такой
|
|
||||||
приём:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
const brandsLogger = logger.withContext('Brands');
|
|
||||||
|
|
||||||
brandsLogger.withMessage('Brand created').toBeLoggedTimes(2);
|
|
||||||
|
|
||||||
brandsLogger.withMessage('Brand update failed').toBeLoggedOnce();
|
|
||||||
```
|
|
||||||
|
|
||||||
Это удобно для группировки проверок по контексту или другим общим параметрам.
|
|
||||||
|
|
||||||
## Примеры использования
|
|
||||||
|
|
||||||
### Проверка бизнес-события
|
|
||||||
|
|
||||||
```ts
|
|
||||||
it('должен логировать создание бренда', () => {
|
|
||||||
service.createBrand({ user: 7 });
|
|
||||||
|
|
||||||
logger.withMessage('Brand created').withLevel('info').withDetails({ user: 7 }).toBeLoggedOnce();
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
### Проверка ошибок
|
|
||||||
|
|
||||||
```ts
|
|
||||||
it('должен логировать ошибку при невалидном статусе', () => {
|
|
||||||
service.updateBrandStatus(42, 'invalid');
|
|
||||||
|
|
||||||
logger.withMessage('Brand update failed').withLevel('error').toBeLogged();
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
### Проверка отсутствия логов
|
|
||||||
|
|
||||||
```ts
|
|
||||||
it('не должен логировать ничего при успешном выполнении без событий', () => {
|
|
||||||
service.doNothing();
|
|
||||||
|
|
||||||
logger.any().toBeNotLogged();
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
### Очистка
|
|
||||||
|
|
||||||
```ts
|
|
||||||
beforeEach(() => {
|
|
||||||
logger.clear();
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
Используйте `clear()` для сброса состояния между тестами, если экземпляр `TestingLogger`
|
|
||||||
переиспользуется в нескольких сценариях.
|
|
||||||
|
|
||||||
## Рекомендации
|
|
||||||
|
|
||||||
- `TestingLogger` предназначен **только для тестов** — в рабочем коде используется обычный `Logger`.
|
|
||||||
- Проверяйте **факт логирования**, а не реализацию — тесты должны оставаться устойчивыми к
|
|
||||||
внутренним изменениям.
|
|
||||||
- Используйте `toBeNotLogged()` для сценариев, где событие **не должно** быть зафиксировано.
|
|
||||||
- Готовый пример работы с `TestingLogger` — `apps/api/src/logger/testing/testing-logger.spec.ts`.
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
label: 'Логирование'
|
|
||||||
@@ -1,380 +0,0 @@
|
|||||||
# Миграции базы данных
|
|
||||||
|
|
||||||
Миграции TypeORM применяются **автоматически при деплое** — и на проде (на каждый тег), и на
|
|
||||||
стейджинге (на каждый push/PR); деплой падает, если миграция не прошла. См.
|
|
||||||
[База и переменные `.env` на стейджинг-хосте](#база-и-переменные-env-на-стейджинг-хосте).
|
|
||||||
|
|
||||||
⚠️ Перед первым прод-деплоем убедитесь, что `aigeo_app` имеет права на DDL и что таблица
|
|
||||||
`migrations` согласована со схемой — см. [Права на БД](#права-на-бд). Автоматического бэкапа перед
|
|
||||||
миграцией нет.
|
|
||||||
|
|
||||||
Схема БД в рантайме не синхронизируется: `synchronize: false`, `migrationsRun: false`. Единственный
|
|
||||||
способ изменить схему — миграция.
|
|
||||||
|
|
||||||
Как **писать** саму миграцию (API `QueryRunner`, `down`, data-миграции) —
|
|
||||||
[Написание миграций](../50-developing/20-migrations.md).
|
|
||||||
|
|
||||||
## Как это устроено
|
|
||||||
|
|
||||||
Webpack не умеет runtime-glob: запись `migrations: ['*.js']` внутри бандла не работает в принципе.
|
|
||||||
Поэтому список миграций генерируется статически на этапе сборки.
|
|
||||||
|
|
||||||
1. **Кодогенерация.** `tools/buildDataSource.ts` сканирует `apps/api/src/**/migrations/*.ts`
|
|
||||||
(миграции лежат по модулям — `apps/api/src/<module>/migrations/`), вытаскивает имена
|
|
||||||
экспортируемых классов и пишет `apps/api/src/migrations.ts` со статическими импортами. Сортировка
|
|
||||||
— по числовому timestamp из имени файла (возрастание) независимо от модуля. Результат прогоняется
|
|
||||||
через Prettier внутри генератора и **коммитится в репозиторий**.
|
|
||||||
2. **Единый DataSource.** `apps/api/src/config/typeorm.config.ts` берёт `migrations` из
|
|
||||||
сгенерированного файла. Один и тот же файл работает локально через `typeorm-ts-node-commonjs` и в
|
|
||||||
собранном виде внутри контейнера.
|
|
||||||
3. **Отдельный бандл.** `apps/api/webpack.data-source.config.js` собирает `data-source.js` в тот же
|
|
||||||
`apps/api/dist`, что и `main.js` (`output.clean: false`, иначе затрёт основной бандл). В образе
|
|
||||||
оба файла лежат в `/app` рядом с `node_modules`.
|
|
||||||
|
|
||||||
⚠️ Попадание `dist` в образ держится на том, что **`apps/api/.dockerignore` отсутствует**:
|
|
||||||
контекст сборки — `apps/api`, а правило `**/dist` из корневого `.dockerignore` при наличии
|
|
||||||
локального файла перестало бы игнорироваться (docker берёт `.dockerignore` из корня контекста).
|
|
||||||
Создание `apps/api/.dockerignore` молча соберёт образ без `main.js` и `data-source.js`.
|
|
||||||
Отдельной CI-проверки этого нет: если файлов не окажется в образе,
|
|
||||||
`migration:show`/`migration:run` на деплое упадут с понятной ошибкой
|
|
||||||
(`Cannot find module '/app/data-source.js'` или аналогичной).
|
|
||||||
|
|
||||||
4. **Шаги в деплое.** После подъёма контейнеров — `migration:show` в лог, затем
|
|
||||||
`migration:run -t each`, на проде и на стейджинге.
|
|
||||||
|
|
||||||
Генерация подключена к сборке через `dependsOn`, отдельно её запускать не нужно:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
yarn nx run api:build # db-migrations-list → main.js → data-source.js
|
|
||||||
yarn nx run api:db-migrations-list # только перегенерация списка
|
|
||||||
```
|
|
||||||
|
|
||||||
Запись в `migrations.ts` идемпотентна: если содержимое не изменилось, файл не переписывается (иначе
|
|
||||||
`api:serve` в watch-режиме уходил бы в бесконечный цикл пересборок).
|
|
||||||
|
|
||||||
## Как добавить миграцию
|
|
||||||
|
|
||||||
1. Создать файл в `apps/api/src/<module>/migrations/` — вручную или через
|
|
||||||
`typeorm migration:generate`. Имя файла обязано начинаться с **13-значного** timestamp:
|
|
||||||
`1774001000000-fix-subscription-plan-id-default.ts`, а имя класса — оканчиваться тем же timestamp
|
|
||||||
(`FixSubscriptionPlanIdDefault1774001000000`). TypeORM берёт timestamp как
|
|
||||||
`parseInt(className.substr(-13))` и игнорирует порядок массива в `migrations.ts`, поэтому
|
|
||||||
расхождение суффикса класса и префикса файла означает применение не в том порядке. Генератор
|
|
||||||
проверяет это и валит сборку.
|
|
||||||
|
|
||||||
`migration:generate` запускается из **корня воркспейса** и требует двух переменных окружения —
|
|
||||||
без них ts-node не подхватит `experimentalDecorators` и TS-алиасы:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
TS_NODE_PROJECT=apps/api/tsconfig.app.json \
|
|
||||||
NODE_OPTIONS="-r tsconfig-paths/register" \
|
|
||||||
yarn typeorm-ts-node-commonjs migration:generate \
|
|
||||||
apps/api/src/<module>/migrations/add-something \
|
|
||||||
-d apps/api/src/config/typeorm.config.ts
|
|
||||||
```
|
|
||||||
|
|
||||||
Те же две переменные задаются один раз в `nx.json` → `targetDefaults` под ключом
|
|
||||||
`db-{show,migrate,revert,drop}` и подмешиваются в эти четыре таргета. Namespace-паттерн важен:
|
|
||||||
`db-*` захватил бы ещё `db-snapshot` / `db-restore` / `db-migrations-list`, которые запускаются
|
|
||||||
обычным `ts-node` из корня и с api-шным tsconfig сломались бы.
|
|
||||||
|
|
||||||
Вывод генератора — черновик: он всегда пишет тело строками `queryRunner.query(...)`, а в проекте
|
|
||||||
DDL оформляется методами `QueryRunner`. См.
|
|
||||||
[Написание миграций](../50-developing/20-migrations.md).
|
|
||||||
|
|
||||||
2. Перегенерировать список: `yarn nx run api:db-migrations-list` (или просто
|
|
||||||
`yarn nx run api:build`).
|
|
||||||
3. **Закоммитить оба файла** — саму миграцию и `apps/api/src/migrations.ts`.
|
|
||||||
4. Проверить локально: `yarn nx run api:db-show` (миграция должна появиться в списке), затем цикл
|
|
||||||
накат → откат → накат — см.
|
|
||||||
[Проверка перед коммитом](../50-developing/20-migrations.md#проверка-перед-коммитом).
|
|
||||||
|
|
||||||
Генератор падает с ненулевым кодом, если: в файле нет `export class`; в файле больше одного
|
|
||||||
`export class`; имя файла не начинается с 13-значного timestamp; суффикс имени класса не совпадает с
|
|
||||||
префиксом имени файла; два файла дают одинаковое имя класса. Так как он висит на `dependsOn` у
|
|
||||||
`build`, любая из этих ошибок валит сборку. Отсутствие каталогов `migrations` — не ошибка: список
|
|
||||||
тогда пустой.
|
|
||||||
|
|
||||||
Файлы-спутники (`*.d.ts`, `*.spec.ts`, `*.test.ts`) в директории миграций игнорируются и
|
|
||||||
генератором, и `tools/checkDataSource.ts` — последний вызывает `readMigrations()` генератора, так
|
|
||||||
что правило фильтрации физически одно.
|
|
||||||
|
|
||||||
### Локальные команды
|
|
||||||
|
|
||||||
| Команда | Что делает |
|
|
||||||
| ------------------------------------ | ------------------------------------- |
|
|
||||||
| `yarn nx run api:db-migrations-list` | перегенерировать статический список |
|
|
||||||
| `yarn nx run api:db-show` | список миграций и их статус |
|
|
||||||
| `yarn nx run api:db-migrate` | применить непримененные |
|
|
||||||
| `yarn nx run api:db-revert` | откатить последнюю применённую |
|
|
||||||
| `yarn nx run api:db-drop` | удалить схему целиком (`schema:drop`) |
|
|
||||||
| `yarn nx run api:db-snapshot` | снять снимок данных в JSON |
|
|
||||||
| `yarn nx run api:db-restore` | восстановить данные из снимка |
|
|
||||||
|
|
||||||
Все они, кроме `db-migrations-list` (он работает только с файлами), подключаются к БД из `.env`
|
|
||||||
(`POSTGRES_USER` / `POSTGRES_PASSWORD` / `POSTGRES_DB` / `POSTGRES_HOST` / `POSTGRES_PORT`).
|
|
||||||
Отдельную базу можно подставить переменной окружения — `dotenv` работает с `override: false`,
|
|
||||||
поэтому окружение имеет приоритет над `.env`:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
POSTGRES_DB=aigeo_migtest yarn nx run api:db-migrate
|
|
||||||
```
|
|
||||||
|
|
||||||
## Проверки в CI
|
|
||||||
|
|
||||||
`.gitea/workflows/ci.yaml`:
|
|
||||||
|
|
||||||
- **`Check migrations list`** — `yarn ts-node tools/buildDataSource.ts --check`. Генератор рендерит
|
|
||||||
список, сравнивает с содержимым `apps/api/src/migrations.ts` и падает при расхождении, ничего не
|
|
||||||
записывая. Сравнение идёт с тем же отформатированным текстом, что и запись, поэтому git в проверке
|
|
||||||
не участвует вовсе.
|
|
||||||
- **`Check data-source`** (после `yarn build`) — `yarn ts-node tools/checkDataSource.ts` загружает
|
|
||||||
собранный `apps/api/dist/data-source.js`, проверяет, что экспорт ведёт себя как `DataSource`
|
|
||||||
(`initialize()` + объект `options`), и что список классов в бандле **посимвольно совпадает** с
|
|
||||||
тем, что даёт `readMigrations()` генератора по файлам на диске (там же валидируются 13-значные
|
|
||||||
timestamp-суффиксы имён классов).
|
|
||||||
|
|
||||||
Оба шага идут **до** сборки docker-образов: битый data-source не попадёт в реестр. Оба
|
|
||||||
продублированы в `.gitea/workflows/production.yaml` — теги не проходят через `ci.yaml` (он
|
|
||||||
срабатывает на push в master и на PR), поэтому свою копию проверок прод-путь обязан иметь.
|
|
||||||
|
|
||||||
### ⚠️ SQL миграций попадает в логи job
|
|
||||||
|
|
||||||
`MigrationRunCommand` принудительно выставляет `logging: ["query", "error", "schema"]` поверх
|
|
||||||
настроек `DataSource`, отключить это флагом или из `typeorm.config.ts` нельзя. Каждый выполненный
|
|
||||||
запрос — вместе со значениями параметров — уходит в лог job деплоя, видимый любому, у кого есть
|
|
||||||
доступ на чтение репозитория.
|
|
||||||
|
|
||||||
Это ограничение принято осознанно: тот же лог — основной инструмент разбора инцидента (см. Runbook,
|
|
||||||
шаг 1). Но из него следует жёсткое правило для авторов миграций:
|
|
||||||
|
|
||||||
**Data-миграции не должны переносить секреты и персональные данные литералами.** Если миграции нужно
|
|
||||||
изменить пароли, токены, email-адреса и т. п. — делайте это выражениями на стороне SQL
|
|
||||||
(`UPDATE … SET token = encode(gen_random_bytes(32), 'hex')`), а не `INSERT`/`UPDATE` с готовыми
|
|
||||||
значениями в тексте миграции. Разовые операции с реальными данными выполняйте вручную через
|
|
||||||
`docker exec` (раздел «Ручной запуск миграций на проде»), а не деплоем.
|
|
||||||
|
|
||||||
## Применение на стейджинге
|
|
||||||
|
|
||||||
Job `deploy-staging` в `.gitea/workflows/ci.yaml` (запускается на каждом PR и push в master), сразу
|
|
||||||
после `docker compose up -d`:
|
|
||||||
|
|
||||||
1. `migration:show` (в лог), затем `migration:run -t each` — через `docker compose exec -T api …`.
|
|
||||||
Отдельного ожидания готовности контейнера нет: живой/healthy HTTP-слой NestJS для
|
|
||||||
`typeorm migration:run` не нужен, он идёт отдельным процессом через `data-source.js`. Если
|
|
||||||
контейнер всё же не поднялся (например, при пустых `POSTGRES_*`), `docker compose exec` упадёт с
|
|
||||||
понятной ошибкой сам.
|
|
||||||
2. `docker system prune -f` — после миграций, одним вызовом в конце скрипта. Если `migration:run`
|
|
||||||
упадёт, под `set -e` prune не выполнится — почистится на следующем деплое.
|
|
||||||
|
|
||||||
Ненулевой код валит job: у шага стоит `script_stop: true` — действие открывает скрипт строкой
|
|
||||||
`set -e`, поэтому упавшая команда завершает его с её кодом выхода, а не продолжает выполнение.
|
|
||||||
|
|
||||||
### База и переменные `.env` на стейджинг-хосте
|
|
||||||
|
|
||||||
Роль и базу стенда создаёт `staging-db-postgres` на стейджинг-хосте — шаг `deploy-staging` в
|
|
||||||
`ci.yaml`, до `docker compose up`:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
staging-db-postgres create <org/project> <branch>
|
|
||||||
```
|
|
||||||
|
|
||||||
Имя роли и БД — `<org_project_branch>` после нормализации (всё не-алфанумерическое заменяется на
|
|
||||||
`_`, длиннее 63 байт — обрезается с хешем). Пароль генерируется при первом создании и
|
|
||||||
переиспользуется при повторных деплоях ветки. Доступы инструмент пишет в `.env` каталога деплоя
|
|
||||||
(`~/<repo>_<branch>/`): `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB`, `POSTGRES_HOST`,
|
|
||||||
`POSTGRES_PORT`. Те же имена `docker-compose.staging.yml` пробрасывает в api, их единственные читают
|
|
||||||
и приложение (`typeorm.config.ts`), и typeorm CLI. При удалении ветки или закрытии PR — с вливанием
|
|
||||||
или без — `cleanup.yaml` вызывает `staging-db-postgres delete`: удаляются БД, роль и строки
|
|
||||||
`POSTGRES_*` из `.env`.
|
|
||||||
|
|
||||||
В compose переменные объявлены через `${POSTGRES_HOST:-}`, то есть **не** обязательные. Обязательный
|
|
||||||
синтаксис `${POSTGRES_HOST:?…}` здесь применять нельзя: он валит любую подкоманду compose, включая
|
|
||||||
`pull` и `down`, — а полуподнятый стек надо уметь погасить.
|
|
||||||
|
|
||||||
`concurrency.cancel-in-progress` в `ci.yaml` оставлен `true` (в отличие от прода). Группа привязана
|
|
||||||
к ветке, поэтому отменяется только предыдущий прогон той же ветки, а быстрая итерация по PR важнее.
|
|
||||||
Плата реальна: отмена посреди `migration:run -t each` оставит базу ветки частично мигрированной
|
|
||||||
(лечится повторным прогоном job).
|
|
||||||
|
|
||||||
## Применение на проде
|
|
||||||
|
|
||||||
Job `deploy-production` в `.gitea/workflows/production.yaml`, шаг `Deploy via SSH` — тот же
|
|
||||||
`jt4d-lab/ssh-action`, что и на стейджинге, плюс `workdir: /srv/jt4d` и
|
|
||||||
`files: docker-compose.production.yml`: компоуз-файл приезжает тем же шагом, отдельного `scp` нет.
|
|
||||||
Порядок:
|
|
||||||
|
|
||||||
1. `docker-compose pull` → `down` → `up -d`.
|
|
||||||
2. Сразу после `up -d` — `migration:show` (в лог видно, что именно будет применено), затем
|
|
||||||
`migration:run -t each`. Последняя команда скрипта, её код выхода уходит через `ssh` и валит job.
|
|
||||||
|
|
||||||
Ожидания готовности контейнера между шагами 1 и 2 нет, и это намеренно:
|
|
||||||
|
|
||||||
- postgres поднимается **до** api — у api стоит `depends_on: postgres: condition: service_healthy`,
|
|
||||||
так что `up -d` не вернётся, пока БД не готова;
|
|
||||||
- `docker exec` сам падает, если контейнер не `running`, — отдельная проверка того же лишь
|
|
||||||
дублировала бы это раньше по времени и потому менее достоверно (с `restart: unless-stopped`
|
|
||||||
крешлупящий контейнер периодически бывает `running`);
|
|
||||||
- ждать `healthy` не нужно тем более: healthcheck образа (`curl /api/health`, `start-period=15s`)
|
|
||||||
поднимает HTTP-слой NestJS, а `migration:run` идёт отдельным процессом со своим соединением через
|
|
||||||
`data-source.js`.
|
|
||||||
|
|
||||||
Логи приложения при провале смотрятся на хосте: `docker logs jt4d_api --tail 50`.
|
|
||||||
|
|
||||||
⚠️ `migration:show` — не безобидная команда «только посмотреть»:
|
|
||||||
|
|
||||||
- `showMigrations()` вызывает `createMigrationsTableIfNotExist()`
|
|
||||||
(`typeorm/migration/MigrationExecutor.js`), то есть выполняет настоящий
|
|
||||||
`CREATE TABLE "migrations"`, если таблицы ещё нет;
|
|
||||||
- `MigrationShowCommand` завершается кодом `0` только на успешном пути. В `catch` стоит
|
|
||||||
`process.exit(1)` — например, при `permission denied for schema public` у `aigeo_app`.
|
|
||||||
|
|
||||||
Под `set -e` это означает, что деплой упадёт уже на `migration:show`, если у `aigeo_app` нет прав на
|
|
||||||
DDL, — и упадёт после того, как новый образ ушёл на трафик.
|
|
||||||
|
|
||||||
`concurrency.group` этого workflow — константа `production-deploy`, а не имя ref. Workflow
|
|
||||||
запускается по тегам, и группа с тегом в имени давала бы каждому тегу собственную группу: два тега
|
|
||||||
подряд запустили бы два `migration:run -t each` параллельно по одной БД, а кросс-процессной
|
|
||||||
блокировки у TypeORM нет. `cancel-in-progress: false` — отмена job посреди набора рвёт SSH-сессию и
|
|
||||||
оставляет БД частично мигрированной.
|
|
||||||
|
|
||||||
`VERSION` и `LOG_LEVEL` передаются в remote-скрипт через `env:` шага и вход `envs:`, а не
|
|
||||||
подстановкой `${{ … }}` в тело скрипта: `VERSION` приходит из git-тега, а в имени ref допустимы
|
|
||||||
кавычки, `;`, `$` и обратные кавычки — шаблонизатор вписал бы их в текст скрипта до запуска шелла.
|
|
||||||
`envs` к тому же всегда оборачивает значение в одинарные кавычки. Оба значения валидируются по
|
|
||||||
белому списку символов (`VERSION` — в job `build`, `LOG_LEVEL` — отдельным шагом перед деплоем).
|
|
||||||
|
|
||||||
### Почему `-t each`
|
|
||||||
|
|
||||||
Каждая миграция выполняется в своей транзакции, а не весь набор в одной длинной. Это осознанное
|
|
||||||
решение: не держим блокировки на всё время деплоя. Плата — при провале на N-й миграции первые N−1
|
|
||||||
остаются применёнными, БД оказывается в промежуточном состоянии. Разбор такого состояния ручной.
|
|
||||||
|
|
||||||
### Почему миграции после `up -d`, а не до
|
|
||||||
|
|
||||||
Осознанное решение. Риск не в нескольких секундах старой схемы, а в том, что при провале миграции
|
|
||||||
новый образ продолжает обслуживать трафик против старой схемы бесконечно
|
|
||||||
(`restart: unless-stopped`). Именно поэтому деплой логирует предыдущий тег образа, а ниже описан
|
|
||||||
runbook отката.
|
|
||||||
|
|
||||||
## ⚠️ Автоматического бэкапа перед миграцией нет
|
|
||||||
|
|
||||||
Деплой **не снимает дамп БД** перед запуском миграций. Это вынесено в отдельную задачу и на момент
|
|
||||||
написания не реализовано.
|
|
||||||
|
|
||||||
Существующий cron-бэкап (`apps/api/src/database/backup.service.ts` + `backup-scheduler.service.ts`)
|
|
||||||
на прод рассчитывать нельзя: в `apps/api/Dockerfile` нет `postgresql-client`, а `BACKUP_DIR` не
|
|
||||||
смонтирован томом в `docker-compose.production.yml`.
|
|
||||||
|
|
||||||
**Практический вывод:** если содержимое БД критично, снимите дамп вручную перед запуском
|
|
||||||
прод-деплоя. При разборе инцидента не рассчитывайте на существование свежей резервной копии.
|
|
||||||
|
|
||||||
## Runbook: миграция упала на проде
|
|
||||||
|
|
||||||
Из-за `-t each` набор может быть применён частично. Порядок разбора:
|
|
||||||
|
|
||||||
1. **Определить, до какой миграции дошли.** В логе job шаг `Применение миграций` печатает каждую
|
|
||||||
применённую миграцию с её `START TRANSACTION` / `COMMIT`. Последняя успешная строка — граница;
|
|
||||||
следующая за ней миграция и есть упавшая, там же лежит текст ошибки от Postgres.
|
|
||||||
2. **Сверить с реальным состоянием БД:**
|
|
||||||
|
|
||||||
```bash
|
|
||||||
ssh <prod>
|
|
||||||
docker exec jt4d_api node_modules/.bin/typeorm migration:show -d data-source.js
|
|
||||||
```
|
|
||||||
|
|
||||||
`[X]` — применена, `[ ]` — нет. Этот вывод — источник истины, а не лог job.
|
|
||||||
|
|
||||||
3. **Решить, катить вперёд или чинить.**
|
|
||||||
- Ошибка разовая (таймаут, блокировка, нехватка прав) — починить причину и повторить
|
|
||||||
`migration:run -t each` вручную (см. ниже). Уже применённые миграции пропустятся.
|
|
||||||
- Ошибка в самой миграции — исправлять кодом: новая миграция поверх либо правка упавшей с
|
|
||||||
последующим передеплоем. Ручные правки схемы мимо миграций оставляют прод и репозиторий в
|
|
||||||
расхождении, и следующий деплой упадёт снова.
|
|
||||||
4. **Откатить образ, если сервис сломан.** Предыдущий тег — это предыдущий тег `v*` в репозитории
|
|
||||||
(`git tag --sort=-creatordate | head`); что именно скачано на хост, видно в
|
|
||||||
`docker images git.jt4d.ru/jt4d/jt4d/api`:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd /srv/jt4d
|
|
||||||
VERSION=<prev> docker-compose up -d
|
|
||||||
```
|
|
||||||
|
|
||||||
⚠️ Один `VERSION` применяется сразу к `web` и `api`. Команда корректна только если оба образа
|
|
||||||
тегированы синхронно (обычный случай — их собирает один прогон `production.yaml`). Если теги
|
|
||||||
разошлись, поднимайте сервисы по одному (`VERSION=<prev> docker-compose up -d api`).
|
|
||||||
|
|
||||||
Откат образа **не откатывает схему БД** — применённые миграции остаются применёнными. Если
|
|
||||||
старый код несовместим с новой схемой, откатывать схему придётся отдельно (`migration:revert`,
|
|
||||||
по одной миграции за вызов) или восстанавливать из ручного дампа.
|
|
||||||
|
|
||||||
5. **Проверить результат:** `/api/health` и `docker logs jt4d_api --tail 100`.
|
|
||||||
|
|
||||||
## Ручной запуск миграций на проде
|
|
||||||
|
|
||||||
Понадобится, если миграции нужно применить вне деплоя (повтор после разбора инцидента, разовая
|
|
||||||
операция). Порт postgres наружу не проброшен, поэтому всё делается через `docker exec` внутри
|
|
||||||
контейнера api — `WORKDIR` образа `/app`, там же лежат `data-source.js` и `node_modules`:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
ssh <prod>
|
|
||||||
|
|
||||||
# посмотреть, что применится
|
|
||||||
docker exec jt4d_api node_modules/.bin/typeorm migration:show -d data-source.js
|
|
||||||
|
|
||||||
# применить
|
|
||||||
docker exec jt4d_api node_modules/.bin/typeorm migration:run -t each -d data-source.js
|
|
||||||
|
|
||||||
# откатить последнюю применённую (по одной за вызов)
|
|
||||||
docker exec jt4d_api node_modules/.bin/typeorm migration:revert -d data-source.js
|
|
||||||
```
|
|
||||||
|
|
||||||
Перед запуском учтите, что автоматического бэкапа нет (см. выше).
|
|
||||||
|
|
||||||
## Права на БД
|
|
||||||
|
|
||||||
Api ходит в прод-БД под `aigeo_app` — это не владелец схемы. Первое, обо что упадёт `migration:run`
|
|
||||||
в свежем окружении, — нехватка прав на DDL. Проверяется пробным `CREATE TABLE _ddl_probe(...)` /
|
|
||||||
`DROP TABLE _ddl_probe` из-под `aigeo_app`.
|
|
||||||
|
|
||||||
Если схема уже содержит объекты из миграций, а записей в таблице `migrations` нет, `migration:run`
|
|
||||||
попытается создать существующее и упадёт. Такое состояние надо **забаселайнить** — проставить записи
|
|
||||||
без выполнения `up()`.
|
|
||||||
|
|
||||||
**Полный baseline** (вся схема уже соответствует всем непримененным миграциям) — штатный флаг
|
|
||||||
TypeORM `--fake` / `-f` (`MigrationRunCommand`, `MigrationExecutor`):
|
|
||||||
|
|
||||||
```bash
|
|
||||||
docker exec jt4d_api node_modules/.bin/typeorm migration:show -d data-source.js # сначала посмотреть список
|
|
||||||
docker exec jt4d_api node_modules/.bin/typeorm migration:run --fake -d data-source.js
|
|
||||||
```
|
|
||||||
|
|
||||||
`--fake` вставляет записи в таблицу `migrations`, не выполняя `up()`. Он применяется ко **всему**
|
|
||||||
набору непримененных миграций сразу, выборочно пометить одну нельзя. Поэтому использовать его можно
|
|
||||||
только когда `migration:show` показывает `[ ]` ровно у тех миграций, объекты которых в схеме уже
|
|
||||||
есть.
|
|
||||||
|
|
||||||
**Частичный baseline** (часть непримененных миграций в схеме есть, часть — нет): `--fake` не
|
|
||||||
подходит, записи проставляются вручную по одной:
|
|
||||||
|
|
||||||
```sql
|
|
||||||
INSERT INTO migrations (timestamp, name) VALUES (1764100000000, 'AddPublicMetricRequests1764100000000');
|
|
||||||
```
|
|
||||||
|
|
||||||
`name` — имя класса точь-в-точь, `timestamp` — числовой префикс из имени файла (он же обязан
|
|
||||||
совпадать с 13-значным суффиксом имени класса — это проверяет генератор). Ошибка в `name` не
|
|
||||||
диагностируется ничем: миграция либо молча выполнится повторно, либо будет пропущена навсегда.
|
|
||||||
|
|
||||||
### Перед первым прод-деплоем
|
|
||||||
|
|
||||||
Прод-деплой применяет миграции на каждый тег — поэтому проверки ниже делаются **до** первого деплоя
|
|
||||||
с миграциями, а не после:
|
|
||||||
|
|
||||||
1. проверить права `aigeo_app` на DDL: пробный `CREATE TABLE _ddl_probe(...)` / `DROP TABLE` из-под
|
|
||||||
него (раздел «Права на БД» выше). Без них деплой упадёт уже на `migration:show`;
|
|
||||||
2. привести таблицу `migrations` в согласованное состояние — baseline, если схема уже содержит
|
|
||||||
объекты из непримененных миграций (там же). Иначе первая же миграция упадёт на
|
|
||||||
`relation already exists`, а с `-t each` набор останется применённым частично;
|
|
||||||
3. снять ручной дамп БД — автоматического бэкапа нет (см. выше).
|
|
||||||
|
|
||||||
То же самое верно для первого деплоя на стейджинге (раздел «Применение на стейджинге»).
|
|
||||||
@@ -1,56 +0,0 @@
|
|||||||
# Geo Platform
|
|
||||||
|
|
||||||
Geo Platform — рабочее пространство для управления присутствием бренда в поисковиках и генеративных
|
|
||||||
ИИ-системах (ChatGPT, Perplexity, Google AI Overviews и т. п.). Платформа помогает подготовить о
|
|
||||||
бренде структурированные, проверяемые и согласованные данные, чтобы поиск и LLM отвечали о нём
|
|
||||||
корректно. Аббревиатура GEO расшифровывается как **Generative Engine Optimization**.
|
|
||||||
|
|
||||||
## Кому подходит
|
|
||||||
|
|
||||||
- Владельцам бизнеса, которым важно, как их компанию описывают поисковики и ИИ-ассистенты.
|
|
||||||
- SEO- и контент-специалистам, отвечающим за структурированные данные, Entity Home и E-E-A-T.
|
|
||||||
- Маркетологам и агентствам, ведущим сразу несколько брендов.
|
|
||||||
- Администраторам, управляющим пользователями платформы.
|
|
||||||
|
|
||||||
## Что можно делать
|
|
||||||
|
|
||||||
- Заводить и вести карточки брендов: название, сайт, ключевые слова, статус, команда с ролями.
|
|
||||||
- Заполнять «паспорт бренда» через пошаговый мастер: юридические данные, миссия, описание, контакты,
|
|
||||||
адрес, политики.
|
|
||||||
- Автоматически генерировать JSON-LD (Organization, LocalBusiness и др.) на основе паспорта и
|
|
||||||
выгружать его для встраивания на сайт.
|
|
||||||
- Проводить NAP-аудит: сверять имя, адрес и телефон бренда во внешних справочниках, соцсетях и
|
|
||||||
сайтах отзывов, отслеживать оценку согласованности.
|
|
||||||
- Собирать Entity Home — авторитетные страницы о компании, команде, доверии и контактах со
|
|
||||||
структурированными фактами.
|
|
||||||
- Связывать бренд с Wikidata через Q-элементы, чтобы закрепить сущность в открытом графе знаний.
|
|
||||||
- Измерять GEO-видимость через LLM-метрики: как часто бренд упоминается ИИ-моделями, в каком
|
|
||||||
контексте и по каким запросам.
|
|
||||||
- Проверять технику сайта: доступность, SSL, базовые сигналы качества.
|
|
||||||
- Отслеживать историю изменений в журнале аудита — ручные правки, импорты, автосинхронизации.
|
|
||||||
- Сравнивать тарифы на витрине — она открыта и без входа, а вошедшему отмечает его текущий план.
|
|
||||||
- Смотреть свою подписку: план, его условия и дата окончания оплаченного периода.
|
|
||||||
- Администраторам — вести тарифную линейку (планы и их версии) и разбирать биллинг конкретного
|
|
||||||
пользователя в его карточке.
|
|
||||||
|
|
||||||
## Разделы интерфейса
|
|
||||||
|
|
||||||
- **Workspace** — список брендов и создание нового.
|
|
||||||
- **Brand Management** — управление одним брендом: сущности, метрики, проверки сайта, отчёты.
|
|
||||||
- **Entity Graph** — работа с данными сущности: Overview, Passport, JSON-LD, Connectors, Audit,
|
|
||||||
Entity Home, Wikidata.
|
|
||||||
- **Тарифы (`/pricing`)** — публичная витрина планов: цены и условия, доступна без входа.
|
|
||||||
- **Settings** — профиль пользователя, язык, тема, вкладка «Моя подписка» с текущим тарифом.
|
|
||||||
- **Admin** — управление пользователями (в карточке пользователя есть вкладка биллинга), тарифная
|
|
||||||
линейка («Тарифы», `/admin/plans`) и системные настройки платформы.
|
|
||||||
|
|
||||||
## Термины
|
|
||||||
|
|
||||||
- **Бренд (Brand / Project)** — основная сущность платформы, объединяет все данные компании.
|
|
||||||
- **Сущность (Entity)** — отдельный объект бренда: филиал, локация, юрлицо.
|
|
||||||
- **NAP** — Name, Address, Phone: канонические контактные данные, которые сверяются с внешними
|
|
||||||
профилями.
|
|
||||||
- **Паспорт бренда (Passport)** — структурированная анкета о компании, из которой строятся JSON-LD и
|
|
||||||
Entity Home.
|
|
||||||
- **JSON-LD** — формат структурированных данных, который читают поисковики и ИИ-модели.
|
|
||||||
- **GEO** — оптимизация под генеративные поисковые системы.
|
|
||||||
+1
-1
@@ -48,7 +48,7 @@ export default defineConfig([
|
|||||||
position: 'before',
|
position: 'before',
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
pattern: '@jt4d-platform/**',
|
pattern: '@it-smi/**',
|
||||||
group: 'internal',
|
group: 'internal',
|
||||||
},
|
},
|
||||||
],
|
],
|
||||||
|
|||||||
+1
-1
@@ -1,5 +1,5 @@
|
|||||||
{
|
{
|
||||||
"name": "jt4d-platform",
|
"name": "it-smi",
|
||||||
"$schema": "./node_modules/nx/schemas/project-schema.json",
|
"$schema": "./node_modules/nx/schemas/project-schema.json",
|
||||||
"targets": {
|
"targets": {
|
||||||
"lint": {
|
"lint": {
|
||||||
|
|||||||
+3
-3
@@ -15,13 +15,13 @@
|
|||||||
"target": "es2022",
|
"target": "es2022",
|
||||||
"baseUrl": "./",
|
"baseUrl": "./",
|
||||||
"customConditions": [
|
"customConditions": [
|
||||||
"@jt4d-platform/source"
|
"@it-smi/source"
|
||||||
],
|
],
|
||||||
"paths": {
|
"paths": {
|
||||||
"@jt4d-platform/api/*": [
|
"@it-smi/api/*": [
|
||||||
"apps/api/src/*"
|
"apps/api/src/*"
|
||||||
],
|
],
|
||||||
"@jt4d-platform/web/*": [
|
"@it-smi/web/*": [
|
||||||
"apps/web/src/*"
|
"apps/web/src/*"
|
||||||
]
|
]
|
||||||
},
|
},
|
||||||
|
|||||||
Reference in new issue
Block a user