Skip to content

course-authoring.md

Latest commit

 

History

History
197 lines (148 loc) · 7.21 KB

course-authoring.md

File metadata and controls

197 lines (148 loc) · 7.21 KB
Raw

Study Builder 강의 자료 제작 방법

Spring Boot 강의는 원문, 문서 구조, 실습, 시작 템플릿을 분리해 관리합니다. 앱이 사용하는 파일을 직접 수정하지 말고 아래 원본을 고친 뒤 생성 명령을 실행합니다.

1. 강의 위키 작성

원문 폴더:

resources/course-sources/spring-course/notion/

현재 16개 문서는 2026-07-31에 가져온 Notion의 일회성 스냅샷입니다. 앱 실행 중 Notion을 다시 읽지 않으므로 배포 뒤에도 같은 내용을 안정적으로 보여 줍니다.

원문은 UTF-8 Markdown으로 작성합니다.

## 학습 목표

사용자가 이 페이지에서 이해할 내용을 자연스러운 문장으로 설명합니다.

## 핵심 개념

- 개념과 이유를 먼저 설명합니다.
- 단순한 명령 목록보다 요청이 흐르는 순서를 보여 줍니다.

```java
// 실행 가능한 예제
```

지원 형식은 ##~#### 제목, 문단, 목록, 인용문, 코드 블록, 링크입니다. Notion에서 가져온 표는 <table><tr><td>...</td></tr></table> 형식을 유지합니다.

문서의 제목과 부모·자식 관계는 다음 파일에서 관리합니다.

resources/course-sources/spring-course/course-manifest.json

문서를 추가할 때는 다음 값을 지정합니다.

  • id: 앱 내부에서 변하지 않는 고유 ID
  • parentId: 상위 문서 ID, 최상위 문서는 null
  • order: 전체 읽기 순서
  • sourceFile: 원문 폴더 기준 경로
  • title, chapterLabel, objective, readingMinutes
  • practiceUnitIds: 이 문서에 연결된 실습 ID

원문을 수정한 뒤 생성합니다.

npm run build:course

이 명령은 Renderer용 콘텐츠, Electron seed, 검색 텍스트, 실습 명령 allowlist와 content-map.json을 함께 만듭니다. 다음 생성 파일은 직접 편집하지 않습니다.

src/course/
electron/storage/spring-course-seed.ts
electron/terminal/course-approved-commands.ts
electron/storage/course-practice.ts
public/course-assets/

배포 학습서는 모두 읽기 전용입니다. 앱 안에서는 강의 원문을 추가·수정·삭제하지 않으며, 저자는 이 source 폴더와 manifest를 바꾼 뒤 다시 빌드합니다. 이전 버전에서 수정된 사용자 데이터는 마이그레이션할 때 원본을 잃지 않도록 별도 문서로 보존합니다.

2. 실습 단계 만들기

파일:

resources/course-sources/spring-course/practice-manifest.json

실습은 Chapter 수가 아니라 사용자가 한 번에 확인할 수 있는 기능 단위로 나눕니다.

