# iam 身份认证服务

> 版本：0.1（骨架）
> 日期：2026-07-07
> 状态：P2 待交付
> 关联文档：[架构影响地图](../../architecture/004_architecture_impact_map.md)

---

## 1. 模块职责

iam 是身份认证限界上下文，管理 User、Role、Permission 三大聚合。
负责用户注册/登录/登出、JWT RS256 签发与刷新、三层角色模型（系统/组织/临时）分配与校验。
同时对外提供权限列表查询（供 api-gateway 与业务服务缓存）。

---

## 2. 技术栈

| 类别 | 技术 | 版本 | 用途 |
|------|------|------|------|
| 语言 | TypeScript | 5.5+ | 类型安全 |
| 框架 | NestJS | 10.x | 依赖注入、模块化 |
| ORM | Drizzle ORM | 0.31+ | 数据访问 |
| 数据库 | MySQL | 8.x | 用户/角色/权限主库 |
| 缓存 | Redis | 7.x | 权限列表缓存、会话 |
| 密码 | bcrypt | 5.x | 密码哈希 |
| 校验 | Zod | 3.23+ | 运行时校验 |
| JWT | jose | 5.x | RS256 签发与公钥暴露 |

---

## 3. 架构图

```mermaid
graph TB
    BFF[BFF/网关] -->|gRPC| IAM[iam 服务]
    IAM --> USER[UserAggregate]
    IAM --> ROLE[RoleAggregate]
    IAM --> PERM[PermissionAggregate]
    IAM -->[(MySQL)]
    IAM -->[(Redis<br/>权限缓存)]
    IAM -->|JWKS| GW[api-gateway 公钥拉取]
    IAM -.事件.-> K[(Kafka<br/>edu.identity.user.*)]
```

> 待 P2 交付时补充完整的分层架构图（Controller/Application/Domain/Infrastructure）。

---

## 4. 核心流程图

```mermaid
sequenceDiagram
    participant GW as API Gateway
    participant IAM as iam
    participant DB as MySQL
    participant K as Kafka

    GW->>IAM: gRPC Login(username, password)
    IAM->>DB: 查询用户 + bcrypt 校验
    IAM->>IAM: 生成 JWT RS256
    IAM-->>GW: {accessToken, refreshToken}
    IAM->>K: 发布 edu.identity.user.logged_in
```

> 待 P2 交付时补充：刷新令牌流程、权限校验流程、角色分配流程。

---

## 5. 对外契约

- **gRPC 服务**：UserService（Login/Refresh/Logout/Register/GetUserProfile）、RoleService、PermissionService（待 P2 定义 protobuf）
- **HTTP 端点**：`/.well-known/jwks.json` 暴露 RS256 公钥
- **领域事件**：`edu.identity.user.created`、`edu.identity.user.updated`、`edu.identity.role.assigned`

> 待 P2 交付时补充完整 protobuf 定义与事件 schema。

---

## 6. 依赖关系

- **上游**：teacher-bff、student-bff、parent-bff、api-gateway（JWKS 拉取）
- **下游**：MySQL（用户/角色/权限表）、Redis（权限缓存）、Kafka（领域事件）
- **共享包**：shared-proto、shared-ts

---

## 7. 架构约束

1. JWT 必须使用 RS256 非对称签名，私钥仅 iam 持有
2. 密码必须 bcrypt 哈希，禁止明文存储
3. 权限列表缓存 TTL 5 分钟，事件驱动失效
4. 三层角色权限取并集，拒绝权限取交集

> 待 P2 交付时补充完整约束清单。

---

## 8. 架构决策

> 待 P2 交付时补充 ADR 记录，预计包括：RS256 选型、bcrypt 参数、会话管理策略、权限缓存策略。