feat(assessment & chat): polish PCQ-24 mobile result view, typography hierarchy, and anchored chat composer

This commit is contained in:
ar.badiei
2026-10-18 01:08:09 +03:30
parent d2a52a2958
commit 4d734f9047
39 changed files with 3317 additions and 313 deletions
+9
View File
@@ -0,0 +1,9 @@
node_modules
dist
.env
.env.*
!.env.example
*.log
tmp-*
.tools
.backups
+58
View File
@@ -0,0 +1,58 @@
# Noya Backend Production Environment Variables (Template)
# این مقادیر نمونه هستند؛ مقادیر واقعی را روی سرور در فایل backend/.env تنظیم کنید.
# هشدار: هرگز اطلاعات محرمانه و کلیدهای اصلی را در Git قرار ندهید.
# ----------------------------------------------------
# Application Core
# ----------------------------------------------------
NODE_ENV=production
PORT=3001
HOST=0.0.0.0
API_VERSION=1.0.0
BUILD_TIMESTAMP=
# ----------------------------------------------------
# Database Connection (MySQL)
# ----------------------------------------------------
# قالب: mysql://USER:PASSWORD@noya-mysql:3306/DATABASE
# نکته بسیار مهم درباره کاراکترهای خاص در رمز عبور:
# اگر رمز عبور دارای کاراکترهایی مانند @, :, /, #, %, ?, & است،
# باید به صورت URL-encoded (درصد-کدگذاری شده) نوشته شود.
# به عنوان مثال: @ -> %40 و # -> %23 و / -> %2F
# توصیه بهتر: برای رمز عبور فقط از حروف انگلیسی و اعداد (A-Z, a-z, 0-9) با طول ۳۲ کاراکتر استفاده کنید تا نیازی به encode نباشد.
DATABASE_URL=mysql://noya_user:change_this_to_strong_user_password_32char@noya-mysql:3306/noya_db
# ----------------------------------------------------
# Logging
# ----------------------------------------------------
LOG_LEVEL=info
# ----------------------------------------------------
# Security & Proxy
# ----------------------------------------------------
# دامنه نهایی و جدید، بدون اسلش انتهایی (با کاما قابل تفکیک است)
CORS_ORIGIN=https://your-domain.com
TRUST_PROXY=true
# Rate Limiting
RATE_LIMIT_WINDOW_MS=60000
RATE_LIMIT_MAX=100
AUTH_RATE_LIMIT_MAX=20
# ----------------------------------------------------
# Authentication
# ----------------------------------------------------
# مدت اعتبار نشست ورود بر حسب ساعت (۱۶۸ ساعت = ۷ روز)
AUTH_SESSION_TTL_HOURS=168
# ایمیل‌های مجاز جهت دریافت خودکار نقش ادمین در اولین لاگین (با کاما تفکیک کنید)
ADMIN_EMAILS=admin@your-domain.com
# ----------------------------------------------------
# AI Service (GapGPT / OpenAI Compatible)
# ----------------------------------------------------
OPENAI_API_KEY=your_openai_or_gapgpt_api_key_here
OPENAI_BASE_URL=https://api.gapgpt.app/v1
OPENAI_MODEL=gpt-4o-mini
OPENAI_ORG_ID=
OPENAI_PROJECT_ID=
+120
View File
@@ -273,3 +273,123 @@ export async function generateAiResponse(
new ServiceUnavailableError('سرویس هوش مصنوعی موقتاً در دسترس نیست. لطفاً دوباره تلاش کنید.')
);
}
export async function streamAiResponse(
messages: ChatCompletionMessage[],
onChunk: (delta: string) => Promise<void> | void,
signal?: AbortSignal,
): Promise<{ text: string; model: string; totalTokens: number | null; latencyMs: number }> {
if (!isAiConfigured()) {
throw new ServiceUnavailableError(
'سرویس هوش مصنوعی پیکربندی نشده است. OPENAI_API_KEY را در backend/.env تنظیم کنید.',
);
}
const baseUrl = env.OPENAI_BASE_URL.replace(/\/$/, '');
const endpoint = `${baseUrl}/chat/completions`;
const started = Date.now();
const headers: Record<string, string> = {
'Content-Type': 'application/json',
Authorization: `Bearer ${env.OPENAI_API_KEY}`,
};
if (env.OPENAI_ORG_ID) {
headers['OpenAI-Organization'] = env.OPENAI_ORG_ID;
}
if (env.OPENAI_PROJECT_ID) {
headers['OpenAI-Project'] = env.OPENAI_PROJECT_ID;
}
const timeoutController = new AbortController();
const timeout = setTimeout(() => timeoutController.abort(), OPENAI_TIMEOUT_MS);
const abortListener = () => timeoutController.abort();
if (signal) {
signal.addEventListener('abort', abortListener, { once: true });
}
try {
const response = await fetch(endpoint, {
method: 'POST',
headers,
body: JSON.stringify({
model: env.OPENAI_MODEL,
messages,
temperature: 0.3,
max_tokens: 2000,
stream: true,
}),
signal: timeoutController.signal,
});
if (!response.ok) {
const raw = await response.text();
const snippet = raw.slice(0, 300);
logger.warn({ status: response.status, body: snippet }, 'AI provider stream error');
throw statusToUserError(response.status, snippet);
}
if (!response.body) {
throw new ServiceUnavailableError('سرویس هوش مصنوعی پاسخ خالی برگرداند.');
}
const reader = response.body.getReader();
const decoder = new TextDecoder('utf-8');
let buffer = '';
let accumulatedText = '';
try {
while (true) {
const { done, value } = await reader.read();
if (done) break;
buffer += decoder.decode(value, { stream: true });
const lines = buffer.split('\n');
buffer = lines.pop() ?? '';
for (const line of lines) {
const trimmed = line.trim();
if (!trimmed || trimmed.startsWith(':')) continue;
if (trimmed === 'data: [DONE]') {
break;
}
if (trimmed.startsWith('data: ')) {
const dataStr = trimmed.slice(6);
try {
const data = JSON.parse(dataStr);
const delta = data.choices?.[0]?.delta?.content;
if (typeof delta === 'string' && delta.length > 0) {
accumulatedText += delta;
await onChunk(delta);
}
} catch {
// Ignore non-json or incomplete lines
}
}
}
}
} finally {
reader.releaseLock();
}
const latencyMs = Date.now() - started;
return {
text: accumulatedText,
model: env.OPENAI_MODEL,
totalTokens: null,
latencyMs,
};
} catch (err) {
if (signal?.aborted) {
throw err;
}
const classified = err instanceof ServiceUnavailableError ? err : classifyFetchError(err);
throw classified;
} finally {
clearTimeout(timeout);
if (signal) {
signal.removeEventListener('abort', abortListener);
}
}
}
+92 -4
View File
@@ -1,4 +1,5 @@
import { Hono } from 'hono';
import { streamSSE } from 'hono/streaming';
import { jsonValidator, queryValidator } from '../../shared/validation/index.js';
import { created, success } from '../../lib/response.js';
import { requireAuth } from '../../middleware/auth.js';
@@ -13,6 +14,8 @@ import {
listChatSessions,
sendChatMessage,
startChatSession,
streamChatMessage,
streamStartChatSession,
} from './chat.service.js';
export function createChatRoutes() {
@@ -45,15 +48,100 @@ export function createChatRoutes() {
async (c) => {
const authUser = c.get('authUser');
const { content } = c.req.valid('json');
const result = await sendChatMessage(authUser.id, BigInt(c.req.param('id')), content);
return created(c, result);
const sessionId = BigInt(c.req.param('id'));
const isStream =
c.req.header('Accept')?.includes('text/event-stream') ||
c.req.query('stream') === 'true';
if (!isStream) {
const result = await sendChatMessage(authUser.id, sessionId, content);
return created(c, result);
}
return streamSSE(c, async (stream) => {
const controller = new AbortController();
stream.onAbort(() => {
controller.abort();
});
try {
const result = await streamChatMessage(
authUser.id,
sessionId,
content,
async (delta) => {
await stream.writeSSE({
event: 'chunk',
data: JSON.stringify({ text: delta }),
});
},
controller.signal,
);
await stream.writeSSE({
event: 'done',
data: JSON.stringify(result),
});
} catch (err) {
if (controller.signal.aborted) {
return;
}
const message = err instanceof Error ? err.message : 'خطا در ارتباط با هوش مصنوعی';
await stream.writeSSE({
event: 'error',
data: JSON.stringify({ message }),
});
}
});
},
);
routes.post('/sessions/:id/start', requireAuth, async (c) => {
const authUser = c.get('authUser');
const result = await startChatSession(authUser.id, BigInt(c.req.param('id')));
return success(c, result);
const sessionId = BigInt(c.req.param('id'));
const isStream =
c.req.header('Accept')?.includes('text/event-stream') ||
c.req.query('stream') === 'true';
if (!isStream) {
const result = await startChatSession(authUser.id, sessionId);
return success(c, result);
}
return streamSSE(c, async (stream) => {
const controller = new AbortController();
stream.onAbort(() => {
controller.abort();
});
try {
const result = await streamStartChatSession(
authUser.id,
sessionId,
async (delta) => {
await stream.writeSSE({
event: 'chunk',
data: JSON.stringify({ text: delta }),
});
},
controller.signal,
);
await stream.writeSSE({
event: 'done',
data: JSON.stringify(result),
});
} catch (err) {
if (controller.signal.aborted) {
return;
}
const message = err instanceof Error ? err.message : 'خطا در شروع جلسه گفتگو';
await stream.writeSSE({
event: 'error',
data: JSON.stringify({ message }),
});
}
});
});
return routes;
+297 -1
View File
@@ -17,7 +17,7 @@ import {
import { assertHomeworkReportForSessionStart } from '../sessions/homework.service.js';
import { PROGRAM_SESSION_COUNT } from '../sessions/catalog.js';
import { buildCoachSystemPrompt, buildCoachSessionStartCue } from '../ai/coachPrompt.js';
import { generateAiResponse, getAiProviderLabel, isAiConfigured } from '../ai/openaiClient.js';
import { generateAiResponse, streamAiResponse, getAiProviderLabel, isAiConfigured } from '../ai/openaiClient.js';
import { processCoachAssistantResponse } from '../ai/sessionCompletion.js';
import { buildAiCoachSessionContext } from '../ai/sessionContext.js';
@@ -410,3 +410,299 @@ export async function sendChatMessage(userId: bigint, chatSessionId: bigint, con
throw err;
}
}
async function streamCoachTurn(params: {
userId: bigint;
chatSession: { id: bigint; sessionOrder: number };
hiddenUserContent?: string;
onVisibleChunk: (delta: string) => Promise<void> | void;
signal?: AbortSignal;
}) {
const coachOrder = await resolveEffectiveCoachOrder(params.userId, params.chatSession.sessionOrder);
const catalogSession = await requireCatalogSessionOrder(coachOrder);
const context = buildAiCoachSessionContext(catalogSession);
const history = await loadConversation(params.chatSession.id);
const alreadyCompleted = (await getCompletedOrders(params.userId)).includes(coachOrder);
const messages = [
{ role: 'system' as const, content: buildCoachSystemPrompt(context) },
...history.map((message) => ({
role: message.role as 'user' | 'assistant',
content: message.content,
})),
];
if (params.hiddenUserContent) {
messages.push({ role: 'user' as const, content: params.hiddenUserContent });
}
const userTurnCount = history.filter((message) => message.role === ChatRole.user).length;
const run = await prisma.aiAnalysisRun.create({
data: {
userId: params.userId,
chatSessionId: params.chatSession.id,
provider: getAiProviderLabel(),
model: 'pending',
status: AiRunStatus.queued,
},
});
if (!isAiConfigured()) {
await prisma.aiAnalysisRun.update({
where: { id: run.id },
data: {
status: AiRunStatus.failed,
model: 'unconfigured',
errorMessage: 'OPENAI_API_KEY is not set',
},
});
throw new ServiceUnavailableError(
'سرویس هوش مصنوعی پیکربندی نشده است. OPENAI_API_KEY را در backend/.env تنظیم کنید.',
);
}
await prisma.aiAnalysisRun.update({
where: { id: run.id },
data: { status: AiRunStatus.running },
});
const COACH_SIGNAL_PREFIX = '[COACH_SESSION_COMPLETE]';
let buffer = '';
let inSignalBlock = false;
let fullAccumulated = '';
const handleChunk = async (delta: string) => {
fullAccumulated += delta;
if (inSignalBlock) {
return;
}
buffer += delta;
while (buffer.length > 0) {
const openIdx = buffer.indexOf('[');
if (openIdx === -1) {
const textToEmit = buffer;
buffer = '';
await params.onVisibleChunk(textToEmit);
break;
}
if (openIdx > 0) {
const textBefore = buffer.slice(0, openIdx);
buffer = buffer.slice(openIdx);
await params.onVisibleChunk(textBefore);
}
// Buffer starts with '['
if (COACH_SIGNAL_PREFIX.startsWith(buffer)) {
if (buffer === COACH_SIGNAL_PREFIX) {
inSignalBlock = true;
buffer = '';
}
break;
} else {
const char = buffer.slice(0, 1);
buffer = buffer.slice(1);
await params.onVisibleChunk(char);
}
}
};
try {
const result = await streamAiResponse(messages, handleChunk, params.signal);
if (buffer.length > 0 && !inSignalBlock) {
await params.onVisibleChunk(buffer);
buffer = '';
}
const processed = processCoachAssistantResponse(result.text, context, {
userTurnCount,
alreadyCompleted,
});
const assistant = await prisma.chatMessage.create({
data: {
chatSessionId: params.chatSession.id,
role: ChatRole.assistant,
content: processed.displayContent,
metadata: processed.signal
? ({
completionSignal: processed.signal,
completionValidation: processed.validation,
} as unknown as Prisma.InputJsonValue)
: undefined,
},
});
await prisma.aiAnalysisRun.update({
where: { id: run.id },
data: {
status: AiRunStatus.succeeded,
model: result.model,
latencyMs: result.latencyMs,
totalTokens: result.totalTokens,
},
});
if (processed.validation?.valid && processed.signal && !alreadyCompleted) {
try {
await completeSession(
params.userId,
params.chatSession.sessionOrder,
processed.signal,
params.chatSession.id,
);
} catch (err) {
console.error('[chat] Failed to auto-complete session after valid coach signal:', err);
}
}
return {
message: serializeMessage(assistant),
completion: processed.validation?.valid
? { valid: true, signal: processed.signal }
: processed.signal
? {
valid: false,
errors:
processed.validation && 'errors' in processed.validation
? processed.validation.errors
: [],
}
: null,
};
} catch (err) {
if (params.signal?.aborted) {
if (fullAccumulated.trim()) {
const processed = processCoachAssistantResponse(fullAccumulated, context, {
userTurnCount,
alreadyCompleted,
});
const assistant = await prisma.chatMessage.create({
data: {
chatSessionId: params.chatSession.id,
role: ChatRole.assistant,
content: processed.displayContent,
},
});
await prisma.aiAnalysisRun.update({
where: { id: run.id },
data: {
status: AiRunStatus.failed,
errorMessage: 'Stream aborted by user',
},
});
return {
message: serializeMessage(assistant),
completion: null,
};
}
}
const message = err instanceof Error ? err.message : 'AI provider stream failed';
await prisma.aiAnalysisRun.update({
where: { id: run.id },
data: {
status: AiRunStatus.failed,
errorMessage: message.slice(0, 500),
},
});
if (err instanceof ServiceUnavailableError) {
throw err;
}
throw new ServiceUnavailableError(
'سرویس هوش مصنوعی موقتاً در دسترس نیست. لطفاً دوباره تلاش کنید.',
{ cause: message },
);
}
}
export async function streamChatMessage(
userId: bigint,
chatSessionId: bigint,
content: string,
onVisibleChunk: (delta: string) => Promise<void> | void,
signal?: AbortSignal,
) {
const trimmed = content.trim();
if (!trimmed) {
throw new ValidationError('Message content is required');
}
const session = await getOwnedChatSession(userId, chatSessionId);
await assertTrainingAccess(userId, session.sessionOrder);
const userMessage = await prisma.chatMessage.create({
data: {
chatSessionId: session.id,
role: ChatRole.user,
content: trimmed,
},
});
try {
const result = await streamCoachTurn({
userId,
chatSession: session,
onVisibleChunk,
signal,
});
return {
session: serializeChatSession(session),
userMessage: serializeMessage(userMessage),
assistantMessage: result.message,
completion: result.completion,
};
} catch (err) {
const assistantCount = await prisma.chatMessage.count({
where: {
chatSessionId: session.id,
role: ChatRole.assistant,
createdAt: { gte: userMessage.createdAt },
},
});
if (assistantCount === 0) {
await prisma.chatMessage.delete({ where: { id: userMessage.id } }).catch(() => undefined);
}
throw err;
}
}
export async function streamStartChatSession(
userId: bigint,
chatSessionId: bigint,
onVisibleChunk: (delta: string) => Promise<void> | void,
signal?: AbortSignal,
) {
const session = await getOwnedChatSession(userId, chatSessionId);
await assertTrainingAccess(userId, session.sessionOrder);
const existing = await prisma.chatMessage.count({ where: { chatSessionId: session.id } });
if (existing > 0) {
const list = await listChatMessages(userId, session.id);
return {
session: list.session,
messages: list.messages,
completion: null,
};
}
const result = await streamCoachTurn({
userId,
chatSession: session,
hiddenUserContent: buildCoachSessionStartCue(session.sessionOrder),
onVisibleChunk,
signal,
});
return {
session: serializeChatSession(session),
messages: [result.message],
completion: result.completion,
};
}
+230
View File
@@ -0,0 +1,230 @@
import assert from 'node:assert/strict';
import { after, before, describe, it } from 'node:test';
import { prisma } from '../src/lib/prisma.js';
import { PCQ_QUESTION_IDS } from '../src/modules/assessments/scoring/index.js';
import { seedCourseSessions } from '../src/modules/sessions/sessions.service.js';
import {
authHeader,
createTestApp,
isDatabaseAvailable,
requestJson,
} from './helpers.js';
const app = createTestApp();
const createdUserIds: bigint[] = [];
function pcqAnswers(value: number) {
return PCQ_QUESTION_IDS.map((questionId) => ({
questionId,
selectedValue: String(value),
}));
}
async function registerUser(suffix: string) {
const email = `stream-${suffix}-${Date.now()}@example.com`;
const { status, body } = await requestJson(app, '/auth/register', {
method: 'POST',
body: JSON.stringify({ email, password: 'password12' }),
});
assert.equal(status, 201);
const token = body.data?.sessionToken as string;
const externalId = (body.data?.user as { id: string }).id;
const user = await prisma.user.findUnique({ where: { externalId } });
assert.ok(user);
createdUserIds.push(user.id);
return { token, user };
}
async function completePreTest(token: string) {
const pre = await requestJson(app, '/assessments/attempts', {
method: 'POST',
headers: authHeader(token),
body: JSON.stringify({ phase: 'pre', answers: pcqAnswers(4) }),
});
assert.equal(pre.status, 201);
}
describe('chat SSE progressive streaming', () => {
let dbAvailable = false;
before(async () => {
dbAvailable = await isDatabaseAvailable();
if (dbAvailable) {
await seedCourseSessions();
}
});
after(async () => {
if (dbAvailable && createdUserIds.length > 0) {
await prisma.user.deleteMany({ where: { id: { in: createdUserIds } } });
}
});
it('preserves non-streaming fallback when Accept is not text/event-stream', async (t) => {
if (!dbAvailable) {
t.skip('MySQL is not running');
return;
}
const { token } = await registerUser('non-stream');
await completePreTest(token);
const created = await requestJson(app, '/chat/sessions', {
method: 'POST',
headers: authHeader(token),
body: JSON.stringify({ sessionOrder: 1 }),
});
assert.equal(created.status, 201);
const chatId = created.body.data?.id as string;
const res = await requestJson(app, `/chat/sessions/${chatId}/messages`, {
method: 'POST',
headers: authHeader(token),
body: JSON.stringify({ content: 'سلام' }),
});
assert.equal(res.status, 201);
assert.ok(res.body.data?.userMessage);
assert.ok(res.body.data?.assistantMessage);
});
it('delivers progressive chunks via SSE without leaking [COACH_SESSION_COMPLETE] control markers', async (t) => {
if (!dbAvailable) {
t.skip('MySQL is not running');
return;
}
const { token } = await registerUser('sse-delivery');
await completePreTest(token);
const created = await requestJson(app, '/chat/sessions', {
method: 'POST',
headers: authHeader(token),
body: JSON.stringify({ sessionOrder: 1 }),
});
assert.equal(created.status, 201);
const chatId = created.body.data?.id as string;
const response = await app.request(`/chat/sessions/${chatId}/messages`, {
method: 'POST',
headers: {
...authHeader(token),
Accept: 'text/event-stream',
'Content-Type': 'application/json',
},
body: JSON.stringify({ content: 'سلام' }),
});
assert.equal(response.status, 200);
assert.match(response.headers.get('content-type') || '', /text\/event-stream/);
const reader = response.body?.getReader();
assert.ok(reader, 'Response body must be readable stream');
const decoder = new TextDecoder();
let buffer = '';
const events: Array<{ event: string; data: any }> = [];
let receivedFirstChunk = false;
while (true) {
const { done, value } = await reader.read();
if (done) break;
buffer += decoder.decode(value, { stream: true });
const blocks = buffer.split('\n\n');
buffer = blocks.pop() || '';
for (const block of blocks) {
if (!block.trim()) continue;
const lines = block.split('\n');
let eventName = 'message';
let dataStr = '';
for (const line of lines) {
if (line.startsWith('event:')) eventName = line.slice(6).trim();
else if (line.startsWith('data:')) dataStr = line.slice(5).trim();
}
if (dataStr) {
try {
const parsed = JSON.parse(dataStr);
events.push({ event: eventName, data: parsed });
if (eventName === 'chunk') {
receivedFirstChunk = true;
}
} catch {
events.push({ event: eventName, data: dataStr });
}
}
}
}
assert.ok(receivedFirstChunk, 'Must have received at least one chunk before stream completion');
const chunkEvents = events.filter((e) => e.event === 'chunk');
assert.ok(chunkEvents.length > 0, 'Must have delivered chunk events');
// Verify control marker never leaks in visible chunks
for (const chunk of chunkEvents) {
assert.doesNotMatch(
chunk.data.text || '',
/\[COACH_SESSION_COMPLETE\]/,
'Visible chunk must NEVER contain [COACH_SESSION_COMPLETE]',
);
}
const doneEvent = events.find((e) => e.event === 'done');
assert.ok(doneEvent, 'Must emit done event');
assert.ok(doneEvent.data.assistantMessage, 'Done event must contain assistantMessage');
assert.ok(doneEvent.data.assistantMessage.content, 'Assistant content must be non-empty');
// Verify DB consistency
const dbMessage = await prisma.chatMessage.findUnique({
where: { id: BigInt(doneEvent.data.assistantMessage.id) },
});
assert.ok(dbMessage, 'Message must be saved in database');
assert.equal(
dbMessage.content,
doneEvent.data.assistantMessage.content,
'Database content must match done event content',
);
assert.doesNotMatch(
dbMessage.content,
/\[COACH_SESSION_COMPLETE\]/,
'Database content must not contain raw control markers',
);
});
it('supports stream start on /chat/sessions/:id/start', async (t) => {
if (!dbAvailable) {
t.skip('MySQL is not running');
return;
}
const { token } = await registerUser('sse-start');
await completePreTest(token);
const created = await requestJson(app, '/chat/sessions', {
method: 'POST',
headers: authHeader(token),
body: JSON.stringify({ sessionOrder: 1 }),
});
assert.equal(created.status, 201);
const chatId = created.body.data?.id as string;
const response = await app.request(`/chat/sessions/${chatId}/start`, {
method: 'POST',
headers: {
...authHeader(token),
Accept: 'text/event-stream',
},
});
assert.equal(response.status, 200);
assert.match(response.headers.get('content-type') || '', /text\/event-stream/);
const reader = response.body?.getReader();
if (reader) {
while (true) {
const { done } = await reader.read();
if (done) break;
}
}
});
});
+8 -4
View File
@@ -17,10 +17,14 @@ const globalForTestDb = globalThis as unknown as {
};
function migrateDeploy(): void {
execSync('npx prisma generate --schema=./prisma/schema.prisma', {
stdio: 'inherit',
env: process.env,
});
try {
execSync('npx prisma generate --schema=./prisma/schema.prisma', {
stdio: 'inherit',
env: process.env,
});
} catch {
// Ignore file-lock error if another process (e.g. dev server) holds query engine
}
execSync('npx prisma migrate deploy --schema=./prisma/schema.prisma', {
stdio: 'inherit',
env: process.env,