Shoqan — от бизнес-задачи к студенческому проекту

Shoqan помогает бизнесу превратить неструктурированное описание проблемы в понятное практическое задание, а студентам — найти задачу и предложить решение. Владелец уточняет требования, подтверждает информацию и самостоятельно выбирает команду.

Проект разработан Нұрболатом и Асетом для хакатона. Текущая версия предназначена для локальной демонстрации. Публичная deployed-версия не настроена; после запуска сайт доступен по адресу http://127.0.0.1:3001/.

Что реализовано

• Создание черновика задания, редактирование темы и восьми полей карточки, подтверждение информации человеком и публикация.
• AI-вопросы для уточнения задачи; при недоступности модели — локальные резервные вопросы.
• Рейтинг полноты карточки от 0 до 100, поиск, сортировка по полноте или дате, фильтры по теме и уровню готовности.
• Предложения команд: описание решения, план, срок, ссылка на прототип; необязательные навыки, интересы и технологии.
• Ручное принятие и отклонение предложений владельцем с пояснением. Подтверждение этапов принятого предложения и начисление до 30 баллов.
• Регистрация, вход, выход, личные проекты и отслеживание отправленных предложений.
• Гостевые проекты с ключом владельца и возможность привязать собственный гостевой проект к аккаунту.
• Казахский и русский интерфейс, AI-перевод карточек без изменения исходных данных.
• AI-наставник: диалог о проекте, обучении и следующих шагах; история в текущей вкладке и начало нового разговора.
• Сохранение данных в SQLite, ручное резервное копирование и локальное восстановление пароля через одноразовый код.

Как работает решение

1. Бизнес описывает проблему. Например: «Остатки товаров считаем вручную, нужна простая складская таблица». Создаётся приватный черновик; описание попадает в поле контекста.
2. Система помогает уточнить требования. AI формирует 3–8 вопросов. Пользователь сам заполняет поля и подтверждает достоверность. AI не заполняет неизвестные факты за человека.
3. Карточка получает рейтинг. Учитываются только непустые подтверждённые поля. После просмотра и явного подтверждения владелец публикует задачу.
4. Команда отправляет предложение. В нём указываются подход, план, срок и ссылка на прототип. Низкий рейтинг задачи не блокирует отклики.
5. Бизнес принимает решение. Владелец выбирает предложение вручную и при необходимости оставляет пояснение. Автор, отправивший предложение из аккаунта, видит результат в разделе «Мои предложения».
6. Бизнес подтверждает прогресс. Для принятого предложения доступны этапы идеи, прототипа и переданного результата: 10, 20 или 30 баллов соответственно.

Как считается рейтинг

Подтверждённое поле	Баллы
Контекст и потребность	20
Данные и материалы	20
Ожидаемый результат	15
Критерии успеха	15
Ограничения	10
Пользователи	10
Контакт и обратная связь	10

Уровни: 0–39 — проект, 40–69 — подготовка к работе, 70–89 — готов, 90–100 — приоритетный. Это полнота задания, а не репутация компании или оценка качества решения.

Название не добавляет баллов, но должно быть заполнено и подтверждено перед публикацией. Все остальные заполненные поля также требуют подтверждения; неизвестные можно оставить пустыми. Минимального порога баллов для публикации нет. Сохранение изменений возвращает опубликованную карточку в черновик до повторной публикации.

Технологии

Компонент	Реализация
Клиент	HTML, CSS, JavaScript ES modules; без UI-фреймворка
Сервер	Node.js 24+, JavaScript, встроенный node:http
База данных	SQLite через встроенный node:sqlite, транзакции, режим WAL
Аутентификация	node:crypto, scrypt с солью, серверные сессии
AI	OpenAI Responses API через встроенный fetch; модель по умолчанию gpt-4o-mini
Структурированные AI-ответы	JSON Schema / Structured Outputs для вопросов и перевода
Тестирование	Встроенный node:test, проверки синтаксиса node --check

В package.json нет внешних npm-зависимостей. Отдельная сборка интерфейса не нужна. Значение OPENAI_MODEL можно изменить на доступную модель с поддержкой используемого формата структурированных ответов.

Архитектура

