Hướng dẫn bắt đầu với SoftJL Community: Dùng AI kết nối yêu cầu, UML, kiểm thử và tài liệu

SoftJL Community là gì

SoftJL Community là một nền tảng kỹ nghệ phần mềm AI có thể tự triển khai, hướng đến đồ án tốt nghiệp, đồ án môn học và bài tập UML về phần mềm. Nền tảng kết nối phân tích yêu cầu, phân tích tính khả thi, mô hình hóa UML, thiết kế, kiểm thử, tài liệu kỹ thuật và theo dõi thay đổi, giúp bạn kiểm tra yêu cầu đã được triển khai vào thiết kế và kiểm thử hay chưa, đồng thời sắp xếp các căn cứ có thể truy xuất để chỉnh sửa, báo cáo và bảo vệ đồ án.

Phiên bản Community cung cấp đầy đủ mã nguồn và được cấp phép theo Apache License 2.0. So với phiên bản được lưu trữ trên trang chính thức, phiên bản Community yêu cầu bạn tự quản lý dịch vụ, cơ sở dữ liệu và nhà cung cấp mô hình, nhưng vẫn giữ các năng lực chính như trích xuất quy tắc yêu cầu, mô hình yêu cầu và thiết kế đầy đủ, phạm vi kiểm thử, tạo tài liệu, truy xuất nguồn, quản lý dự án và kết nối mô hình BYOK.

Quy trình làm việc cốt lõi

Nền tảng hoạt động theo một chuỗi kỹ thuật từ yêu cầu đến xác minh: trước tiên nhập yêu cầu và xác nhận các quy tắc, sau đó tiến hành phân tích tính khả thi, tạo mô hình yêu cầu và mô hình thiết kế, tiếp theo tạo ca kiểm thử và ma trận phạm vi bao phủ, cuối cùng tạo tài liệu kỹ thuật có thể chỉnh sửa và tải xuống.

• Quy tắc yêu cầu: trích xuất quy tắc từ yêu cầu ngôn ngữ tự nhiên, kiểm tra chất lượng, chỉnh sửa, xác nhận thủ công và sắp xếp điều kiện nghiệm thu.
• Phân tích tính khả thi: tạo sơ đồ môi trường hệ thống, sơ đồ quy trình nghiệp vụ và hệ thống, cùng với phân tích phương án triển khai.
• Mô hình UML: xây dựng các mô hình về cấu trúc chức năng, ca sử dụng, khái niệm miền, giao diện nguyên mẫu, yêu cầu triển khai, kiến trúc tổng thể, lớp thiết kế và cơ sở dữ liệu.
• Kiểm thử và phạm vi bao phủ: tạo ca kiểm thử cho các kịch bản thông thường, bất thường và biên, đồng thời xác định khoảng trống thông qua ma trận phạm vi bao phủ và ma trận truy xuất.
• Tài liệu kỹ thuật: tạo báo cáo nghiên cứu tính khả thi, đặc tả yêu cầu phần mềm và tài liệu thiết kế phần mềm, đồng thời hỗ trợ quản lý phiên bản và tải xuống DOCX.
• Ảnh hưởng của thay đổi: xem quan hệ nguồn giữa yêu cầu, thiết kế, kiểm thử và tài liệu để xác định những sản phẩm nào cần cập nhật sau khi sửa đổi.
• Kết nối mô hình: cấu hình dịch vụ mô hình tương thích với OpenAI để gọi nhà cung cấp mô hình của bạn.

Kết quả tạo ra được dùng để xác định và sắp xếp các căn cứ kỹ thuật; vẫn cần con người kiểm tra các ràng buộc mô hình, nội dung biểu đồ, tính nhất quán nghiệp vụ của tài liệu, đồng thời thực hiện kiểm thử trong hệ thống thực tế.

Chuẩn bị môi trường trước khi cài đặt

Cần chuẩn bị các môi trường sau cho lần chạy đầu tiên:

• Node.js 22
• npm 10
• Java 21
• Graphviz
• Tùy chọn: Docker để chạy PostgreSQL và OnlyOffice

