# CLAUDE.md — dc-solon-gateway 项目说明

> 本文件是 Claude Code 在本项目的工作指引。项目代码、约定、关键决策均记录于此。

## 项目概述

**dc-solon-gateway** 是数据中心转发网关，作为中转服务器收敛健康设备（手表）的 token 获取请求，规避 HTTP 爆破风控误报。

### 背景
健康设备众多且共用同一接口账号（watchUser），设备各自向源服务器（jeecg）请求 `/sys/watchUserLogin` 换 token。因 RSA 加密密码每次密文不同，短时间高频率访问被 WAF 误判为 HTTP 爆破。

### 解决方案
旧服务器域名指向本中转服务器：
- `/sys/watchUserLogin` → **本地处理**：解密验证设备密码（防伪造）+ 单飞换 token + Redis 缓存
- 其余业务接口 → **手动 HttpUtils 透传**至源服务器 `http://10.10.10.228:29999`
- token 失效三重自愈：10秒主动探活 + 预过期刷新 + 业务接口 401 被动兜底
- **全局 CORS**：CorsFilter 处理跨域（设备后台跨域访问网关），OPTIONS 预检直接短路返回

## 技术栈

| 组件 | 选择 |
|------|------|
| 框架内核 | Solon Cloud Gateway（提供 Vert.x HTTP Server + Solon 内核） |
| 透传 | 本地通配 Controller（`@Mapping("/**")`）+ HttpUtils 手动透传 |
| HTTP 客户端 | `solon-net-httputils`（`HttpUtils.http(url).exec(method)`） |
| Redis | `redisx`（基于 Jedis，复用源服务器 228:6379 db11） |
| 定时任务 | `solon-scheduling-simple`（`@Scheduled` + `@EnableScheduling`） |
| JSON | Solon 内置 `snack4`（`org.noear.snack4.ONode`，不使用 fastjson，规避其 0day 漏洞） |

## 关键约定（开发必须遵守）

### 1. 文件路径
- 所有文件操作必须用**完整绝对 Windows 路径**（如 `E:\yixiongspace\dc-solon-gateway\src\...`）

### 2. 代码注释
- 所有注释用**简体中文**（类/方法/行内注释）
- 标识符（类名/方法名/变量名）用英文

### 3. Solon 注意事项（踩过的坑，务必牢记）
- **不要用 `solon.cloud.gateway.routes` 路由透传**：其 `Path=/**` 会覆盖本地 Controller，使 watchUserLogin 无法本地处理。本项目用本地通配 Controller 手动透传。
- **定时任务用 `@Scheduled`**（非 `@Async`），启动类加 `@EnableScheduling`，注解包 `org.noear.solon.scheduling.simple.annotation.Scheduled`。
- **Redis 用 redisx**（非 solon-redis-jedis），API 为会话式 `getBucket().store/get` + `open(session -> session.key(k).delete())`。
- **HTTP 响应状态码**用 `response.code()`（非 `.status()`），JSON body 用 `bodyOfJson()`。

### 4. RSA 加密
- 中转的 `RsaEncryptUtil` 必须与源服务器 `RSAEncryptUtils` 对齐：`Cipher.getInstance("RSA")` = `RSA/ECB/PKCS1Padding`，公钥 X.509、私钥 PKCS#8、明文 UTF-8、密文 Base64。
- 源服务器代码位置：`E:\giteaspace\data-center-boot-spring3\jeecg-boot-base-core\...\RSAEncryptUtils.java`

### 5. 单飞机制
- 中转为**单实例**，单飞用本地 `synchronized` 双检锁（无需 Redis 分布式锁）。
- 探活失效/被动401 后必须**先清缓存再换 token**（`forceRefresh`），否则命中旧缓存返回失效 token 死循环。

## 配置

配置采用 **.env + 占位符** 机制（类似 dotenv）：

- **`.env`**（项目根目录，**不入库**）：存储真实敏感值（密码、私钥、Redis、源服务器地址），格式 `KEY=VALUE`
- **`.env.example`**（入库）：模板，复制为 `.env` 后填真实值
- **`app.yml`**（注意：Solon 默认读 `app.yml`，非 `application.yml`）：用 `${KEY}` 占位符引用 .env 变量
- **`EnvLoader`**：`Solon.start` 前调用，读取 `.env` → `System.setProperty` 注入系统属性，使 yml 占位符解析
- **`GatewayConfig` / `RedisConfig`**：双保险读取（先 Solon.cfg，取不到则 fallback `System.getProperty`）

> .env 不入 git（见 `.gitignore`）。修改敏感配置只改 `.env`，不改 yml。
> 运行：`java -jar dc-solon-gateway.jar`（从项目根/jar同目录启动，确保能读到 `.env`）。

## 相关文档

- 方案设计与开发进度：`E:\data\ob_data\myob\11 健康长庆\数据中心转发网关优化\数据中心转发网关优化.md`
- 项目记忆：`.claude/memory/`（索引见 `.claude/memory/MEMORY.md`）

## 待联调验证（测试环境）

以下 API 细节在编码时基于文档/训练数据，需真实环境验证：本地路由优先级、redisx 注入与删除方法、Solon Context API、@Body 注解、redisx 版本兼容性。详见 OB 文档「开发记录」章节。