financial/README.md

Financial

계좌, 거래, 카테고리, 할부, 대출, 반복거래, 가맹점 자동분류 규칙을 관리하는 PHP 기반 개인 금융 관리 서비스입니다.

프로젝트 성격

Financial은 개인 금융 데이터를 서버 렌더링 PHP 화면에서 관리하는 내부 서비스입니다. 계좌와 거래를 중심으로 카테고리, 할부, 대출, 반복거래, 가맹점 규칙을 연결해 실제 지출/상환 흐름을 기록합니다.

공통 인증 bootstrap이 세션, remember token, CSRF, private no-store header를 담당합니다.

주요 기능

• 계좌 생성/수정/목록
• 거래 생성/수정/삭제/조회
• 카테고리 관리
• 할부 등록, 청구 처리, 선납 처리
• 대출 등록, 상환 등록, 선납 처리
• 반복거래 관리
• 가맹점 자동분류 규칙 관리
• 카테고리 추천 API
• PWA assets와 offline 화면 제공

주요 API/흐름

• public/api/category_suggest.php: merchant rule 기반 카테고리 추천
• 일반 form POST 저장: 각 화면의 검증 후 서비스 함수로 저장
• 저장 후 redirect/flash 메시지로 사용자 피드백 제공

구성

• app/config/database.php: DB 설정 bridge
• app/lib/auth.php: 인증, remember token, CSRF, no-store header
• app/lib/db.php: PDO 연결
• app/lib/account_service.php: 계좌 서비스
• app/lib/transaction_service.php: 거래 저장과 조회
• app/lib/installment_service.php: 할부 청구와 선납 처리
• app/lib/loan_service.php: 대출과 상환 처리
• app/lib/recurring_service.php: 반복거래 처리
• app/lib/merchant_pattern_service.php: 가맹점 규칙과 추천
• public/*.php: 사용자 화면과 form 처리
• public/assets/app.css: 화면 스타일
• public/assets/pwa.js, public/sw.js: PWA 동작

데이터/저장소

• financial DB tables: 계좌, 거래, 카테고리, 할부, 대출, 반복거래, 가맹점 규칙
• /home/seo/secret/financial.php: DB 접속 secret

처리 흐름

1. 사용자가 화면을 열면 인증과 권한을 확인합니다.
2. POST 요청은 CSRF token을 검증합니다.
3. 입력값 검증 후 도메인별 service 함수에서 저장합니다.
4. 저장 후 redirect와 flash 메시지로 응답합니다.
5. 카테고리 추천 API는 merchant rule 우선순위와 confidence를 반환합니다.

주요 함수/모듈

• auth.php: 로그인, 세션, CSRF
• transaction_service.php: 거래 저장과 조회
• installment_*: 할부 청구와 선납 처리
• merchant_rules.php: 가맹점 자동분류 규칙 관리

보안

• 로그인 세션과 remember token을 사용합니다.
• POST form은 CSRF token을 검증합니다.
• 개인 금융 데이터 응답은 private/no-store 상태를 유지해야 합니다.
• 레포에는 DB 비밀번호를 포함하지 않고, 배포 환경의 secret 파일에서만 로드합니다.

운영 체크포인트

• 삭제된 미사용 테이블이 다시 참조되지 않는지 확인합니다.
• 가맹점 추천 규칙의 우선순위 충돌을 주기적으로 점검합니다.
• DB 백업과 secret 파일 권한을 관리합니다.