mirror of
http://git.pig4cloud.com/pig/pigx.git
synced 2026-11-08 04:39:00 +08:00
feat(docs): add behavioral guidelines for coding practices in AGENTS.md and CLAUDE.md
This commit is contained in:
PIGCLOUD committed
1 parent
21127c11b5
commit
b19c1c2f0f
2 files changed
+67
-324
No files matched your search
@@ -0,0 +1,67 @@
|
||||
# Repository Guidelines
|
||||
|
||||
## Project Structure & Module Organization
|
||||
|
||||
pigx aggregates Spring Cloud services through the root `pom.xml`. Runtime services sit under dedicated folders:
|
||||
`pigx-register` (service discovery/Nacos), `pigx-gateway` (edge routing), `pigx-auth` (OAuth2), `pigx-upms` (user &
|
||||
permission), `pigx-flow` (workflow), `pigx-app-server`, and `pigx-visual` (monitoring plus
|
||||
schedulers). Shared libraries and DTOs live in `pigx-common`. Sample SQL and Docker build contexts reside in `db/`,
|
||||
while infra manifests live in `docker-compose.yml`. Every module uses the standard `src/main/java` and `src/test/java`
|
||||
layout.
|
||||
|
||||
## Build, Test, and Development Commands
|
||||
|
||||
- `mvn -T 1C clean install -DskipTests` compiles all modules with the managed BOM; add `-pl pigx-gateway -am` to limit
|
||||
the build to a single service.
|
||||
- `mvn -pl pigx-gateway spring-boot:run` (swap the module name as needed) starts a service with dev profiles for live
|
||||
reloads.
|
||||
- `docker-compose up -d pigx-mysql pigx-redis pigx-register` brings up local infrastructure; run
|
||||
`docker-compose up --build pigx-auth pigx-upms` when you need the auth stack.
|
||||
- `mvn -pl pigx-knowledge test` executes module tests; append `-DskipITs` to bypass integration suites.
|
||||
|
||||
## Testing Guidelines
|
||||
|
||||
Use `spring-boot-starter-test` (JUnit 5, AssertJ, Mockito) for unit and slice tests. Name classes `*Tests.java` and
|
||||
colocate fixtures in `src/test/resources`. Target >70% line coverage on the service layer that guards authentication,
|
||||
gateway filters, and approval flows. Run `mvn verify` before opening a PR to exercise the full plugin stack.
|
||||
|
||||
## Commit & Pull Request Guidelines
|
||||
|
||||
Follow the repo’s `type(scope): summary` history, e.g. `fix(upms): clear login failure cache` or
|
||||
`feat(ai-voice): add speech transcription`. Each PR must describe the impact area, list affected modules, and reference
|
||||
internal tickets or issues. Attach curl/Postman snippets or screenshots whenever UI or OpenAPI responses change. Rebase
|
||||
on `ai-dev`, avoid committing generated artifacts, and call out schema/config updates explicitly.
|
||||
|
||||
## Security & Configuration Tips
|
||||
|
||||
Never commit environment secrets; rely on `docker-compose.yml` plus `.env` overrides ignored by Git. Keep `db/` seed
|
||||
data sanitized, and drive end-to-end checks against `pigx-register` (ports 8848/9848) with `pigx-gateway` (9999) so
|
||||
discovery behavior matches production.
|
||||
|
||||
## Behavioral Guidelines
|
||||
|
||||
The following four rules apply to all tasks and take precedence over other default behaviors.
|
||||
|
||||
### 1. Think Before Coding
|
||||
|
||||
- When requirements are ambiguous, ask first — never make silent assumptions
|
||||
- If a simpler solution exists, say so explicitly rather than quietly picking a direction
|
||||
- When something is unclear, surface the confusion instead of pushing forward with guesswork
|
||||
|
||||
### 2. Prefer Simplicity
|
||||
|
||||
- Use the minimum code needed to solve the current problem; add nothing unrequested
|
||||
- Do not introduce abstractions for one-off code or design for hypothetical future needs
|
||||
- Ask yourself: would a senior engineer call this over-engineered?
|
||||
|
||||
### 3. Surgical Changes
|
||||
|
||||
- Only touch what the task requires; do not refactor adjacent code as a side effect
|
||||
- Do not alter style or structure unrelated to the current task
|
||||
- Every changed line must trace directly to a stated requirement
|
||||
|
||||
### 4. Goal-Driven Execution
|
||||
|
||||
- Convert vague instructions into verifiable goals — prefer tests as the success criterion
|
||||
- "Fix a bug" → write a failing test that reproduces it, then make it pass
|
||||
- "Add validation" → write tests covering invalid inputs, then make them pass
|
||||
@@ -1,324 +0,0 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Project Overview
|
||||
|
||||
PigX is a proprietary enterprise-grade microservices platform built on Spring Cloud Alibaba, focusing on AI knowledge
|
||||
management, document processing, and intelligent Q&A capabilities. The current version is 5.11.0.
|
||||
|
||||
**Important**: This is NOT an open-source project. All rights reserved by the author. Commercial use requires proper
|
||||
licensing.
|
||||
|
||||
## Technology Stack
|
||||
|
||||
- **Java Version**: Java 17
|
||||
- **Spring Boot**: 3.5.9
|
||||
- **Spring Cloud**: 2025.0.1
|
||||
- **Spring Cloud Alibaba**: 2023.0.3.3
|
||||
- **AI/ML Libraries**:
|
||||
- LangChain4j: 1.6.0
|
||||
- Spring AI: 1.0.2
|
||||
- **Database**:
|
||||
- MySQL (for business data)
|
||||
- PostgreSQL with pgvector extension (for vector storage)
|
||||
- Support for Qdrant, Milvus, Chroma, Neo4j
|
||||
- **ORM**: MyBatis-Plus
|
||||
- **Container**: Undertow
|
||||
- **Service Discovery**: Nacos
|
||||
- **Build Tool**: Maven
|
||||
|
||||
## Project Structure
|
||||
|
||||
### Module Organization
|
||||
|
||||
```
|
||||
pigx/
|
||||
├── pigx-boot/ # Monolithic deployment starter (combines all modules)
|
||||
├── pigx-knowledge/ # AI knowledge base module (core AI capabilities)
|
||||
├── pigx-auth/ # Authentication module (dependency)
|
||||
├── pigx-upms-biz/ # User management module (dependency)
|
||||
├── pigx-gateway/ # API gateway (microservices mode)
|
||||
├── pigx-register/ # Nacos registry (microservices mode)
|
||||
├── pigx-visual/ # Visual management modules (monitoring, codegen, etc.)
|
||||
├── db/ # Database initialization scripts
|
||||
└── docker-compose.yml # Docker compose configuration
|
||||
```
|
||||
|
||||
### Key Module: pigx-knowledge
|
||||
|
||||
The knowledge module follows a standard layered architecture:
|
||||
|
||||
```
|
||||
pigx-knowledge/src/main/java/com/pig4cloud/pigx/knowledge/
|
||||
├── controller/ # REST API endpoints
|
||||
├── service/ # Business logic layer
|
||||
│ └── impl/ # Service implementations
|
||||
├── mapper/ # MyBatis mapper interfaces
|
||||
├── entity/ # JPA/MyBatis entities
|
||||
├── dto/ # Data transfer objects
|
||||
├── config/ # Spring configuration classes
|
||||
└── support/ # Support utilities and handlers
|
||||
├── constant/ # Enums and constants
|
||||
├── handler/ # Specialized handlers
|
||||
│ ├── rag/ # RAG (Retrieval Augmented Generation) handlers
|
||||
│ ├── parse/ # Document parsing handlers
|
||||
│ ├── model/ # AI model handlers
|
||||
│ └── websearch/ # Web search handlers
|
||||
├── provider/ # External service providers
|
||||
├── rule/ # LiteFlow rule definitions
|
||||
├── function/ # LangChain4j functions
|
||||
└── util/ # Utility classes
|
||||
```
|
||||
|
||||
### Vector Storage Architecture
|
||||
|
||||
The system uses a factory pattern for vector store implementations:
|
||||
|
||||
- **Interface**: `EmbeddingStoreFactory` (pigx-knowledge/support/handler/rag/)
|
||||
- **Supported Stores**: Qdrant, Milvus, Chroma, PGVector, Neo4j
|
||||
- **Factory Method**: `createEmbeddingStore(embedStoreEntity, datasetEntity)`
|
||||
- Each store type has its own factory implementation that checks `support(storeType)`
|
||||
|
||||
## Build and Run Commands
|
||||
|
||||
### Maven Profiles
|
||||
|
||||
The project has two main profiles:
|
||||
|
||||
- **cloud** (default): Microservices mode with Spring Cloud
|
||||
- **boot**: Monolithic mode using pigx-boot
|
||||
|
||||
### Build Commands
|
||||
|
||||
```bash
|
||||
# Build entire project (microservices mode)
|
||||
mvn clean install
|
||||
|
||||
# Build monolithic version
|
||||
mvn clean install -P boot
|
||||
|
||||
# Build specific module
|
||||
mvn clean install -pl pigx-knowledge
|
||||
|
||||
# Skip tests
|
||||
mvn clean install -DskipTests
|
||||
|
||||
# Build Docker image for a module
|
||||
mvn clean install docker:build -pl pigx-knowledge
|
||||
|
||||
# Format code according to Spring Java Format
|
||||
mvn spring-javaformat:apply
|
||||
```
|
||||
|
||||
### Run Commands
|
||||
|
||||
#### Monolithic Mode (Recommended for Development)
|
||||
|
||||
```bash
|
||||
# Run pigx-boot module
|
||||
cd pigx-boot
|
||||
mvn spring-boot:run
|
||||
|
||||
# Or run with specific profile
|
||||
mvn spring-boot:run -Dspring-boot.run.profiles=dev
|
||||
```
|
||||
|
||||
**Default port**: 8080 (configured in pigx-boot)
|
||||
|
||||
#### Microservices Mode
|
||||
|
||||
```bash
|
||||
# Start all services using Docker Compose
|
||||
docker-compose up
|
||||
|
||||
# Or start infrastructure first, then individual services
|
||||
# 1. Start Nacos (service discovery)
|
||||
cd pigx-register && mvn spring-boot:run
|
||||
|
||||
# 2. Start gateway
|
||||
cd pigx-gateway && mvn spring-boot:run
|
||||
|
||||
# 3. Start knowledge service
|
||||
cd pigx-knowledge && mvn spring-boot:run
|
||||
```
|
||||
|
||||
**Knowledge service port**: 9010
|
||||
|
||||
### Test Commands
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
mvn test
|
||||
|
||||
# Run tests for specific module
|
||||
mvn test -pl pigx-knowledge
|
||||
|
||||
# Run specific test class
|
||||
mvn test -pl pigx-knowledge -Dtest=YourTestClass
|
||||
|
||||
# Run tests with coverage
|
||||
mvn clean test jacoco:report
|
||||
```
|
||||
|
||||
## Development Configuration
|
||||
|
||||
### Database Setup
|
||||
|
||||
The project uses PostgreSQL with pgvector for the boot module:
|
||||
|
||||
- **Host**: localhost (or pgvector in Docker)
|
||||
- **Port**: 5432
|
||||
- **Database**: pigxx_boot
|
||||
- **Username**: postgres
|
||||
- **Password**: postgres
|
||||
|
||||
Database initialization scripts are in `db/` directory:
|
||||
|
||||
- `0pigxx_boot.sql` - Boot module schema
|
||||
- `9pigxx_ai.sql` - AI knowledge base schema
|
||||
|
||||
### Redis Configuration
|
||||
|
||||
- **Host**: 127.0.0.1
|
||||
- **Database**: 5
|
||||
|
||||
### Nacos Configuration
|
||||
|
||||
For microservices mode:
|
||||
|
||||
- **Server**: pigx-register:8848
|
||||
- **Username**: nacos
|
||||
- **Password**: nacos
|
||||
- Configuration files are loaded from Nacos dynamically
|
||||
|
||||
### File Storage
|
||||
|
||||
Local file storage (configurable):
|
||||
|
||||
- **Path**: /Users/lengleng/Downloads/img (development)
|
||||
- Can be configured in `application-dev.yml`
|
||||
|
||||
## Code Style and Conventions
|
||||
|
||||
### Code Formatting
|
||||
|
||||
The project uses Spring Java Format. Run before committing:
|
||||
|
||||
```bash
|
||||
mvn spring-javaformat:apply
|
||||
```
|
||||
|
||||
### Package Naming Conventions
|
||||
|
||||
- **Controllers**: Suffix with `Controller` (e.g., `AiDatasetController`)
|
||||
- **Services**: Interface without suffix, impl with `Impl` (e.g., `EmbeddingStoreService`, `EmbeddingStoreServiceImpl`)
|
||||
- **Mappers**: Suffix with `Mapper` for both interface and XML (e.g., `AiDatasetMapper.java`, `AiDatasetMapper.xml`)
|
||||
- **Entities**: Suffix with `Entity` (e.g., `AiDatasetEntity`)
|
||||
- **DTOs**: Suffix with `DTO` (e.g., `AiMultimodalEmbeddingArkDTO`)
|
||||
- **Enums**: Suffix with `Enums` (e.g., `EmbedBizTypeEnums`, `ModelSupportEnums`)
|
||||
|
||||
### MyBatis Mapper XML Location
|
||||
|
||||
All MyBatis mapper XMLs are in: `src/main/resources/mapper/*.xml`
|
||||
|
||||
### Constants and Enums
|
||||
|
||||
Located in `support/constant/` package. Key enums:
|
||||
|
||||
- `EmbedBizTypeEnums` - Embedding business types
|
||||
- `ModelSupportEnums` - Supported AI models
|
||||
- `EmbedStoreSupportEnums` - Supported vector stores
|
||||
- `FileTypeEnums` - Supported file types
|
||||
- `ChatTypeEnums` - Chat interaction types
|
||||
|
||||
## AI/RAG Implementation Details
|
||||
|
||||
### Embedding Store Factory Pattern
|
||||
|
||||
When working with vector stores:
|
||||
|
||||
1. Create a factory class implementing `EmbeddingStoreFactory`
|
||||
2. Implement `support(String storeType)` to declare supported types
|
||||
3. Implement `createEmbeddingStore(...)` to instantiate the store
|
||||
4. Register as a Spring `@Component`
|
||||
|
||||
### LangChain4j Integration
|
||||
|
||||
- Document parsers: Apache PDFBox, Apache POI
|
||||
- Embedding models: Support for OpenAI, custom models via factory
|
||||
- Vector stores: Qdrant, Milvus, Chroma, PGVector
|
||||
- Document splitters and transformers in handler/rag package
|
||||
|
||||
### LiteFlow Rule Engine
|
||||
|
||||
Business rules are defined in the `support/rule/` package using LiteFlow DSL.
|
||||
|
||||
## API Documentation
|
||||
|
||||
API documentation is available via Swagger/Knife4j:
|
||||
|
||||
- **Swagger UI**: http://localhost:9010/doc.html (knowledge service)
|
||||
- **OpenAPI**: Enabled via `@EnableOpenApi` annotation
|
||||
- Token URL for auth: Configured in swagger.token-url property
|
||||
|
||||
## Git Workflow
|
||||
|
||||
**Current branch**: ai-leng-dev
|
||||
**Main branch**: dev (use this for PRs)
|
||||
|
||||
## Important Notes
|
||||
|
||||
### Security
|
||||
|
||||
- Configuration encryption: Uses Jasypt with password "pigx"
|
||||
- Login encryption: Uses AES with key "pigxpigxpigxpigx" (16 chars)
|
||||
- OAuth2 resource server protection enabled
|
||||
|
||||
### Docker
|
||||
|
||||
Docker Maven plugin is configured but disabled by default (`docker.skip=false` in pom).
|
||||
Registry: registry.cn-hangzhou.aliyuncs.com/pigcloudx
|
||||
|
||||
### Magic API
|
||||
|
||||
Low-code API platform is integrated for dynamic API creation:
|
||||
|
||||
- Configuration: `src/main/resources/lowcode/magic-api.yml`
|
||||
- Requires additional setup for production use
|
||||
|
||||
### File Parsing
|
||||
|
||||
Supports multiple formats via Tika, Torchv, and custom parsers:
|
||||
|
||||
- PDF, Word, Excel, PowerPoint (Apache POI)
|
||||
- HTML to DOCX conversion (Aspose Words)
|
||||
- Unstructured data (Torchv)
|
||||
|
||||
## Common Development Tasks
|
||||
|
||||
### Adding a New Vector Store
|
||||
|
||||
1. Create factory class in `pigx-knowledge/support/handler/rag/`
|
||||
2. Implement `EmbeddingStoreFactory` interface
|
||||
3. Add store type to `EmbedStoreSupportEnums`
|
||||
4. Add dependencies in `pigx-knowledge/pom.xml`
|
||||
|
||||
### Adding a New AI Model
|
||||
|
||||
1. Add model configuration to `ModelSupportEnums`
|
||||
2. Create model provider in `support/provider/` if needed
|
||||
3. Update embedding service implementation
|
||||
|
||||
### Adding a New Document Parser
|
||||
|
||||
1. Create parser handler in `support/handler/parse/`
|
||||
2. Register file type in `FileTypeEnums`
|
||||
3. Integrate with document processing pipeline
|
||||
|
||||
### Modifying Database Schema
|
||||
|
||||
1. Update SQL in `db/` directory
|
||||
2. Update corresponding entity classes
|
||||
3. Update MyBatis mapper interfaces and XMLs
|
||||
4. Run database migration scripts
|
||||
Reference in new issue
Block a user