# 프로젝트 관리 모듈 (아사나식) — `app/modules/project/`
> 회사(dbxcorp.co.kr) 직원이 프로젝트→섹션→작업 3단계 구조를 캘린더/타임라인/
> 보드로 관리하는 아사나(Asana) 스타일 협업 모듈. DB는 `project_db` 전용.
**화면 용어는 아사나 한국어판에 맞춘다(2026-09-25 통일)** — 새 화면·메시지도 이 표를 따른다.
작업(예전 "업무") · 하위 작업 / 상위 작업 · 내 작업 · 섹션(예전 "세션") · 협업자(예전 "팔로워") ·
목록(보기 탭, 예전 "리스트") · 캘린더(예전 "달력") · 수신함 · 첨부 파일 · 작업 링크 복사 ·
프로젝트 칸 + "다른 프로젝트에 추가"(예전 "연결된 프로젝트") · 담당자 없음(예전 "(미지정)").
"@태그"는 그대로 쓴다. 코드 식별자·DB 컬럼(`tasks`, `stage_id`, `task_followers` 등)과 코드 주석은 예전 이름 그대로다.
## 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`).
받는 쪽은 **같은 프로젝트의 최상위 작업만**(순환 방지), 하위 작업의 하위 작업은 함께 따라간다.
**하위 작업도 작업과 같은 팝업에서 똑같이 편집**(아사나식) — 보드 카드의 하위 작업 줄 클릭·우클릭 "열기",
작업 팝업 하위 작업 줄의 › 버튼, 공유 링크로 연다(`openTaskById`). 제목 위에 상위 작업 경로
(`#pj-t-parent`, 누르면 상위 작업으로 — `GET /api/tasks/{id}` 가 `parent_title` 을 준다),
섹션 칸·다른 프로젝트 연결은 숨긴다. 저장해도 보드 목록(`tasks`)엔 넣지 않는다(`mergeTask`).
- **멀티호밍(다른 프로젝트에 연결)** — `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` 지원), 폼의
> `