650df5b058
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
18 KiB
18 KiB
[프로젝트] 프로젝트 관리 모듈(아사나식) — 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-appzoom .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, 새 작업은 제목이 생기는 순간 생성). - 파일 끌어 놓기 = 첨부(2026-10-19): 업무 창 아무 곳(
.pj-task-modal-card, 설명칸 포함)·보드 메인 업무 카드에 파일을 놓으면POST /project/api/tasks/{id}/attachments(여러 개 차례로,uploadTaskFiles). 종류 "Files" 로 카드·세부 업무 끌기와 구분, 받는 곳 밖에 놓친 파일은 document 가 막아 화면이 파일로 넘어가지 않음. - 설명란 서식 도구에 글자 색·크기(서버는 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_activitycompleted 를 댓글 사이에 표시(댓글 수 제외). - 협업자(
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.pystdlib smtplib,SMTP_*+PROJECT_NOTIFY_EMAILenv, 미설정 시 조용히 skip,BackgroundTasks비동기). - PC 알림 프로그램(
desktop/notifier/, C# .NET Framework 4.8 WinForms exe 하나·트레이 상주, 마이그레이션 023notifier_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) 입력 창 — 월 전체 목표는 직접 입력(주차 합계와 별개), 맨 아래 차이 = 월 목표 − 주차 합계. 주차마다 두 칸(마이그레이션 030value_dist유통·인플 ·value_mall카페24·네이버,value= 합계 그대로 — 회의록 누적 목표는 합계), 머리글은 전체 목표 아래 구분선 밑. 030 전 한 칸 값은 유통·인플 칸에 미리 들어감, 030 미적용이면 한 칸 그대로. - 목표 표·회의록 칸 저장은 공용
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_note020)·전주 목표·결과. 정량 목표·결과는 숫자면 원 정수 칸, 아니면 글 칸target_text·result_text(예: 20개, 021). - 실적 조회 장애는 0원이 아니라 "미확인".
- 위에 목표 표 그 달 열 글을 영역별 "N월 계획" 카드로.
- 참석자 옆 [회의록 보드] = 그 주차의 빈 Google 슬라이드를 독립 창으로(오른쪽 🔗 아이콘 = 그 보드 링크 복사). 공유 드라이브
MEETING_BOARD_FOLDER_ID(없으면 만듦),app/integrations/google_slides.py, Drive appProperties 로 주차 연결 — Drive·Slides 권한 토큰 필요. - 표를 스크롤해도 보이는 머리 영역 3칸:
1·2. (2026-10-19) 카드 위 빈 공간 한 줄
.pj-meet-kpitop= N월 계획 + 숫자 4개(월 목표 매출·월 누적 목표 매출(goal_week_targets1주차이 주차 합)·월 누적 실적(1일오늘)·누적 목표 대비 차액·%, 잘리지 않음 — 좁으면 줄바꿈), 아래 카드.pj-meet-pn= 결정사항 제목(왼쪽) + 결정 사항(크게). 월 계획 상세(목표 표 그 달 글)는 뺐다. (.pj-meet-kpibar는 예전 숫자 상자 이름이라 쓰지 말 것) 3. "N주차 작업 등록" 표(제목·담당자·프로젝트·섹션 → [적용] = 서버가 그 프로젝트에 작업 생성,initMeetQuickTasks). 주차별 서버 표goal_meeting_tasks(마이그레이션 025)라 모두가 같이 보고, 남의 프로젝트 이름은 가림, 완료 프로젝트·섹션은 목록에서 뺌. 작업 칸(마이그레이션 026parent_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) 테두리 = 구역(구분) 처음·끝 가로선만 굵은 검정 2px, 나머지 선(세로·항목 사이·하위 줄 사이·바깥 위·좌우)은 모두 회색#bfc3c9(2026-10-19 마지막 요청 — 앞선 '전부 검정'·'항목 사이 검정'을 바꿈, 표 머리 아래 회색선은 없앰). 구역 끝에 닿는 칸(병합 포함)은.is-sec-end(아래선 없음 — 다음 구역 굵은 선이 대신). 둘 다 JSmarkMeetSecEnds가 달고 표 다시 그리기·끌기 뒤에도 다시 계산.