교실 QR 자리선택 준비

Teacher Flow

선생님용 빠른 흐름

1. 명단 넣기

CSV/엑셀을 열거나 표를 붙여넣은 뒤 명단 반영만 누르면 됩니다.

2. 순번 정리

우선 대상 자동 채우기와 나머지 자동 채우기로 대부분 바로 끝낼 수 있습니다.

3. QR 배포

세션 JSON 저장 후 실시간 세션 만들기로 바로 학생 링크와 QR을 만듭니다.

1. Roster

학생 명단 넣기

가장 추천

CSV/엑셀 파일 열기

CSV는 바로 읽고, 엑셀 파일도 첫 번째 시트를 바로 불러올 수 있습니다.

엑셀 바로 사용

표 복사 후 붙여넣기

엑셀 표를 그대로 복사해서 아래 입력칸에 붙여넣어도 됩니다. 탭 구분 표를 읽습니다.

처음 시작

샘플 양식 받기

이름,별점,선택순번,청소면제 형식의 샘플 CSV를 내려받아 바로 편집할 수 있습니다.

CSV 또는 엑셀 표 붙여넣기

바로 읽는 파일 형식은 .csv, .txt, .tsv, .xlsx, .xls 입니다. .numbers는 표를 복사해서 붙여넣거나 CSV로 저장해 주세요. 지원 열은 이름, 별점, 선택순번, 학급도우미, 전화번호, 이메일, 청소면제, 특별구역, 청소넘김, 다음청소페널티, 청소횟수 입니다.

이름만 붙여넣어도 되고, 이름,별점,선택순번,전화번호,이메일,청소면제 CSV나 엑셀 표 붙여넣기, 엑셀 파일 열기도 됩니다.

2. Order

학생 순번 정하기

자리 선택 우선 최소 별점 우선 대상 외 자동 채우기 학생이 자기 차례를 정해진 횟수만큼 넘길 수 있게 허용 학생 스킵 가능 횟수 학생이 스스로 랜덤 자리 선택 가능

최고 별점보다 1 높은 값까지 둘 수 있습니다. 그렇게 두면 우선 학생 없이 전체를 랜덤 또는 수동으로 시작할 수 있습니다. `수동으로 정하기`가 아니면 기준 미만 학생은 자리 QR을 받지 않고, 선택 종료 뒤 자동 배치됩니다.

순번은 1번부터 연속이어야 합니다. 우선 대상 자동 채우기는 설정한 최소 별점 이상 학생부터 채우고, 나머지 자동 채우기는 수동/별점/랜덤 방식에 맞춰 뒤 순번을 채웁니다. QR 순번이 없는 학생은 학생 선택이 끝난 뒤 같은 규칙으로 자동 배치됩니다.

3. Seats

사용할 좌석만 켜 두기

학생이 직접 고를 좌석판입니다. 쓰지 않을 좌석은 클릭해서 끄고, 자리 배치를 바꾸고 싶으면 격자 보기에서는 좌석 카드를 다른 자리 위로 끌어 놓고, 자유 배치를 켜면 교실 안 원하는 위치로 좌석을 직접 끌어 놓을 수 있습니다. 아래 교탁 쪽 맨 앞줄이 1-1부터 시작합니다.

초록색은 사용, 회색은 사용 안 함입니다.

4. Cleaning

청소표 만들기

청소 선택 우선 최소 별점 우선 대상 외 배정 방식 학급도우미는 청소에서 제외 특별구역 학생은 일반 청소에서 제외 청소 선택 학생이 자기 차례를 정해진 횟수만큼 넘길 수 있게 허용 청소 학생 스킵 가능 횟수 청소 선택 학생이 스스로 랜덤 요일/구역 선택 가능

청소도 자리배치처럼 우선 학생이 먼저 요일과 역할을 고르고, 기준 미만 학생은 남은 칸을 수동/별점/랜덤 방식으로 자동 배치합니다.

