پی‌گیر (PayGir)

پی‌گیر یک نرم‌افزار دسکتاپ حسابداری شخصی است که برای مدیریت درآمدها، هزینه‌ها، بدهی‌ها و طلب‌ها، کارت‌های بانکی و اهداف مالی طراحی شده است. رابط کاربری کاملاً فارسی و راست‌چین است، از تاریخ شمسی پشتیبانی می‌کند و امکان تهیهٔ گزارش‌های قابل چاپ را فراهم می‌کند.

---

فهرست مطالب

• امکانات
• تکنولوژی‌های استفاده‌شده
• معماری پروژه
• ساختار پوشه‌ها
• پیش‌نیازها
• راه‌اندازی و نصب
• ساختار پایگاه داده
• مستندات و دیاگرام‌ها
• نکات مهم

---

امکانات

احراز هویت و مدیریت کاربر

• ثبت‌نام و ورود با رمز عبور هش‌شده (BCrypt)
• ویرایش اطلاعات کاربری و تصویر پروفایل
• امکان حذف حساب کاربری

مدیریت تراکنش‌ها

• ثبت تراکنش‌های دریافتی و پرداختی
• اتصال هر تراکنش به شخص، کارت بانکی و هدف مالی
• تعیین وضعیت بدهی/طلب برای هر تراکنش
• ویرایش و حذف تراکنش‌ها با به‌روزرسانی خودکار موجودی کارت‌ها (از طریق Trigger در سطح دیتابیس)

مدیریت اشخاص (طرف‌حساب‌ها)

• ثبت اطلاعات کامل اشخاص شامل نام، موبایل، ایمیل، آدرس، شمارهٔ کارت و نام بانک
• دسته‌بندی اشخاص
• مشاهدهٔ سابقهٔ تراکنش‌های هر شخص

مدیریت کارت‌های بانکی

• افزودن، ویرایش و حذف کارت‌های بانکی
• تشخیص خودکار نام بانک از روی شمارهٔ کارت
• نمایش و به‌روزرسانی خودکار موجودی هر کارت

اهداف مالی

• تعریف هدف مالی با مبلغ و سطح اولویت
• پیگیری میزان پیشرفت هر هدف

گزارش‌گیری

• گزارش دریافتی‌ها و پرداختی‌ها
• گزارش ماهانه
• گزارش وضعیت بدهی‌ها
• گزارش اهداف مالی
• خروجی قابل چاپ و PDF با Stimulsoft Reports

رابط کاربری

• طراحی کاملاً فارسی و راست‌چین (RTL)
• پشتیبانی از حالت روشن و تاریک (Light/Dark Mode)
• نمایش تاریخ شمسی
• کامپوننت‌های اعتبارسنجی سفارشی برای فرم‌ها

---

تکنولوژی‌های استفاده‌شده

تکنولوژی	نسخه	کاربرد
C# / .NET Framework	4.7.2	زبان و پلتفرم اصلی
Windows Forms	—	رابط کاربری دسکتاپ
Entity Framework	6.2.0 (Database First / EDMX)	لایهٔ دسترسی به داده
SQL Server	2022	پایگاه داده
BCrypt.Net-Next	4.0.3	هش کردن رمز عبور
Stimulsoft Reports	2023.1.1	تولید گزارش‌های چاپی
Newtonsoft.Json	13.0	پردازش JSON

---

معماری پروژه

پروژه بر اساس معماری لایه‌ای (N-Tier) پیاده‌سازی شده و از الگوهای Repository و Unit of Work استفاده می‌کند:

┌─────────────────────────────────────────┐
│   PayGir.App  (Windows Forms UI)        │
├─────────────────────────────────────────┤
│   PayGir.ViewModels                     │
├─────────────────────────────────────────┤
│   PayGir.Business                       │
├─────────────────────────────────────────┤
│   PayGir.DataLayer                      │
│   (EF6 EDMX + UnitOfWork + Repository)  │
├─────────────────────────────────────────┤
│   SQL Server — Accounting_DB            │
└─────────────────────────────────────────┘

           PayGir.Utility
   (ابزارهای مشترک بین همهٔ لایه‌ها)

پروژه‌های Solution

پروژه	نوع	توضیح
PayGir.App	WinExe	فرم‌ها و رابط کاربری
PayGir.DataLayer	Class Library	مدل EDMX، UnitOfWork، GenericRepository
PayGir.ViewModels	Class Library	مدل‌های نمایشی
PayGir.Business	Class Library	منطق تجاری
PayGir.Utility	Class Library	تبدیل تاریخ شمسی، حالت تاریک، RtlMessageBox

---

ساختار پوشه‌ها

