DEV_ModamDoc 개발 사양서

• 문서 버전: v1.1 (as-built)
• 작성일: 2026-07-30 (KST)
• 대상 프로젝트: DEV_ModamDoc / 실제 소스: 하위 폴더 modam_doc/
• 성격: 개발자를 위한 지식 관리 플랫폼(KMS) — 네이버 카페형 문서 저장소 + 일정관리

본 문서는 현재 구현되어 있는 내용만 서술한다. (미구현/미사용 항목은 포함하지 않음)

1. 프로젝트 개요

1.1 프로젝트명

• DEV_ModamDoc (저장소 루트)
• 실제 Django 프로젝트 폴더: modam_doc/ (패키지명도 modam_doc — 서버 mdmproj1 구조와 일치)

1.2 개발 목적

• 개발 문서를 체계적으로 관리하는 웹 시스템
• Markdown + 위지윅(WYSIWYG) 겸용 문서 작성
• 게시판(그룹/하위)·태그로 분류해 쉽게 검색 가능한 문서 저장소
• 업무 노하우·기술 자산의 축적 및 재사용
• 일정/할 일(To Do)까지 통합한 개인 개발 생산성 허브

1.3 한 줄 정의

로컬(Windows)에서 개발하고 서버(hetz02 mdmproj1 규약)로 이전 가능한,
네이버 카페형 개발 문서 + 일정 관리 Django 사이트.

2. 개발 배경 (왜 만들게 되었는가)

• 프로젝트 문서가 Word·Excel·메모장 등에 흩어져 한곳에서 관리되지 않음.
• 이전 프로젝트의 개발 내용을 다시 찾기 어렵고 표준 문서 양식이 없음.
• 유지보수 시 과거 이력·의사결정 근거를 추적하기 어려움.
• 기존 서버(hetz02 mdmproj1)와 동일한 개발 워크플로우(로컬 개발 → 서버 이전) 를 재사용.
• 문서와 함께 개발 일정/할 일을 같은 사이트에서 다루고 싶음.

3. 개발 목표 (달성 현황)

4. 시스템 구성

4.1 논리 구조

사용자(Browser)
   │  HTTP
Django (modam_doc)
   ├─ mdl_login_info : 인증 + 로컬 자동 로그인
   ├─ app_doc        : 게시판/문서/첨부/검색
   └─ app_schedule   : 달력 + To Do
   │  raw SQL (proj_common.get_conn)
SQLite (db.sqlite3)
   │
파일 저장소 (media/attachments/)

4.2 로컬 실행 구조 (현재)

Browser → Django runserver (127.0.0.1:8001) → SQLite
                                    static: WhiteNoise

4.3 서버 배포 목표 (hetz02 mdmproj1 규약)

Browser → Apache → mod_wsgi → Django → SQLite → Storage

5. 적용 기술

Backend

• Python 3.8.6(로컬 .venv) / 3.12(서버 목표)
• Django 4.2.7
• 데이터 접근: raw SQL(Django ORM 미사용) — sqlite3 커서 직접 사용
• models.py는 비워둠, 스키마는 pkg_sql_statement / proj_sql_mapping에서 수동 관리
• 인증만 Django 기본 contrib.auth 사용

Frontend

• HTML5 / CSS3 (순수 CSS)
• Vanilla JavaScript
• Toast UI Editor — 마크다운 ↔ 위지윅, CDN 없이 static/vendor/toastui/에 벤들링

문서 렌더링

• Markdown 3.5.2 (md→HTML) + bleach 6.1.0 (XSS 정제) + Pygments 2.17.2 (코드 하이라이트)
• 외부 링크는 target="modamDocLinkWindow"로 한 탭 재사용

Database

• SQLite (db.sqlite3)

Server / 정적

• 로컬: Django runserver / waitress(serve.py)
• 서버 목표: Ubuntu + Apache + mod_wsgi
• 정적 파일: WhiteNoise(CompressedStaticFilesStorage)
• CORS: django-cors-headers

