bfs_manager 0.0.2

A dynamic local SQLite database to server synchronization manager for Flutter applications.

Flutter bfs_manager SDK વપરાશ દસ્તાવેજ (Usage Documentation)

આ દસ્તાવેજ (document) સમજાવે છે કે તમારા કોઈપણ ફ્લટર (Flutter) પ્રોજેક્ટમાં bfs_manager SDK લાઇબ્રેરીને કઈ રીતે સેટઅપ અને ઉપયોગ કરવો.

---

૧. લાઇબ્રેરી ઇન્સ્ટોલ કરવી (Installation)

તમે આ લાઇબ્રેરીને GitHub પર અપલોડ કર્યા વગર પણ સીધા તમારા લોકલ કોમ્પ્યુટરના પાથ (local folder path) દ્વારા તમારા અન્ય પ્રોજેક્ટ્સમાં વાપરી શકો છો.

પદ્ધતિ ૧: લોકલ પાથ દ્વારા (GitHub વગર - ભલામણ કરેલ)

જો તમારો મેઈન પ્રોજેક્ટ અને સિંક લાઇબ્રેરી બંને એક જ કોમ્પ્યુટર પર અલગ ફોલ્ડરમાં હોય, તો pubspec.yaml માં નીચે મુજબ પાથ સેટ કરો:

dependencies:
  flutter:
    sdk: flutter
    
  # લોકલ ફોલ્ડર પાથ દ્વારા SDK ઉમેરો (relative અથવા absolute path)
  bfs_manager:
    path: ../bfs_manager # તમારો bfs_manager પેકેજનો પાથ

---

પદ્ધતિ ૨: ગીથબ રિપોઝીટરી દ્વારા (જો ભવિષ્યમાં ઓનલાઈન વાપરવું હોય)

જો ભવિષ્યમાં ગીથબ પરથી ડાયરેક્ટ ઈમ્પોર્ટ કરવું હોય:

dependencies:
  flutter:
    sdk: flutter
    
  bfs_manager:
    git:
      url: https://github.com/your-username/bfs_manager.git
      ref: main

ત્યારબાદ ટર્મિનલમાં આ કમાન્ડ રન કરો:

flutter pub get

---

૨. SDK ઇનિશિયલાઇઝ કરવું (Initialization)

તમારી એપ રન થાય ત્યારે main.dart અથવા ડેટાબેઝ ઇનિશિયલાઇઝ થાય ત્યારે SDK ને ઇનિશિયલાઇઝ કરો. આ માટે તમારે તમારા મેઈન એપ ડેટાબેઝ (sqflite Database instance) અને બેઝ URL (Base URL) પાસ કરવાના રહેશે.

Note

એકવાર લોગિન અથવા રજીસ્ટ્રેશન સફળ થાય એટલે SDK ઇન્ટર્નલી જ Bearer Token સ્ટોર કરી લેશે અને ભવિષ્યના તમામ સિંક API કોલ્સમાં ઓટોમેટિક હેડર સેટ કરી દેશે.

ઉદાહરણ (main.dart માં):

import 'package:flutter/material.dart';
import 'package:bfs_manager/bfs_manager.dart';
import 'package:your_app/database/app_database.dart'; // તમારી એપનો Floor ડેટાબેઝ

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // ૧. તમારી એપનો Floor ડેટાબેઝ બિલ્ડ કરો
  final appDb = await $FloorAppDatabase.databaseBuilder('app_database.db').build();

  // ૨. SDK સિંક મેનેજર ઇનિશિયલાઇઝ કરો
  await BfsManager.instance.init(
    baseUrl: "https://your-domain.com/api",
    appDatabase: appDb.database, // Floor નો sqflite Database ઓબ્જેક્ટ આપો
  );

  runApp(const MyApp());
}

---

૩. લોકલ ડેટાબેઝમાં ઓપરેશન કરવા અને સિંક માટે રજીસ્ટર કરવું (Insert/Update/Delete)

