Nhật ký công việc cho nhiệm vụ "Hợp nhất dịch vụ next-js và app"

Cổng thông tin "Gorodskie bani" được viết lại hoàn toàn trên haih-agent

Trong khuôn khổ nhiệm vụ, trang web không chỉ đơn thuần được chuyển sang một engine khác, mà thực chất đã được viết lại hoàn toàn từ đầu trên kiến trúc haih-agent / haih CMS.

Kho lưu trữ của engine: https://github.com/haih-net/agent/

Phiên bản cổng thông tin cũ: https://old.gorodskie-bani.ru/

Phiên bản mới: https://gorodskie-bani.ru/

Mục tiêu chính của việc đại tu là loại bỏ kiến trúc nặng nề và phân mảnh của dự án Next.js cũ, đồng thời chuyển cổng thông tin sang mô hình đơn giản hơn, thống nhất hơn và hướng tới AI (AI-first), nơi nội dung, cấu trúc trang và sự phát triển tiếp theo của trang web thuận tiện nhất cho việc làm việc thôngผ่าน AI.

Những gì đã được thực hiện

Trên thực tế, bốn khối công việc lớn đã được hoàn thành:

• xây dựng hoàn toàn phiên bản công khai mới của trang web trên haih-agent;
• tái cấu trúc kiến trúc lưu trữ nội dung;
• chuyển toàn bộ cơ sở dữ liệu lịch sử từ MySQL sang PostgreSQL;
• chuyển trang web sang mô hình trong đó phần lớn việc quản lý và phát triển có thể được thực hiện bởi AI agent thông qua API và các thực thể nội dung được chuẩn hóa.

Do đó, sẽ chính xác hơn nếu xem xét giai đoạn này không phải là một "thiết kế lại" thông thường hoặc "thay đổi CMS", mà là một cuộc đại tu kiến trúc hoàn chỉnh của sản phẩm.

Di chuyển MySQL → PostgreSQL

Phiên bản cũ của trang web lưu trữ dữ liệu trong MySQL và sử dụng số lượng lớn các thực thể và bảng riêng biệt cho các loại nội dung khác nhau.

Để chuyển sang hệ thống mới, các trình nhập (importers) chuyên dụng đã được viết để:

• đọc dữ liệu từ cơ sở dữ liệu MySQL cũ;
• chuyển đổi các cấu trúc cũ thành mô hình chuẩn hóa mới;
• chuyển dữ liệu sang PostgreSQL;
• duy trì các liên kết, nội dung lịch sử và các URL hiện có ở những nơi cần thiết;
• điều chỉnh nội dung cũ cho hệ thống tệp, hình ảnh và trang mới.

Việc di chuyển cơ sở dữ liệu lịch sử là một trong những phần quan trọng nhất của công việc, bởi vì trang web mới không chỉ bắt đầu từ tờ giấy trắng mà phải giữ lại nội dung đã tích lũy qua nhiều năm.

Thay vì nhiều thực thể — một Concept duy nhất

Một trong những thay đổi kiến trúc quan trọng là việc từ bỏ số lượng lớn các thực thể chuyên biệt.

Trong dự án cũ, ví dụ, có các thành phần tồn tại riêng biệt:

• thành phố;
• nhà tắm và phòng xông hơi;
• đánh giá;
• bình luận;
• bài viết;
• các loại nội dung khác.

Đối với mỗi loại như vậy, thường cần có các mô hình, truy vấn, mẫu (templates), logic hiển thị, API và kịch bản quản trị riêng.

Trong kiến trúc mới, phần lớn nội dung được quy về một thực thể phổ quát — Concept.

Concept chỉ chứa một vài trường cơ bản:

• Tên;
• Mô tả SEO;
• Phần giới thiệu cho danh sách;
• Nội dung;
• Hình ảnh;
• Danh sách tệp cho thư viện ảnh;
• Tọa độ cho bản đồ.

