dbx-main/docs/PROJECT_MODULE.md

# 프로젝트 관리 모듈 (아사나식) — `app/modules/project/`

> 회사(dbxcorp.co.kr) 직원이 프로젝트·서브프로젝트·업무를 달력/타임라인/보드로
> 관리하는 아사나(Asana) 스타일 협업 모듈. DB는 `project_db` 전용.

## 1. 개요

| 항목 | 값 |
| --- | --- |
| URL prefix | `/project` |
| DB | `project_db` (PostgreSQL, 역할 `project_app` CRUD only) |
| 연결 env | `PROJECT_DB_URL` (미설정 시 "설정 필요" 안내, 앱은 죽지 않음) |
| 진입 권한 | 권한키 `project` (관리자 페이지 토글로 직원별 부여, admin 자동) |
| 멤버 배정 후보 | `project` 권한 보유 등록 사용자 자동 목록 (`GET /project/api/assignable-users`) |
| 관리 권한 | 프로젝트 생성/삭제·사용자 배정 = ERP 관리자(`is_admin`) / 서브프로젝트·업무·단계 = 배정 멤버 또는 owner |
| 메일 알림 | `app/mail.py` (stdlib smtplib). 업무 배정/완료 시 관리자에게 발송 |

## 2. 데이터 모델 (`scripts/sql/project_db_init.sql`)

- `projects` — `parent_id`(self-FK, NULL=최상위 / NOT NULL=서브프로젝트, `ON DELETE CASCADE`), name, description, color, owner_email, start/due_date, status(active|archived).
- `project_members` — 프로젝트↔사용자 배정. role(manager|member), `UNIQUE(project_id, user_email)`.
- `project_stages` — 진행단계(칸반 컬럼). 프로젝트 생성 시 기본 4단계 seed(할 일/진행 중/검토/완료). `is_done_stage`=TRUE 단계로 옮기면 업무 완료 처리.
- `tasks` — 업무. stage_id, title, description, assignee_email/name, priority(low|normal|high), start/due_date, completed_at.
- `task_comments` — 댓글(스켈레톤 테이블, UI는 추후).
- `project_activity` — 활동 이력(created/assigned/completed/stage_changed). 메일 트리거 근거 + 타임라인.

## 3. 화면 / 뷰

- **홈** (`/project/`): "진행중인 프로젝트" / "완료된 프로젝트" 두 섹션으로 구분된 카드 그리드 + "내 업무" 사이드.
  관리자는 "새 프로젝트"(이름/설명/시작일/마감일/색상 지정 + 멤버 다중 선택, 생성 직후 일괄 배정). 완료 섹션은 접기/펼치기(localStorage 기억).
  각 카드에 이름 아래 배정 멤버(아이콘+이름), 진행률 바(완료/전체 업무)와 업무 미리보기(단계·담당자·마감일, 최대 8건 + 더보기)를 표시 —
  완료된 업무도 취소선으로 계속 노출해 전체 현황을 한눈에 파악.
  카드 이름 옆에는 호버 시에만 보이는 "업무 추가" 아이콘 버튼(관리자 또는 해당 프로젝트 멤버/owner) — 같은 업무편집 팝업을 새 업무 작성 모드로 연다.
  카드·내 업무의 업무를 클릭하면 페이지 이동 없이 그 자리에서 업무편집 팝업(담당자·단계·일정·첨부·댓글)이 뜬다
  (`#pj-modal-task` + `home_tasks`/`#pj-home-data`, 담당자·단계 옵션은 해당 프로젝트를 API 로 즉시 조회).
  업무에 댓글이 있으면 말풍선 아이콘+개수를 표시, 더블클릭하면 댓글만 보는 카톡 대화창 스타일 팝업(`#pj-modal-comments`)이 뜬다.
  확인 안 한 새 댓글은 말풍선이 커지며 반짝이고(브라우저별 `localStorage: pj_seen_comments` 로 확인 여부 기억), 팝업을 열면(확인하면) 원래대로 돌아간다.
  날짜는 전부 `mm/dd(요일)` 형식(`_fmt_date_kr`)으로 표시.
  프로젝트/업무/댓글/멤버/단계가 추가·수정되면 `GET /project/api/live-version`(최근 변경 시각) 폴링으로 감지해
  해당 화면을 열어둔 모든 사용자의 페이지가 자동 새로고침(모달을 열어 입력 중이면 닫힐 때까지 대기).
