사내 마켓·동호회 서비스 설계하기

마지막 확인

w09-project-design.md

선택한 주제의 결정·실행 결과를 기록하세요. 뒤에는 두 후보의 완성 초안을 함께 넣었습니다.

# 9주차 · 사내 마켓 또는 동호회 관리
선택 주제 / 선택 이유: [내용]
확인한 사용자 불편 / 수업용 가정: [각각]
목표 UX / 역할별 화면 / 첫 사용 순서: [내용]
첫 구현 / 후속 기능과 담당: [내용]
상태·권한·중복·실패 규칙: [내용]
DB 선택 / 보존·백업 이유: [내용]
사진 원본 저장 위치 / DB의 파일 연결 정보: [내용]
사진 업로드·게시글 저장 실패 시 안내: [내용]
프로젝트 위치 / README 실행 순서: [내용]
등록·재조회·다른 계정 확인 결과: [내용]
완료 / 미완료 / 시안 여부: [각각]

## 마켓 PRD
# 사내 나눔·중고 마켓 · PRD 초안
수업용 제안. 실제 회사의 규칙은 확인 후 확정한다.
사용자: 직원(게시자 또는 관심 직원).
목표 UX: 사진·가격/나눔·상태를 보고 물건을 찾고 게시자에게 연락한다.
전체 기능:
- 사진·제목·설명·판매/나눔 구분·가격을 포함한 게시글 등록
- 목록·상세 조회, 찜하기/취소, 채팅 요청
- 판매중 → 예약중 → 거래완료, 예약 취소 시 판매중 복귀
역할:
- 직원은 게시글을 조회하고 자기 계정으로 찜·채팅 요청한다.
- 게시글 수정·거래 상태 변경은 게시자만 한다.
- 채팅 요청을 보냈다는 이유로 예약 상태를 자동 변경하지 않는다.
입력 규칙 초안:
- 판매는 0보다 큰 가격, 나눔은 가격 0으로 저장한다.
- 사진은 등록한 파일을 서버가 확인한 뒤 연결한다.
- 같은 직원의 같은 게시글 찜·채팅 요청은 중복 생성하지 않는다.
첫 구현: 사진 포함 등록 → 목록 → 상세 → 새로고침 후 재조회.
후속 구현: 찜·채팅 요청·거래 상태 관리. 전체 요구에서 삭제하지 않는다.
채팅 요청은 연락 요청 기록과 게시자의 확인까지다.
실시간 메시지 송수신·결제·배송은 이번 범위에 포함하지 않는다.
완료 확인:
- 사진·가격/나눔·상태가 목록과 상세에 일치한다.
- 찜을 두 번 눌러도 중복 레코드가 생기지 않는다.
- 채팅 요청이 저장되고 게시자가 확인할 수 있다.
- 다른 직원은 내 게시글의 상태를 변경할 수 없다.
- 저장 오류이면 성공 안내 대신 입력 내용을 유지한다.

## 마켓 ERD
# 사내 마켓 · 기록과 관계 예시
PK는 각 기록 번호, FK는 다른 기록을 가리키는 번호다.
users(id PK, name)
posts(id PK, seller_id FK→users, title, description,
      kind: sale|giveaway, price, status: available|reserved|completed)
stored_files(id PK, owner_id FK→users, storage_provider, bucket, object_key)
post_photos(id PK, post_id FK→posts, stored_file_id FK→stored_files, order_no)
favorites(user_id FK→users, post_id FK→posts)
chat_requests(id PK, post_id FK→posts, requester_id FK→users, created_at)
status_events(id PK, post_id FK→posts, from_status, to_status, actor_id FK→users, created_at)
직원 1명 → 여러 게시글 / 게시글 1개 → 여러 사진·찜·채팅 요청·상태 변경 기록
favorites는 (user_id, post_id)를 중복 없이 보관한다.
chat_requests도 (post_id, requester_id)를 중복 없이 보관한다.
예시:
users: id=7 김직원 / id=9 박직원
posts: id=42, seller_id=7, title=사무용 의자,
       kind=sale, price=15000, status=available
stored_files: id=12, owner_id=7, storage_provider=s3,
              bucket=수업용 비공개 버킷, object_key=images/chair.jpg
post_photos: id=61, post_id=42, stored_file_id=12, order_no=1
favorites: user_id=9, post_id=42
chat_requests: id=101, post_id=42, requester_id=9
나눔 게시글 예: kind=giveaway, price=0.
채팅 요청이 생겨도 posts.status는 여전히 available이다.
판매자가 예약을 확인하면 status를 reserved로 바꾸고 status_events를 함께 저장한다.

## 마켓 API
# 사내 마켓 · API 명세 예시
구현할 약속이며 실제 실행 응답이 아니다. JSON 필드와 권한은 Go에서 확인한다.
모든 동작은 로그인한 직원 계정으로 처리한다. 작성자 ID는 서버가 결정한다.