Khi sử dụng dịch vụ kết xuất lần đầu, hệ thống có thể cần kết nối mạng để tải phông chữ tiếng Trung cho PDF. Docker không bắt buộc khi trải nghiệm tạm thời các dịch vụ cốt lõi, nhưng nên cấu hình PostgreSQL bền vững khi sử dụng lâu dài; nếu cần chỉnh sửa DOCX trực tuyến, bạn cũng phải bật OnlyOffice.

Khởi động nhanh các dịch vụ cốt lõi

1. Lấy mã nguồn và cài đặt phụ thuộc

git clone https://github.com/guolola/SoftJL.git
cd SoftJL
npm ci

2. Khởi động môi trường phát triển

npm run dev

Lệnh này tự động xây dựng các gói dùng chung contracts và prompts, đồng thời khởi động song song các dịch vụ Web, API và kết xuất. Web thường chạy trên http://localhost:3000, API sử dụng cổng 4101, còn Render Service sử dụng cổng 4002.

Sau khi thấy đầu ra Web là Ready, bạn có thể mở http://localhost:3000. Đồng thời nên kiểm tra trạng thái hoạt động:

http://localhost:3000/api/health
http://127.0.0.1:4002/health

Cả hai giao diện kiểm tra trạng thái đều phải trả về kết quả chứa status: "ok".

3. Tìm hiểu chế độ bộ nhớ tạm thời

Chạy trực tiếp npm run dev mặc định sẽ sử dụng chế độ bộ nhớ tạm thời. Sau khi dịch vụ khởi động lại, tài khoản, dự án, cấu hình dịch vụ mô hình và lịch sử chạy sẽ bị mất; các tệp tài liệu được lưu riêng trong thư mục cục bộ cũng không thể thay thế bản sao lưu cơ sở dữ liệu. Vì vậy, chế độ này phù hợp để trải nghiệm nhanh nhưng không phù hợp để lưu trữ dự án lâu dài.

Cấu hình cơ sở dữ liệu bền vững và chỉnh sửa trực tuyến

Sử dụng PostgreSQL phát triển

Sau khi cài đặt và khởi động Docker trên máy, bạn có thể dùng lệnh sau để chạy cơ sở dữ liệu phát triển chuyên dụng và các dịch vụ cốt lõi:

npm run dev:postgres

Cách này sẽ lưu cơ sở dữ liệu trong volume dữ liệu Docker. Thông tin xác thực trong tập lệnh chỉ dùng cho phát triển trên máy cục bộ; môi trường sản xuất bắt buộc phải thay thế, và không được dùng trực tiếp cơ sở dữ liệu của phiên bản đầy đủ hiện có làm cơ sở dữ liệu cho phiên bản Community.

Kết nối PostgreSQL hiện có

Nếu đã chuẩn bị PostgreSQL, bạn có thể sao chép .env.example ở thư mục gốc thành .env, sau đó thiết lập DATABASE_URL và UML_PROVIDER_CONFIG_SECRET do bạn tự tạo:

cp .env.example .env

Sau khi cấu hình xong, chạy lại npm run dev. Hãy bảo quản cẩn thận khóa mã hóa, vì tùy ý thay đổi UML_PROVIDER_CONFIG_SECRET sẽ khiến thông tin xác thực của nhà cung cấp mô hình đã lưu không thể giải mã. Không được đưa thông tin kết nối cơ sở dữ liệu và khóa vào Git.

Bật OnlyOffice

Khi cần chỉnh sửa tài liệu trực tuyến, trước tiên hãy khởi động Docker Engine, sau đó chạy:

npm run dev:full

Tập lệnh này sẽ kiểm tra OnlyOffice trên cổng 8080 của máy cục bộ; nếu dịch vụ không khả dụng, tập lệnh sẽ tạo hoặc khởi động container tương ứng. Lần chạy đầu tiên có thể cần tải image. Chỉ các dịch vụ cốt lõi cũng có thể tạo và tải tài liệu; chức năng chỉnh sửa trực tuyến cần cấu hình OnlyOffice bổ sung.

Cấu hình dịch vụ mô hình AI

