Add LICENSE and README files with project details and MIT License

2025-08-13 11:23:27 +03:00
parent 8f4c0688f7
commit 948ffc0cbb
3 changed files with 324 additions and 0 deletions
--- a/7
+++ b/7
@@ -0,0 +1,7 @@
+Copyright © 2025 Karolis K.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
--- a/README.md
+++ b/README.md
@@ -0,0 +1,167 @@
+# KTUSA Problemų Sistema (KTUSA-PS)
+
+Status: Archived (development discontinued mid–2022)
+
+## 1. Historical Note
+Development began around 2020 as an initiative of the InfoSA academic committee. Due to a lack of continued institutional interest in deploying the platform, active work ceased around mid‑2022.
+
+The creator (Karolis K.) previously collaborated with other InfoSA members on an earlier iteration of the system implemented with the Symfony PHP framework. This second iteration (the one in this repository) was a full rewrite using ASP.NET Core + Vue 3 and was developed solely by Karolis.
+
+The information system (IS) was submitted in January 2022 as coursework for the university module:
+T120B165 "Saityno taikomųjų programų projektavimas"  
+(https://uais.cr.ktu.lt/ktuis/stp_report_ects.mdl_ml?p_kodas=T120B165&p_year=2021&p_lang=LT&p_stp_id=8058)
+
+No further functional evolution, security hardening, or production deployment steps were performed after the academic submission phase.
+
+## 2. Overview
+KTUSA-PS (KTU Student Association Problem System) is a web platform for registering, classifying, moderating, and publishing student issues and feedback. It was designed as a Single Page Application (SPA) with a REST API backend, emphasizing transparency in problem resolution workflows within the student community.
+
+The original detailed Lithuanian system description remains in `SISTEMA.md`.
+
+## 3. Technology Stack
+### Backend (.NET)
+- Framework: ASP.NET Core (C#)
+- Data Access: Entity Framework Core (Code First)
+- Database: MySQL
+- Authentication & Authorization: Azure Active Directory (MSAL) + JWT Bearer
+- API Documentation: Swagger / OpenAPI
+- Pattern: MVC + separated data layer project (`KTUSAPS.Data`)
+
+### Frontend (Vue.js)
+- Framework: Vue.js 3 (Composition API)
+- Router: Vue Router 4
+- State Management: Vuex 4
+- UI: Bootstrap 5 + Bootstrap Icons
+- Build Tool: Vite
+- HTTP Client: Axios
+- Authentication: MSAL Browser library (Azure AD integration)
+
+## 4. Core Functional Domains
+### For Students
+1. Submit issues / problems
+2. Choose issue types (categorization)
+3. Provide feedback / comments and votes
+
+### For Administrators
+1. Manage issues (review, update status, resolve)
+2. Maintain issue types (create / edit bilingual categories)
+3. Control publication of problems & solutions
+4. Moderate published feedback
+
+## 5. Data Model (Key Entities)
+- Issue – core submitted problem (type, description, resolution state)
+- IssueType – bilingual (LT/EN) classification metadata
+- PublishedProblem – publicly visible version of an issue
+- PublishedFeedback – publicly visible feedback / commentary
+- Admin – administrator role assignments
+- Vote – rating / voting entity for feedback or solutions
+
+## 6. Security Features (As Implemented)
+1. Azure AD authentication (institutional accounts)
+2. Role / claim-based authorization for admin-only areas
+3. JWT validation for API access control
+4. HTTPS-first assumptions (no explicit production reverse-proxy hardening done)
+5. Localized security warnings (e.g., unsafe context notices)
+
+Note: Since the system was never hardened for production, additional measures (rate limiting, auditing, CSP, advanced logging, backup strategy) were not finalized.
+
+## 7. Architecture Highlights
+- SPA frontend served alongside ASP.NET Core backend
+- RESTful API boundaries; clear separation of concerns
+- Separate data project (`KTUSAPS.Data`) to isolate Entity Framework models & migrations
+- Bilingual support (Lithuanian / English) for selected entities
+- Responsive UI leveraging Bootstrap 5
+
+## 8. Project Structure (Simplified)
+```
+KTUSA PS.sln
+├── KTUSAPS/                 # Web application (API + SPA host)
+│   ├── Controllers/         # API endpoints
+│   ├── Auth/                # Authorization handlers & policies
+│   ├── Services/            # (Planned/initial) business services
+│   ├── ClientApp/           # Vue 3 application (Vite)
+│   │   ├── src/
+│   │   │   ├── components/
+│   │   │   ├── pages/
+│   │   │   ├── router/
+│   │   │   └── store/
+│   │   ├── package.json
+│   │   └── vite.config.js
+│   ├── Startup.cs / Program.cs
+│   └── appsettings*.json
+└── KTUSAPS.Data/            # Data layer (DbContext + EF models + migrations)
+    ├── Model/
+    ├── Migrations/
+    └── SAPSDataContext.cs
+```
+
+## 9. Getting Started (Historical Dev Setup)
+Prerequisites:
+- .NET 6 SDK
+- Node.js 16+ (with npm)
+- MySQL Server (local or remote)
+
+### Backend
+```bash
+cd KTUSAPS
+dotnet restore
+dotnet run
+```
+The API will start on the configured Kestrel port (see `launchSettings.json`).
+
+### Frontend
+```bash
+cd KTUSAPS/ClientApp
+npm install
+npm run dev
+```
+Vite dev server will proxy or call the API directly (adjust base URLs in Axios / config if needed).
+
+### Database
+1. Create a MySQL database (e.g., `ktusaps_db`).
+2. Update the connection string in `KTUSAPS/appsettings.Development.json` (or `appsettings.json`).
+3. Apply migrations:
+```bash
+cd KTUSAPS
+dotnet ef database update
+```
+
+If `dotnet ef` is not available, install tools: `dotnet tool install --global dotnet-ef`.
+
+## 10. Authentication Configuration (Azure AD)
+The project expects Azure AD application credentials (Tenant ID, Client ID, etc.) in configuration. Since the environment is no longer active, placeholders may exist. For reenabling:
+- Register an app in Azure AD
+- Configure redirect URIs for SPA & API
+- Populate settings (e.g., `AzureAd` section) in `appsettings.Development.json`
+
+## 11. Usage Flow (Conceptual)
+1. User authenticates via Azure AD popup (MSAL in browser).
+2. Access token is obtained and attached to API calls (Bearer token).
+3. Student submits an issue (Issue stored; optionally flagged for publication later).
+4. Admin reviews issues, assigns type, updates status.
+5. Issue may be published (becomes `PublishedProblem`).
+6. Feedback & votes are optionally published (`PublishedFeedback`).
+
+## 12. Limitations / Incomplete Areas
+- No production-grade logging & monitoring strategy
+- Limited error handling / validation messages
+- No automated CI/CD pipeline included
+- Security hardening (headers, rate limiting, input sanitation depth) incomplete
+- i18n only partial beyond data fields (UI translations not fully finalized)
+- Testing (unit/integration) minimal to none in repository
+
+## 13. Academic Context
+This codebase primarily served as an academic / portfolio artifact rather than a deployed organizational system. It demonstrates full-stack integration (Azure AD auth, EF Core, SPA frontend) rather than polished end-user production readiness.
+
+## 14. Contribution & Maintenance
+This repository is unmaintained. Pull requests are unlikely to be reviewed. Fork if you wish to build upon it. Consider upgrading dependencies (ASP.NET Core version, Vue tooling, MSAL libraries) before any reuse.
+
+## 15. License
+Released under the MIT License. See the `LICENSE` file for the complete text and copyright notice.
+
+## 16. Credits
+Author: Karolis K.  
+Initial concept support: InfoSA academic committee (earlier iteration collaboration).
+
+---
+For the original Lithuanian descriptive document, see `SISTEMA.md`.
--- a/SISTEMA.md
+++ b/SISTEMA.md
@@ -0,0 +1,150 @@
+# KTUSA Problemų Sistema (KTUSA-PS)
+
+## Apžvalga
+
+**KTUSA-PS** yra **KTU SA (Kauno technologijos universiteto Studentų atstovybės) problemų sprendimo sistema** – internetinė platforma, skirta studentų problemų registravimui, tvarkymui ir sprendimui.
+
+## Technologijų rinkinys
+
+### Backend (.NET)
+- **Framework**: ASP.NET Core (C#)
+- **Duomenų bazė**: MySQL su Entity Framework Core
+- **Autentifikacija**: Microsoft Azure Active Directory (MSAL) su JWT Bearer autentifikacija
+- **API**: RESTful API su Swagger dokumentacija
+- **Architektūra**: MVC pattern su atskirtu duomenų sluoksniu
+
+### Frontend (Vue.js)
+- **Framework**: Vue.js 3 su Composition API
+- **Maršrutizacija**: Vue Router 4
+- **Būsenos valdymas**: Vuex 4
+- **UI Framework**: Bootstrap 5 su Bootstrap Icons
+- **Build Tool**: Vite
+- **HTTP klientas**: Axios
+- **Autentifikacija**: Azure MSAL Browser
+
+## Pagrindinės funkcijos
+
+### Studentams
+1. **Problemų registravimas** – studentai gali pateikti problemas sistemoje
+2. **Problemų tipų pasirinkimas** – galimybė klasifikuoti problemas pagal tipus
+3. **Atsiliepimų teikimas** – galimybė komentuoti ir vertinti sprendimus
+
+### Administratoriams
+1. **Problemų valdymas** – peržiūrėti, redaguoti ir spręsti pateiktas problemas
+2. **Problemų tipų administravimas** – kurti ir tvarkyti problemų kategorijas
+3. **Publikavimo kontrolė** – spręsti, kurios problemos ir sprendimai bus viešai matomi
+4. **Atsiliepimų moderavimas** – tvarkyti naudotojų atsiliepimus
+
+## Duomenų modelis
+
+### Pagrindinės esybės
+- **Issue** – problemų registravimas su aprašymu, tipu ir sprendimo būsena
+- **IssueType** – problemų kategorijos (dvikalbės: LT/EN)
+- **PublishedProblem** – viešai publikuojamos problemos
+- **PublishedFeedback** – viešai publikuojami atsiliepimai
+- **Admin** – administratorių vaidmenys
+- **Vote** – balsavimo / vertinimo sistema
+
+## Saugumo funkcijos
+
+1. **Azure AD integracija** – autentifikacija per Microsoft Active Directory
+2. **Vaidmenų sistema** – atskirtos administratorių ir paprastų naudotojų teisės
+3. **JWT tokenų validacija** – saugus API prieigos kontrolės mechanizmas
+4. **HTTPS privalomumas** – saugus duomenų perdavimas
+5. **Lokalizuoti saugumo perspėjimai** – naudotojų informavimas apie nesaugius ryšius
+
+## Architektūros ypatybės
+
+- **SPA (Single Page Application)** – Vue.js kliento dalis su ASP.NET Core serverio dalimi
+- **RESTful API** – aiškiai struktūrizuotas API dizainas
+- **Mikroservisų elementai** – atskirtas duomenų sluoksnis (`KTUSAPS.Data`)
+- **Lokalizacija** – dvi kalbos (lietuvių ir anglų)
+- **Prisitaikantis dizainas** – sukurtas su Bootstrap, pritaikytas mobiliesiems įrenginiams
+
+## Projekto struktūra
+
+```
+KTUSA PS.sln                          # Visual Studio solution failas
+├── KTUSAPS/                          # Pagrindinis web aplikacijos projektas
+│   ├── Controllers/                  # API kontroleriai
+│   │   ├── IssuesController.cs       # Problemų valdymo API
+│   │   ├── IssueTypesController.cs   # Problemų tipų API
+│   │   └── ...
+│   ├── ClientApp/                    # Vue.js frontend aplikacija
+│   │   ├── src/
+│   │   │   ├── components/           # Vue komponentai
+│   │   │   ├── pages/                # Puslapių komponentai
+│   │   │   ├── router/               # Maršrutizacijos konfigūracija
+│   │   │   └── store/                # Vuex būsenos valdymas
+│   │   ├── package.json
+│   │   └── vite.config.js
+│   ├── Auth/                         # Autentifikacijos logika
+│   ├── Services/                     # Verslo logikos servisai
+│   └── Program.cs                    # Aplikacijos entry point
+└── KTUSAPS.Data/                     # Duomenų sluoksnis
+    ├── Model/                        # Entity Framework modeliai
+    ├── Migrations/                   # Duomenų bazės migracijos
+    └── SAPSDataContext.cs            # DbContext
+```
+
+## Diegimas ir konfigūracija
+
+- **Konfigūracijos failai** – `appsettings.json` (taip pat `appsettings.Development.json` vystymui)
+- **Parengta naudoti su Docker** – tiek Vite, tiek .NET Core dalims
+- **Duomenų bazės migracijos** – valdomos per Entity Framework Core migracijas
+- **Swagger dokumentacija** – automatiškai generuojama API dokumentacija
+
+## Paleidimo instrukcijos
+
+### Reikalavimai
+- .NET 6.0 arba naujesnis
+- Node.js 16+ ir npm
+- MySQL serveris
+
+### Serverio dalies paleidimas
+```bash
+cd KTUSAPS
+dotnet restore
+dotnet run
+```
+
+### Kliento dalies paleidimas
+```bash
+cd KTUSAPS/ClientApp
+npm install
+npm run dev
+```
+
+### Duomenų bazės konfigūracija
+1. Sukurkite MySQL duomenų bazę
+2. Atnaujinkite prisijungimo eilutę (connection string) faile `appsettings.json`
+3. Paleiskite migracijas:
+```bash
+dotnet ef database update
+```
+
+## Pagrindinės sistemos dalys
+
+### Autentifikacija
+Sistema naudoja Microsoft Azure Active Directory autentifikaciją. Vartotojai prisijungia per savo institucijos paskyrą, o sistema automatiškai nustato jų teises.
+
+### Problemų valdymas
+- Studentai gali registruoti problemas per intuityvią formą
+- Administratoriai gali peržiūrėti visas problemas ir jas administruoti
+- Problemos gali būti skirstomos į tipus ir kategorijas
+
+### Publikavimo sistema
+- Administratoriai sprendžia, kurios problemos ir sprendimai bus viešai matomi
+- Publikuotos problemos tampa matomos visiems sistemos naudotojams
+- Atsiliepimų sistema leidžia vertinti sprendimų kokybę
+
+## Saugumas ir privatumas
+
+- Visi duomenys perduodami per HTTPS
+- Vartotojų duomenys saugomi pagal GDPR reikalavimus
+- Prieiga prie administratoriaus funkcijų griežtai kontroliuojama
+- Sistema perspėja apie nesaugius ryšius ar lokalų paleidimą
+
+---
+
+Sistema sukurta siekiant pagerinti KTU studentų problemų sprendimo procesus, užtikrinant skaidrumą, efektyvumą ir saugumą visame problemų valdymo cikle.