જ્યારે પણ યુઝર પોતાની એપ્લિકેશનમાં કોઈ નવો રેકોર્ડ ઉમેરે (Insert), સુધારે (Update) કે ડીલીટ (Delete) કરે, ત્યારે તેને લોકલી સેવ કરવાની સાથે SDK ના insertLocal ફંક્શનને કોલ કરવું પડશે જેથી તે સિંક કતાર (queue) માં ઉમેરાઈ જાય.

એ. ડેટા ઇન્સર્ટ (Insert) કરતી વખતે:

// ૧. તમારી એપના લોકલ ડેટાબેઝમાં ડેટા સેવ કરો
final task = Task(uuid: "generated-uuid-123", title: "નવું કામ", status: "pending");
await appDb.taskDao.insertTask(task);

// ૨. સિંક કરવા માટે SDK ને ડેટા મોકલો
await BfsManager.instance.insertLocal(
  tableName: "tb_tasks",
  status: "insert", // 'insert' સ્ટેટસ
  data: task.toJson(), // મેપ ફોર્મેટમાં ડેટા (Map<String, dynamic>)
);

---

૪. સિંક્રોનાઇઝેશન એપીઆઈ કોલ કરવા (Sync Operations)

લાઇબ્રેરી આપમેળે બેકએન્ડ એપીઆઈ કોલ કરીને સિંક્રોનાઇઝેશન પૂરું કરશે:

એ. પ્રારંભિક ડેટા ડાઉનલોડ કરવા (Pull All)

જ્યારે યુઝર નવું લોગિન કરે ત્યારે બધો જ સર્વરનો ડેટા ખેંચવા માટે (તમામ સિંક ટેબલના નામની યાદી સાથે):

await BfsManager.instance.pullAll(
  ['tb_tasks', 'tb_categories'], // સિંક કરવાના ટેબલ્સની યાદી
  onStart: () {
    print("સિંક ચાલુ થયું...");
  },
  onComplete: () {
    print("બધો ડેટા લોકલી સિંક થઈ ગયો!");
  },
  onError: (error) {
    print("ભૂલ આવી: $error");
  },
);

બી. લોકલ ફેરફારો સર્વર પર મોકલવા (Push Changes)

બધા જ લોકલી બાકી રહેલા ફેરફારો સર્વર પર આપોઆપ મોકલી દેશે:

await BfsManager.instance.pushChanges();

---

૫. યુઝર ઓથેન્ટિકેશન એપીઆઈ (Login / Register APIs)

જ્યારે પણ યુઝર રજીસ્ટ્રેશન કે લોગિન કરે, ત્યારે SDK ના apiRegister અને apiLogin ફંક્શનનો ઉપયોગ કરીને સર્વર સાથે સીધો કનેક્ટ કરી શકો છો. જો તમારે કોઈ વધારાના પેરામીટર્સ હેડરમાં મોકલવા હોય, તો તમે ઓપ્શનલ extraHeaders પેરામીટર વાપરી શકો છો.

એ. યુઝર લોગિન (Login API)

// લોગિન એપીઆઈ કોલ (ઓપ્શનલ હેડર્સ સાથે)
await BfsManager.instance.apiLogin(
  loginData,
  extraHeaders: {
    "X-App-Platform": "iOS",
    "X-Device-Id": "unique-device-id-xyz"
  },
  onStart: () => print("લોગિન પ્રક્રિયા શરૂ..."),
  onSuccess: (response) async {
    print("લોગિન સફળ!");
    
    // લોગિન સફળ થયા પછી ડેટા પ્રથમ વાર ડાઉનલોડ કરવા માટે pullAll() રન કરો
    await BfsManager.instance.pullAll(['tb_tasks']);
  },
  onFail: (error) => print("લોગિન અસફળ: $error"),
);

---

૬. SDK આંતરિક રીતે ડેટા કઈ રીતે સાચવે છે? (Internal Database Insertion)

ઘણા ડેવલપર્સને પ્રશ્ન થાય છે કે: "મેં મારા પ્રોજેક્ટમાં ટેબલ્સ બનાવ્યા છે, તો બહારથી આવેલો ડેટા SDK આપમેળે કઈ રીતે ટેબલમાં સેવ કરશે?"

આનો ઉત્તર ખૂબ જ સરળ છે. SDK સીધો જ sqflite ની ડાયનેમિક ક્વેરીઝ નો ઉપયોગ કરે છે. તેને કોઈપણ મોડેલ ક્લાસ કે Floor DAO ફાઈલોની જરૂર પડતી નથી.

