# 프로젝트 관리 모듈 (아사나식) — `app/modules/project/`
> 회사(dbxcorp.co.kr) 직원이 프로젝트→섹션→작업 3단계 구조를 캘린더/타임라인/
> 보드로 관리하는 아사나(Asana) 스타일 협업 모듈. DB는 `project_db` 전용.
**화면 용어는 아사나 한국어판에 맞춘다(2026-09-25 통일)** — 새 화면·메시지도 이 표를 따른다.
작업(예전 "업무") · 하위 작업 / 상위 작업 · 내 작업 · 섹션(예전 "세션"·"단계") ·
협업자(예전 "팔로워", 버튼은 "협업자로 참여 / 협업자에서 나가기" — 예전 "팔로우 / 팔로우 취소") ·
목록(보기 탭, 예전 "리스트") · 캘린더(예전 "달력") · 수신함 · 첨부 파일 · 작업 링크 복사 ·
프로젝트 칸 + "다른 프로젝트에 추가"(예전 "연결된 프로젝트") · 담당자 없음(예전 "(미지정)").
"@태그"는 그대로 쓴다. 코드 식별자·DB 컬럼(`tasks`, `stage_id`, `task_followers` 등)과 코드 주석은 예전 이름 그대로다.
**도움말** — `/project/help`(`project/help.html` + `static/project-help.css`), 프로젝트 관리 화면 상단 바 로그아웃
오른쪽 **?** 아이콘(`_help_btn.html`, `erp_base.html` 의 `topbar_after_logout` 블록)으로 새 탭에서 연다. 처음 쓰는 사람용
기능 설명 20장 — **화면 기능을 바꾸면 도움말도 같이 고친다.**
**멤버 이름 표기** — 이메일 아이디의 첫 글자만 대문자(king → King). JS 는 `idOf(email)`/`capName(s)`,
템플릿은 `{{ nm[:1]|upper }}{{ nm[1:] }}` 로 화면에 그릴 때만 바꾼다(API `id`·DB 값은 그대로 — 멘션·검색은 이메일 기준).
**프로젝트 색상·아이콘(아사나식)** — 색상표는 아사나 프로젝트 16색(`store.COLOR_PALETTE`, 8칸×2줄, 새 프로젝트
기본은 파랑 `DEFAULT_PROJECT_COLOR`). 예전 팔레트 색으로 만든 프로젝트는 그 색 그대로(수정 팝업이 첫 칸으로
바꾸지 않는다). 아이콘은 아사나 프로젝트 아이콘과 같은 종류 42개를 Material Symbols 이름으로(`store.PROJECT_ICONS`
— 아사나의 실제 아이콘 이미지는 쓰지 않는다), `projects.icon`(마이그레이션 011, NULL = 색 + 첫 글자).
새 프로젝트·프로젝트 수정 팝업의 "아이콘" 격자(`renderIconPalette`, 첫 칸 "Aa" = 아이콘 없음), 사이드바 배지·
제목 알약에 흰 아이콘(`projBadgeInner`). 아이콘은 고르거나 바꿨을 때만 서버로 보내므로 011 전에도 다른 수정은 된다.
**색상표는 모든 편집창이 이 하나** — 섹션 편집도 같은 16색(`STAGE_COLOR_PALETTE = COLOR_PALETTE`). 섹션에서 첫 칸(연회색)은
"색 없음"(NULL, 기본 회색 머리), 예전 10색으로 칠한 섹션은 그대로(`LEGACY_STAGE_COLORS`). 밝은 색(연노랑·하늘·연분홍 등)
위에서는 글자·아이콘을 어둡게(`isLightColor` → `.is-light`: 섹션 머리·사이드바 배지·제목 알약).
## 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`).
받는 쪽은 **같은 프로젝트의 최상위 작업만**(순환 방지), 하위 작업의 하위 작업은 함께 따라간다.
펼친 하위 작업 목록 맨 아래 **"+ 하위 작업 추가"**(아사나, `renderSubAdd`) — 누르면 그 자리에 새 줄
(✓ · "작업 이름 입력" · 점선 달력 · 점선 사람)이 열려 Enter 로 바로 만들고, 줄은 열린 채 다음 입력으로.
Esc 또는 빈 채로 다른 곳을 누르면 닫힘. 보드가 8초마다 다시 그려져도 입력 중인 값·포커스는
`subDrafts` 에서 되살린다.
**하위 작업도 작업과 같은 팝업에서 똑같이 편집**(아사나식) — 보드 카드의 하위 작업 줄 클릭·우클릭 "열기",
작업 팝업 하위 작업 줄의 › 버튼, 공유 링크로 연다(`openTaskById`). 제목 위에 상위 작업 경로
(`#pj-t-parent`, 누르면 상위 작업으로 — `GET /api/tasks/{id}` 가 `parent_title` 을 준다),
섹션 칸·다른 프로젝트 연결은 숨긴다. 저장해도 보드 목록(`tasks`)엔 넣지 않는다(`mergeTask`).
작업 팝업의 하위 작업 줄(`initSubtaskBlock`)도 아사나식 — ⠿ 손잡이로 끌어 순서 변경
(`PUT /api/tasks/{id}/subtasks/order` → `db.reorder_subtasks`), ✓ 완료, 제목 칸은 글자 폭만큼
(`fitTitle`)이고 줄의 빈 곳을 누르면 하위 작업 열기, 마감일은 날짜 글자만(없으면 점선 달력
아이콘, 누르면 아사나식 날짜 팝업 `openDatePopover`), 담당자는 아이콘만(누르면 아이콘+이름 메뉴).
삭제는 우클릭 메뉴(줄에 × 없음).
- **날짜 고르기는 전부 아사나식 날짜 팝업(`openDatePopover`)** — 브라우저 기본 달력(`input[type=date]`)을
화면에 두지 않는다. 보드 카드·작업 팝업·하위 작업 줄은 직접 팝업을 열고, 폼의 날짜 칸(새 프로젝트 마감일,
프로젝트 수정 시작일·마감일(버튼 하나), 하위 작업 추가 마감일)은 `enhanceDateInput` 이 숨긴 input 옆에
날짜 버튼을 붙인다(input 은 값 저장소 — `.value` 읽기/쓰기·change 이벤트 그대로). 새 날짜 칸도 이 함수를 쓴다.
- **멀티호밍(다른 프로젝트에 연결)** — `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` 으로 옮겨져 브라우저 기본 말풍선이 안 뜬다).
> 별도 툴팁 구현 금지 — 부득이하면(대시보드 막대처럼 요소에 붙는 것) 같은 색·꼬리 모양으로.
>
> **댓글 말풍선(💬 N) 규칙** — 보드 카드·목록 행·캘린더 막대·내 작업 어디서든 **한 번 클릭**으로 댓글
> 대화창(`#pj-modal-comments`, `initCommentsChat`)이 열린다. `.pj-cmt-badge[data-task-id]` 만 달면
> 문서 캡처 단계 클릭 처리가 카드/행 클릭(작업 열기)보다 먼저 받아 막으므로 따로 연결할 필요 없다
> (`wireBadge` 는 안 읽음 표시만). 댓글 본문의 웹페이지 주소(`https://…`, `www.…`)는 작업 팝업 댓글·
> 대화창 모두 `linkifyToHtml` 로 새 탭 링크가 된다(나머지 글자는 이스케이프). 대화창 입력칸 붙여넣기는
> 글자가 있으면 글자 우선, 그림만 있을 때 첨부.
>
> **담당자 고르기 규칙 — 모든 화면·앞으로 추가하는 기능 공통.** 담당자를 고르는 곳은 항상 "아이콘 + 이름".
> 팝업 메뉴는 `assigneeMenuItems(emails, cur, onPick)` + `showContextMenu`(항목 `icon`/`checked` 지원), 폼의
> `