청소는 요일마다 6명씩 배정합니다. 우선 학생은 별점순으로 먼저 칸을 고르고, 나머지는 교사가 채웁니다. 학생 1명은 한 구역만 맡고, 청소를 넘긴 학생은 확정할 때 다음 차례용 별점 페널티가 예약됩니다.

청소 후보

0명

이번 배정

0명

청소 상태

생성 전

청소 후보가 준비되면 월요일부터 금요일까지 6명씩 한 조로 청소표를 만들 수 있습니다.

5. Export

바로 실시간 세션 만들기

QR 대상 학생

0명

자동 배치 학생

0명

사용 좌석

36석

QR 준비 상태

준비 전

세션 이름 학생이 코드 뒤에 PIN까지 입력하도록 하기

Mail Template

반별 안내 문구와 발송 상태

자리 메일 제목 템플릿

바로 쓸 수 있는 변수

{sessionName} {sessionCode} {studentName} {studentLabel} {studentCode} {studentPin} {studentUrl} {sessionCodeLine} {studentCodeLine} {studentPinLine} {studentUrlLine}

자리 메일 본문 템플릿

청소 메일 제목 템플릿

자리/청소 공통 변수

{sessionName} {sessionCode} {studentName} {studentLabel} {studentCode} {studentPin} {studentUrl} {sessionCodeLine} {studentCodeLine} {studentPinLine} {studentUrlLine}

청소 메일 본문 템플릿

자리와 청소 모두 메일 CSV를 저장할 수 있고, Google Sheets에서 발송 후 내려받은 CSV를 다시 불러오면 학생 카드에 발송 완료, 미발송, 오류 상태가 반영됩니다.

보안을 더 높이려면 {studentPin} 또는 {studentPinLine}은 메일 본문에 넣지 말고, 필요하면 학생에게 따로 알려 주세요. 같은 메일에 링크와 PIN을 함께 넣으면 보호 효과가 줄어듭니다.

Auto Send

Gmail 자동 발송 연결

Apps Script 웹앱 URL 웹앱 비밀키

비밀키는 이제 이 브라우저의 현재 탭에만 임시로 보관됩니다. 웹앱 URL은 https://script.google.com/macros/s/.../exec 주소만 사용하세요.

Apps Script 웹앱 URL과 비밀키를 넣으면, 자리 세션과 청소 세션의 미발송 메일을 이 화면에서 바로 보낼 수 있습니다.

이 화면에서 Gmail 자동 발송 안내와 스크립트 보기

1. 비밀키 만들기

위의 비밀키 만들기를 눌러 값을 만든 뒤, 아래 스크립트의 WEBHOOK_SECRET 자리에 같은 값을 넣습니다.

2. Google Apps Script 붙여넣기

새 구글 스프레드시트에서 확장 프로그램 → Apps Script를 연 뒤, 기본 코드를 모두 지우고 아래 스크립트를 붙여넣습니다.

3. 웹앱으로 배포하기

배포 → 새 배포 → 웹 앱에서 실행 사용자: 나로 배포한 뒤, 나온 웹앱 URL을 이 화면의 Apps Script 웹앱 URL 칸에 넣습니다.

4. 연결 점검 후 자동 발송

연결 점검이 성공하면 자리 QR 세션 또는 청소 QR 세션을 만든 상태에서 각 버튼으로 바로 자동 발송하면 됩니다.

붙여넣을 Apps Script

const WEBHOOK_SECRET = "PASTE_YOUR_WEBAPP_SECRET";
const RESULT_TYPE = "classroom-planner-mail-automation-result";

