feat: отправка формы обращения в SharePoint через api.tnsu.kz

POST /feedback собирает поля формы в столбцы списка (Company резолвится
в название по справочнику, Type/Title — по виду обращения) и создаёт
элемент через api.tnsu.kz /SharePoint/ListItem. Ошибки авторизации и
апстрима логируются в stdout и возвращаются клиенту как 502, чтобы сбой
на проде было видно явно.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

.dockerignore

@@ -0,0 +1,7 @@
+node_modules
+dist
+dist-ssr
+.git
+.vscode
+.idea
+npm-debug.log*

.gitea/workflows/deploy.yml

@@ -0,0 +1,123 @@
+name: build-and-deploy
+
+# Прод — единственное окружение деплоя, поэтому катим при каждом пуше в main.
+# Раннер должен быть self-hosted во внутренней сети: Nexus (nexus.tnsu.kz) снаружи
+# не достаётся. workflow_dispatch — на случай ручного передеплоя (например, старым тегом).
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+    inputs:
+      image_tag:
+        description: "Тег образа (по умолчанию — короткий sha коммита)"
+        required: false
+        default: ""
+
+env:
+  REGISTRY: nexus.tnsu.kz:8082
+
+jobs:
+  # Единый источник тега для образа и для деплоя
+  prepare:
+    runs-on: ubuntu-22.04
+    outputs:
+      tag: ${{ steps.vars.outputs.tag }}
+    steps:
+      - name: Resolve image tag
+        id: vars
+        run: |
+          TAG="${{ github.event.inputs.image_tag }}"
+          if [ -z "$TAG" ]; then TAG="${GITHUB_SHA::8}"; fi
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+
+  build-and-push:
+    needs: prepare
+    runs-on: ubuntu-22.04
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - image: hr-appeals-web
+            context: .
+            dockerfile: Dockerfile
+          - image: hr-appeals-auth
+            context: server
+            dockerfile: server/Dockerfile
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Ensure docker CLI is installed
+        run: |
+          set -e
+          SUDO=""
+          if [ "$(id -u)" -ne 0 ]; then SUDO="sudo"; fi
+          if ! command -v docker >/dev/null 2>&1; then
+            $SUDO apt-get update
+            $SUDO env DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends docker.io
+          fi
+
+      - name: Docker login to Nexus
+        run: echo "${{ secrets.NEXUS_PASSWORD }}" | docker login "$REGISTRY" -u "${{ secrets.NEXUS_USER }}" --password-stdin
+
+      - name: Build image
+        run: |
+          docker build \
+            -f "${{ matrix.dockerfile }}" \
+            -t "$REGISTRY/${{ matrix.image }}:${{ needs.prepare.outputs.tag }}" \
+            -t "$REGISTRY/${{ matrix.image }}:latest" \
+            "${{ matrix.context }}"
+
+      - name: Push image
+        run: |
+          docker push "$REGISTRY/${{ matrix.image }}:${{ needs.prepare.outputs.tag }}"
+          docker push "$REGISTRY/${{ matrix.image }}:latest"
+
+      - name: Docker logout
+        if: always()
+        run: docker logout "$REGISTRY"
+
+  deploy:
+    needs: [prepare, build-and-push]
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Ensure ssh client is installed
+        run: |
+          set -e
+          SUDO=""
+          if [ "$(id -u)" -ne 0 ]; then SUDO="sudo"; fi
+          if ! command -v ssh >/dev/null 2>&1 || ! command -v scp >/dev/null 2>&1 || ! command -v ssh-keyscan >/dev/null 2>&1; then
+            $SUDO apt-get update
+            $SUDO env DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends openssh-client
+          fi
+
+      - name: Configure SSH
+        run: |
+          mkdir -p ~/.ssh
+          printf '%s\n' "${{ secrets.DEPLOY_SSH_KEY }}" > ~/.ssh/deploy_key
+          chmod 600 ~/.ssh/deploy_key
+          ssh-keyscan -H "${{ vars.DEPLOY_HOST }}" >> ~/.ssh/known_hosts
+
+      - name: Upload compose file
+        run: |
+          scp -i ~/.ssh/deploy_key docker-compose.yml \
+            "${{ vars.DEPLOY_USER }}@${{ vars.DEPLOY_HOST }}:${{ vars.DEPLOY_PATH }}/docker-compose.yml"
+
+      - name: Roll out
+        run: |
+          ssh -i ~/.ssh/deploy_key "${{ vars.DEPLOY_USER }}@${{ vars.DEPLOY_HOST }}" "
+            set -e
+            cd '${{ vars.DEPLOY_PATH }}'
+            sed -i '/^IMAGE_TAG=/d' .env
+            echo 'IMAGE_TAG=${{ needs.prepare.outputs.tag }}' >> .env
+            docker compose pull
+            docker compose up -d --remove-orphans
+            docker image prune -f
+          "
+
+      - name: Cleanup SSH key
+        if: always()
+        run: rm -f ~/.ssh/deploy_key

