196 lines
4.6 KiB
Markdown
196 lines
4.6 KiB
Markdown
<p align="center">
|
|
<img src="assets/icon/app_icon.png" alt="car64 logo" width="120" />
|
|
</p>
|
|
|
|
<h1 align="center">car64</h1>
|
|
|
|
<p align="center">
|
|
A modern Flutter + Supabase app for tracking and managing die-cast car collections.
|
|
</p>
|
|
|
|
---
|
|
|
|
## Table of Contents
|
|
|
|
- [Overview](#overview)
|
|
- [Features](#features)
|
|
- [Tech Stack](#tech-stack)
|
|
- [Prerequisites](#prerequisites)
|
|
- [Configuration](#configuration)
|
|
- [Getting Started](#getting-started)
|
|
- [VS Code Workflows](#vs-code-workflows)
|
|
- [Project Structure (high level)](#project-structure-high-level)
|
|
- [Troubleshooting](#troubleshooting)
|
|
- [Release Checklist](#release-checklist)
|
|
- [Roadmap](#roadmap)
|
|
- [Contributing](#contributing)
|
|
- [Security Notes](#security-notes)
|
|
- [License](#license)
|
|
- [Reference](#reference)
|
|
|
|
## Overview
|
|
|
|
car64 helps collectors scan model IDs, organize personal and shared collections, and keep a clean catalog with community validation/reporting flows.
|
|
|
|
## Features
|
|
|
|
- Fast scan workflow (camera OCR + manual entry fallback)
|
|
- Multi-collection support with member roles (owner/member/viewer)
|
|
- Private image storage with signed URL access
|
|
- Collection collaboration and member management
|
|
- Community validation and issue reporting for catalog entries
|
|
- Profile/settings flows including password updates and report tracking
|
|
|
|
## Tech Stack
|
|
|
|
- Flutter (Material 3)
|
|
- Supabase (Auth, PostgREST, Storage, RPC)
|
|
- Shared Preferences (local settings)
|
|
- Google ML Kit Text Recognition (scanner)
|
|
|
|
## Prerequisites
|
|
|
|
- Flutter SDK (stable)
|
|
- A Supabase project
|
|
- For iOS builds: macOS + Xcode
|
|
|
|
## Configuration
|
|
|
|
Supabase config is required at runtime/build time (no embedded fallback values).
|
|
|
|
### Option A: local defines file (recommended)
|
|
|
|
Use:
|
|
|
|
- `.env/flutter_defines.json` (local, ignored by git)
|
|
- `.env/flutter_defines.example.json` (tracked template)
|
|
|
|
Expected shape:
|
|
|
|
```json
|
|
{
|
|
"SUPABASE_URL": "https://your-project.supabase.co",
|
|
"SUPABASE_ANON_KEY": "your_anon_key",
|
|
"SUPABASE_USE_PKCE": "true"
|
|
}
|
|
```
|
|
|
|
### Option B: direct dart-define flags
|
|
|
|
```bash
|
|
flutter run \
|
|
--dart-define=SUPABASE_URL=https://your-project.supabase.co \
|
|
--dart-define=SUPABASE_ANON_KEY=your_anon_key \
|
|
--dart-define=SUPABASE_USE_PKCE=true
|
|
```
|
|
|
|
## Getting Started
|
|
|
|
1. Install dependencies
|
|
|
|
```bash
|
|
flutter pub get
|
|
```
|
|
|
|
2. Run analyze
|
|
|
|
```bash
|
|
flutter analyze
|
|
```
|
|
|
|
3. Launch app
|
|
|
|
```bash
|
|
flutter run
|
|
```
|
|
|
|
## VS Code Workflows
|
|
|
|
### Run / Debug (`launch.json`)
|
|
|
|
Use **Run and Debug** with:
|
|
|
|
- `Flutter (Supabase Local - Debug)`
|
|
- `Flutter (Supabase Local - Profile)`
|
|
- `Flutter (Supabase Local - Release)`
|
|
|
|
These configurations read:
|
|
|
|
`--dart-define-from-file=.env/flutter_defines.json`
|
|
|
|
### Build Tasks (`tasks.json`)
|
|
|
|
Use **Terminal → Run Task**:
|
|
|
|
- `Flutter Build APK (Release)`
|
|
- `Flutter Build App Bundle (Release)`
|
|
- `Flutter Build iOS IPA (Release)`
|
|
|
|
## Project Structure (high level)
|
|
|
|
- `lib/screens/` UI screens and flows
|
|
- `lib/services/` Supabase integration/services
|
|
- `lib/widgets/` reusable UI components
|
|
- `lib/utils/` helpers and formatting utilities
|
|
- `lib/theme/` app theme and colors
|
|
|
|
## Troubleshooting
|
|
|
|
### App fails at startup with Supabase config error
|
|
|
|
- Ensure `.env/flutter_defines.json` exists locally.
|
|
- Confirm all required keys are present:
|
|
- `SUPABASE_URL`
|
|
- `SUPABASE_ANON_KEY`
|
|
- `SUPABASE_USE_PKCE`
|
|
|
|
### Build task works but app cannot connect to backend
|
|
|
|
- Verify the Supabase URL/key pair belong to the same project.
|
|
- Check Supabase RLS policies and RPC permissions.
|
|
|
|
### iOS IPA task fails on Windows
|
|
|
|
- `flutter build ipa` requires macOS + Xcode.
|
|
|
|
## Release Checklist
|
|
|
|
- [ ] `flutter pub get`
|
|
- [ ] `flutter analyze`
|
|
- [ ] Manual smoke test on Android
|
|
- [ ] Manual smoke test on iOS
|
|
- [ ] Confirm `.env/flutter_defines.json` points to production Supabase
|
|
- [ ] Build Android `appbundle`
|
|
- [ ] Build iOS `ipa`
|
|
- [ ] Verify auth, scan flow, collections, and upload flows
|
|
|
|
## Roadmap
|
|
|
|
- [ ] Optional dark/light theme toggle in settings
|
|
- [ ] Extended scanner confidence hints and retry UX
|
|
- [ ] Bulk actions and better collection analytics
|
|
- [ ] Improved offline behavior for low-connectivity sessions
|
|
|
|
## Contributing
|
|
|
|
See `CONTRIBUTING.md` for branching strategy, commit message rules, and PR guidelines.
|
|
|
|
## Security Notes
|
|
|
|
- Supabase anon keys are intentionally client-side, but RLS and RPC permissions must be strict.
|
|
- Sensitive local config files are git-ignored.
|
|
- User-facing errors are sanitized and shown via global overlays.
|
|
|
|
For reporting vulnerabilities, see `SECURITY.md`.
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT License.
|
|
See `LICENSE` for details.
|
|
|
|
## Reference
|
|
|
|
- Contributor guidelines: `CONTRIBUTING.md`
|
|
- Security policy: `SECURITY.md`
|
|
- Product/backend notes: `TPB.md`
|
|
|