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
```bash
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
```bash
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
```bash
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):**
```json
{ "strict": false, "strictNullChecks": false, "noUnusedLocals": false, "noUnusedParameters": false }
```

**API Pattern (shared axios instance):**
```typescript
// 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:**
```typescript
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

<!-- gitnexus:start -->
# GitNexus — Code Intelligence

This project is indexed by GitNexus as **Build_God** (660 symbols, 954 relationships, 0 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.

> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.

## Always Do

- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.

## When Debugging

1. `gitnexus_query({query: "<error or symptom>"})` — find execution flows related to the issue
2. `gitnexus_context({name: "<suspect function>"})` — see all callers, callees, and process participation
3. `READ gitnexus://repo/Build_God/process/{processName}` — trace the full execution flow step by step
4. For regressions: `gitnexus_detect_changes({scope: "compare", base_ref: "main"})` — see what your branch changed

## When Refactoring

- **Renaming**: MUST use `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` first. Review the preview — graph edits are safe, text_search edits need manual review. Then run with `dry_run: false`.
- **Extracting/Splitting**: MUST run `gitnexus_context({name: "target"})` to see all incoming/outgoing refs, then `gitnexus_impact({target: "target", direction: "upstream"})` to find all external callers before moving code.
- After any refactor: run `gitnexus_detect_changes({scope: "all"})` to verify only expected files changed.

## Never Do

- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.

## Tools Quick Reference

| Tool | When to use | Command |
|------|-------------|---------|
| `query` | Find code by concept | `gitnexus_query({query: "auth validation"})` |
| `context` | 360-degree view of one symbol | `gitnexus_context({name: "validateUser"})` |
| `impact` | Blast radius before editing | `gitnexus_impact({target: "X", direction: "upstream"})` |
| `detect_changes` | Pre-commit scope check | `gitnexus_detect_changes({scope: "staged"})` |
| `rename` | Safe multi-file rename | `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` |
| `cypher` | Custom graph queries | `gitnexus_cypher({query: "MATCH ..."})` |

## Impact Risk Levels

| Depth | Meaning | Action |
|-------|---------|--------|
| d=1 | WILL BREAK — direct callers/importers | MUST update these |
| d=2 | LIKELY AFFECTED — indirect deps | Should test |
| d=3 | MAY NEED TESTING — transitive | Test if critical path |

## Resources

| Resource | Use for |
|----------|---------|
| `gitnexus://repo/Build_God/context` | Codebase overview, check index freshness |
| `gitnexus://repo/Build_God/clusters` | All functional areas |
| `gitnexus://repo/Build_God/processes` | All execution flows |
| `gitnexus://repo/Build_God/process/{name}` | Step-by-step execution trace |

## Self-Check Before Finishing

Before completing any code modification task, verify:
1. `gitnexus_impact` was run for all modified symbols
2. No HIGH/CRITICAL risk warnings were ignored
3. `gitnexus_detect_changes()` confirms changes match expected scope
4. All d=1 (WILL BREAK) dependents were updated

## Keeping the Index Fresh

After committing code changes, the GitNexus index becomes stale. Re-run analyze to update it:

```bash
npx gitnexus analyze
```

If the index previously included embeddings, preserve them by adding `--embeddings`:

```bash
npx gitnexus analyze --embeddings
```

To check whether embeddings exist, inspect `.gitnexus/meta.json` — the `stats.embeddings` field shows the count (0 means no embeddings). **Running analyze without `--embeddings` will delete any previously generated embeddings.**

> Claude Code users: A PostToolUse hook handles this automatically after `git commit` and `git merge`.

## CLI

| Task | Read this skill file |
|------|---------------------|
| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |

<!-- gitnexus:end -->