설정

• python-dotenv 기반 환경변수 (로컬 기본값, 서버 .env)

의존성 (requirements.txt)

Django==4.2.7
whitenoise==6.6.0
django-cors-headers==4.3.1
python-dotenv==1.0.1
Markdown==3.5.2
bleach==6.1.0
Pygments==2.17.2
waitress==3.0.0

6. 개발 기간

7. 주요 기능

7.1 게시판 / 분류

• 좌측 트리: 그룹 → 하위 게시판 계층(tb_board.parent_id)
• 즐겨찾는 게시판, 전체글보기, 공지 구분
• 그룹 접기/펴기 상태 기억(다음 조회 시 유지), 활성 게시판 자동 스크롤
• 게시판 관리: 추가 / 이름변경 / 순서이동 / 부모변경 / 즐겨찾기 / 삭제

7.2 문서 관리

• 등록 / 수정 / 보기 / 이동 / 소프트 삭제(status='D')
• 목록: 정렬(최신 위=내림차순 기본, 오름차순 선택), 공지 상단 고정, 조회수·좋아요
• 여러 글 선택 → 이동 / 삭제

7.3 Markdown / 에디터

• Markdown + 위지윅 겸용(Toast UI Editor), 실시간 미리보기
• 저장 시 서버에서 md→정제 HTML(content_html) 캐시, 코드블록 하이라이트
• 외부 링크 한 탭 재사용, YouTube 임베드/클릭 토글

7.4 첨부 / 이미지

• 다중 파일 업로드, 원본명 매핑(tb_file), 안전한 다운로드 응답
• 저장 위치: media/attachments/

7.5 검색

• 제목 / 제목+본문 키워드, 기간 필터

7.6 태그

• tb_tag / tb_doc_tag 매핑 기반 분류

7.7 일정관리 (app_schedule)

• 월간 달력(일요일 시작, 날짜별 할 일 개수 배지, 이전/다음/오늘 이동)
• To Do — Microsoft To Do 스타일 상세 패널
• 완료 · 별표(중요) · 나의 하루 · 미리 알리기(시각) · 기한 · 반복(일/주/월/년) · 메모 · 삭제
• 좌측 메뉴: 달력 / 오늘 할 일 / 미완료 / 완료됨 / 전체 할 일 (뱃지 카운트)

8. DB 설계

8.1 ERD

