comrelay/docs/project-refactor-plan.md

프로젝트 우선 구조 리팩터 계획 (Project-First)

작성 2026-06-20. 현재 저장소(Repo)=프로젝트 1:1 구조를 프로젝트 우선 + 프로젝트 1:N 저장소 로 전환한다. 이 문서가 리팩터의 단일 진실 공급원(SSOT). 단계별로 갱신한다.

1. 목표 구조

Project (이름/설명/공개범위)                ← 작업의 기본 단위(우선)
  ├─ ProjectMember (admin/member, isOwner)  ← 멤버십을 프로젝트로 이동(RepoMember 폐지)
  ├─ Task (project, seq[프로젝트 내 순번], …) ← 업무는 프로젝트 소속
  │     └─ checklist / comment / attachment (기존 그대로, Task 종속)
  ├─ Activity (project, taskSeq?, …)         ← 활동도 프로젝트 단위
  └─ Repo[] (project FK, gitea 필드…)         ← 0~N개 저장소 연동(선택, 코드 연동 전용)

• 일반 프로젝트 = 연동 저장소 0개. 업무·멤버·활동 정상 사용.
• 저장소 연동 프로젝트 = 저장소 1~N개 링크. 추가로 Gitea/코드참조.

2. 확정된 설계 결정 (사용자 합의 2026-06-20)

1. 업무·멤버·활동 = 프로젝트 단위. Task→Repo 종속을 Task→Project 로 이동. RepoMember 폐지 → ProjectMember.
2. Gitea 자동 가져오기(역방향 동기화) → import 저장소는 "미분류" 기본 프로젝트에 연결. 관리자가 나중에 적절한 프로젝트로 이동.
3. dev DB 초기화(volume 재생성). 마이그레이션 스크립트 불필요.

3. 추가 설계 결정 (구현자 판단 — 변경 가능)

• 라우팅: 업무는 프로젝트 직속, 저장소는 형제 부속.
  • /projects · /projects/:projectId (상세=업무목록) · /projects/:projectId/{members,activity,settings}
  • /projects/:projectId/tasks/:seq (업무 상세) · /projects/:projectId/tasks/new
  • /projects/:projectId/repos (연동 저장소 목록·링크) · /projects/:projectId/repos/:repoSlug (저장소 상세/설정)
  • /tasks (내 업무, 프로젝트 횡단 — 경로 유지)
