2026-11-07 16:27:38 +08:00
|
|
|
|
import type {
|
|
|
|
|
|
AiCapability,
|
|
|
|
|
|
AiConversationRequest,
|
|
|
|
|
|
AiConversationResult,
|
|
|
|
|
|
AiPlanStep,
|
2026-11-07 22:25:39 +08:00
|
|
|
|
AiModelInfo,
|
|
|
|
|
|
AiTaskDto,
|
2026-11-07 16:27:38 +08:00
|
|
|
|
} from '@classhelper/shared';
|
2026-09-11 21:57:38 +08:00
|
|
|
|
import {
|
|
|
|
|
|
API_PATHS,
|
2026-10-11 11:49:32 +08:00
|
|
|
|
type AiAuditDto,
|
|
|
|
|
|
type AiInterpretResult,
|
|
|
|
|
|
type AiSettingsDto,
|
|
|
|
|
|
type ApiErrorResponse,
|
2026-10-06 19:41:18 +08:00
|
|
|
|
type ArchivedClassContentDto,
|
|
|
|
|
|
type ArchivedYearDetailDto,
|
|
|
|
|
|
type ArchivedYearDto,
|
2026-10-11 11:49:32 +08:00
|
|
|
|
type AssignUserGroupsRequest,
|
2026-09-11 21:57:38 +08:00
|
|
|
|
type ClassDetailDto,
|
|
|
|
|
|
type ClassDto,
|
2026-10-06 19:41:18 +08:00
|
|
|
|
type AutoTermWeeksRequest,
|
2026-09-12 23:48:59 +08:00
|
|
|
|
type ClassPlanImportResultDto,
|
|
|
|
|
|
type ClassPlanPreviewDto,
|
2026-11-07 16:27:38 +08:00
|
|
|
|
type ClassPlanYamlImportResultDto,
|
|
|
|
|
|
type ClassPlanYamlPreviewDto,
|
2026-09-12 08:41:08 +08:00
|
|
|
|
type ClassStatusDto,
|
2026-10-11 11:49:32 +08:00
|
|
|
|
type ClientDeviceDto,
|
|
|
|
|
|
type ClientPushResult,
|
|
|
|
|
|
type ClientReleaseDto,
|
2026-09-11 21:57:38 +08:00
|
|
|
|
type CourseDto,
|
2026-09-12 13:57:46 +08:00
|
|
|
|
type CreateCallRequest,
|
2026-10-11 11:49:32 +08:00
|
|
|
|
type CreateClassRequest,
|
|
|
|
|
|
type CreateClientCommandRequest,
|
2026-09-11 21:57:38 +08:00
|
|
|
|
type CreateCourseRequest,
|
|
|
|
|
|
type CreateGradeRequest,
|
|
|
|
|
|
type CreateHomeworkRequest,
|
2026-10-11 11:49:32 +08:00
|
|
|
|
type BulkCreateHomeworkRequest,
|
|
|
|
|
|
type BulkCreateNotificationRequest,
|
|
|
|
|
|
type BulkPublishResult,
|
|
|
|
|
|
type NotificationCreatorsDto,
|
|
|
|
|
|
type NotificationDaysDto,
|
2026-09-11 21:57:38 +08:00
|
|
|
|
type CreateNotificationRequest,
|
2026-10-11 11:49:32 +08:00
|
|
|
|
type CreatePermissionGroupRequest,
|
2026-09-11 21:57:38 +08:00
|
|
|
|
type CreateScheduleRequest,
|
2026-10-06 19:41:18 +08:00
|
|
|
|
type CreateStudentRequest,
|
2026-09-11 21:57:38 +08:00
|
|
|
|
type DashboardSummary,
|
2026-10-02 11:18:47 +08:00
|
|
|
|
type DatabaseBackupMetaDto,
|
|
|
|
|
|
type DatabaseBackupScheduleDto,
|
|
|
|
|
|
type DatabaseConnectionTestDto,
|
|
|
|
|
|
type DatabaseStatusDto,
|
|
|
|
|
|
type DatabaseSwitchJobDto,
|
2026-10-11 16:21:38 +08:00
|
|
|
|
type ExamDto,
|
|
|
|
|
|
type ExamRankingDto,
|
2026-09-11 21:57:38 +08:00
|
|
|
|
type GradeDto,
|
2026-10-06 19:41:18 +08:00
|
|
|
|
type GradeLevelType,
|
2026-09-11 21:57:38 +08:00
|
|
|
|
type GradeStats,
|
2026-10-06 19:41:18 +08:00
|
|
|
|
type HolidaySuggestionDto,
|
2026-09-27 16:34:01 +08:00
|
|
|
|
type HomeworkDaysDto,
|
2026-09-11 21:57:38 +08:00
|
|
|
|
type HomeworkDto,
|
2026-09-12 23:48:59 +08:00
|
|
|
|
type HomeworkSubmissionsDto,
|
2026-09-11 21:57:38 +08:00
|
|
|
|
type LoginRequest,
|
|
|
|
|
|
type LoginResponse,
|
2026-10-11 11:49:32 +08:00
|
|
|
|
type MyPermissionsDto,
|
2026-09-11 21:57:38 +08:00
|
|
|
|
type NotificationDto,
|
2026-10-06 19:41:18 +08:00
|
|
|
|
type PaginatedResult,
|
2026-10-11 11:49:32 +08:00
|
|
|
|
type PermissionCatalogDto,
|
|
|
|
|
|
type PermissionGroupDto,
|
|
|
|
|
|
type PermissionMemberDto,
|
|
|
|
|
|
type PushClientUpdateRequest,
|
2026-09-11 21:57:38 +08:00
|
|
|
|
type ScheduleDto,
|
|
|
|
|
|
type ScheduleWeekView,
|
2026-10-06 19:41:18 +08:00
|
|
|
|
type SessionUser,
|
2026-09-11 21:57:38 +08:00
|
|
|
|
type StudentDto,
|
2026-10-06 19:41:18 +08:00
|
|
|
|
type StudentGradeDetailDto,
|
|
|
|
|
|
type StudentStatus,
|
|
|
|
|
|
type StudentTransferDto,
|
|
|
|
|
|
type SubjectTeacherDto,
|
2026-10-11 11:49:32 +08:00
|
|
|
|
type SystemDiagnosticsDto,
|
|
|
|
|
|
type SystemSettingsDto,
|
2026-09-12 15:35:01 +08:00
|
|
|
|
type TableImportPreview,
|
|
|
|
|
|
type TableImportResult,
|
2026-10-06 19:41:18 +08:00
|
|
|
|
type TermWeeksDto,
|
2026-09-12 15:35:01 +08:00
|
|
|
|
type TimeLayoutDto,
|
|
|
|
|
|
type TimeLayoutImportResult,
|
|
|
|
|
|
type TimeLayoutParsePreview,
|
2026-10-11 11:49:32 +08:00
|
|
|
|
type UpdateAiSettingsRequest,
|
2026-09-12 15:51:08 +08:00
|
|
|
|
type UpdateClassAccountRequest,
|
2026-09-11 21:57:38 +08:00
|
|
|
|
type UpdateClassRequest,
|
2026-10-05 16:39:38 +08:00
|
|
|
|
type UpdateInfo,
|
2026-10-11 11:49:32 +08:00
|
|
|
|
type UpdatePermissionGroupRequest,
|
2026-10-06 19:41:18 +08:00
|
|
|
|
type UpdateStudentRequest,
|
|
|
|
|
|
type UpdateTermWeeksRequest,
|
2026-09-11 21:57:38 +08:00
|
|
|
|
type UserDto,
|
|
|
|
|
|
} from '@classhelper/shared';
|
|
|
|
|
|
import { api } from './http';
|
|
|
|
|
|
|
|
|
|
|
|
/* ------------------------------------------------------------------ 认证 */
|
|
|
|
|
|
|
|
|
|
|
|
export const authApi = {
|
|
|
|
|
|
login: (payload: LoginRequest): Promise<LoginResponse> => api.post(API_PATHS.auth.login, payload),
|
|
|
|
|
|
logout: (): Promise<{ loggedOut: boolean }> => api.post(API_PATHS.auth.logout, {}),
|
2026-10-06 19:41:18 +08:00
|
|
|
|
/** 当前会话主体:教师/管理员是账号,ClassHelper 班级端是班级 */
|
|
|
|
|
|
me: (): Promise<SessionUser> => api.get(API_PATHS.auth.me),
|
2026-09-11 21:57:38 +08:00
|
|
|
|
changePassword: (payload: {
|
|
|
|
|
|
currentPassword: string;
|
|
|
|
|
|
newPassword: string;
|
|
|
|
|
|
}): Promise<{ changed: boolean }> => api.patch(API_PATHS.auth.changePassword, payload),
|
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
|
|
/* ------------------------------------------------------------------ 班级 */
|
|
|
|
|
|
|
|
|
|
|
|
export const classApi = {
|
|
|
|
|
|
list: (params?: { keyword?: string }): Promise<ClassDto[]> => api.get(API_PATHS.classes, params),
|
|
|
|
|
|
detail: (id: string): Promise<ClassDetailDto> => api.get(`${API_PATHS.classes}/${id}`),
|
|
|
|
|
|
create: (payload: CreateClassRequest): Promise<ClassDto> => api.post(API_PATHS.classes, payload),
|
|
|
|
|
|
update: (id: string, payload: UpdateClassRequest): Promise<ClassDto> =>
|
|
|
|
|
|
api.patch(`${API_PATHS.classes}/${id}`, payload),
|
2026-10-31 09:40:23 +08:00
|
|
|
|
updateSettings: (
|
|
|
|
|
|
id: string,
|
|
|
|
|
|
payload: { termWeeks?: number; termStartDate?: string | null },
|
|
|
|
|
|
): Promise<ClassDto> => api.patch(`${API_PATHS.classes}/${id}/settings`, payload),
|
2026-09-11 21:57:38 +08:00
|
|
|
|
remove: (id: string): Promise<{ id: string }> => api.delete(`${API_PATHS.classes}/${id}`),
|
|
|
|
|
|
students: (id: string): Promise<StudentDto[]> => api.get(`${API_PATHS.classes}/${id}/students`),
|
|
|
|
|
|
addStudent: (
|
|
|
|
|
|
id: string,
|
2026-10-06 19:41:18 +08:00
|
|
|
|
payload: { studentNo: string; name: string; gender?: string; guardianPhone?: string },
|
2026-09-11 21:57:38 +08:00
|
|
|
|
): Promise<StudentDto> => api.post(`${API_PATHS.classes}/${id}/students`, payload),
|
2026-10-06 19:41:18 +08:00
|
|
|
|
removeStudent: (id: string, studentId: string): Promise<unknown> =>
|
|
|
|
|
|
api.delete(`${API_PATHS.classes}/${id}/students/${studentId}`),
|
|
|
|
|
|
/** 设置 / 更改班主任(每班 1 人):仅管理员 */
|
2026-09-13 10:34:46 +08:00
|
|
|
|
assignHeadTeacher: (id: string, teacherId: string): Promise<ClassDto> =>
|
|
|
|
|
|
api.patch(`${API_PATHS.classes}/${id}/head-teacher`, { teacherId }),
|
2026-10-06 19:41:18 +08:00
|
|
|
|
/**
|
|
|
|
|
|
* 设置各科任课老师(班级 + 科目 + 教师):仅管理员。
|
|
|
|
|
|
* 这是「科任老师」这条关系的唯一写入口。
|
|
|
|
|
|
*/
|
|
|
|
|
|
assignSubjectTeachers: (
|
|
|
|
|
|
id: string,
|
|
|
|
|
|
assignments: Array<{ courseId?: string | null; subjectName: string; teacherId?: string | null }>,
|
2026-10-17 03:06:46 +08:00
|
|
|
|
): Promise<SubjectTeacherDto[]> => api.put(`${API_PATHS.classes}/${id}/subject-teachers`, { assignments }),
|
2026-09-12 15:51:08 +08:00
|
|
|
|
/** 设置 / 重置班级账号(班级码 + 班级密码):仅管理员 */
|
|
|
|
|
|
updateAccount: (id: string, payload: UpdateClassAccountRequest): Promise<ClassDto> =>
|
|
|
|
|
|
api.patch(`${API_PATHS.classes}/${id}/class-account`, payload),
|
2026-10-06 19:41:18 +08:00
|
|
|
|
setGradeQuery: (id: string, enabled: boolean): Promise<{ studentGradeQueryEnabled: boolean }> =>
|
|
|
|
|
|
api.patch(`${API_PATHS.classes}/${id}/student-grade-query`, { enabled }),
|
|
|
|
|
|
/** 学年升级:只改年级,不归档、数据沿用 */
|
2026-10-23 22:55:21 +08:00
|
|
|
|
promote: (classIds: string[]): Promise<{ promoted: number }> =>
|
|
|
|
|
|
api.post(`${API_PATHS.classes}/promote`, { classIds }),
|
2026-09-11 21:57:38 +08:00
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
|
|
/* ------------------------------------------------------------------ 课程 */
|
|
|
|
|
|
|
|
|
|
|
|
export const courseApi = {
|
|
|
|
|
|
list: (classId?: string): Promise<CourseDto[]> =>
|
|
|
|
|
|
api.get(API_PATHS.courses, classId ? { classId } : undefined),
|
|
|
|
|
|
create: (payload: CreateCourseRequest): Promise<CourseDto> => api.post(API_PATHS.courses, payload),
|
|
|
|
|
|
remove: (id: string): Promise<{ id: string }> => api.delete(`${API_PATHS.courses}/${id}`),
|
|
|
|
|
|
};
|
|
|
|
|
|
|
2026-10-11 11:49:32 +08:00
|
|
|
|
/**
|
|
|
|
|
|
* 从「同名课程已存在」的失败里取出那门已有课程的 id。
|
|
|
|
|
|
*
|
|
|
|
|
|
* 服务端对 `POST /courses` 做了 (班级 + 科目名) 去重(返回 409 `COURSE_EXISTS` +
|
|
|
|
|
|
* `details.courseId`),因为课程创建会把创建者写成任课老师 —— 若放行同名第二门课,
|
|
|
|
|
|
* 谁都能借"新建科目"把自己变成别人的科目的老师,绕过科目维度的写权限。
|
|
|
|
|
|
* 前端拿到这个 id 就**复用既有课程**:权限判定随即回到"你是不是这门课的老师",
|
|
|
|
|
|
* 该 403 的地方就 403(而不是悄悄多出一门归属自己的同名课)。
|
|
|
|
|
|
*/
|
|
|
|
|
|
export function courseIdFromExistsError(error: unknown): string | null {
|
|
|
|
|
|
const data = (error as { response?: { data?: ApiErrorResponse } })?.response?.data;
|
|
|
|
|
|
if (!data || data.code !== 'COURSE_EXISTS') return null;
|
|
|
|
|
|
const details = data.details as { courseId?: unknown } | null | undefined;
|
|
|
|
|
|
return typeof details?.courseId === 'string' ? details.courseId : null;
|
|
|
|
|
|
}
|
|
|
|
|
|
|
2026-09-11 21:57:38 +08:00
|
|
|
|
/* ------------------------------------------------------------------ 课表 */
|
|
|
|
|
|
|
|
|
|
|
|
export const scheduleApi = {
|
|
|
|
|
|
list: (params: { classId?: string; week?: number; dayOfWeek?: number }): Promise<ScheduleDto[]> =>
|
|
|
|
|
|
api.get(API_PATHS.schedules, params),
|
|
|
|
|
|
grid: (params: { classId?: string; week?: number }): Promise<ScheduleWeekView> =>
|
|
|
|
|
|
api.get(`${API_PATHS.schedules}/grid`, params),
|
2026-09-12 08:41:08 +08:00
|
|
|
|
/** 班级当前上课状态:上课时段发布紧急通知时必须先二次确认 */
|
|
|
|
|
|
classStatus: (classId: string): Promise<ClassStatusDto> =>
|
|
|
|
|
|
api.get(`${API_PATHS.schedules}/current`, { classId }),
|
2026-09-11 21:57:38 +08:00
|
|
|
|
create: (payload: CreateScheduleRequest): Promise<ScheduleDto> => api.post(API_PATHS.schedules, payload),
|
|
|
|
|
|
update: (id: string, payload: Partial<CreateScheduleRequest>): Promise<ScheduleDto> =>
|
|
|
|
|
|
api.patch(`${API_PATHS.schedules}/${id}`, payload),
|
|
|
|
|
|
remove: (id: string): Promise<{ id: string }> => api.delete(`${API_PATHS.schedules}/${id}`),
|
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
|
|
/* ------------------------------------------------------------------ 作业 */
|
|
|
|
|
|
|
|
|
|
|
|
export const homeworkApi = {
|
|
|
|
|
|
list: (params: {
|
|
|
|
|
|
classId?: string;
|
|
|
|
|
|
courseId?: string;
|
|
|
|
|
|
pendingOnly?: boolean;
|
|
|
|
|
|
keyword?: string;
|
2026-09-27 16:34:01 +08:00
|
|
|
|
/** 只看某一天(YYYY-MM-DD,按作业所属日期) */
|
|
|
|
|
|
date?: string;
|
2026-09-11 21:57:38 +08:00
|
|
|
|
}): Promise<HomeworkDto[]> => api.get(API_PATHS.homeworks, params),
|
2026-09-27 16:34:01 +08:00
|
|
|
|
/** 哪些天有作业(日期选择器高亮) */
|
2026-11-07 16:27:38 +08:00
|
|
|
|
days: (params: {
|
|
|
|
|
|
classId?: string;
|
|
|
|
|
|
courseId?: string;
|
|
|
|
|
|
keyword?: string;
|
|
|
|
|
|
pendingOnly?: boolean;
|
|
|
|
|
|
from?: string;
|
|
|
|
|
|
to?: string;
|
|
|
|
|
|
days?: number;
|
|
|
|
|
|
}): Promise<HomeworkDaysDto> => api.get(`${API_PATHS.homeworks}/days`, params),
|
2026-09-11 21:57:38 +08:00
|
|
|
|
detail: (id: string): Promise<HomeworkDto> => api.get(`${API_PATHS.homeworks}/${id}`),
|
|
|
|
|
|
create: (payload: CreateHomeworkRequest): Promise<HomeworkDto> => api.post(API_PATHS.homeworks, payload),
|
2026-10-11 11:49:32 +08:00
|
|
|
|
/** 一次给多个班级布置同一份作业(服务端逐班判定并返回逐班结果) */
|
|
|
|
|
|
bulkCreate: (payload: BulkCreateHomeworkRequest): Promise<BulkPublishResult> =>
|
|
|
|
|
|
api.post(`${API_PATHS.homeworks}/bulk`, payload),
|
2026-09-11 21:57:38 +08:00
|
|
|
|
update: (id: string, payload: Partial<CreateHomeworkRequest>): Promise<HomeworkDto> =>
|
|
|
|
|
|
api.patch(`${API_PATHS.homeworks}/${id}`, payload),
|
|
|
|
|
|
remove: (id: string): Promise<{ id: string }> => api.delete(`${API_PATHS.homeworks}/${id}`),
|
2026-10-06 19:41:18 +08:00
|
|
|
|
/** 提交名单 / 未交名单(教师与 ClassHelper 班级端可用) */
|
2026-09-12 23:48:59 +08:00
|
|
|
|
submissions: (id: string): Promise<HomeworkSubmissionsDto> =>
|
|
|
|
|
|
api.get(`${API_PATHS.homeworks}/${id}/submissions`),
|
2026-10-06 19:41:18 +08:00
|
|
|
|
saveSubmissions: (id: string, notSubmittedStudentIds: string[]): Promise<HomeworkSubmissionsDto> =>
|
|
|
|
|
|
api.patch(`${API_PATHS.homeworks}/${id}/submissions`, { notSubmittedStudentIds }),
|
2026-09-11 21:57:38 +08:00
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
|
|
/* ------------------------------------------------------------------ 通知 */
|
|
|
|
|
|
|
|
|
|
|
|
export const notificationApi = {
|
|
|
|
|
|
list: (params: {
|
|
|
|
|
|
classId?: string;
|
|
|
|
|
|
priority?: string;
|
|
|
|
|
|
unreadOnly?: boolean;
|
|
|
|
|
|
keyword?: string;
|
2026-10-11 11:49:32 +08:00
|
|
|
|
/** 只看某一天(YYYY-MM-DD,按通知所属日期 assignDate) */
|
|
|
|
|
|
date?: string;
|
|
|
|
|
|
/** 日期区间(含边界) */
|
|
|
|
|
|
from?: string;
|
|
|
|
|
|
to?: string;
|
|
|
|
|
|
/** 只看某位发布人 */
|
|
|
|
|
|
createdBy?: string;
|
2026-09-11 21:57:38 +08:00
|
|
|
|
}): Promise<NotificationDto[]> => api.get(API_PATHS.notifications, params),
|
2026-10-11 11:49:32 +08:00
|
|
|
|
/** 按天归档:有通知的日期 + 当天条数 */
|
|
|
|
|
|
days: (params: {
|
|
|
|
|
|
classId?: string;
|
|
|
|
|
|
priority?: string;
|
2026-11-07 16:27:38 +08:00
|
|
|
|
keyword?: string;
|
2026-10-11 11:49:32 +08:00
|
|
|
|
createdBy?: string;
|
|
|
|
|
|
from?: string;
|
|
|
|
|
|
to?: string;
|
|
|
|
|
|
}): Promise<NotificationDaysDto> => api.get(`${API_PATHS.notifications}/days`, params),
|
|
|
|
|
|
/** 按发布人归档:发布人 + 各人的通知条数 */
|
|
|
|
|
|
creators: (params: {
|
|
|
|
|
|
classId?: string;
|
|
|
|
|
|
priority?: string;
|
|
|
|
|
|
date?: string;
|
|
|
|
|
|
from?: string;
|
|
|
|
|
|
to?: string;
|
|
|
|
|
|
}): Promise<NotificationCreatorsDto> => api.get(`${API_PATHS.notifications}/creators`, params),
|
2026-09-11 21:57:38 +08:00
|
|
|
|
create: (payload: CreateNotificationRequest): Promise<NotificationDto> =>
|
|
|
|
|
|
api.post(API_PATHS.notifications, payload),
|
2026-10-11 11:49:32 +08:00
|
|
|
|
/** 一次给多个班级发同一条通知(服务端逐班判定并返回逐班结果) */
|
|
|
|
|
|
bulkCreate: (payload: BulkCreateNotificationRequest): Promise<BulkPublishResult> =>
|
|
|
|
|
|
api.post(`${API_PATHS.notifications}/bulk`, payload),
|
2026-09-11 21:57:38 +08:00
|
|
|
|
remove: (id: string): Promise<{ id: string }> => api.delete(`${API_PATHS.notifications}/${id}`),
|
|
|
|
|
|
unreadCount: (classId?: string): Promise<{ count: number }> =>
|
|
|
|
|
|
api.get(`${API_PATHS.notifications}/unread-count`, classId ? { classId } : undefined),
|
|
|
|
|
|
};
|
|
|
|
|
|
|
2026-09-12 13:57:46 +08:00
|
|
|
|
/* ------------------------------------------------------------------ 叫人 */
|
|
|
|
|
|
|
|
|
|
|
|
export const callApi = {
|
2026-10-06 19:41:18 +08:00
|
|
|
|
/** 点名让学生来找老师(ClassHelper 班级端灵动岛会立即弹出"请 XXX 同学找 XXX 老师") */
|
2026-09-12 13:57:46 +08:00
|
|
|
|
create: (payload: CreateCallRequest): Promise<NotificationDto> => api.post(API_PATHS.calls, payload),
|
|
|
|
|
|
};
|
|
|
|
|
|
|
2026-09-11 21:57:38 +08:00
|
|
|
|
/* ------------------------------------------------------------------ 成绩 */
|
|
|
|
|
|
|
|
|
|
|
|
export const gradeApi = {
|
|
|
|
|
|
list: (params: {
|
|
|
|
|
|
classId?: string;
|
|
|
|
|
|
courseId?: string;
|
2026-10-06 19:41:18 +08:00
|
|
|
|
/** 学生 id(学生是名单记录,不是账号) */
|
|
|
|
|
|
studentId?: string;
|
2026-09-11 21:57:38 +08:00
|
|
|
|
examName?: string;
|
|
|
|
|
|
}): Promise<GradeDto[]> => api.get(API_PATHS.grades, params),
|
|
|
|
|
|
stats: (params: { classId?: string; courseId?: string; examName?: string }): Promise<GradeStats> =>
|
|
|
|
|
|
api.get(`${API_PATHS.grades}/stats`, params),
|
|
|
|
|
|
create: (payload: CreateGradeRequest): Promise<GradeDto> => api.post(API_PATHS.grades, payload),
|
|
|
|
|
|
bulkCreate: (payload: {
|
|
|
|
|
|
classId: string;
|
|
|
|
|
|
courseId?: string | null;
|
|
|
|
|
|
examName: string;
|
|
|
|
|
|
totalScore?: number;
|
2026-10-06 19:41:18 +08:00
|
|
|
|
levelType?: GradeLevelType;
|
2026-09-11 21:57:38 +08:00
|
|
|
|
publishedAt?: string | null;
|
2026-10-06 19:41:18 +08:00
|
|
|
|
items: Array<{ studentId: string; score: number; level?: string }>;
|
2026-09-11 21:57:38 +08:00
|
|
|
|
}): Promise<{ count: number; items: GradeDto[] }> => api.post(`${API_PATHS.grades}/bulk`, payload),
|
|
|
|
|
|
update: (id: string, payload: Partial<CreateGradeRequest>): Promise<GradeDto> =>
|
|
|
|
|
|
api.patch(`${API_PATHS.grades}/${id}`, payload),
|
2026-10-06 19:41:18 +08:00
|
|
|
|
/** 批量改等级:逐条指定;或整批重算(classId + examName + levelType) */
|
|
|
|
|
|
updateLevels: (
|
|
|
|
|
|
payload:
|
|
|
|
|
|
| { items: Array<{ id: string; level: string }> }
|
|
|
|
|
|
| { classId: string; examName: string; courseId?: string | null; levelType: GradeLevelType },
|
|
|
|
|
|
): Promise<{ updated: number }> => api.patch(`${API_PATHS.grades}/levels`, payload),
|
|
|
|
|
|
/** 按**学号**查某个学生的成绩明细(教师端"按学号查成绩") */
|
|
|
|
|
|
studentDetail: (studentNo: string, classId?: string): Promise<StudentGradeDetailDto> =>
|
2026-10-17 03:06:46 +08:00
|
|
|
|
api.get(
|
|
|
|
|
|
`${API_PATHS.grades}/student/${encodeURIComponent(studentNo)}`,
|
|
|
|
|
|
classId ? { classId } : undefined,
|
|
|
|
|
|
),
|
2026-10-11 16:21:38 +08:00
|
|
|
|
/** 某班出现过的考试(含"是否计入总分") */
|
|
|
|
|
|
listExams: (classId: string): Promise<ExamDto[]> => api.get(`${API_PATHS.grades}/exams`, { classId }),
|
|
|
|
|
|
/** 设置"这次考试是否把所有科目相加做总分排名" */
|
|
|
|
|
|
setExam: (payload: { classId: string; name: string; countInTotal: boolean }): Promise<ExamDto> =>
|
|
|
|
|
|
api.put(`${API_PATHS.grades}/exams`, payload),
|
|
|
|
|
|
/** 一次考试的单科榜与总分榜 */
|
|
|
|
|
|
ranking: (params: { classId: string; examName: string }): Promise<ExamRankingDto> =>
|
|
|
|
|
|
api.get(`${API_PATHS.grades}/ranking`, params),
|
2026-09-11 21:57:38 +08:00
|
|
|
|
remove: (id: string): Promise<{ id: string }> => api.delete(`${API_PATHS.grades}/${id}`),
|
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
|
|
/* ------------------------------------------------------------------ 学生 */
|
|
|
|
|
|
|
2026-10-06 19:41:18 +08:00
|
|
|
|
// 学生是「名单记录」不是「账号」:没有密码相关接口,登录统一走班级码 + 班级密码。
|
|
|
|
|
|
// 学号(studentNo)是学生的唯一标识与查询键。
|
2026-09-11 21:57:38 +08:00
|
|
|
|
export const studentApi = {
|
2026-10-06 19:41:18 +08:00
|
|
|
|
list: (params?: {
|
|
|
|
|
|
classId?: string;
|
|
|
|
|
|
keyword?: string;
|
|
|
|
|
|
status?: StudentStatus;
|
|
|
|
|
|
includeArchived?: boolean;
|
|
|
|
|
|
}): Promise<StudentDto[]> => api.get(API_PATHS.students, params),
|
|
|
|
|
|
create: (payload: CreateStudentRequest): Promise<StudentDto> => api.post(API_PATHS.students, payload),
|
|
|
|
|
|
update: (id: string, payload: UpdateStudentRequest): Promise<StudentDto> =>
|
|
|
|
|
|
api.patch(`${API_PATHS.students}/${id}`, payload),
|
2026-09-11 21:57:38 +08:00
|
|
|
|
remove: (id: string): Promise<{ id: string }> => api.delete(`${API_PATHS.students}/${id}`),
|
2026-10-06 19:41:18 +08:00
|
|
|
|
/** 调班:单个与批量同一接口(studentIds 长度 1 即单个);学号不变、历史可查 */
|
2026-10-23 22:55:21 +08:00
|
|
|
|
transfer: (
|
|
|
|
|
|
studentIds: string[],
|
|
|
|
|
|
toClassId: string | null,
|
|
|
|
|
|
note?: string,
|
|
|
|
|
|
allowGradeChange?: boolean,
|
|
|
|
|
|
): Promise<{ moved: number }> =>
|
|
|
|
|
|
api.post(`${API_PATHS.students}/transfer`, { studentIds, toClassId, note, allowGradeChange }),
|
2026-10-06 19:41:18 +08:00
|
|
|
|
/** 转出(学籍离开本校,不是调班) */
|
2026-10-23 22:55:21 +08:00
|
|
|
|
transferOut: (studentIds: string[], note?: string, toSchool?: string): Promise<{ transferred: number }> =>
|
|
|
|
|
|
api.post(`${API_PATHS.students}/transfer-out`, { studentIds, note, toSchool }),
|
2026-10-06 19:41:18 +08:00
|
|
|
|
/** 某个学生的调班 / 转出历史 */
|
|
|
|
|
|
transfersOf: (id: string): Promise<PaginatedResult<StudentTransferDto>> =>
|
|
|
|
|
|
api.get(`${API_PATHS.students}/${id}/transfers`),
|
2026-09-11 21:57:38 +08:00
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
|
|
/* ------------------------------------------------------------------ 仪表盘 */
|
|
|
|
|
|
|
|
|
|
|
|
export const dashboardApi = {
|
|
|
|
|
|
summary: (): Promise<DashboardSummary> => api.get(API_PATHS.dashboard),
|
2026-09-13 08:39:11 +08:00
|
|
|
|
/**
|
|
|
|
|
|
* 学期信息:`maxWeek` 是该班的教学周数(`Class.termWeeks`,班主任可调,默认 20),
|
|
|
|
|
|
* 不带 classId 时后端回退全局默认值。
|
|
|
|
|
|
*/
|
|
|
|
|
|
term: (classId?: string): Promise<{ currentWeek: number; maxWeek: number }> =>
|
|
|
|
|
|
api.get('/dashboard/term', classId ? { classId } : undefined),
|
2026-09-11 21:57:38 +08:00
|
|
|
|
};
|
|
|
|
|
|
|
2026-09-13 10:34:46 +08:00
|
|
|
|
/* ------------------------------------------------------------------ 教师管理(仅管理员) */
|
2026-09-11 21:57:38 +08:00
|
|
|
|
|
2026-10-06 19:41:18 +08:00
|
|
|
|
/** 教师的 `username` 就是**工号**(也是登录名),界面上统一叫「工号」 */
|
2026-09-11 21:57:38 +08:00
|
|
|
|
export const teacherApi = {
|
|
|
|
|
|
list: (keyword?: string): Promise<UserDto[]> =>
|
|
|
|
|
|
api.get(API_PATHS.teachers, keyword ? { keyword } : undefined),
|
|
|
|
|
|
create: (payload: {
|
|
|
|
|
|
username: string;
|
|
|
|
|
|
name: string;
|
2026-10-06 19:41:18 +08:00
|
|
|
|
phone?: string;
|
2026-09-13 10:34:46 +08:00
|
|
|
|
password?: string;
|
2026-09-11 21:57:38 +08:00
|
|
|
|
role?: 'TEACHER' | 'ADMIN';
|
|
|
|
|
|
}): Promise<UserDto> => api.post(API_PATHS.teachers, payload),
|
2026-09-13 10:34:46 +08:00
|
|
|
|
update: (
|
|
|
|
|
|
id: string,
|
2026-10-06 19:41:18 +08:00
|
|
|
|
payload: { username?: string; name?: string; phone?: string; role?: 'TEACHER' | 'ADMIN' },
|
2026-09-13 10:34:46 +08:00
|
|
|
|
): Promise<UserDto> => api.patch(`${API_PATHS.teachers}/${id}`, payload),
|
|
|
|
|
|
remove: (id: string): Promise<{ id: string }> => api.delete(`${API_PATHS.teachers}/${id}`),
|
|
|
|
|
|
resetPassword: (id: string, newPassword?: string): Promise<unknown> =>
|
|
|
|
|
|
api.post(`${API_PATHS.teachers}/${id}/reset-password`, newPassword ? { newPassword } : {}),
|
2026-10-06 19:41:18 +08:00
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
|
|
/* ------------------------------------------------------------------ 毕业归档(仅管理员) */
|
|
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
|
* 归档是**打标记 + 只读**,不删数据:毕业班级的作业与通知原样留在库里,
|
|
|
|
|
|
* 通过 `classContent()` 只读查看。「未毕业而升级的班级不归档」走 `classApi.promote`。
|
|
|
|
|
|
*/
|
|
|
|
|
|
export const archiveApi = {
|
|
|
|
|
|
list: (): Promise<ArchivedYearDto[]> => api.get(API_PATHS.archives),
|
|
|
|
|
|
summary: (): Promise<{
|
|
|
|
|
|
archiveCount: number;
|
|
|
|
|
|
classCount: number;
|
|
|
|
|
|
graduateCount: number;
|
|
|
|
|
|
transferredCount: number;
|
|
|
|
|
|
suggestedEnrollmentYears: number[];
|
|
|
|
|
|
}> => api.get(`${API_PATHS.archives}/summary`),
|
|
|
|
|
|
detail: (id: string): Promise<ArchivedYearDetailDto> => api.get(`${API_PATHS.archives}/${id}`),
|
|
|
|
|
|
/** 归档班级的作业与通知(只读) */
|
|
|
|
|
|
classContent: (id: string, classId: string, limit = 200): Promise<ArchivedClassContentDto> =>
|
|
|
|
|
|
api.get(`${API_PATHS.archives}/${id}/classes/${classId}/content`, { limit }),
|
|
|
|
|
|
/** 撤销归档(误操作的退路,不删任何数据) */
|
|
|
|
|
|
remove: (id: string): Promise<{ id: string }> => api.delete(`${API_PATHS.archives}/${id}`),
|
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
|
|
/* ------------------------------------------------------------------ 学期周次(仅管理员可写) */
|
|
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
|
* 学期周次:逐周指定实际的起止日期。
|
|
|
|
|
|
*
|
|
|
|
|
|
* 课表、作业、成绩都按教学周组织,而"开学日期 + 每周七天"的线性推算遇到调休、
|
|
|
|
|
|
* 周末补课、错峰开学就会整体错位 —— 所以支持逐周配置。
|
|
|
|
|
|
* `classId` 留空 = 全校默认;保存后变更会随课表下发给教室的 ClassHelper 班级端。
|
|
|
|
|
|
*/
|
|
|
|
|
|
export const termApi = {
|
|
|
|
|
|
get: (classId?: string): Promise<TermWeeksDto> =>
|
|
|
|
|
|
api.get(API_PATHS.term, classId ? { classId } : undefined),
|
|
|
|
|
|
save: (payload: UpdateTermWeeksRequest): Promise<TermWeeksDto> => api.put(API_PATHS.term, payload),
|
|
|
|
|
|
/** 按学期开始日期一键生成逐周区间(配置的起点) */
|
|
|
|
|
|
auto: (payload: AutoTermWeeksRequest): Promise<TermWeeksDto> => api.post(`${API_PATHS.term}/auto`, payload),
|
|
|
|
|
|
/** 联网获取法定节假日安排(只给建议;机房没外网时 ok=false 属正常) */
|
|
|
|
|
|
holidays: (year?: number): Promise<HolidaySuggestionDto> =>
|
|
|
|
|
|
api.get(`${API_PATHS.term}/holidays`, year ? { year } : undefined),
|
2026-09-11 21:57:38 +08:00
|
|
|
|
};
|
2026-09-12 15:35:01 +08:00
|
|
|
|
|
2026-09-12 23:48:59 +08:00
|
|
|
|
/* ------------------------------------------------------------------ 导入(模板 / 表格 / 课表时间配置 / ClassIsland 课程表) */
|
2026-09-12 15:35:01 +08:00
|
|
|
|
|
2026-10-06 19:41:18 +08:00
|
|
|
|
type TableKind = 'grades' | 'students' | 'teachers' | 'classTeachers';
|
|
|
|
|
|
|
2026-09-12 15:35:01 +08:00
|
|
|
|
export const importApi = {
|
|
|
|
|
|
/** 模板下载地址(CSV 走 JSON,XLSX 走二进制) */
|
|
|
|
|
|
template: (
|
2026-10-06 19:41:18 +08:00
|
|
|
|
kind: TableKind,
|
2026-09-12 15:35:01 +08:00
|
|
|
|
format: 'csv' | 'xlsx' = 'csv',
|
|
|
|
|
|
): Promise<{ kind: string; format: string; fileName: string; content: string }> =>
|
|
|
|
|
|
api.get(`${API_PATHS.imports}/template`, { kind, format }),
|
|
|
|
|
|
|
|
|
|
|
|
/** 上传表格并预览(解析 + 必填列校验 + 建议映射,不写库) */
|
|
|
|
|
|
previewTable: (payload: {
|
2026-10-06 19:41:18 +08:00
|
|
|
|
kind: TableKind;
|
2026-09-12 15:35:01 +08:00
|
|
|
|
fileName: string;
|
|
|
|
|
|
contentBase64: string;
|
|
|
|
|
|
}): Promise<TableImportPreview> => api.post(`${API_PATHS.imports}/table/preview`, payload),
|
|
|
|
|
|
|
2026-09-13 10:34:46 +08:00
|
|
|
|
/** 确认字段映射与写入模式后执行导入(教师名单与班级无关,classId 可省略) */
|
2026-09-12 15:35:01 +08:00
|
|
|
|
commitTable: (payload: {
|
2026-10-06 19:41:18 +08:00
|
|
|
|
kind: TableKind;
|
2026-09-13 10:34:46 +08:00
|
|
|
|
classId?: string;
|
2026-09-12 15:35:01 +08:00
|
|
|
|
fileName: string;
|
|
|
|
|
|
contentBase64: string;
|
|
|
|
|
|
mapping: Record<string, string>;
|
|
|
|
|
|
mode: 'append' | 'upsert';
|
2026-10-06 19:41:18 +08:00
|
|
|
|
/** 班级任课老师导入:是否用「工号」匹配已有教师账号 */
|
|
|
|
|
|
useTeacherNo?: boolean;
|
2026-09-12 15:35:01 +08:00
|
|
|
|
}): Promise<TableImportResult> => api.post(`${API_PATHS.imports}/table/commit`, payload),
|
|
|
|
|
|
|
|
|
|
|
|
/** ClassIsland 时间配置解析预览(不写库) */
|
|
|
|
|
|
previewTimeLayout: (payload: {
|
|
|
|
|
|
classId: string;
|
|
|
|
|
|
name?: string;
|
|
|
|
|
|
mode?: 'replace' | 'merge';
|
|
|
|
|
|
payload: unknown;
|
|
|
|
|
|
}): Promise<TimeLayoutParsePreview> => api.post(`${API_PATHS.imports}/time-layout/preview`, payload),
|
|
|
|
|
|
|
|
|
|
|
|
/** 某班已导入的时间配置 */
|
|
|
|
|
|
listTimeLayouts: (classId: string): Promise<TimeLayoutDto[]> =>
|
|
|
|
|
|
api.get(`${API_PATHS.imports}/time-layout`, { classId }),
|
|
|
|
|
|
|
|
|
|
|
|
/** 导入(覆盖或合并;解析失败返回 400 且不改动原配置) */
|
|
|
|
|
|
importTimeLayout: (payload: {
|
|
|
|
|
|
classId: string;
|
|
|
|
|
|
name?: string;
|
|
|
|
|
|
mode: 'replace' | 'merge';
|
|
|
|
|
|
payload: unknown;
|
|
|
|
|
|
}): Promise<TimeLayoutImportResult> => api.post(`${API_PATHS.imports}/time-layout`, payload),
|
|
|
|
|
|
|
|
|
|
|
|
removeTimeLayout: (id: string): Promise<{ id: string }> =>
|
|
|
|
|
|
api.delete(`${API_PATHS.imports}/time-layout/${id}`),
|
2026-09-12 23:48:59 +08:00
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
|
* ClassIsland 课程表(ClassPlan)解析预览(不写库)。
|
|
|
|
|
|
* 注意:请求体里的 JSON 字段名就叫 payload(与 ClassIsland 档案 JSON 同名)。
|
|
|
|
|
|
*/
|
|
|
|
|
|
previewClassPlan: (payload: {
|
|
|
|
|
|
classId: string;
|
|
|
|
|
|
mode?: 'replace' | 'merge';
|
|
|
|
|
|
payload: unknown;
|
|
|
|
|
|
}): Promise<ClassPlanPreviewDto> => api.post(`${API_PATHS.imports}/class-plan/preview`, payload),
|
|
|
|
|
|
|
|
|
|
|
|
/** 导入 ClassIsland 课程表(支持单双周:replace 覆盖 / merge 合并;失败会抛错且不改动原课表) */
|
|
|
|
|
|
importClassPlan: (payload: {
|
|
|
|
|
|
classId: string;
|
|
|
|
|
|
mode?: 'replace' | 'merge';
|
|
|
|
|
|
payload: unknown;
|
|
|
|
|
|
}): Promise<ClassPlanImportResultDto> => api.post(`${API_PATHS.imports}/class-plan`, payload),
|
2026-11-07 16:27:38 +08:00
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
|
* 课表 YAML 解析预览(不写库)。
|
|
|
|
|
|
* YAML 面向手写 / 大模型生成:`enable_day` 1=周一 … 7=周日,`weeks` 取 all/odd/even。
|
|
|
|
|
|
*/
|
|
|
|
|
|
previewYamlClassPlan: (payload: {
|
|
|
|
|
|
classId: string;
|
|
|
|
|
|
mode?: 'replace' | 'merge';
|
|
|
|
|
|
text: string;
|
|
|
|
|
|
}): Promise<ClassPlanYamlPreviewDto> => api.post(`${API_PATHS.imports}/class-plan/yaml/preview`, payload),
|
|
|
|
|
|
|
|
|
|
|
|
/** 导入课表 YAML(支持单双周:replace 覆盖 / merge 合并;解析失败会抛错且不改动原课表) */
|
|
|
|
|
|
importYamlClassPlan: (payload: {
|
|
|
|
|
|
classId: string;
|
|
|
|
|
|
mode?: 'replace' | 'merge';
|
|
|
|
|
|
text: string;
|
|
|
|
|
|
}): Promise<ClassPlanYamlImportResultDto> => api.post(`${API_PATHS.imports}/class-plan/yaml`, payload),
|
2026-09-12 15:35:01 +08:00
|
|
|
|
};
|
2026-09-27 14:59:12 +08:00
|
|
|
|
|
2026-10-02 11:18:47 +08:00
|
|
|
|
/* ------------------------------------------------------------------ 数据库管理(仅管理员) */
|
|
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
|
* 数据库管理:状态 / 连接测试 / 备份 / 导入导出 / 定时备份 / 一键切换。
|
|
|
|
|
|
*
|
|
|
|
|
|
* 「快照下载」与「数据库文件下载」是二进制流,走 http.ts 的 download()(返回 Blob),
|
|
|
|
|
|
* 由页面负责触发浏览器保存;导入把快照 JSON 转 base64 放进请求体(受 12MB 请求体限制)。
|
|
|
|
|
|
*/
|
|
|
|
|
|
export const databaseApi = {
|
|
|
|
|
|
status: (): Promise<DatabaseStatusDto> => api.get(`${API_PATHS.database}/status`),
|
2026-10-05 16:39:38 +08:00
|
|
|
|
testConnection: (payload: {
|
|
|
|
|
|
provider: 'sqlite' | 'mysql';
|
|
|
|
|
|
url: string;
|
|
|
|
|
|
}): Promise<DatabaseConnectionTestDto> => api.post(`${API_PATHS.database}/test-connection`, payload),
|
2026-10-02 11:18:47 +08:00
|
|
|
|
listBackups: (): Promise<DatabaseBackupMetaDto[]> => api.get(`${API_PATHS.database}/backups`),
|
|
|
|
|
|
createBackup: (): Promise<DatabaseBackupMetaDto> => api.post(`${API_PATHS.database}/backups`, {}),
|
|
|
|
|
|
restoreBackup: (name: string): Promise<{ counts: Record<string, number> }> =>
|
|
|
|
|
|
api.post(`${API_PATHS.database}/backups/${encodeURIComponent(name)}/restore`, {}),
|
|
|
|
|
|
deleteBackup: (name: string): Promise<{ name: string }> =>
|
|
|
|
|
|
api.delete(`${API_PATHS.database}/backups/${encodeURIComponent(name)}`),
|
|
|
|
|
|
importSnapshot: (base64: string): Promise<{ counts: Record<string, number> }> =>
|
|
|
|
|
|
api.post(`${API_PATHS.database}/import`, { data: base64 }),
|
|
|
|
|
|
/** 下载当前库的 JSON 快照(Blob,页面触发浏览器保存) */
|
|
|
|
|
|
downloadSnapshot: (): Promise<Blob> => api.download(`${API_PATHS.database}/export`),
|
|
|
|
|
|
/** 下载数据库文件(仅 SQLite 模式;MySQL 无单文件概念) */
|
|
|
|
|
|
downloadSqliteFile: (): Promise<Blob> => api.download(`${API_PATHS.database}/sqlite-file`),
|
|
|
|
|
|
getSchedule: (): Promise<DatabaseBackupScheduleDto> => api.get(`${API_PATHS.database}/backup-schedule`),
|
|
|
|
|
|
saveSchedule: (payload: DatabaseBackupScheduleDto): Promise<DatabaseBackupScheduleDto> =>
|
|
|
|
|
|
api.put(`${API_PATHS.database}/backup-schedule`, payload),
|
|
|
|
|
|
startSwitch: (payload: { provider: 'sqlite' | 'mysql'; url: string }): Promise<{ jobId: string }> =>
|
|
|
|
|
|
api.post(`${API_PATHS.database}/switch`, payload),
|
|
|
|
|
|
getSwitchJob: (jobId: string): Promise<DatabaseSwitchJobDto | null> =>
|
|
|
|
|
|
api.get(`${API_PATHS.database}/switch/jobs/${encodeURIComponent(jobId)}`),
|
|
|
|
|
|
};
|
2026-10-05 16:39:38 +08:00
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
|
* 更新检查:问服务端 GitHub 上有没有比本机新的版本。
|
|
|
|
|
|
*
|
|
|
|
|
|
* **Web 端不直连 GitHub** —— 服务端下发的 CSP `connect-src` 只放行 `'self'` 与 WebSocket
|
|
|
|
|
|
* (见 `middleware/security.ts`),浏览器直连 `api.github.com` 会被拦掉;
|
|
|
|
|
|
* 走服务端转发还顺带让所有管理员共享同一份缓存(匿名限流 60 次/小时/IP)。
|
|
|
|
|
|
*
|
|
|
|
|
|
* `ok:false` 是正常结果(机房没外网 / GitHub 限流),不是异常。
|
|
|
|
|
|
*/
|
|
|
|
|
|
export const updateApi = {
|
|
|
|
|
|
/** @param force 绕过服务端缓存;仅管理员生效 */
|
|
|
|
|
|
check: (force = false): Promise<UpdateInfo> =>
|
|
|
|
|
|
api.get(`${API_PATHS.update}/check${force ? '?force=1' : ''}`),
|
|
|
|
|
|
};
|
2026-10-11 11:49:32 +08:00
|
|
|
|
|
|
|
|
|
|
/* ------------------------------------------------------------------ 权限组与用户权限 */
|
|
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
|
* 权限组管理(服务端 `modules/permissions`)。
|
|
|
|
|
|
*
|
|
|
|
|
|
* 权限生效规则:**有权限组时取各组的并集**(因此也能用来收回权限),
|
|
|
|
|
|
* 没有任何组时回落到角色默认模板;管理员固定拥有全集,班级端不受权限组影响。
|
|
|
|
|
|
*
|
|
|
|
|
|
* 除 `me` 之外,本组接口都要求当前账号有 `permission:manage`(否则服务端 403)。
|
|
|
|
|
|
*/
|
|
|
|
|
|
export const permissionApi = {
|
|
|
|
|
|
/** 当前账号的生效权限(任何登录账号都能读自己这一份) */
|
|
|
|
|
|
me: (): Promise<MyPermissionsDto> => api.get(`${API_PATHS.permissions}/me`),
|
|
|
|
|
|
/** 权限目录:全部键 / 中文名 / 分类 / 各键的默认角色 / 管理员不可剥夺的键 */
|
|
|
|
|
|
catalog: (): Promise<PermissionCatalogDto> => api.get(`${API_PATHS.permissions}/catalog`),
|
|
|
|
|
|
listGroups: (): Promise<PermissionGroupDto[]> => api.get(`${API_PATHS.permissions}/groups`),
|
|
|
|
|
|
createGroup: (payload: CreatePermissionGroupRequest): Promise<PermissionGroupDto> =>
|
|
|
|
|
|
api.post(`${API_PATHS.permissions}/groups`, payload),
|
|
|
|
|
|
/** `keys` 传了就**整体替换**该组的权限键(不传则保持原样) */
|
|
|
|
|
|
updateGroup: (id: string, payload: UpdatePermissionGroupRequest): Promise<PermissionGroupDto> =>
|
|
|
|
|
|
api.patch(`${API_PATHS.permissions}/groups/${id}`, payload),
|
|
|
|
|
|
/** 内置权限组不能删除(服务端会 400),调用前页面已经禁用了按钮 */
|
|
|
|
|
|
removeGroup: (id: string): Promise<{ id: string }> => api.delete(`${API_PATHS.permissions}/groups/${id}`),
|
|
|
|
|
|
/** 可分配权限的成员(管理员与教师;管理员是固定行,不能分配) */
|
|
|
|
|
|
listMembers: (): Promise<PermissionMemberDto[]> => api.get(`${API_PATHS.permissions}/users`),
|
|
|
|
|
|
/** 分配权限组:传空数组 = 回到角色默认模板 */
|
|
|
|
|
|
assignGroups: (userId: string, payload: AssignUserGroupsRequest): Promise<PermissionMemberDto> =>
|
|
|
|
|
|
api.put(`${API_PATHS.permissions}/users/${userId}/groups`, payload),
|
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
|
|
/* ------------------------------------------------------------------ 客户端设备(远控与版本管理) */
|
|
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
|
* 「客户端设备」页的接口。
|
|
|
|
|
|
*
|
|
|
|
|
|
* 权限(与后端 `clients.module.ts` 逐个对齐):
|
2026-10-17 03:06:46 +08:00
|
|
|
|
* - `list`:查看、设备管理、远控、更新任一权限;`remove`:`client:manage`
|
2026-10-11 11:49:32 +08:00
|
|
|
|
* - `commands`:`remote:control`(关机 / 重启 / 注销 / 锁屏,机器上还会再弹一次确认框)
|
|
|
|
|
|
* - `pushUpdate`:`client:update-push`
|
|
|
|
|
|
*/
|
|
|
|
|
|
export const clientApi = {
|
|
|
|
|
|
/** 设备列表(自动心跳上报产生的记录);`classId` 留空 = 全部班级 */
|
|
|
|
|
|
devices: (classId?: string): Promise<ClientDeviceDto[]> =>
|
|
|
|
|
|
api.get(`${API_PATHS.clients}/devices`, classId ? { classId } : undefined),
|
|
|
|
|
|
/**
|
|
|
|
|
|
* 下发远控命令。
|
|
|
|
|
|
*
|
|
|
|
|
|
* 同一台机器上未执行的旧命令会被服务端**自动撤销**(否则"先关机、后重启"会排队执行)。
|
|
|
|
|
|
*/
|
|
|
|
|
|
commands: (payload: CreateClientCommandRequest): Promise<ClientPushResult> =>
|
|
|
|
|
|
api.post(`${API_PATHS.clients}/commands`, payload),
|
|
|
|
|
|
/** 统一下发客户端更新:按设备 / 按班级 / 全部,或 `clear: true` 取消下发 */
|
|
|
|
|
|
pushUpdate: (payload: PushClientUpdateRequest): Promise<ClientPushResult> =>
|
|
|
|
|
|
api.post(`${API_PATHS.clients}/updates`, payload),
|
|
|
|
|
|
/** 移除一台设备记录(换机 / 旧机器清理;只删记录,不影响那台机器本身) */
|
|
|
|
|
|
removeDevice: (id: string): Promise<{ id: string }> => api.delete(`${API_PATHS.clients}/devices/${id}`),
|
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
|
|
/** GitHub 代下与「登记 → 校验 sha256」都可能要几十秒到几分钟,够长才不至于半路超时 */
|
|
|
|
|
|
const CLIENT_RELEASE_FETCH_TIMEOUT_MS = 10 * 60 * 1000;
|
|
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
|
* 客户端安装包缓存管理(服务端 `modules/update/client-releases.service.ts`)。
|
|
|
|
|
|
*
|
|
|
|
|
|
* 教室机器常常没有外网,所以安装包由**服务端替教室下载**再缓存:
|
2026-10-18 11:53:37 +08:00
|
|
|
|
* Web 端不直连 GitHub(CSP 的 connect-src 只放行 self 与 WebSocket,见 AGENTS.md 的现行工程约定)。
|
2026-10-11 11:49:32 +08:00
|
|
|
|
*
|
2026-10-17 03:06:46 +08:00
|
|
|
|
* 权限:`list` 要查看、设备管理或更新任一权限;`fetch` / `register` / `remove` 要 `client:update-push`。
|
2026-10-11 11:49:32 +08:00
|
|
|
|
*/
|
|
|
|
|
|
export const clientReleaseApi = {
|
|
|
|
|
|
/** 服务端已缓存的安装包列表 */
|
|
|
|
|
|
list: (): Promise<ClientReleaseDto[]> => api.get(`${API_PATHS.update}/client/releases`),
|
|
|
|
|
|
/**
|
|
|
|
|
|
* 让服务端从 GitHub 下载指定版本并登记。
|
|
|
|
|
|
*
|
|
|
|
|
|
* ⚠️ **必须显式放宽超时**:axios 实例默认 20 秒,而服务端自己允许下载 10 分钟
|
|
|
|
|
|
* (`client-releases.service.ts` 的 `FETCH_TIMEOUT_MS`)。用默认值会在服务端还在下载时
|
|
|
|
|
|
* 就报"请求超时",用户会以为失败而重复点。这里与服务端取同一个上限。
|
|
|
|
|
|
*/
|
|
|
|
|
|
fetch: (version: string): Promise<ClientReleaseDto> =>
|
2026-10-17 03:06:46 +08:00
|
|
|
|
api.post(`${API_PATHS.update}/client/fetch`, { version }, { timeout: CLIENT_RELEASE_FETCH_TIMEOUT_MS }),
|
2026-10-11 11:49:32 +08:00
|
|
|
|
/** 登记一份已经手工放进 `data/client-releases/<版本>/` 的安装包 */
|
|
|
|
|
|
register: (payload: { version: string; fileName?: string; notes?: string }): Promise<ClientReleaseDto> =>
|
|
|
|
|
|
api.post(`${API_PATHS.update}/client/releases`, payload),
|
|
|
|
|
|
/** 删除缓存(元数据 + 磁盘文件) */
|
|
|
|
|
|
remove: (version: string): Promise<{ version: string }> =>
|
|
|
|
|
|
api.delete(`${API_PATHS.update}/client/releases/${encodeURIComponent(version)}`),
|
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
|
|
/* ------------------------------------------------------------------ 大模型助手 */
|
|
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
|
* 大模型助手的接口前缀(取自共享契约 `API_PATHS.ai`,与服务端 `modules/ai` 的挂载点同源)。
|
|
|
|
|
|
*/
|
|
|
|
|
|
const AI_BASE = API_PATHS.ai;
|
|
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
|
* 大模型助手(服务端 `modules/ai`)。
|
|
|
|
|
|
*
|
|
|
|
|
|
* 权限:`settings` / `audit` 要 `ai:manage`(仅管理员);`interpret` 要 `ai:use`(教师也有)。
|
|
|
|
|
|
*
|
2026-11-07 16:27:38 +08:00
|
|
|
|
* 解释和附件预览只保存计划与审计;确认后由绑定的原业务接口执行写入。
|
2026-10-11 11:49:32 +08:00
|
|
|
|
*/
|
|
|
|
|
|
export const aiApi = {
|
2026-11-07 22:25:39 +08:00
|
|
|
|
tasks: (): Promise<AiTaskDto[]> => api.get(`${AI_BASE}/tasks`),
|
|
|
|
|
|
task: (id: string): Promise<AiTaskDto> => api.get(`${AI_BASE}/tasks/${id}`),
|
|
|
|
|
|
createTask: (payload: AiConversationRequest): Promise<{ id: string }> =>
|
|
|
|
|
|
api.post(`${AI_BASE}/tasks`, payload),
|
|
|
|
|
|
startTask: (id: string): Promise<null> => api.post(`${AI_BASE}/tasks/${id}/start`),
|
|
|
|
|
|
stopTask: (id: string): Promise<null> => api.post(`${AI_BASE}/tasks/${id}/stop`),
|
|
|
|
|
|
executeTask: (
|
|
|
|
|
|
id: string,
|
|
|
|
|
|
body: {
|
|
|
|
|
|
confirmed: true;
|
|
|
|
|
|
extraConfirmed?: boolean;
|
|
|
|
|
|
urgentConfirmed?: boolean;
|
|
|
|
|
|
secrets?: Record<string, Record<string, string>>;
|
|
|
|
|
|
},
|
|
|
|
|
|
): Promise<null> => api.post(`${AI_BASE}/tasks/${id}/execute`, body),
|
|
|
|
|
|
models: (payload: { baseUrl?: string; apiKey?: string }): Promise<AiModelInfo[]> =>
|
|
|
|
|
|
api.post(`${AI_BASE}/models`, payload),
|
2026-10-11 11:49:32 +08:00
|
|
|
|
/**
|
|
|
|
|
|
* 读取配置。
|
|
|
|
|
|
*
|
|
|
|
|
|
* 只有 `ai:manage` 能读(教师读会 403,而响应拦截器会弹一个错误提示),
|
|
|
|
|
|
* 所以助手页**不要**无条件调它——教师侧靠"探测式":直接尝试解析,
|
|
|
|
|
|
* 服务端回了 `AI_NOT_CONFIGURED` 再切空态。
|
|
|
|
|
|
*/
|
|
|
|
|
|
settings: (): Promise<AiSettingsDto> => api.get(`${AI_BASE}/settings`),
|
|
|
|
|
|
/**
|
|
|
|
|
|
* 保存配置。
|
|
|
|
|
|
*
|
|
|
|
|
|
* `apiKey` 的三种语义(服务端约定):传字符串 = 换新、传 `null` = 清除、**不传 = 保持原样**。
|
|
|
|
|
|
* 因此"留空表示不修改"时不要往 body 里塞 `apiKey: ''`,那会被当成一个空密钥。
|
|
|
|
|
|
*/
|
|
|
|
|
|
updateSettings: (payload: UpdateAiSettingsRequest): Promise<AiSettingsDto> =>
|
|
|
|
|
|
api.put(`${AI_BASE}/settings`, payload),
|
|
|
|
|
|
/** 把一句话解析成待确认的操作;`text` 上限 500 字(超出由服务端 400) */
|
2026-11-07 16:27:38 +08:00
|
|
|
|
interpret: (
|
|
|
|
|
|
payload: AiConversationRequest,
|
|
|
|
|
|
signal?: AbortSignal,
|
|
|
|
|
|
): Promise<AiInterpretResult & AiConversationResult> =>
|
|
|
|
|
|
api.post(`${AI_BASE}/interpret`, payload, { timeout: 120000, signal }),
|
|
|
|
|
|
capabilities: (): Promise<AiCapability[]> => api.get(`${AI_BASE}/capabilities`),
|
|
|
|
|
|
plan: (id: string): Promise<AiPlanStep[]> => api.get(`${AI_BASE}/plans/${id}`),
|
|
|
|
|
|
prepare: (
|
|
|
|
|
|
id: string,
|
|
|
|
|
|
files: Record<string, { contentBase64: string }>,
|
|
|
|
|
|
mappings?: Record<string, Record<string, string>>,
|
|
|
|
|
|
): Promise<AiPlanStep[]> => api.post(`${AI_BASE}/plans/${id}/prepare`, { files, mappings }),
|
|
|
|
|
|
confirm: (
|
|
|
|
|
|
id: string,
|
|
|
|
|
|
body: {
|
|
|
|
|
|
confirmed: true;
|
|
|
|
|
|
extraConfirmed?: boolean;
|
|
|
|
|
|
urgentConfirmed?: boolean;
|
|
|
|
|
|
secrets?: Record<string, Record<string, string>>;
|
|
|
|
|
|
},
|
|
|
|
|
|
): Promise<AiPlanStep[]> => api.post(`${AI_BASE}/plans/${id}/confirm`, body),
|
|
|
|
|
|
discard: (id: string): Promise<null> => api.delete(`${AI_BASE}/plans/${id}`),
|
2026-10-11 11:49:32 +08:00
|
|
|
|
/** 使用记录(谁、什么时候、说了什么、解析成什么、结果如何),倒序 */
|
|
|
|
|
|
audit: (limit = 50): Promise<AiAuditDto[]> => api.get(`${AI_BASE}/audit`, { limit }),
|
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
|
|
/* ------------------------------------------------------------------ 系统设置与诊断 */
|
|
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
|
* 系统设置与诊断(服务端 `modules/system`),全部要 `system:manage`(仅管理员)。
|
|
|
|
|
|
*/
|
|
|
|
|
|
const SYSTEM_BASE = API_PATHS.system;
|
|
|
|
|
|
|
|
|
|
|
|
export const systemApi = {
|
|
|
|
|
|
settings: (): Promise<SystemSettingsDto> => api.get(`${SYSTEM_BASE}/settings`),
|
|
|
|
|
|
/** 目前只有 `developerMode` 一项;保存后服务端返回完整设置 */
|
|
|
|
|
|
updateSettings: (payload: Partial<SystemSettingsDto>): Promise<SystemSettingsDto> =>
|
|
|
|
|
|
api.put(`${SYSTEM_BASE}/settings`, payload),
|
|
|
|
|
|
/** 只读诊断信息(版本 / Node / 平台 / 运行时长 / 数据库 / 目录 / 模块数) */
|
|
|
|
|
|
diagnostics: (): Promise<SystemDiagnosticsDto> => api.get(`${SYSTEM_BASE}/diagnostics`),
|
|
|
|
|
|
};
|