#ai

Junjie

1 天以前 e84e3dd99d2df058f00ba4a544cf148d2118ae38

#ai

 CLAUDE.md

New file
@@ -0,0 +1,93 @@
# CLAUDE.md

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

## Project Overview

WCS (Warehouse Control System) — Java 17 / Spring Boot 3.5 warehouse automation system controlling stacker cranes (Crn/DualCrn), shuttle cars (RGV), conveyors (Devp), and barcode scanners. Frontend is server-rendered HTML with Vue 2-style inline JS, PixiJS canvas for map visualization, Layui for UI. No separate frontend build pipeline.

## Build & Run

```bash
mvn -q -DskipTests compile           # compile
mvn test                              # all tests (none currently exist under src/test/)
mvn -q -Dtest=SomeTest test           # single test
mvn clean package -DskipTests         # package → target/wcs.war
mvn -q -DskipTests spring-boot:run    # dev run (port 9090, context path /wcs)
```

**Prerequisites:** MySQL 127.0.0.1:3306/db `wcs`, Redis 127.0.0.1:6379, custom framework JAR:
```bash
cd version/lib && mvn install:install-file -Dfile=framework-3.4.0.jar -DgroupId=cn.cool -DartifactId=framework -Dversion=3.4.0 -Dpackaging=jar -DgeneratePom=true
```

**Production:** Deploy `wcs.war` to external Tomcat.

## Architecture

**Entry point:** `src/main/java/com/zy/Boot.java` — `@EnableAsync`, `@EnableScheduling`, scans `com.zy` + `com.core`.

### Java Packages

| Package | Role |
|---------|------|
| `com.zy.asrs` | Business domain — controllers, services, mappers, entities, tasks, planners, WebSocket, domain models |
| `com.zy.core` | Device runtime & scheduling — dispatch, network (real/fake/API), threads, plugins, movement, tracing |
| `com.zy.system` | System management — users, roles, permissions, logging, license, config, scheduled tasks |
| `com.zy.ai` | AI features — LLM routing, prompt templates, MCP server tools, chat storage |
| `com.zy.common` | Common utilities — auth, web helpers, i18n, Excel, annotations |
| `com.core` | Legacy common base — annotations, exceptions, utilities, code generators |

### Frontend

| Path | Content |
|------|---------|
| `src/main/webapp/views/**` | Page directories (watch, ai, basStation, locMast, etc.) |
| `src/main/webapp/static/js/**` | Page scripts — paired by directory name with views |
| `src/main/webapp/components/` | PixiJS components: MapCanvas.js, WatchCrnCard.js, WatchRgvCard.js, etc. |
| `src/main/webapp/static/css/` | Stylesheets |

### Resources

| Path | Content |
|------|---------|
| `src/main/resources/mapper/*.xml` | 31 MyBatis XML mapper files |
| `src/main/resources/sql/*.sql` | SQL migration scripts |
| `src/main/resources/i18n/` | Language packs (zh-CN, en-US) |
| `src/main/resources/application.yml` | Main config (DB, Redis, AI, device, logging) |

## Key Conventions

**Backend chain:** `Controller → Service → ServiceImpl → Mapper.java → mapper/*.xml → Entity/DTO/Param`. Many queries depend on XML SQL — never change only the Java Mapper interface without updating the XML.

**Frontend pattern:** Views in `views/<feature>/` paired with scripts in `static/js/<feature>/`. Keep Vue 2-style inline script writing; do not introduce a new frontend framework or build system.

**Context path:** All frontend paths must include `/wcs` prefix. WebSocket URLs must include `/wcs`.

**Field changes:** When changing a field, sync across: entity class, Mapper interface, XML (resultMap/select/insert/update), parameter objects, return objects, and frontend field names.

**AI config:** LLM routing, prompts, and MCP mount info have migrated to database table `sys_llm_route`. `application.yml` is fallback only — distinguish "database primary config" vs "YAML fallback".

**PixiJS map lifecycle:** `mounted → createMap → connectWs → getMap → createMapData`. Real-time refresh via WebSocket routes `/console/latest/data/crn|dualcrn|station|rgv`. Container hierarchy: `tracksGraphics` (track lines), `shelvesContainer` (shelves), `objectsContainer` (static), `objectsContainer2` (devices).

## Locating Code

```bash
rg -n "关键字" src/main/java src/main/resources src/main/webapp
rg --files src/main/java/com/zy | rg "Controller|Service|Mapper|Task|Thread"
```

By task type:
- **Backend API/logic:** follow the Controller→Service→Mapper→XML chain
- **DB schema/menus/config:** check `src/main/resources/sql/*.sql` + `system/` or `asrs/`
- **Device threads/scheduling:** `core/thread/`, `core/dispatch/`, `core/task/`, `core/network/`, `asrs/task/`
- **Monitor/map/WebSocket:** `views/watch/`, `components/MapCanvas.js`, `asrs/ws/`
- **AI/LLM/MCP:** `ai/controller/`, `ai/service/`, `ai/config/`, `ai/mcp/`

## High-Risk Change Areas

- **Mapper XML:** Watch for missing field mappings, alias mismatches, wrong result types
- **Thread/scheduling logic:** Watch for race conditions, duplicate dispatch, state leaks, dead loops, swallowed exceptions
- **Frontend field changes:** Ensure JSON field names match between backend response and frontend JS
- **Context path code:** Ensure frontend hardcoded paths include `/wcs`
- **Monitor/map logic:** Distinguish "backend data correct but frontend render wrong" vs "frontend display correct but state source wrong"