# 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）

```text
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`）：
```java
Result.success(data);                    // 成功带数据
Result.success();                        // 成功无数据
Result.fail(ResultCode.DATA_NOT_FOUND);  // 失败指定码
```
响应 JSON 结构：
```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` — 生产环境：连接生产中间件，开启认证与监控

启动切换：
```bash
# 本地（默认）
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` 配置）

### 构建与启动
```powershell
$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` 注解生成文档