# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Overview

Yi.Abp.Net8 is a modular, multi-tenant SaaS platform built on ABP Framework 8.3.4 with .NET 8.0. It uses **SqlSugar** (not EF Core) as the ORM and follows Domain-Driven Design (DDD) principles. The platform includes AI/ML features (chat, models, agents, token tracking), RBAC, forum, messaging, and digital collectibles modules.

## Architecture

### Solution Structure

```
Yi.Abp.Net8/
├── src/                    # Main application host
│   └── Yi.Abp.Web/         # ASP.NET Core 8.0 Web Host (port 19001)
├── framework/              # Framework layer (shared infrastructure)
│   ├── Yi.Framework.Core                    # Core utilities, JSON handling
│   ├── Yi.Framework.SqlSugarCore            # SqlSugar ORM abstraction (v5.1.4.197-preview22)
│   ├── Yi.Framework.SqlSugarCore.Abstractions # Repository interfaces
│   ├── Yi.Framework.AspNetCore              # ASP.NET Core extensions
│   ├── Yi.Framework.AspNetCore.Authentication.OAuth # QQ, Gitee OAuth
│   ├── Yi.Framework.Ddd.Application          # DDD application base classes
│   ├── Yi.Framework.BackgroundWorkers.Hangfire # Job scheduling
│   ├── Yi.Framework.Caching.FreeRedis        # Redis caching
│   └── Yi.Framework.SemanticKernel          # AI/ML integration
├── module/                 # Business modules (each follows 5-layer DDD pattern)
│   ├── ai-hub/            # AI services (chat, models, sessions, agents)
│   ├── rbac/              # Role-Based Access Control (core auth/authz)
│   ├── bbs/               # Forum/community
│   ├── chat-hub/          # Real-time messaging
│   ├── audit-logging/     # Audit trail tracking
│   ├── code-gen/          # Code generation
│   ├── tenant-management/ # Multi-tenancy support
│   ├── digital-collectibles/ # NFT/digital assets
│   └── ai-stock/          # AI-powered stock analysis
├── test/                  # Unit tests (xUnit + NSubstitute + Shouldly)
├── client/                # HTTP API clients
└── tool/                  # Development utilities
```

### Module Structure (DDD Layers)

Each module follows this pattern:

```
module/[feature]/
├── [Feature].Domain.Shared/     # Constants, enums, shared DTOs
├── [Feature].Domain/            # Entities, aggregates, domain services
├── [Feature].Application.Contracts/ # Service interfaces, DTOs
├── [Feature].Application/       # Application services (implementations)
└── [Feature].SqlSugarCore/      # Repository implementations, DbContext
```

**Dependency Flow:** Application → Domain + Application.Contracts → Domain.Shared → Framework

### Module Registration

All modules are registered in `src/Yi.Abp.Web/YiAbpWebModule.cs`. When adding a new module:

1. Add `DependsOn` attribute in `YiAbpWebModule`
2. Add conventional controller in `PreConfigureServices`:
```csharp
options.ConventionalControllers.Create(typeof(YiFramework[Feature]ApplicationModule).Assembly,
    option => option.RemoteServiceName = "[service-name]");
```

### API Routing

All API routes use the unified prefix: `/api/app/{service-name}/{controller}/{action}`

Registered service names:
- `default` - Main application services
- `rbac` - Authentication, authorization, user/role management
- `ai-hub` - AI chat, models, sessions, agents
- `bbs` - Forum posts and comments
- `chat-hub` - Real-time messaging
- `tenant-management` - Multi-tenant configuration
- `code-gen` - Code generation utilities
- `digital-collectibles` - NFT/digital assets
- `ai-stock` - Stock analysis

## Database

**ORM:** SqlSugar (NOT Entity Framework Core)

**Configuration** (`appsettings.json`):
```json
"DbConnOptions": {
  "Url": "DataSource=yi-abp-dev.db",
  "DbType": "Sqlite",  // Sqlite, Mysql, Sqlserver, Oracle, PostgreSQL
  "EnabledCodeFirst": true,    // Auto-create tables
  "EnabledDbSeed": true,        // Auto-seed data
  "EnabledSaasMultiTenancy": true
}
```

**Multi-tenancy:** Tenant isolation via `HeaderTenantResolveContributor` (NOT cookie-based). Tenant is resolved from `__tenant` header.

## Key Technologies

| Component | Technology |
|-----------|-----------|
| Framework | ABP 8.3.4 |
| .NET Version | .NET 8.0 |
| ORM | SqlSugar 5.1.4.197-preview22 |
| Authentication | JWT Bearer + Refresh Tokens |
| OAuth | QQ, Gitee |
| Caching | FreeRedis (optional) |
| Background Jobs | Hangfire (in-memory or Redis) |
| Logging | Serilog (daily rolling files) |
| Testing | xUnit + NSubstitute + Shouldly |
| Container | Autofac |

## Important Notes

- **JSON Serialization:** Uses Microsoft's `System.Text.Json`, NOT Newtonsoft.Json. Date format handled via `DatetimeJsonConverter`.
- **Multi-tenancy:** Tenant resolved from `__tenant` header, NOT cookies.
- **Rate Limiting:** Disabled in development, enabled in production (1000 req/60s sliding window).
- **Swagger:** Available at `/swagger` in development.
- **Hangfire Dashboard:** Available at `/hangfire` (requires JWT authorization).
- **Background Workers:** Disabled in development (`AbpBackgroundWorkerOptions.IsEnabled = false`).

## Development Workflow

1. **Branch:** Main branch is `abp`, current development branch is `ai-hub`.
2. **Commit Convention:** Chinese descriptive messages with prefixes (`feat:`, `fix:`, `style:`).
3. **Testing:** Run `dotnet test` before committing.
4. **Building:** Use `dotnet build --no-restore` for faster builds after initial restore.