README.md (versão em inglês)

# 📚 Book Manager (Gestão de Livros)

**Turn your WordPress site into a complete school library system.**

This plugin was built for schools that want to modernize their collection management, lending, and student engagement — all inside WordPress, without installing external systems and without paying anything.

---

## 🚀 What does this plugin do?

| Module | Features |
|--------|----------|
| 📖 **Public Catalog** | Book showcase with covers, filters (genre, category, discipline), and search bar |
| 🧑‍🎓 **Students & Teachers** | Registration with approval, custom fields, library card, profile photo |
| 🔄 **Full Circulation** | Reservations with waiting list, checkouts, returns, and renewals |
| 🏥 **Service Desk** | Quick screen with barcode scanner, book registration by ISBN, and queue management |
| 🎮 **Gamification** | XP, automatic badges, reading leaderboard, reading logs with reviews and videos |
| 🤖 **Artificial Intelligence** | Automatic discipline classification, activity generator, and "Diva" chatbot (uses Groq) |
| 📞 **WhatsApp** | Send return reminders, overdue notices, and notifications with one click |
| 🏷️ **Professional Cataloging** | Call Number (CDU/Cutter) generated by AI, A4 label printing |
| 📊 **Reports** | 8 report types with charts and PDF export |
| ⚙️ **School Settings** | Custom name, logo, footer. Adjustable limits, loan periods, and fines |
| 📦 **Import/Export** | CSV and ZIP for books, students, loan history, reading logs, and settings |
| 🔄 **School Year Transition** | Reset XP and badges, automatic re-registration, leaderboard backup |

---

## 📸 Screenshots

*[Add screenshots here: public catalog, student dashboard, service desk, librarian dashboard]*

---

## 🧩 Installation

1. Download the plugin (`.zip` file)
2. In your WordPress dashboard, go to **Plugins → Add New → Upload Plugin**
3. Choose the file and click **Install Now**
4. Activate the plugin
5. A new **Library** menu will appear in the sidebar

**Done!** No additional configuration is required. You can start adding books immediately.

---

## 🔌 API Setup (optional, but recommended)

To use AI features and automatic cover search, configure the keys in **Library → Settings → APIs**:

| API | Purpose | Where to get it |
|-----|---------|-----------------|
| **Google Books** | Auto-fetch book covers and synopses | [console.cloud.google.com](https://console.cloud.google.com) |
| **Groq** | Discipline classification, activities, Diva chatbot | [console.groq.com](https://console.groq.com) (free, 1,500 req/day) |
| **YouTube Data API** | Search for video reviews during CSV import | [console.cloud.google.com](https://console.cloud.google.com) |

---

## 💡 Quick Start

### Adding Books
1. Go to **Library → Add New**
2. Fill in title, author, publisher, and ISBN
3. Click **Fetch Cover** to automatically get the cover from Google Books
4. Use **Classify with AI** to automatically assign disciplines

### Registering Students
1. Students can self-register via the `[bm_register]` page (place this shortcode on a page called "My Account")
2. The librarian approves registrations in **Library → Students → Approve Registrations**

### Checking Out Books
1. Use the **Service Desk** for quick checkouts (supports barcode scanner)
2. Students can reserve books directly from the book page (**Reserve** button)

---

## 🧑‍💼 Who is this plugin for?

- School libraries (elementary, middle, and high school)
- Reading rooms
- Small community libraries
- Any institution needing a simple, complete library system integrated with WordPress

---

## 🛠️ Technology

- **Native WordPress:** Custom Post Types, User Meta, Post Meta, Transients API
- **PHP 7.4+** and **MySQL/MariaDB** (already included with WordPress)
- **No external dependencies:** No composer, npm, CDN, or additional frameworks
- **AI via Groq API** (free) for classification, activities, and chatbot
- **Modular code:** Built for easy maintenance and expansion

---

## 📖 Full Documentation

The project documentation is organized in three files within the repository:

| File | Content |
|------|---------|
| `claude.md` | Behavior guidelines and code governance |
| `escopo.md` | Technical specifications, data structure, and security barriers |
| `roadmap.md` | Development phases and planned features |

---

## 🤝 Contributing

This is an open-source project. If you find bugs, have suggestions, or want to contribute code:

1. Open an **issue** describing the problem or suggestion
2. Fork the repository
3. Submit a **pull request** with your changes

All contributions are welcome!

---

## 👨‍💻 Author

**Daniel Pereira**  
[GitHub](https://github.com/odanielpereira) | [Website](https://odanielpereira.com)

---

## 📄 License

This plugin is licensed under **GPL v2.0 or later** — the same license as WordPress.  
Feel free to use, modify, and distribute it.

---

**Thank you for using Book Manager!** 📚

Pronto para levar ao Chat 11, se precisar de ajuda para revisar ou ajustar o tom.