Build_God/AGENTS.md

AGENTS.md - Build God Project

Project Overview

• Backend: ASP.NET Core 8.0 + PostgreSQL + SqlSugar ORM
• Admin Frontend: Vue 3 + TypeScript + Vite + Element Plus (port 5173)
• Game Frontend: Vue 3 + TypeScript + Vite + Element Plus + TailwindCSS + Three.js (port 5174)

---

1. Build, Lint, and Test Commands

Backend

dotnet build Build_God_Api/Build_God_Api/Build_God_Api.csproj
dotnet run --project Build_God_Api/Build_God_Api/Build_God_Api.csproj
dotnet run --urls "http://localhost:5091"

No test framework or linting configured.

Admin Frontend

npm install
npm run dev              # http://localhost:5173
npm run build            # Production build
npm run type-check       # Type-check only
npm run preview          # Preview production build

Game Frontend

npm install
npm run dev              # http://localhost:5174
npm run build            # Production build
vue-tsc --build          # Type-check only

No test framework or ESLint configured for frontends.

---

2. Code Style Guidelines

Backend (.NET/C#)

Conventions:

• File-scoped namespaces (namespace Build_God_Api.Controllers;)
• Nullable reference types enabled (<Nullable>enable</Nullable>)
• Primary constructors for dependency injection
• Use async/await for all I/O operations
• Avoid region - prefer natural code organization

Naming:

• Classes/Types: PascalCase (AccountController)
• Methods/Properties: PascalCase (GetAccount)
• Local variables/Parameters: camelCase (accountId)
• Interfaces: Prefix with I (IAccountService)
• DTOs: Postfix with Cmd for commands, Dto for responses

Project Structure:

Build_God_Api/Build_God_Api/
  Controllers/    # API endpoints
  Services/       # Business logic interfaces & implementations
  Services/Game/  # Game-specific services
  DB/             # Database entities (extend BaseEntity)
  Dto/            # Data transfer objects
  Common/         # Utilities
  Hubs/            # SignalR hubs

Error Handling:

• BadRequest("message") for validation errors
• Ok(result) for success
• Try-catch with Console.WriteLine for error logging
• Use DataAnnotations for input validation at controller level

Route Conventions:

• [Route("api/god/[controller]")]
• [ApiController] with [HttpGet]/[HttpPost] attributes

Database (SqlSugar):

• Entities extend BaseEntity (provides Id, CreatedOn, UpdatedOn, CreatedBy, UpdatedBy)
• Auto-increment PK: [SugarColumn(IsPrimaryKey = true, IsIdentity = true)]

---

Frontend (Vue 3 + TypeScript)

Conventions:

• Composition API with <script setup lang="ts">
• Path alias: @/ maps to src/
• Admin: Plain CSS (<style scoped lang="css">)
• Game: Tailwind CSS utility classes

Naming:

• Components: PascalCase (LoginView.vue, Sidebar.vue)
• Variables/functions: camelCase (handleLogin)
• Types/Interfaces: PascalCase (LoginRequest)
• Store names: kebab-case in defineStore (defineStore('auth', ...))

Project Structure:

Admin: src/api/, src/components/, src/views/, src/stores/, src/router/, src/assets/
Game:  src/api/, src/components/, src/composables/, src/views/, src/stores/, src/router/

TypeScript Settings (tsconfig.app.json):

{ "strict": false, "strictNullChecks": false, "noUnusedLocals": false, "noUnusedParameters": false }

API Pattern (shared axios instance):

// src/api/index.ts
const instance = axios.create({
  baseURL: import.meta.env.VITE_API_URL || 'http://localhost:5091/api/god/',
  timeout: 10000,
  headers: { 'Content-Type': 'application/json' }
})
instance.interceptors.request.use((config) => {
  const token = localStorage.getItem('auth_token') // or sessionStorage for Admin
  if (token) config.headers.Authorization = `Bearer ${token}`
  return config
})
instance.interceptors.response.use(
  (response) => response.data,
  (error) => { /* handle 401, reject with data */ }
)
export default instance

// src/api/{entity}.ts
import http from './index'
export const characterApi = {
  getList: (): Promise<CharacterDto[]> => http.get('/character/list')
}

Pinia Store Pattern:

export const useAuthStore = defineStore('auth', () => {
  const token = ref('')
  const isAuthenticated = computed(() => !!token.value)
  const login = async (credentials: LoginRequest): Promise<boolean> => { /* ... */ }
  return { token, isAuthenticated, login }
})

---

3. API Integration

• Base URL: http://localhost:5091/api/god/
• Auth: JWT Bearer tokens
  • Game: localStorage as auth_token
  • Admin: sessionStorage as auth_token

Key Endpoints:

• POST /api/god/account/register
• POST /api/god/account/login
• POST /api/god/account/login/admin

---

4. Development Workflow

1. dotnet run --project Build_God_Api/Build_God_Api/Build_God_Api.csproj
2. npm run dev in Build_God_Admin_Frontend/Frontend/
3. npm run dev in Build_God_Game/

---

5. Adding New Features

Backend

1. Create model in DB/ (extend BaseEntity)
2. Create interface in Services/
3. Implement service in Services/
4. Create controller in Controllers/
5. Register service in Program.cs

Frontend

1. Add API function in src/api/{entity}.ts
2. Add Pinia store in src/stores/ if needed
3. Create view component in src/views/
4. Add route in src/router/index.ts

---

6. Important Notes

• Admin credentials: admin / love_god.123
• Test account: Tom / 123456 (email: 976802198@qq.com)
• Backend: ports 59447 (HTTPS), 59448 (HTTP)
• Always use await with async operations