Cài đặt & bắt đầu | Tài liệu MoneyFlow

MoneyFlow hiện là bản phát triển nội bộ (0.x): chưa có trên App Store, chưa có trên TestFlight, và mã nguồn nằm trong kho riêng tư. Trang này mô tả cách dựng ứng dụng từ mã nguồn, cách chạy thử bằng chế độ demo, và cách dựng máy chủ đồng bộ ở mức tổng quát.

Yêu cầu

Máy Mac có Xcode 27 trở lên.
iPhone hoặc iPad chạy iOS/iPadOS 26.1 trở lên (hoặc trình giả lập tương ứng).
Máy chủ đồng bộ: Node.js 20 trở lên và PostgreSQL.

Build ứng dụng từ mã nguồn

open MoneyFlow.xcodeproj                     # scheme MoneyFlow
xcodebuild test -project MoneyFlow.xcodeproj -scheme MoneyFlow \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
  -only-testing:MoneyFlowTests

Mở MoneyFlow.xcodeproj trong Xcode, chọn scheme MoneyFlow và chạy. Địa chỉ máy chủ đồng bộ được khai báo trong MoneyFlow/Config.swift; hãy đổi thành địa chỉ máy chủ của bạn trước khi build. Bộ test gồm 63 test chạy trên kho SwiftData trong bộ nhớ.

Đăng nhập lần đầu

Ứng dụng xác thực hoàn toàn trên máy chủ đồng bộ, nên lần mở đầu tiên cần tên đăng nhập và mật khẩu do quản trị máy chủ cấp. Sau khi đăng nhập, ứng dụng đồng bộ ngay lần đầu, rồi lưu mã phiên trong Keychain. Phiên mặc định có hiệu lực 30 ngày; khi hết hạn, ứng dụng cho đăng nhập lại ngay trong màn Tài khoản mà không mất các thay đổi đang chờ đẩy lên.

Ứng dụng không chứa mật khẩu hay khoá API nào. Xem Bảo mật và quyền riêng tư.

Chế độ demo

Bản Debug có chế độ demo để xem thử ứng dụng hoặc chụp ảnh mà không cần máy chủ. Chạy ứng dụng với tham số -seedDemoData:

Ứng dụng nạp khoảng 2,5 tháng dữ liệu mẫu của hai thành viên giả, rồi đăng nhập cục bộ.
Dữ liệu demo nằm trong một kho riêng, tách hẳn kho thật.
Đồng bộ và xoá dữ liệu trên máy chủ bị tắt, nên dữ liệu mẫu không bao giờ lên máy chủ thật. Thông báo hoá đơn của chế độ demo cũng không động đến thông báo thật.

Chế độ demo không có trong bản Release.

Dựng máy chủ đồng bộ

Máy chủ là một ứng dụng Node.js + Express dùng PostgreSQL. Các bước ở mức tổng quát:

cd Backend
cp .env.example .env        # điền thông tin cơ sở dữ liệu, JWT_SECRET, BTMC_API_KEY
npm install
npm run db:init             # tạo bảng và tài khoản mặc định (mật khẩu ngẫu nhiên in ra một lần)
npm test                    # kiểm tra dữ liệu đồng bộ
npm start

Tạo một cơ sở dữ liệu PostgreSQL và một tài khoản riêng cho ứng dụng, rồi điền thông tin vào .env.
JWT_SECRET phải là chuỗi ngẫu nhiên dài. Máy chủ từ chối khởi động nếu biến này thiếu hoặc còn là giá trị mẫu.
BTMC_API_KEY là khoá của nguồn giá vàng, chỉ nằm trên máy chủ.
npm run db:init sinh mật khẩu ngẫu nhiên cho từng tài khoản mới và in ra một lần duy nhất (hoặc dùng DEFAULT_USER_PASSWORD nếu bạn đặt). Tài khoản đã có không bao giờ bị ghi đè. Đổi mật khẩu về sau bằng npm run user:passwd -- <tên>.
JWT_EXPIRES_IN quyết định thời hạn phiên, mặc định 30d.
Máy chủ mặc định chỉ lắng nghe trên giao diện loopback. Hãy đặt sau một đường hầm hoặc reverse proxy có HTTPS để ứng dụng truy cập từ ngoài; không cần mở port trực tiếp.
Khi nâng cấp máy chủ có sẵn: dừng tiến trình, cập nhật mã, chạy lại npm install và npm run db:init (an toàn khi chạy lại), rồi khởi động lại.

Hướng dẫn từng bước, kể cả quy trình nâng cấp an toàn, nằm trong Backend/DEPLOY.md của kho mã nguồn.

Xử lý sự cố thường gặp

Máy chủ không khởi động. Kiểm tra JWT_SECRET đã đặt và không còn là giá trị mẫu, và Node.js từ phiên bản 20 trở lên.
Đăng nhập báo hết hạn. Mở Tài khoản, chọn "Đăng nhập lại để đồng bộ". Các thay đổi trên máy vẫn được giữ và đẩy lên sau khi đăng nhập.
Đồng bộ báo máy chủ từ chối dữ liệu. Thông báo chỉ rõ bản ghi không hợp lệ. Các bản ghi khác vẫn được tải về bình thường.
Giá vàng hiện "Chưa có giá". Ứng dụng chưa lấy được giá thật từ máy chủ; giá trị vàng lúc đó chỉ là ước tính. Xem Tiết kiệm và vàng.
Máy từng chạy dữ liệu demo bản cũ bị chặn đồng bộ. Vào Tài khoản, chọn "Xoá toàn bộ dữ liệu" để dọn dữ liệu mẫu rồi đồng bộ lại.
Kiểm thử treo. Dùng bản Xcode chính thức thay cho bản beta; bản beta có thể làm trình chạy kiểm thử không phản hồi.