SMB — Sutady Moneybook

SMB(Sutady Moneybook) 2.4.1은 SQLite와 MCP(Model Context Protocol)를 기반으로 한 풀스택 개인 가계부 시스템입니다. 로컬 단독 실행과 오프라인 저장을 기본 지원하며, Cloudflare Tunnel을 통해 네트워크를 넘어 안전하게 접근할 수도 있습니다. 장부의 유일한 데이터 소스는 로컬 SQLite이며, 외부 클라우드 데이터베이스에 의존하지 않으므로 데이터를 완전히 자체 관리할 수 있습니다.

구현된 기능

• 빠른 수입/지출 기록, 발생 날짜만 기록하며 금액은 정수 "분" 단위로 저장합니다.

• 완전한 사용자 정의 분류, 비활성화, 마이그레이션 또는 영구 삭제, 월/년 장부, 검색 필터, 전역 30일 휴지통, CSV/JSON 내보내기.

• 주간, 월간, 연간 추이, 분류 상세, 분류 구성 및 이전 기간 동일 진행도 비교.

• DeepSeek 소비 개요, 이상 증가, 절약 제안, 분류 구조 및 사용자 정의 질문; 프로그램이 숫자를 담당하고 모델은 해석만 담당하며, 현재 외부 모델에 장부 메모를 전송하지 않습니다.

• 표준 Streamable HTTP MCP; 웹페이지에서 "확인 모드"와 "직접 제어 모드" 사이를 전환할 수 있습니다. 직접 모드에서는 장부, 분류, 대출, 구독, AI, 백업 및 시간대를 관리할 수 있으며 30일간 실행 취소 가능한 작업 기록이 유지됩니다.

• SQLite WAL＋synchronous=FULL, 마이그레이션 전 스냅샷, 일일 무결성/외래 키 백업, age 공개 키 암호화 및 Google Drive 업로드.

• Cloudflare Access 이중 보호, PWA 설치, Windows 로그인 자동 시작 및 실패 시 재시작 보조 스크립트.

• 네 가지 테마, 네 가지 내장 페이지 배경, 그리고 현재 기기에만 저장되는 개인 배경 이미지. 개인 이미지는 브라우저 내에서 압축되고 메타데이터가 제거되며, 삭제되지 않고 일시적으로 내장 배경으로 전환할 수 있습니다.

• 쿼리 우선 인사이트 홈: 기간과 수입/지출 유형이 URL에 저장되어, 새로고침하거나 분류 장부에서 돌아와도 원래 보던 위치가 유지됩니다.

• 모바일에서는 간결한 요약, 상세/구성 전환, 하단 고정 내비게이션 및 장부 필터 서랍을 사용합니다. 검색 중에는 이전 목록을 유지하여 콘텐츠 깜빡임을 방지합니다.

• 사이트 전체 날짜는 설정의 장부 시간대를 기준으로 하며, 컴퓨터와 Android의 시간대가 다를 때도 "오늘", 기본 월 및 AI 분석 기간이 일관되게 유지됩니다.

• 독립적인 "항목" 모듈로 타인이 나에게 빚진 대출, 분할 상환 및 CNY/USD 구독을 관리합니다. 항목은 기본적으로 소비 통계에 포함되지 않습니다. 적극적으로 연결하거나 동시에 생성한 일반 장부만 차트에 영향을 줍니다.

• 대출은 차용인 비활성화, 부분 상환, 자동 결제 완료 및 30일 휴지통을 지원합니다. 구독은 첫 회 혜택, 월/년/사용자 정의 기간, 만료 확인, 결제 내역 및 앱 내 알림을 지원합니다.

• 매월 위안화 총 예산과 분류 예산을 설정할 수 있습니다. 예산은 이월되지 않고 장부 기록을 차단하지 않으며, 인사이트 페이지에 사용액, 잔액, 예측 및 분류 위험이 표시됩니다.

• "장부 검진"은 결정적 규칙으로 의심스러운 중복, 대규모 지출, 예산 위험, 확인 대기 중인 갱신 및 연결 이상을 알려줍니다. 검증은 장부를 자동으로 수정하지 않으며, AI는 프로그램이 발견한 사실만 설명합니다.

• Android/Windows 설치 후 앱 메뉴에 "한 건 기록" 빠른 진입점이 제공됩니다. OpenClaw는 한 번의 원자적 쓰기로 최대 20건의 장부를 기록하고 일괄 실행 취소할 수 있습니다.

