Files
dbx-main/docs/PROJECT_MODULE.md
T
king 8f73c0dcb9 feat(project): 수신함도 좌측 사이드바 + 우측 프레임 2단 레이아웃으로
수신함이 사이드바 없이 화면 전체를 쓰고 있어, 내 업무·프로젝트 화면과
같은 2단 구조로 맞췄다. 내용은 오른쪽 프레임 안에서만 스크롤한다.

- inbox.html 을 .pj-layout + 공용 _side.html + <section class="pj-main">
  으로 감쌌다. 사이드바로 이동할 수 있으니 "← 프로젝트" 버튼은 뺐다.
- _side.html 에 side_active('inbox' | 'mytasks' | '')를 받아 지금 보고 있는
  개인 메뉴를 강조한다. 새 프로젝트 "+" 는 그 모달을 갖고 배선하는 화면
  (내 업무·프로젝트)에서만 보인다.
- 라우터: 사이드바 데이터를 세 화면이 같이 쓰므로 _nav_projects 헬퍼로
  묶고, 수신함에도 nav_projects/my_open_total 을 넘긴다.
- 내 업무·수신함 본문은 폭 1180px 로 제한 — 표/목록이 화면 끝까지 늘어나
  눈이 따라가기 힘들던 문제(보드·달력 등은 종전대로 전체 폭).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-22 13:27:07 +09:00

16 KiB

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

회사(dbxcorp.co.kr) 직원이 프로젝트→세션→업무 3단계 구조를 달력/타임라인/ 보드로 관리하는 아사나(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)
생성 권한 프로젝트·세션·업무(하위 업무 포함) 생성은 로그인해 이 모듈에 접근할 수 있는 사용자 누구나. 프로젝트를 만든 사람은 자동으로 owner 가 되어 그 프로젝트를 관리(_can_manage)할 수 있다.
수정/이동 권한 서브프로젝트·업무·세션 CRUD(이름변경·완료토글·순서변경 등) = 그 프로젝트의 배정 멤버 또는 owner 또는 admin(_require_manage)
삭제 권한 프로젝트·세션·업무 모두 "만든 사람만"(슈퍼관리자 예외, 생성자 정보 없는 과거 데이터는 admin 허용) — _can_delete 하나로 통일
멤버 배정 여전히 관리자(is_admin) 전용. 비관리자가 "새 프로젝트" 모달을 열면 멤버 선택란은 안내 문구만 뜨고 시도하지 않는다(불필요한 403 방지)
메일 알림 app/mail.py (stdlib smtplib). 업무 배정/완료 시 관리자에게 발송

1-1. 프로젝트 → 세션 → 업무 (하위 업무 포함) 3단계 구조

