প্রকল্প সম্পর্কে

# অ্যাটিক অ্যাটিক একটি ওপেন-সোর্স, সেলফ-হোস্টেড হোম ইনভেন্টরি অ্যাপ্লিকেশন যা ব্যক্তি ও পরিবারের জন্য। এটি আপনার মালিকানার সবকিছু—যন্ত্রপাতি, টুলস, ইলেকট্রনিকস, বই, গেম, আসবাব—ক্যাটালগ করতে দেয় এবং অবস্থান, অবস্থা, ক্রয়ের তথ্য, ওয়ারেন্টি, ছবি, রসিদ ও ম্যানুয়াল একসাথে রাখে। এটি একটি বাড়ির সংগঠনকে নেস্টেড লোকেশন (রুম, শেলফ, ক্যাবিনেট, বক্স) দিয়ে মিরর করে। ক্যাটাগরি ও কাস্টম ফিল্ড প্রতিটি আইটেম টাইপের বিস্তারিত ক্যাপচার করে, এবং কালেকশন স্টোরেজ পরিবর্তন না করে সম্পর্কিত আইটেম গ্রুপ করে। এটি একটি নির্দিষ্ট কালেকশন বা সম্পূর্ণ পরিবারের ইনভেন্টরির জন্য কাজ করে। ## মূল বৈশিষ্ট্য **হোম ইনভেন্টরি** - প্রতিটি ক্যাটাগরির জন্য কাস্টম অ্যাট্রিবিউটসহ (স্ট্রিং, নাম্বার, বুলিয়ান, ডেট, ড্রপডাউন) সম্পূর্ণ CRUD - হায়ারার্কিক্যাল ক্যাটাগরি ও লোকেশন; চাইল্ড ক্যাটাগরি অ্যানসেস্টর কাস্টম ফিল্ড ইনহেরিট করে - কন্ডিশন ট্র্যাকিং (নতুন, ব্যবহৃত, ক্ষতিগ্রস্ত, বা কাস্টম) - ড্যাশবোর্ডে ওয়ারেন্টি মেয়াদ শেষ হওয়ার মনিটরিং - ইনভয়েস, ম্যানুয়াল, ছবির জন্য ফাইল অ্যাটাচমেন্ট - শেয়ার্ড হাউসহোল্ড কালেকশন (যেমন PS5 গেম, বই, আসবাব); একাধিক কালেকশনে অ্যাসেট অ্যাসাইন, কালেকশন দিয়ে ফিল্টার; কালেকশন ডিলিট করলে অ্যাসেট সংরক্ষিত থাকে - ক্রয়ের তারিখ, মূল্য, নোটসহ ড্যাশবোর্ড ভ্যালু সামারি **সার্চ ও ডিসকভারি** - অ্যাসেট নাম ও বর্ণনার মধ্যে ফুল-টেক্সট সার্চ - ক্যাটাগরি, লোকেশন, কন্ডিশন দিয়ে ফিল্টার; ক্যাটাগরি ফিল্টারে ডিসেন্ড্যান্ট ক্যাটাগরি অন্তর্ভুক্ত - কেস-ইনসেনসিটিভ সাবস্ট্রিংসহ অ্যাট্রিবিউট ভ্যালু সার্চ, ড্রপডাউন লেবেলসহ - টাইপড অ্যাট্রিবিউট তুলনা ও কালেকশন মেম্বারশিপসহ নেস্টেড Match all (AND) / Match any (OR) ফিল্টার তৈরি - প্রাইভেটভাবে নামযুক্ত ফিল্টার সেভ; সাইডবার শর্টকাট হিসেবে সর্বোচ্চ পাঁচটি পিন; অ্যাডমিন অন্য ইউজারদের সেভ করা ফিল্টার অ্যাক্সেস করতে পারে না **স্মার্ট ইন্টিগ্রেশন** - Google Books, TMDB (মুভি/টিভি), BoardGameGeek, IGDB (ভিডিও গেম) থেকে স্বয়ংক্রিয় ইমপোর্ট - মেটাডেটা ও কভার ইমেজ স্বয়ংক্রিয়ভাবে পপুলেট - নতুন ইমপোর্ট সোর্সের জন্য প্লাগইন সিস্টেম Google Books ক্রেডেনশিয়াল ছাড়াই কাজ করে কিন্তু শেয়ার্ড কোটা কম হতে পারে; নির্ভরযোগ্য ইমপোর্টের জন্য `ATTIC_GOOGLE_BOOKS_API_KEY` সেট করুন। IGDB-এর জন্য Twitch অ্যাপ্লিকেশন থেকে `ATTIC_IGDB_CLIENT_ID` ও `ATTIC_IGDB_CLIENT_SECRET` প্রয়োজন; টোকেন শুধু মেমরিতে রাখা হয়। **সেলফ-হোস্টেড ও সিকিউর** - Docker-ভিত্তিক ডিপ্লয়মেন্ট, সম্পূর্ণ ডেটা মালিকানা - লোকাল পাসওয়ার্ড অথ ও OIDC/SSO (Keycloak সামঞ্জস্যপূর্ণ) - Swagger ডকসসহ REST API - অ্যাটাচমেন্টের জন্য লোকাল বা S3-সামঞ্জস্যপূর্ণ স্টোরেজ - ডার্ক মোড, মোবাইল-রেসপন্সিভ UI ## অ্যাসেট ফিল্টার একটি টার্মের জন্য **Search attribute values** বা নিয়ম ও নেস্টেড গ্রুপ কম্বাইন করতে **Advanced filter** ব্যবহার করুন। টেক্সট equals/contains সমর্থন করে; নাম্বার/ডেট তুলনা ও রেঞ্জ সমর্থন করে; বুলিয়ান true/false; ড্রপডাউন যেকোনো অপশন; একাধিক সিলেকশন ও কালেকশন all সমর্থন করে। প্রতিটি অ্যাট্রিবিউট empty/not-empty চেক সমর্থন করে (null, খালি স্ট্রিং, খালি অ্যারে empty হিসেবে গণ্য; শূন্য ও false নয়)। কুইক সার্চ ভ্যালু ও ড্রপডাউন লেবেল ম্যাচ করে, অ্যাট্রিবিউট নাম বা ইন্টারনাল ID নয়। `%`, `_`, ব্যাকস্ল্যাশ লিটারাল। শুধু সক্রিয়, দৃশ্যমান অ্যাট্রিবিউট অংশগ্রহণ করে। কুইক সার্চ, পেজ ফিল্টার ও অ্যাডভান্সড নিয়ম AND দিয়ে কম্বাইন হয়। ড্রাফট প্রয়োগ করুন, নতুন নামযুক্ত ফিল্টার হিসেবে সেভ করুন, বা বিদ্যমান আপডেট করুন। সেভ করা ক্রাইটেরিয়া পেজিনেশন বাদ দেয়। ডিলিট করা রেফারেন্স বা ইনকম্প্যাটিবল পরিবর্তনের জন্য নিয়ম মেরামত প্রয়োজন; রিনেম স্থিতিশীল ID দিয়ে রেফারেন্স সংরক্ষণ করে। API: `GET /api/assets?attribute_q=Commodore`, `POST /api/assets/search` দিয়ে স্ট্রাকচার্ড সার্চ, `/api/saved-filters`-এর অধীনে পার্সোনাল CRUD। উদাহরণ বডি: ```json { "criteria": { "version": 1, "expression": { "kind": "group", "match": "all", "children": [ { "kind": "rule", "field": "attribute_q", "operator": "contains", "value": "Commodore" }, { "kind": "rule", "field": "q", "operator": "search", "value": "computer" } ] } }, "limit": 20, "offset": 0 } ``` `{"name":"Retro computers","criteria":{...}}` দিয়ে সেভ করা ফিল্টার তৈরি করুন; `PUT /api/saved-filters/{id}` দিয়ে আপডেট করুন। `criteria` বাদ দিলে শুধু রিনেম হয়। GET/list রেসপন্সে অবৈধ ডেফিনিশনের জন্য `issues` অন্তর্ভুক্ত। এক্সপ্রেশন ৫টি গ্রুপ লেভেল, ৫০টি নিয়ম, মেম্বারশিপ নিয়মে ১০০টি ভ্যালু অনুমোদন করে; JSON বডি ৬৪ KiB-তে সীমাবদ্ধ। সম্পূর্ণ wire format-এর জন্য `/api/docs` দেখুন। ## কুইক স্টার্ট ### পূর্বশর্ত - Docker ও Docker Compose, Go 1.27+, Bun 1.1+, Make ### ডেভেলপমেন্ট সেটআপ 1. ক্লোন ও ইনফ্রা চালু: `git clone [email protected]:lmmendes/attic.git && cd attic && docker compose up -d` 2. মাইগ্রেশন চালান: `make migrate-up` 3. ব্যাকএন্ড চালু: `cd backend && go run ./cmd/server` 4. ফ্রন্টএন্ড চালু (নতুন টার্মিনাল): `cd frontend && bun install && bun run dev` 5. অ্যাপ খুলুন: - ফ্রন্টএন্ড: http://localhost:3000 - ব্যাকএন্ড API: http://localhost:8080 - API ডকস: http://localhost:8080/api/docs - Keycloak: http://localhost:8180 - ডিফল্ট টেস্ট ক্রেডেনশিয়াল: `testuser` / `testpassword` ### ব্রাউজার ইন্টিগ্রেশন টেস্ট Playwright স্যুট প্রকৃত ব্রাউজার ওয়ার্কফ্লো টেস্ট করে (লগইন, ক্যাটাগরি/অ্যাট্রিবিউট হ্যান্ডঅফ, ফিচার সেটিংস)। ```bash cd frontend bunx playwright install chromium bun run test:e2e ``` `http://127.0.0.1:3000`-এ Nuxt dev সার্ভার টার্গেট করে; অন্য ইনস্ট্যান্সের জন্য `E2E_BASE_URL` সেট করুন। GitHub Actions প্রতিটি PR-এ একই স্যুট চালায়। ### প্রোডাকশন ডিপ্লয়মেন্ট ```bash cp .env.example .env # Edit .env docker compose -f docker-compose.prod.yml up -d --build docker compose -f docker-compose.prod.yml exec backend \ /app/migrate -path /migrations -database "$DATABASE_URL" up ``` আরও বিস্তারিত [getattic.dev](https://getattic.dev)-এ। ## টেক স্ট্যাক | কম্পোনেন্ট | টেকনোলজি | |-----------|------------| | ব্যাকএন্ড | Go 1.27, Chi router, PostgreSQL | | ফ্রন্টএন্ড | Nuxt 4, Nuxt UI 4, Tailwind CSS | | অথ | লোকাল পাসওয়ার্ড বা OIDC/SSO | | স্টোরেজ | S3-সামঞ্জস্যপূর্ণ (AWS S3, MinIO, LocalStack) | ## লাইসেন্স MIT