PayGir/
├── Source/
│   ├── PayGir V0.0.1/              # پروژهٔ اصلی (UI)
│   │   ├── PayGir V0.0.1.sln       # فایل Solution
│   │   ├── Accounting/             # فرم‌های تراکنش و گزارش‌ها
│   │   ├── Cards/                  # فرم‌های مدیریت کارت بانکی
│   │   ├── Goal/                   # فرم‌های اهداف مالی
│   │   ├── Interacts/              # فرم‌های مدیریت اشخاص
│   │   ├── SignUp - Login/         # فرم‌های ورود و ثبت‌نام
│   │   ├── Validator/              # کامپوننت‌های اعتبارسنجی
│   │   ├── Reports/                # قالب‌های گزارش Stimulsoft (*.mrt)
│   │   └── Resources/              # آیکون‌ها و تصاویر
│   ├── Accounting.DataLayer/       # لایهٔ داده
│   │   ├── PayGirModel.edmx        # مدل Entity Framework
│   │   ├── Context/UnitOfWork.cs
│   │   ├── Repositories/
│   │   └── Services/
│   ├── PayGir.Business/
│   ├── PayGir.ViewModels/
│   └── PayGir.Utility/
│       └── Convertor/              # DateConvertor، LightOrDark، RtlMessageBox
├── BackUp/
│   └── schema.sql                  # ساخت کامل پایگاه داده (بدون داده)
├── PayGir_Documentation/           # مستندات پروژه
│   ├── Pictures/                   # تصاویر دیاگرام‌های UML
│   ├── UML_Diagrams/               # فایل‌های Visual Paradigm
│   └── Word + PDF/                 # مستند نهایی پروژه
├── UML/
└── icons/

---

پیش‌نیازها

• Visual Studio 2022 (نسخهٔ 17.11 یا بالاتر)
• .NET Framework 4.7.2 Developer Pack
• SQL Server 2022 (یا نسخهٔ سازگار) به‌همراه SQL Server Management Studio
• Stimulsoft Reports.NET 2023.1 — برای بخش گزارش‌گیری لازم است و باید روی سیستم نصب باشد

---

راه‌اندازی و نصب

۱. دریافت سورس

git clone https://github.com/<your-username>/PayGir.git

۲. ساخت پایگاه داده

ابتدا یک پایگاه دادهٔ خالی بسازید:

CREATE DATABASE [Accounting_DB];

سپس اسکریپت BackUp/schema.sql را روی همان پایگاه داده اجرا کنید. این اسکریپت تمام جدول‌ها، کلیدها، ویوها، پروسیجرهای ذخیره‌شده و تریگرها را می‌سازد و جدول‌های مرجع (بانک‌ها، نوع تراکنش و وضعیت بدهی) را نیز مقداردهی می‌کند.

توجه: به‌دلیل حفظ حریم خصوصی، فایل بکاپ پایگاه دادهٔ اصلی در این مخزن قرار ندارد؛ آن فایل حاوی نام، شمارهٔ تماس و سوابق مالی افراد واقعی بود. schema.sql تنها ساختار را می‌سازد و هیچ دادهٔ شخصی ندارد. پس از اجرای آن، از داخل خود برنامه ثبت‌نام کنید و اطلاعات خود را وارد نمایید.

تریگرهای مربوط به به‌روزرسانی خودکار موجودی کارت‌ها نیز داخل همین schema.sql گنجانده شده‌اند و نیازی به اجرای هیچ فایل جداگانه‌ای نیست.

۳. تنظیم Connection String

فایل Source/PayGir V0.0.1/App.config را باز کرده و مقدار data source را با نام SQL Server خود جایگزین کنید:

<connectionStrings>
  <add name="Accounting_DBEntities"
       connectionString="metadata=res://*/PayGirModel.csdl|res://*/PayGirModel.ssdl|res://*/PayGirModel.msl;
       provider=System.Data.SqlClient;
       provider connection string=&quot;data source=YOUR-SERVER\INSTANCE;
       initial catalog=Accounting_DB;integrated security=True;
       trustservercertificate=True;MultipleActiveResultSets=True;App=EntityFramework&quot;"
       providerName="System.Data.EntityClient" />
</connectionStrings>

همین تنظیم را در فایل Source/Accounting.DataLayer/App.Config نیز بررسی کنید.

۴. بیلد و اجرا

۱. فایل Source/PayGir V0.0.1/PayGir V0.0.1.sln را در Visual Studio باز کنید. ۲. دستور Restore NuGet Packages را اجرا کنید. ۳. پروژهٔ PayGir.App را به‌عنوان Startup Project تنظیم کنید. ۴. با کلید F5 پروژه را اجرا کنید.

---

ساختار پایگاه داده

جدول‌ها

جدول	توضیح
Users	اطلاعات کاربران و رمز عبور هش‌شده
Accounting	تراکنش‌های مالی (رکورد اصلی سیستم)
AccountingTypes	نوع تراکنش (دریافتی / پرداختی)
Interact	اشخاص و طرف‌حساب‌ها
UserCard	کارت‌های بانکی کاربر و موجودی آن‌ها
Goal	اهداف مالی به‌همراه مبلغ و اولویت
DebtStatus	وضعیت بدهی/طلب
Bank	فهرست بانک‌ها و الگوی شمارهٔ کارت

