feat: apply the advice from advisor (#9)

* feat: apply the advice from advisor

* feat: update eng abstract

* feat: add api doc appendix

appendix.tex

@@ -1,3 +1,63 @@
-\chapter{เรื่องที่หนึ่ง}
+\chapter{วิธีการติดตั้งเพื่อใช้งานใน Local Environment}
+
+\begin{enumerate}
+	\item ดาวน์โหลดซอร์สโค้ดจาก Repository ที่ URL https://github.com/deeptech-kmitl/project-beaver
+	\item ดาวน์โหลดและติดตั้ง Node.js ตั้งแต่เวอร์ชัน 20 เป็นต้นไป
+	\item ดาวน์โหลดและติดตั้ง PNPM ตั้งแต่เวอร์ชัน 8 เป็นต้นไป
+	\item ดาวน์โหลดและติดตั้ง Go ตั้งแต่เวอร์ชัน 1.21 เป็นต้นไป
+	\item ดาวน์โหลดและติดตั้ง Docker ตั้งแต่เวอร์ชัน 24 เป็นต้นไป
+	\item ดาวน์โหลดและติดตั้ง Google Cloud CLI ตั้งแต่เวอร์ชัน 444 เป็นต้นไป
+	\item ติดตั้ง Package dependencies ด้วยคำสั่ง pnpm install
+	\item ยืนยันตัวตนผู้เข้าใช้งาน Google Cloud Environment ด้วยคำสั่ง gcloud config set auth/impersonate\_service\_account 335637802412-compute@developer.gserviceaccount.com
+	\item สร้าง Local Database Environment ด้วยคำสั่ง docker compose up -d
+	\item เปิดเซิร์ฟเวอร์สำหรับเว็บไซต์ด้วยคำสั่ง pnpm nx serve web
+	\item สร้าง Binary เพื่อใช้เปิดระบบด้วยคำสั่ง pnpm nx run-many -t build --projects="tag:api" --parallel=10
+	\item เปิดเซิร์ฟเวอร์สำหรับระบบหลังบ้านด้วยคำสั่ง
+		GCP\_BUCKET\_NAME="coolbeaver-app-data" \
+		GCP\_UPLOAD\_PATH="user-documents/" \
+		GCP\_CERTIFICATE\_PATH="certificates/" \
+		GCP\_SERVICE\_ACCOUNT\_ID="335637802412-compute@developer.gserviceaccount.com" \
+		GCP\_PROJECT\_ID="coolbeaver" \
+		DATABASE\_URL="mysql://root:coolbeaver@localhost:3306/coolbeaver" \
+		pnpm nx run-many -t serve --projects="tag:api" --parallel=50
+	\item ทดสอบการใช้งานด้วยการเข้าไปยัง http://localhost:4200
+\end{enumerate}
+
+\chapter{วิธีการนำส่งระบบขึ้นไปยัง Google Cloud Platform}
+
+\begin{enumerate}
+	\item ดาวน์โหลดซอร์สโค้ดจาก Repository ที่ URL https://github.com/deeptech-kmitl/project-beaver
+	\item ดาวน์โหลดและติดตั้ง Node.js ตั้งแต่เวอร์ชัน 20 เป็นต้นไป
+	\item ดาวน์โหลดและติดตั้ง PNPM ตั้งแต่เวอร์ชัน 8 เป็นต้นไป
+	\item ดาวน์โหลดและติดตั้ง Go ตั้งแต่เวอร์ชัน 1.21 เป็นต้นไป
+	\item ดาวน์โหลดและติดตั้ง Docker ตั้งแต่เวอร์ชัน 24 เป็นต้นไป
+	\item ดาวน์โหลดและติดตั้ง Google Cloud CLI ตั้งแต่เวอร์ชัน 444 เป็นต้นไป
+	\item ติดตั้ง Package dependencies ด้วยคำสั่ง pnpm install
+	\item ยืนยันตัวตนผู้เข้าใช้งาน Google Cloud Environment ด้วยคำสั่ง gcloud config set auth/impersonate\_service\_account 335637802412-compute@developer.gserviceaccount.com
+	\item หากมีการเพิ่ม API ใหม่ ให้เพิ่ม Service ไปที่ tools/deployment/skaffold.yaml
+	\item หากมีการเพิ่ม API ใหม่ ให้เพิ่มไฟล์การตั้งค่า Service ไปที่ tools/deployments/services/<service-name>.yaml
+	\item หากมีการเพิ่ม API ใหม่ ให้เพิ่มการตั้งค่า Gateway ไปที่ tools/deployments/gateway/main.yaml
+	\item หากมีการเพิ่ม API ใหม่ ให้เพิ่ม Deployment Pipeline ไปที่ tools/deployments/clouddeploy.yaml
+	\item เมื่อทำการแก้ไข API เรียบร้อย ให้ปรับใช้การเปลี่ยนแปลงไปยัง Cloud Deploy ด้วยคำสั่ง gcloud deploy apply --file=tools/deployments/clouddeploy.yaml --region=asia-southeast1 --project=coolbeaver
+	\item หลังจากนั้นให้เพิ่มการตั้งค่า Gateway ด้วยคำสั่ง gcloud api-gateway api-configs create <gateway-config-name> \
+      --api=core --openapi-spec=./tools/deployments/gateway/main.yaml \
+      --project=coolbeaver --backend-auth-service-account=335637802412-compute@developer.gserviceaccount.com
+	\item เมื่อตั้งค่า Gateway สำเร็จ ให้ปรับใช้การตั้งค่าด้วยคำสั่ง gcloud api-gateway gateways update core-gateway \
+      --api=core --api-config=<gateway-config-name> \
+      --location=asia-northeast1 --project=coolbeaver
+	\item เมื่อทำเสร็จสิ้นทุกขั้นตอน สามารถบันทึกการเปลี่ยนแปลงไปยัง Repository ได้ทันที และเป็นอันจบขั้นตอนการนำส่งระบบ
+\end{enumerate}
+
+\chapter{เอกสารคู่มือของ API}
+
+เอกสารคู่มือของ API สามารถเข้าถึงได้จาก https://bebras-schema.pages.dev \\
+
+ในคู่มือจะเป็นเอกสารอิเล็กทรอนิกส์ในรูปแบบเว็บไซต์ ที่ช่วยให้เห็นถึงพารามิเตอร์ และรูปแบบการตอบกลับได้สวยงามขึ้น ด้วย Redoc ที่ Generate เพิ่มเติมจาก Swagger Schema อันเดียวกับที่ใช้ในการตั้งค่า API Gateway ช่วยให้ผู้จัดทำสามารถเข้าใจและปรับใช้โครงสร้างข้อมูลได้อย่างถูกต้อง
+
+\begin{figure}[H]
+    \centering
+    \includegraphics[width=125mm,scale=1.0]{images/redoc-schema.png}
+    \caption{ตัวอย่างเอกสารคู่มือของ API ในรูปแบบเว็บไซต์}
+    \label{fig:redoc-schema}
+\end{figure}
 
-\lipsum[1-8]

chapters/chapter1.tex

@@ -32,16 +32,9 @@ \section{ขั้นตอนการดำเนินงานของโ
     \item ศึกษาการใช้งานของเทคโนโลยีที่ใช้
 \end{enumerate}
 
-\section{ขั้นตอนการดำเนินงานของโครงงาน}
-\begin{enumerate}
-    \item รวบรวมและวิเคราะห์ความต้องการของผู้ใช้งาน
-    \item ร่วมกันพูดคุยกับทีมเรื่องเทคโนโลยีที่ใช้
-    \item ออกแบบฐานข้อมูล
-    \item ศึกษาการใช้งานของเทคโนโลยีที่ใช้
-\end{enumerate}
-
 \section{ประโยชน์ที่คาดว่าจะได้รับ}
 \begin{enumerate}
     \item ได้รับประสบการณ์ในการออกแบบ ปรับปรุง และพัฒนาระบบ ที่ทันสมัยและสามารถนำมาใช้งานได้จริง
     \item ได้รับทักษะในค้นคว้าและเก็บข้อมูลจากผู้ใช้งานจริง เพื่อนำมาพัฒนาระบบที่สามารถใช้งานได้จริง
-\end{enumerate}
+    \item ครูผู้ประสานงานและผู้จัดการการแข่งขัน ได้รับระบบที่ใช้งานได้ง่ายผ่านเว็บแอปพลิเคชัน รวดเร็ว และทันสมัย
+\end{enumerate}

chapters/chapter3.tex

@@ -143,3 +143,21 @@ \subsection{พจนานุกรมข้อมูลของตารา
 \input{tables/database-participates}
 \input{tables/database-questions}
 
+\section{โครงสร้างการนำส่งระบบ (Deployment Architecture)}
+
+การนำส่งระบบเพื่อให้ผู้ใช้งานสามารถใช้จริงบนเว็บแอปพลิเคชันนั้น ทางผู้จัดทำได้นำส่งขึ้นบน Google Cloud Platform เพื่อให้สามารถได้เซิร์ฟเวอร์ที่เสถียร ปลอดภัย และทันสมัย โดยจะเริ่มที่
+เมื่อผู้จัดทำส่งโค้ดขึ้นไปบน GitHub Repository ระบบ Continuous Integration ของ GitHub Actions จะทำการ Build Container Image และสร้างการ Release ไปบน Cloud Deploy เพื่อเก็บ Container Image ไปยัง Artifact Repository และเริ่มการ Build Service บน Google Cloud Platform ด้วย Cloud Build ในระหว่างกระบวนการนี้ Cloud Build จะเก็บ Log ไว้บน Logging Service เมื่อ Build สำเร็จ Cloud Build จะสร้าง Rolling Release เพื่อนำไปปรับใช้กับ Cloud Run เพื่อทำการสร้าง Revision ให้สามารถใช้งานต่อได้ทันทีโดยไม่ต้องปิดเซิร์ฟเวอร์ และสามารถเข้าถึง API บน Cloud Run ได้ผ่าน Cloud API Gateway
+ดังแสดงในรูปที่ \ref{fig:deployment-architecture}
+
+\begin{figure}[H]
+    \centering
+    \includegraphics[width=120mm,scale=1.0]{diagrams/cloud.png}
+    \caption{แผนภาพโครงสร้างการนำส่งระบบบน Google Cloud Platform}
+    \label{fig:deployment-architecture}
+\end{figure}
+
+\subsection{ระบบย่อยทั้งหมด (Microservices)}
+
+ในการนำส่งระบบแสดงสถิติและจัดการรายชื่อของผู้สมัครแข่งขันทดสอบทักษะการคิดเชิงคำนวณ ได้ปรับใช้การพัฒนาแบบ Microservices เพื่อช่วยให้สามารถแยกการทำงานของ API ให้ชัดเจนมากขึ้น ดังตารางที่ \ref{tab:api-mapping}
+
+\input{tables/api-mapping}

full-report.tex

@@ -4,6 +4,7 @@
 \documentclass{itkmitlproject}
 
 \usepackage{afterpage}
+\usepackage{longtable}
 \usepackage{graphicx,amsmath,latexsym,amssymb,amsthm,svg}
 \usepackage{indentfirst}
 \usepackage{hyperref}
@@ -68,11 +69,14 @@
     \pagenumbering{Roman}
 
     \makeabstract{
-        Bebras เป็น Web application สำหรับคุณครูชั้นมัธยมศึกษาในการเพิ่มรายชื่อนักเรียนโดยการส่งรายชื่อนักเรียนที่ต้องการเป็นไฟล์ Excel (.xlsx) เพื่อส่งนักเรียนในรายชื่อไปแข่งขันใน Moodle จากการที่ได้ร่วมพัฒนาโปรเจกต์นี้ นักศึกษาได้รับมอบหมายให้พัฒนาในส่วนของระบบระบบแสดงสถิติและจัดการรายชื่อของผู้สมัครแข่งขันทดสอบทักษะการคิดเชิงคำนวณ ซึ่งเป็นหนึ่งในฟังก์ชันการทำงานที่สำคัญของโปรเจกต์ ซึ่งประกอบไปด้วยการแสดงสถิติคะแนนของผู้เข้าแข่งขันและสามารถจัดการรายชื่อของผู้สมัครได้แก่ การเพิ่มรายชื่อ ลบรายชื่อและแก้ไขรายชื่อ
+        Bebras เป็นการแข่งขันทดสอบทักษะการคิดเชิงคำนวณ ที่นักเรียนทั่วประเทศสามารถเข้าร่วมการทดสอบแข่งขันได้ โดยการจัดการรายชื่อผู้เข้าแข่งขันจะจัดการบนระบบเว็บแอปพลิเคชัน
+        เพื่อให้คุณครูสามารถใช้งานและเข้าถึงได้ง่ายผ่านเว็บเบราว์เซอร์และสามารถเพิ่มรายชื่อนักเรียนโดยการส่งรายชื่อนักเรียนที่ต้องการเพิ่มเป็นไฟล์ Excel (.xlsx) เพื่อส่งรายชื่อนักเรียนในรายชื่อไปแข่งขันบนระบบ Moodle
+        จากการที่ได้ร่วมพัฒนาโปรเจกต์นี้ นักศึกษาได้รับมอบหมายให้พัฒนาในส่วนของระบบแสดงสถิติและจัดการรายชื่อของผู้สมัครแข่งขันทดสอบทักษะการคิดเชิงคำนวณ
+        ซึ่งเป็นหนึ่งในฟังก์ชันการทำงานที่สำคัญของโปรเจกต์ ซึ่งประกอบไปด้วยการแสดงสถิติคะแนนของผู้เข้าแข่งขันและสามารถจัดการรายชื่อของผู้สมัคร ได้แก่ การเพิ่มรายชื่อ ลบรายชื่อและแก้ไขรายชื่อ
     }
 
     \makeabstracteng{
-        Bebras is a web application designed for middle school teachers to manage student lists by uploading student names in Excel files (.xlsx) for participation in competitions on Moodle. As part of this project, We have been tasked with developing the system's statistical display and management of applicant lists for a computational thinking skills test. This is one of the critical functionalities of the project, including displaying statistics of participant scores and the ability to manage applicant lists, such as adding, deleting, and editing names.
+        Bebras is a computational thinking skills test competition where students across the country can participate in competitive contest. The contestant list management will be managed on a Web application so that teachers can easily use and access it through a web browser and can add a list of students by submitting the list of students they want to add as an Excel file (.xlsx) to submit the list of students to compete on the Moodle. Our tasks is developing a system to display statistics and manage candidates' lists to test their computational thinking skills, which is one of the key functionalities of the project.
     }
 
     \makeack
@@ -120,8 +124,8 @@
     \bibliography{references}
     \def\inbib{0}
 
-    % \startappendix
-    % \include{appendix}
+    \startappendix
+    \include{appendix}
 
     \makeauthorbio
 \end{document}