This commit is contained in:
2026-09-21 14:14:38 +03:30
parent 4705925022
commit 74e048cc2a
4 changed files with 1024 additions and 780 deletions

16
package-lock.json generated
View File

@@ -5600,22 +5600,6 @@
"integrity": "sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==", "integrity": "sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==",
"dev": true, "dev": true,
"license": "ISC" "license": "ISC"
},
"node_modules/yaml": {
"version": "2.9.0",
"resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.0.tgz",
"integrity": "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==",
"extraneous": true,
"license": "ISC",
"bin": {
"yaml": "bin.mjs"
},
"engines": {
"node": ">= 14.6"
},
"funding": {
"url": "https://github.com/sponsors/eemeli"
}
} }
} }
} }

View File

@@ -1,147 +1,442 @@
/** /**
* API تدریسینو — تنها جایی که فرانت باید برای صدا زدنِ بک‌اند به آن نگاه کند. * کلاینتِ API تدریسینو — برای فرانتِ React/TypeScript (MathApp_frontend).
* *
* import { api } from '@/api'; * از روی OpenAPI واقعیِ همین بک‌اند نوشته شده، نه از روی حدس. نامِ فیلدها
* const home = await api.home(); * دقیقاً همان چیزی‌ست که سرور برمی‌گرداند (camelCase).
* *
* هیچ‌جای اپ نباید مستقیم fetch بزند: مسیرِ خام، مدیریتِ توکن و رفتارِ * نکته‌های مهمِ اتصال:
* درستِ خطا همه اینجا یک‌جا جمع‌اند. * - احرازِ هویت توکنِ Bearer است، نه کوکی. پس `credentials: 'include'` لازم
* * نیست و CORS سمتِ سرور هم عمداً بدونِ credentials تنظیم شده.
* هر مسیر و هر نامِ فیلد از OpenAPI واقعیِ سرویس گرفته شده. جاهایی که * - توکنِ دسترسی امضاشده و کوتاه‌عمر است؛ با ۴۰۱ باید `refresh` صدا زد.
* غافلگیرکننده‌اند کامنت خورده‌اند، چون اشتباهشان خطای ۴۰۰/۴۰۴ می‌دهد که * این کلاینت خودش یک‌بار refresh می‌کند و درخواست را تکرار.
* از پیامش علت معلوم نیست. * - برای پرسش از دستیار کافی‌ست `lessonId` بدهید؛ سرور خودش می‌فهمد آن درس
* مالِ کدام پایه و فصل است و پاسخ را به کتاب مستند می‌کند.
*/ */
import { ApiError, createHttpClient, localTokenStorage } from './client';
import type { ClientOptions, HttpClient, RequestOptions, Tokens } from './client';
import type {
AnswerResponse, AskResponse, Grade, HomeResponse, LessonIntro, Plan, Question,
ReportReason, ReportResponse, UserProfile,
} from './types';
export { ApiError, localTokenStorage, createHttpClient }; export type Json = Record<string, unknown>;
export type { Tokens, HttpClient, ClientOptions, RequestOptions };
export * from './types';
/** پرسش از دستیار کند است (تولیدِ متن)؛ ۱۵ ثانیه‌ی پیش‌فرض کم است. */ export interface Tokens {
const ASK_TIMEOUT_MS = 45_000; token: string;
refreshToken: string;
}
export function createApi(options: ClientOptions = {}) { /* ─── انواعِ پاسخ ───────────────────────────────────────────────────────── */
const http = createHttpClient(options);
return { export type NodeStatus = 'locked' | 'unlocked' | 'in_progress' | 'completed';
http,
/* ── ورود ─────────────────────────────────────────────────────────── */ export interface HomeNode {
auth: { id: string;
/** «شروع سریع» بدونِ شماره. توکنِ مهمان refreshToken ندارد. */ title: string;
async guest(deviceId: string) { status: NodeStatus;
const data = await http.post<{ lessonIds: number[];
userId: string; token: string; isNewUser: boolean; isGuest: boolean; }
}>('/auth/session', { type: 'guest', deviceId }); export interface HomeUnit {
http.storage.set({ token: data.token, refreshToken: '' }); id: string;
return data; title: string;
}, nodes: HomeNode[];
/** گامِ ۱ — در حالتِ توسعه `devOtp` هم برمی‌گردد. */ }
requestOtp(phone: string) { export interface HomeResponse {
return http.post<{ success: boolean; devOtp?: string }>( units: HomeUnit[];
'/auth/otp/request', { phone }, stats: { progressPercent: number; xp: number; coins: number };
); }
},
/** گامِ ۲ — نامِ فیلد در سرور `otp` است، نه `code`. */
async login(phone: string, otp: string) {
const data = await http.post<{ userId: string } & Tokens>(
'/auth/login', { phone, otp },
);
http.storage.set({ token: data.token, refreshToken: data.refreshToken });
return data;
},
logout() {
http.storage.set(null);
},
isSignedIn() {
return Boolean(http.storage.get()?.token);
},
},
/* ── کاربر ────────────────────────────────────────────────────────── */ export interface Grade {
profile: { id: number;
get: (opts?: RequestOptions) => http.get<UserProfile>('/user/profile', opts), title: string;
update: (patch: Partial<Pick<UserProfile, icon: string;
'name' | 'avatar' | 'birthYear' | 'parentPhone' | 'bio'>>) => color: string;
http.patch<UserProfile>('/user/profile', patch), }
setGrade: (gradeId: number) =>
http.post<{ success: boolean; gradeId: number }>('/user/grade', { gradeId }),
},
/** xp/سکه/استریک اینجاست، نه در profile. */ export interface UserSummary {
summary: (opts?: RequestOptions) => userId: string;
http.get<Record<string, unknown>>('/user/summary', opts), name: string;
avatar: string;
gradeId: number | null;
xp: number;
coins: number;
streak: { current: number; longest: number };
subscription: string;
}
/** پایه‌ها را هاردکد نکنید — اضافه می‌شوند. */ export interface UserProfile {
grades: (opts?: RequestOptions) => userId: string;
http.get<{ grades: Grade[] }>('/grades', opts).then((r) => r.grades), phone: string | null;
name: string;
avatar: string;
isGuest: boolean;
gradeId: number | null;
birthYear: number | null;
parentPhone: string;
bio: string;
}
/** بدونِ gradeId، پایه‌ی ذخیره‌شده‌ی خودِ کاربر استفاده می‌شود. */ export interface LessonIntro {
home: (gradeId?: number, opts?: RequestOptions) => lessonId: string;
http.get<HomeResponse>(gradeId ? `/home?gradeId=${gradeId}` : '/home', opts), title: string;
introText: string;
/* ── درس و آزمون ──────────────────────────────────────────────────── */ /** برای انتخابِ حالتِ ماسکوت در صفحه‌ی درس */
lessons: { mascotAnimation: string;
intro: (lessonId: number | string, opts?: RequestOptions) =>
http.get<LessonIntro>(`/lessons/${lessonId}/intro`, opts),
questions: (lessonId: number | string, opts?: RequestOptions) =>
http.get<{ questions: Question[] }>(`/lessons/${lessonId}/questions`, opts)
.then((r) => r.questions),
complete: (lessonId: number | string) =>
http.create<Record<string, unknown>>(`/lessons/${lessonId}/complete`, {}),
},
questions: {
/** /**
* ثبتِ پاسخ. مسیر زیرِ /questions است نه /lessons، و نامِ فیلد * صفر یعنی متنِ درس هست ولی آزمونش هنوز ساخته نشده — «به‌زودی» نشان دهید،
* `selectedOptionId` است. کلیدِ یکتا می‌گیرد تا دابل‌کلیکِ کاربر یا * نه کویزِ خالی. `complete` هم `totalQuestions: 0` را نمی‌پذیرد.
* تکرارِ خودکارِ شبکه دو بار XP ندهد و دو بار «قلب» کم نکند.
*/ */
answer: (questionId: number | string, selectedOptionId: number | string) => questionCount: number;
http.create<AnswerResponse>(`/questions/${questionId}/answer`, { selectedOptionId }), }
/** «این سوال ایراد دارد» — گزارشِ تکراریِ همان کاربر ردیفِ تازه نمی‌سازد. */ export interface QuestionOption {
report: (questionId: number | string, reason: ReportReason, note = '') => id: string;
http.post<ReportResponse>(`/questions/${questionId}/report`, { reason, note }), value: string;
}, }
export interface Question {
id: string;
type: 'multiple_choice' | 'count_objects';
prompt: string;
options: QuestionOption[];
}
/* ── دستیار ───────────────────────────────────────────────────────── */ export interface AnswerResult {
ai: { correct: boolean;
/** correctOptionId: string;
* فقط `lessonId` کافی‌ست: سرور خودش می‌فهمد این درس مالِ کدام پایه و xpEarned: number;
* فصل است و پاسخ را به کتاب مستند می‌کند. heartsRemaining: number;
* /** حالتِ ماسکوت: درست → happy، غلط → encourage */
* ⚠️ نامِ فیلدِ پرسش `userQuestion` است، نه `question`. mascotMood: string;
*/ }
ask: (
userQuestion: string,
ctx: { lessonId?: number | string; conversationId?: string; gradeId?: number } = {},
opts?: RequestOptions,
) =>
http.post<AskResponse>('/ai/ask', { userQuestion, ...ctx }, {
timeoutMs: ASK_TIMEOUT_MS,
...opts,
}),
/** ⚠️ `isHelpful` بولین است، نه رشته‌ی up/down. `reason` اختیاری. */ export interface LessonComplete {
feedback: (messageId: number | string, isHelpful: boolean, reason?: string) => stars: number;
http.post<{ success: boolean }>( xpEarned: number;
`/ai/messages/${messageId}/feedback`, { isHelpful, reason }, coinsEarned: number;
), stats: { progressPercent: number; xp: number; coins: number };
}, }
/* ── اشتراک ───────────────────────────────────────────────────────── */ export interface Hearts {
plans: (opts?: RequestOptions) => currentHearts: number;
http.get<{ plans: Plan[] }>('/subscription/plans', opts).then((r) => r.plans), maxHearts: number;
nextRefillAt: string | null;
isUnlimited: boolean;
}
export interface AskResponse {
conversationId: string;
messageId: string;
answer: string;
suggestedFollowUps: string[];
remainingQuota: number;
/** تکه‌های کتاب که پاسخ رویشان بنا شده؛ خالی یعنی پاسخِ عمومی */
usedChunks: { title: string; summary: string }[];
}
export interface Plan {
id: string;
title: string;
price: number;
durationDays: number;
features: string[];
}
/* ─── خطا ───────────────────────────────────────────────────────────────── */
export class ApiError extends Error {
constructor(
readonly status: number,
readonly detail: string,
readonly body: Json,
) {
super(detail);
this.name = 'ApiError';
}
/** ۴۲۹: throttle یا اتمامِ سهمیه‌ی روزانه‌ی دستیار */
get isRateLimited() {
return this.status === 429;
}
/** ۵۰۳: سرویسِ هوش مصنوعی/پیامک موقتاً در دسترس نیست */
get isProviderDown() {
return this.status === 503;
}
}
/* ─── کلاینت ────────────────────────────────────────────────────────────── */
export interface ClientOptions {
baseUrl?: string;
/** خواندن/نوشتنِ توکن؛ پیش‌فرض localStorage */
storage?: {
get(): Tokens | null;
set(t: Tokens | null): void;
}; };
} }
export type Api = ReturnType<typeof createApi>; const STORAGE_KEY = 'tadrisino.tokens';
/** نمونه‌ی پیش‌فرض — برای حالتِ عادی همین کافی‌ست. */ function defaultStorage() {
export const api = createApi(); return {
get(): Tokens | null {
try {
const raw = localStorage.getItem(STORAGE_KEY);
return raw ? (JSON.parse(raw) as Tokens) : null;
} catch {
return null;
}
},
set(t: Tokens | null) {
try {
if (t) localStorage.setItem(STORAGE_KEY, JSON.stringify(t));
else localStorage.removeItem(STORAGE_KEY);
} catch {
/* حالتِ خصوصیِ مرورگر — نادیده */
}
},
};
}
export function createClient(options: ClientOptions = {}) {
const baseUrl = (options.baseUrl ?? '/api').replace(/\/$/, '');
const storage = options.storage ?? defaultStorage();
async function raw<T>(
method: string,
path: string,
body?: unknown,
extraHeaders: Record<string, string> = {},
retryOn401 = true,
): Promise<T> {
const tokens = storage.get();
const headers: Record<string, string> = { ...extraHeaders };
if (body !== undefined) headers['Content-Type'] = 'application/json';
if (tokens?.token) headers['Authorization'] = `Bearer ${tokens.token}`;
const response = await fetch(`${baseUrl}${path}`, {
method,
headers,
body: body === undefined ? undefined : JSON.stringify(body),
});
if (response.status === 401 && retryOn401 && tokens?.refreshToken) {
const refreshed = await refresh(tokens.refreshToken).catch(() => null);
if (refreshed) return raw<T>(method, path, body, extraHeaders, false);
storage.set(null);
}
const text = await response.text();
const parsed: Json = text ? (JSON.parse(text) as Json) : {};
if (!response.ok) {
const detail =
(parsed.detail as string) ??
(parsed.error as string) ??
`خطای ${response.status}`;
throw new ApiError(response.status, detail, parsed);
}
return parsed as T;
}
async function refresh(refreshToken: string) {
const response = await fetch(`${baseUrl}/auth/refresh`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ refreshToken }),
});
if (!response.ok) return null;
const data = (await response.json()) as Tokens;
storage.set({ token: data.token, refreshToken: data.refreshToken });
return data;
}
return {
/* ── ورود (صفحه‌ای که فعلاً در فرانت نیست و باید ساخته شود) ────────── */
auth: {
/** مهمان: بدونِ شماره، فقط با شناسه‌ی دستگاه. برای «شروع سریع». */
async guest(deviceId: string) {
const data = await raw<{ userId: string; token: string; isNewUser: boolean; isGuest: boolean }>(
'POST', '/auth/session', { type: 'guest', deviceId },
);
storage.set({ token: data.token, refreshToken: '' });
return data;
},
/** گامِ ۱: ارسالِ پیامکِ کد. در حالتِ توسعه `devOtp` هم برمی‌گردد. */
requestOtp(phone: string) {
return raw<{ success: boolean; devOtp?: string; note?: string }>(
'POST', '/auth/otp/request', { phone },
);
},
/** گامِ ۲: تأییدِ کد و گرفتنِ توکن. نامِ فیلد در سرور `otp` است. */
async login(phone: string, otp: string) {
const data = await raw<{ userId: string } & Tokens>(
'POST', '/auth/login', { phone, otp },
);
storage.set({ token: data.token, refreshToken: data.refreshToken });
return data;
},
logout() {
storage.set(null);
},
isSignedIn() {
return Boolean(storage.get()?.token);
},
},
/* ── صفحه‌ی «بیا باهم آشنا بشیم» ──────────────────────────────────── */
profile: {
get: () => raw<UserProfile>('GET', '/user/profile'),
/** اسم/آواتار/… . فقط فیلدهایی که می‌فرستید عوض می‌شوند. */
update: (patch: Partial<Pick<UserProfile, 'name' | 'avatar' | 'birthYear' | 'parentPhone' | 'bio'>>) =>
raw<UserProfile>('PATCH', '/user/profile', patch),
setGrade: (gradeId: number) =>
raw<{ success: boolean; gradeId: number }>('POST', '/user/grade', { gradeId }),
},
/** فهرستِ پایه‌ها را از سرور بگیرید، هاردکد نکنید — پایه‌ها اضافه می‌شوند. */
grades: () => raw<{ grades: Grade[] }>('GET', '/grades').then((r) => r.grades),
/* ── صفحه‌ی خانه و نقشه‌ی مهارت ────────────────────────────────────── */
/** بدونِ gradeId، پایه‌ی ذخیره‌شده‌ی خودِ کاربر ملاک است. */
home: (gradeId?: number) =>
raw<HomeResponse>('GET', gradeId ? `/home?grade=${gradeId}` : '/home'),
summary: () => raw<UserSummary>('GET', '/user/summary'),
hearts: () => raw<Hearts>('GET', '/user/hearts'),
streakCalendar: () =>
raw<{ currentStreak: number; longestStreak: number; activeDays: string[] }>(
'GET', '/user/streak/calendar',
),
leaderboard: (period: 'weekly' | 'monthly' = 'weekly') =>
raw<{ period: string; entries: unknown[] }>('GET', `/leaderboard?period=${period}`),
/* ── صفحه‌ی درس و سوال ─────────────────────────────────────────────── */
lesson: {
intro: (lessonId: number) => raw<LessonIntro>('GET', `/lessons/${lessonId}/intro`),
questions: (lessonId: number) =>
raw<{ questions: Question[] }>('GET', `/lessons/${lessonId}/questions`).then((r) => r.questions),
/**
* `idempotencyKey` را بدهید تا اگر شبکه قطع شد و کاربر دوباره زد،
* امتیاز/قلب دوبار حساب نشود.
*/
answer: (questionId: number, selectedOptionId: number, idempotencyKey?: string) =>
raw<AnswerResult>(
'POST', `/questions/${questionId}/answer`, { selectedOptionId },
idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {},
),
/**
* پایانِ درس. `correctCount` را سرور با تعدادِ واقعیِ سوال‌ها سقف می‌زند.
* مجموعِ XPِ کاربر **اینجا** به‌روز می‌شود، نه سرِ هر پاسخ.
*/
complete: (
lessonId: number,
result: { correctCount: number; totalQuestions: number },
idempotencyKey?: string,
) =>
raw<LessonComplete>(
'POST', `/lessons/${lessonId}/complete`, result,
idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {},
),
},
/* ── صفحه‌ی «از رُبو بپرس» ─────────────────────────────────────────── */
ai: {
/**
* `lessonId` را بدهید تا پاسخ به کتابِ همان درس مستند شود؛ لازم نیست
* subject/grade/chapter را خودتان حساب کنید.
* `conversationId` را از پاسخِ قبلی پاس بدهید تا گفتگو ادامه پیدا کند.
*/
ask: (input: {
userQuestion: string;
lessonId?: number | string;
conversationId?: string;
questionId?: number | string;
idempotencyKey?: string;
}) => {
const { idempotencyKey, ...body } = input;
return raw<AskResponse>(
'POST', '/ai/ask', body,
idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {},
);
},
/**
* همان ask ولی توکن‌به‌توکن (SSE). اولین کلمه ~۳.۵ ثانیه به‌جای ~۱۰.
* برای حبابِ چتِ «در حالِ تایپ» همین را استفاده کنید.
*/
async askStream(
input: { userQuestion: string; lessonId?: number | string; conversationId?: string },
onDelta: (text: string) => void,
): Promise<{ conversationId?: string; messageId?: string }> {
const tokens = storage.get();
const response = await fetch(`${baseUrl}/ai/ask`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
...(tokens?.token ? { Authorization: `Bearer ${tokens.token}` } : {}),
},
body: JSON.stringify({ ...input, stream: true }),
});
if (!response.ok || !response.body) {
throw new ApiError(response.status, 'استریم شروع نشد', {});
}
const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = '';
let done: { conversationId?: string; messageId?: string } = {};
for (;;) {
const { value, done: finished } = await reader.read();
if (finished) break;
buffer += decoder.decode(value, { stream: true });
// رویدادها با یک خطِ خالی از هم جدا می‌شوند.
const parts = buffer.split('\n\n');
buffer = parts.pop() ?? '';
for (const part of parts) {
const event = /^event: (.+)$/m.exec(part)?.[1];
const dataLine = /^data: (.+)$/m.exec(part)?.[1];
if (!event || !dataLine) continue;
const payload = JSON.parse(dataLine) as Json;
if (event === 'chunk') onDelta(String(payload.delta ?? ''));
else if (event === 'done') done = payload as typeof done;
else if (event === 'error') {
throw new ApiError(503, String(payload.detail ?? 'خطای دستیار'), payload);
}
}
}
return done;
},
/** 👍/👎 روی یک پاسخ. `reason` اختیاری ولی خیلی مفید است. */
feedback: (messageId: string | number, isHelpful: boolean, reason?: string) =>
raw<{ success: boolean }>('POST', `/ai/messages/${messageId}/feedback`, {
isHelpful,
...(reason ? { reason } : {}),
}),
history: (conversationId: string | number) =>
raw<{ conversationId: string; lessonId: string | null; messages: unknown[] }>(
'GET', `/ai/conversations/${conversationId}/messages`,
),
},
/* ── صفحه‌ی اشتراک ─────────────────────────────────────────────────── */
subscription: {
plans: () => raw<{ plans: Plan[] }>('GET', '/subscription/plans').then((r) => r.plans),
status: () =>
raw<{ active: boolean; planId: string | null; expiresAt: string | null }>(
'GET', '/subscription/status',
),
/**
* `paymentUrl` را در مرورگر باز کنید. آن آدرس خودش سراغِ زرین‌پال
* می‌رود؛ اپ نباید مستقیم با درگاه حرف بزند.
*/
purchase: (planId: string, idempotencyKey?: string) =>
raw<{ orderId: string; paymentUrl: string }>(
'POST', '/subscription/purchase', { planId },
idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {},
),
},
notifications: {
list: () => raw<{ items: unknown[]; unreadCount: number }>('GET', '/notifications'),
markRead: (id: number) => raw<Json>('POST', `/notifications/${id}/read`),
},
};
}
export type TadrisinoClient = ReturnType<typeof createClient>;

View File

@@ -119,3 +119,4 @@ export interface ReportResponse {
reportId: number; reportId: number;
alreadyReported: boolean; alreadyReported: boolean;
} }
*/

File diff suppressed because it is too large Load Diff