LINKRIGHTS (링크라이츠)

이주배경청소년이 자신의 권리를 알고 → 할 수 있는 행동을 찾고 → 실제 도움을 받을 기관까지 연결되도록 돕는 권리정보 웹사이트입니다.

이 문서는 개발을 전공하지 않은 분이 사이트를 직접 운영·수정할 수 있도록 쓴 안내서입니다. 모르는 단어가 나오면 그 자리에서 쉬운 설명을 함께 적어두었습니다.

---

목차

1. 이 사이트는 무엇으로 만들어졌나요
2. 처음 한 번만 하는 준비 (설치)
3. 내 컴퓨터에서 사이트 실행하기
4. 환경변수와 OpenAI API 키 설정
5. 콘텐츠 수정 방법 (가장 자주 하는 일)
6. 권리정보 새로 추가하기
7. 기관 정보 수정하기
8. 이미지 넣고 바꾸기
9. 인터넷에 배포하기
10. AI 비용 관리와 모니터링
11. 안전 규칙 — 반드시 지켜주세요
12. 자주 생기는 문제 해결
13. 폴더 구조

---

1. 이 사이트는 무엇으로 만들어졌나요

항목	사용한 것	왜 이것을 골랐나요
웹사이트 뼈대	Next.js (넥스트제이에스)	검색(구글)에 잘 노출되고, 무료 배포가 쉽고, 자료가 가장 많습니다.
디자인	Tailwind CSS	색·글자 크기를 한 곳에서 관리할 수 있어 나중에 바꾸기 쉽습니다.
콘텐츠 저장	JSON 파일 (content 폴더)	데이터베이스 서버가 없어 월 고정비 0원이고, 파일 하나만 고치면 내용이 바뀝니다.
배포(인터넷 공개)	Vercel	이 프로젝트 규모에서는 무료로 쓸 수 있고, 파일을 올리면 자동으로 사이트가 갱신됩니다.
AI	OpenAI API	질문에 맞는 안내를 만들 때만 사용합니다.

JSON이란? 컴퓨터가 읽기 쉬운 형태로 정보를 적어둔 텍스트 파일입니다. 메모장으로 열 수 있고, "제목": "내용" 처럼 생겼습니다.

중요한 설계 원칙

• 회원가입·로그인·데이터베이스가 없습니다. 그래서 개인정보 사고 위험과 운영 비용이 매우 낮습니다.
• AI는 등록된 자료만 근거로 답합니다. 기관 이름과 전화번호를 스스로 만들어내지 못하도록 서버에서 한 번 더 걸러냅니다.

---

2. 처음 한 번만 하는 준비 (설치)

(1) Node.js 설치

Node.js는 이 사이트를 내 컴퓨터에서 실행하기 위해 필요한 프로그램입니다.

1. https://nodejs.org 에 접속합니다.
2. LTS라고 적힌 초록색 버튼을 눌러 내려받습니다. (버전 20 이상)
3. 내려받은 파일을 실행하고 "다음"만 계속 누르면 설치가 끝납니다.
4. 설치가 잘 됐는지 확인합니다. PowerShell(윈도우 시작 메뉴에서 "powershell" 검색)을 열고 아래를 입력하세요.

node -v

v20.x.x 처럼 숫자가 나오면 성공입니다.

(2) 프로젝트 폴더에서 필요한 파일 내려받기

PowerShell에서 이 프로젝트 폴더로 이동한 뒤 아래를 입력합니다. (1~3분 걸립니다)

npm install

npm install 은 사이트를 만드는 데 필요한 부품들을 인터넷에서 내려받는 명령입니다. 딱 한 번만 하면 되고, 나중에 부품이 바뀔 때만 다시 하면 됩니다.

---

3. 내 컴퓨터에서 사이트 실행하기

npm run dev

실행하면 화면에 http://localhost:3000 이라는 주소가 나옵니다. 그 주소를 브라우저에 붙여넣으면 사이트가 보입니다.

• 파일을 수정하고 저장하면 브라우저가 자동으로 새로고침됩니다.
• 종료하려면 PowerShell에서 Ctrl + C 를 누릅니다.

콘텐츠만 고친 뒤 문제가 없는지 확인하고 싶다면:

npm run check

✅ 콘텐츠 점검 완료 가 나오면 정상입니다. ❌ 가 나오면 어떤 파일의 무엇이 잘못됐는지 한국어로 알려주므로, 그 부분만 고치면 됩니다.

---

4. 환경변수와 OpenAI API 키 설정