1. Khởi động dịch vụ Web và đăng nhập tài khoản.
2. Vào phần cài đặt tài khoản và thêm một Provider tương thích với OpenAI.
3. Nhập HTTPS Base URL và API Key của nhà cung cấp mô hình.
4. Thực hiện khám phá mô hình và kiểm tra kết nối.
5. Chọn một mô hình khả dụng làm mô hình mặc định.

Trong môi trường tự triển khai, hãy sử dụng dịch vụ mô hình của riêng bạn; chi phí gọi mô hình do nhà cung cấp tương ứng thanh toán. Môi trường sản xuất nên sử dụng cơ sở dữ liệu bền vững và khóa mã hóa thông tin xác thực, đồng thời tắt lối vào khách phát triển và cơ chế dự phòng văn bản thuần legacy.

Hoàn tất một lần mô hình hóa bằng hệ thống đặt chỗ ngồi thư viện

Dưới đây là một yêu cầu đơn giản: sau khi đăng nhập, sinh viên tra cứu chỗ ngồi còn trống, chọn ngày và khung giờ để gửi đặt chỗ; cùng một sinh viên không được đặt trùng trong cùng khung giờ; sau khi đặt chỗ thành công sẽ gửi thông báo; quản trị viên có thể quản lý chỗ ngồi, xem lịch sử đặt chỗ và xử lý các trường hợp hủy bất thường.

Bước 1: Tạo dự án và xác nhận quy tắc yêu cầu

Sau khi tạo dự án, nhập mô tả nghiệp vụ trên vào nền tảng để hệ thống trích xuất các quy tắc yêu cầu. Tập trung kiểm tra vai trò người dùng, điều kiện đặt chỗ, ràng buộc đặt trùng, hành vi thông báo và quy trình hủy bất thường. Sau khi xác nhận chính xác, hãy lưu các quy tắc và điều kiện nghiệm thu để tránh việc các mô hình sau dựa trên yêu cầu mơ hồ.

Bước 2: Hoàn tất phân tích tính khả thi

Hoàn tất ba hạng mục phân tích theo quy trình dự án:

• Sơ đồ môi trường hệ thống: xác định ranh giới và tương tác giữa sinh viên, quản trị viên, dịch vụ thông báo và hệ thống đặt chỗ.
• Sơ đồ quy trình nghiệp vụ và hệ thống: làm rõ quy trình xử lý tra cứu chỗ ngồi, gửi đặt chỗ, gửi thông báo và hủy bất thường.
• Phương án triển khai: so sánh các phương án ứng viên, ghi lại chi phí, lợi ích và rủi ro.

Sau khi hoàn tất phân tích, trước tiên hãy kiểm tra ranh giới hệ thống và quy trình có phù hợp với yêu cầu ban đầu hay không, rồi mới chuyển sang giai đoạn tạo mô hình.

Bước 3: Tạo mô hình yêu cầu và mô hình thiết kế

Nền tảng có thể tạo mô hình yêu cầu đầy đủ dựa trên các yêu cầu đã xác nhận, bao gồm cấu trúc chức năng, quy trình nghiệp vụ tổng thể, ca sử dụng, khái niệm miền, quan hệ giao diện nguyên mẫu và yêu cầu triển khai. Sau khi xác nhận mô hình yêu cầu, hệ thống sẽ tạo mô hình thiết kế theo quan hệ tiền đề, chẳng hạn như kiến trúc tổng thể, hiện thực hóa ca sử dụng, lớp thiết kế, điều hướng trang, cơ sở dữ liệu, quan hệ thành phần và thiết kế triển khai.

Sau khi tạo, hãy mở quan hệ nguồn để kiểm tra mỗi phần tử thiết kế có thể truy xuất ngược về quy tắc yêu cầu hay không. Nhờ đó, khi quy tắc đặt chỗ thay đổi, bạn có thể dễ dàng xác định các ca sử dụng, lớp, thiết kế cơ sở dữ liệu và bài kiểm thử bị ảnh hưởng.

Bước 4: Tạo kiểm thử và ma trận phạm vi bao phủ

Đối với hệ thống đặt chỗ, ít nhất hãy kiểm tra các kịch bản sau:

