✨ 特性

• 🪶 轻量 —— 压缩后小于 5 KB，零运行时依赖
• 🔒 严格类型 —— 每个实体、每个约束、每个结果都有类型
• ⚡ 异步友好 —— 全面 Promise 化，长耗时求解自动轮询
• 🌐 通用 —— 支持 Node.js 18+ 与现代浏览器
• 🛡️ 安全 —— 抛出结构化错误，附带 HTTP 状态码、错误码与请求 ID

📦 安装

npm install @classflow-api/sdk
# or
pnpm add @classflow-api/sdk
# or
yarn add @classflow-api/sdk

🚀 快速开始

import { ClassFlow } from '@classflow-api/sdk';

const cf = new ClassFlow({ apiKey: 'cf_your_api_key' });

const result = await cf.schedule({
  timeSlots: [
    { id: 'mon-1', day: 'monday', period: 1 },
    { id: 'mon-2', day: 'monday', period: 2 },
  ],
  courses: [
    { id: 'math', name: 'Mathematics', teacherId: 't1', studentCount: 30, requiredSlots: 5 },
  ],
  teachers: [
    { id: 't1', name: 'Ms. Chen', availableSlots: ['mon-1', 'mon-2'] },
  ],
  rooms: [
    { id: 'r1', name: 'Room 101', capacity: 35, features: [] },
  ],
  constraints: ['time_conflict', 'room_capacity', 'teacher_availability'],
});

console.log(`Score: ${result.metrics.score}`);
console.log(`Conflicts: ${result.metrics.conflictCount}`);
console.log(`Assignments: ${result.assignments.length}`);

💡 常用操作

老师缺勤时查找替课老师

const candidates = await cf.findSubstitutes({
  absentTeacherId: 't1',
  absentDay: 'monday',
  currentAssignments: result.assignments,
  timeSlots, courses, rooms, teachers,
  constraints: ['time_conflict'],
});

for (const c of candidates) {
  console.log(`${c.teacherName}: covers ${c.coverableClasses}/${c.totalClassesToCover}`);
}

查询可用性

const availability = await cf.queryAvailability({
  currentAssignments: result.assignments,
  timeSlots, rooms, teachers,
  days: ['wednesday'],
  requiredFeatures: ['lab'],
});

for (const entry of availability.freeRooms) {
  const names = entry.rooms.map(r => r.name).join(', ');
  console.log(`${entry.slot.day} P${entry.slot.period}: ${names}`);
}

求解前预检

const check = await cf.validate({ timeSlots, courses, teachers, rooms, constraints });
if (!check.feasible) {
  console.warn('Infeasible:', check.violations);
}

查看用量

const usage = await cf.usage();
console.log(`Plan: ${usage.plan}, used ${usage.consumed}/${usage.quota}`);

⚙️ 配置

const cf = new ClassFlow({
  apiKey: 'cf_…',
  baseUrl: 'https://api.classflow.dev',  // override for self-hosted / staging
  timeout: 30_000,                       // ms; default 60_000
  fetch: customFetch,                    // optional fetch impl
});

❗ 错误处理

import { ClassFlow, ClassFlowError } from '@classflow-api/sdk';

try {
  await cf.schedule(req);
} catch (err) {
  if (err instanceof ClassFlowError) {
    console.error(err.status, err.code, err.requestId, err.message);
  }
}

🛠️ 开发

git clone https://github.com/classflow-api/sdks.git
cd sdks/typescript
npm install
npm run build

📄 许可证

MIT

🔗 相关项目

• classflow-api/api —— 后端 API
• classflow-api/sdks —— 全部官方 SDK
• classflow-api/docs —— 开发者文档