Dockerfile

@@ -0,0 +1,16 @@
+# syntax=docker/dockerfile:1
+
+FROM node:20-alpine AS build
+WORKDIR /app
+
+COPY package.json package-lock.json .npmrc ./
+RUN npm ci
+
+COPY . .
+RUN npm run build
+
+FROM nginx:1.27-alpine AS runtime
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+COPY --from=build /app/dist /usr/share/nginx/html
+
+EXPOSE 80

docker-compose.yml

@@ -0,0 +1,23 @@
+services:
+  hr-appeals-web:
+    image: nexus.tnsu.kz:8082/hr-appeals-web:${IMAGE_TAG:-latest}
+    restart: unless-stopped
+    ports:
+      - "80:80"
+    depends_on:
+      - hr-appeals-auth
+
+  hr-appeals-auth:
+    image: nexus.tnsu.kz:8082/hr-appeals-auth:${IMAGE_TAG:-latest}
+    restart: unless-stopped
+    environment:
+      GRAPH_TENANT_ID: ${GRAPH_TENANT_ID:?в .env на сервере не задан GRAPH_TENANT_ID}
+      GRAPH_CLIENT_ID: ${GRAPH_CLIENT_ID:?в .env на сервере не задан GRAPH_CLIENT_ID}
+      GRAPH_CERT_PATH: /certs/SPFxDeploy_cert.pem
+      GRAPH_KEY_PATH: /certs/SPFxDeploy_key.pem
+      SHAREPOINT_SITE_URL: ${SHAREPOINT_SITE_URL:?в .env на сервере не задан SHAREPOINT_SITE_URL}
+      SHAREPOINT_LIST_NAME: ${SHAREPOINT_LIST_NAME:?в .env на сервере не задан SHAREPOINT_LIST_NAME}
+    volumes:
+      # Каталог с сертификатом/ключом на сервере — путь задаётся в .env
+      # (GRAPH_CERT_DIR), сами файлы в git не попадают.
+      - ${GRAPH_CERT_DIR:?в .env на сервере не задан GRAPH_CERT_DIR}:/certs:ro

nginx.conf

@@ -0,0 +1,18 @@
+server {
+    listen 80;
+    server_name _;
+
+    root /usr/share/nginx/html;
+    index index.html;
+
+    # Запросы к Graph/SharePoint идут не из браузера, а через сервис
+    # hr-appeals-auth — он подписывает JWT сертификатом и меняет его на
+    # app-only токен, клиенту токен и приватный ключ не видны.
+    location /api/ {
+        proxy_pass http://hr-appeals-auth:3000/;
+    }
+
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+}

server/.dockerignore

@@ -0,0 +1,2 @@
+node_modules
+dist

server/Dockerfile

@@ -0,0 +1,22 @@
+# syntax=docker/dockerfile:1
+
+FROM node:20-alpine AS build
+WORKDIR /app
+
+COPY package.json package-lock.json ./
+RUN npm ci
+
+COPY . .
+RUN npm run build
+
+FROM node:20-alpine AS runtime
+WORKDIR /app
+ENV NODE_ENV=production
+
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev
+
+COPY --from=build /app/dist ./dist
+
+EXPOSE 3000
+CMD ["node", "dist/index.js"]

server/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "hr-appeals-auth",
+  "version": "0.1.0",
+  "private": true,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "express": "^4.21.2",
+    "jsonwebtoken": "^9.0.2"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/jsonwebtoken": "^9.0.7",
+    "@types/node": "^22.20.1",
+    "typescript": "~5.8.0"
+  }
+}

server/src/config.ts