• 대출 기록 시 검색 가능한 단일 차용인 선택기를 사용합니다. 새 차용인과 대출은 같은 트랜잭션으로 저장됩니다. 동일 이름의 활성 기록은 재사용되며, 비활성화된 기록은 먼저 복원해야 합니다.

• OpenClaw 제안 재시도는 확인 대기 항목을 중복 생성하지 않습니다. 작업 센터에서 필요에 따라 필드 변경 사항과 실패 상태를 확인할 수 있습니다. 장부 검진은 MCP 읽기 전용 쿼리로도 가능하며 메모는 반환하지 않습니다.

• 선택적 "자금" 모듈로 위안화 계좌, 잔액 거래 내역, 계좌 간 이체, 수수료, 잔액 보정 및 전액 환불을 기록합니다. 총 자금에는 미수금 대출, 투자 또는 미래 수입이 포함되지 않습니다.

• 자금 추적을 활성화하기 전의 과거 장부는 소급 적용되지 않습니다. 활성화 후의 일반 수입/지출은 계좌에 연결되며, 잔액은 초기 잔액과 추가식 자금 거래 내역으로 계산되므로 두 번째 잔액 진실을 유지하지 않습니다.

• OpenClaw는 계좌, 이체, 보정 및 환불을 정확하게 조회하고 관리할 수 있습니다. 모든 직접 쓰기는 계속해서 멱등성 requestId를 사용하며, 모호한 계좌 이름은 거부됩니다.

"항목"의 실제 작업, 자금 활성화 전후의 연동 규칙 및 OpenClaw 권한은 대출 및 구독 사용 가이드를 참조하세요. 계좌 활성화, 자금 영향, 환불 및 검진 알림은 자금 추적 사용 및 유지 관리 가이드를 참조하세요.

Related MCP server: ExpenseTracker MCP Server

인사이트와 장부

• 인사이트의 "분류 상세"는 분류 순위, 금액 및 전기 대비 변화를 비교하는 데 사용되고, "분류 구성"은 도넛 차트, 금액 및 비율을 보는 데 사용되며, 둘은 동시에 표시되지 않습니다.

• 분류 구성은 이번 기간에 금액이 있는 모든 분류를 완전히 표시하며 더 이상 "기타"로 통합하지 않습니다. 각 섹터와 범례는 해당 장부로 드릴다운할 수 있습니다.

• 장부 페이지에는 "최근 입력", "월 장부", "년 장부", "휴지통"의 네 가지 동등한 진입점이 있습니다. 휴지통은 모든 날짜를 아우르며 삭제 시간 순으로 정렬되고, 이전에 본 월을 계승하지 않습니다.

• 이전 URL도 계속 호환됩니다: /bills는 최근 입력을 열고, /bills?view=ledger&period=month&anchor=...는 월 장부를 열며, period를 year로 바꾸면 년 장부가 열리고, /bills?view=trash는 전역 휴지통을 엽니다.

• 일반 삭제는 30일간 보관되며 복원할 수 있습니다. 휴지통의 장부는 영구 삭제할 수 있습니다. 설정의 분류 관리에서도 영향 범위를 표시하고 이름을 확인한 후 분류와 그 전체 장부를 영구 삭제할 수 있습니다. 영구 삭제는 실행 취소할 수 없지만, 연결된 대출 또는 구독 항목은 보존되며 장부 연결이 자동으로 해제됩니다.

페이지 업데이트와 개인 배경

• 페이지가 열려 있는 동안 30초마다 현재 페이지의 장부 데이터를 동기화합니다. 창에 다시 포커스하거나 네트워크가 복구될 때도 즉시 동기화합니다.

• PWA는 매분 새 버전을 확인하며, 새 버전을 발견하면 편집 중인 양식이 없을 때 자동으로 업데이트합니다. "설정 → 실행 상태"에서 "확인 및 새로고침"을 클릭할 수도 있습니다.

• Cloudflare 로그인이 만료되면 페이지의 "다시 로그인"을 사용하고, 사이트 쿠키를 삭제하거나 사이트 데이터를 지우지 마세요. "다시 로그인"과 "확인 및 새로고침"은 PWA 프로그램 캐시만 교체하며, 로그인 쿠키, 외관 기본 설정 및 IndexedDB의 개인 배경은 유지합니다. 전체 사이트 데이터를 지워야만 현재 기기의 개인 이미지가 삭제됩니다.

• "순수, 종이, 질감, 안개"를 선택하면 개인 이미지가 일시적으로 비활성화되지만 이미지는 현재 기기에 계속 남아 있으며, 언제든지 "이미지 사용"을 클릭하여 복원할 수 있습니다.

