eb-service-api/CLAUDE.md

CLAUDE.md

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

Project Overview

eb-service-api (易借消息服务) — multi-module Java Spring Boot API service providing AI/ML capabilities (OCR, face recognition, image audit, etc.) via REST APIs. Integrates with Alibaba Cloud, Tencent Cloud, and Baidu AI services.

Tech Stack

• Core: Java 8 + Spring Boot 2.6.3 + Spring Cloud Finchley.SR1
• Data: MySQL + MyBatis-Plus 3.4.3 + Druid connection pool
• Cache: Redis (Jedis client)
• Messaging: RabbitMQ (manual ACK)
• Config: Nacos (service discovery + config center)
• Docs: Knife4j/Swagger 2.6.1
• Tools: Lombok 1.18.24 + Hutool 5.8.25 + Fastjson 1.2.75 + OkHttp 4.2.0
• AI SDKs: Alibaba Cloud (face, OCR, image audit, object detection, etc.) + Tencent Cloud face + Baidu AI
• Deploy: Docker + Kubernetes (Jenkins CI/CD)

Build Commands

# Build all modules
mvn clean package -DskipTests

# Build single module with dependencies
mvn clean package -pl api-web/api-interface -am -DskipTests

# Build specific web module
mvn clean package -pl api-web/api-admin -am -DskipTests
mvn clean package -pl api-web/api-job -am -DskipTests
mvn clean package -pl api-gateway -am -DskipTests

Run Services

Each service is a separate Spring Boot application:

Service	Port	Main Class	Description
api-interface	8888	com.heyu.api.ApiUserApiApplication	User-facing API
api-admin	8899	com.heyu.api.admin.http.api.ApiAdminHttpApiApplication	Admin API
api-job	8877	com.heyu.api.job.api.ApiJobApiApplication	Scheduled jobs
api-gateway	8080	com.heyu.api.gateway.GatewayApplication	API Gateway (Zuul)

# Example: run api-interface in dev mode
java -jar api-web/api-interface/target/api-interface.jar --spring.profiles.active=dev

Profiles: dev, pre, online. Config split between local bootstrap.yml/bootstrap-{profile}.yml and Nacos config center.

Module Structure

eb-service-api (parent pom, groupId: com.lz.eb)
├── api-common          # Shared annotations (@Describe, @AppRealyLogin, @AdminNotNeedLogin)
├── api-mapper          # Data layer: entities, DAOs, services, MyBatis XML mappers, utils, constants
├── api-third           # Third-party integrations (Alibaba Cloud AI, Tencent, Baidu, OSS)
├── api-gateway         # Zuul API gateway with Redis rate limiting
├── api-web
│   ├── api-interface   # User-facing REST controllers + RabbitMQ listeners
│   ├── api-admin       # Admin REST controllers
│   └── api-job         # Scheduled tasks & job listeners

Module Dependencies

