iscatel_student_list 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/diagrams/view.md ADDED
@@ -0,0 +1,123 @@
1
+ ```mermaid
2
+ classDiagram
3
+ direction LR
4
+
5
+ namespace View {
6
+
7
+ class StudentListView {
8
+ + HIGHLIGHT_EMPTY_COLUMNS : Integer[]$
9
+ + EMPTY_CELL_COLOR : FXColor$
10
+ - controller : StudentListInitialController
11
+ - app : FXApp
12
+ - table : FXTable
13
+ - anchor_row : Integer
14
+ - selected_rows : Integer[]
15
+ - cell_icons : Hash
16
+ - table_font : FXFont
17
+ - button_font : FXFont
18
+ - button_read : FXButton
19
+ - button_create : FXButton
20
+ - button_update : FXButton
21
+ - button_delete : FXButton
22
+ - button_previous_page : FXButton
23
+ - button_next_page : FXButton
24
+ - pages_label : FXLabel
25
+ + update_table(current_page : Integer, pages_count : Integer)
26
+ + set_table_params(column_names : String[], page_entities_count : Integer)
27
+ + set_table_data(data_table : DataTable)
28
+ - create()
29
+ - initialize_fonts(app : FXApp)
30
+ - initialize_window()
31
+ - initialize_table()
32
+ - initialize_buttons()
33
+ - fit_columns(padding : Integer)
34
+ - select_single_row(current_row : Integer)
35
+ - select_rows(current_row : Integer)
36
+ - update_buttons()
37
+ - create_cell_icon(width : Integer, height : Integer) FXIcon
38
+ - highlight_empty_cells(columns : Integer[])
39
+ - selected_rows=(rows : Integer[])
40
+ }
41
+
42
+ class FXMainWindow
43
+ class FXApp
44
+ class FXVerticalFrame
45
+ class FXHorizontalFrame
46
+ class FXTable
47
+ class FXButton
48
+ class FXLabel
49
+ class FXIcon
50
+ class FXMessageBox
51
+
52
+ class ModalWindow {
53
+ - controller : Object
54
+ - buttons_font : FXFont
55
+ - label_font : FXFont
56
+ - initialize_fonts(app : FXApp)
57
+ - initialize_window(_parent : StudentListView, _title_text : String, _width : Integer, _height : Integer)*
58
+ }
59
+
60
+ class ReadWindow {
61
+ - selected_number : Integer
62
+ - initialize_window(parent : StudentListView, title_text : String, width : Integer, height : Integer)
63
+ }
64
+
65
+ class DeleteWindow {
66
+ - initialize_window(parent : StudentListView, title_text : String, width : Integer, height : Integer)
67
+ }
68
+
69
+ class InsertUpdateWindow {
70
+ - inputs : Hash
71
+ - field_validation : Hash
72
+ - button_ok : FXButton
73
+ - button_cancel : FXButton
74
+ - initialize_window(parent : StudentListView, title_text : String, width : Integer, height : Integer)
75
+ - validate_text_field(field_name : Symbol, text_field : FXTextField)
76
+ - fill_text_fields(student : Hash)
77
+ - update_buttons()
78
+ }
79
+
80
+ }
81
+
82
+ namespace External_Controller {
83
+ class StudentListInitialController {
84
+ <<Controller>>
85
+ }
86
+ class ModalWindowController {
87
+ <<Controller>>
88
+ }
89
+ }
90
+
91
+ namespace External_Model {
92
+ class DataListStudentShort {
93
+ <<Model>>
94
+ }
95
+ class DataTable {
96
+ <<Model>>
97
+ }
98
+ }
99
+
100
+ StudentListView o-- StudentListInitialController : информирует
101
+ InsertUpdateWindow o-- ModalWindowController : информирует
102
+
103
+ StudentListView --|> FXMainWindow
104
+ StudentListView *-- FXApp
105
+ StudentListView *-- FXVerticalFrame
106
+ StudentListView *-- FXHorizontalFrame
107
+ StudentListView *-- FXTable
108
+ StudentListView *-- FXButton
109
+ StudentListView *-- FXLabel
110
+ StudentListView *-- FXIcon
111
+ StudentListView ..> FXMessageBox : использует
112
+ StudentListView *-- ModalWindow
113
+ ReadWindow --|> ModalWindow
114
+ DeleteWindow --|> ModalWindow
115
+ InsertUpdateWindow --|> ModalWindow
116
+ StudentListView *-- ReadWindow
117
+ StudentListView *-- DeleteWindow
118
+ StudentListView *-- InsertUpdateWindow
119
+ ModalWindow ..> FXMessageBox : использует
120
+
121
+ DataListStudentShort ..> StudentListView : уведомляет
122
+ StudentListView ..> DataTable : использует
123
+ ```
data/exe/student_list ADDED
@@ -0,0 +1,5 @@
1
+ #!/usr/bin/env ruby
2
+
3
+ require 'student_list'
4
+
5
+ StudentList.run
@@ -0,0 +1,326 @@
1
+ require 'logger'
2
+ require 'fileutils'
3
+ require_relative '../model/data_list_student_short.rb'
4
+ require_relative '../model/student_list.rb'
5
+ require_relative '../domain/student.rb'
6
+
7
+ # Модуль двухуровневого логирования для контроллеров приложения.
8
+ # Разделяет поток записей на лог ошибок/исключений и лог операций с БД.
9
+ module ControllerLogger
10
+ # Директория для хранения файлов журналов
11
+ LOG_DIR = '../logs'.freeze
12
+
13
+ # Путь к файлу журнала ошибок и исключений
14
+ ERROR_LOG_PATH = File.join(LOG_DIR, 'errors.log').freeze
15
+
16
+ # Путь к файлу журнала операций с базой данных (2 уровень)
17
+ DB_LOG_PATH = File.join(LOG_DIR, 'db_operations.log').freeze
18
+
19
+ # Возвращает или инициализирует логгер ошибок.
20
+ #
21
+ # @return [Logger] экземпляр логгера уровня +Logger::ERROR+
22
+ def self.error_logger
23
+ @error_logger ||= create_logger(ERROR_LOG_PATH, Logger::ERROR)
24
+ end
25
+
26
+ # Возвращает или инициализирует логгер операций с БД.
27
+ #
28
+ # @return [Logger] экземпляр логгера уровня +Logger::INFO+
29
+ def self.db_logger
30
+ @db_logger ||= create_logger(DB_LOG_PATH, Logger::INFO)
31
+ end
32
+
33
+ # Создаёт настроенный экземпляр +Logger+ с ежедневной ротацией файлов.
34
+ #
35
+ # @param path [String] путь к файлу журнала
36
+ # @param level [Integer] уровень важности сообщений (+Logger::INFO+, +Logger::ERROR+ и т.д.)
37
+ # @return [Logger] настроенный объект логгера
38
+ def self.create_logger(path, level)
39
+ FileUtils.mkdir_p(LOG_DIR)
40
+ logger = Logger.new(path, 'daily')
41
+ logger.level = level
42
+ logger.formatter = proc do |severity, datetime, _progname, msg|
43
+ "[#{datetime.strftime('%Y-%m-%d %H:%M:%S')}] [#{severity}] #{msg}\n"
44
+ end
45
+ logger
46
+ end
47
+
48
+ private
49
+
50
+ # Записывает сообщение об ошибке и трассировку стека исключения в журнал.
51
+ #
52
+ # @param message [String] описание контекста ошибки
53
+ # @param exception [Exception, nil] перехваченное исключение
54
+ # @return [Boolean] результат записи в лог
55
+ def log_error(message, exception = nil)
56
+ details = message.to_s
57
+ if exception
58
+ details += " | #{exception.class}: #{exception.message}"
59
+ details += "\n#{exception.backtrace.first(10).join("\n")}" if exception.backtrace
60
+ end
61
+ ControllerLogger.error_logger.error(details)
62
+ end
63
+
64
+ # Записывает информацию об операции с базой данных в журнал.
65
+ #
66
+ # @param operation [String] код или название операции (например, +'DB_INSERT'+)
67
+ # @param details [String, nil] дополнительные параметры операции
68
+ # @return [Boolean] результат записи в лог
69
+ def log_db(operation, details = nil)
70
+ text = details ? "#{operation} | #{details}" : operation.to_s
71
+ ControllerLogger.db_logger.info(text)
72
+ end
73
+ end
74
+
75
+ # Абстрактный базовый контроллер для модальных диалогов добавления и редактирования студента.
76
+ #
77
+ # @abstract Наследники должны реализовать методы {#get_window_data} и {#refresh_data}.
78
+ class ModalWindowController
79
+ include ControllerLogger
80
+
81
+ # Инициализирует контроллер модального окна.
82
+ #
83
+ # @param student_list [StudentList] объект доступа к базе данных
84
+ # @raise [NotImplementedError] при попытке инстанцировать базовый класс {ModalWindowController}
85
+ def initialize(student_list)
86
+ raise(NotImplementedError, "#{self.class} не может иметь экземпляров") if self.class == ModalWindowController
87
+ @student_list = student_list
88
+ end
89
+
90
+ # Выполняет валидацию значения конкретного поля формы с помощью правил модели {Student}.
91
+ #
92
+ # @param field_name [Symbol] имя поля (+:last_name+, +:first_name+, +:patronymic+, +:telegram+, +:email+, +:phone+, +:git+)
93
+ # @param field_data [String, nil] введённое значение поля
94
+ # @return [Boolean] +true+, если значение валидно
95
+ def validate_data(field_name, field_data)
96
+ case field_name
97
+ when :last_name then Student.valid_name?(field_data, false)
98
+ when :first_name then Student.valid_name?(field_data, false)
99
+ when :patronymic then Student.valid_name?(field_data, true)
100
+ when :telegram then Student.valid_telegram?(field_data)
101
+ when :email then Student.valid_email?(field_data)
102
+ when :phone then Student.valid_phone?(field_data)
103
+ when :git then Student.valid_git?(field_data)
104
+ end
105
+ end
106
+
107
+ # Возвращает начальные данные для заполнения полей модального окна.
108
+ #
109
+ # @abstract
110
+ # @return [Hash{Symbol => String, nil}] словарь значений полей
111
+ # @raise [NotImplementedError] если метод не реализован в наследнике
112
+ def get_window_data
113
+ raise(NotImplementedError, "#{self.class}#get_window_data не реализован")
114
+ end
115
+
116
+ # Сохраняет изменения, внесённые пользователем в модальном окне.
117
+ #
118
+ # @abstract
119
+ # @param _student_data [Hash{Symbol => String, nil}] данные полей формы
120
+ # @return [void]
121
+ # @raise [NotImplementedError] если метод не реализован в наследнике
122
+ def refresh_data(_student_data)
123
+ raise(NotImplementedError, "#{self.class}#refresh_data не реализован")
124
+ end
125
+ end
126
+
127
+ # Контроллер модального окна добавления нового студента.
128
+ class ModalInsertWindowController < ModalWindowController
129
+ # Возвращает пустой шаблон полей для формы добавления студента.
130
+ #
131
+ # @return [Hash{Symbol => nil}] хэш со значениями +nil+ для всех полей
132
+ def get_window_data
133
+ { last_name: nil, first_name: nil, patronymic: nil, telegram: nil, email: nil, phone: nil, git: nil }
134
+ end
135
+
136
+ # Создаёт объект {Student} из данных формы и сохраняет его в БД.
137
+ #
138
+ # @param student_data [Hash{Symbol => String, nil}] данные нового студента
139
+ # @return [Boolean] результат записи в лог успешной операции
140
+ # @raise [StandardError] при ошибке валидации или записи в БД
141
+ def refresh_data(student_data)
142
+ student_data[:id] = nil
143
+ student = Student.from_hash(student_data)
144
+ log_db('DB_INSERT', "Добавление студента: #{student}")
145
+ @student_list.create_student(student)
146
+ log_db('DB_INSERT_OK', "Студент успешно добавлен: #{student.last_name_initials}")
147
+ rescue StandardError => e
148
+ log_error("Ошибка при добавлении студента (#{student_data.inspect})", e)
149
+ raise
150
+ end
151
+ end
152
+
153
+ # Контроллер модального окна редактирования существующего студента.
154
+ class ModalUpdateWindowController < ModalWindowController
155
+ # Инициализирует контроллер редактирования для студента с заданным ID.
156
+ #
157
+ # @param student_list [StudentList] объект доступа к БД
158
+ # @param id [Integer] идентификатор редактируемого студента
159
+ def initialize(student_list, id)
160
+ super(student_list)
161
+ @student_id = id
162
+ end
163
+
164
+ # Загружает текущие данные редактируемого студента из БД для заполнения формы.
165
+ #
166
+ # @return [Hash{Symbol => String, nil}] словарь атрибутов студента
167
+ def get_window_data
168
+ student = @student_list.get_student_by_id(@student_id)
169
+ {
170
+ last_name: student.last_name,
171
+ first_name: student.first_name,
172
+ patronymic: student.patronymic,
173
+ telegram: student.telegram,
174
+ email: student.email,
175
+ phone: student.phone,
176
+ git: student.git
177
+ }
178
+ end
179
+
180
+ # Обновляет запись студента в БД на основе данных, изменённых в форме.
181
+ #
182
+ # @param student_data [Hash{Symbol => String, nil}] обновлённые данные полей
183
+ # @return [Boolean] результат записи в лог успешной операции
184
+ # @raise [StandardError] при ошибке валидации или обновления записи в БД
185
+ def refresh_data(student_data)
186
+ student_data[:id] = @student_id
187
+ student = Student.from_hash(student_data)
188
+ log_db('DB_UPDATE', "Обновление студента id=#{@student_id}: #{student}")
189
+ @student_list.update_student_by_id(student)
190
+ log_db('DB_UPDATE_OK', "Студент id=#{@student_id} успешно обновлён")
191
+ rescue StandardError => e
192
+ log_error("Ошибка при обновлении студента id=#{@student_id} (#{student_data.inspect})", e)
193
+ raise
194
+ end
195
+ end
196
+
197
+ # Главный контроллер окна списка студентов в архитектуре MVC.
198
+ # Координирует работу представления {StudentListView}, модели {DataListStudentShort} и хранилища {StudentList}.
199
+ class StudentListInitialController
200
+ include ControllerLogger
201
+
202
+ # @return [Integer] номер текущей страницы
203
+ attr_reader :current_page
204
+
205
+ # @return [Integer] количество записей, отображаемых на одной странице
206
+ attr_reader :rows_on_page_count
207
+
208
+ # Инициализирует главный контроллер, модель списка и подключение к БД.
209
+ #
210
+ # @param view [StudentListView] экземпляр главного окна представления
211
+ # @raise [StandardError] при сбое подключения к базе данных
212
+ def initialize(view)
213
+ @view = view
214
+ @current_page = 1
215
+ @rows_on_page_count = 10
216
+ @model = DataListStudentShort.new([])
217
+ @model.observe(view)
218
+
219
+ log_db('DB_CONNECT', 'Инициализация подключения к базе данных PostgreSQL')
220
+ @student_list = StudentList.new
221
+ log_db('DB_CONNECT_OK', 'Подключение к базе данных установлено')
222
+ rescue StandardError => e
223
+ log_error('Ошибка подключения к базе данных при запуске приложения', e)
224
+ raise
225
+ end
226
+
227
+ # Создаёт контроллер для модального окна добавления студента.
228
+ #
229
+ # @return [ModalInsertWindowController] контроллер добавления
230
+ def initialize_insert_controller
231
+ ModalInsertWindowController.new(@student_list)
232
+ end
233
+
234
+ # Создаёт контроллер для модального окна редактирования выделенного студента.
235
+ #
236
+ # @return [ModalUpdateWindowController] контроллер редактирования
237
+ def initialize_update_controller
238
+ selected_id = @model.get_selected.first
239
+
240
+ ModalUpdateWindowController.new(@student_list, selected_id)
241
+ end
242
+
243
+ # Возвращает текущее количество строк на странице.
244
+ #
245
+ # @return [Integer] число записей на страницу
246
+ def get_rows_on_page_count
247
+ @rows_on_page_count
248
+ end
249
+
250
+ # Устанавливает новое количество отображаемых строк на странице и корректирует номер страницы.
251
+ #
252
+ # @param rows_on_page_count [Integer] новое количество записей на страницу
253
+ # @return [Integer] актуальный номер текущей страницы
254
+ def set_rows_on_page_count(rows_on_page_count)
255
+ @rows_on_page_count = rows_on_page_count
256
+ valid_page
257
+ end
258
+
259
+ # Переключает пагинацию на следующую страницу.
260
+ #
261
+ # @return [Integer] актуальный номер текущей страницы
262
+ def next_page
263
+ @current_page += 1
264
+ valid_page
265
+ end
266
+
267
+ # Переключает пагинацию на предыдущую страницу.
268
+ #
269
+ # @return [Integer] актуальный номер текущей страницы
270
+ def previous_page
271
+ @current_page -= 1
272
+ valid_page
273
+ end
274
+
275
+ # Вычисляет общее количество страниц исходя из числа записей в БД.
276
+ #
277
+ # @return [Integer] количество страниц (минимум 1)
278
+ def get_pages_count
279
+ total = @student_list.get_size
280
+ [total.ceildiv(@rows_on_page_count), 1].max
281
+ end
282
+
283
+ # Синхронизирует выделенные в таблице строки с моделью {DataListStudentShort}.
284
+ #
285
+ # @param selected_rows [Array<Integer>] массив индексов выделенных строк
286
+ # @return [Array<Integer>] обработанный массив индексов
287
+ def refresh_selected_rows(selected_rows)
288
+ @model.clear_selected
289
+ selected_rows.each { |row| @model.select(row) }
290
+ end
291
+
292
+ # Загружает актуальную страницу данных из БД, уведомляет наблюдателей и обновляет таблицу в представлении.
293
+ #
294
+ # @return [void]
295
+ def refresh_data
296
+ valid_page
297
+ @model.list = @student_list.get_k_n_student_short_list(@current_page, @rows_on_page_count)
298
+ @model.notify
299
+ @view.update_table(@current_page, get_pages_count)
300
+ end
301
+
302
+ # Удаляет всех выделенных студентов из базы данных и сбрасывает пагинацию на первую страницу.
303
+ #
304
+ # @return [Integer] номер текущей страницы (+1+)
305
+ # @raise [StandardError] при ошибке удаления записей из БД
306
+ def delete_students
307
+ students_ids = @model.get_selected
308
+ log_db('DB_DELETE', "Удаление студентов с id=#{students_ids.inspect}")
309
+ students_ids.each { |id| @student_list.delete_student_by_id(id) }
310
+ log_db('DB_DELETE_OK', "Удалено записей: #{students_ids.size}")
311
+ @current_page = 1
312
+ rescue StandardError => e
313
+ log_error("Ошибка при удалении студентов id=#{students_ids.inspect}", e)
314
+ raise
315
+ end
316
+
317
+ private
318
+
319
+ # Ограничивает номер текущей страницы допустимым диапазоном +1..get_pages_count+.
320
+ #
321
+ # @return [Integer] скорректированный номер страницы
322
+ def valid_page
323
+ pages_count = get_pages_count
324
+ @current_page = [[@current_page, pages_count].min, 1].max
325
+ end
326
+ end
@@ -0,0 +1,21 @@
1
+ # Модуль для генерации сеттеров с автоматической валидацией присваиваемых значений.
2
+ #
3
+ # Для каждого поля +field+ ожидает наличие в классе метода валидации +valid_<field>?+.
4
+ module ValidAttrAccessor
5
+ # Создаёт геттеры и валидирующие сеттеры для перечисленных полей.
6
+ #
7
+ # @param fields [Array<Symbol>] список имён атрибутов
8
+ # @return [Array<Symbol>] переданный список полей
9
+ # @raise [NotImplementedError] если в классе не определён метод валидации +valid_<field>?+
10
+ # @raise [ArgumentError] если переданное в сеттер значение не прошло валидацию
11
+ def self.attr_accessor(*fields)
12
+ fields.each do |field|
13
+ attr_reader field
14
+ valid_method_name = "valid_#{field}?".to_sym
15
+ define_method("#{field}=") do |value|
16
+ raise(NotImplementedError, "#{self.class}##{valid_method_name} не реализован") unless self.class.respond_to?(valid_method_name, true)
17
+ self.class.send(valid_method_name, value) ? instance_variable_set("@#{field}", value) : raise(ArgumentError)
18
+ end
19
+ end
20
+ end
21
+ end
@@ -0,0 +1,69 @@
1
+ # Абстрактный базовый класс, определяющий общий интерфейс и базовые поля студента.
2
+ #
3
+ # @abstract Наследники должны реализовать методы {#contact}, {#last_name_initials} и {#to_s}.
4
+ class BasicStudent
5
+ # @return [Integer, nil] уникальный идентификатор студента
6
+ attr_reader :id
7
+
8
+ # @return [String, nil] ссылка на Git-профиль студента
9
+ attr_reader :git
10
+
11
+ # Возвращает контактную информацию студента.
12
+ #
13
+ # @abstract
14
+ # @return [String, nil] строка с контактом или +nil+
15
+ # @raise [NotImplementedError] если метод не переопределён в классе-наследнике
16
+ def contact()
17
+ raise(NotImplementedError, "#{self.class}#contact не реализован")
18
+ end
19
+
20
+ # Возвращает фамилию и инициалы студента.
21
+ #
22
+ # @abstract
23
+ # @return [String] фамилия и инициалы
24
+ # @raise [NotImplementedError] если метод не переопределён в классе-наследнике
25
+ def last_name_initials()
26
+ raise(NotImplementedError, "#{self.class}#last_name_initials не реализован")
27
+ end
28
+
29
+ # Запрещает прямое создание экземпляров абстрактного класса {BasicStudent}.
30
+ #
31
+ # @raise [NotImplementedError] при попытке инстанцировать {BasicStudent} напрямую
32
+ def initialize
33
+ raise(NotImplementedError, "#{self.class} не может иметь экземпляров") if self.class.is_a?(BasicStudent)
34
+ end
35
+
36
+ # Проверяет, указана ли у студента ссылка на Git.
37
+ #
38
+ # @return [Boolean] +true+, если ссылка на Git задана
39
+ def has_git?()
40
+ not git.nil?
41
+ end
42
+
43
+ # Проверяет, указан ли у студента хотя бы один способ связи.
44
+ #
45
+ # @return [Boolean] +true+, если контакт задан
46
+ def has_contact?
47
+ not contact.nil?
48
+ end
49
+
50
+ # Возвращает полное строковое представление объекта студента.
51
+ #
52
+ # @abstract
53
+ # @return [String] строковое представление студента
54
+ # @raise [NotImplementedError] если метод не переопределён в классе-наследнике
55
+ def to_s()
56
+ raise(NotImplementedError, "#{self.class}#to_s? не реализован")
57
+ end
58
+
59
+ # Формирует краткую сводку информации о студенте (ФИО, ID, Git и контакт).
60
+ #
61
+ # @return [String] краткая строка с доступными данными студента
62
+ def short_info
63
+ info = last_name_initials
64
+ info += " #{id}" unless id.nil?
65
+ info += " #{git}"
66
+ info += " #{contact}" unless contact.nil?
67
+ info
68
+ end
69
+ end