# snake

**Repository Path**: rambox/snake

## Basic Information

- **Project Name**: snake
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-08-27
- **Last Updated**: 2026-09-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# snake 微服务体系

> 统一认证中心 + 业务中台框架的 Java 微服务脚手架。
> 本文件面向未来维护者与 AI 协作者，记录项目定位、模块地图与必须遵守的全局约定。

---

## 1. 项目定位

| 层级 | 说明 |
| :--- | :--- |
| `framework/*` | 业务无关的基础框架模块，通过 Maven 依赖被各微服务复用 |
| `microservice/*` | 独立部署的微服务，当前聚焦 `ms-uaa` 统一认证中心 |
| `deploy/` | Nacos 配置即代码方案、发布脚本与环境相关配置 |
| `snake-dependencies` | 根 BOM，统一管理 Spring Boot 4.x、Spring Cloud、Spring Authorization Server、MyBatis-Plus 等版本 |

核心设计原则：

1. **框架模块引入即生效，不引入零负担**：全部通过 `META-INF/spring/AutoConfiguration.imports` 自动装配，禁止 `@ComponentScan` 依赖。
2. **约定优于配置**：包名、错误码、Redis Key、JWT Claims、ORM 返回类型等硬约束写入代码规则（ArchUnit）与文档。
3. **标准与自研双轨**：自有客户端走轻量自研端点；第三方接入走标准 OAuth2.1 / OIDC 端点。

---

## 2. 模块地图

### 2.1 framework 模块

| 模块 | 坐标 | 作用 | 关键入口 |
| :--- | :--- | :--- | :--- |
| `framework/web` | `org.snake.framework:web` | 统一响应 `Result`、业务异常 `BusinessException`、全局异常处理、JWT 签发、`@CurrentUser` 解析 | `Result`, `BusinessException`, `JwtTokenIssuer`, `CurrentUser` |
| `framework/redis` | `org.snake.framework:redis` | 统一 Redis 访问门面：强制 TTL、JSON 序列化、统一异常、慢操作观测 | `RedisOps`, `ReactiveRedisOps`, `RedisKeys` |
| `framework/orm` | `org.snake.framework:orm` | MyBatis-Plus 工程化封装 + ArchUnit 规则集 | `BaseEntity`, `SnakeBaseMapper`, `SnakeService`, `PageQuery`, `PageResult`, `OrmRules` |
| `framework/log` | `org.snake.framework:log` | 统一日志模板 `logback-base.xml`、TraceId 兜底 | `logback-base.xml`, `TidConverter` |
| `framework/swagger` | `org.snake.framework:swagger` | SpringDoc 自动装配、网关聚合 servers 指向 | `ApiDocAutoConfiguration` |
| `framework/security` | `org.snake.framework:security` | 资源服务器基座：JWT 验签（官方 starter）、角色映射、`@PreAuthorize` 总开关、统一 401/403、`@CurrentUser` 从 JWT 取身份 | `ResourceServerAutoConfiguration`, `ResourceServerMethodSecurityAutoConfiguration`, `JwtAuthoritiesConverter`, `JwtPrincipalResolver` |
| `framework/dbm` | `org.snake.framework:dbm` | 数据库迁移工具模块（详见模块 README） | — |
| `framework/common` | `org.snake.framework:common` | 公共常量/工具（规划中） | — |
| `framework/concurrent` | `org.snake.framework:concurrent` | 并发工具（规划中） | — |
| `framework/mq` | `org.snake.framework:mq` | 消息队列封装（规划中） | — |

### 2.2 microservice 模块

| 服务 | 作用 | 状态 |
| :--- | :--- | :--- |
| `ms-uaa` | 统一认证中心：OIDC / OAuth 2.1 授权服务器（Token 签发、客户端注册、用户体系、SSO），端口 9201。**2026-09 起从 0 分阶段搭建**，进度见 `microservice/ms-uaa/doc/spec.md` | 开发中（阶段 0 已完成：可签发 JWT + 公布 JWKS） |
| `ms-market-collector` | 行情采集：itick 数据源适配，七品类（Symbol/Stock/Indices/Future/Fund/Forex/Crypto）REST 行情查询，端口 9202 | 开发中 |
| `ms-pay-engine` | 支付引擎 | 占位 |
| `ms-matching-engine` | 撮合引擎 | 占位 |

---

## 3. 全局硬约束（AI 实现功能前必须先读）

### 3.1 版本与构建