function doPost(e) {
  const payload = parsePayload_(e);
  const requestId = String(payload.requestId || "");
  const action = String(payload.action || "").trim();
  const returnOrigin = normalizeReturnOrigin_(payload.returnOrigin);

  try {
    if (!WEBHOOK_SECRET || WEBHOOK_SECRET === "PASTE_YOUR_WEBAPP_SECRET") {
      throw new Error("WEBHOOK_SECRET를 먼저 바꿔 주세요.");
    }
    if (String(payload.secret || "").trim() !== WEBHOOK_SECRET) {
      throw new Error("비밀키가 맞지 않습니다.");
    }

    if (action === "ping") {
      return buildResultPage_(
        {
          type: RESULT_TYPE,
          requestId,
          action,
          ok: true,
          message: `연결 확인 완료: ${Session.getEffectiveUser().getEmail() || "현재 Google 계정"}`,
          summary: {
            sentCount: 0,
            errorCount: 0,
            skippedCount: 0,
            remainingQuota: MailApp.getRemainingDailyQuota(),
          },
          rows: [],
        },
        returnOrigin
      );
    }

    if (action !== "send_selection_emails") {
      throw new Error(`지원하지 않는 action입니다: ${action}`);
    }

    const mails = Array.isArray(payload.mails) ? payload.mails : [];
    if (!mails.length) {
      throw new Error("보낼 메일이 없습니다.");
    }

    const remainingQuota = MailApp.getRemainingDailyQuota();
    let sentCount = 0;
    let errorCount = 0;
    let skippedCount = 0;

    const rows = mails.map((mail) => {
      const emailAddress = String(mail.emailAddress || "").trim();
      const mailSubject = String(mail.mailSubject || "").trim() || "교실 QR 안내";
      const mailBody = String(mail.mailBody || "").trim();
      const studentUrl = String(mail.studentUrl || "").trim();
      const baseRow = {
        studentId: String(mail.studentId || "").trim(),
        selectionOrder: Number(mail.selectionOrder || 0),
        studentName: String(mail.studentName || "").trim(),
        emailAddress,
        sentAt: "",
      };

      if (!emailAddress || !mailBody) {
        skippedCount += 1;
        return {
          ...baseRow,
          status: "skipped",
        };
      }

      if (sentCount >= remainingQuota) {
        skippedCount += 1;
        return {
          ...baseRow,
          status: "quota_exceeded",
        };
      }

      try {
        MailApp.sendEmail({
          to: emailAddress,
          subject: mailSubject,
          body: buildPlainTextBody_(mailBody, studentUrl),
          htmlBody: buildHtmlBody_(mailBody, studentUrl),
        });

        sentCount += 1;
        return {
          ...baseRow,
          status: "sent",
          sentAt: new Date().toISOString(),
        };
      } catch (error) {
        errorCount += 1;
        return {
          ...baseRow,
          status: "error",
          sentAt: "",
          message: String(error && error.message ? error.message : error),
        };
      }
    });

    return buildResultPage_(
      {
        type: RESULT_TYPE,
        requestId,
        action,
        ok: true,
        message: `자동 발송을 마쳤습니다. 발송 ${sentCount}건, 건너뜀 ${skippedCount}건, 오류 ${errorCount}건입니다.`,
        summary: {
          sentCount,
          errorCount,
          skippedCount,
          remainingQuota: Math.max(remainingQuota - sentCount, 0),
        },
        rows,
      },
      returnOrigin
    );
  } catch (error) {
    return buildResultPage_(
      {
        type: RESULT_TYPE,
        requestId,
        action,
        ok: false,
        message: String(error && error.message ? error.message : error),
        summary: {
          sentCount: 0,
          errorCount: 0,
          skippedCount: 0,
          remainingQuota: MailApp.getRemainingDailyQuota(),
        },
        rows: [],
      },
      returnOrigin
    );
  }
}

function parsePayload_(e) {
  const parameterPayload = e && e.parameter && e.parameter.payload ? String(e.parameter.payload) : "";
  if (parameterPayload) {
    return JSON.parse(parameterPayload);
  }

  const raw = e && e.postData && e.postData.contents ? String(e.postData.contents) : "{}";
  const parsed = JSON.parse(raw);
  if (parsed && typeof parsed === "object" && parsed.payload) {
    return JSON.parse(String(parsed.payload));
  }
  return parsed;
}