Đồng thời, ý nghĩa của thực thể không được xác định bằng một bảng cứng nhắc riêng biệt trong cơ sở dữ liệu, mà bằng ngữ cảnh, các mối liên kết, đường dẫn và nội dung.

Cơ chế cơ bản giống nhau có thể được sử dụng cho thành phố, cơ sở, bài viết hoặc loại tài liệu khác.

Tại sao việc chuẩn hóa lại đơn giản hóa đáng kể cơ sở mã

Phương pháp tiếp cận này làm giảm đáng kể khối lượng mã ứng dụng.

Trước đây, mỗi loại nội dung mới có tiềm năng yêu cầu:

• mô hình dữ liệu mới;
• các thao tác CRUD riêng biệt;
• các hợp đồng API riêng biệt;
• biểu mẫu quản trị riêng biệt;
• các mẫu hoặc thành phần React riêng biệt;
• logic lựa chọn và hiển thị bổ sung.

Sau khi chuyển sang Concept, phần lớn cơ sở hạ tầng này trở thành chung.

Điều này làm giảm:

• số lượng mô hình chuyên biệt;
• số lượng các truy vấn trùng lặp;
• khối lượng logic mẫu (boilerplate logic);
• số lượng nơi cần duy trì hành vi giống nhau;
• chi phí phát triển trang web sau này.

Càng ít thực thể đặc biệt, càng ít mã liên quan cần được giữ trong bộ nhớ của ứng dụng và thực thi khi hiển thị trang.

Kết quả là kiến trúc trở nên đơn giản hơn đối với cả máy chủ và nhà phát triển.

Giảm tải cho việc tạo mẫu (templating)

Việc chuẩn hóa nội dung không chỉ ảnh hưởng đến cấu trúc cơ sở dữ liệu mà còn ảnh hưởng đến việc hiển thị.

Thay vì số lượng lớn các mẫu riêng biệt cho các loại trang khác nhau, một tập hợp chung các thành phần và quy tắc hiển thị được sử dụng.

Các trang có thể được lắp ráp từ Markdown và các thành phần đặc biệt: thẻ, ảnh bìa, thư viện ảnh, bản đồ, cột, liên kết, khối tương tác với AI và các phần tử khác.

Điều này cho phép một hệ thống kết xuất duy nhất phục vụ số lượng lớn các trang khác nhau mà không cần phải tạo một trang React riêng biệt hoặc một tập hợp các mẫu đặc biệt cho từng thực thể.

Nói cách khác, độ phức tạp được chuyển từ nhiều mô hình chương trình rời rạc sang nội dung được chuẩn hóa + các thành phần có thể tái sử dụng.

Thay đổi chính — trang web đã trở thành AI-first

Điều quan trọng nhất trong việc đại tu này không phải là thiết kế mới hay thậm chí là việc thay đổi stack công nghệ.

Kiến trúc mới từ đầu đã được xây dựng sao cho trang web có thể được phát triển và duy trì đầy đủ thông qua AI.

AI agent sẽ dễ dàng hơn rất nhiều khi làm việc với một hệ thống mà thay vì hàng chục hợp đồng khác nhau, chỉ có một mô hình Concept dễ hiểu và một số thao tác chuẩn.

Đối với agent, không còn cần phải hiểu riêng biệt:

• bảng thành phố được sắp xếp như thế nào;
• API của bài viết khác với API của nhà tắm ở điểm nào;
• các trường đánh giá nằm ở đâu;
• phương pháp riêng biệt nào được sử dụng để cập nhật một loại tài liệu cụ thể;
• biểu mẫu quản trị nào chịu trách nhiệm cho đối tượng này hay đối tượng khác.

Phần lớn nội dung được xử lý theo cùng một cách.

Điều này có nghĩa là agent có thể sử dụng các thao tác giống nhau để:

