Thêm README.md cho dự án

2026-06-25 20:07:52 +07:00
parent 8df94bca26
commit 48ffd7e49b
1 changed files with 133 additions and 0 deletions
@@ -0,0 +1,133 @@
+# Travel Planning - Multi-User Travel Itinerary Management System
+
+A comprehensive travel planning application that enables collaborative itinerary planning, expense tracking, and photo sharing for travel groups.
+
+## Features
+
+- **Tour Management**: Create and manage travel tours with multiple legs (stages) and locations
+- **Multi-user Collaboration**: Invite friends to join tours with role-based access control
+- **Interactive Maps**: Visual tour planning with Leaflet.js integration
+- **Expense Tracking**: Automatic cost splitting with configurable adult/child discounts
+- **Photo Sharing**: Secure photo album with privacy controls (PUBLIC, TOUR_ONLY, PRIVATE)
+- **Real-time Navigation**: Live GPS tracking and route optimization using OSRM API
+
+## Tech Stack
+
+| Layer | Technology | Purpose |
+|-------|-----------|---------|
+| **Frontend** | React + Vite | Single Page Application with fast HMR |
+| | TailwindCSS | Utility-first CSS framework |
+| | Zustand | Lightweight state management |
+| | Leaflet.js | Interactive map rendering |
+| **Backend** | NestJS | Scalable Node.js framework |
+| | JWT | Authentication & authorization |
+| | Prisma ORM | Type-safe database access |
+| | PostgreSQL + PostGIS | Spatial database for geographic data |
+
+## Project Structure
+
+```
+travelplanning/
+├── backend/                    # Backend API server
+│   ├── src/
+│   │   ├── auth/              # Authentication modules
+│   │   ├── main.ts            # NestJS entry point
+│   │   └── v1/              # API v1 endpoints
+│   └── prisma/
+│       └── schema.prisma      # Database schema
+├── frontend/                   # React frontend
+│   └── src/
+│       ├── pages/            # Main pages
+│       ├── components/       # Reusable UI components
+│       ├── hooks/          # Custom React hooks
+│       └── store/          # Zustand stores
+├── docs/                      # Documentation
+│   ├── ARCHITECTURE.md        # System architecture
+│   └── UITourDesign.md        # UI design specifications
+└── .env                       # Environment variables
+```
+
+## Database Schema
+
+The application uses PostgreSQL with Prisma ORM. Key models include:
+
+- **User**: Registered users with admin capability
+- **Tour**: Travel itineraries with date ranges and participant management
+- **Leg**: Stages within a tour (ordered sequence)
+- **Location**: Geographic points with timing and status tracking
+- **Expense**: Cost tracking linked to legs/locations
+- **Photo**: Media storage with privacy controls
+- **TourParticipant**: Many-to-many relationship with role-based permissions
+
+### User Roles
+
+| Role | Permissions |
+|------|-------------|
+| OWNER | Full access to all features |
+| MANAGER | Can edit tour content and manage members |
+| MEMBER | View tour and participate, access financial data |
+| MEMBER_NO_FINANCE | View tour only, no financial access |
+| VIEWER_ONLY | Read-only access to itinerary and photos |
+
+## API Endpoints
+
+### Tours
+- `GET /api/v1/tours` - Get all public tours
+- `POST /api/v1/tours` - Create new tour
+- `GET /api/v1/tours/:id` - Get tour details
+- `PUT /api/v1/tours/:id` - Update tour
+
+### Authentication
+- `POST /api/v1/auth/login` - User login
+- `POST /api/v1/auth/register` - User registration
+- `POST /api/v1/auth/promote-admin` - Admin role promotion (with secret key)
+
+### Photos
+- `GET /api/v1/public-photos` - Get public photos
+- `POST /api/v1/tours/:id/photos` - Upload tour photos
+
+## Quick Start
+
+### Prerequisites
+- Node.js 18+
+- PostgreSQL with PostGIS extension
+
+### Installation
+
+```bash
+# Install dependencies
+npm install
+cd frontend && npm install
+cd ../backend && npm install
+
+# Set up database
+npx prisma migrate dev
+npx prisma generate
+
+# Start development servers
+npm run dev                    # Frontend (Vite)
+npm run start:backend          # Backend (NestJS)
+```
+
+### Environment Variables
+
+Create `.env` in the root directory:
+
+```env
+DATABASE_URL="postgresql://user:password@localhost:5432/traveldb"
+JWT_SECRET="your-secret-key"
+```
+
+## Mobile Optimization
+
+The application is built mobile-first with support for:
+- Safe area insets for notch displays (iOS/Android)
+- Touch gestures for map interactions
+- Responsive layouts for all screen sizes
+- Device orientation and compass integration
+
+## Documentation
+
+See the `docs/` directory for detailed documentation:
+- [ARCHITECTURE.md](docs/ARCHITECTURE.md) - System architecture and data models
+- [UITourDesign.md](docs/UITourDesign.md) - UI design specifications