- **Spring Boot 4.1 / Spring Cloud 2024.x**：注意 Boot 4.x 与 3.x 的包名/类名差异（如 Jackson 3 `tools.jackson.*`、Redis 自动装配类改名）。
- **Maven 本地仓库**：`D:\maven-repo`（由 `settings.xml` 指定），framework 模块安装后查这里。
- **版本属性**：
  - `${revision}` 只表达本 reactor 自身版本。
  - 跨 reactor 的 framework 依赖用 `${framework.version}`（microservice 父 pom 与 gateway pom 各定义一处）。
- **framework 父 pom** 必须带 `flatten-maven-plugin`（resolveCiFriendliesOnly），否则 `${revision}` 安装后消费方无法解析。

### 3.2 框架 Bean 注册规约

- 框架模块 Bean 必须使用 **`@Bean` + `AutoConfiguration.imports`**，禁止 `@Component`。
- 必须配合条件注解：`@ConditionalOnClass`、`@ConditionalOnMissingBean`、`@ConditionalOnBean`。
- 框架核心类应保持纯 POJO（便于单元测试），Spring 装配在 AutoConfiguration 中完成。

### 3.3 错误码

统一使用 `framework/web` 的 `Result`：

| 场景 | 业务码 |
| :--- | :--- |
| 成功 | 200 |
| 参数校验失败 | 400001 |
| 验证码错误/过期 | 400002 |
| 用户名或密码错误 | 400003 |
| 用户被锁定 | 400004 |
| 用户被禁用/注销 | 400005 |
| Token 无效 | 401001 |
| Token 已过期 | 401002 |
| Refresh Token 无效/已轮转 | 401003 |
| 会话已失效 | 401004 |
| 访问拒绝 | 403001 |
| 请求过于频繁 | 429001 |
| 服务端内部错误 | 500000 |

### 3.4 存储分层

| 层级 | 存储 | 数据范围 |
| :--- | :--- | :--- |
| 热态 | Redis | 验证码、限流、登录失败锁定、会话、RefreshToken、IP 黑名单缓存、OAuth2 授权元数据 |
| 冷态主数据 | MySQL | `sys_user`、`sys_client`、社交绑定、MFA、Webhook、IP 黑名单持久化 |
| 冷态审计/历史 | MySQL（可切 ES） | 登录审计、RefreshToken 冷备、会话历史 |

### 3.5 安全基线

- 密码算法：`{bcrypt}`，cost ≥ 12。
- Access Token TTL：Web 默认 **15 分钟**。
- Refresh Token TTL：默认 **30 天**，Redis 存储，只存 SHA-256 哈希。
- 验证码：Redis TTL 2 分钟，**取出即删**。
- 会话吊销：RefreshToken 立即失效；Access Token 不拉黑，靠短 TTL 自然过期。
- 敏感字段不得明文存储。

---

## 4. 新建微服务 checklist

1. 继承 `microservice` 父 pom，引入 `snake-dependencies` BOM。
2. 按需引入 `framework/web`、`framework/redis`、`framework/orm`、`framework/log`、`framework/swagger`。
3. 配置 `spring.application.name`、Nacos discovery/config、数据源、Redis。
4. 创建 `logback-spring.xml`（仅声明 `log.path` 并 `include` `logback-base.xml`）。
5. 业务包结构：`controller / service / mapper / entity / config / common`。
6. 启动类 `@MapperScan("org.snake.microservice.xxx.mapper")`。
7. 若引入 `framework/orm`，必须加 ArchUnit 规则校验（参考 `framework/orm` README §6）。

---

## 5. 关键外部依赖

| 依赖 | 版本/说明 |
| :--- | :--- |
| Nacos | 3.x（本地 dev），配置与发现统一 namespace `{NACOS_NAMESPACE:dev}` |
| MySQL | 8.x，业务表前缀 `sys_` |
| Redis | 7.x， Lettuce 客户端 |
| Sentinel | 规则由 Nacos 下发 |

---

## 6. 文档索引

- 框架能力：`framework/*/README.md`
- 框架使用规范：`openspec/specs/framework-*/spec.md`
- 认证中心路线图（分阶段，从 0 搭建）：`microservice/ms-uaa/doc/spec.md`
- 环境配置发布：`deploy/README.md`
- 项目约定速查：`project_memory.md`（本文档同级）
- 网关设计：`doc/架构设计.md`（顶层）→ `doc/gateway设计.md`（能力/流程）→ `doc/gateway/`（模块拆分）