• Sinh viên có thể tra cứu chỗ ngồi còn trống trong ngày và khung giờ được chỉ định.
• Sinh viên có thể gửi đặt chỗ hợp lệ và nhận thông báo.
• Khi cùng một sinh viên đặt trùng trong cùng khung giờ, hệ thống có thể từ chối yêu cầu.
• Khi không có chỗ trống, khung giờ không hợp lệ hoặc thiếu thông tin đặt chỗ, hệ thống có thể xử lý ngoại lệ.
• Quản trị viên có thể quản lý chỗ ngồi, xem lịch sử đặt chỗ và xử lý hủy bất thường.

Sử dụng ma trận phạm vi bao phủ và ma trận truy xuất để xác định các yêu cầu chưa có căn cứ thiết kế hoặc kiểm thử. Các ca kiểm thử do nền tảng tạo ra vẫn cần được thực thi trong hệ thống thực tế; không thể chỉ lấy việc tạo thành công làm kết quả nghiệm thu.

Bước 5: Tạo tài liệu kỹ thuật

Sau khi hoàn tất phân tích tính khả thi, mô hình yêu cầu và mô hình thiết kế, bạn có thể tạo ba loại tài liệu kỹ thuật: báo cáo nghiên cứu tính khả thi, đặc tả yêu cầu phần mềm và tài liệu thiết kế phần mềm. Sau khi tạo, hãy kiểm tra tính nhất quán giữa nội dung và biểu đồ, chỉnh sửa theo mẫu và yêu cầu định dạng của trường, rồi quản lý phiên bản và tải xuống DOCX.

Cách xử lý khi yêu cầu thay đổi

Ví dụ, dự án thay đổi quy tắc từ “cùng một sinh viên không được đặt trùng trong cùng khung giờ” thành “mỗi sinh viên được đặt tối đa hai khung giờ mỗi ngày”. Không nên chỉ sửa một câu trong tài liệu mà cần kiểm tra theo quan hệ nguồn và phụ thuộc:

1. Lưu và xác nhận quy tắc yêu cầu mới.
2. Mở quan hệ nguồn và ảnh hưởng thay đổi để xem các sản phẩm yêu cầu, ca sử dụng, thiết kế và kiểm thử bị ảnh hưởng.
3. Cập nhật mô hình yêu cầu và mô hình thiết kế theo thứ tự phụ thuộc.
4. Kiểm tra lại các ràng buộc cơ sở dữ liệu, quy trình nghiệp vụ và xử lý ngoại lệ.
5. Cập nhật ca kiểm thử và ma trận phạm vi bao phủ, đồng thời thực hiện kiểm thử hồi quy trong hệ thống thực tế.
6. Tạo lại hoặc chỉnh sửa các tài liệu liên quan và giữ lại lịch sử phiên bản.

Các đường nối nguồn và số lượng bao phủ phù hợp để giúp bạn xác định phạm vi kiểm tra, nhưng cuối cùng vẫn phải mở từng mô hình cụ thể để kiểm tra đầy đủ các ràng buộc, điều kiện đầu vào và hành vi.

Kết nối Coding Agent bên ngoài

Phiên bản Community cho phép người triển khai tự bật kết nối MCP chỉ đọc, để Coding Agent tương thích có thể đọc thiết kế đã lưu trong phạm vi dự án, điều kiện nghiệm thu, ràng buộc kỹ thuật và thông tin kiểm thử. Lối vào trải nghiệm MCP cục bộ là “Trợ lý lập trình” trên thanh bên hoặc “Kết nối dự án này” trong phần cài đặt dự án; trước khi sử dụng cần hoàn tất cài đặt và xây dựng.

npm run dev:mcp

Kết nối này chỉ cung cấp căn cứ kỹ thuật ở chế độ chỉ đọc, không thay thế việc xem xét mã nguồn, chạy thực tế và nghiệm thu kiểm thử. README cũng đặc biệt lưu ý rằng khả năng tương thích của ứng dụng khách Coding Agent thực tế và việc nghiệm thu mã được tạo vẫn đang được hoàn thiện; khi sử dụng, hãy tham khảo tài liệu kết nối MCP.

