85 lines
3.7 KiB
Markdown
85 lines
3.7 KiB
Markdown
# CogMind (web)
|
|
|
|
문제를 풀고 **확신도**를 함께 기록하면, AI가 "안다고 착각한 개념"을 짚어 주는 메타인지 학습 서비스입니다.
|
|
|
|
API 키: [Google AI Studio](https://aistudio.google.com/apikey)
|
|
|
|
## 화면 주소
|
|
|
|
History API 로 화면마다 주소를 갖습니다. 브라우저 뒤로/앞으로 가기가 그대로 동작하고,
|
|
주소를 직접 열거나 새로고침해도 같은 화면이 뜹니다 (`server.ts` 의 SPA 폴백).
|
|
|
|
| 주소 | 화면 |
|
|
| --- | --- |
|
|
| `/` | 시작 화면 |
|
|
| `/quiz/3` | 풀고 있는 시험의 3번 문제 (문항마다 뒤로가기 한 단계) |
|
|
| `/tests/:id` | 시험 결과 리포트 — 새로고침·공유 가능 |
|
|
| `/history` | 지난 기록 목록 |
|
|
|
|
진행 중인 시험은 메모리에만 있으므로, 새로고침한 뒤의 `/quiz/*` 는 시작 화면으로 보냅니다.
|
|
|
|
## 서버 API
|
|
|
|
| 엔드포인트 | 설명 |
|
|
| --- | --- |
|
|
| `GET /api/chapters` | `chapter.json` (학교 종류 → 과목 → 단원) |
|
|
| `POST /api/questions` | `{ school, subject, chapter, difficulty, amount }` → 문항 생성 |
|
|
| `POST /api/tests` | 시험 결과 저장 → 저장된 기록 전체 반환 |
|
|
| `GET /api/tests` | 기록 목록 (요약) |
|
|
| `GET /api/tests/:id` | 기록 상세 |
|
|
| `POST /api/tests/:id/feedback` | 메타인지 평가·학습 추천 생성 후 기록에 저장 |
|
|
| `POST /api/tests/:id/questions/:index/explain` | 해설 생성 후 해당 문항에 저장 |
|
|
| `POST /api/tests/:id/questions/:index/twin` | 쌍둥이 문제 생성 후 해당 문항의 `children` 에 추가 |
|
|
| `POST /api/tests/:id/questions/:index/ask` | 해설에 이어지는 후속 질문. 질문·답변을 `conversation` 에 추가 |
|
|
|
|
해설과 피드백은 한 번 만들어지면 그대로 재사용합니다(중복 호출 시 저장된 값 반환).
|
|
실패 시 `4xx/502` 와 `{ error }` 를 돌려줍니다.
|
|
|
|
## 기록 저장 형식
|
|
|
|
기록은 `data/history.json` 한 파일에 배열로 쌓입니다 (`.gitignore` 대상).
|
|
|
|
```jsonc
|
|
{
|
|
"id": "msmjphyx-xj7nbf",
|
|
"createdAt": "2026-08-10T01:21:13.785Z",
|
|
"student": "김민준",
|
|
"school": "고등학교", "subject": "수학", "chapter": "도함수",
|
|
"difficulty": "medium",
|
|
"score": { "total": 3, "correct": 2, "percent": 67,
|
|
"overconfident": 1, "lucky": 1, "solid": 1 },
|
|
"feedback": { "summary": "...", "detail": "...", "recommendation": "..." },
|
|
"questions": [
|
|
{
|
|
"question": "...", "correct_answer": "...", "incorrect_answers": ["..."],
|
|
"user_answer": "...", "confidence": "sure", "is_correct": false,
|
|
"explanation": "AI 해설 (key/value)",
|
|
"conversation": [ // 해설에 이어서 주고받은 질문·답변
|
|
{ "role": "user", "content": "왜 그런가요?", "createdAt": "..." },
|
|
{ "role": "assistant", "content": "...", "createdAt": "..." }
|
|
],
|
|
"children": [ // 쌍둥이 문제
|
|
{ "question": "...", "correct_answer": "...",
|
|
"incorrect_answers": ["..."], "createdAt": "..." }
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## 구조
|
|
|
|
```
|
|
server.ts express 서버 + Gemini 호출
|
|
store.ts data/history.json 기반 기록 저장소
|
|
chapter.json 학교 종류 → 과목 → 단원
|
|
public/index.html 앱 셸
|
|
public/images/ logo-light.png (밝은 테마) · logo-dark.png (어두운 테마)
|
|
public/main.css 디자인 토큰과 스타일 (라이트/다크 자동)
|
|
public/main.js 상태, 서버 통신, 화면 전환
|
|
public/report.js 리포트 렌더러 (결과 화면과 기록 상세가 공용)
|
|
public/optionPage.js 시작 화면 (<option-page>)
|
|
public/testPage.js 퀴즈 화면 (<test-page>)
|
|
public/historyPage.js 지난 기록 목록 (<history-page>)
|
|
```
|