Браузер: public/
    │ fetch /api/*, cookie сессии или ключ гостевого владельца
    ▼
HTTP-сервер: server/app.js
    ├── auth.js + limits.js       аккаунты, доступ и лимиты
    ├── domain.js                подтверждения, рейтинг, валидация
    ├── store.js ──► SQLite       задачи, предложения, аккаунты, сессии
    └── ai.js / translate.js / mentor.js ──► OpenAI Responses API

Интерфейс и API обслуживаются одним сервером. Черновики и управление предложениями доступны владельцу; каталог возвращает только опубликованные задачи. Версии записей защищают от сохранения поверх параллельных изменений.

Путь	Назначение
public/app.js, public/style.css	Каталог, редактор, предложения, языки и оформление
public/account.js, public/mentor.js	Формы аккаунта и чат с наставником
server/index.js, server/app.js	Запуск сервера, статические файлы и HTTP API
server/domain.js, server/store.js	Предметные правила и хранение
server/auth.js, server/limits.js	Аутентификация и ограничение запросов
server/ai.js, server/translate.js, server/mentor.js	Три AI-функции
server/seed.js	Базовые демонстрационные данные
scripts/	API-демонстрация, резервная копия, восстановление пароля
tests/	Автоматические проверки
docs/contract.md	Подробный контракт API

Основные маршруты: /api/tasks, /api/tasks/draft, /api/tasks/:id/clarify, /api/tasks/:id/publish, /api/tasks/:id/proposals, /api/proposals/mine, /api/auth/*, /api/mentor. Форматы и методы описаны в контракте API.

Установка и запуск

1. Подготовьте среду

Установите Node.js 24 или новее и откройте терминал в корне полученного репозитория:

node --version

npm install не требуется: используются встроенные модули Node.js.

2. Создайте локальную конфигурацию

Windows PowerShell — команда сохраняет уже существующий .env.local:

if (!(Test-Path .env.local)) { Copy-Item .env.example .env.local }

Linux/macOS:

[ -f .env.local ] || cp .env.example .env.local

Основные настройки:

Переменная	Значение по умолчанию / назначение
HOST	127.0.0.1 — локальное прослушивание
PORT	3001
DATABASE_PATH	./data/app.sqlite
OPENAI_API_KEY	Не задана; собственный ключ для AI-функций
OPENAI_MODEL	gpt-4o-mini
AI_REQUESTS_PER_DAY	200 исходящих AI-запросов за 24-часовое окно процесса
AI_MAX_CONCURRENT	3 одновременных исходящих AI-запроса
COOKIE_SECURE	true включает Secure-cookie для HTTPS-окружения
FRONTEND_ORIGIN	Дополнительный разрешённый origin; по умолчанию http://localhost:5173

Для встроенного интерфейса отдельный frontend-сервер и изменение FRONTEND_ORIGIN не нужны. Ключ вводится только в .env.local; не публикуйте его. После изменения конфигурации перезапустите сервер.

3. Добавьте демо и запустите сайт

npm.cmd run seed
npm.cmd start

В Linux/macOS используйте npm вместо npm.cmd. В Windows форма npm.cmd помогает обойти блокировку npm.ps1 политикой PowerShell.

Откройте http://127.0.0.1:3001/. Проверка сервера: http://127.0.0.1:3001/api/health, ожидаемый ответ — {"ok":true}. Адрес /api/tasks показывает JSON, а не интерфейс.

База создаётся автоматически и сохраняется между перезапусками. На пустой базе seed добавляет 5 опубликованных задач, 5 черновиков и 5 предложений с профилями команд. Повторный запуск не дублирует эти записи и сохраняет решения по предложениям и их прогресс. Общий ключ владельца базовых демо-задач — local-demo-owner; он предназначен только для локальной демонстрации.

Дополнительные данные, созданные на компьютере автора, не входят в стандартный seed: локальная база и каталог artifacts/ исключены из Git. Числа в каталоге на новом компьютере могут отличаться от скриншотов демонстрации.

Для разработки с перезапуском при изменениях: npm.cmd run dev. Для остановки сервера: Ctrl+C.

Как проверить решение

Сценарий для жюри

1. Откройте сайт, выберите РУС, зарегистрируйте тестовый аккаунт через «Войти» → «Регистрация». Пароль должен содержать 12–128 символов. Email-подтверждение не требуется.
2. Создайте задачу с описанием: «Остатки товаров считаем вручную. Нужна простая складская таблица». Запросите уточняющие вопросы. Без OpenAI-ключа будут показаны резервные вопросы.
3. Заполните название «Учёт остатков», данные «Синтетический CSV, 100 товаров» и ожидаемый результат «Таблица остатков». Подтвердите название, контекст, данные и результат, затем сохраните. Ожидаемый рейтинг — 55/100: 20 + 20 + 15.
4. Просмотрите карточку, подтвердите проверку человеком и опубликуйте. Задача должна появиться в каталоге, несмотря на незаполненные поля.
5. В другом браузере зарегистрируйте второй тестовый аккаунт. Откройте задачу и отправьте предложение: команда «Демо», контакт [email protected], решение «Сделаем таблицу остатков», план «Согласовать CSV → реализовать импорт → проверить 100 строк», срок «2 недели», прототип https://example.test/prototype. Это заведомо демонстрационная ссылка, не рабочий прототип.
6. В первом аккаунте откройте управление предложениями и примите предложение с пояснением. Затем подтвердите этап «Прототип» — появится 20 баллов прогресса. Для этого теста подтверждение моделирует готовность; в реальном проекте этап подтверждается после проверки результата.
7. Во втором аккаунте обновите «Мои предложения»: должны отображаться решение, пояснение и баллы. Перезапуск сервера не должен удалять эти записи.
8. При настроенном AI откройте «AI наставник». Напишите «Мой тестовый проект называется Самғау», затем спросите название проекта. Проверьте продолжение диалога. Перевод карточки можно сравнить с оригиналом; он не меняет рейтинг.

Автоматические проверки

npm.cmd run check
npm.cmd test

Тесты проверяют HTTP-сценарии, права доступа, рейтинг, версии записей, предложения, этапы прогресса, восстановление пароля, навигацию, резервное копирование и обработку AI-ответов. Они не требуют OpenAI-ключа и не обращаются к реальному AI. Проверки с подменёнными ответами не доказывают доступность внешнего API.

При запущенном сервере можно выполнить во втором терминале:

npm.cmd run demo

Скрипт проходит путь от черновика до принятого предложения, моделируя действия человека на вымышленных данных. Каждый запуск добавляет одну задачу и одно предложение в текущую базу. Если сервер настроен с AI-ключом, уточнение может вызвать реальный API-запрос.

Данные и интеграции

• Основной источник данных — введённые пользователями описания, подтверждённые поля и предложения команд. Демо-наборы синтетические; контакты и прототипы на example.test служат примерами.
• SQLite хранит задачи, предложения, аккаунты, хэши паролей, сессии и одноразовые коды восстановления в хэшированном виде. Пароли защищены scrypt с индивидуальной солью; cookie сессии использует HttpOnly и SameSite=Strict, срок сессии — 7 дней.
• OpenAI — единственная реализованная внешняя AI-интеграция. Для уточнения передаются описание и поля задачи, для перевода — значения полей, для наставника — сообщения диалога. API-ключ остаётся на сервере; запросы содержат store: false.
• Перевод отображается отдельно от оригинала и кэшируется в памяти сервера до 100 вариантов. Открытие каталога и смена языка могут вызывать AI-запросы.
• Чат наставника хранит до 40 сообщений в sessionStorage текущей вкладки. В модель передаётся до 20 предыдущих сообщений плюс новый вопрос, суммарно до 30 000 символов. История чата не хранится в SQLite и не синхронизируется между устройствами.
• CSV упоминается в примерах бизнес-задач. Сам Shoqan не реализует загрузку и обработку складских CSV, а помогает сформулировать такое задание.

Обслуживание локальной версии

Резервная копия

npm.cmd run backup

Команда создаёт новую SQLite-копию в backups/ и проверяет её целостность; сервер можно не останавливать. Копия содержит данные аккаунтов и проектов, но не .env.local и не гостевые ключи из браузера. Автоматического расписания нет.

Для проверки восстановления остановите сервер, скопируйте выбранную резервную копию в новый файл, например data/restored.sqlite, задайте DATABASE_PATH=./data/restored.sqlite в .env.local и запустите сервер. Не перезаписывайте исходную базу: это позволяет вернуться к ней.

Забытый пароль

Откройте «Забыли пароль?» на странице входа. Администратор локального компьютера выдаёт код командой:

npm.cmd run password:reset -- [email скрыт]

Введите полученный код и новый пароль на сайте. Код действует 15 минут и используется один раз. Смена пароля завершает все сессии аккаунта, сохраняя его проекты. Код не отправляется по email; публичного API для его выдачи нет.

Для гостевых проектов отдельно сохраняйте ID и ключ владельца из интерфейса. Используйте один адрес сайта: localhost и 127.0.0.1 имеют разные браузерные хранилища.

Ограничения текущей версии

• Нет публичного хостинга, домена и настроенного HTTPS. Локальный сайт доступен, пока запущен сервер; AI дополнительно требует интернет, действующий ключ и доступный лимит API.
• Нет email-подтверждения, email-уведомлений и восстановления пароля по почте. Восстановление доступно через локальный терминал.
• Нет полноценного чата между бизнесом и командой и истории всех изменений решений: сохраняются текущее решение и пояснение. AI-наставник — отдельный диалог с моделью.
• AI-наставник не имеет доступа к базе, файлам, браузеру и инструментам: не публикует задачи, не выбирает команды и не меняет баллы. Ответы и переводы могут содержать ошибки.
• Без AI уточнение работает на резервных вопросах, перевод показывает оригинал, а наставник сообщает о недоступности. Локальной языковой модели нет.
• Каталог загружается целиком, без пагинации. Лимиты запросов и AI-кэш находятся в памяти одного процесса и сбрасываются после его перезапуска.
• Нет автоматического подбора команд, проверки фактической готовности прототипа или автоматического начисления баллов за качество: решения принимает владелец задания.
• Гостевые предложения не появляются автоматически в личном кабинете после регистрации. Потерянный гостевой ключ нельзя восстановить по email.
• Нет автоматических резервных копий и подтверждённого нагрузочными испытаниями режима работы для публичного сервиса. Публикация в интернете требует отдельной настройки окружения, HTTPS и доступа.

Дополнительная документация

• Контракт API
• Состояние проекта и ограничения
• Сценарий пятиминутной демонстрации
• Устройство AI-функций