• 각 브라우저 세션의 첫 콜드 스타트 시 SMB 브랜드 시작 화면이 한 번 짧게 표시됩니다. 데이터 새로고침과 페이지 전환 시에는 다시 재생되지 않으며, 시스템에서 "동작 줄이기"가 켜져 있으면 건너뜁니다.

빠른 시작 및 로컬 실행

Node.js 22 이상이 필요합니다.

방법 1: Windows 원클릭 시작(가장 권장)

프로젝트 루트 디렉터리의 打开 SMB.cmd 를 더블 클릭하세요.

• 첫 실행 시 종속성을 자동으로 확인하고, 템플릿에 따라 .env 기본 구성을 자동 생성한 후 컴파일 및 패키징을 완료합니다.

• 이후 서비스가 자동으로 시작되고 기본 브라우저에서 가계부 홈페이지가 열립니다(기본 접속 http://127.0.0.1:8788, 로그인 없는 단일 기기 모드).

방법 2: 명령줄 수동 시작(플랫폼 공통: Windows / Linux / macOS)

프로젝트 루트 디렉터리에서 터미널을 엽니다:

# 1. 安装项目依赖
npm install

# 2. 初始化本地配置（默认开启免登录单机模式）
cp .env.example .env

# 3. 运行开发模式（推荐本地体验，支持代码热重载）
npm run dev
# 浏览器访问 http://127.0.0.1:5173

# 或者编译并启动正式生产服务：
npm run build
npm start
# 浏览器访问 http://127.0.0.1:8788

품질 검사

npm test
npm run typecheck
npm run build

정식 업데이트 전에 무결성 검사를 거친 스냅샷을 추가로 생성할 수 있습니다:

npm.cmd run backup:snapshot -- manual-update
npm.cmd run backup:verify-restore

고급 기능 및 배포 가이드

개인 컴퓨터에서 단일 기기로만 가계부를 기록한다면 외부 서비스를 전혀 구성할 필요 없이 바로 사용할 수 있습니다.

다음과 같은 고급 기능이 필요하다면 해당 가이드를 참조하여 필요에 따라 구성하세요:

• 모바일 원격 가계부 기록: Cloudflare Tunnel을 통해 공인 IP 없이 터널링하고 Access 신원 인증을 사용합니다. 자세한 내용은 배포 가이드를 참조하세요.

• AI 지능형 소비 분석: 루트 디렉터리의 配置DeepSeek密钥.cmd 를 더블 클릭하거나 .env에 DeepSeek API Key를 입력하면 소비 인사이트와 절약 제안이 활성화됩니다.

• 원격지 암호화 자동 클라우드 백업: Google Drive와 age 암호화 키를 구성하여 매일 자동 스냅샷 업로드를 구현합니다. 자세한 내용은 복구 가이드를 참조하세요.

• 자금 및 계좌 관리: 다중 계좌 자산 거래 내역, 이체 및 잔액 보정. 자세한 내용은 자금 추적 가이드를 참조하세요.

• 대출 및 구독 관리: 외부 미수금, 분할 상환 및 정기 구독 결제 추적. 자세한 내용은 항목 사용 가이드를 참조하세요.

디렉터리

• src/: 모바일과 컴퓨터가 공유하는 React PWA.

• server/: Node API, MCP, DeepSeek, 자금, 재무 항목 및 백업 서비스.

• db/: SQLite 테이블 구조 및 마이그레이션.

• tests/: 금액, 날짜, 항목, 인터페이스, AI 및 MCP 테스트.

• scripts/: 초기화, 자동 시작, 백업 키 및 복구 스크립트.

• deploy/: Cloudflare 및 OpenClaw의 키 없는 구성 템플릿.

비공개 파일 .env, 정식 데이터베이스, 백업, 로그 및 빌드 산출물은 모두 버전 관리에서 제외됩니다.

버전 번호는 package.json에서만 관리합니다. 수정 및 시각적 다듬기는 패치 버전을 올리고, 하위 호환되는 새 기능은 마이너 버전을 올리며, 제품 정체성 또는 비호환 계약 변경은 메이저 버전을 올립니다. 릴리스 기록은 CHANGELOG.md를 참조하세요. 로고 규정과 편집 가능한 원본 파일은 브랜드 가이드를 참조하세요.

명시적으로 연기된 장부 가져오기, 제3자 잔액 동기화 및 더 복잡한 계좌 기능은 ROADMAP.md를 참조하세요.