POST /api/uploads
사진 파일 업로드 → 201 {"fileId":12,"url":"/api/files/12"}
파일 종류·크기·소유자 검사는 서버에서 한다. 허용 기준은 팀이 정한다.
S3를 쓰는 예시: 서버가 파일 업로드를 확인하고 DB에 객체 키·소유자를 기록한 뒤 fileId를 반환.
사진 원본이 아니라 객체 키·파일 번호를 게시글과 연결한다.
GET /api/files/12 → 서버가 로그인·접근 권한 확인 후 파일 또는 만료되는 보기 주소 제공.
업로드 직후 미연결 사진은 소유자만 접근하고, 게시글에 연결된 뒤에는 해당 게시글의 열람 권한을 따른다.
API url은 우리 서버의 안정된 파일 경로이며 공개 S3 주소나 영구적인 임시 링크라는 뜻이 아니다.
POST /api/posts
보냄:
{"title":"사무용 의자","description":"직접 전달 가능합니다","kind":"sale","price":15000,"photoIds":[12]}
201:
{"id":42,"status":"available"}
필수 제목·사진 누락, 판매/나눔 가격 규칙 불일치이면 400.
사진은 현재 직원이 등록한 파일만 연결한다.

GET /api/posts → 200 게시글 목록
GET /api/posts/42 → 200
{"id":42,"sellerId":7,"title":"사무용 의자","kind":"sale","price":15000,"status":"available","photos":["/api/files/12"],"isFavorited":false}
PATCH /api/posts/42
게시자만 제목·내용·판매/나눔·가격·사진을 수정. 등록과 같은 입력 검증.
보냄: {"title":"사무용 의자 나눔","kind":"giveaway","price":0}
200 {"id":42,"kind":"giveaway","price":0,"status":"available"}
거래 상태 변경은 아래 status 경로로 분리한다.

PUT /api/posts/42/favorite → 200 {"favorited":true}
DELETE /api/posts/42/favorite → 200 {"favorited":false}
같은 요청을 반복해도 찜 기록은 중복되지 않는다.

POST /api/posts/42/chat-requests
보냄: {}
201 {"id":101,"postId":42,"status":"requested"}
이미 요청했으면 기존 요청 번호를 200으로 돌려준다.
게시자 본인의 글 또는 거래완료 글에는 요청을 만들지 않는다(400).
GET /api/posts/42/chat-requests → 게시자만 요청 목록 조회.

PATCH /api/posts/42/status
보냄: {"status":"reserved"}
200 {"id":42,"status":"reserved"}
게시자만 변경. available→reserved→completed,
예약 취소 reserved→available을 허용하는 초안.
허용하지 않은 변경은 400. 변경과 상태 이력은 함께 저장한다.

로그인 없음 401 / 남의 글 변경·연락 요청 목록 조회 403 / 없는 게시글 404.
저장 실패 500과 {"error":{"code":"save_failed"}}.
실패 시 작성 내용을 유지하고 성공 안내를 하지 않는다.

## 동호회 PRD
# 동호회 관리 · PRD 초안
수업용 제안. 공개 범위·운영 권한·집계 기준은 팀이 확인 후 확정한다.
사용자: 가입 전 직원, 승인된 멤버, 해당 동호회 운영자.
목표 UX: 소개를 보고 가입한 뒤 공지·일정을 확인하고 참석 기록을 찾는다.
전체 기능:
- 동호회 소개, 가입 신청과 운영자의 승인
- 동호회별 공지 등록
- 모임 일정 등록, 멤버의 참석/불참 응답
- 멤버별 연간 실제 참석 횟수 조회
권한 초안:
- 직원은 소개를 보고 본인 계정으로 가입 신청한다.
- 운영자는 자기 동호회의 신청 승인·공지·일정·실제 참석 확인을 담당한다.
- 승인 멤버는 해당 동호회의 공지·일정을 보고 본인의 참석/불참을 응답한다.
- 일반 멤버는 다른 사람의 승인·실제 참석 기록을 바꾸지 않는다.
데이터 규칙 초안:
- 같은 사람의 같은 동호회 가입 신청은 중복되지 않는다.
- 참석 의사 응답과 실제 참석 확인 기록을 분리한다.
- 같은 멤버·모임의 실제 참석은 한 번만 센다.
- 완료된 모임의 실제 참석=true인 기록을 해당 연도로 집계한다.
- 취소·미래 모임이나 단순 참석 응답은 실제 참석 횟수에 넣지 않는다.
첫 구현: 소개 조회 → 가입 신청 → 운영자 승인 → 본인 가입 상태 재조회.
후속 구현: 공지·모임·응답·실제 참석·연간 조회. 전체 요구에서 삭제하지 않는다.
완료 확인: 승인 전후 표시와 접근 범위가 바뀌고, 다른 동호회 운영 권한이 섞이지 않는다.
참석 응답만으로 연간 횟수가 올라가지 않고 실제 참석을 기록·수정하면 집계도 바뀐다.

