공통 기반

아키텍처 · 기술 스택 · 폴더 구조 · 공통 규약 — 모든 기능설계의 전제

▍시스템 구성도

# 실벗 전체 시스템 아키텍처 (기존 p24 청사진 재활용·정밀화) ┌──────────────────────────────────────────────────────────┐ │ [어르신 단말] PWA sb.kiam.kr │ │ 큰글씨 UI · 마이크(STT) · 스피커(TTS) · 카메라 · GPS · 푸시 │ └───────────┬─────────────────────────────┬─────────────────┘ │ HTTPS / WSS │ WebRTC(영상) ▼ ▼ ┌────────────────────────┐ ┌────────────────────────────┐ │ 실벗 서버 sb.kiam.kr │◄──►│ 원챗 onechat.kiam.kr │ │ Apache + PHP 8 + JWT │SSO │ - 대화 세션/이력 영속화 │ │ - 회원/프로필/가족 │ │ - AI 아바타 렌더(음성·표정) │ │ - 건강/약/SOS/지자체 │ │ - WebSocket 라우팅 │ │ - 결제/구독/알림 │ │ - 콜백·데일리·푸시 발송 │ │ MariaDB (sbdb) │ └──────────────┬───────────────┘ └──────────┬─────────────┘ │ │ ▼ ▼ ┌────────────────────────────┐ ┌────────────────────────┐ │ DeepSeek LLM API │ │ 외부: FCM(푸시)/119 연계 │ │ 의도·감정·응답 생성 │ │ /토스페이먼츠/SMS게이트웨이│ └────────────────────────────┘ └────────────────────────┘

역할 분담 핵심 — 실벗 회원·건강·안전·기억(두뇌) / 원챗 대화 세션·아바타·발송(입·얼굴) / DeepSeek 언어 이해·생성(언어능력). 느슨한 결합(API/WSS).

▍기술 스택 확정

레이어	기술	비고
프론트엔드	PWA (HTML/CSS/Vanilla JS or 경량 프레임워크), Service Worker	설치형·오프라인·푸시
백엔드	PHP 8.x (Apache)	현 sb.kiam.kr 서버 환경
DB	MariaDB `sbdb` · UTF8MB4 · InnoDB	기존 p25 18테이블 기반
인증	JWT (Bearer) + 이메일 인증코드	원챗과 SSO 토큰 연계
실시간	WebSocket(WSS) · SSE(스트리밍)	대화/알림
AI 대화 코어	원챗 OneChat 아바타 API	onechat.kiam.kr
LLM	DeepSeek API	의도·감정·응답
음성	STT/TTS (브라우저 Web Speech 또는 외부 API)	큰소리·느린속도
푸시/알림	FCM(Web Push) + SMS 게이트웨이 + 원챗 발송	이중화
결제	토스페이먼츠 (빌링키 정기결제)	가족 구독

▍서버 폴더 구조 (백엔드)

/var/www/.../sb/ # 실벗 서버 루트 ├─ public/ # 웹 진입점 │ ├─ index.php # 프론트 컨트롤러 │ └─ pwa/ # PWA 정적 자원(manifest, sw.js, icons) ├─ api/ # REST 엔드포인트 │ └─ v1/ │ ├─ auth/ # 인증 │ ├─ ai/ # 아리 대화 (d01) │ ├─ sos/ # SOS (d02) │ ├─ health/ family/ village/ ... ├─ app/ │ ├─ Controllers/ # 요청 처리 │ ├─ Services/ # 비즈니스 로직 (OneChatService, DeepSeekService …) │ ├─ Models/ # DB 모델 │ └─ Middleware/ # JwtAuth, RateLimit … ├─ config/ # db.php, onechat.php, deepseek.php, toss.php ├─ db/ # migrations/ seeds/ └─ storage/ # logs/ uploads/ audio/

▍공통 API 규약

모든 엔드포인트는 /api/v1/* · JSON · Authorization: Bearer <JWT> (인증 제외).

표준 응답 — 성공

{ "success": true, "data": { /* 페이로드 */ }, "meta": { "ts": 1718000000 } }

표준 응답 — 실패

{ "success": false, "error": { "code": "AUTH_EXPIRED", // 기계용 코드 "message": "세션이 만료되었어요. 다시 로그인해 주세요.", // 어르신용 문구 "detail": "jwt exp at ..." // 개발용(운영 비노출) } }

공통 에러 코드

HTTP	code	의미
400	`VALIDATION_FAILED`	입력값 오류
401	`AUTH_REQUIRED` / `AUTH_EXPIRED`	미인증/만료
403	`FORBIDDEN`	권한 없음(공유범위 위반 등)
404	`NOT_FOUND`	리소스 없음
429	`RATE_LIMITED`	요청 과다
502	`UPSTREAM_ONECHAT` / `UPSTREAM_LLM`	원챗/LLM 장애 → 폴백 동작
500	`INTERNAL`	서버 오류

설계 공통 원칙

장애 폴백 — 원챗/LLM 장애 시에도 SOS·복약 등 생명·핵심 기능은 자체 로직으로 반드시 동작한다(d02 참조).

공유범위(존엄) — 모든 데이터 응답은 어르신이 설정한 share_scope를 서버에서 강제 필터링한다.

감사 로그 — 가족/지자체의 모든 열람·공유는 audit_logs에 기록(기획서 존엄 원칙 구현).

다음 장 — 이 공통 기반 위에서 d01 아리 아바타 대화와 d02 SOS를 6계층(UI→Flow→DB→API→Seq→Comp)으로 끝까지 설계합니다.