function buildResultPage_(result, returnOrigin) {
  const safeJson = JSON.stringify(result)
    .replace(/</g, "\\u003c")
    .replace(/>/g, "\\u003e");
  const safeOrigin = JSON.stringify(returnOrigin || "*");
  const summary = escapeHtml_(String(result.message || "요청을 처리했습니다."));

  const html = `
<!doctype html>
<html lang="ko">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>교실 QR Gmail 자동 발송</title>
    <style>
      body { font-family: Arial, "Apple SD Gothic Neo", "Noto Sans KR", sans-serif; padding: 24px; line-height: 1.6; color: #1f2b2c; }
      .card { padding: 20px; border-radius: 18px; border: 1px solid #d8e2df; background: #ffffff; max-width: 640px; margin: 0 auto; }
      h1 { margin-top: 0; font-size: 1.3rem; }
      p { margin: 0; }
      .meta { margin-top: 12px; color: #627273; font-size: 0.92rem; }
    </style>
  </head>
  <body>
    <div class="card">
      <h1>${result.ok ? "Gmail 자동 발송 완료" : "Gmail 자동 발송 오류"}</h1>
      <p>${summary}</p>
      <p class="meta">이 창은 잠시 뒤 자동으로 닫힙니다. 닫히지 않으면 직접 닫아도 됩니다.</p>
    </div>
    <script>
      const result = ${safeJson};
      const targetOrigin = ${safeOrigin};
      try {
        if (window.opener && typeof window.opener.postMessage === "function") {
          window.opener.postMessage(result, targetOrigin || "*");
        }
      } catch (error) {}
      window.setTimeout(() => {
        try {
          window.close();
        } catch (error) {}
      }, 400);
    </script>
  </body>
</html>`;

  return HtmlService.createHtmlOutput(html);
}

function buildPlainTextBody_(body, url) {
  return [body, "", url ? `링크: ${url}` : ""].filter(Boolean).join("\n");
}

function buildHtmlBody_(body, url) {
  const escapedBody = escapeHtml_(body).replace(/\n/g, "<br />");
  const button = url
    ? `<p><a href="${escapeAttribute_(url)}" style="display:inline-block;padding:12px 18px;border-radius:999px;background:#1f5c4d;color:#ffffff;text-decoration:none;font-weight:700;">자리 선택 열기</a></p>`
    : "";

  return [
    '<div style="font-family:Arial,Apple SD Gothic Neo,Noto Sans KR,sans-serif;line-height:1.7;color:#1f2b2c;">',
    `<p>${escapedBody}</p>`,
    button,
    url ? `<p style="font-size:12px;color:#627273;word-break:break-all;">${escapeHtml_(url)}</p>` : "",
    "</div>",
  ].join("");
}

function normalizeReturnOrigin_(value) {
  const text = String(value || "").trim();
  if (!text || text === "null") {
    return "*";
  }
  return text;
}

function escapeHtml_(value) {
  return String(value || "")
    .replace(/&/g, "&")
    .replace(/</g, "<")
    .replace(/>/g, ">")
    .replace(/"/g, """);
}

function escapeAttribute_(value) {
  return escapeHtml_(value);
}

`realtime-config.js`가 준비되면 이 화면에서 곧바로 실시간 세션을 만들고 QR까지 볼 수 있습니다.

현재 요약

자리 QR은 `QR 대상 학생`에게만 만들어집니다. `자동 배치 학생`은 QR 없이 선택 종료 뒤 랜덤/규칙 배정됩니다.

예전 방식으로 JSON 저장하기

qr-setup 열기 청소 세션 만들기

선생님이 명단만 올리면 거의 바로 QR을 만들 수 있게