@@ -0,0 +1,18 @@
+function requireEnv(name: string): string {
+  const value = process.env[name];
+  if (!value) {
+    throw new Error(`Не задана переменная окружения ${name}`);
+  }
+  return value;
+}
+
+export const config = {
+  tenantId: requireEnv('GRAPH_TENANT_ID'),
+  clientId: requireEnv('GRAPH_CLIENT_ID'),
+  certPath: requireEnv('GRAPH_CERT_PATH'),
+  keyPath: requireEnv('GRAPH_KEY_PATH'),
+  scope: process.env.GRAPH_SCOPE ?? 'https://graph.microsoft.com/.default',
+  port: Number(process.env.PORT ?? 3000),
+  sharepointSiteUrl: requireEnv('SHAREPOINT_SITE_URL'),
+  sharepointListName: requireEnv('SHAREPOINT_LIST_NAME')
+};

server/src/graphAuth.ts

@@ -0,0 +1,81 @@
+import { readFileSync } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import jwt from 'jsonwebtoken';
+import { config } from './config';
+
+interface CachedToken {
+  accessToken: string;
+  expiresAt: number;
+}
+
+interface TokenResponse {
+  access_token: string;
+  expires_in: number;
+}
+
+const TOKEN_ENDPOINT = `https://login.microsoftonline.com/${config.tenantId}/oauth2/v2.0/token`;
+
+// Обновляем токен заранее, а не строго по истечении — иначе запрос, уже летящий
+// к Graph с почти протухшим токеном, может получить 401.
+const REFRESH_MARGIN_MS = 60_000;
+
+let cached: CachedToken | null = null;
+
+function buildClientAssertion(): string {
+  const certificatePem = readFileSync(config.certPath, 'utf8');
+  const privateKey = readFileSync(config.keyPath, 'utf8');
+
+  // x5t — SHA-1 отпечаток DER-сертификата, base64url. По нему Azure AD находит
+  // публичный ключ приложения и проверяет подпись JWT.
+  const der = certificatePem
+    .replace(/-----BEGIN CERTIFICATE-----/, '')
+    .replace(/-----END CERTIFICATE-----/, '')
+    .replace(/\s+/g, '');
+  const thumbprint = createHash('sha1').update(Buffer.from(der, 'base64')).digest('base64url');
+
+  const nowSeconds = Math.floor(Date.now() / 1000);
+
+  return jwt.sign(
+    {
+      aud: TOKEN_ENDPOINT,
+      iss: config.clientId,
+      sub: config.clientId,
+      jti: randomUUID(),
+      nbf: nowSeconds,
+      exp: nowSeconds + 5 * 60
+    },
+    privateKey,
+    { algorithm: 'RS256', header: { alg: 'RS256', x5t: thumbprint } }
+  );
+}
+
+export async function getAppOnlyToken(): Promise<string> {
+  if (cached && cached.expiresAt - REFRESH_MARGIN_MS > Date.now()) {
+    return cached.accessToken;
+  }
+
+  const body = new URLSearchParams({
+    grant_type: 'client_credentials',
+    client_id: config.clientId,
+    client_assertion_type: 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
+    client_assertion: buildClientAssertion(),
+    scope: config.scope
+  });
+
+  const response = await fetch(TOKEN_ENDPOINT, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body
+  });
+
+  if (!response.ok) {
+    throw new Error(`Не удалось получить app-only токен: ${response.status} ${await response.text()}`);
+  }
+
+  const data = (await response.json()) as TokenResponse;
+  cached = {
+    accessToken: data.access_token,
+    expiresAt: Date.now() + data.expires_in * 1000
+  };
+  return cached.accessToken;
+}

server/src/index.ts

@@ -0,0 +1,41 @@
+import express from 'express';
+import { config } from './config';
+import { getAppOnlyToken } from './graphAuth';
+import { submitFeedback } from './sharepoint';
+
+const app = express();
+app.use(express.json());
+
+app.get('/healthz', (_req, res) => {
+  res.status(200).send('ok');
+});
+
+// Временный диагностический эндпоинт: подтверждает, что связка
+// "сертификат -> подписанный JWT -> access-токен" реально работает,
+// до того как появится сама логика сохранения формы в Graph/SharePoint.
+app.get('/diag/token', async (_req, res) => {
+  try {
+    await getAppOnlyToken();
+    res.status(200).json({ ok: true });
+  } catch (error) {
+    res.status(502).json({ ok: false, error: (error as Error).message });
+  }
+});
+
+app.post('/feedback', async (req, res) => {
+  try {
+    await submitFeedback(req.body);
+    res.status(201).json({ ok: true });
+  } catch (error) {
+    const message = (error as Error).message;
+    // Логируем целиком в stdout прод-контейнера — если отвалится авторизация
+    // (протухший/незарегистрированный сертификат, неверный scope), это должно
+    // быть видно сразу в логах, а не тонуть в одной строке ответа клиенту.
+    console.error('Не удалось отправить обращение в SharePoint:', message);
+    res.status(502).json({ ok: false, error: message });
+  }
+});
+
+app.listen(config.port, () => {
+  console.log(`hr-appeals-auth listening on :${config.port}`);
+});