Các lệnh phát triển thường dùng

• npm run build:packages: xây dựng các gói dùng chung contracts và prompts.
• npm run build: xây dựng các gói dùng chung và toàn bộ ứng dụng.
• npm run dev:render: khởi động riêng dịch vụ kết xuất PlantUML.
• npm run test:contracts: xác thực các hợp đồng dùng chung.
• npm run test:api: chạy kiểm thử API.
• npm run test:render: chạy kiểm thử dịch vụ kết xuất.
• npm run test:web: chạy toàn bộ kiểm thử Web.
• npm run typecheck:web: kiểm tra kiểu Web.
• npm run lint:web: thực hiện kiểm tra tĩnh Web.
• npm audit --audit-level=high: kiểm tra các thông báo bảo mật của phụ thuộc.

Sau khi các gói dùng chung thay đổi, trước khi khởi động riêng ứng dụng hoặc chạy kiểm thử, cần thực hiện npm run build:packages. Đầu ra xây dựng, cấu hình môi trường, khóa riêng, nhật ký và dữ liệu chạy cục bộ phải được giữ trong phạm vi bị Git bỏ qua.

Tổng quan kiến trúc

Dự án sử dụng cấu trúc gồm nhiều ứng dụng và các gói dùng chung:

• apps/web: workspace và các trang React, Next.js.
• apps/api: API Fastify, xác thực, quy trình tạo, bản ghi chạy và lắp ráp tài liệu.
• apps/render-service: kết xuất biểu đồ PlantUML.
• packages/contracts và packages/prompts: các hợp đồng dùng chung và lời nhắc tạo nội dung.
• packages/harness-e2e và packages/harness-eval: kiểm thử nghiệm thu và đánh giá chất lượng.

Lưu ý về triển khai và sử dụng

• Phiên bản cộng đồng nên sử dụng cơ sở dữ liệu riêng, không dùng làm phương án thay thế suy giảm cho cơ sở dữ liệu của phiên bản đầy đủ trên trang chính thức.
• Thông tin xác thực cơ sở dữ liệu trong tập lệnh khởi động phát triển chỉ phù hợp để sử dụng trên máy cục bộ và phải được thay thế trong môi trường sản xuất.
• Không được đưa khóa mô hình, thông tin kết nối cơ sở dữ liệu và khóa mã hóa vào kho mã nguồn.
• Tài liệu kỹ thuật có thể dùng làm tài liệu báo cáo dự án, nhưng không tương đương với một luận văn tốt nghiệp hoàn chỉnh.
• Cần kiểm tra thủ công tính nhất quán nghiệp vụ của biểu đồ, tài liệu và mã nguồn, đồng thời xác minh bằng bằng chứng chạy thực tế.
• Trước khi triển khai sản xuất, cần thay thế cấu hình miền dịch vụ, cơ sở dữ liệu, email và mô hình.

Tóm tắt

SoftJL Community phù hợp với các nhà phát triển muốn tổ chức đồ án tốt nghiệp hoặc đồ án môn học theo quy trình kỹ thuật. Sau khi hoàn tất cài đặt môi trường, cấu hình cơ sở dữ liệu và mô hình, bạn có thể bắt đầu từ các quy tắc yêu cầu để từng bước tạo phân tích khả thi, mô hình yêu cầu và thiết kế UML, phạm vi bao phủ kiểm thử và tài liệu kỹ thuật, đồng thời theo dõi phạm vi ảnh hưởng khi yêu cầu thay đổi.

Công cụ giúp giảm tình trạng tài liệu phân tán và công việc biên soạn lặp lại, nhưng không thể thay thế phán đoán thiết kế của con người, việc triển khai mã nguồn, kiểm thử thực tế và chuẩn bị cho buổi bảo vệ cuối cùng. Nên sử dụng nội dung do nền tảng tạo ra như bản nháp kỹ thuật có thể truy vết và cơ sở kiểm tra, kết hợp với yêu cầu của nhà trường và kết quả vận hành thực tế của hệ thống để hoàn tất sản phẩm bàn giao.