• tạo tài liệu;
• cập nhật văn bản;
• thay đổi mô tả SEO;
• thêm hình ảnh;
• chỉnh sửa phần giới thiệu;
• làm việc với tọa độ;
• chuẩn bị thư viện ảnh;
• xây dựng lại các trang;
• cập nhật hàng loạt nội dung;
• tìm kiếm và phân tích thông tin bên trong trang web.

Quản lý nội dung hoàn toàn thông qua AI

Trong hệ thống mới, bảng điều khiển quản trị cổ điển không còn là phương thức chính để quản lý trang web nữa.

Nội dung có thể truy cập thông qua API và AI agent có thể thực hiện các thay đổi theo tác vụ của con người.

Trên thực tế, quy trình làm việc giờ đây trông như sau:

con người diễn ạt tác vụ → AI phân tích trang web và dữ liệu → thực hiện các thay đổi thông qua API → con người kiểm tra kết quả.

Điều này hoàn toàn khác biệt so với CMS truyền thống, nơi con người buộc phải thủ công đi qua các biểu mẫu quản trị và chỉnh sửa từng thực thể riêng biệt.

Kết quả là AI không còn là một "phòng chat" bổ sung nằm trên trang web, mà trở thành một giao diện quản lý và phát triển dự án đầy đủ.

Trợ lý AI cho người dùng cuối

Việc chuẩn hóa nội dung tương tự cũng rất hữu ích cho agent trò chuyện với khách truy cập cổng thông tin.

Vì các thành phố, cơ sở, ấn phẩm và các tài liệu khác được trình bày theo định dạng nhất quán, agent sẽ dễ dàng hơn trong việc:

• tìm kiếm thông tin cần thiết;
• hiểu các mối liên hệ giữa các đối tượng;
• tìm các cơ sở ở một thành phố cụ thể;
• sử dụng tọa độ và dữ liệu địa lý;
• làm việc với các mô tả và ấn phẩm;
• tạo câu trả lời dựa trên nội dung hiện có.

Nói cách khác, kiến trúc mới đồng thời cải thiện hai phía của việc làm việc với AI:

1. AI như một công cụ của nhà phát triển và chủ sở hữu trang web — tạo và chỉnh sửa nội dung, thay đổi cấu trúc trang và giúp phát triển dự án.
2. AI như một giao diện cho khách truy cập — điều hướng trong danh mục và trả lời các câu hỏi của người dùng.

Cập nhật giao diện và phần công khai

Song song với việc di chuyển kiến trúc, phần công khai của cổng thông tin đã được cập nhật hoàn toàn.

Trong phiên bản mới, các tính năng sau đã được triển khai:

• trang chủ được cập nhật;
• điều hướng và kiểu chữ mới;
• danh mục cơ sở;
• trang cá nhân của các nhà tắm và phòng xông hơi;
• thư viện ảnh;
• phân trang (pagination);
• danh mục thành phố;
• điều hướng theo bảng chữ cái và tìm kiếm;
• các trang thành phố với các bộ sưu tập cơ sở;
• bản đồ với các điểm đánh dấu và nhóm đối tượng;
• các ấn phẩm theo địa chỉ lịch sử;
• giao diện gọi trợ lý AI.

Do đó, kiến trúc mới không bị giới hạn ở việc tái cấu trúc bên trong — phiên bản công khai hoạt động của cổng thông tin với dữ liệu lịch sử thực tế đã được lắp ráp hoàn chỉnh trên đó.

SEO và bảo tồn nội dung lịch sử

Trong quá trình di chuyển, điều quan trọng là không làm mất giá trị tìm kiếm của trang web hiện có.

Do đó, trong quá trình chuyển đổi, các yếu tố sau đã được tính đến:

• URL lịch sử;
• các ấn phẩm cũ;
• trang cơ sở;
• trang thành phố;
• liên kết nội bộ;
• mô tả SEO;
• nội dung hiện có.

Việc giữ nguyên các đường dẫn cũ ở những nơi có thể sẽ làm giảm nguy cơ tụt hạng hàng loạt của các trang đã được lập chỉ mục sau khi thay đổi engine.