erDiagram
    tb_board ||--o{ tb_board : "parent_id(그룹-하위)"
    tb_board ||--o{ tb_doc  : "board_id"
    tb_doc   ||--o{ tb_file : "doc_id"
    tb_doc   ||--o{ tb_comment : "doc_id"
    tb_doc   ||--o{ tb_doc_tag : "doc_id"
    tb_tag   ||--o{ tb_doc_tag : "tag_id"
    auth_user ||--o{ tb_doc : "author_id"

tb_todo는 문서 테이블과 독립(개인 일정). auth_user는 Django 기본 인증 테이블.

8.2 테이블 설명

tb_board — 게시판/그룹 트리
| 컬럼 | 타입 | 설명 |
|---|---|---|
| board_id | INTEGER PK | 게시판 ID |
| parent_id | INTEGER | 상위 그룹(트리) |
| name | TEXT | 이름 |
| sort_order | INTEGER | 정렬 순서 |
| is_group | INTEGER | 그룹 여부 |
| is_favorite | INTEGER | 즐겨찾기 |
| created_at | TEXT | 생성 시각 |

tb_doc — 문서
| 컬럼 | 타입 | 설명 |
|---|---|---|
| doc_id | INTEGER PK | 문서 ID |
| board_id | INTEGER | 소속 게시판 |
| title | TEXT | 제목 |
| content_md | TEXT | 마크다운 원본 |
| content_html | TEXT | 렌더 캐시(정제 HTML) |
| author_id | INTEGER | 작성자(auth_user) |
| is_notice | INTEGER | 공지 여부 |
| view_count / like_count | INTEGER | 조회수 / 좋아요 |
| status | TEXT | N(정상) / D(삭제) |
| created_at / updated_at | TEXT | 생성 / 수정 시각 |

tb_file — 첨부파일
file_id PK, doc_id, orig_name, stored_name, size, uploaded_at

tb_tag / tb_doc_tag — 태그 / 문서-태그 매핑
tb_tag(tag_id PK, name) · tb_doc_tag(doc_id, tag_id) (복합 PK)

tb_comment — 댓글
comment_id PK, doc_id, author_id, content, status, created_at

tb_todo — 할 일(일정관리)
| 컬럼 | 타입 | 설명 |
|---|---|---|
| todo_id | INTEGER PK | 할 일 ID |
| content | TEXT | 내용 |
| is_done | INTEGER | 완료 |
| is_star | INTEGER | 중요(별표) |
| is_my_day | INTEGER | 나의 하루 |
| due_date | TEXT | 기한(YYYY-MM-DD) |
| remind_time | TEXT | 알림 시각(HH:MM) |
| repeat_unit / repeat_interval | TEXT/INTEGER | 반복 단위 / 간격 |
| note | TEXT | 메모 |
| created_at | TEXT | 생성 시각 |

8.3 데이터 규칙

• 소프트 삭제: 문서·댓글은 status='D' 표시, 기본 조회는 항상 status != 'D'.
• 스키마는 CREATE TABLE IF NOT EXISTS + 필요 시 ALTER TABLE 보정으로 수동 마이그레이션.
  (인덱스는 컬럼 보정 이후 생성 — 기존 DB 순서 오류 방지)

9. 화면 구성

• 상단 공용 메뉴(templates/nav_menu.html): 문서관리 / 모담영어 / 일정관리 + 검색 + 사용자.
• 앱 구조: 각 앱은 nav_menu.html을 include하는 앱 셸 + 자체 사이드바/콘텐츠.

10. 개발 이슈 (설계·기술 의사결정) ★

10.1 Markdown 저장 방식

• 문제: HTML 저장 vs Markdown 원본 저장?
• 결론: Markdown 원본(content_md) 저장 + 렌더 HTML(content_html) 캐시 병행.
• 이유: 유지보수·재편집 용이, 렌더는 캐시로 성능 확보.

10.2 데이터 접근 방식 (ORM vs raw SQL)

• 결론: 기준 서버 mdmproj1 관례를 따라 raw SQL(models.py 비움), 인증만 ORM.
• 이유: 서버 프로젝트와 규약 일치 → 이전·유지보수 일관성.

10.3 삭제 안전성

• 해결: 소프트 삭제(status='D') + 기본 조회 status != 'D' 필터.

10.4 XSS / 보안

• 사용자 Markdown → HTML 렌더 시 bleach 화이트리스트 정제 후 저장.
• Django 기본 CSRF 적용(모든 POST 폼). 첨부는 원본명 매핑·저장명 분리·media/attachments/ 격리.

10.5 외부 링크 / 탭 재사용

• 문제: 외부 링크·모담영어·유튜브 클릭 시 새 탭이 계속 열림.
• 해결: 명명된 타깃으로 한 탭 재사용. rel="noopener" 제거가 필요했고,
  modameng.com·modam_doc 양쪽 COOP 해제로 창 핸들 재사용 확보. YouTube는 임베드 전환.

10.6 그룹 접기/펴기 상태 유지

• 클라이언트에 상태 저장 → 조회 시 프리렌더 스크립트로 복원, 활성 게시판 자동 스크롤.

10.7 일정관리 스키마 마이그레이션 순서 버그

• 문제: 기존 DB에서 is_my_day 인덱스를 컬럼 추가 전에 생성하려다 no such column 오류.
• 해결: 인덱스 생성을 분리, ALTER(컬럼 보정) 이후 실행.

10.8 로컬 단독 사용 편의 (자동 로그인)

• AutoLoginMiddleware로 자동 admin 로그인. 배포 직전 주석 처리하면 정상 로그인 사용.

10.9 Windows 운영 이슈

• 서버 자동 실행(작업 스케줄러) + 콘솔창 숨김(VBScript WScript.Shell.Run ...,0).
• .bat는 ASCII 전용(한글 포함 시 cmd 인코딩 깨짐) → stop/start 스크립트 재작성.
• 관리자 권한 프로세스는 일반 권한으로 종료 불가 → 비관리자 실행 원칙.

11. 성능

• 렌더 캐시: 문서 HTML을 저장 시 1회 렌더(content_html)해 조회 시 재렌더 없음.
• 정적 파일: WhiteNoise 압축 저장, collectstatic → proj_all_static/.
• 인덱스: tb_todo(due_date), tb_todo(is_my_day) 등 조회 조건에 인덱스.
• 검색: LIKE 기반 키워드/기간 필터.

12. 유지보수 / 운영

12.1 주요 커맨드 (작업 디렉터리 modam_doc/)

• 실행(8001): .venv\Scripts\python.exe manage.py runserver 127.0.0.1:8001 (또는 start_server.bat)
• 서버 시작/종료: start_server_now.bat / stop_server.bat
• 마이그레이션(auth): .venv\Scripts\python.exe manage.py migrate
• 스키마+시드: .venv\Scripts\python.exe manage.py initdb
• 관리자 계정: .venv\Scripts\python.exe manage.py createsuperuser

12.2 로그 / 백업

• 실행 로그: server.log
• 백업 대상: db.sqlite3, media/(첨부).

12.3 배포 절차 (hetz02 규약)

1. 서버로 코드 이전
2. .env(SECRET_KEY / ALLOWED_HOSTS / DEBUG=false 등) 설정
3. AutoLoginMiddleware 주석 처리(정상 로그인 사용)
4. collectstatic → Apache + mod_wsgi 연결
5. db.sqlite3·.env·media/·.venv/는 배포 대상에서 제외

12.4 설정 이식성

• settings.py 환경변수: DJANGO_DEBUG, DJANGO_SECRET_KEY, DJANGO_ALLOWED_HOSTS.
• 세션 쿠키명 분리(modam_doc_sssn_00), TIME_ZONE='Asia/Seoul', LOGIN_URL='/login/'.
• 로컬은 .env 없이 기본값으로 즉시 구동.

12.5 시간대 규칙

• 모든 날짜·시각은 KST(UTC+9) 기준(문서 파일명/본문 날짜 포함).

13. 변경 이력

부록 A. 폴더 구조 (요약)

DEV_ModamDoc/
└─ modam_doc/
   ├─ manage.py · serve.py · requirements.txt
   ├─ start_server.bat · start_server_now.bat · stop_server.bat · start_server_hidden.vbs
   ├─ modam_doc/            # settings · urls · wsgi
   ├─ mdl_login_info/       # 인증 + AutoLoginMiddleware
   ├─ app_doc/              # 게시판/문서/첨부/검색
   ├─ app_schedule/         # 달력 + To Do
   ├─ proj_common/          # get_conn() 등 공통
   ├─ proj_sql_mapping/     # 공통 SQL(게시판 트리 등)
   ├─ templates/            # nav_menu.html, base.html, 로그인
   ├─ static/ · proj_all_static/(STATIC_ROOT) · media/(첨부)
   └─ docs/                 # 작업 로그(일자별) + 본 사양서

부록 B. 앱별 URL 요약

• app_doc: /, /search/, /board/<id>/, /board/<id>/write/, /doc/<id>/, /doc/<id>/edit/,
  /doc/<id>/like/, /docs/move/, /docs/delete/, /manage/boards/..., /file/<id>/download/
• app_schedule: /schedule/, /schedule/todo/{add,toggle,delete,update,star,my-day,remind,due,repeat}/