환경변수란? 비밀번호처럼 코드 안에 직접 적으면 안 되는 값을 따로 보관하는 방법입니다.

(1) 파일 만들기

프로젝트 폴더에 있는 .env.example 파일을 복사하고, 이름을 .env.local 로 바꿉니다.

(2) OpenAI API 키 발급받기

1. https://platform.openai.com 에 로그인합니다.
2. 오른쪽 위 → API keys → Create new secret key
3. 만들어진 키(sk- 로 시작하는 긴 글자)를 복사합니다. 이 화면을 닫으면 다시 볼 수 없으니 바로 붙여넣으세요.

(3) .env.local 파일에 붙여넣기

OPENAI_API_KEY=sk-여기에_복사한_키
OPENAI_MODEL=gpt-4o-mini
DAILY_REQUEST_LIMIT=500
RATE_LIMIT_PER_WINDOW=6
NEXT_PUBLIC_SITE_URL=https://실제-사이트-주소

이름	뜻	권장값
OPENAI_API_KEY	OpenAI 비밀 키	필수
OPENAI_MODEL	사용할 AI 모델	gpt-4o-mini (가장 저렴)
DAILY_REQUEST_LIMIT	하루 전체 AI 질문 허용 횟수	처음에는 300~500
RATE_LIMIT_PER_WINDOW	한 사람이 5분 동안 물을 수 있는 횟수	6
NEXT_PUBLIC_SITE_URL	실제 사이트 주소 (검색 노출에 사용)	배포 후 입력
DATABASE_URL	관리자 페이지용 데이터베이스 (Vercel 마켓플레이스에서 Neon 을 연결하면 자동으로 들어옵니다)	관리자 페이지를 쓸 때만
ADMIN_PASSWORD	관리자 페이지 비밀번호 (8자 이상)	관리자 페이지를 쓸 때만

관리자 페이지(/admin)를 쓰려면 DATABASE_URL 과 ADMIN_PASSWORD 가 필요합니다. 자세한 설정 방법은 docs/관리자-페이지-설정.md 에 있습니다. 두 값이 없으면 사이트는 예전처럼 문의 메일 주소를 보여주고, 그 밖의 기능은 모두 그대로 동작합니다.

⚠️ .env.local 파일은 절대로 다른 사람에게 보내거나 GitHub에 올리지 마세요. 이 프로젝트는 이미 .gitignore 설정으로 자동 제외되도록 되어 있습니다. 키가 유출된 것 같으면 OpenAI 사이트에서 그 키를 삭제(Revoke)하고 새로 만드세요.

---

5. 콘텐츠 수정 방법 (가장 자주 하는 일)

모든 글은 content 폴더 안에 있습니다. 코드를 건드릴 필요가 없습니다.

바꾸고 싶은 것	열어야 할 파일
문의 이메일, 사이트 소개 문구, 예시 질문	content/site.json
소개 페이지 전체 글	content/about.json
프로그램·활동 카드	content/programs.json
자주 묻는 질문	content/faq.json
기관 목록 (전화번호 등)	content/organizations.json
긴급상황 안내문과 감지 키워드	content/emergency.json
분야(카테고리) 이름	content/categories.json
권리정보 글	content/rights/파일이름.json
버튼·메뉴 같은 짧은 화면 문구	messages/ko.json (영어는 en.json, 중국어 zh.json, 베트남어 vi.json)

수정할 때 지켜야 할 3가지 규칙

1. 따옴표 " 를 지우지 마세요. 글자는 항상 " 와 " 사이에 있어야 합니다.
2. 줄 끝의 쉼표 , 를 지우지 마세요. 단, 목록의 마지막 줄에는 쉼표가 없어야 합니다.
3. 글 안에 큰따옴표를 쓰고 싶으면 \" 처럼 앞에 \ 를 붙이세요.

수정한 뒤에는 반드시 npm run check 로 확인하세요.

예시: 문의 이메일 바꾸기

content/site.json 을 열고

"contactEmail": "[email protected]",

이 줄의 이메일만 바꾸면 사이트 아래쪽과 개인정보 페이지의 이메일이 한꺼번에 바뀝니다.

---

6. 권리정보 새로 추가하기

1. content/rights 폴더 안의 기존 파일(예: labor-unpaid-wages.json)을 복사합니다.
2. 파일 이름을 새 이름으로 바꿉니다. 예: labor-overtime.json
   • 영어 소문자와 - 만 사용하세요. 한글·띄어쓰기는 안 됩니다.
   • 이 파일 이름이 인터넷 주소가 됩니다.
