Files
dbx-main/app/modules/project/CLAUDE.md
T
king 7540bc5610 feat(project): 주간 회의록 항목 사이 가로선 검정 · 같은 항목 하위 줄 사이만 회색
- markMeetSecEnds 가 칸 바로 아래 줄이 새 항목이면 .is-item-end(검정), 아니면 회색
- 구역 경계 굵은 선은 그대로

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 12:16:46 +09:00

127 lines
17 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/`, `project_db`
> 이 모듈만 고칠 때 읽는 요약. 상세는 `docs/PROJECT_MODULE.md` — **178KB 큰 문서, 통째로 읽지 말 것.**
> `grep -n '^#' docs/PROJECT_MODULE.md` 로 목차를 보고 해당 절(아래 괄호의 6-x 번호)만 offset/limit 으로 읽는다.
> 정적 파일: `app/static/project*.js|css`(`project.js`·`project.css`·`project-goal-*`·`project-meeting-*`·`project-options.js`·`project-help.*`·`project-fonts.css`), `erp-overdue.js|css`.
> 템플릿: `templates/project/`. PC 알림 프로그램: `desktop/notifier/`.
> 다른 모듈과 연결: 긴급 공지(`notice`)가 `ProjectStore.pool` 공유 · 회의록 머리 카드가 실적 `performance_store` 매출 읽기 · 회의록 보드는 `app/integrations/google_slides.py`.
## 꼭 지킬 코드 규칙
- 라우터 핸들러는 동기 DB 라 `def` 로 둔다(`async def` 금지).
- 말풍선은 전부 아사나식 공용 말풍선(`.pj-hovertip`) — 새 기능도 `title=`/`data-tip=` 만 달고 별도 툴팁 구현 금지. 모달 대화창 안 말풍선은 popover(top layer).
- 담당자 배정 UI = 아이콘+이름(`assigneeMenuItems` / `enhanceAssigneeSelect`), 글자만 메뉴·기본 select 금지.
- 상단 바 화면 배율 토글(`html.pj-ui-scale` → `.erp-app` zoom .75, 2880×1620·200%용) — **팝업은 반드시 `document.body` 에 붙인다**(배율 안의 fixed 좌표는 어긋남).
- 권한 판단은 **지금 기준 공통 모듈 `access.py`** 하나로(목록·배지·알림·멘션·메일 수신자·삭제·댓글 수정까지 — 멤버에서 빠지면 기록이 있어도 안 보이고 알림도 없음).
- URL 의 섹션·부모 작업이 그 프로젝트 것인지 서버가 검증.
- 용어는 **"업무"**(2026-10-13 "작업"에서 다시 통일 — 화면·메시지·알림 제목, 코드·DB 는 그대로)·"세부 업무"·"메인 업무 추가". ERP 메뉴 이름은 "Project"(`app/main.py` 모듈 목록 title).
- 화면 기능을 바꾸면 도움말(`/project/help`)도 같이 고친다.
- UI 버그는 로컬 헤드리스 크롬/엣지로 렌더·좌표 덤프해 재현 후 고칠 것.
## 권한 — 관리자 등급 4단계 (2026-10-12, 6-14)
- **수퍼관리자(`SUPER_ADMIN_EMAIL` 한 명 고정, 추가 불가) > Admin(`role=admin`) > Pro user(`role=pro`) > User**.
- 판단: `access.is_pro`(Pro user 이상)·`access.is_project_admin`(Admin 이상), 라우터 `_require_pro`, 화면 `pj_pro`·`pj_admin`(`_role_ctx`). `is_admin` 은 ERP 상단 관리자 메뉴용 그대로. pro 는 프로젝트 모듈 밖에서는 user 와 같다.
- Pro user 이상: 새 프로젝트·프로젝트 이름/색/아이콘/소유자 수정·멤버 배정(자기가 멤버인 프로젝트)·사이드바 순서·남의 댓글 수정/삭제·휴지통·전체 보기·담당자별 합계·전체 멤버·소유자 변경.
- Admin 이상 또는 만든 사람: 프로젝트·섹션 삭제. 멤버 누구나: 작업 삭제·서브프로젝트(표는 6-14).
- 진입 권한키 `project`(관리자 페이지 토글로 직원별 부여, admin 자동).
- 배정 멤버(또는 owner)만 그 프로젝트를 조회 — **관리자도 멤버가 아니면 안 보임, 예외는 슈퍼관리자뿐**(2026-10-07, `access.sees_all_projects`; 사이드바 목록·검색·휴지통·알림도 같은 기준, 화면·API 모두 비멤버 403).
- 연결(멀티호밍)된 작업은 연결된 프로젝트 멤버에게 읽기 전용(6-10).
- 멤버 배정 후보는 `project` 권한 보유 등록 사용자에서 자동 목록(`GET /project/api/assignable-users`).
## 구조 / 데이터
- 프로젝트/서브프로젝트(self-FK `parent_id`, CASCADE) → 진행단계(`project_stages`, 칸반 섹션) → 작업(`tasks`: 담당자·우선순위·시작/마감).
- 멤버 배정(`project_members`)·활동이력(`project_activity`).
- 프로젝트 색상 32색(아사나 16색 + 진한 16색, 수정 창 12열).
- 아이콘(`projects.icon`, Material Symbols 42종, 마이그레이션 011 + [아사나 아이콘] 탭 33종 `"asana:"+이름`, 채워진 모양 전용 부분 글꼴 `material-symbols-asana.woff2`).
- 섹션: 새 프로젝트는 섹션 없이 시작 — `create_project(seed_stages=True)` 일 때만 기본 4단계. 섹션 머리는 모두 `#f3f3f3`(섹션별 색 지정 없음), 섹션 이름 굵게.
- 섹션 기본 담당자 `default_assignee_email`(마이그레이션 009) — 담당자 빈 작업을 그 섹션에 만들거나 옮기면 자동 배정. 섹션 제목 오른쪽 담당자 아이콘 = 그 자리에서 지정(6-16).
- 실시간 반영은 `project_live_version` 카운터(마이그레이션 007, 미적용 시 MAX 폴백).
## 화면
- 첫 화면(`/project/`)은 **내 작업 목록**(프로젝트 홈 카드 화면은 폐지). 내 업무 화면 줄 클릭 = 오른쪽 업무 창(iframe).
- 프로젝트 화면은 캘린더(FullCalendar)/타임라인(vis-timeline)/보드/목록/대시보드 뷰 토글.
- 좌측 사이드바는 수신함·내 작업·휴지통·프로젝트 화면 공용(`templates/project/_side.html` + 프로젝트 목록 동작 `initSideTree`, 새 프로젝트/수정 모달 `_side_modals.html`) — 프로젝트 목록(순서 변경·✎·×)은 어느 화면에서나 같다.
- 사이드바 메뉴: 수신함·전체 보기(Pro user 이상 — 예전 오른쪽 위 "전체 프로젝트" 토글, `?scope=all`, 기본 대시보드)·내 작업(접이식)·목표.
- 보드는 아사나처럼 섹션이 가로로 계속 늘어나고(넘치면 가로 스크롤) 카드의 담당자·마감일을 클릭해 그 자리에서 바꾼다.
- 보드 카드 끌기 = 실시간 미리보기(2026-10-19, `startCardDrag`·`placeCardPh`): 원래 카드는 숨기고 점선 자리 표시(`.pj-card-ph`)가 카드 사이로 FLIP 애니메이션, 끄는 모양은 기울어진 복제(`setDragImage`). 놓은 자리 그대로 — 다른 섹션도 PUT stage 뒤 `stages/{id}/tasks/order`(기본 정렬·필터 없음일 때만, 전체 보기는 섹션 맨 끝). 끄는 중엔 실시간 동기화 쉼(`html.pj-card-dragging`). 컬럼 body 는 dragenter 도 preventDefault(안 하면 자리 표시가 들어온 직후 놓을 때 drop 거부).
- 사이드바 전체 검색(`/api/search`, 제목·설명·댓글, pg_trgm) + 프로젝트/내 작업 필터 바(찾기·상태·담당자·마감·우선순위·정렬, 클라이언트 필터).
- 대시보드: "업무 합계(프로젝트별)" 카드, 섹션별 카드 삭제, 대시보드 업무 목록 패널에서 연 업무 창은 패널 왼쪽에(6-16·6-17·6-19).
- 담당자별 패널 날짜 mm/dd(요일)·지난 마감 빨강(6-20).
- 패널(`/project/p/{pid}?task=&embed=1`, `html.pj-embed`).
- **업무를 다른 프로젝트로 이동** — 보드 카드를 왼쪽 프로젝트 목록에 끌어 놓으면 섹션 선택 창 → `POST /project/api/tasks/{id}/move-project`(세부 업무 함께, 원 소속 권한 + 대상 프로젝트 멤버)(6-18).
## 업무 창 / 댓글 / 협업자
- 작업 창은 **저장 버튼 없이 실시간 저장**(칸별 PUT, `saveField`/`saveChain`, 새 작업은 제목이 생기는 순간 생성).
- 설명란 서식 도구에 글자 색·크기(서버는 span style 의 color·font-size 만 허용, `desc_inline_style`). 주소 붙여넣기 시 자동 링크. 설명란 이미지 더블클릭 = 별도 창 이미지 보기(확대·축소·끌어 이동).
- 설명란·댓글에서 @로 멤버 태그(`task_mentions`, 마이그레이션 006) → 수신함에 그 작업이 쌓임. 댓글 `@아이디` 는 아이콘+이름 칩.
- 댓글·답글 입력칸은 Enter 등록·Shift+Enter 줄바꿈(textarea).
- 댓글 답글·이모티콘 반응(마이그레이션 012 `task_comments.parent_id`·`task_comment_reactions`, 미적용 시 버튼 숨김·API 503). 반응 = 댓글 쓴 사람에게 알림(`type=reaction`).
- 완료 이력 줄은 `project_activity` completed 를 댓글 사이에 표시(댓글 수 제외).
- 협업자(`task_followers`, 자동 팔로우: 만든 사람·담당자·댓글·@태그) — 완료·댓글 알림은 담당자+협업자에게만.
- **담당자는 협업자가 아니다**(협업자 = 담당자 외의 멤버, `db.add_followers` 가 거르고 담당자 지정 시 협업자에서 뺌, 기존 겹친 행은 마이그레이션 028).
- 세부 업무: 업무 창 세부 업무 줄 담당자 오른쪽 = 협업자 지정. 만들 때(업무 창 추가 칸·보드 카드 새 줄) 협업자도 같이(`POST …/tasks` 의 `followers`, 비멤버 400). 만든 사람을 자동 협업자로 넣지 않음(고른 사람만). 보드 카드 세부 업무 줄에도 협업자 아이콘. 추가 칸은 동그라미 아이콘 버튼. 빈 마감일 아이콘 늘 옅게(6-17·6-19·6-20).
- 작업 삭제는 휴지통(`project_trash`, 마이그레이션 010) — 삭제 직전 스냅샷 3개월 보관, Pro user 이상만 보기·복구(`/project/trash`).
## 알림
- 수신함은 확인 안 한 태그·읽지 않은 알림만(2026-10-08) — [확인] 버튼 없이 줄을 누르면 읽음·확인 처리(같은 작업 줄 함께) + 페이지 이동 없이 오른쪽 iframe 패널, 다른 줄을 고르거나 패널을 닫으면 그 줄은 목록에서 빠짐.
- 나를 태그하거나 작업이 배정되면 프로젝트 화면 가운데 아래에 깜박이는 큰 팝업(닫기 전까지, `initTaskAlerts` + `GET /api/notifications/alerts`).
- **마감 지난 내 업무 위쪽 알림**(`static/erp-overdue.js`, ERP 모든 화면, `GET /project/api/my-overdue`, 닫으면 1시간 뒤 다시 — 새로 지난 업무는 바로)(6-17).
- 마감 알림(`reminders.py` 데몬 스레드, 영업일 09시, D-1/당일/지연, `task_reminders` 로 중복 방지, `PROJECT_REMINDER_*` env) — 마이그레이션 008.
- 작업 배정·완료 시 관리자에게 메일(`app/mail.py` stdlib smtplib, `SMTP_*` + `PROJECT_NOTIFY_EMAIL` env, 미설정 시 조용히 skip, `BackgroundTasks` 비동기).
- **PC 알림 프로그램**(`desktop/notifier/`, C# .NET Framework 4.8 WinForms exe 하나·트레이 상주, 마이그레이션 023 `notifier_links`·`notifier_tokens`, 6-11)
- 브라우저가 뒤에 있어도 태그·배정 알림을 웹 팝업과 같은 모양으로 화면 위에.
- 브라우저 `/project/notifier?code=` 승인으로 PC별 토큰(서버는 SHA-256 만, PC 는 DPAPI). `GET /project/api/notifier/alerts`(Bearer)는 웹 알림과 같은 `_alerts_payload`, 토큰마다 지금 사용자·권한 재확인.
- 프로그램이 돌고 있으면(최근 3분 확인, `notifier_active`) 웹 큰 팝업은 쉰다(`desktop: true`).
- 압축·난독화 금지(백신 오탐), 빌드 `desktop/notifier/build.ps1`.
## Project 옵션 (상단 톱니, 2026-10-16)
- 왼쪽 분류 | 오른쪽 설정. 새 옵션도 이 창에.
- 폰트 = 누구나·이 브라우저(localStorage `pj_font`).
- 처음 여는 탭·보드 카드 표지 = **수퍼관리자·Admin 만 수정·모든 사용자에게 적용**(서버 `project_options` 마이그레이션 029, `GET/PUT /project/api/options`, `store.normalize_project_options`).
- 긴급 공지 = 수퍼관리자만.
## 연간 목표 (마이그레이션 013, `goal_*` 테이블, 6-9)
- 사이드바 "목표" → 연도 펼침 → `/project/goals/{연도}`. 매출(목표·실적·달성)·로아스 월별 숫자 + 업무 영역(상품·마케팅·컨텐츠·유통 등)별 연간·월별 글.
- 조회는 전원·입력(주차별 목표·연도 추가/삭제 포함)은 Pro user 이상.
- 3·6·9·12월 오른쪽 1~4분기 칸(글 칸 13=1분기·15=2분기·14=3분기·16=4분기 — 예전 반기 칸 번호 재사용, 15·16 은 마이그레이션 017) + 분기 월 칸 접기 애니메이션(localStorage `pj_goal_fold_q`, 표는 `width:1px` + `table-layout:fixed`)(6-9-0).
- 영역·줄 이름 클릭 바로 수정. 로아스는 % 표기.
- **엑셀식 칸 병합** — 마우스로 끌어 사각형 선택 → 우클릭 셀 병합/병합 해제, 같은 영역 안 세로 `row_span` + 같은 분기 월 칸 가로, 글은 왼쪽 위 칸(`goal_cell_merges`, 마이그레이션 014·015·017).
- 3열 줄 추가는 같은 항목 칸(2열) 안에(`goal_rows.label_cont`, 마이그레이션 016).
- 구조 변경은 새로고침 없이 제자리 다시 그리기(`refreshTable`) + 애니메이션.
- 모든 열 너비 끌어서 조절(localStorage `pj_goal_col_w`), 세로 스크롤 틀 고정은 머리 줄 + 매출·로아스 줄까지, 항목 칸 +·우클릭으로 줄 위/아래 추가·삭제.
- 목표 표 매출 목표 월 칸을 누르면 **주차별 매출 목표**(`goal_week_targets`) 입력 창 — 월 전체 목표는 직접 입력(주차 합계와 별개), 맨 아래 차이 = 월 목표 − 주차 합계.
- 목표 표·회의록 칸 저장은 공용 `createFieldSaver`(같은 칸 요청 직렬화·보낸 값만 저장됨·실패 시 초안 유지·localStorage 초안 백업, 저장 실패면 구조 변경 중단 — 6-9-3).
- 구역·항목 메뉴는 우클릭 + ⋮ 버튼(키보드·터치).
## 주간 회의록 (`/project/goals/{연도}/meetings/{월}`, 6-9-2·6-9-3·6-9-4·6-22)
- 진입: 목표 표 월 머리. `goal_meetings`·`goal_meeting_items` 마이그레이션 015.
- 수정: 프로젝트 권한자 **누구나**. Pro user 이상 [회의 완료](`completed_at`, 마이그레이션 022)면 잠금(지난주 결과는 다음 주 회의록이 열려 있는 동안 허용). 삭제·완료·완료 해제는 Pro user 이상.
- 표 첫 열 머리 글자 "구분".
- 주차 탭 — **주차는 그 달 안**(`store.month_weeks`): 1일이 월~금이면 1일~일요일이 1주차, 토·일이면 1일~다음 주 일요일, 그 뒤 월~일, 말일이 월·화면 앞 주차에 붙음. 회의록 `week_start` = 주차 시작일(마이그레이션 020).
- 지난주 = **바로 앞 주차**(`store.prev_week_period`) 회의록의 같은 연결키 줄(`line_key`, 마이그레이션 018 — 생성 순서·이름 변경과 무관, **이름 추정 연결 금지**)로 리뷰.
- 열: 주요 업무·정량 목표 ‖ 전주 업무·결과(글, `result_note` 020)·전주 목표·결과. 정량 목표·결과는 숫자면 원 정수 칸, 아니면 글 칸 `target_text`·`result_text`(예: 20개, 021).
- 실적 조회 장애는 0원이 아니라 "미확인".
- 위에 목표 표 그 달 열 글을 영역별 "N월 계획" 카드로.
- 참석자 옆 [회의록 보드] = 그 주차의 빈 Google 슬라이드를 독립 창으로(오른쪽 🔗 아이콘 = 그 보드 링크 복사). 공유 드라이브 `MEETING_BOARD_FOLDER_ID`(없으면 만듦), `app/integrations/google_slides.py`, Drive appProperties 로 주차 연결 — Drive·Slides 권한 토큰 필요.
- 표를 스크롤해도 보이는 머리 영역 3칸:
1. 월 계획 + 머리 줄에 숫자 4개 작게 1행 — 월 목표 매출·월 누적 목표 매출(`goal_week_targets` 1주차~이 주차 합)·월 누적 실적(1일~오늘)·누적 목표 대비 차액·%.
2. 결정 사항·메모.
3. "N주차 작업 등록" 표(제목·담당자·프로젝트·섹션 → [적용] = 서버가 그 프로젝트에 작업 생성, `initMeetQuickTasks`).
주차별 서버 표 `goal_meeting_tasks`(마이그레이션 025)라 모두가 같이 보고, 남의 프로젝트 이름은 가림, 완료 프로젝트·섹션은 목록에서 뺌.
작업 칸(마이그레이션 026 `parent_task_id`) = 이미 있는 작업을 고르면 그 작업의 세부 작업으로 등록.
등록된 줄 제목 = 오른쪽 작업 창(편집, 저장 대기), [크게 열기] = 같은 표를 넓은 창으로.
- 실적 모듈 `performance_store` 매출은 머리 카드에만 읽기 전용 — 줄(쇼핑몰)별 자동 결과·이번주 실적·연결 배지·쇼핑몰 연결 메뉴는 폐지, 지난주 결과는 늘 직접 입력.
- "주요 업무" 칸 우클릭 위/아래 줄 추가 = 항목 칸은 그대로 그 항목 안에(마이그레이션 027 `label_cont`, 항목 칸 나누기).
- 회의록 줄 작업은 새로고침 없이 제자리 다시 그리기(`refreshMeeting`) + 애니메이션.
- 구분(구역) 칸 우클릭·⋯ = 구역 통째로 위/아래(`move-section`).
- 항목 칸 끌어 옮기기(2026-10-19) — 마우스로 항목 칸을 5px 이상 끌면 묶음(label_cont 줄 + 걸친 세로 병합)이 같은 구역 안에서 실시간 이동(칸 단위 FLIP, 구분 칸은 늘 첫 줄), 놓으면 `POST meeting-items/{id}/move-to {before_item_id|null}`(`db.move_meeting_group`, 묶음 사이·다른 구역은 거절) → `refreshMeeting`. Esc 취소, 짧게 누르기는 이름 수정.
- 회의록 표(`.pj-meet-table`) 테두리는 검정 `#000`, 구역(구분) 처음·끝 가로선은 굵게 2px, 항목과 항목 사이 가로선은 검정(`.is-item-end`), 같은 항목 안 하위 줄 사이만 회색 `#bfc3c9`(2026-10-19). 구역 끝에 닿는 칸(병합 포함)은 `.is-sec-end`(아래선 없음 — 다음 구역 굵은 선이 대신). 둘 다 JS `markMeetSecEnds` 가 달고 표 다시 그리기·끌기 뒤에도 다시 계산.