# 🎉 Android Photo App - Complete Setup Guide

## ✅ Project Status: READY FOR DEVELOPMENT

Your Vue + Cordova Android photo printing app is fully configured and running!

---

## 🚀 Quick Start Commands

### **Development Mode** (Hot Reload Enabled)
```bash
cd "/Applications/XAMPP/xamppfiles/htdocs/Android Photo App"
npm run serve
```
**→ Opens at http://localhost:8080**

### **Build for Android** 
```bash
# Debug APK
npm run cordova-build

# Release APK (signed)
npm run cordova-build-apk
```

---

## 📁 Project Structure

```
Android Photo App/
├── src/                         ← ⭐ EDIT HERE (Vue source)
│   ├── main.js                  Vue app entry point
│   ├── App.js                   Main component (UI & logic)
│   └── utils.js                 API, printing, validation
│
├── public/                      ← Static files
│   ├── index.html               HTML template (auto-enhanced by Vue)
│   ├── js/
│   │   └── cordova-init.js      Cordova lifecycle
│   └── css/
│       └── styles.css           Global styles
│
├── dist/                        ← Build output (auto-generated)
├── www/                         ← Cordova web files (auto-generated)
├── platforms/                   ← Android/iOS platforms
│   └── android/
│       └── build/outputs/apk/
│           ├── debug/           Debug APK
│           └── release/         Release APK
│
├── config.xml                   Cordova configuration
├── package.json                 Dependencies & scripts
├── vue.config.js                Vue CLI config
├── babel.config.js              JavaScript transpilation
└── README.md                    Full documentation
```

---

## 🎯 Current Features

✅ **Photo Gallery**
- 2-column responsive layout
- Auto-scrolls when needed
- 60DVH height (60% of viewport height)

✅ **Photo Selection**
- Click to select/deselect
- Visual blue border when selected
- Toggle by clicking again

✅ **Printing**
- OS Print: Uses native Android dialog
- IP Print: Connects via IPP protocol (192.168.x.x format)
- Auto-converts images to Base64

✅ **Input Validation**
- IP format checker
- API error handling
- User-friendly error messages (Chinese)

✅ **UI/UX**
- 16:9 aspect ratio container
- Portrait-only orientation
- Responsive sizing with percentages
- Smooth animations & transitions

---

## 🔧 Development Workflow

### 1. **Start Dev Server**
```bash
npm run serve
```
- Server runs at `http://localhost:8080`
- Auto-reloads on file changes
- Supports hot module replacement (HMR)

### 2. **Edit Source Files**
All source files are in `src/`:
- `src/App.js` - UI layout, photo gallery, buttons
- `src/utils.js` - API calls, validation, printing
- `src/main.js` - Vue app initialization

### 3. **Test in Browser**
Open http://localhost:8080:
- Photo gallery displays (fetches from API)
- Click photos to select
- Enter printer IP (format: 192.168.x.x)
- Test print buttons

### 4. **Build Production**
```bash
npm run build-cordova
```
- Compiles Vue to optimized JavaScript
- Copies assets to `www/` for Cordova
- Ready for `cordova build android`

---

## 📱 Building APK

### **Quick Build (Debug)**
```bash
npm run cordova-build
```
**Output:** `platforms/android/build/outputs/apk/debug/app-debug.apk`

### **Release Build (Signed for Play Store)**
```bash
# First time: Create keystore
keytool -genkey -v -keystore ~/keys/photoapp.keystore \
  -keyalg RSA -keysize 2048 -validity 10000 \
  -alias photoapp -storepass YOUR_PASSWORD -keypass YOUR_PASSWORD

# Build release APK
npm run cordova-build-apk
```
**Output:** `platforms/android/build/outputs/apk/release/app-release.apk`

### **Install on Device**
```bash
adb install -r platforms/android/build/outputs/apk/debug/app-debug.apk
```

---

## 🔌 API Configuration

**Endpoint:** `https://5ml.mmdbfiles.com/list_json.php`

**Token:** (Already configured in `src/utils.js`)
```javascript
const API_TOKEN = 'aGY94sMpQsoWY63AcdUgrqLLVJ83Bm0EctAQDH2AEgxjH715r21f3Q8OG2fl0kOl'
```

**Response Format:**
```json
[
  {
    "photo": "https://5ml.mmdbfiles.com/assets/0200c94b95254235ba34795a.png",
    "file_name": "0200c94b95254235ba34795a.png",
    "date": "2026-04-27 13:58:35"
  }
]
```

---

## 🎨 Customization

### **Change App Name**
Edit `config.xml`:
```xml
<name>Your App Name</name>
```

### **Change App ID**
Edit `config.xml`:
```xml
<widget id="com.yourcompany.appname" ...>
```

### **Add Logo**
Place logo image at: `public/assets/logo.png`

Edit `src/App.js` (change `v-if="false"` to `v-if="true"`):
```javascript
<img src="./assets/logo.png" alt="Logo" class="logo" v-if="true">
```

### **Change Colors**
Edit color values in `src/App.js` styles section:
```javascript
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
// Change #667eea and #764ba2 to your colors
```

---

## ⚙️ npm Scripts Reference

```bash
npm run serve              # Start dev server (http://localhost:8080)
npm run build              # Build Vue app to dist/
npm run build-cordova      # Build Vue + copy to www/
npm run cordova-build      # Build debug APK
npm run cordova-build-apk  # Build release APK (signed)
```

---

## 🐛 Troubleshooting

### **Dev Server Won't Start**
```bash
# Kill existing process
pkill -f "vue-cli-service"

# Clear node_modules cache
rm -rf node_modules/.cache

# Reinstall dependencies
npm install

# Start again
npm run serve
```

### **APK Build Fails**
```bash
# Clean and rebuild
cordova clean
npm run build-cordova
npm run cordova-build
```

### **Cannot Connect to API**
- Check internet connectivity
- Verify token is valid
- Check if endpoint is accessible: https://5ml.mmdbfiles.com/list_json.php
- Check browser console (F12) for CORS errors

### **Printer Connection Failed**
- Ensure printer is on WiFi
- Verify IP address format: 192.168.x.x
- Test printer is reachable: `ping 192.168.x.x`
- Check printer supports IPP protocol

---

## 📋 Environment Info

- **Node.js**: Required (v14+)
- **npm**: Package manager (comes with Node.js)
- **Cordova**: CLI tool for mobile apps
- **Android SDK**: Required for Android builds
- **Java**: Required (JDK 8+)

---

## 🔗 Useful Resources

- **Vue.js Documentation**: https://vuejs.org/
- **Cordova Documentation**: https://cordova.apache.org/docs/
- **Android Studio**: https://developer.android.com/studio
- **Printer Plugin**: https://github.com/katzer/cordova-plugin-printer

---

## 💡 Next Steps

1. ✅ **Verify app is running** at http://localhost:8080
2. 🖼️ **Add your logo** to `public/assets/logo.png`
3. 🎨 **Customize colors** in `src/App.js`
4. 📸 **Test photo loading** - click a photo to select it
5. 🖨️ **Test printing** (requires printer access)
6. 🔨 **Build APK** when ready: `npm run cordova-build`
7. 📤 **Deploy to device** via `adb install`

---

## ✨ You're All Set!

The app is fully functional and ready for development. Start with `npm run serve` and enjoy hot-reload development!

If you have any questions, refer to the [README.md](README.md) or [QUICKSTART.md](QUICKSTART.md) files.

Happy coding! 🚀