LabX Backend

Base ASP.NET Core Web API net9.0, tổ chức theo Clean Architecture nhẹ và có quy trình phát triển với agent. Mở LabX_Be.sln từ thư mục này trong Visual Studio, hoặc mở cả thư mục bằng Codex.

Chạy nhanh

Cần .NET SDK theo global.json (9.0.300 hoặc bản vá mới hơn cùng feature band) và truy cập NuGet để restore/audit.

./scripts/verify.ps1
./scripts/smoke-test.ps1
dotnet run --project src/Api --launch-profile http

• API: http://localhost:5033/.
• OpenAPI JSON: http://localhost:5033/openapi/v1.json (Development; chưa có Swagger UI).
• Health: /health, /health/live, /health/ready.
• Dừng API: Ctrl+C.
• Một lệnh locked restore/NuGet audit/format/build/test/coverage: ./scripts/verify.ps1.
• Kiểm tra tiến trình HTTP thật sau khi build Release: ./scripts/smoke-test.ps1.
• Quét dependency/secret/image: hướng dẫn kiểm tra.

Cấu trúc

LabX_Be.sln
src/
  Api/                     HTTP, middleware, config, DI
  Application/             DTOs, interfaces, services, validators, mappings
  Domain/                  Entities, value objects, business rules
  Infrastructure/          Persistence và external adapters
tests/
  UnitTests/               Project test unit, chưa có test case
  IntegrationTests/        Project test integration, chưa có test case
  ArchitectureTests/       Project test kiến trúc, chưa có test case
docs/                     Context, hướng dẫn, ADR, API, test strategy, templates
scripts/                  Verify, HTTP smoke test và security scan
.codex/agents/            Custom subagents cho backend, SDS và testing
.agents/skills/           Skills cho backend, API, database, debugging, review, SDS và testing
.github/workflows/        Build/test trên GitHub Actions
AGENTS.md                 Hướng dẫn dùng chung cho agent

Đã tạo sẵn các thư mục nền trong bốn layer; xem cấu trúc chi tiết. Các thư mục code đã được tạo theo mẫu phân loại trách nhiệm; SDS, system test và handoff được tạo khi có nội dung thực tế. bin/, obj/ và artifacts/ là output tự sinh khi build/test, có thể xóa và tạo lại.

Làm việc với agent

Đọc quy trình và prompt mẫu, bắt đầu từ bối cảnh dự án.

• Codex tự đọc AGENTS.md ở root và file scoped trong src/, tests/ hoặc docs/.
• Custom subagents backend_development, software_design_specification và testing được đăng ký ở .codex/agents/.
• Skills trong .agents/skills/ được Codex phát hiện tự động; có thể gọi bằng $skill-name.
• Ví dụ: Dùng testing subagent để viết integration test cho API foundation hoặc $backend-development implement requirement tôi cung cấp.
• Không cần tài khoản API, plugin riêng hay package AI để sử dụng bộ hướng dẫn này.
• Agent Backend Development dùng backend-development, api-development, database-development, backend-debugging hoặc code-review; xem prompt mẫu trong hướng dẫn trên.

Cấu hình

Đọc hướng dẫn cấu hình. CORS mặc định đóng; Development cho phép http://localhost:3000 và http://localhost:5173. Production/Staging đặt origin qua biến môi trường. Chỉ tạo thêm appsettings.{Environment}.json khi cần override; dotnet run không tự đọc .env.

docker compose up --build

Docker dùng cổng 8080 và môi trường Production mặc định; xem /health. Đây là container API, chưa kèm database. Hạ container bằng docker compose down khi dùng xong.

Triển khai Linux

CI publish image đã kiểm tra lên ghcr.io/dat23052004/stm-be bằng tag commit SHA và tag branch. Bộ CD Linux dùng Docker Compose, Caddy HTTPS, hai slot staging/production và SSH deployment có kiểm tra health/rollback. Deploy tự động mặc định tắt cho tới khi điền GitHub Environments và server config; xem hướng dẫn triển khai Linux.

Phạm vi hiện tại

Đã có solution, HTTP pipeline nền, cấu hình môi trường, ba project test trống, CI, Docker, GHCR/CD scaffold cho Linux và bộ agent/tài liệu. Chưa có use case nghiệp vụ hoặc test case; source đang ở trạng thái base để bắt đầu phát triển tính năng thật. Chưa chọn database, authentication/authorization, storage/email, frontend hoặc mô hình nghiệp vụ LabX. Giữ .NET 9 theo yêu cầu. Repository được lưu tại dat23052004/stm-be; workflow build-test chạy khi push vào main/develop, khi mở pull request hoặc khi chạy thủ công. Dependabot theo dõi NuGet, Docker và GitHub Actions; các bản nâng major của .NET SDK/runtime bị bỏ qua để không tự chuyển dự án sang .NET 10. Các quyết định này được theo dõi trong project context; không sao chép nghiệp vụ AuLac.

Xem kiến trúc, chiến lược test và quyết định base.