3. 파일을 열어 아래 항목을 채웁니다.

{
  "id": "labor-overtime",          // 파일 이름과 반드시 똑같이!
  "category": "labor",             // categories.json 에 있는 분야 id
  "status": "published",           // published = 공개 / draft = 숨김
  "featured": false,               // true 면 홈 화면에 먼저 보입니다
  "owner": "운영팀",                // 이 글을 책임지는 사람
  "reviewed_at": "2026-10-01",     // 내용을 확인한 날짜
  "keywords": ["야근", "연장근로", "overtime"],   // 검색·AI 매칭에 쓰입니다
  "organizations": ["moel-1350"],  // organizations.json 에 있는 기관 id 만!
  "related": ["labor-contract"],   // 함께 보면 좋은 다른 글의 id
  "sources": [
    { "title": "고용노동부", "url": "https://www.moel.go.kr", "publisher": "고용노동부" }
  ],
  "i18n": {
    "ko": {
      "title": "제목",
      "summary": "한두 문장 요약",
      "situations": ["이런 상황인가요? 1", "이런 상황인가요? 2"],
      "rights": [{ "title": "권리 제목", "body": "쉬운 설명" }],
      "actions": [{ "title": "행동 제목", "body": "구체적으로 무엇을 하면 되는지" }],
      "note": "확인이 필요한 부분 (없으면 이 줄을 지우세요)"
    }
  }
}

4. 저장하고 npm run check 실행 → ✅ 가 나오면 완료입니다.
5. 메뉴, 목록, 사이트맵(검색엔진용 목록)에 자동으로 추가됩니다. 다른 파일은 손대지 않아도 됩니다.

다른 언어 번역을 추가하려면

"i18n" 안에 "ko" 와 같은 모양으로 "en", "zh", "vi" 를 추가하면 됩니다. 번역이 없어도 괜찮습니다. 그 언어로 볼 때 한국어 원문과 함께 "이 내용은 아직 이 언어로 번역되지 않았습니다" 안내가 자동으로 표시됩니다.

---

7. 기관 정보 수정하기

content/organizations.json 을 엽니다. 기관 하나는 아래와 같이 생겼습니다.

{
  "id": "moel-1350",
  "category": "public",        // emergency / public / youth / migrant / legal 중 하나
  "emergency": false,          // true 면 긴급 연락처로 강조됩니다
  "name":        { "ko": "...", "en": "...", "zh": "...", "vi": "..." },
  "description": { "ko": "...", "en": "...", "zh": "...", "vi": "..." },
  "phone": "1350",
  "website": "https://www.moel.go.kr",
  "languages": ["ko", "en", "zh", "vi"],
  "region": "전국",
  "hours": { "ko": "평일 09:00~18:00" },
  "status": "published",       // draft 로 바꾸면 사이트에서 사라집니다
  "owner": "운영팀",
  "reviewed_at": "2026-09-06",
  "source_url": "https://www.moel.go.kr"
}

🔒 여기에 없는 기관·전화번호는 사이트 어디에도 나오지 않습니다. AI 답변에 등록되지 않은 번호가 섞여 있으면 서버가 자동으로 지웁니다. 반대로 말하면, 여기에 잘못된 번호를 적으면 그대로 노출됩니다. 등록 전에 꼭 공식 홈페이지에서 확인하세요.

기관을 지우고 싶다면 삭제하지 말고 "status": "draft" 로 바꾸세요. 그 기관을 참조하던 권리정보가 오류를 내지 않게 됩니다.

긴급 기관의 공식 사이트 (report_url, 선택) 긴급 도움 페이지에서 휴대폰은 전화 버튼(tel:)을, PC에서는 공식 사이트 링크를 함께 보여줍니다. 신고·안내 전용 공식 페이지가 있다면 "report_url": "https://..." 로 적으세요. 비워 두면 website 를 쓰고, 둘 다 없으면 전화 버튼만 보입니다. 공식 기관 누리집에서 직접 확인한 주소만 적고, 추측한 주소나 검색 결과 주소는 적지 마세요.

---

8. 이미지 넣고 바꾸기

1. 사진을 public/images 폴더에 넣습니다. (파일 이름은 영어 소문자로, 예: mentoring-2026.jpg)
2. content/programs.json 에서 해당 항목의 "image" 값에 파일 이름을 적습니다.

"image": "mentoring-2026.jpg"

3. 사진이 없으면 "image": "" 로 두세요. 빈 자리에 색 배경이 자동으로 들어갑니다.

사진 가이드

