글 수정

게시판 취소 공지

본문 상단 탭에서 마크다운 ↔ 위지윅(서식 편집) 전환

글자 크기 줄간격 배

# 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. 개발 목표 (달성 현황)

| 구분 | 목표 |
|---|---|
| 편집 | Markdown + 위지윅 겸용 작성 |
| 렌더 | 서버측 md→정제 HTML 캐시, 코드 하이라이트 |
| 분류 | 게시판(그룹/하위) 트리, 즐겨찾기, 태그 |
| 목록 | 정렬(오름/내림), 공지 상단 고정 |
| 관리 | 게시판 추가/이름변경/이동/즐겨찾기/삭제 |
| 문서 | 등록·수정·보기·이동·소프트 삭제 |
| 첨부 | 파일 업로드/다운로드, 이미지 첨부 |
| 검색 | 제목/본문/기간 검색 |
| 일정 | 달력 + To Do(상세 패널) |
| 이식 | 환경변수 기반 로컬↔서버 배포 |

---

## 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. 개발 기간

| 구분 | 기간(KST) | 내용 |
|---|---|---|
| 프로젝트 구축 | 2026-07-22 | 스캐폴딩, 게시판/문서 CRUD, 마크다운, 검색 |
| 외부링크·에디터 | 2026-07-22~23 | 외부링크 한 탭 재사용, Toast UI 위지윅 겸용 |
| 통합·유튜브 | 2026-07-25 | 모담영어(modameng.com) 상단 통합, 유튜브 임베드 |
| 운영 자동화 | 2026-07-28 | 작업 스케줄러 자동 실행, start/stop 스크립트 |
| 일정관리 | 2026-07-30 | 달력 + To Do(MS To Do 스타일 상세 패널) |
| 현재 | 지속 개발 중 | — |

---

## 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
```mermaid
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. 화면 구성

| 화면 | 경로(예) | 설명 |
|---|---|---|
| 로그인 | `/login/` | 로컬은 자동 로그인 미들웨어로 우회 |
| 메인/게시판 | `/`, `/board/<id>/` | 좌측 트리 + 우측 글 목록 |
| 글쓰기/수정 | `/board/<id>/write/`, `/doc/<id>/edit/` | 마크다운+위지윅+첨부+태그 |
| 글 보기 | `/doc/<id>/` | 렌더 HTML, 조회수, 좋아요, 첨부 |
| 검색 | `/search/` | 키워드/기간 |
| 게시판 관리 | `/manage/boards/` | 그룹/게시판 CRUD·정렬 |
| 일정관리 | `/schedule/` (`?view=today\|incomplete\|done\|all`) | 달력 + To Do 상세 패널 |
| 관리자 | `/admin/` | Django Admin |

- 상단 공용 메뉴(`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. 변경 이력

| 버전 | 날짜(KST) | 내용 |
|---|---|---|
| 0.1 | 2026-07-22 | 프로젝트 구축(게시판/문서 CRUD, 마크다운, 검색, 첨부) |
| 0.2 | 2026-07-22~23 | 외부링크 한 탭 재사용, Toast UI 위지윅 겸용 에디터 |
| 0.3 | 2026-07-25 | 모담영어 상단 통합, YouTube 임베드 |
| 0.4 | 2026-07-28 | 작업 스케줄러 자동 실행, start/stop 스크립트 |
| 0.5 | 2026-07-30 | 일정관리(달력 + To Do 상세 패널) |
| 1.0~1.1 | 2026-07-30 | 개발 사양서(as-built) 정리 |

---

## 부록 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}/`

태그

파일 첨부

취소