راهنمای راه‌اندازی سامانه شفافیت مالی مدرسه

فهرست مطالب

• معرفی پروژه
• پیش‌نیازها
• مراحل راه‌اندازی
• ساختار فایل CSV
• تنظیمات گوگل شیت
• استقرار روی GitHub Pages
• مدیریت و نگهداری

معرفی پروژه

این یک سامانه تحت وب برای نمایش شفاف درآمدها و هزینه‌های مدرسه است که به صورت رایگان و متن‌باز توسعه یافته است. ویژگی‌های اصلی:

• 📊 نمایش گرافیکی تراکنش‌های مالی
• 📱 طراحی واکنش‌گرا (قابل نمایش روی موبایل و تبلت)
• 🔄 اتصال خودکار به Google Sheets برای به‌روزرسانی داده‌ها
• 🎨 رابط کاربری فارسی و زیبا
• 🔒 عدم نیاز به پایگاه داده جداگانه

پیش‌نیازها

برای راه‌اندازی این سامانه برای مدرسه جدید، به موارد زیر نیاز دارید:

1. یک حساب Gmail - برای ایجاد Google Sheets
2. یک حساب GitHub - برای میزبانی فایل‌ها
3. دسترسی به اینترنت - برای بارگذاری فایل‌ها

مراحل راه‌اندازی

مرحله ۱: ایجاد حساب‌های مورد نیاز

الف) ایجاد حساب Gmail جدید (در صورت نیاز)

1. به آدرس gmail.com بروید
2. روی "Create account" کلیک کنید
3. اطلاعات مدرسه را وارد کنید (مثلاً: fatemieh.hojaghan@gmail.com)
4. حساب جدید را تأیید کنید

ب) ایجاد حساب GitHub جدید (در صورت نیاز)

1. به آدرس github.com بروید
2. روی "Sign up" کلیک کنید
3. اطلاعات مدرسه را وارد کنید
4. حساب جدید را تأیید کنید

مرحله ۲: ایجاد Google Sheets جدید

الف) ایجاد شیت جدید

1. به آدرس sheets.google.com بروید
2. روی "+ Blank" کلیک کنید تا شیت جدید ایجاد شود
3. نام شیت را به "school_finance" تغییر دهید

ب) تنظیم ساختار شیت

ستون‌های زیر را در سطر اول (هدر) وارد کنید:

ستون اول	ستون دوم	ستون سوم	ستون چهارم	ستون پنجم	ستون ششم
نوع	عنوان	مبلغ	شخص	تاریخ	دسته‌بندی

ج) وارد کردن داده‌های نمونه

می‌توانید از داده‌های نمونه زیر استفاده کنید:

نوع,عنوان,مبلغ,شخص,تاریخ,دسته‌بندی
income,کمک مالی اولیای پایه اول,3500000,انجمن اولیا و مربیان,1402/07/05,کمک مالی
expense,خرید کتاب‌های درسی,1850000,مدیریت مدرسه,1402/07/15,کالای آموزشی

مرحله ۳: انتشار Google Sheets به صورت عمومی

الف) تنظیمات اشتراک‌گذاری

1. در Google Sheets روی دکمه "Share" کلیک کنید
2. روی "Change to anyone with the link" کلیک کنید
3. گزینه "Viewer" را انتخاب کنید
4. روی "Copy link" کلیک کنید

ب) انتشار به فرمت CSV

1. از منوی "File" گزینه "Share" را انتخاب کنید
2. روی "Publish to web" کلیک کنید
3. از dropdown گزینه "Comma-separated values (.csv)" را انتخاب کنید
4. روی "Publish" کلیک کنید
5. لینک ایجاد شده را کپی کنید

مرحله ۴: ایجاد ریپازیتوری GitHub

الف) ایجاد ریپازیتوری جدید

1. به آدرس github.com بروید و وارد شوید
2. روی علامت "+" در بالای صفحه کلیک کنید
3. "New repository" را انتخاب کنید
4. نام ریپازیتوری را وارد کنید (مثلاً: school-finance-fatemiyeh)
5. گزینه "Public" را انتخاب کنید
6. تیک "Add a README file" را بزنید
7. روی "Create repository" کلیک کنید

ب) آپلود فایل‌ها

1. در صفحه ریپازیتوری، روی "Add file" → "Upload files" کلیک کنید
2. فایل index.html را آپلود کنید
3. در پایین صفحه روی "Commit changes" کلیک کنید

مرحله ۵: تنظیم لینک Google Sheets در کد

الف) ویرایش فایل index.html

در فایل index.html خط زیر را پیدا کنید:

const CSV_FILE_PATH = 'https://docs.google.com/spreadsheets/d/e/2PACX-1vTxKbZzfIawiNSsxkU3eEJWXtuGFrLU462XxPpVofuIQGDRcibsDWSwevWl5F4XlBiXsMyDQm0Kyg40/pub?output=csv';

لینک خود را جایگزین کنید:

const CSV_FILE_PATH = 'لینک-کپی-شده-از-گوگل-شیت-شما';

