# 프로젝트 관리 모듈 (아사나식) — `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`) | | 조회 권한 | 프로젝트 화면(`/p/{id}`)·멤버/세션/업무/활동/스냅샷 API 도 멤버·owner·admin 만(`_require_manage`). 비멤버는 403. `GET /api/users/tasks` 를 프로젝트 없이 부르면 내가 볼 수 있는 프로젝트의 업무만 돌려준다 | | 입력 검증 | URL 의 세션이 URL 의 프로젝트 것인지(`_stage_of_project`), 업무 생성/수정·연결 시 세션이 그 프로젝트 것인지(`stage_in_project`), 하위 업무의 부모가 같은 프로젝트인지 확인 — 권한은 URL 의 project_id 로 보므로 이걸 안 보면 남의 프로젝트를 건드릴 수 있다 | | 삭제 권한 | **프로젝트·세션·업무 모두 "만든 사람만"**(슈퍼관리자 예외, 생성자 정보 없는 과거 데이터는 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). 업무 편집 팝업 안에 인라인으로 표시되며(체크박스+ 제목+담당자+마감일, 한 줄에서 바로 저장), 보드/캘린더/리스트에는 최상위 업무만 카드로 뜬다(하위 업무는 부모 카드의 "N ⤷ ▾" 토글로 — 누르면 아사나처럼 카드 아래로 하위 업무 목록(완료 체크·제목·마감·담당자)이 펼쳐진다. 펼친 상태는 페이지에 머무는 동안 유지). 세션을 갖지 않는다(칸반에 안 보이므로). 펼친 하위 업무 한 줄을 다른 카드로 드래그하면 그 업무의 하위 업무로 옮겨진다 (`POST /api/tasks/{id}/move-parent` `{parent_task_id}` → `db.move_subtask`, 활동 `subtask_moved`). 받는 쪽은 **같은 프로젝트의 최상위 업무만**(순환 방지), 하위 업무의 하위 업무는 함께 따라간다. - **멀티호밍(다른 프로젝트에 연결)** — `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` 가 걸려 `` 로 못 씀 — 그래서 인라인 전용 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. 화면 / 뷰 > **말풍선(툴팁) 규칙 — 모든 화면·앞으로 추가하는 기능 공통.** 말풍선은 아사나식 공용 말풍선 > 하나(`.pj-hovertip`, `initHoverTips`)만 쓴다: 어두운 배경 + 아래 꼬리, 커서 바로 위, 화면 끝이면 > 안쪽으로 밀리고 위가 모자라면 아래로 뒤집힘. 요소에 `data-tip="문구"` 또는 `title="문구"` 만 달면 > 된다(`title` 은 마우스를 올리는 순간 `data-tip` 으로 옮겨져 브라우저 기본 말풍선이 안 뜬다). > 별도 툴팁 구현 금지 — 부득이하면(대시보드 막대처럼 요소에 붙는 것) 같은 색·꼬리 모양으로. > > **담당자 고르기 규칙 — 모든 화면·앞으로 추가하는 기능 공통.** 담당자를 고르는 곳은 항상 "아이콘 + 이름". > 팝업 메뉴는 `assigneeMenuItems(emails, cur, onPick)` + `showContextMenu`(항목 `icon`/`checked` 지원), 폼의 > `