"세션"은 새 개념이 아니라 기존 "단계"(칸반 컬럼)를 그대로 재사용한다 — 아사나도 보드 뷰의 컬럼과 리스트 뷰의 구분선이 같은 "섹션" 하나다. DB 컬럼/테이블 이름(project_stages, stage_id)은 그대로 두고, 사용자에게 보이는 문구만 "세션"으로 바꿨다.

  • 세션 관리 — 프로젝트 화면(/project/p/{id})에서 "이 프로젝트" 스코프로 볼 때만 보드 컬럼에 관리 UI가 붙는다(이름변경·완료토글·삭제·"+ 세션 추가"). 컬럼 헤더를 드래그해서 순서를 바꿀 수 있다(카드 드래그와 같은 네이티브 HTML5 DnD, PUT /api/projects/{id}/stages/order 재사용). "전체 프로젝트" 스코프(여러 프로젝트를 세션 '이름'으로 합쳐 보는 예전 방식)에서는 세션을 하나로 특정할 수 없어 관리 UI가 없다.
  • 하위 업무(subtask) — 새 테이블이 아니라 tasks.parent_task_id 재사용 (부모 삭제 시 CASCADE). 업무 편집 팝업 안에 인라인으로 표시되며(체크박스+ 제목+담당자+마감일, 한 줄에서 바로 저장), 보드/캘린더/리스트에는 최상위 업무만 카드로 뜬다(하위 업무는 부모 카드에 "2/5" 진행 배지로만 나타난다). 세션을 갖지 않는다(칸반에 안 보이므로).
  • 멀티호밍(다른 프로젝트에 연결) — task_project_links 테이블. 업무 하나가 원래 소속(기본 홈, tasks.project_id/stage_id)과 무관하게 다른 프로젝트의 한 세션에도 동시에 나타날 수 있다(아사나의 "Add to project"). 업무 편집 팝업의 "연결된 프로젝트" 칩에서 추가/해제한다. 새 연결을 만들 때는 원 프로젝트·대상 프로젝트 양쪽 관리 권한이 필요하지만(무단으로 남의 업무를 끌어와 노출시키는 것 방지), 이미 연결된 업무를 그 프로젝트 보드 안에서 다른 세션으로 드래그하는 것은 대상 프로젝트 권한만 있으면 된다. list_tasks(project_id=X)(비재귀 단일 프로젝트 조회, 프로젝트 화면이 쓰는 바로 그 경로)가 자동으로 연결된 업무까지 포함해서 돌려준다 — 다른 호출 경로(홈/내 업무 등 project_id 없이 부르는 전체보기)는 원 소속만 세어 중복 노출을 막는다.
  • 사이드바 프로젝트 스코프 — 프로젝트 화면 툴바에 "이 프로젝트"/"전체 프로젝트" 토글이 있다. 기본은 "이 프로젝트"(아사나처럼 지금 선택한 프로젝트의 세션만 보드/캘린더/타임라인/리스트에 나온다), "전체 프로젝트"는 예전처럼 접근 가능한 모든 프로젝트를 합쳐서 보여준다. 서버가 tasks 배열의 각 행에 context_project_id(어느 프로젝트를 보다가 담겼는지)를 표시해두고, 클라이언트가 이 값으로 스코프를 걸러낸다(순수 프론트 필터 — 서버 재조회 없음).
  • 업무 설명 이미지 삽입 — 설명란이 contenteditable 로 바뀌어 이미지를 붙여넣거나 파일로 올릴 수 있다. 새 첨부 endpoint 없이 기존 task_attachments 업로드를 재사용하고, 표시는 GET /api/attachments/{id}/inline(다운로드용 /download 는 Content-Disposition: attachment 가 걸려 <img> 로 못 씀 — 그래서 인라인 전용 endpoint를 따로 뒀다)로 한다. 저장 전 서버가 store.sanitize_description_html() 로 허용 태그만 남기고 스크립트/이벤트속성/위험 URL 스킴을 제거한다(표준 html.parser, 외부 라이브러리 없음). 새 업무 작성 중(저장 전, task_id 없음) 에는 이미지 삽입이 비활성화된다 — 첨부가 업무 id 를 필요로 하기 때문.

2. 데이터 모델 (scripts/sql/project_db_init.sql + ..._002_* ~ ..._006_*)

  • 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(="세션") — 진행단계(칸반 컬럼). 프로젝트 생성 시 자동으로 만들지 않는다(아사나처럼 직접 "+ 세션 추가"로 만든다 — create_project 의 seed_stages 기본값은 False). is_done_stage=TRUE 단계로 옮기면 업무 완료 처리. created_by(003) — 삭제를 "만든 사람만"으로 제한하기 위함. color(004, nullable) — 세션 생성/편집 팝업에서 아사나 10색 팔레트 (store.STAGE_COLOR_PALETTE) 중 선택, 보드 컬럼 헤더에 표시.
  • tasks — 업무. stage_id, title, description(HTML — 이미지 삽입 지원), assignee_email/name, priority(low|normal|high), start/due_date, completed_at, parent_task_id(003, self-FK ON DELETE CASCADE, NULL=최상위 업무).
  • task_project_links(003) — 멀티호밍. (task_id, project_id) UNIQUE, stage_id nullable(그 프로젝트 안에서의 세션).
  • task_comments — 댓글.
  • task_attachments — 첨부(설명란 이미지도 이걸 재사용).
  • project_activity — 활동 이력(created/assigned/completed/stage_changed). 메일 트리거 근거 + 타임라인.
  • task_mentions(006) — @태그. (task_id, COALESCE(comment_id,0), mentioned_email) UNIQUE, source=description|comment, is_read. 수신함의 "나를 태그한 업무" 목록 근거.