api-web/* → api-mapper (no dependency on api-web)
api-web/* → api-third → api-mapper
api-web/* → api-common

Architecture Patterns

Controller Layer

• All controllers extend BaseController (Baidu API integration + common helpers)
• Organized by AI domain: controller/face/, controller/ocr/, controller/imageaudit/, controller/bankcard/, etc.
• URI prefix convention:
  • App-facing: /app/*
  • Merchant-managed: /mm/*

AOP

• LogAop — @Around on all @RestController/@Controller methods. Handles:
  • Request/response logging (with trace ID)
  • Authentication (token validation, account info)
  • Tencent Cloud auth header validation (X-TCloudMarket-Custom-AuthConfig)
  • @NotIntercept annotation bypass
• ZhenZhenLogAop — Additional logging aspect

Authentication Annotations

Annotation	Location	Purpose
@AppRealyLogin	api-common	Endpoint requires real user login
@AdminNotNeedLogin	api-common	Admin endpoint skips authentication
@EbAuthentication	api-mapper	Custom auth bypass
@NotIntercept	api-mapper	Skip LogAop interception
@QPS	api-mapper	Rate limiting
@CacheResult	api-mapper	Result caching
@Describe	api-common	API method description

API Response

Unified response class R<T> (com.heyu.api.data.utils.R):

// Structure: { code, msg, data, traceId }
R.ok()                       // success with no data
R.ok().setData(result)       // success with data
R.error("error message")     // failure
R.error(RespCode.FAILED)     // failure with code

Third-party wrapper ApiR<T> (com.heyu.api.data.utils.ApiR):

ApiR.setData(resp)           // success
ApiR.error("error message")  // failure

Data Layer (api-mapper)

Package com.heyu.api.data:

Path	Purpose
entity/{domain}/	MyBatis-Plus entity classes
dao/{domain}/	MyBatis mapper interfaces
service/{domain}/	Service interfaces
service/impl/{domain}/	Service implementations
mapper/{domain}/*Mapper.xml	MyBatis XML mappings
constants/	ApiConstants, RedisConstans
utils/	RedisUtils, Base64Utils, DateUtils, etc.
dto/	DTOs including RespCode

MyBatis-Plus config:

• Mapper scan: com.heyu.api.data.**.dao
• Entity scan: com.heyu.api.data.**.entity
• XML locations: classpath*:mapper/**/*Mapper.xml,classpath*:mapper/**/*Dao.xml
• Soft delete: logic-delete-value: -1, logic-not-delete-value: 0
• Camel case mapping enabled
• ID type: AUTO (database auto-increment)

RabbitMQ Listeners

Listeners in com.heyu.api.listener (api-interface) and com.heyu.api.job.api.listener (api-job):

Listener	Purpose
VVUrlQueueSimpleRabbitListener	URL statistics logging
CreateDataQueueSimpleRabbitListener	Data creation processing
DelaySimpleRabbitListener	Delayed message handling
PostCodeQueueSimpleRabbitListener	Postal code processing
SendDingDingQueueSimpleRabbitListener	DingTalk notifications
AccountQueueSimpleRabbitListener	Account amount processing

All use manual ACK (channel.basicAck()) and @RabbitHandler + @RabbitListener.

Queue names configured in bootstrap.yml under eb.config.rabbitQueue.

Third-Party Integrations (api-third)

Package	Service
alibaba/	Alibaba Cloud AI (face, OCR, image audit, object detection, image enhancement, goods recognition)
tencent/	Tencent Cloud face recognition (FaceID SDK)
baidu/	Baidu AI (token cached in Redis, accessed via BaseController)
oss/	Alibaba Cloud OSS file storage
jsapi/	WeChat Pay JSAPI integration

Code Standards

Naming Conventions

• Entity: no special suffix, plain class names (e.g., User, VvAllData)
• DAO/Mapper: XxxDao interface + XxxDao.xml XML mapping
• Constants: ApiConstants (general), RedisConstans (Redis key prefixes + TTL)
• Utils: XxxUtils (e.g., RedisUtils, DateUtils, Base64Utils)

Redis

• Key prefix constants in RedisConstans (e.g., AI::TYPE::info::, device::info::)
• TTL constants in seconds: ONE_DAY, ONE_HOUR, SECOND_OF_ONE_7_DAY, etc.
• Always set expiration via RedisUtils.set(key, value, expire)

Logging

• Use @Slf4j (Lombok)
• Logback config per profile: log/logback-{profile}.xml
• Trace ID via MDC (logid or X-B3-TraceId from Spring Cloud Sleuth)
• Key fields in logs: className#methodName, IP, URI

Error Handling

• R.error(msg) for API response errors
• ApiR.error(msg) for third-party call errors
• RespCode enum: SUCCESS("200"), FAILED("400")
• Gateway: GatewayExceptionHandler for reactive error handling

Environment

• JDK 8 (source/target 1.8)
• Maven 3.6+
• MySQL 5.7+ (Druid pool)
• Redis 5.0+
• RabbitMQ 3.8+
• Nacos 2.x (service discovery + config center)

Deployment

Docker + Kubernetes via Jenkins CI/CD:

• Base image: alpine-jdk11:3.0
• Health check: /actuator/health
• Resource limit: 1024Mi memory
• Log volume: /home/heyu/logs → NFS /nfs/data/heyu/api/logs
• Rolling update: 50% max surge/unavailable