{
  "version": 3,
  "units": [{
    "id": 19,
    "unitId": "spring-practice-19",
    "pageId": "spring-chapter-06",
    "sectionHeading": "소유자 권한 검사",
    "chapter": "Chapter 06",
    "title": "소유자 인가 확인",
    "heading": "다른 사용자의 수정을 거부하세요",
    "objective": "인증과 리소스 인가를 구분합니다.",
    "concepts": ["Authentication", "ownerId", "403"],
    "task": ["검사 위치를 찾습니다.", "실패 테스트를 작성합니다."],
    "check": ["401과 403을 설명할 수 있습니다."],
    "deliverable": "Study 소유자 인가 계약",
    "requirements": [
      "Controller가 인증 사용자의 userId를 Service에 전달합니다.",
      "Service가 변경 전에 Study ownerId와 userId를 비교합니다."
    ],
    "acceptance": [
      "본인 수정은 성공하고 다른 사용자의 수정은 HTTP 403입니다.",
      "인증되지 않은 401과 권한이 없는 403을 구분합니다."
    ],
    "file": "src/main/java/com/ducami/studymate/domain/study/service/StudyService.java",
    "verification": {
      "kind": "command",
      "commandId": "practice-19-test",
      "display": "./gradlew test --tests '*StudyAuthorizationTest'",
      "executable": "./gradlew",
      "args": ["test", "--tests", "*StudyAuthorizationTest"]
    }
  }]
}
  • pageId는 course-manifest.json의 실제 문서 ID여야 합니다.
  • sectionHeading은 해당 원문의 실제 제목과 일치해야 합니다.
  • file은 Workspace 기준 상대 경로만 사용합니다.
  • deliverable은 사용자가 이번 단계에서 완성할 API, Entity, Service 또는 확인 기록을 한 문장으로 적습니다.
  • requirements에는 Endpoint와 HTTP method, Request·Response 필드, 테이블·컬럼·자료형, Service 동작처럼 구현 전에 알아야 할 계약을 최소 두 개 적습니다.
  • acceptance에는 성공·실패 결과와 상태 코드, 저장 여부처럼 테스트로 판정할 완료 기준을 최소 두 개 적습니다.
  • display, executable, args는 정확히 일치하는 명령만 승인됩니다.
  • command 실습은 명령이 성공해야 완료됩니다.
  • observation 실습은 체크리스트를 확인하고 명령을 실행한 뒤 노트를 저장해야 완료됩니다.
  • 화면 이동이나 단계 클릭만으로는 완료되지 않습니다.

3. Spring Boot 시작 템플릿 만들기

원본 폴더:

resources/template-sources/spring-boot-rest/

이 폴더는 사용자가 선택한 빈 Workspace에 복사됩니다. 완성된 강의 답안이 아니라 Spring Initializr에서 받은 시작 프로젝트 수준을 유지합니다.

필수 파일:

.study-builder-template.json
build.gradle
settings.gradle
gradlew
gradlew.bat
gradle/wrapper/*
src/main/java/.../StudymateApplication.java
src/main/resources/application.yaml
src/test/java/.../StudymateApplicationTests.java
docs/LEARNING.md

템플릿을 바꾼 뒤 ZIP을 다시 만듭니다.

npm run build:templates

생성된 resources/templates/spring-boot-rest.zip은 직접 수정하지 않습니다. 완성 예시는 resources/reference-sources/studymate-complete/에만 두며 사용자 Workspace에는 복사하지 않습니다.

4. 별도 읽기 자료 Markdown 만들기

강의 배포와 무관한 읽기 자료도 source와 manifest에 등록해 배포합니다. 현재 상용 UI는 런타임 Markdown 가져오기나 사용자 편집 기능을 노출하지 않습니다.

# 나의 Spring 메모

## 확인할 내용

직접 정리한 설명입니다.

```java
class Example {}
```

[Spring Boot 공식 문서](https://spring.io/projects/spring-boot)

파일은 UTF-8 Markdown으로 저장하고, 빌드 전 repository에 API Key나 개인 정보가 포함되지 않았는지 확인합니다.

5. 검증

npm run build:course
npm run build:templates
npm run typecheck
npm run test
npm run build:desktop
npm run test:e2e

수동으로 다음을 확인합니다.

  1. 16개 문서가 부모·자식 목차로 표시되고 본문 검색이 동작합니다.
  2. 배포 학습서는 읽기 전용이며 추가·수정 UI가 노출되지 않습니다.
  3. 실습 CTA는 연결된 본문 절에만 나타납니다.
  4. 18개 실습은 실행 또는 관찰 증거가 있어야 완료됩니다.
  5. 빈 폴더에 시작 템플릿을 만든 뒤 파일 저장, 터미널 실행, Workspace 재시작 복원이 동작합니다.
  6. 이미지·내부 문서 링크·외부 HTTPS 링크가 깨지지 않습니다.

자료 묶음에는 API Key, .env, 실제 DB, 인증서, build/, .gradle/, userData를 포함하지 않습니다.