From e84e3dd99d2df058f00ba4a544cf148d2118ae38 Mon Sep 17 00:00:00 2001 From: Junjie <fallin.jie@qq.com> Date: 星期四, 09 四月 2026 22:52:16 +0800 Subject: [PATCH] #ai --- CLAUDE.md | 93 ++++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 93 insertions(+), 0 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..340b001 --- /dev/null +++ b/CLAUDE.md @@ -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鈫扴ervice鈫扢apper鈫扻ML 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" -- Gitblit v1.9.1