Đồng thời, việc chuyển sang haih-agent không có nghĩa là tự động tăng thứ hạng tìm kiếm. Hiệu ứng SEO của kiến trúc mới trước hết nằm ở chỗ trang web trở nên dễ bảo trì hơn, thay đổi nhanh hơn, dễ mở rộng nội dung hơn và thuận tiện hơn để cải thiện có hệ thống với sự trợ giúp của AI.

Giờ đây, việc cập nhật hàng loạt siêu dữ liệu (metadata), văn bản, cấu trúc trang và nội dung có thể được thực hiện nhanh hơn đáng kể so với kiến trúc trước đây.

Tại sao điều này lại quan trọng đối với sự phát triển trong tương lai

Kết quả chính của việc di chuyển không chỉ là giảm nợ kỹ thuật (technical debt).

Cổng thông tin giờ đây nằm trong một kiến trúc cho phép thực hiện các tác vụ trong tương lai nhanh hơn rất nhiều.

Quy trình làm việc mới trông như sau:

triển khai engine → cấu hình giao diện và các thành phần → lắp ráp các trang → tải lên hoặc tạo nội dung → tiếp tục phát triển trang web thông qua AI và API.

Nếu cần thiết, các quy trình nghiệp vụ phức tạp vẫn có thể có các mô hình chương trình riêng biệt, nhưng nội dung tiêu chuẩn không còn đòi hỏi phải tạo ra cơ sở hạ tầng riêng cho từng loại trang mới.

Điều này đặc biệt quan trọng đối với các dự án nội dung lớn, nơi chi phí bảo trì thường không được xác định bằng độ phức tạp của một trang, mà bằng số lượng các thực thể, biểu mẫu và mẫu khác nhau.

Thời gian thực hiện

Việc đại tu toàn bộ cổng thông tin, bao gồm giao diện mới, chuyển dữ liệu lịch sử và di chuyển sang kiến trúc mới, đã được hoàn thành trong khoảng ba ngày.

Đồng thời, phần lớn thời gian đã được dành cho việc đảm bảo khả năng tương thích với trang web cũ và nhập cơ sở dữ liệu hiện có.

Dự án mới nếu không cần phải chuyển đổi cấu trúc legacy trên một engine đã được chuẩn bị sẵn thì có thể được lắp ráp nhanh hơn đáng kể.

Tổng kết

Trong khuôn khổ nhiệm vụ, trang web "Gorodskie bani" thực chất đã được tạo lại từ đầu trên haih-agent.

Kiến trúc phân mảnh cũ với số lượng lớn các thực thể chuyên biệt đã được thay thế bằng mô hình thống nhất Concept, cơ sở dữ liệu lịch sử đã được chuyển từ MySQL sang PostgreSQL bằng các trình nhập được viết riêng, và phần công khai của cổng thông tin đã được lắp ráp lại hoàn toàn trên engine mới.

Thành tựu chính của công việc này là việc chuyển đổi sang kiến trúc trang web hướng dẫn bởi AI (AI-driven).

Giờ đây, AI không chỉ có thể trả lời khách truy cập mà còn có thể tham gia đầy đủ vào sự phát triển của chính dự án: làm việc với nội dung, thay đổi trang, cập nhật dữ liệu SEO, quản lý tệp, cấu trúc tài liệu và thực hiện các thao tác hàng loạt thông qua API.

Kết quả là trang web đã trở nên đơn giản hơn về kiến trúc, tiết kiệm chi phí hơn trong việc phát triển sau này và thích nghi tốt hơn đáng kể cho việc phát triển, điền nội dung và hỗ trợ với sự trợ giúp của trí tuệ nhân tạo.

haih CMS / haih-agent trong dự án này không chỉ được sử dụng như một engine mới, mà còn là nền tảng cho trang web, nơi AI là một thành viên đầy đủ của toàn bộ vòng đời — từ phát triển đến quản lý nội dung và giao tiếp với người dùng cuối.