View ها

• DueTransactions — تراکنش‌های سررسیدشده
• UserInteractions — خلاصهٔ تعامل کاربر با هر شخص
• UserTransactionHistory — سابقهٔ تراکنش‌های کاربر

Stored Procedure ها

• GetAllTransactionsByPerson — تمام تراکنش‌های یک شخص
• GetTotalTransactionsByTypeAndDateRange — جمع تراکنش‌ها بر اساس نوع و بازهٔ زمانی
• GetTotalTransactionsByTypeForAllPersons — جمع تراکنش‌ها بر اساس نوع برای همهٔ اشخاص
• GetLoanStatus — وضعیت بدهی‌ها

---

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

مستندات کامل پروژه در پوشهٔ PayGir_Documentation قرار دارد:

مورد	مسیر
Use Case Diagram	Pictures/1. PayGir_UseCase_Diagram/
Sequence Diagram	Pictures/2. PayGir_Sequnce_Diagram/
Collaboration Diagram	Pictures/3. PayGir_Collabration_Diagram/
Class Diagram	Pictures/4. PayGir_Class_Diagram/
State Machine Diagram	Pictures/5. PayGir_State_Machine_Diagram/
Activity Diagram	Pictures/6. PayGir_Activity_Diagram/
مستند نهایی (Word / PDF)	Word + PDF/
فایل‌های Visual Paradigm	UML_Diagrams/

---

نکات مهم

• رمزهای عبور با الگوریتم BCrypt هش می‌شوند و هرگز به‌صورت متن ساده ذخیره نمی‌شوند.
• به‌روزرسانی موجودی کارت‌ها در سطح پایگاه داده و از طریق Trigger انجام می‌شود، نه در کد برنامه. این تریگرها هنگام اجرای BackUp/schema.sql ساخته می‌شوند.
• کتابخانهٔ Stimulsoft Reports.NET 2023.1 در مخزن قرار ندارد و باید جداگانه نصب شود؛ بدون آن بخش گزارش‌گیری بیلد نمی‌شود. پروژه هر پنج اسمبلی موردنیاز (Stimulsoft.Base، Stimulsoft.Data، Stimulsoft.Report، Stimulsoft.Report.Win، Stimulsoft.Controls) را پس از نصب به‌صورت خودکار پیدا می‌کند و نیازی به تنظیم دستی مسیر نیست.
• قالب‌های گزارش (*.mrt) در پوشهٔ Source/PayGir V0.0.1/Reports/ نگهداری می‌شوند و هنگام بیلد به‌صورت خودکار در کنار فایل اجرایی کپی می‌گردند. برای ویرایش ظاهر گزارش‌ها، فایل موردنظر را با Stimulsoft Designer باز کنید. اگر قالب جدیدی اضافه کردید، حتماً آن را با Copy to Output Directory = PreserveNewest به PayGir.App.csproj معرفی کنید، وگرنه هنگام اجرا پیدا نمی‌شود.
• تاریخ‌ها در پایگاه داده میلادی ذخیره می‌شوند و هنگام نمایش با کلاس DateConvertor به شمسی تبدیل می‌گردند.

---

توسعه‌دهنده

این پروژه به‌عنوان یک پروژهٔ دانشگاهی طراحی و پیاده‌سازی شده است.

---

مجوز

این پروژه تحت مجوز MIT منتشر شده است — جزئیات در فایل LICENSE.

توجه: این مجوز فقط شامل کدهای همین مخزن می‌شود. کتابخانهٔ Stimulsoft Reports یک محصول تجاری با مجوز جداگانه است و در این مخزن قرار ندارد؛ برای استفاده از آن باید مجوز خود را از سازندهٔ آن تهیه کنید.

---

English Summary

PayGir is a Persian (RTL) personal finance and accounting desktop application built with C# / .NET Framework 4.7.2 and Windows Forms.

It lets users track income and expenses, manage bank cards and their balances, keep records of people they transact with, set financial goals, and generate printable reports.

Stack: C# · WinForms · Entity Framework 6 (Database First / EDMX) · SQL Server 2022 · BCrypt.Net · Stimulsoft Reports

Architecture: N-Tier (UI → ViewModels → Business → DataLayer) with the Repository and Unit of Work patterns.

Key features: BCrypt-hashed authentication · income/expense transactions linked to people, cards and goals · automatic card-balance updates via SQL triggers · Jalali (Shamsi) date support · light/dark theme · four printable report types.

Setup: create an empty Accounting_DB database in SQL Server and run BackUp/schema.sql against it, update the connection string in Source/PayGir V0.0.1/App.config, then open Source/PayGir V0.0.1/PayGir V0.0.1.sln in Visual Studio 2022 and run.

The original database backup is deliberately not included — it contained real people's names, phone numbers and financial records. schema.sql creates the full structure (tables, keys, views, stored procedures, triggers and lookup data) with no personal data.