સિંક ફ્લો પ્રક્રિયા:

૧. જ્યારે તમે SDK શરૂ કરો છો ત્યારે appDatabase: appDb.database પાસ કરો છો. આ ઓબ્જેક્ટ sqflite ડેટાબેઝ સાથે ડાયરેક્ટ જોડાયેલો હોય છે. ૨. જ્યારે સર્વર પરથી કોઈ ડેટા પુલ (pull) થાય છે, ત્યારે SDK તમારા દ્વારા પાસ કરેલા tableName નો ઉપયોગ કરી નીચે મુજબ ક્વેરી રન કરે છે:

// SDK ની અંદર રહેલો આંતરિક સિંક કોડ:
Future<void> dynamicInsertOrReplace(String tableName, Map<String, dynamic> data) async {
  // ૧. ડેટામાંથી કી (Keys) અને વેલ્યુ (Values) ડાયનેમિકલી મેળવવી
  final columns = data.keys.join(",");
  final placeholders = List.generate(data.length, (index) => "?").join(",");
  final values = data.values.toList();
  
  // ૨. sqflite દ્વારા રન-ટાઇમ પર ડાયનેમિક ક્વેરી ચલાવવી
  await appDatabase.rawInsert("""
    INSERT OR REPLACE INTO $tableName
    ($columns)
    VALUES
    ($placeholders)
  """, values);
}

---

૭. સંપૂર્ણ વર્કિંગ ઉદાહરણ (Complete Working Example)

આ સેક્શનમાં મુખ્ય એપમાં ડેટાબેઝ કેવી રીતે બનાવવો અને તેને સ્ક્રીન સાથે કઈ રીતે કનેક્ટ કરવો તે એક સંપૂર્ણ ઉદાહરણ દ્વારા દર્શાવેલ છે.

એ. સ્ટેપ ૧: ડેટાબેઝ એન્ટિટી (Entity) અને DAO વ્યાખ્યાયિત કરવા

તમારા પ્રોજેક્ટમાં Floor લાઇબ્રેરીનો ઉપયોગ કરીને ડેટાબેઝ એન્ટિટી અને DAO બનાવો.

lib/database/task.dart:

import 'package:floor/floor.dart';

@Entity(tableName: 'tb_tasks')
class Task {
  @primaryKey
  final String uuid;
  final String title;
  final String status;

  Task({required this.uuid, required this.title, required this.status});

  // સિંક પેલોડ માટે ડેટાને JSON/Map માં કન્વર્ટ કરવા
  Map<String, dynamic> toJson() {
    return {
      'uuid': uuid,
      'title': title,
      'status': status,
    };
  }
}

lib/database/task_dao.dart:

import 'package:floor/floor.dart';
import 'task.dart';

@dao
abstract class TaskDao {
  @Query('SELECT * FROM tb_tasks')
  Future<List<Task>> getAllTasks();

  @insert
  Future<void> insertTask(Task task);

  @Query('DELETE FROM tb_tasks WHERE uuid = :uuid')
  Future<void> deleteTaskByUuid(String uuid);
}

lib/database/app_database.dart:

import 'dart:async';
import 'package:floor/floor.dart';
import 'package:sqflite/sqflite.dart' as sqflite;
import 'task.dart';
import 'task_dao.dart';

part 'app_database.g.dart'; // Floor કોડ જનરેશન ફાઈલ

@Database(version: 1, entities: [Task])
abstract class AppDatabase extends FloorDatabase {
  TaskDao get taskDao;
}

---

બી. સ્ટેપ ૨: ફ્લટર સ્ક્રીનમાં ઉપયોગ (Task List Screen)

આ સ્ક્રીન લોકલ ડેટાબેઝમાંથી ડેટા બતાવશે, નવો ડેટા ઉમેરશે અને સર્વર સાથે ઓટો-સિંક કરશે.

lib/screens/task_screen.dart:

import 'package:flutter/material.dart';
import 'package:uuid/uuid.dart';
import 'package:bfs_manager/bfs_manager.dart';
import '../database/app_database.dart';
import '../database/task.dart';

