Nhiệm vụ: Thêm admin resolver để cập nhật hàng loạt URI của concept sang URL thân thiện với SEO

Thêm admin resolver để cập nhật hàng loạt URI của concept sang URL thân thiện với SEO

27.08.2026tác nhân haih

Tạo một admin bulk-resolver an toàn để chuyển đổi các URI concept cũ sang slug dễ đọc với con người và duy trì các chuyển hướng (redirect).

Mục tiêu

Thêm một admin GraphQL resolver vào haih-agent để di chuyển hàng loạt các concept cũ sang các URI thân thiện với con người (ЧПУ / slug).

Hiện tại, vẫn còn một lượng lớn các concept lịch sử trong cơ sở dữ liệu có URI được tạo theo sơ đồ cũ và không sử dụng định dạng slugifyUri mới / dễ đọc. Logic mới hoạt động đối với các thực thể được tạo và sửa đổi, nhưng các bản ghi cũ không tự động di chuyển.

Cần có một công cụ quản trị tập trung cho phép cập nhật các URI đó một cách an toàn và hàng loạt.

Resolver cần làm gì

Thêm một mutation/resolver chỉ dành cho admin (admin-only) để:

Chọn ra các concept cần di chuyển URI.
Đối với mỗi concept, tính toán URI đích theo các quy tắc slugifyUri() hiện hành và tên/phân cấp hiện tại của thực thể.
Không thay đổi URI nếu nó đã khớp với định dạng hiện tại.
Khi thay đổi, sử dụng logic thay đổi URI chung hiện có (processUriChange hoặc tương đương) để tự động tạo chuyển hướng 301 từ địa chỉ cũ sang địa chỉ mới.
Không sao chép các quy tắc slugify/redirect cục bộ bên trong resolver — hãy sử dụng mã chung của haih-agent.
Trả về kết quả thực thi rõ ràng: số bản ghi đã xem xét, số bản ghi đã thay đổi, số bản ghi đã bỏ qua, số bản ghi kết thúc bằng lỗi.

Bảo mật và Khả năng quản lý

Resolver phải hoàn toàn là quản trị viên (administrative).

Nên cung cấp:

dryRun để xem trước các thay đổi sắp tới mà không ghi vào DB;
limit/batch size để di chuyển theo từng phần;
Khả năng tiếp tục di chuyển bằng cursor/offset hoặc một phương pháp ổn định khác;
Bộ lọc chỉ áp dụng cho các concept mà URI thực sự cần thay đổi;
Ghi log oldUri -> newUri;
Phát hiện xung đột URI trước khi ghi;
Hành vi có thể dự đoán được nếu hai concept cạnh tranh cho cùng một URI sau khi slugify;
Khả năng chạy lại resolver một cách an toàn mà không làm hỏng các thực thể đã di chuyển.

Xung đột URI

Xác định chiến lược cho các xung đột một cách riêng biệt.

Không được phép âm thầm ghi đè URI hiện có. Nếu slug được tính toán đã bị chiếm bởi một concept khác, resolver phải:

hoặc bỏ qua bản ghi và trả về xung đột trong báo cáo;
hoặc sử dụng một chiến lược tạo tính duy nhất xác định trước.

Chiến lược này phải được cố định rõ ràng trong quá trình triển khai.

Kịch bản ví dụ

Trước đó:

/concepts/cmt...

hoặc một URI lịch sử/kỹ thuật khác.

Đối với concept có tên:

TypeScript Generics

sau khi di chuyển, nó sẽ trở thành dạng như:

/concepts/typescript-generics

Đồng thời, địa chỉ cũ vẫn phải tiếp tục hoạt động thông qua chuyển hướng 301.

SEO: Tại sao điều này lại cần thiết

Quá trình di chuyển này quan trọng không chỉ để thuận tiện cho URL, mà còn là một phần trong chiến lược SEO/GEO chung của các dự án dựa trên haih-agent.

1. Ngữ nghĩa ngay trong URL

Một địa chỉ kỹ thuật như:

/concepts/cmt7tulwi034wtj0qmz5n3s7h

không cung cấp cho công cụ tìm kiếm bất kỳ ngữ cảnh bổ sung nào về nội dung trang.

Một URL thân thiện như:

/concepts/typescript-generics

chứa các từ trùng khớp với chủ đề của tài liệu. URL trở thành một tín hiệu rõ ràng khác cùng với title, description, tiêu đề và nội dung chính.

2. Snippet rõ ràng hơn và lòng tin của người dùng

URL dễ đọc với con người được nhận diện tốt hơn trong SERP, liên kết và chia sẻ. Người dùng hiểu trang nói về cái gì ngay trước khi nhấp chuột, thay vì một chuỗi ID kỹ thuật.

Điều này có tiềm năng cải thiện chất lượng nhấp chuột và giảm cảm giác về một trang "kỹ thuật" hoặc không minh bạch.

3. Di chuyển ổn định không làm mất các tín hiệu tích lũy

Điều cực kỳ quan trọng là không chỉ thay thế URL, mà còn giữ lại các URL cũ thông qua 301.

301 cho phép các công cụ tìm kiếm hiểu rằng tài liệu đã chuyển đến địa chỉ thường trực mới và chuyển các tín hiệu tích lũy của trang cũ sang URI mới thay vì phát sinh hàng loạt lỗi 404.

4. Canonical và loại bỏ nội dung trùng lặp

Sau khi di chuyển, URI thân thiện với con người sẽ trở thành địa chỉ canonical của trang.

Các URL kỹ thuật cũ không được lập chỉ mục như các bản sao riêng biệt. Chuyển hướng đến URL canonical thân thiện phải hoạt động đối với chúng.

5. Di chuyển hàng loạt nội dung lịch sử

Nếu không có công cụ bulk, cơ chế thân thiện với SEO mới chỉ ảnh hưởng đến các concept mới và được chỉnh sửa thủ công. Phần lớn nội dung đã tích lũy sẽ vẫn ở trên các URI kỹ thuật cũ và không nhận được lợi ích từ URL thân thiện.

Admin resolver cho phép đưa toàn bộ phần lịch sử về mô hình URL mới ngay lập tức hoặc theo từng lô (batch).

6. Nền tảng cho các dự án downstream

Vì fi1osof.ru và các dự án khác sử dụng haih-agent làm cơ sở, resolver nên nằm trực tiếp trong haih-agent chứ không được triển khai riêng biệt trong từng ứng dụng.

Điều này sẽ cung cấp một cơ chế di chuyển URI thống nhất cho tất cả các sản phẩm trên nền tảng này.