## 동호회 ERD
# 동호회 · 기록과 관계 예시
users(id PK, name)
clubs(id PK, name, description, manager_id FK→users)
memberships(id PK, club_id FK→clubs, user_id FK→users,
            status: pending|approved)
notices(id PK, club_id FK→clubs, author_id FK→users, title, body)
events(id PK, club_id FK→clubs, title, starts_at, ends_at,
       status: scheduled|completed|cancelled)
rsvps(event_id FK→events, user_id FK→users, response: attending|declined)
attendance_records(event_id FK→events, user_id FK→users,
                   attended, checked_by FK→users)
직원 여러 명 ↔ 여러 동호회: memberships로 연결.
동호회 1개 → 여러 공지·모임 / 모임 1개 → 여러 의사 응답·실제 참석 기록.
memberships는 (club_id,user_id), rsvps와 attendance_records는 (event_id,user_id)가 중복되지 않음.
예시:
users: id=7 김직원 / id=9 이운영자
clubs: id=5, name=등산 동호회, manager_id=9
memberships: id=21, club_id=5, user_id=7, status=approved
notices: id=51, club_id=5, title=가을 모임 안내
events: id=81, club_id=5, starts_at=2026-10-25T09:00:00+09:00, ends_at=2026-10-25T12:00:00+09:00, status=completed
rsvps: event_id=81, user_id=7, response=attending
attendance_records: event_id=81, user_id=7, attended=true, checked_by=9
위 예시 모임만 있으면 2026년 참석 횟수는 1회다.
단순 rsvp=attending만 있고 실제 참석 기록이 없으면 실제 횟수는 0회다.
연간 횟수는 중복으로 저장하는 누적 숫자보다 원래 참석 기록으로 계산한다.
수업용 연도 기준은 Asia/Seoul에서 모임 시작일이 속한 연도다.

## 동호회 API
# 동호회 관리 · API 명세 예시
구현할 약속이며 실제 실행 응답이 아니다. 로그인과 해당 동호회의 권한을 Go에서 확인한다.

GET /api/clubs/5 → 200
{"id":5,"name":"등산 동호회","description":"함께 걷는 모임","membershipStatus":null}
POST /api/clubs/5/join-requests
보냄: {}
201 {"membershipId":21,"status":"pending"}
신청한 직원은 서버 로그인 정보에서 결정. 이미 신청한 경우 기존 상태를 200으로 반환.
GET /api/clubs/5/memberships?status=pending
해당 동호회 운영자만 대기 신청 목록 조회.
200 [{"membershipId":21,"userId":7,"name":"김직원","status":"pending"}]
GET /api/clubs/5/members
운영자만 승인 멤버 목록을 조회해 실제 참석·연간 조회 대상을 선택.
200 [{"membershipId":21,"userId":7,"name":"김직원","status":"approved"}]

PATCH /api/clubs/5/memberships/21
보냄: {"status":"approved"}
해당 동호회 운영자만 승인.
200 {"membershipId":21,"clubId":5,"status":"approved"}

POST /api/clubs/5/notices
보냄: {"title":"가을 모임 안내","body":"공지 내용"}
운영자만 등록 → 201 {"id":51}
GET /api/clubs/5/notices → 승인 멤버·운영자에게 200 공지 목록.

POST /api/clubs/5/events
보냄: {"title":"정기 등산","startsAt":"2026-11-15T09:00:00+09:00","endsAt":"2026-11-15T12:00:00+09:00"}
운영자만 등록 → 201 {"id":82,"status":"scheduled"}
GET /api/clubs/5/events → 승인 멤버·운영자에게 200 일정 목록.
PUT /api/events/82/rsvp
보냄: {"response":"attending"} 또는 {"response":"declined"}
해당 동호회의 승인 멤버 본인 응답만 변경.
200 {"eventId":82,"response":"attending"}
참석 의사만 저장하며 실제 참석 횟수는 올리지 않는다.

PATCH /api/events/81/status
보냄: {"status":"completed"}
운영자가 모임 종료 후 완료로 변경(endsAt이 현재보다 미래면 거절).
PUT /api/events/81/attendance/7
보냄: {"attended":true}
운영자만 해당 멤버의 실제 참석을 기록·수정.
모임 완료 여부·멤버 소속을 검사 → 200 {"eventId":81,"userId":7,"attended":true}
GET /api/clubs/5/members/7/attendance?year=2026
본인 또는 운영자만 조회.
200 {"year":2026,"attendedCount":1}
완료된 모임의 실제 참석 기록을 모임 시작일의 연도(수업 초안 Asia/Seoul)로 계산.
다른 승인 멤버는 본인 화면에서 자기 횟수를 확인한다.

로그인 없음 401 / 다른 동호회 운영·다른 사람 기록 변경 403 / 없는 기록 404.
날짜·응답 값·소속 오류 400 / 저장 실패 500과 error.code=save_failed.
실패 시 입력·기존 응답을 유지하고 성공으로 표시하지 않는다.