3. 화면 / 뷰

  • 내 업무 (/project/): 프로젝트 모듈의 첫 화면. 예전 홈(프로젝트 카드 그리드)은 없앴다 — 좌측 "내 업무" 메뉴와 같은 화면이다(project/mytasks.html). 내가 담당자인 업무를 한 표에 모아 보여준다: 완료 체크박스 · 업무 · 프로젝트 · 세션 · 우선순위 · 시작 · 마감. 헤더 클릭으로 정렬, 상단 탭으로 진행 중/완료/전체 필터, 오른쪽에 진행/완료/지연 요약. 체크박스는 그 자리에서 완료 토글, 행을 누르면 그 프로젝트로 이동하며 업무 편집 팝업이 열리고(?task=), 우클릭은 열기/완료/삭제 메뉴. 완료된 업무 행은 반투명 + 취소선. 8초 주기로 목록을 다시 받는다. 표/목록 화면이라 본문 폭은 1180px 로 제한한다(보드·달력 등 프로젝트 뷰는 전체 폭). 좌측 사이드바는 프로젝트·수신함 화면과 공용(project/_side.html, side_active 로 활성 메뉴 표시) — 수신함 · 내 업무 · 프로젝트 트리(+ 새 프로젝트). "전체 멤버"는 그 팝업을 배선하는 코드가 initProject 안에 있어 프로젝트 화면에서만 나온다.
  • 프로젝트 (/project/p/{id}): 좌측 사이드바(공용 _side.html) + 우측 뷰 토글. 좌측 "내 업무"는 접이식 패널이 아니라 /project/ 로 가는 링크다. 이 프로젝트의 멤버는 화면 위 제목 오른쪽에 겹친 아바타로 둔다(.pj-title-members) — 마우스를 올리면 이름(data-tip, initHoverTips 가 위임 방식이라 동적 요소에도 붙는다), 클릭하면 그 사람이 이 프로젝트에서 맡은 업무 팝업, 우클릭(관리자)하면 제외, 옆 + 는 멤버 배정. 좌측 트리의 업무 클릭도 페이지 이동 없이 바로 팝업(이미 로드된 전체 업무 데이터 사용). 좌측 맨 위 수신함(미확인 @태그 배지)과 내 업무(접이식, 기본 접힘 — 업무를 고르면 팝업이 열리며 다시 접힌다)가 있다. 예전 화면 오른쪽에 항상 떠 있던 "내 업무" 패널은 없앴고 이 메뉴가 그 역할을 대신한다(레이아웃도 3열 → 2열).
    • 달력 — FullCalendar. 업무를 시작~마감 기간으로 표시. 클릭 편집.
    • 타임라인 — vis-timeline(간트형). 기간 있는 업무만.
    • 보드 — 세션별 칸반. 세션은 아사나처럼 가로로 계속 늘어난다 — 화면을 넘치면 아래로 접히지 않고 보드가 가로로 스크롤된다(.pj-board-canvas = flex + width:max-content, 막대는 attachHScrollIndicator 가 직접 그린다. 예전 매이슨리 절대배치는 제거). 카드 안의 담당자/마감일을 클릭하면 그 자리에서 바로 바꾼다(담당자=멤버 목록 메뉴, 마감일=날짜 입력칸 + 지우기). 값이 없는 칩은 카드에 마우스를 올리면 흐리게 나타난다. 카드 드래그로 세션 이동(PUT /api/tasks/{id} stage_id, 멀티호밍된 업무는 POST /api/tasks/{id}/links). 같은 세션 안에서 드래그하면 이동이 아니라 카드 순서만 바꾼다(PUT /api/projects/{id}/stages/{stage_id}/tasks/order, 세션 재정렬과 같은 패턴 — tasks.sort_order를 그 세션 소속만 0부터 재배정). 세션 컬럼 자체도 드래그로 재정렬(§1-1).
    • 리스트 — 표.
    • 4개 뷰 모두 툴바의 "이 프로젝트"/"전체 프로젝트" 스코프 토글을 따른다(§1-1).
    • 라이브러리는 현재 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) 마이그레이션 002~006 적용 (첨부/알림, 세션 생성자·하위업무·멀티호밍,
#    업무 시간, 세션 색상, 댓글 첨부, @태그)
docker exec -i postgres-db psql -U postgres -d project_db \
    < scripts/sql/project_db_002_attachments_notifications.sql
docker exec -i postgres-db psql -U postgres -d project_db \
    < scripts/sql/project_db_003_sections_subtasks_links.sql
docker exec -i postgres-db psql -U postgres -d project_db \
    < scripts/sql/project_db_003_task_times.sql
docker exec -i postgres-db psql -U postgres -d project_db \
    < scripts/sql/project_db_004_stage_color.sql
docker exec -i postgres-db psql -U postgres -d project_db \
    < scripts/sql/project_db_005_comment_attachments.sql
docker exec -i postgres-db psql -U postgres -d project_db \
    < scripts/sql/project_db_006_mentions.sql

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

⚠️ 003 안에는 기존 tasks.description(일반 텍스트)을 안전한 HTML로 바꾸는 1회성 UPDATE 문이 있다(설명란이 contenteditable 로 바뀌어 이제 description 을 항상 HTML로 취급하기 때문). 두 번 실행하면 이중 이스케이프되니 꼭 한 번만 돌릴 것.

5-1. 설명란 링크 · @태그(멘션)

  • 설명란 링크 — 업무 편집 팝업의 설명란(contenteditable)에 웹주소를 붙여넣으면 자동으로 <a target="_blank" rel="noopener noreferrer"> 가 된다(linkifyToHtml). contenteditable 안에서는 브라우저가 링크를 기본으로 열지 않으므로 클릭을 직접 받아 새 탭으로 연다. 서식바의 링크 버튼으로 만든 링크도 같은 속성으로 맞춘다 (normalizeEditorLinks). 저장 시 sanitizer 가 a 의 href/target/rel 만 통과시킨다.
  • @태그(멘션) — 설명란·댓글 입력칸에서 @ 를 누르면 등록된 프로젝트 멤버 목록이 뜨고 (GET /project/api/all-users), 고르면 · 설명란: <span class="pj-mention" data-email="...">@아이디</span> 칩 · 댓글: @아이디 평문 + 이메일을 화면이 따로 기억해 전송 시 mentions 로 함께 보냄. 서버는 설명란은 저장될 HTML 에서 직접 이메일을 뽑고(store.extract_mentions_from_html, 화면이 보낸 목록을 믿지 않는다), 댓글은 받은 목록을 정규화해 쓴다. 새로 태그된 사람에게만 알림(type=mention)이 생긴다 — 같은 자리에서 중복 저장 안 됨.
  • 수신함 (/project/inbox) — 위쪽 "나를 태그한 업무"(업무 1건당 1행, 최근 태그순. 누르면 확인 처리, "열기"는 ?task= 로 그 업무 편집 팝업까지 연다) + 아래쪽 "알림". 내 업무·프로젝트 화면과 같은 2단 레이아웃(좌측 공용 사이드바 + 우측 프레임)이다. API: GET /api/mentions, GET /api/mentions/unread-count, POST /api/mentions/read (task_id 주면 그 업무만, 없으면 전부). 006 마이그레이션이 아직 안 돌아간 환경에서도 화면이 죽지 않게 조회/기록은 모두 감싸져 있다.

6. 댓글 · 첨부 · 알림센터 · 세션 편집 (구현됨)

  • 댓글 task_comments — 업무 모달 하단. 등록/삭제(본인·관리자). 새 댓글 시 관련자 인앱 알림.
  • 업무 편집 팝업 — 윗줄은 메타(좌) + 첨부/연결/댓글(우) 2단, 그 아래 설명란과 하위 업무가 각각 팝업 너비 전체를 쓰는 별도 행(.pj-desc-block / .pj-subtask-full, 그리드 1 / -1). 하위 업무는 제목 왼쪽 체크박스로 완료를 토글하고, 완료된 줄은 반투명(50%) + 취소선. 좁은 화면과 "새 업무"(compact)에서는 단일 컬럼으로 흐른다.
  • 첨부 task_attachments — 업무 모달. 파일 업로드(최대 20MB)/다운로드/삭제. 실제 파일은 DATA_DIR/project/<task_id>/<uuid>.<ext>, DB엔 메타만. 첨부 디렉토리는 운영 볼륨(DATA_DIR)에 저장돼 재배포에도 보존. 설명란 이미지 삽입도 이 표를 재사용(§1-1).
  • 세션 편집 — 보드 칸반 헤더에서 이름변경/완료토글/삭제, 트레일링 "+ 세션 추가", 컬럼 드래그로 순서 변경. PUT .../stages/order, PUT .../stages/{id}, 삭제는 만든 사람만.
  • 알림센터(인앱) project_notifications — 배정/완료/댓글 시 수신자별 알림 생성. 우측 상단 벨(미읽음 배지) → /project/inbox. 항목 클릭=읽음, "모두 읽음". 본인 행동은 알림 제외.
  • 마이그레이션: scripts/sql/project_db_002_attachments_notifications.sql (첨부·알림 테이블 + 권한), scripts/sql/project_db_003_sections_subtasks_links.sql (세션 생성자·하위업무·멀티호밍).

7. 추후 단계

검색/필터 · 업무 라벨(태그 분류) · 하위 업무의 하위 업무(다단계 중첩, 아사나도 UI상 1단계만 허용해 현재 의도적으로 안 함).