Files
dbx-main/docs/PROJECT_MODULE.md
T

430 lines
40 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 프로젝트 관리 모듈 (아사나식) — `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` 가 걸려 `<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. 화면 / 뷰
> **말풍선(툴팁) 규칙 — 모든 화면·앞으로 추가하는 기능 공통.** 말풍선은 아사나식 공용 말풍선
> 하나(`.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` 지원), 폼의
> `<select>` 는 `enhanceAssigneeSelect(sel)` 로 감싼다(select 는 숨겨 값 저장소로 유지). 미지정 = 점선 원 사람 아이콘.
>
> **날짜 규칙.** 마감일(시작일) 고르기는 아사나식 팝업 `openDatePopover(anchor, {start, due, allowStart, onChange})`
> 하나만(브라우저 기본 date 캘린더 금지). 마감일 표기는 `dueInfo(iso, done)` — 어제(빨강)·오늘/내일(초록)·그 밖 mm/dd(요일),
> 지난 날짜 빨강, 완료 작업은 색 없음.
- **내 작업** (`/project/`): 프로젝트 모듈의 첫 화면. 예전 홈(프로젝트 카드 그리드)은
**없앴다** — 좌측 "내 작업" 메뉴와 같은 화면이다(`project/mytasks.html`).
내가 담당자인 작업을 한 표에 모아 보여준다: 완료 체크박스 · 작업 · 프로젝트 · 섹션 ·
우선순위 · 시작 · 마감. 헤더 클릭으로 정렬, 상단 탭으로 진행 중/완료/전체 필터,
오른쪽에 진행/완료/지연 요약. 체크박스는 그 자리에서 완료 토글, 행을 누르면 그
프로젝트로 이동하며 작업 편집 팝업이 열리고(`?task=`), 우클릭은 열기/완료/삭제 메뉴.
완료된 작업 행은 반투명 + 취소선. 8초 주기로 목록을 다시 받는다.
표/목록 화면이라 본문 폭은 1180px 로 제한한다(보드·캘린더 등 프로젝트 뷰는 전체 폭).
좌측 사이드바는 프로젝트·수신함 화면과 공용(`project/_side.html`, `side_active` 로
활성 메뉴 표시) — 수신함 · 내 작업 ·
프로젝트 트리(+ 새 프로젝트) · "전체 멤버". 프로젝트 트리는 **수신함·내 작업·휴지통·프로젝트
네 화면 모두 같다** — 관리자에게 드래그 순서 변경(⣿)·✎ 수정·× 삭제·우클릭 메뉴(공용
`initSideTree`, 모달은 `project/_side_modals.html` 을 각 화면이 include). "전체 멤버"는 **관리자(`is_admin`)에게만**
그리고 수신함·내 작업·프로젝트 화면 모두에서 나온다. 아이콘 클릭 = 그 사람의 담당 작업
팝업(`_member_tasks_modal.html`, `initMemberTasks`) — 프로젝트 화면에선 더블클릭 시 그 자리에서
편집 팝업, 다른 화면에선 그 작업의 프로젝트 화면(`?task=`)으로 이동.
- **프로젝트** (`/project/p/{id}`): 좌측 사이드바(공용 `_side.html`) + 우측 뷰 토글.
좌측 "내 작업"는 접이식 패널이 아니라 `/project/` 로 가는 링크다.
**이 프로젝트의 멤버는 화면 위 제목 오른쪽**에 겹친 아바타로 둔다(`.pj-title-members`) —
마우스를 올리면 이름(`data-tip`, `initHoverTips` 가 위임 방식이라 동적 요소에도 붙는다),
클릭하면 그 사람이 이 프로젝트에서 맡은 작업 팝업, 우클릭(관리자)하면 제외, 옆 `+` 는 멤버 배정.
좌측 트리의 작업 클릭도 페이지 이동 없이 바로 팝업(이미 로드된 전체 작업 데이터 사용).
좌측 맨 위 **수신함**(미확인 @태그 배지)과 **내 작업**(접이식, 기본 접힘 — 작업을 고르면
팝업이 열리며 다시 접힌다)가 있다. 예전 화면 오른쪽에 항상 떠 있던 "내 작업" 패널은 없앴고
이 메뉴가 그 역할을 대신한다(레이아웃도 3열 → 2열).
- **캘린더** — FullCalendar. 작업을 시작~마감 기간으로 표시. 클릭 편집.
- **타임라인** — vis-timeline(간트형). 기간 있는 작업만.
- **대시보드** — 합계 타일 4개 + 미완료 작업(섹션별)·작업 합계(완료 상태별) 차트. **"예정된 작업 합계
(담당자별)" 차트는 관리자(`is_admin`)에게만** 보인다(사람별 업무량이 드러나서). 화면 표시만 막는 것 —
작업 데이터 자체는 멤버가 원래 볼 수 있는 범위 그대로다.
- **보드** — 섹션별 칸반. 섹션은 아사나처럼 **가로로 계속 늘어난다** — 화면을 넘치면
아래로 접히지 않고 보드가 가로로 스크롤된다(`.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. 배포
```bash
# 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~008 적용 (첨부/알림, 섹션 생성자·하위 작업·멀티호밍,
# 작업 시간, 섹션 색상, 댓글 첨부, @태그)
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_003b_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
docker exec -i postgres-db psql -U postgres -d project_db \
< scripts/sql/project_db_007_live_version.sql
docker exec -i postgres-db psql -U postgres -d project_db \
< scripts/sql/project_db_008_followers_reminders_search.sql
docker exec -i postgres-db psql -U postgres -d project_db \
< scripts/sql/project_db_009_stage_default_assignee.sql
docker exec -i postgres-db psql -U postgres -d project_db \
< scripts/sql/project_db_010_trash.sql
docker exec -i postgres-db psql -U postgres -d project_db \
< scripts/sql/project_db_011_project_icon.sql
docker exec -i postgres-db psql -U postgres -d project_db \
< scripts/sql/project_db_012_comment_replies_reactions.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 마이그레이션이 아직 안 돌아간 환경에서도 화면이 죽지 않게 조회/기록은 모두 감싸져 있다.
## 5-2. 작업 공유 링크 (퍼머링크)
- 작업 편집 팝업의 **공유** 버튼(`#pj-share-task`)이 `{origin}/project/t/{task_id}` 를
클립보드에 복사한다. 보드/목록/캘린더/타임라인 카드 우클릭과 내 작업 목록
우클릭의 "링크 복사"도 같은 함수(`shareTaskLink`)를 쓴다.
`navigator.clipboard` 는 https 에서만 동작하므로 임시 textarea 폴백을 두고,
둘 다 실패하면 주소를 `prompt` 로 보여준다.
- `GET /project/t/{task_id}` 는 권한만 확인하고 `/project/p/{project_id}?task=` 로
넘긴다(화면은 기존 경로가 그린다 — 작업이 다른 프로젝트로 옮겨가도 링크는 산다).
- 로그인 전이면 `/login?next=/project/t/{id}` 로 보내 **로그인 후 그 작업으로 복귀**.
- `project` 모듈 권한 없음 / 작업 없음 / 그 프로젝트 멤버 아님 → 각각 403·404·403
안내 화면(`denied.html`). 즉 **주소를 알아도 멤버가 아니면 못 본다**.
- 하위 작업 링크도 그 하위 작업 자신의 팝업으로 연다(목록엔 없으니 `GET /api/tasks/{id}` 로 받아 연다).
- `?task=` 로 들어왔는데 그 작업이 화면 목록에 없으면(완료 섹션 필터 등)
`GET /api/tasks/{id}` 로 그 작업만 받아 팝업을 연다.
## 6. 댓글 · 첨부 · 수신함 · 섹션 편집 (구현됨)
- **댓글** `task_comments` — 작업 모달 하단. 등록/삭제(본인·관리자). 새 댓글 시 관련자 인앱 알림.
- **작업 편집 팝업** — 버튼 줄(공유·완료·삭제·저장 상태·패널 접기)은 **팝업 맨 위에 고정**
(`.pj-modal-actions-top`) — 카드가 flex column 이고 `.pj-modal-body` 만 스크롤하므로 sticky 없이 고정된다(sticky 는 카드 padding 안쪽에 붙어 바가 밀려 내려오고 제목을 덮었다). 저장 버튼은 없다 — 실시간 저장(§6-6).
그 아래 메타(담당자·섹션·우선순위·마감일 한 줄 — 마감일은 캘린더 아이콘 버튼, 좁으면 2×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` (섹션 생성자·하위 작업·멀티호밍).
## 6-1. 실시간 반영 · 성능
- **live-version** — `GET /api/live-version` 이 돌려주는 값이 바뀌면 화면이 조용히 다시 받는다.
007 마이그레이션의 문장 단위 트리거가 projects·members·stages·tasks·comments·attachments·
links(+ mentions INSERT) 변경 때마다 `project_live_version.version` 을 1 올린다 — 삭제·섹션
이름변경·첨부 추가까지 감지되고, 서버는 PK 한 줄만 읽는다. 007 미적용이면 예전 MAX() 방식
(삭제 감지 못함)으로 자동 폴백하고 5분마다 다시 확인한다.
- 화면은 열자마자 기준값을 잡고, 탭이 안 보이는 동안(`document.hidden`)은 묻지 않는다.
바뀌면 `GET /api/projects/{id}/snapshot`(작업+섹션+멤버 한 번에)으로 이 프로젝트 맥락의
행을 통째로 바꿔 끼운다(삭제된 작업도 사라짐).
- 프로젝트 화면은 접근 가능한 모든 프로젝트의 작업/섹션을 각각 **쿼리 한 번**으로 읽는다
(`list_tasks_for_projects`, `list_stages_for_projects`). 행마다 `context_project_id`·
`is_linked`·`home_stage_id` 가 붙는다 — 연결 작업 행의 `stage_id` 는 연결된 쪽 섹션이고,
작업 편집 팝업의 "섹션" 선택은 항상 `home_stage_id`(원래 소속)를 쓴다.
- 라우터 핸들러는 전부 `def`(sync) — DB 드라이버가 동기라 `async def` 면 쿼리 동안 이벤트
루프 전체가 멈춘다. 첨부 업로드는 한도+1 바이트까지만 읽는다.
- 첨부 `/inline` 은 png/jpeg/gif/webp/bmp 만 화면에 띄우고 나머지(html·svg 등)는 다운로드로
내려준다(`X-Content-Type-Options: nosniff` + CSP sandbox). 작업/프로젝트/댓글 삭제 시
디스크 첨부도 같이 지운다.
- 설명란 sanitizer 는 URL 을 허용 목록(http/https/mailto/tel/상대경로, img 는 png·jpeg 등
data: 이미지)으로 검사한다 — 금지 목록은 `jav&#x09;ascript:` 로 우회됐다.
## 6-2. 검색 · 필터 · 정렬
- **전체 검색** — 좌측 사이드바 맨 위 검색창(`#pj-global-search`, 어디서든 `/` 키). 2글자 이상이면
`GET /api/search?q=` 로 내가 볼 수 있는 프로젝트의 작업(하위 작업 포함)를 제목·설명·댓글에서
찾는다. 설명은 HTML 이라 DB 에서 넉넉히 가져와 본문 텍스트로 다시 확인한다(태그 이름에만
걸린 결과 제거). 결과에 "설명/댓글" 어디서 걸렸는지와 미리보기. 누르면 `/project/t/{id}`.
008 의 pg_trgm GIN 인덱스(title·description·comment body)가 `ILIKE '%…%'` 를 받쳐준다.
- **필터 바** — 프로젝트 화면(`#pj-filterbar`): 찾기(제목·설명·담당자·섹션) · 상태 · 담당자
(나/없음/특정인) · 마감(지남/오늘/이번 주/없음) · 우선순위 · 정렬(기본/마감일/우선순위/제목/
담당자/최근 생성). 서버 재조회 없이 `visibleTasks()`(스코프 → 필터 → 정렬)에서 거르므로
보드·목록·캘린더·타임라인·대시보드 모두에 적용된다. 프로젝트별로 localStorage 에 기억.
필터나 정렬이 켜져 있으면 보드 카드 순서 드래그는 막는다(가려진 카드 때문에 순서가 어긋남).
목록은 열 제목 클릭 정렬이 우선. 내 작업 화면에도 찾기·마감·우선순위 필터(`#pj-mt-filterbar`).
공용 로직: `taskMatchesFilter` / `sortTasksBy`.
## 6-3. 협업자 · 마감 알림
- **협업자**(`task_followers`, 008) — 아사나의 협업자. 작업 팝업 메타 목록의 "협업자" 줄에서
추가(+ → 프로젝트 멤버)/빼기(×)/내 팔로우 토글. 즉시 저장(저장 버튼과 무관).
자동 팔로우: 만든 사람 · 담당자(배정 시) · 댓글 단 사람 · @태그된 사람. 008 이 기존 작업에도
같은 규칙으로 백필한다. API: `GET/POST /api/tasks/{id}/followers`(body `email`, 없으면 나),
`DELETE /api/tasks/{id}/followers/{email}` — 다른 사람은 그 프로젝트 멤버·owner·관리자만 추가 가능.
- **알림 수신자 변경** — 완료·댓글 인앱 알림은 이제 "담당자 + 협업자"에게만 간다(예전: 프로젝트
멤버 전원). 008 미적용이면 예전 방식으로 폴백.
- **마감 알림**(`reminders.py`) — 웹 프로세스 안 데몬 스레드가 5분마다 깨어, 영업일(주말·
`KR_HOLIDAYS` 제외) 설정 시각(`PROJECT_REMINDER_HOUR`, 기본 9시 KST) 이후 하루 한 번 돈다.
`due_soon`(다음 영업일까지 마감 — 금요일이면 주말·월요일분까지) · `due_today` · `overdue`
(최근 7일 이내 마감분). 수신자는 담당자, 없으면 협업자. `task_reminders` UNIQUE(작업·종류·
마감일·수신자)로 한 번만 — 재기동·중복 실행에도 안전, 마감일을 바꾸면 다시 알린다.
`PROJECT_REMINDER_EMAIL=true` 면 사람별 요약 메일 1통(SMTP 필요). `PROJECT_REMINDERS=false` 로 끔.
## 6-4. 섹션 기본 담당자 (마이그레이션 009)
- `project_stages.default_assignee_email`(TEXT, '' = 미지정). 섹션 편집 창(✎ / "+ 섹션 추가")의
"기본 담당자" 에서 지정 — 후보는 작업 담당자와 같다(프로젝트 멤버 + owner, 서버도 검증).
- **자동 배정 규칙**(`db._stage_default_assignee`) — 담당자가 **비어 있는** 작업만:
· 그 섹션에 작업 생성(`create_task`, 하위 작업 제외)
· 다른 섹션에서 그 섹션으로 이동(`update_task` 의 `stage_id` 변경 — 카드 드래그·작업 팝업 섹션 변경)
이미 담당자가 있으면 그대로. 지정된 사람이 프로젝트 멤버에서 빠졌으면 무시.
자동 배정도 일반 배정과 같이 활동이력·협업자·인앱 알림·메일이 나간다(`_newly_assigned`).
멀티호밍으로 연결된 프로젝트 쪽 섹션 이동(`/links`)은 대상 아님.
- 보드 섹션 머리 이름 옆에 기본 담당자 아바타(작게, 툴팁). 새 작업 팝업은 그 섹션 기본 담당자를 미리 채운다.
- 009 미적용이어도 앱은 동작 — 조회는 `to_jsonb(행)->>'default_assignee_email'` 로 컬럼 유무와
무관, 지정 시도만 503("마이그레이션 009 필요"). 화면은 기본 담당자가 바뀐 경우에만 필드를 보낸다.
## 6-5. 휴지통 (마이그레이션 010)
- 작업을 지우면(하위 작업 CASCADE 포함) **지우기 직전 스냅샷**을 같은 트랜잭션에서 `project_trash.payload`(JSONB)에
남긴 뒤 예전처럼 삭제한다(`db.delete_task` → `(ids, trash_id)`). 스냅샷 = `tasks` + 딸린 테이블
`task_comments · task_followers · task_mentions · task_attachments · task_project_links · project_activity ·
task_reminders`(`TRASH_CHILD_TABLES`). 알림(`project_notifications`)은 되살리면 수신함이 옛 알림으로 차서 제외.
모든 조회 쿼리에 "삭제됨" 필터를 넣는 소프트 삭제 대신 이 방식 — 기존 화면·쿼리를 안 건드린다.
- 첨부 실물은 지우지 않고 `DATA_DIR/project/_trash/<trash_id>/<task_id>/` 로 옮긴다(복구 시 되돌림).
- **보관 3개월**(`expires_at`). 휴지통 화면을 열거나 작업을 지울 때 만료분을 영구 삭제(`_purge_trash`).
- **관리자 전용**: 좌측 "휴지통" 메뉴·`/project/trash` 화면·`POST /project/api/trash/{id}/restore` 모두 `is_admin`.
복구는 원래 id 그대로(`restore_trash`): 같은 id 가 이미 있으면 거부, 프로젝트가 지워졌으면 거부, 하위 작업만
지웠는데 상위가 없으면 거부(상위 먼저 복구). 지워진 섹션은 섹션 없이, 지워진 프로젝트를 가리키는 연결/이력은 뺀다.
복구하면 휴지통 행은 지운다.
- 화면: 삭제 확인은 `confirmTaskDelete` 하나 — 하위 작업이 있으면 "하위 작업 N개까지 모두 삭제"를 분명히 묻는다.
카드의 하위 작업 줄 우클릭 = 열기 / 완료 / **하위 작업 삭제**. 삭제 후 토스트 "휴지통으로 옮겼습니다".
- 010 미적용이면 휴지통 없이 예전처럼 영구 삭제(휴지통 화면에 안내).
- 프로젝트 삭제(작업 전체 CASCADE)와 댓글 삭제는 아직 휴지통 대상이 아니다.
## 6-6. 작업 창 실시간 저장 · 제목 줄바꿈 · 프로젝트 제목 바로 수정
- **저장 버튼 없음**(아사나식). 칸마다 바로 `PUT /api/tasks/{id}` 로 **그 필드만** 보낸다(`saveField`) —
제목: blur/Enter(빈 값이면 되돌림) · 설명: 입력 멈춤 1.2초·blur(이미지 업로드 중이면 미룸) ·
담당자/섹션/우선순위/마감일: change 즉시. 요청은 `saveChain` 한 줄로 순서 보장, 보낼 값·id 는 부르는
순간 잡으므로 저장 중 다른 작업을 열어도 안전. 닫기·다른 작업 열기 직전 `flushAutoSave`. 버튼 줄에
"저장 중… / ✓ 저장됨 / 저장 실패" 표시(`#pj-autosave-state`).
- **새 작업**은 제목이 처음 생기는 순간 지금 칸 값으로 `POST` → 기존 작업 화면(댓글·첨부·하위 작업)으로
바꿔 연다. 그 사이 더 친 제목·설명은 이어서 저장. 제목 없이 닫으면 만들지 않는다.
- 섹션을 옮기면 서버가 기본 담당자를 넣거나 완료 처리할 수 있어 응답으로 담당자 칸·완료 버튼을 다시 맞춘다.
- 작업 제목칸은 `textarea`(자동 높이, `fitTitleHeight`) — 긴 제목은 다음 줄로. Enter·붙여넣은 줄바꿈은 막는다.
- 프로젝트 화면 제목 알약(`.pj-pill-name`)은 마우스 올림 → 테두리, 클릭 → contenteditable 로 이름 수정
(`PUT /api/projects/{id}` `{name}`, Enter/blur 저장·Esc 취소). `can_manage` 인 사람만.
## 6-7. 댓글 답글 · 이모티콘 반응 · 완료 이력 · @칩 (마이그레이션 012)
- `task_comments.parent_id`(답글, 한 단계 — 답글의 답글도 원 댓글에 붙음, 원 댓글 삭제 시 CASCADE) +
`task_comment_reactions`(comment_id·user_email·emoji PK, `task_id` 는 휴지통 스냅샷용 —
`TRASH_CHILD_TABLES` 에 포함). 012 트리거로 반응도 live-version 을 올린다.
- API: `GET /api/tasks/{id}/comments` → `{comments(+reactions), events, features}` —
`events` 는 `project_activity` 의 완료(`completed`) 이력 — **작업이 지금 완료 상태일 때 마지막 1건만**
(완료 취소하면 사라짐, 이력 행은 보존), 댓글 수에는 안 셈. `features` 는 012 적용 여부.
`POST /api/tasks/{id}/comments` 에 `parent_id`. `POST /api/comments/{id}/reactions` `{emoji}` = 켜기/끄기 토글.
- 화면: 작업 창 댓글은 시간순(댓글 + "OO 님이 이 작업을 완료했습니다" 줄), 답글은 원 댓글 아래 들여쓰기 +
답글 입력칸. 마우스 올림 도구 모음(👍 👀 🙌 ✅ · 반응 추가(이모티콘 창) · 답글 · 수정 · 삭제).
댓글 대화창은 말풍선 위 인용으로 답글 표시, 입력칸 위 "OO 님에게 답글" 줄.
본문의 `@아이디` 는 사용자 목록(`/api/all-users`)과 맞으면 아이콘+이름 칩(`commentBodyHtml`).
- 012 미적용이면 답글·반응 버튼이 숨겨지고, API 는 503 "마이그레이션 012 필요". 완료 이력·@칩은 012 없이도 동작.
## 6-8. 수신함 오른쪽 작업 창 · 화면 배율
- 수신함의 "확인"(예전 "이동"/"열기")은 페이지를 떠나지 않고 오른쪽 패널(`.pj-inbox-panel`)에 작업 창만 띄운다.
프로젝트 화면을 `?task={id}&embed=1` 로 iframe 에 열고, `html.pj-embed` 가 작업 창 외에는 숨긴다.
작업 창을 닫으면 iframe 이 `postMessage({type:"pj-embed-close"})` → 패널 닫힘. Ctrl+클릭은 새 탭(예전처럼 이동).
- 화면 배율 토글(상단 바 `fit_screen`, `_help_btn.html`) — `html.pj-ui-scale` 이면 `.erp-app` 에 `zoom: .75`
(2880×1620·200% = CSS 폭 1440px 에서 1920 기준 화면처럼). zoom 안에서 줄어드는 `vh` 높이는 배율로 나눠
되돌린다. 팝업은 전부 `body` 에 붙어 배율 밖이라 좌표 보정 불필요(전체 검색 결과창도 body 로 옮김),
배율 안에서 마우스 거리로 크기를 바꾸는 작업 창 너비 조절만 `uiZoom()` 으로 나눈다. localStorage `pj_ui_scale`.
## 7. 추후 단계
작업 라벨(태그 분류) · 반복 작업 · 템플릿 · 작업 의존성 · 하위 작업의 하위 작업(다단계 중첩,
아사나도 UI상 1단계만 허용해 현재 의도적으로 안 함).