server/src/sharepoint.ts

@@ -0,0 +1,91 @@
+import { config } from './config';
+import { getAppOnlyToken } from './graphAuth';
+
+const SHAREPOINT_API_URL = 'https://api.tnsu.kz/SharePoint/ListItem';
+
+export type AppealKind = 'complaint' | 'suggestion' | 'other';
+
+const KIND_LABELS: Record<AppealKind, string> = {
+  complaint: 'Обращение',
+  suggestion: 'Предложение',
+  other: 'Другое'
+};
+
+// Форма присылает id компании из справочника (см. COMPANY_OPTIONS во фронтовом
+// src/features/feedback/model.ts) — колонка Company в SharePoint текстовая и
+// ждёт название, а не id, поэтому здесь его резолвим. Список держим в синхроне
+// с фронтовым вручную — общего пакета между сервером и клиентом сейчас нет.
+const COMPANY_NAMES: Record<string, string> = {
+  '8028abac-ac23-8fd8-11ef-cb57631a9ab0': 'ТОО AFL Engineering',
+  '9de064a4-44c8-88ef-11ec-831c058b1141': 'ТОО CL MANAGEMENT',
+  '9de064a4-44c8-88ef-11ec-8287fb7737a2': 'ТОО KazPromService',
+  'ec3c78a7-29ef-4725-11ed-a6d8fcd0911d': 'ТОО QAZGEOMAX',
+  '15009595-005d-00fa-11ef-11309f5e395d': 'ТОО Selin Invest',
+  '03f4deac-f543-e8cf-11f1-84eb25329fc3': 'ТОО Selin Studio',
+  '9de064a4-44c8-88ef-11ec-8284930fad96': 'ТОО TANSU Construction',
+  '9de064a4-44c8-88ef-11ec-8285925d83d2': 'ТОО АСТЕЛ-К',
+  '15009595-005d-00fa-11ef-0b8bb5ec1a88': 'ТОО ГеоТрек',
+  '15009595-005d-00fa-11ef-0b8714483372': 'ТОО Монтажник-Т',
+  '8028beac-ac23-8fd8-11f0-5351706e5996': 'ТОО ОСН Беркут',
+  '8028b0ac-ac23-8fd8-11ef-dcdb24b82e02': 'ТОО СТ Global',
+  '15009595-005d-00fa-11ef-1131801d9f3e': 'ТОО ТехЛаб',
+  '03f4deac-f543-e8cf-11f1-84f51483f59e': 'Частная компания Seline Holding Ltd'
+};
+
+export interface IFeedbackSubmission {
+  company: string;
+  isAnonymous: boolean;
+  fullName: string;
+  position: string;
+  wantsFeedback: boolean;
+  kind: AppealKind;
+  kindOther: string;
+  situation: string;
+  suggestion: string;
+}
+
+// Имена полей — internal name столбцов списка SharePoint (Company/Name/Position/
+// Type/IssueDescription/SuggestionText/WantsFeedback), не отображаемые названия.
+function buildFields(data: IFeedbackSubmission): Record<string, unknown> {
+  const typeLabel = data.kind === 'other' ? data.kindOther : KIND_LABELS[data.kind];
+  const name = data.isAnonymous ? '' : data.fullName;
+  const companyName = COMPANY_NAMES[data.company];
+
+  if (!companyName) {
+    console.warn(`Неизвестный id компании из формы, отправляю как есть: ${data.company}`);
+  }
+
+  return {
+    Title: name ? `${typeLabel} — ${name}` : typeLabel,
+    Company: companyName ?? data.company,
+    Name: name,
+    Position: data.isAnonymous ? '' : data.position,
+    Type: typeLabel,
+    IssueDescription: data.situation,
+    SuggestionText: data.suggestion,
+    WantsFeedback: data.wantsFeedback
+  };
+}
+
+export async function submitFeedback(data: IFeedbackSubmission): Promise<void> {
+  const token = await getAppOnlyToken();
+
+  const response = await fetch(SHAREPOINT_API_URL, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${token}`
+    },
+    body: JSON.stringify({
+      siteUrl: config.sharepointSiteUrl,
+      listName: config.sharepointListName,
+      fields: buildFields(data)
+    })
+  });
+
+  if (!response.ok) {
+    throw new Error(
+      `api.tnsu.kz вернул ошибку при создании элемента списка: ${response.status} ${await response.text()}`
+    );
+  }
+}

server/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "lib": ["ES2022"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src"]
+}

src/features/feedback/model.test.ts

@@ -4,7 +4,7 @@ import { COMPANY_OPTIONS, getAppealFieldsConfig } from './model';
 // правило из getAppealFieldsConfig — если оно разойдётся, форма и валидация
 // начнут спорить друг с другом. Эти тесты фиксируют контракт правила.
 describe('getAppealFieldsConfig', () => {
-  it('жалоба: описание обязательно, предложение показано, но необязательно', () => {
+  it('обращение: описание обязательно, предложение показано, но необязательно', () => {
     const fields = getAppealFieldsConfig('complaint');
     expect(fields.situation).toEqual({ visible: true, required: true });
     expect(fields.suggestion).toEqual({ visible: true, required: false });

src/features/feedback/model.ts

@@ -43,7 +43,7 @@ export const COMPANY_OPTIONS: ISelectOption[] = [
 // значением ниже (EMPTY_FEEDBACK.kind), так что выбор пользователя.
 export const KIND_OPTIONS: ISelectOption[] = [
   { value: 'suggestion', label: 'Предложение' },
-  { value: 'complaint', label: 'Жалоба' },
+  { value: 'complaint', label: 'Обращение' },
   { value: 'other', label: 'Другое' }
 ];
 
@@ -61,7 +61,7 @@ export interface IAppealFieldsConfig {
 
 /**
  * Состав полей зависит от вида обращения:
- *   жалоба      — обязательно описание, а предложение — на желание автора;
+ *   обращение   — обязательно описание, а предложение — на желание автора;
  *   предложение — только само предложение, «ситуации» ещё нет;
  *   другое      — свободное описание, без предложения.
  * Одно правило на форму и на валидацию, чтобы они не разошлись.

src/features/feedback/texts.ts

@@ -28,7 +28,7 @@ export const TEXTS = {
 
   placeholders: {
     company: 'Выберите компанию',
-    fullName: 'Иванов Иван Иванович',
+    fullName: 'Нурлан Нурланович Нурланов',
     position: 'Например: инженер-проектировщик',
     kindOther: 'Свой вариант',
     situation: 'Опишите, что произошло: когда, где, кто участвовал',

src/features/feedback/validateFeedback.test.ts

@@ -6,7 +6,7 @@ const VALID_COMPANY = '9de064a4-44c8-88ef-11ec-8285925d83d2';
 const LONG_TEXT = 'Развёрнутое описание, которого достаточно для проверки правила';
 const SHORT_TEXT = 'коротко';
 
-/** Полностью заполненное «жалоба»-обращение — стартовая точка для тестов. */
+/** Полностью заполненное обращение — стартовая точка для тестов. */
 function buildValidComplaint(overrides: Partial<IFeedbackData> = {}): IFeedbackData {
   return {
     ...EMPTY_FEEDBACK,
@@ -61,17 +61,17 @@ describe('validateFeedback: вид обращения "Другое"', () => {
 // Состав обязательных полей зависит от вида обращения (см. getAppealFieldsConfig
 // в model.ts) — эти тесты фиксируют контракт, чтобы форма и валидация не разошлись.
 describe('validateFeedback: обязательность полей по видам обращения', () => {
-  it('жалоба: описание ситуации обязательно', () => {
+  it('обращение: описание ситуации обязательно', () => {
     const errors = validateFeedback(buildValidComplaint({ situation: '' }));
     expect(errors.situation).toBeDefined();
   });
 
-  it('жалоба: предложение по улучшению НЕ обязательно', () => {
+  it('обращение: предложение по улучшению НЕ обязательно', () => {
     const errors = validateFeedback(buildValidComplaint({ suggestion: '' }));
     expect(errors.suggestion).toBeUndefined();
   });
 
-  it('жалоба: если предложение всё же указано, но слишком коротко — ошибка', () => {
+  it('обращение: если предложение всё же указано, но слишком коротко — ошибка', () => {
     const errors = validateFeedback(buildValidComplaint({ suggestion: SHORT_TEXT }));
     expect(errors.suggestion).toBeDefined();
   });