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/): 프로젝트 카드 그리드 + "내 업무" 사이드. 관리자는 "새 프로젝트".
• 프로젝트 (/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. 배포

# 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. 추후 단계 (스켈레톤 이후)

댓글/첨부 UI · 태그 · 하위업무(체크리스트) · 검색/필터 · 아사나식 알림센터(인앱) · 단계 순서 드래그 편집 · 업무 정렬 영속화.