- **프로젝트** (`/project/p/{id}`): 좌측 서브프로젝트/멤버, 우측 뷰 토글.
  좌측 트리의 업무 클릭도 페이지 이동 없이 바로 팝업(이미 로드된 전체 업무 데이터 사용).
  - **달력** — FullCalendar. 업무를 시작~마감 기간으로 표시. 클릭 편집.
  - **타임라인** — vis-timeline(간트형). 기간 있는 업무만.
  - **보드** — 단계별 칸반. 카드 드래그로 단계 이동(`PUT /api/tasks/{id}` `stage_id`).
  - **리스트** — 표.
  - 라이브러리는 현재 CDN 로드(스켈레톤). 추후 `app/static/vendor/` self-host 권장.

## 4. 메일 알림

- `app/mail.py` `send_email(...)` — `SMTP_HOST` 있어야 발송, 없으면 skip. STARTTLS/SSL/평문 지원.
- env: `SMTP_HOST/PORT/USER/PASSWORD/FROM/TLS`, 수신자 `PROJECT_NOTIFY_EMAIL`(쉼표, 비우면 admin 전원).
- 트리거: 업무 신규 배정(생성/수정 시 담당자 변경) · 완료단계 진입. `BackgroundTasks` 비동기, 실패는 로그만.

## 5. 배포

```bash
# 1) DB 생성 (superuser 1회, 컨테이너 postgres-db)
read -s -p "project_app password: " APP_PWD; echo
docker exec -i postgres-db psql -U postgres -v app_password="$APP_PWD" \
    < scripts/sql/project_db_init.sql

# 2) /opt/www/main/.env 에 등록
#    PROJECT_DB_URL=postgresql://project_app:<APP_PWD>@postgres-db:5432/project_db
#    (메일 쓰려면 SMTP_* 추가)

# 3) 재배포 (git pull 후 반드시 --build)
cd /opt/www/main && docker compose up -d --build web
```

## 6. 댓글 · 첨부 · 알림센터 · 단계편집 (구현됨)

- **댓글** `task_comments` — 업무 모달 하단. 등록/삭제(본인·관리자). 새 댓글 시 관련자 인앱 알림.
- **첨부** `task_attachments` — 업무 모달. 파일 업로드(최대 20MB)/다운로드/삭제. 실제 파일은 `DATA_DIR/project/<task_id>/<uuid>.<ext>`, DB엔 메타만. 첨부 디렉토리는 운영 볼륨(DATA_DIR)에 저장돼 재배포에도 보존.
- **단계 편집** — 보드 칸반 헤더에서 단계 이름변경/완료토글/좌우 이동(순서)/삭제, 트레일링 "+ 단계 추가". `PUT .../stages/order`, `PUT .../stages/{id}`.
- **알림센터(인앱)** `project_notifications` — 배정/완료/댓글 시 수신자별 알림 생성. 우측 상단 벨(미읽음 배지) → `/project/inbox`. 항목 클릭=읽음, "모두 읽음". 본인 행동은 알림 제외.
- 마이그레이션: `scripts/sql/project_db_002_attachments_notifications.sql` (첨부·알림 테이블 + 권한).

## 7. 추후 단계

태그 · 하위업무(체크리스트) · 검색/필터 · 업무 정렬 영속화 · 칸반 단계 드래그 정렬 · 멘션.