From 02991408312de0c87cf3e1fd0646fa71f8448d6f Mon Sep 17 00:00:00 2001
From: Dvurechensky <46356631+Dvurechensky@users.noreply.github.com>
Date: Sun, 2 Mar 2025 22:32:32 +0300
Subject: [PATCH] 1.0.3

README
---
 README.md | 463 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 463 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b119158
--- /dev/null
+++ b/README.md
@@ -0,0 +1,463 @@
+# 🌁 Шаблон проекта ASP NET CORE MVC, Frontend - на TypeScript
+
+## 🎇 Этапы наполнения конфигурациями 🎇
+
+---
+1. ⛅ Импорт `tsconfig.json` ⛅
+---
+
+<details>
+<summary>Раскрыть код tsconfig.json</summary>
+
+```json
+{
+    "compilerOptions": {
+        "target": "es2016", // Устанавливает уровень JavaScript, в который компилируется TypeScript (в данном случае ES2016).
+        "module": "es6", // Определяет, какой модульный формат используется в процессе компиляции (ES6 модули).
+        "moduleResolution": "node", // Способ разрешения модулей. В данном случае используется разрешение как в Node.js.
+        "jsx": "preserve", // Как компилировать JSX. В данном случае оставляем JSX без изменений.
+        "declaration": false, // Указывает, генерировать ли файлы типов (.d.ts). Здесь это отключено.
+        "removeComments": true, // Указывает, что комментарии должны быть удалены из скомпилированного кода.
+        "noImplicitAny": false, // Отключает предупреждения о неявных типах `any` в коде.
+        "noEmitOnError": true, // Указывает, что компиляция должна быть остановлена, если есть ошибки.
+        "sourceMap": true, // Генерирует карты исходных кодов для упрощения отладки.
+        "esModuleInterop": true, // Включает совместимость с модулями ES при импорте CommonJS модулей.
+        "experimentalDecorators": true, // Включает поддержку экспериментальных декораторов в TypeScript.
+        "emitDecoratorMetadata": true, // Включает генерацию метаданных для декораторов, которые могут использоваться в таких библиотеках как TypeORM или Angular.
+        "outDir": "ScriptsAndCss/JsScripts", // Указывает директорию для сохранения скомпилированных файлов.
+        "lib": [ "es2016", "dom" ] // Указывает библиотеки, которые будут включены при компиляции (ES2016 и DOM).
+    },
+    "exclude": [
+        "node_modules" // Исключает папку node_modules из процесса компиляции.
+    ]
+}
+```
+
+</details>
+
+---
+2. ⛅ Импорт `webpack.config.js` ⛅
+---
+
+<details>
+<summary>Раскрыть код webpack.config.js</summary>
+
+```js
+const path = require('path');
+const MiniCssExtractPlugin = require('mini-css-extract-plugin');
+const CssMinimizerPlugin = require('css-minimizer-webpack-plugin'); 
+const TerserPlugin = require('terser-webpack-plugin');  // Импортируем TerserPlugin
+
+module.exports = {
+    entry: {
+        app: './ScriptsAndCss/TypeScripts/main_api.ts', // Точка входа для JavaScript
+        styles: './ScriptsAndCss/CssFiles/styles.css'   // Точка входа для CSS (может быть любой CSS-файл)
+    },
+    output: {
+        path: path.resolve(__dirname, 'wwwroot/js'),
+        filename: '[name].min.js' // Используем [name] для динамического имени файла
+    },
+    resolve: {
+        extensions: ['.ts', '.js', '.css'] // Добавили .css
+    },
+    module: {
+        rules: [
+            {
+                test: /\.ts$/,
+                use: 'ts-loader',
+                exclude: /node_modules/
+            },
+            {
+                test: /\.css$/,
+                use: [
+                    MiniCssExtractPlugin.loader, // Извлекает CSS в отдельные файлы
+                    'css-loader'               // Обрабатывает @import и url()
+                ]
+            }
+        ]
+    },
+    plugins: [
+        new MiniCssExtractPlugin({
+            filename: '../css/app.min.css' // Куда Webpack должен поместить CSS-файл
+        })
+    ],
+    mode: 'development',
+    watch: true,
+};
+```
+
+</details>
+<br>
+
+> В случае публикации в Production релиза нужно сменить режим `mode: 'development'` на `mode: 'production'` в файле конфигурации
+
+<details>
+<summary>Раскрыть код изменений webpack.config.js</summary>
+
+```js
+mode: 'production',  // Изменен режим на production для минимизации
+optimization: {
+    minimize: true,  // Включаем минимизацию
+    minimizer: [
+        new TerserPlugin(),  // Плагин для минимизации JS
+        new CssMinimizerPlugin()  // Плагин для минимизации CSS
+    ]
+},
+```
+
+</details>
+
+---
+3. ⛅ Импорт `package.json` - ряд плагинов опционален под ваш проект ⛅
+---
+
+<details>
+<summary>Раскрыть код package.json</summary>
+
+```json
+{
+  "version": "1.0.0",
+  "name": "asp.net",
+  "private": true,
+  "devDependencies": {
+    "css-minimizer-webpack-plugin": "7.0.0",
+    "terser-webpack-plugin": "5.3.12",
+    "cytoscape": "^3.31.0",
+    "cytoscape-cose-bilkent": "4.1.0",
+    "grunt": "1.4.1",
+    "style-loader": "^4.0.0",
+    "css-loader": "^7.1.2",
+    "mini-css-extract-plugin": "^2.9.2",
+    "grunt-webpack": "^7.0.0",
+    "webpack-cli": "^6.0.1",
+    "ts-loader": "^9.5.2",
+    "browser-sync": "^3.0.3",
+    "grunt-browser-sync": "^2.2.0",
+    "grunt-contrib-clean": "2.0.0",
+    "grunt-contrib-concat": "2.0.0",
+    "grunt-contrib-cssmin": "5.0.0",
+    "grunt-contrib-uglify": "5.0.1",
+    "grunt-contrib-watch": "1.1.0",
+    "grunt-ts": "6.0.0-beta.22"
+  },
+  "dependencies": {
+    "cytoscape": "^3.31.0"
+  },
+  "comments": {
+    "version": "Указывает текущую версию вашего проекта.",
+    "name": "Имя вашего проекта.",
+    "private": "Указывает, что проект является приватным и не должен быть опубликован в npm.",
+    "devDependencies": {
+      "css-minimizer-webpack-plugin": "Плагин для минимизации CSS файлов в процессе сборки Webpack.",
+      "terser-webpack-plugin": "Плагин для минимизации JavaScript с использованием Terser.",
+      "cytoscape": "Библиотека для работы с графами и сетями.",
+      "cytoscape-cose-bilkent": "Плагин для Cytoscape, который добавляет алгоритм планирования расположения узлов.",
+      "grunt": "Система автоматизации задач для Node.js, например, для сборки, минификации и тестирования.",
+      "style-loader": "Лоадер для инжекции CSS в DOM через теги `<style>` в процессе сборки.",
+      "css-loader": "Лоадер для обработки CSS файлов и поддержки импорта других CSS или стилей.",
+      "mini-css-extract-plugin": "Плагин для извлечения CSS в отдельные файлы, что улучшает производительность.",
+      "grunt-webpack": "Плагин для интеграции Webpack с системой Grunt.",
+      "webpack-cli": "CLI для работы с Webpack, позволяет запускать сборку через командную строку.",
+      "ts-loader": "Лоадер для загрузки TypeScript файлов в Webpack.",
+      "browser-sync": "Инструмент для синхронизации браузеров и автоперезагрузки в процессе разработки.",
+      "grunt-browser-sync": "Плагин для интеграции BrowserSync с Grunt.",
+      "grunt-contrib-clean": "Плагин для удаления файлов или папок перед выполнением задач.",
+      "grunt-contrib-concat": "Плагин для конкатенации (объединения) файлов в один.",
+      "grunt-contrib-cssmin": "Плагин для сжатия CSS файлов.",
+      "grunt-contrib-uglify": "Плагин для сжатия JavaScript файлов (использует UglifyJS).",
+      "grunt-contrib-watch": "Плагин для отслеживания изменений файлов и автоматического выполнения задач.",
+      "grunt-ts": "Плагин для компиляции TypeScript файлов в Grunt."
+    }
+  }
+}
+```
+
+</details>
+
+---
+4. ⛅ Импорт `Gruntfile.js` ⛅
+---
+
+<details>
+<summary>Раскрыть код Gruntfile.js</summary>
+
+```js
+const webpackConfig = require('./webpack.config.js');
+
+module.exports = function (grunt) {
+    grunt.initConfig({
+        webpack: {
+            options: webpackConfig,
+            build: {
+            }
+        },
+        browserSync: {
+            dev: {
+                bsFiles: {
+                    src: [
+                        'wwwroot/css/*.css',
+                        'wwwroot/js/app.min.js', // Webpack создает app.min.js
+                        'Views/**/*.cshtml'
+                    ]
+                },
+                options: {
+                    watchTask: true,
+                    proxy: "localhost:5000" // Замените на свой локальный адрес
+                }
+            }
+        },
+        watch: {
+            ts: {
+                files: ['ScriptsAndCss/TypeScripts/**/*.ts'],
+                tasks: ['webpack:build'], // Webpack компилирует и собирает
+                options: {
+                    spawn: false,
+                },
+            },
+            bsReload: {
+                files: ['wwwroot/css/*.css', 'wwwroot/js/app.min.js', 'Views/**/*.cshtml'],
+                options: {
+                    reload: true
+                }
+            }
+        },
+        clean: ["wwwroot/css/*", "wwwroot/js/*", "ScriptsAndCss/Combined/*"],
+        cssmin: { //сжатие CSS
+            css: {
+                src: ["ScriptsAndCss/CssFiles/*"], //какой файл сжимать
+                dest: "wwwroot/css/app.min.css" //сжатый выходной файл
+            }
+        },
+    });
+
+    grunt.loadNpmTasks('grunt-webpack');
+    grunt.loadNpmTasks('grunt-browser-sync');
+    grunt.loadNpmTasks('grunt-contrib-watch');
+    grunt.loadNpmTasks('grunt-contrib-clean');
+    grunt.loadNpmTasks('grunt-contrib-cssmin');
+
+    grunt.registerTask("build", ["clean", "webpack:build", "cssmin"]);
+    grunt.registerTask("default", ["build", "browserSync:dev", "watch"]);
+};
+```
+
+</details>
+
+---
+4. ⛅ Импорт `app_configuration.json` ⛅
+---
+
+<details>
+<summary>Раскрыть код app_configuration.json</summary>
+
+```json
+{
+  "appSettings": {
+    "appHost": "localhost:8833"
+  }
+}
+```
+
+</details>
+
+---
+
+## 🎇 Этапы сборочного процесса 🎇 
+
+---
+- 🌋 Восстановить NPM пакеты
+---
+- 🌋 Настроить директории для генерации Frontend
+    - в корне проекта где мы будем его внедрять создаём такуб структуру папок
+        - 📁ScriptsAndCss      
+            - 📁〰️📁CssFiles     
+            - 📁〰️📁JsScripts    
+            - 📁〰️📁TypeScripts 
+---
+- 🌋 Установить Nuget пакеты
+    - **`TypeScript.MSBuild`**
+    - **`AspNetCore.Mvc.Razor.RuntimeCompilation`**
+    - **`Swashbuckle.AspNetCore.Swagger`**
+    - **`Swashbuckle.AspNetCore.SwaggerGen`**
+    - **`Swashbuckle.AspNetCore.SwaggerUI`**
+---
+- 🌋 В файле `Views/Shared/_Layout.cshtml` изменить адреса до `css` и `js` файлов так как теперь они называются **`app.min.css`** и **`app.min.js`**
+---
+- 🌋 Добавить простейшую точку входа `[js]` приложения в папку 📁ScriptsAndCss〰️>📁TypeScripts  - **`main_api.ts`** 
+
+<details>
+<summary>Раскрыть код main_api.ts</summary>
+
+```ts
+(() => {
+    //по загрузке окна
+    window.addEventListener("load", async () => {
+        //получаем текущий URL
+        const currentUrl = new URL(document.location.href);
+
+        //получаем путь из URL
+        const pathname = currentUrl.pathname.toLowerCase();
+
+        //разбиваем пути URL на части
+        const partsPath = pathname.split("/");
+
+        //смотрим путь
+        switch (partsPath[1]) {
+            case "": //страница авторизации
+            {
+
+            }
+            break;
+            default:
+                break;
+        }
+    }
+})();
+```
+
+</details>
+<br>
+
+---
+- 🌋 Добавить простейшую точку входа `[css]` приложения в папку 📁ScriptsAndCss〰️>📁CssFiles  - **`style.css`** 
+
+
+<details>
+<summary>Раскрыть код style.css</summary>
+
+```ts
+// ваши стили - скопируйте из wwwroot то что там было
+```
+
+</details>
+<br>
+
+---
+- 🌋 Добавить примерно такое содержимое в **`Program.cs`**
+> Поясняю - в данном примере вырезано внесение `CSRF` токена в логику работы сервера а также `Middleware` отвечающий за обработку служб защиты от подделки запросов. Тут мы вносим лишь Swagger для генерации документации по API и конфигурационный файл декларирующий **`host`** и **`port`** вашего сервера принудительно.
+
+<details>
+<summary>Раскрыть код Program.cs</summary>
+
+```cs
+using System.Reflection;
+using System.Text.Json;
+
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.OpenApi.Models;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Configuration.SetBasePath(Directory.GetCurrentDirectory())
+    .AddJsonFile($"{LoggingExtensions.AppDir}/app_configuration.json");
+
+builder.WebHost.UseUrls($"https://{builder.Configuration["appSettings:appHost"]}");
+
+builder.Services.AddControllersWithViews();
+
+#region В этом регионе объявляем сервисы 
+
+// Например
+// builder.Services.AddSingleton<ICashService, CashService>();
+
+#endregion
+
+builder.Services.Configure<JsonOptions>(options =>
+{
+    options.JsonSerializerOptions.WriteIndented = true; //для красивого форматирования
+    options.JsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
+});
+
+builder.Services.AddSwaggerGen(options =>
+{
+    options.SwaggerDoc("v1", new OpenApiInfo
+    {
+        Title = "App API",
+        Version = "1.0.0",
+        Description = "Информация об API",
+        Contact = new OpenApiContact
+        {
+            Name = "Dvurechensky"
+        }
+    });
+    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
+    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
+    options.IncludeXmlComments(xmlPath);
+});
+
+var app = builder.Build();
+
+if (!app.Environment.IsDevelopment())
+{
+    app.UseExceptionHandler("/Home/Error");
+    app.UseHsts();
+}
+else
+{
+    app.UseSwagger();
+    app.UseSwaggerUI(c =>
+    {
+        c.SwaggerEndpoint("/swagger/v1/swagger.json", "Документация");
+        c.RoutePrefix = "docs";
+    });
+    app.UseDeveloperExceptionPage(); //используем страницу исключений
+}
+
+// app.UseHttpsRedirection();
+
+app.UseStaticFiles();
+app.UseRouting();
+
+app.UseAuthorization();
+
+app.MapControllerRoute(
+    name: "default",
+    pattern: "{controller=Home}/{action=Index}/{id?}");
+
+app.Run();
+```
+
+</details>
+<br>
+
+---
+- 🌋 В диспетчере выполнения задач выполнить задачу `default` для генерации файлов
+---
+- 🌋 В настройках проекта в разделе `Выходные данные` поставить галочку на `Файл документации` - `Создание файла, содержащего документацию по API` для успешной работы **`Swagger`**
+---
+
+## 🎇 Итог 🎇
+
+#### 📷 База 📷
+При успешном старте в данном примере мы получим сервер:
+- по адресу **`https://localhost:8833`** 
+- документацию Swagger **`https://localhost:8833/docs/`**
+---
+#### 📷 Плюшки 📷 
+---
+- в свою очередь при вёрстке `Typescript` и активированной задаче `default` в `Диспетчере выполнения задач` - в реальном времени будет перезагружаться страница и мы увидим новые изменения на `Frontned` - лицевой стороне Web-сервера после каждого сохранения файла в проекте
+- при установке параметров указанных для `production` версии в файле `webpack.config.js` мы можем собрать `Release` версию и опубликовать её в сеть в которой все файлы `css` и `js` будут сжаты и минимизированы для более быстрой и качественной работы сервера в сети
+- мы можем прикрутить любую существующую библиотеку NPM и использовать её в скриптах `Typescript` для создания качественного `Frontend` - состояние которого мы можем отслеживать в реальном времени при разработке. Typescript поддерживает последние возможности ECMAScript (например, async/await, декораторы, модули и т. д.), что делает код более современным и удобным.
+- используя ASP.NET Core MVC для серверной части (backend), позволяет создавать масштабируемые, производительные и безопасные веб-приложения 
+- Typescript для фронтенда (frontend) обеспечивает типизацию и улучшение читаемости кода, предотвращая множество ошибок, которые могут возникнуть при использовании обычного JavaScript.
+---
+#### 📷 Примерный процесс разработки: 📷
+---
+🎃 Frontend (Typescript + Webpack):
+
+🎈 Вы пишете код на Typescript, который потом компилируется с помощью Webpack.
+Webpack минифицирует и обрабатывает ваши файлы, генерирует отдельные чанки для кода, CSS и изображений.
+Grunt помогает автоматизировать задачи, такие как запуск Webpack, минификация CSS/JS, запуск локального сервера с BrowserSync.
+Backend (ASP.NET Core MVC):
+
+🎈 Серверная часть обрабатывает бизнес-логику, запросы от клиента и взаимодействует с базой данных.
+Вся верстка и фронтенд код (собранный через Webpack) размещаются в папке wwwroot или другой папке для статических файлов.
+
+🎃 Автоматизация сборки и деплоя:
+
+🎈 Grunt автоматически обрабатывает сборку фронтенда, выполняет задачи, такие как минификация, копирование файлов и т. д.
+Webpack поддерживает горячую замену модулей, что ускоряет процесс разработки.
+Разработка с возможностью тестирования и отладки:
+
+🎈 В процессе разработки с помощью BrowserSync можно синхронизировать несколько браузеров и автоматически перезагружать страницы.
+Webpack и Grunt делают разработку более продуктивной за счет автоматизации рутинных задач.
\ No newline at end of file