CLAUDE.md – 头寸管理系统（Position Management System）

项目概述

本项目实现头寸管理功能从现有资管系统（XAMS）中的完全解耦，构建独立的头寸管理系统。系统提供头寸的生成、更新、删除、查询及规则驱动的自动化处理能力，通过标准 REST API 供上游系统调用。

核心目标：高内聚、低耦合、可扩展、可维护，支持平滑迁移。

技术栈（强制）

类别	技术选型	版本/说明
语言	Java	17
框架	Spring Boot	2.7.18
微服务	Spring Cloud	2021.0.8
构建工具	Maven	3.8+，多模块结构
服务注册/配置	Nacos	2021.0.5.0（本地可禁用）
API网关	Spring Cloud Gateway	3.x（生产环境）
ORM	MyBatis-Plus	3.5.5（含分页插件、乐观锁插件）
数据库	Oracle	19c（生产）/ XE（开发）
连接池	Druid	1.2.20，自带 SQL 监控页面 `/druid`
缓存	Redis 6.x（Lettuce）+ Caffeine 3.1.8（本地缓存）	本地可禁用 Redis
消息队列	RocketMQ	4.9.x（spring-boot-starter 2.2.3）
认证授权	Sa-Token	1.37.0，无状态 + 拦截器，本地可关闭
接口文档	SpringDoc OpenAPI 3	1.7.0，`/swagger-ui.html`
对象映射	MapStruct	1.5.5.Final，编译期生成
监控	Spring Boot Actuator + Micrometer Prometheus	`/actuator/health`、`/actuator/prometheus`
日志	Logback + SLF4J	生产配合 ELK 输出 JSON 格式
参数校验	JSR-303（spring-boot-starter-validation）	`@Valid` + `@Validated`

本地开发：所有依赖从阿里云 Maven 镜像（https://maven.aliyun.com/repository/public）下载，本地仓库路径 D:\maven-repository（见 ~/.m2/settings.xml），不依赖内网 Nexus。

项目模块结构（Maven Multi-Module）

position-management-system/
├── pom.xml                      # 父POM，统一依赖版本管理
├── position-common/             # 公共组件：Result/ResultCode、异常体系、CORS、Sa-Token配置
├── position-domain/             # 领域模型：实体、值对象、仓储接口、领域服务接口、领域事件
├── position-infrastructure/     # 基础设施：持久化实现、MyBatis-Plus配置、Druid配置、缓存实现
├── position-application/        # 应用层：应用服务实现（编排领域服务）、命令/查询对象、DTO
├── position-api/                # 接口层：REST Controller、OpenAPI配置、多环境配置
├── position-scheduler/          # 定时任务：基于 Spring Scheduled，执行批处理、数据核对、缓存刷新
└── position-admin/              # （可选）管理后台：提供简单的配置界面，初期可省略

框架规范（强制遵守）

1. 统一返回结构

所有 Controller 接口必须返回 Result<T>（位于 position-common）：

Result.success(data);                    // 成功带数据
Result.success();                        // 成功无数据
Result.fail(ResultCode.DATA_NOT_FOUND);  // 失败指定码

响应 JSON 结构：

{ "code": 200, "message": "操作成功", "data": {}, "success": true }

2. 异常处理

业务异常抛 BusinessException(ResultCode, message)，由 GlobalExceptionHandler 统一捕获
参数校验异常（@Valid、@Validated）自动转为 Result.fail(PARAM_INVALID, ...)
Sa-Token 未登录/无权限异常自动转为 401/403 Result
禁止在 Controller 中 try-catch 后自行返回

3. 多环境配置（Spring Profile）

配置文件位于 position-api/src/main/resources/：

application.yml — 公共配置（端口、Druid 连接池、MyBatis-Plus、Sa-Token、SpringDoc、Actuator）
application-local.yml — 本地开发：禁用 Nacos/Redis/RocketMQ，关闭认证拦截
application-dev.yml — 开发环境：连 Nacos/Redis/RocketMQ，开启认证拦截
application-prod.yml — 生产环境：连接生产中间件，开启认证与监控

启动切换：

# 本地（默认）
mvn -pl position-api spring-boot:run
# 指定环境
java -jar position-api.jar --spring.profiles.active=dev

4. 数据库访问

实体继承 MyBatis-Plus 体系，使用 @TableName、@TableId、@Version、@TableLogic 注解
Mapper 继承 BaseMapper<T>，复杂查询写 XML（position-infrastructure/src/main/resources/mapper/）
分页统一使用 Page<T>（MyBatis-Plus 分页插件已配置，Oracle 方言）
逻辑删除字段：deleted（0 未删除，1 已删除，已在全局配置）

5. 认证授权（Sa-Token）

本地开发：sa-token.enable-auth=false，所有接口放行
dev/prod：sa-token.enable-auth=true，/api/** 需登录
放行路径：/api/health、/api/auth/login、接口文档、Druid 监控
Token 通过 Authorization 请求头传递

6. 接口路径规范

所有业务接口统一前缀 /api/，如 /api/positions、/api/positions/{id}
健康检查：GET /api/health
接口文档：/swagger-ui.html（本地与 dev 环境）

7. 监控端点

健康检查：GET /actuator/health
Prometheus 指标：GET /actuator/prometheus
Druid SQL 监控：/druid/index.html（账号 admin/admin）

本地运行

前置条件

JDK 17（当前配置 D:\JDK）
Oracle 19c/XE，监听 localhost:1521，SID ORCL，账号 system/Root123456
Maven 本地仓库：D:\maven-repository（已在 ~/.m2/settings.xml 配置）

构建与启动

$env:JAVA_HOME = "D:\JDK"
$env:Path = "$env:JAVA_HOME\bin;$env:Path"
mvn clean install -DskipTests -B
mvn -pl position-api spring-boot:run

验证

健康检查：GET http://localhost:8080/api/health
接口文档：http://localhost:8080/swagger-ui.html
Druid 监控：http://localhost:8080/druid/index.html
Actuator：http://localhost:8080/actuator/health

编码约定

实体类使用 Lombok @Data；DTO ↔ Entity 转换使用 MapStruct
包结构：com.example.position.{模块}.{分层}
日志使用 SLF4J（@Slf4j），关键业务操作记录 INFO，异常记录 ERROR
所有对外接口使用 @Tag、@Operation 注解生成文档

CLAUDE.md 6.9 KB Permalink Lịch sử Raw