• 가로가 긴 사진(가로:세로 = 3:2 정도)이 가장 잘 보입니다.
• 용량은 한 장에 500KB 이하를 권장합니다. (너무 크면 휴대폰에서 느려집니다)
• 청소년의 적극적이고 주체적인 모습(활동·발표·배움)을 담아주세요.
• 얼굴이 나오는 사진은 반드시 본인과 보호자의 동의를 받은 뒤 사용하세요.

---

9. 인터넷에 배포하기

아래 과정은 처음 한 번만 설정하면, 이후에는 파일을 올릴 때마다 사이트가 자동으로 갱신됩니다.

(1) GitHub에 프로젝트 올리기

1. https://github.com 에서 계정을 만듭니다.
2. New repository → 이름을 linkrights 로 만들고 Private(비공개)로 만듭니다.
3. 화면에 나오는 안내대로 이 폴더를 올립니다. (GitHub Desktop 프로그램을 쓰면 클릭만으로 가능합니다)

(2) Vercel에 연결하기

1. https://vercel.com 에 GitHub 계정으로 로그인합니다.
2. Add New → Project → 방금 만든 linkrights 저장소를 선택합니다.
3. Environment Variables(환경변수) 칸에 아래를 하나씩 입력합니다.
   • OPENAI_API_KEY → 발급받은 키
   • OPENAI_MODEL → gpt-4o-mini
   • DAILY_REQUEST_LIMIT → 500
   • NEXT_PUBLIC_SITE_URL → Vercel이 알려준 주소 (예: https://linkrights.vercel.app)
4. Deploy 를 누릅니다. 2~3분 뒤 사이트 주소가 나옵니다.

(3) 이후 수정하는 방법

파일을 고쳐서 GitHub에 올리면(= commit & push) Vercel이 자동으로 사이트를 새로 만듭니다. GitHub 웹사이트에서 파일을 직접 열어 연필 아이콘을 눌러 고치는 것도 가능합니다.

(4) 도메인 연결 (선택)

직접 구매한 주소(예: linkrights.org)가 있다면 Vercel → Settings → Domains 에서 연결할 수 있습니다. 연결한 뒤에는 NEXT_PUBLIC_SITE_URL 값도 그 주소로 바꿔주세요.

계정 소유자를 정해두세요. GitHub·Vercel·OpenAI 계정은 프로젝트가 끝난 뒤에도 사이트를 유지할 사람(또는 단체 공용 계정)의 이름으로 만드는 것을 권장합니다.

---

10. AI 비용 관리와 모니터링

비용을 줄이기 위해 이미 적용된 것

• 일반적인 정보 탐색은 AI 없이 정적 페이지로 제공합니다. (비용 0원)
• 긴급 키워드가 감지되면 AI를 호출하지 않고 검토된 안내만 보여줍니다. (비용 0원)
• 질문 길이를 500자로 제한합니다.
• 질문과 가장 관련 있는 권리정보 4건만 AI에게 전달합니다.
• 답변 길이를 제한하고, 정해진 형식(JSON)으로만 받습니다.
• 한 사람이 5분에 6번, 하루 전체 500번까지만 물을 수 있습니다.

예산 기준 (프로젝트 기준: OpenAI 월 최대 약 100만 원)

단계	기준	해야 할 일
🟢 정상	월 사용액 30만 원 미만	그대로 운영
🟡 주의	월 사용액 50만 원 도달	DAILY_REQUEST_LIMIT 을 300 이하로 낮춤
🟠 경고	월 사용액 70만 원 도달	더 저렴한 모델로 변경, 홍보 일정 조정
🔴 정지	월 사용액 90만 원 도달	OpenAI 하드 리밋으로 자동 정지 (아래 설정)

반드시 해두어야 할 설정

1. OpenAI → Settings → Limits 에서
   • Hard limit(하드 리밋)을 설정하세요. 이 금액을 넘으면 API가 자동으로 멈춥니다.
   • Soft limit(알림 기준)을 그보다 낮게 설정해 이메일 알림을 받으세요.
2. 매주 월요일 OpenAI → Usage 화면에서 사용액을 확인하고 기록하세요.
3. Vercel → Analytics 에서 방문자 수와 /api/ask 호출 수를 함께 확인하면 원인을 알기 쉽습니다.

💡 서버가 여러 대로 나뉘어 실행되는 환경에서는 사이트 안의 하루 제한이 대략적인 상한으로 동작합니다. 그래서 OpenAI 쪽 하드 리밋 설정이 가장 확실한 안전장치입니다. 반드시 설정해 주세요.

---

11. 안전 규칙 — 반드시 지켜주세요

이 사이트는 청소년이 법률·의료·체류 정보를 찾는 곳입니다. 아래는 선택이 아니라 필수입니다.

1. 기관 정보는 반드시 공식 홈페이지에서 확인한 뒤 등록하세요. 전화번호·운영시간은 바뀝니다. 최소 6개월에 한 번 다시 확인하고 reviewed_at 날짜를 갱신하세요.
2. AI가 만든 문장을 그대로 권리정보 페이지에 붙여넣지 마세요. 권리정보는 공식 자료를 근거로 사람이 작성하고 검토한 뒤 올립니다.
3. 최저임금처럼 매년 바뀌는 숫자는 1월에 반드시 갱신하세요. (content/rights/labor-minimum-wage.json)
4. 개인정보를 받지 마세요. 이 사이트에는 회원가입도, 개인정보를 저장하는 곳도 없습니다. 문의는 이메일로만 받고, 상담이 필요한 사람은 등록된 공식 상담기관으로 안내하세요.
5. 긴급 연락처를 임의로 바꾸지 마세요. content/emergency.json 수정은 담당자 확인 후에만 하세요.
6. 1년 이상 검토되지 않은 정보는 화면에 "검토가 필요한 정보입니다" 라고 표시되고, AI가 근거로 사용하지 않습니다. 이 표시가 보이면 내용을 다시 확인해 주세요.
7. 공개 전에는 docs/데이터-검증-체크리스트.md 를 처음부터 끝까지 확인하세요.

---

12. 자주 생기는 문제 해결

증상	원인과 해결 방법
npm 명령이 없다고 나옴	Node.js가 설치되지 않았습니다. 2번 참고.
npm run check 에서 ❌ JSON 형식 오류	쉼표나 따옴표가 빠졌습니다. 오류 메시지에 적힌 파일 이름을 열어 그 부분만 고치세요.
등록되지 않은 기관 id 오류	권리정보의 organizations 에 적은 id가 organizations.json 에 없습니다. 철자를 확인하세요.
사이트는 뜨는데 AI가 답을 못 함	.env.local 의 OPENAI_API_KEY 가 없거나 틀렸습니다. 또는 OpenAI 잔액이 부족합니다.
"오늘 사용할 수 있는 AI 질문 수를 모두 사용했습니다"	하루 한도에 도달했습니다. DAILY_REQUEST_LIMIT 값을 조정하거나 다음 날 다시 시도하세요.
글을 고쳤는데 사이트에 안 보임	"status" 가 draft 로 되어 있는지 확인하세요. 배포 사이트라면 GitHub에 올렸는지 확인하세요.
화면이 이상하게 깨져 보임	npm install 을 다시 실행한 뒤 npm run dev 를 다시 시작해 보세요.

---

13. 폴더 구조

linkrights/
├─ content/                  ← 📝 글과 데이터 (여기만 고치면 됩니다)
│   ├─ site.json                 사이트 기본 정보, 문의 이메일
│   ├─ categories.json           분야(일·알바, 학교 등)
│   ├─ organizations.json        기관 목록 (전화번호·홈페이지)
│   ├─ emergency.json            긴급 안내문과 감지 키워드
│   ├─ about.json                소개 페이지 글
│   ├─ programs.json             프로그램·활동 카드
│   ├─ faq.json                  자주 묻는 질문
│   └─ rights/                   권리정보 글 (파일 1개 = 페이지 1개)
│
├─ messages/                 ← 🌐 버튼·메뉴 같은 짧은 문구 (ko / en / zh / vi)
├─ public/images/            ← 🖼️ 사진 파일
├─ docs/                     ← 📚 설계 문서와 운영 체크리스트
├─ scripts/check-content.mjs ← 🔍 콘텐츠 점검 프로그램
│
└─ src/                      ← ⚙️ 화면을 그리는 코드 (평소에는 건드리지 않습니다)
    ├─ app/                      페이지 (주소 하나 = 폴더 하나)
    │   ├─ [locale]/             언어별 페이지
    │   └─ api/ask/              AI 질문을 처리하는 서버 코드
    ├─ components/               반복해서 쓰는 화면 부품
    └─ lib/                      데이터 읽기, 검색, AI 연결 등

---

문의

이 사이트에 대한 문의는 content/site.json 의 contactEmail 에 적힌 주소로 받습니다. 정보 오류를 발견하면 알려주세요. 확인 후 수정하고 검토일을 갱신합니다.