class TaskScreen extends StatefulWidget {
  final AppDatabase database;

  const TaskScreen({super.key, required this.database});

  @override
  State<TaskScreen> createState() => _TaskScreenState();
}

class _TaskScreenState extends State<TaskScreen> {
  final TextEditingController _taskController = TextEditingController();
  List<Task> _tasks = [];
  bool _isLoading = false;

  @override
  void initState() {
    super.initState();
    _loadLocalTasks();
  }

  // લોકલ ડેટાબેઝમાંથી ડેટા લોડ કરવો
  Future<void> _loadLocalTasks() async {
    final tasks = await widget.database.taskDao.getAllTasks();
    setState(() {
      _tasks = tasks;
    });
  }

  // નવો ટાસ્ક ઉમેરવો અને સિંક માટે રજીસ્ટર કરવો
  Future<void> _addTask() async {
    final title = _taskController.text.trim();
    if (title.isEmpty) return;

    final String localUuid = const Uuid().v4(); // લોકલ યુનિક આઈડી

    final newTask = Task(
      uuid: localUuid,
      title: title,
      status: 'pending',
    );

    // ૧. મુખ્ય એપના ડેટાબેઝમાં લોકલી સેવ કરો
    await widget.database.taskDao.insertTask(newTask);

    // ૨. સિંક માટે SDK ના Task Queue માં રજીસ્ટર કરો
    await BfsManager.instance.insertLocal(
      tableName: 'tb_tasks',
      status: 'insert',
      data: newTask.toJson(),
    );

    _taskController.clear();
    _loadLocalTasks(); // સ્ક્રીન અપડેટ કરો

    // ૩. સર્વર પર તાત્કાલિક અપલોડ (Push) ચાલુ કરો (Background માં ચાલશે)
    BfsManager.instance.pushChanges();
  }

  // સર્વર પરથી નવા અપડેટ્સ મેળવવા (Incremental Pull)
  Future<void> _syncUpdates() async {
    setState(() => _isLoading = true);
    try {
      // સર્વરના ફેરફારો ખેંચો અને લોકલ ડેટાબેઝમાં ઓટો-અપડેટ કરો
      await BfsManager.instance.pullUpdates();
      await _loadLocalTasks(); // ફ્રેશ ડેટા લોકલ ડેટાબેઝમાંથી પાછો લોડ કરો
      ScaffoldMessenger.of(context).showSnackBar(
        const SnackBar(content: Text("સિંક સફળ રહ્યો!")),
      );
    } catch (e) {
      ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(content: Text("સિંક અસફળ: $e")),
      );
    } finally {
      setState(() => _isLoading = false);
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text("સિંક ટાસ્ક લિસ્ટ (Sync Tasks)"),
        actions: [
          IconButton(
            icon: _isLoading 
              ? const SizedBox(width: 20, height: 20, child: CircularProgressIndicator(color: Colors.white, strokeWidth: 2)) 
              : const Icon(Icons.sync),
            onPressed: _isLoading ? null : _syncUpdates,
          )
        ],
      ),
      body: Column(
        children: [
          Padding(
            padding: const EdgeInsets.all(8.0),
            child: Row(
              children: [
                Expanded(
                  child: TextField(
                    controller: _taskController,
                    decoration: const InputDecoration(hintText: "નવો ટાસ્ક લખો..."),
                  ),
                ),
                IconButton(
                  icon: const Icon(Icons.add_circle, color: Colors.blue, size: 40),
                  onPressed: _addTask,
                )
              ],
            ),
          ),
          Expanded(
            child: _tasks.isEmpty
              ? const Center(child: Text("કોઈ ટાસ્ક નથી. ઉમેરવા માટે + બટન દબાવો."))
              : ListView.builder(
                  itemCount: _tasks.length,
                  itemBuilder: (context, index) {
                    final item = _tasks[index];
                    return ListTile(
                      title: Text(item.title),
                      subtitle: Text("UUID: ${item.uuid}"),
                      trailing: Text(item.status, style: const TextStyle(color: Colors.grey)),
                    );
                  },
                ),
          ),
        ],
      ),
    );
  }
}