# aicrm_server

**Repository Path**: hello101105/aicrm_server

## Basic Information

- **Project Name**: aicrm_server
- **Description**: 智能crm
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-26
- **Last Updated**: 2026-10-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# songzhi-server (AI-CRM Backend)

#### Introduction

Backend service of the AI-CRM (AI-powered Customer Relationship Management) system. Built on the songzhi framework (a RuoYi-Vue derivative), it provides full-domain CRM APIs and an AI Agent gateway.

- Tech stack: Spring Boot 3.3.2 / Java 17 / Maven multi-module / MyBatis-Plus / Flowable 7 / MySQL
- Base package: `com.songzhi`, parent POM: `com.songzhi:songzhi-server:4.3.0`
- Packaging: fat jar with `<classifier>exec</classifier>`

#### Module Architecture

| Module | Description |
|--------|-------------|
| songzhi-admin | Bootstrap module (packages songzhi-admin exec.jar), aggregates all dependencies and configuration |
| songzhi-framework | Framework foundation (Shiro security, interceptors, web config) |
| songzhi-system | System management (users/roles/menus/dictionaries/logs) |
| songzhi-common | Common utilities and base classes |
| songzhi-dynamic-datasource | Dynamic multi-datasource support |
| songzhi-flowable | Workflow engine (approval flows) |
| **songzhi-crm** | **CRM business domains**: lead / campaign / customer / opportunity / product / quotation / order / contract / receivable / follow-up / after-sales / performance target / competitor / schedule / aggregated dashboards — 13 domains mapped to 29 `crm_` tables |
| **songzhi-agent** | **Agent gateway**: tool registry, risk-graded execution (low: auto / medium: card confirmation / high: double confirmation), LLM orchestration SPI (default MockLlmService keyword rules, gracefully degradable), entity alignment, SSE streaming chat, four-element audit (agent_chat_log), daily brief job, ASR speech-to-text SPI |
| songzhi-api | Open API |
| songzhi-ureport | UReport designer |

#### Requirements

- JDK 17+
- Maven 3.8+
- MySQL 5.7+ / 8.0
- Redis

#### Installation

1. Create database `aicrm` (utf8mb4) and run the scripts under `sql/` in order:
   - `crm_ddl.sql` (29 table DDLs)
   - `crm_dict.sql` (dictionary data)
   - `crm_menu.sql` (menus 3000~3153)
2. Edit database/Redis connection settings in `songzhi-admin/src/main/resources/application-dev.yml` (database name is already set to `aicrm`).
3. Build:

```bash
mvn clean package -DskipTests
```

4. Run:

```bash
java -jar songzhi-admin/target/songzhi-admin-4.3.0-exec.jar
# Or run the bootstrap class in songzhi-admin during development
```

5. Default service URL: `http://localhost:8080/songzhi-admin` (port per application.yml).

#### Agent Configuration

`songzhi.agent.*` section in `application.yml`:

```yaml
songzhi:
  agent:
    llm: mock            # mock = built-in keyword-rule fallback | remote = real LLM (SPI extension)
    confirm-expire-minutes: 15   # confirmation card timeout (minutes)
    prompt-publish-hit-rate: 90  # prompt gray-release threshold (hit rate %)
    brief-cron: "0 30 8 * * ?"   # daily brief generation time (08:30 every day)
    asr:
      mode: mock         # mock = not connected (explicit message) | http = HTTP transcription service
      url: ''            # transcription service URL (audio in, text out)
      app-key: ''        # optional auth header
      text-field: text   # response text field (dot-notation supported)
```

- LLM: implement the `LlmOrchestrationService` SPI to plug in a real LLM; in mock mode intent parsing (15 intents), time-range parsing (today/this week/last month/last N days) and keyword extraction all work, and LLM failures degrade naturally.
- ASR: implement the `AsrService` SPI, or set `mode=http` to point to any HTTP transcription service (e.g. self-hosted Whisper / Funasr gateway — PII never leaves your network).
- Tool registry: `agent_tool_config` table; on startup `AgentToolSeeder` idempotently registers the default 20 tools. Risk level (1 low / 2 medium / 3 high) determines the execution policy.

#### Core Mechanisms

- **Approval triple**: `approval_status / process_instance_id / current_approver`, written back uniformly by `ApprovalTripleHelper` + `CrmApprovalListener` (Flowable `PROCESS_COMPLETED`); business services must not update the DB on their own.
- **Data permission**: `@CrmDataScope` three-level filtering (own / dept & sub-depts / all), injecting SQL conditions on `owner_id` / `dept_id`; the agent forwards requests to standard CRM APIs under the user's own identity, so unauthorized access is rejected at the CRM layer.
- **Audit**: agent write operations carry the `X-Agent-Log-Id` header; `AgentTraceInterceptor` captures it and `AgentTraceHolder` fills back the `agent_log_id` column in `CrmCrudServiceImpl.save`, making "business data → original utterance" replayable.

#### Directory Structure (key parts)

```
songzhi-crm/src/main/java/com/songzhi/modules/crm/
  ├── lead/            # leads (scoring, one-click convert, 48h recycle job)
  ├── campaign/        # marketing campaigns (budget approval, ROI)
  ├── customer/        # customers (360 view, merge, churn warning)
  ├── opportunity/     # opportunities (stage flow, funnel, loss attribution)
  ├── product/         # products & discount policies
  ├── quotation/       # quotations (versions, convert to order)
  ├── order/           # sales orders (delivery, returns)
  ├── contract/        # contracts & receivable plans
  ├── aftersales/      # after-sales tickets (SLA job, NPS feedback)
  ├── performance/     # performance targets & ranking
  ├── competitor/      # competitors
  ├── schedule/        # schedules
  ├── dashboard/       # workbench / board / report aggregation
  └── common/          # CrmCrudServiceImpl base, approval utils, data scope

songzhi-agent/src/main/java/com/songzhi/modules/agent/
  ├── llm/             # LlmOrchestrationService SPI, MockLlmService, EntityAligner, AsrService
  ├── tool/            # ToolRegistry, ToolExecutor, RiskPolicyExecutor, AgentToolSeeder
  ├── appapi/          # app-side chat/SSE/confirm/brief/ASR endpoints
  ├── brief/           # daily brief
  ├── chatlog/         # audit logs
  ├── prompt/ kb/ eval/ # prompts / knowledge base / evaluation
  └── config/          # AgentProperties
```

#### Contributing

1. Fork this repository
2. Create a `feat_xxx` branch
3. Commit code (follow the existing package structure and framework conventions: unified response wrapper, MyBatis-Plus logical delete `is_deleted`, camelCase entity mapping)
4. Open a Pull Request

中文文档：见 [README.md](README.md)