ب) ویرایش لینک ویرایش اطلاعات

خط زیر را پیدا کنید و لینک Google Sheets خود را جایگزین کنید:

window.open('https://docs.google.com/spreadsheets/d/1REA4d7ZXSTZXLTxZlKztiexZ9erah8ci-U3f6ToQLW4/edit?pli=1&gid=0#gid=0', '_blank');

مرحله ۶: فعال‌سازی GitHub Pages

1. به ریپازیتوری خود در GitHub بروید
2. به تب "Settings" بروید
3. در منوی سمت چپ، "Pages" را انتخاب کنید
4. در بخش "Source"، "Deploy from a branch" را انتخاب کنید
5. از dropdown، شاخه "main" را انتخاب کنید
6. روی "Save" کلیک کنید
7. پس از چند دقیقه، سایت شما در آدرس زیر قابل دسترسی خواهد بود:
   https://username.github.io/repository-name

ساختار فایل CSV

فایل CSV باید دارای ساختار زیر باشد:

فرمت استاندارد

نوع,عنوان,مبلغ,شخص,تاریخ,دسته‌بندی

مقادیر مجاز برای ستون "نوع"

• income - برای درآمدها
• expense - برای هزینه‌ها

مثال از داده‌های واقعی

نوع,عنوان,مبلغ,شخص,تاریخ,دسته‌بندی
income,کمک مالی اولیای پایه اول,3500000,انجمن اولیا و مربیان,1402/07/05,کمک مالی
income,کمک خیرین مدرسه,12500000,بنیاد خیریه دانش,1402/07/10,کمک خیرین
expense,خرید کتاب‌های درسی پایه اول,1850000,مدیریت مدرسه,1402/07/15,کالای آموزشی
expense,تعمیر سیستم گرمایشی سالن,4200000,مدیریت مدرسه,1402/07/10,تعمیرات و نگهداری

تنظیمات گوگل شیت

نکات مهم در مدیریت گوگل شیت

1. سطح دسترسی: مطمئن شوید که شیت برای همه با لینک قابل مشاهده است
2. فرمت تاریخ: از فرمت 1402/07/05 استفاده کنید
3. فرمت اعداد: اعداد را بدون کاما و به صورت انگلیسی وارد کنید
4. هدر جدول: سطر اول باید دقیقاً مانند نمونه باشد

آموزش تصویری تنظیمات

استقرار روی GitHub Pages

مزایای استفاده از GitHub Pages

• 🆓 رایگان
• 🔒 امن
• ⚡ سریع
• 📈 مقیاس‌پذیر

آدرس نهایی سایت

پس از تنظیمات، سایت شما در آدرس زیر قابل دسترسی خواهد بود:

https://[username].github.io/[repository-name]

مثال:

https://fatemiyeh-school.github.io/school-finance

مدیریت و نگهداری

به‌روزرسانی منظم داده‌ها

1. ورود روزانه تراکنش‌ها: پس از هر تراکنش مالی، اطلاعات را در Google Sheets وارد کنید
2. بررسی ماهانه: در پایان هر ماه، خلاصه‌ای از عملکرد مالی را بررسی کنید
3. پشتیبان‌گیری: periodically از Google Sheets خود پشتیبان بگیرید

دسترسی‌ها و نقش‌ها

نقش	دسترسی	توضیحات
مدیر مالی	ویرایش Google Sheets	مسئول ورود تراکنش‌ها
مدیر مدرسه	مشاهده Google Sheets	نظارت بر عملکرد مالی
اولیاء	مشاهده سایت	پیگیری شفافیت مالی

عیب‌یابی مشکلات متداول

مشکل ۱: داده‌ها نمایش داده نمی‌شوند

• ✅ بررسی اتصال اینترنت
• ✅ بررسی صحت لینک CSV
• ✅ بررسی ساختار فایل CSV

مشکل ۲: تاریخ‌ها به درستی نمایش داده نمی‌شوند

• ✅ بررسی فرمت تاریخ (باید 1402/07/05 باشد)
• ✅ عدم استفاده از کاراکترهای خاص

مشکل ۳: سایت روی GitHub Pages کار نمی‌کند

• ✅ بررسی تنظیمات GitHub Pages
• ✅ بررسی نام فایل (حتماً باید index.html باشد)
• ✅ منتظر ماندن ۵-۱۰ دقیقه برای استقرار

نمونه‌های عملی

نمونه فایل CSV کامل

فایل school_finance.csv در این ریپازیتوری نمونه کاملی از ساختار مورد نیاز است.

نمونه سایت‌های راه‌اندازی شده

• مدرسه نمونه: مشاهده نمونه زنده

پشتیبانی

در صورت بروز هرگونه مشکل یا نیاز به راهنمایی بیشتر، می‌توانید از راه‌های زیر کمک بگیرید:

1. ایجاد Issue در ریپازیتوری GitHub
2. مراجعه به مستندات رسمی
3. ارتباط با توسعه‌دهنده

---

توسعه داده شده با ❤️ برای مدارس ایران