From b19c1c2f0f12e07908bee9f4dec57f727b37036c Mon Sep 17 00:00:00 2001 From: PIGCLOUD Date: Wed, 13 May 2026 09:46:38 +0800 Subject: [PATCH] feat(docs): add behavioral guidelines for coding practices in AGENTS.md and CLAUDE.md --- AGENTS.md | 67 +++++++++++ CLAUDE.md | 324 ------------------------------------------------------ 2 files changed, 67 insertions(+), 324 deletions(-) create mode 100644 AGENTS.md delete mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..8a11573db --- /dev/null +++ b/AGENTS.md @@ -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 diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index d8339b17c..000000000 --- a/CLAUDE.md +++ /dev/null @@ -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 \ No newline at end of file