• 저장소 식별자: slugName 은 Gitea 조직 내 유일이므로 전역 유일 유지(프로젝트 내 유일로 바꾸지 않음). Repo 에 project_id FK만 추가.
• Task.seq: @Unique(['repo','seq']) → @Unique(['project','seq']) (프로젝트 내 순번 #N).
• 권한: assertMember/assertAdmin(repo.id, …) → assertProjectMember/assertProjectAdmin(project.id, …). 저장소 단위 세분 권한은 두지 않음(프로젝트 멤버면 연동 저장소 전체 접근). 향후 옵션.
• 저장소 자체엔 멤버 없음. 저장소는 순수 Gitea 연동 메타. 멤버십/권한은 소유 프로젝트가 결정.
• "미분류" 기본 프로젝트: 시스템 예약 프로젝트 1개(부팅 시 보장 생성). Gitea import 대상.

4. 단계별 실행 계획

Phase 1 — 백엔드 데이터 모델 + Project 모듈 (핵심)

• Project·ProjectMember 엔티티 + ProjectModule/ProjectService/ProjectController(CRUD + 멤버 초대/역할/제거 + 권한 가드)
• "미분류" 기본 프로젝트 부팅 보장(OnApplicationBootstrap)
• Repo 에 project FK 추가. RepoMember 폐지. Repo 생성/수정/삭제가 프로젝트 권한으로 게이트.
• Task 를 project 종속으로 변경(@Unique(['project','seq'])), 권한 체인 프로젝트로 교체, 담당자=프로젝트 멤버.
• Activity 를 project 종속으로. (taskSeq 유지)
• RepoSyncService: import → "미분류" 프로젝트 연결.
• AiService.suggestChecklist: 프로젝트/저장소 컨텍스트 정합.
• 컨트롤러 라우트 재배치(/projects/...). 기존 /repos/... 제거 또는 이전.
• 검증: build/lint/test.

Phase 2 — 프론트 프로젝트 중심 재구성

• project.store·useProject·types/project.ts
• 신규 페이지: ProjectListPage(진입점)·ProjectDetailPage(업무목록)·ProjectSettingsPage·ProjectMembersPage·ProjectActivityPage
• 저장소: 프로젝트 내 "연동 저장소" 섹션 + RepoLinkPage(기존 RepoCreate 재구성)
• task/member/activity 스토어를 projectId 키로 재설계
• 라우팅 전면 교체, AppShell 네비(프로젝트/내 업무)
• 검증: type-check/lint/build.

Phase 3 — 마무리

• 문서(api-contract.md)·메모리 갱신, 잔여 UI 정리, 런타임 점검.

5. 진행 로그

• Phase 0: 계획 수립 ✅
• Phase 1-a: Project/ProjectMember 모듈 기반(엔티티·서비스·컨트롤러·"미분류" 부팅) ✅ (커밋 2f66cdd)
• Phase 1-b: 백엔드 이전 ✅ — Activity(project FK·listForProject)·Repo(project FK, RepoMember 폐지)·Task(project 종속, seq 프로젝트 내 순번, 권한=ProjectMember) 전환. RepoService 프로젝트 종속(/projects/:projectId/repos, 멤버·업무카운트·캐시 제거). Task/Activity 컨트롤러 /projects/.... RepoSync→"미분류". AiService 프로젝트 컨텍스트. member.service/controller·repo-member·repo-cache 삭제. 검증 build/lint 0·14 tests.
• Phase 1 잔여(소소, 후속): ProjectResponse 카운트(repoCount/doneCount/totalCount 현재 0 stub) 집계 배선, ProjectMemberService 활동·알림 배선(TODO), TaskService.assigneeCounts→ProjectMemberService taskCount 연결.
• Phase 2-a: 프론트 프로젝트 중심 재구성 ✅ — types/project·useProject·project.store 신설. useTask/useMember/useActivity 를 /projects/:projectId/... 로, task/my-task/activity 타입·스토어를 projectId/projectName 으로 전환. 알림 store 라우팅/문구 프로젝트화. 라우팅 /projects/... 전면 교체. 페이지 rename(Repo*→Project*): List/Create(간단 폼)/Detail/Settings/Members/Activity. RepoHeader→ProjectHeader, RepoTabs→ProjectTabs. AppShell 네비 "프로젝트". 죽은 파일(repo.store/useRepo/GiteaRepoBar) 삭제. 검증 type-check/lint/build 0.
• Phase 1 카운트 배선 ✅ — ProjectService 가 프로젝트별 연동 저장소 수·업무 완료/전체 수를 그룹 쿼리로 집계(Repo/Task forFeature 등록). ProjectMemberService 멤버 taskCount 집계 + 초대/역할변경/제거 시 활동 적재·대상자 알림 발송(Activity/Notification 모듈 주입). TaskService 미사용 집계 메서드 제거. 검증 build/lint 0·14 tests.
• Phase 2b 저장소 연동 UI ✅ — useRepo(프로젝트 종속) 복구, types/repo ApiRepo 를 새 RepoResponse(projectId 추가·members/counts 제거)로 정합. ProjectTabs 에 "저장소" 탭(repoCount) 추가, 신규 ProjectReposPage(/projects/:id/repos) — 연동 저장소 목록 + slug 가용성 체크 포함 연동(생성) 폼 + 연동 해제(admin). 라우트 추가. 화면 잔여 "저장소" 문구를 "프로젝트"로 정리(crumb·설정 문구·멤버 모달·주석). 검증 type-check/lint/build 0.
• 다음 = Phase 3 마무리(문서·메모리 갱신, 런타임 점검).