Build_God/AGENTS.md

AGENTS.md - Build God Project

Guidelines for agentic coding agents working on this repository.

Project Overview

• Backend: ASP.NET Core 8.0 Web API (C#) with PostgreSQL and 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 (.NET API)

# Build the solution
dotnet build Build_God_Api/Build_God_Api/Build_God_Api.csproj

# Run the API (launches on https://localhost:59447, http://localhost:59448)
dotnet run --project Build_God_Api/Build_God_Api/Build_God_Api.csproj

# Run with specific URL
dotnet run --urls "http://localhost:5091"

Note: No test framework or linting is currently configured for the backend.

Admin Frontend (Build_God_Admin_Frontend/Frontend)

# Install dependencies
npm install

# Start development server (http://localhost:5173)
npm run dev

# Build for production
npm run build

# Type-check only
npm run type-check

# Preview production build
npm run preview

Game Frontend (Build_God_Game)

# Install dependencies
npm install

# Start development server (http://localhost:5174)
npm run dev

# Build for production
npm run build

# Type-check only
vue-tsc --build

Note: No test framework or ESLint is configured for either frontend.

---

2. Code Style Guidelines

Backend (.NET/C#)

Conventions

• Use file-scoped namespaces (namespace Build_God_Api.Controllers;)
• Enable nullable reference types (<Nullable>enable</Nullable>)
• Use primary constructors for dependency injection
• Use async/await for all I/O operations
• Use region sparingly - prefer natural code organization

Naming

• Classes/Types: PascalCase (AccountController, AccountService)
• Methods/Properties: PascalCase (GetAccount, UserName)
• Local variables/Parameters: camelCase (accountId, emailAddress)
• 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
  Services/Game/         # Game-specific services
  DB/                    # Database entities (extend BaseEntity)
  Dto/                   # Data transfer objects
  Common/                # Utilities and helpers
  Hubs/                  # SignalR hubs

Error Handling

• Return BadRequest("error message") for validation errors
• Return Ok(result) for successful operations
• Use try-catch with Console.WriteLine for error logging
• Validate inputs at controller level using DataAnnotations

Route Conventions

• Use [Route("api/god/[controller]")]
• Use [ApiController] and HTTP method attributes ([HttpGet], [HttpPost])

Database Entities (SqlSugar)

• All entities extend BaseEntity which provides Id, CreatedOn, UpdatedOn, CreatedBy, UpdatedBy
• Use [SugarColumn(IsPrimaryKey = true, IsIdentity = true)] for auto-increment primary keys

---

Frontend (Vue 3 + TypeScript)

Conventions

• Use Composition API with <script setup lang="ts">
• Use path aliases: @/ 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, userName)
• Types/Interfaces: PascalCase (LoginRequest, User)
• Store names: kebab-case in defineStore (defineStore('auth', ...))

Project Structure

Admin Frontend (src/):
  api/              # API modules
  components/       # Reusable components
  views/            # Page components (subdir: admin/)
  stores/           # Pinia stores
  router/           # Vue Router config
  assets/           # Static assets

Game Frontend (src/):
  api/              # API modules
  components/       # Reusable components
  composables/      # Vue composables
  views/            # Page components
  stores/            # Pinia stores
  router/           # Vue Router config

Imports

• Use @/ alias: import { useAuthStore } from '@/stores/auth'
• Order: external libs → internal imports → types/interfaces

TypeScript Settings (tsconfig.app.json)

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

TypeScript Patterns

• Define types/interfaces for all API payloads
• Use ref<T> and computed<T> for reactive state
• Use unknown or proper types instead of any

Vue Component Pattern

<script setup lang="ts">
import { ref, computed } from 'vue'
import { useRouter } from 'vue-router'
import { ElMessage } from 'element-plus'

const router = useRouter()
const loading = ref(false)
</script>

<template>
  <!-- Element Plus components -->
</template>

<style scoped lang="css">
/* Component styles */
</style>

Pinia Store Pattern

import { defineStore } from 'pinia'
import { ref, computed } from 'vue'

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

API Module Pattern

All API modules share a centralized axios instance from api/index.ts.

src/api/index.ts - Shared axios instance (one per frontend):

import axios from 'axios'

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) => {
    if (error.response?.status === 401) {
      localStorage.removeItem('auth_token')
      window.location.href = '/login'
    }
    return Promise.reject(error.response?.data || error.message)
  }
)

export default instance

src/api/{entity}.ts - Individual API modules (import from index):

import http from './index'

export interface CharacterDto { ... }

export const characterApi = {
  getList: (): Promise<CharacterDto[]> => {
    return http.get('/character/list')
  }
}

---

3. API Integration

Base URL

• Development: http://localhost:5091/api/god/
• Routes: api/god/{entity} (e.g., api/god/account/login)

Authentication

• JWT Bearer tokens
• Store in localStorage as auth_token (Game) or sessionStorage (Admin)
• Header: Authorization: Bearer {token}

Key Endpoints

• POST /api/god/account/register - Register account
• POST /api/god/account/login - User login
• POST /api/god/account/login/admin - Admin login

---

4. Development Workflow

1. Start Backend: dotnet run --project Build_God_Api/Build_God_Api/Build_God_Api.csproj
2. Start Admin Frontend: npm run dev (in Build_God_Admin_Frontend/Frontend/)
3. Start Game Frontend: 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 (import http from ./index)
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 runs on ports 59447 (HTTPS) and 59448 (HTTP)
• Admin Frontend uses sessionStorage; Game Frontend uses localStorage
• Always use await with async operations
• Run type-check before committing