| 항목 | 내용 |
|---|
| 기능 ID | FEAT-FAMILY |
| 연결 시스템 | 마스터 시스템⑤ 가족연결 · PART4 3주체 연결(어르신·가족·실벗) |
| 한 줄 정의 | 가족을 초대해 권한·공유범위를 설정하고, 안부·사진·건강을 안전하게 공유 |
| 관련 액터 | PWA(어르신)가족앱실벗서버 |
설계 철학 — 가족 연결의 핵심은 "공유범위(share_scope)"입니다. 어르신이 무엇을 누구에게 보일지 스스로 통제할 수 있어야 존엄이 지켜집니다.
▍설계 7계층 체크리스트
| 계층 | 이 문서의 섹션 |
|---|
| ① UI | 가족 초대 / 가족 피드 SCR-FAM-01·02 |
| ② Flow | 초대 → 수락 → 권한설정 상태 머신 |
| ③ Data | family_relations / family_invites / share_scopes |
| ④ API | 초대·수락·권한·피드 엔드포인트 |
| ⑤ Seq | 초대코드 발급 → 수락 → 공유범위 적용 시퀀스 |
| ⑥ Comp | 가족 연결·공유범위 가드 모듈 |
| ⑦ Test | 검수 체크리스트 |
② Flow · 초대·수락 상태 머신
초대코드 발급→
대기(pending)→
가족 수락→
공유범위 설정→
연결됨(active)
초대코드는 10분 만료·1회용. 수락 시 어르신에게 "○○님을 가족으로 연결할까요?" 확인을 받아야 active.
▍공유범위(share_scope) 권한 모델
| 범위 | 기본값 | 설명 |
|---|
| sos | ON | SOS 발동 시 알림 (생명 직결 — 기본 ON 권장) |
| location | OFF | 위치 공유 (어르신 명시 동의 필요) |
| health | OFF | 건강·복약 현황 |
| schedule | OFF | 일정·외출 |
③ Data · DB 스키마
기존 p25의 family_relations 재활용 + 초대(family_invites)·공유범위(share_scopes) 신설.
MariaDB · UTF8MB4 · InnoDB
CREATE TABLE family_relations (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
senior_id BIGINT NOT NULL, -- 어르신
family_id BIGINT NOT NULL, -- 가족 회원
relation VARCHAR(20), -- '아들','딸','며느리'
status ENUM('pending','active','blocked') DEFAULT 'pending',
UNIQUE KEY uq_rel (senior_id, family_id),
FOREIGN KEY (senior_id) REFERENCES users(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
CREATE TABLE family_invites (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
senior_id BIGINT NOT NULL,
code CHAR(6) UNIQUE, -- 6자리 1회용
expires_at DATETIME NOT NULL, -- 발급+10분
used_at DATETIME
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
CREATE TABLE share_scopes (
relation_id BIGINT NOT NULL,
scope ENUM('sos','location','health','schedule'),
enabled TINYINT DEFAULT 0,
PRIMARY KEY (relation_id, scope),
FOREIGN KEY (relation_id) REFERENCES family_relations(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
설계 포인트 — 모든 가족 데이터 응답은 share_scopes를 거쳐 필터링된다. 공유 OFF 항목은 API 레벨에서 제거되어 가족 앱에 아예 내려가지 않는다.
④ API · 엔드포인트 명세
| M | 경로 | 설명 |
|---|
| POST | /family/invite | 초대코드 발급(10분 만료) |
| POST | /family/accept | 가족이 코드로 수락 → pending |
| POST | /family/{id}/confirm | 어르신이 연결 확인 → active |
| PUT | /family/{id}/scopes | 가족별 공유범위 설정 |
| GET | /family/feed | 가족 피드(공유범위 필터링됨) |
PUT /api/v1/family/45/scopes
{ "scopes": { "sos":true, "health":true, "location":false, "schedule":false } }
⑥ Comp · 컴포넌트 / 모듈 구조
프론트엔드 (PWA)
features/family/
├─ InviteView.js # 초대코드·공유
├─ FamilyFeed.js # 안부·사진 피드
├─ ScopeSettings.js # 가족별 공유범위 토글
└─ familyApi.js
백엔드 (PHP)
app/
├─ Controllers/FamilyController.php
├─ Services/
│ ├─ FamilyService.php # 초대·수락·연결
│ └─ ScopeGuard.php # 공유범위 필터(전 응답 통과)
└─ Models/ FamilyRelation FamilyInvite ShareScope
| 모듈 | 책임 |
|---|
ScopeGuard | 존엄의 수문장. 가족에게 나가는 모든 데이터를 share_scopes로 필터. OFF 항목은 애초에 직렬화하지 않음. |
FamilyService | 초대코드 생성(만료·1회용)·수락·이중 확인 처리. |
⑦ Test · 검수 체크리스트
| ID | 시나리오 | 기대 결과 |
|---|
| T-01 | 가족 초대 → 코드 발급 | 6자리 코드 생성, 10분 만료 설정 |
| T-02 | 가족이 코드로 수락 + 어르신 확인 | status=active, sos 공유 기본 ON |
| T-03 | 만료된 코드로 수락 시도 | 거절(코드 만료 안내) |
| T-04 | health=OFF 상태로 가족 피드 조회 | 건강 데이터 응답에서 완전 제외(누출 0) |
| T-05 | 위치 공유 ON으로 변경 | 변경 후 피드에 위치 표시 |
| T-06 | 가족 연결 해제(blocked) | 모든 공유 즉시 중단 |
완료 판정 — T-01~T-06 통과 시 FEAT-FAMILY 완료. T-04(공유범위 누출 0)는 프라이버시·존엄의 절대 기준.
기능설계 ⑤ 완성 — 가족 연결을 7계층으로 설계했습니다. 어르신이 공유범위를 스스로 통제하므로 안심하고 연결합니다.