0a71b02e04
NestJS (6 services): implement @RequirePermission decorator with SetMetadata+Reflector, register APP_GUARD globally, fix as assertions to type guards, add explicit return types, fix import type for express, fix /metrics implicit any, replace native Error with ApplicationError, remove typeorm remnants, register LifecycleService. teacher-bff: add logger, ApplicationError, GlobalErrorFilter, forward real userId to downstream, log downstream failures, migrate health controller to shared/health. Go (2 services): interface to any, doc comments, CORS dev whitelist, JWT secret fail-fast, push-gateway internal API auth, metrics and readyz endpoints, remove dead code. Python (2 services): lifespan return type, dev_mode to bool, data-ana APIRouter, ai POST body model, ClickHouse async wrapping.
719 lines
37 KiB
Markdown
719 lines
37 KiB
Markdown
# 模块架构设计文档 — iam
|
||
|
||
> AI：ai02（TS / 身份认证）
|
||
> 阶段：阶段 2 交付物
|
||
> 日期：2026-07-09
|
||
> 关联：[阶段 1 理解确认书](./01-understanding.md)、[004 架构影响地图](../../../docs/architecture/004_architecture_impact_map.md)、[pending-features P2](../../../docs/architecture/roadmap/pending-features.md)
|
||
> 状态：待 coord 交叉审查
|
||
|
||
---
|
||
|
||
## 1. 模块内部分层图
|
||
|
||
### 1.1 调用链总览
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph Client["客户端 / Gateway / BFF"]
|
||
Req[HTTP 请求<br/>带 x-user-id / x-user-roles 头]
|
||
end
|
||
|
||
subgraph NestJS["iam 服务（NestJS）"]
|
||
direction TB
|
||
MW[AuthMiddleware<br/>❌ 当前未注册，P2 仍走 header 直读]
|
||
Guard[PermissionGuard<br/>APP_GUARD 全局守卫]
|
||
Filter[GlobalErrorFilter<br/>全局异常过滤器]
|
||
|
||
subgraph Controllers["Controller 层"]
|
||
IamCtl[IamController<br/>/iam/register, login, refresh, me]
|
||
RbacCtl[RbacController<br/>/iam/viewports, permissions, roles]
|
||
UserCtl[UserController<br/>P2 新增: 用户 CRUD]
|
||
RoleCtl[RoleController<br/>P2 新增: 角色 CRUD]
|
||
ViewportCtl[ViewportController<br/>P2 新增: 视口 CRUD]
|
||
JwksCtl[JwksController<br/>P2 新增: RS256 公钥暴露]
|
||
end
|
||
|
||
subgraph Services["Application Service 层"]
|
||
IamSvc[IamService<br/>认证编排]
|
||
RbacSvc[RbacService<br/>RBAC 编排]
|
||
UserSvc[UserService<br/>用户领域编排]
|
||
CacheSvc[PermissionCacheService<br/>Redis 权限缓存]
|
||
end
|
||
|
||
subgraph Domain["Domain 层（P2 轻量）"]
|
||
UserEntity[UserEntity<br/>聚合根]
|
||
RoleEntity[RoleEntity<br/>聚合根]
|
||
end
|
||
|
||
subgraph Repo["Repository 层"]
|
||
IamRepo[IamRepository<br/>Drizzle 查询]
|
||
RbacRepo[RbacRepository<br/>Drizzle 查询]
|
||
end
|
||
|
||
subgraph Outbox["Outbox 模块"]
|
||
OutboxTbl[(iam_outbox 表)]
|
||
Relay[OutboxRelayWorker<br/>后台轮询 + Kafka 投递]
|
||
end
|
||
|
||
subgraph Infra["基础设施"]
|
||
Db[(MySQL<br/>iam_db)]
|
||
Redis[(Redis<br/>权限缓存 + token 黑名单)]
|
||
Kafka[(Kafka<br/>edu.identity.user.* topic)]
|
||
end
|
||
end
|
||
|
||
Req --> MW
|
||
MW --> Guard
|
||
Guard --> Controllers
|
||
Controllers --> Services
|
||
Services --> Domain
|
||
Services --> Repo
|
||
Services --> CacheSvc
|
||
Repo --> Db
|
||
CacheSvc --> Redis
|
||
Services --> OutboxTbl
|
||
OutboxTbl --> Relay
|
||
Relay --> Kafka
|
||
Controllers -.异常.-> Filter
|
||
```
|
||
|
||
### 1.2 中间件 / Guard / Filter 拦截顺序
|
||
|
||
```
|
||
请求进入
|
||
→ AuthMiddleware（P2 仍不注册，Controller 直读 header）
|
||
→ PermissionGuard（APP_GUARD，DEV_MODE 旁路 + DB 驱动权限校验）
|
||
→ Controller Handler（Zod 校验 body）
|
||
→ Application Service（业务编排）
|
||
→ Repository（Drizzle 查询）
|
||
→ 异常抛出
|
||
→ GlobalErrorFilter（统一兜底，注入 traceId）
|
||
→ 响应返回
|
||
```
|
||
|
||
### 1.3 目录结构（P2 目标态）
|
||
|
||
```
|
||
services/iam/src/
|
||
├─ iam/ # 限界上下文：认证
|
||
│ ├─ iam.controller.ts # 认证端点（register/login/refresh/me/logout）
|
||
│ ├─ iam.service.ts # 认证编排
|
||
│ ├─ iam.repository.ts # 用户/refresh_token 查询
|
||
│ ├─ iam.schema.ts # users / refresh_tokens 表
|
||
│ ├─ iam.dto.ts # Zod schema
|
||
│ └─ domain/
|
||
│ └─ user.entity.ts # UserEntity 聚合根（P2 新增）
|
||
├─ rbac/ # 限界上下文：RBAC（P2 从 iam/ 拆出）
|
||
│ ├─ rbac.controller.ts # 角色/权限/视口查询端点
|
||
│ ├─ role.controller.ts # 角色 CRUD（P2 新增）
|
||
│ ├─ permission.controller.ts # 权限点 CRUD（P2 新增）
|
||
│ ├─ viewport.controller.ts # 视口配置 CRUD（P2 新增）
|
||
│ ├─ rbac.service.ts # RBAC 编排
|
||
│ ├─ rbac.repository.ts # 角色/权限/视口查询
|
||
│ ├─ rbac.schema.ts # roles / permissions / role_permissions / role_viewports 表
|
||
│ └─ domain/
|
||
│ └─ role.entity.ts # RoleEntity 聚合根（P2 新增）
|
||
├─ jwks/ # 限界上下文：JWT 公钥暴露（P2 新增）
|
||
│ ├─ jwks.controller.ts # GET /iam/.well-known/jwks.json
|
||
│ ├─ jwks.service.ts # 密钥加载 + JWK Set 生成
|
||
│ └─ jwks.repository.ts # 密钥元数据持久化（可选）
|
||
├─ cache/ # 限界上下文：Redis 缓存（P2 新增）
|
||
│ ├─ permission-cache.service.ts # getEffectivePermissions 缓存
|
||
│ └─ token-blacklist.service.ts # refresh token 黑名单
|
||
├─ outbox/ # Outbox 模式（P2 新增）
|
||
│ ├─ outbox.schema.ts # iam_outbox 表
|
||
│ ├─ outbox.publisher.ts # 写入 outbox（事务内）
|
||
│ └─ outbox.relay-worker.ts # 后台轮询 + Kafka 投递
|
||
├─ config/
|
||
│ ├─ database.ts # Drizzle 池（已有）
|
||
│ ├─ redis.ts # Redis 客户端（P2 新增）
|
||
│ ├─ jwt.ts # RS256 密钥加载（P2 新增）
|
||
│ └─ env.ts # 环境变量（P2 扩展）
|
||
├─ middleware/
|
||
│ ├─ auth.middleware.ts # 保留（P2 仍不注册）
|
||
│ └─ permission.guard.ts # 改造：DB 驱动 + 缓存
|
||
├─ shared/
|
||
│ ├─ errors/ # 已有
|
||
│ ├─ health/ # 已有
|
||
│ ├─ lifecycle/ # 改造：关闭顺序 HTTP→Kafka→Redis→DB
|
||
│ └─ observability/ # 已有
|
||
├─ app.module.ts # 改造：imports 新增 OutboxModule、CacheModule、JwksModule
|
||
└─ main.ts # 改造：启动 OutboxRelayWorker
|
||
```
|
||
|
||
## 2. 领域模型
|
||
|
||
### 2.1 聚合根与实体
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class UserEntity {
|
||
-id: string
|
||
-email: string
|
||
-passwordHash: string
|
||
-name: string
|
||
-status: UserStatus
|
||
-dataScope: DataScope
|
||
-createdAt: Date
|
||
-updatedAt: Date
|
||
+create(props) UserEntity$
|
||
+rename(name) UserRenamedEvent
|
||
+disable() UserDisabledEvent
|
||
+changeDataScope(scope) UserDataScopeChangedEvent
|
||
+verifyPassword(plain) bool
|
||
}
|
||
|
||
class RoleEntity {
|
||
-id: string
|
||
-name: string
|
||
-description: string?
|
||
-roleType: RoleType
|
||
+create(props) RoleEntity$
|
||
+rename(name) RoleRenamedEvent
|
||
}
|
||
|
||
class Permission {
|
||
+id: string
|
||
+name: string
|
||
+resource: string
|
||
+action: string
|
||
}
|
||
|
||
class RoleViewport {
|
||
+id: string
|
||
+roleId: string
|
||
+viewportKey: string
|
||
+label: string
|
||
+route: string
|
||
+sortOrder: string
|
||
+requiredPermission: string?
|
||
+componentConfig: string?
|
||
}
|
||
|
||
class RefreshToken {
|
||
+id: string
|
||
+userId: string
|
||
+tokenHash: string
|
||
+expiresAt: Date
|
||
+revokedAt: Date?
|
||
+isRevoked() bool
|
||
+isExpired() bool
|
||
}
|
||
|
||
UserEntity "1" --> "many" RefreshToken : 拥有
|
||
RoleEntity "1" --> "many" Permission : 通过 role_permissions
|
||
RoleEntity "1" --> "many" RoleViewport : 配置
|
||
```
|
||
|
||
### 2.2 值对象（枚举）
|
||
|
||
```typescript
|
||
enum UserStatus {
|
||
ACTIVE = "active",
|
||
DISABLED = "disabled",
|
||
PENDING = "pending", // P2 新增：注册后待激活
|
||
}
|
||
|
||
enum DataScope {
|
||
SELF = "self", // L0
|
||
CLASS = "class", // L1
|
||
GRADE = "grade", // L2
|
||
SCHOOL = "school", // L3
|
||
DISTRICT = "district", // L4
|
||
ALL = "all", // L5
|
||
}
|
||
|
||
enum RoleType {
|
||
// P2 新增：三层角色模型
|
||
SYSTEM = "system", // 系统预设（admin/teacher/student/parent）
|
||
ORGANIZATION = "organization", // 组织分配（年级组长/班主任/学科组长）
|
||
TEMPORARY = "temporary", // 临时授权（代课教师）
|
||
}
|
||
```
|
||
|
||
### 2.3 聚合间通信
|
||
|
||
- **同服务内**：`IamService` 直接调用 `RbacService`、`PermissionCacheService`（NestJS DI）
|
||
- **跨服务**：通过 Kafka 事件（Outbox 发布），不直接调用其他服务
|
||
|
||
## 3. 数据模型
|
||
|
||
### 3.1 表清单（P2 目标态）
|
||
|
||
#### 3.1.1 已有表（保留）
|
||
|
||
| 表名 | 用途 | 主键 | 唯一索引 |
|
||
| ---------------------- | -------------------- | ----------------------------- | ----------------------- |
|
||
| `iam_users` | 用户主表 | `id` (char36) | `email` |
|
||
| `iam_roles` | 角色表 | `id` | `name` |
|
||
| `iam_user_roles` | 用户-角色绑定 | `(userId, roleId)` 复合 | — |
|
||
| `iam_permissions` | 权限点表 | `id` | `name` |
|
||
| `iam_role_permissions` | 角色-权限映射 | `(roleId, permissionId)` 复合 | — |
|
||
| `iam_refresh_tokens` | refresh token 持久化 | `id` | — |
|
||
| `iam_role_viewports` | 角色-视口配置 | `id` | `(roleId, viewportKey)` |
|
||
|
||
#### 3.1.2 P2 新增表
|
||
|
||
| 表名 | 用途 | 主键 | 唯一索引 |
|
||
| ------------------------------ | ------------------------------- | ---- | ----------------------- |
|
||
| `iam_outbox` | Outbox 事件表（事务内写入） | `id` | — |
|
||
| `iam_parent_student_relations` | 家长-学生关系表 | `id` | `(parentId, studentId)` |
|
||
| `iam_user_sessions` | 用户会话记录（审计 + 强制下线） | `id` | `userId + deviceHash` |
|
||
|
||
> **注**：`class_subject_teachers` 表归属 core-edu（见 §8.1 决策点 8），不在 iam。
|
||
|
||
#### 3.1.3 P2 表结构定义
|
||
|
||
```typescript
|
||
// iam_outbox：Outbox 事件表
|
||
export const iamOutbox = mysqlTable(
|
||
"iam_outbox",
|
||
{
|
||
id: char("id", { length: 36 }).notNull().primaryKey(),
|
||
aggregateId: char("aggregate_id", { length: 36 }).notNull(),
|
||
aggregateType: varchar("aggregate_type", { length: 50 }).notNull(), // 'User' | 'Role'
|
||
eventType: varchar("event_type", { length: 100 }).notNull(), // 'UserRegistered' | ...
|
||
payload: text("payload").notNull(), // JSON 序列化
|
||
topic: varchar("topic", { length: 100 }).notNull(), // 'edu.identity.user.created'
|
||
status: mysqlEnum("status", ["pending", "published", "failed"])
|
||
.notNull()
|
||
.default("pending"),
|
||
retryCount: int("retry_count").notNull().default(0),
|
||
occurredAt: timestamp("occurred_at").notNull().defaultNow(),
|
||
publishedAt: timestamp("published_at"),
|
||
createdAt: timestamp("created_at").notNull().defaultNow(),
|
||
},
|
||
(table) => ({
|
||
statusIdx: index("idx_outbox_status").on(table.status), // relay 轮询用
|
||
aggregateIdx: index("idx_outbox_aggregate").on(table.aggregateId),
|
||
}),
|
||
);
|
||
|
||
// iam_parent_student_relations：家长-学生关系
|
||
export const parentStudentRelations = mysqlTable(
|
||
"iam_parent_student_relations",
|
||
{
|
||
id: char("id", { length: 36 }).notNull().primaryKey(),
|
||
parentId: char("parent_id", { length: 36 }).notNull(),
|
||
studentId: char("student_id", { length: 36 }).notNull(),
|
||
relation: varchar("relation", { length: 20 }).notNull(), // 'father' | 'mother' | 'guardian'
|
||
createdAt: timestamp("created_at").notNull().defaultNow(),
|
||
},
|
||
(table) => ({
|
||
parentStudentUniq: uniqueIndex("uniq_parent_student").on(
|
||
table.parentId,
|
||
table.studentId,
|
||
),
|
||
studentIdx: index("idx_student").on(table.studentId),
|
||
}),
|
||
);
|
||
|
||
// iam_roles 表扩展：新增 role_type 字段
|
||
// 在现有 iam_roles 表 ALTER ADD:
|
||
// role_type ENUM('system','organization','temporary') NOT NULL DEFAULT 'system'
|
||
// level INT NOT NULL DEFAULT 0 -- 三层优先级：system=0(最高) / organization=1 / temporary=2
|
||
```
|
||
|
||
### 3.2 索引策略
|
||
|
||
| 表 | 索引 | 用途 |
|
||
| ------------------------------ | -------------------------------------------------- | -------------------------------- |
|
||
| `iam_users` | PK(`id`)、UNIQUE(`email`) | 主键查询、登录查询 |
|
||
| `iam_user_roles` | INDEX(`userId`)、INDEX(`roleId`) | 按用户查角色、按角色查用户 |
|
||
| `iam_role_permissions` | INDEX(`roleId`)、INDEX(`permissionId`) | 按角色查权限 |
|
||
| `iam_refresh_tokens` | INDEX(`userId`)、INDEX(`tokenHash`) | 按用户查 token、按 hash 校验 |
|
||
| `iam_role_viewports` | INDEX(`roleId`) | 按角色查视口 |
|
||
| `iam_outbox` | INDEX(`status`)、INDEX(`aggregateId`) | relay 轮询 pending、按聚合查事件 |
|
||
| `iam_parent_student_relations` | UNIQUE(`parentId`,`studentId`)、INDEX(`studentId`) | 防重、按学生查家长 |
|
||
|
||
### 3.3 读写分离策略
|
||
|
||
- **写路径**：所有 Command 走 MySQL 主库（iam 独占库，无读写分离）
|
||
- **读路径**：P2 暂不引入 ClickHouse 读模型（iam 读多写少但数据量小，MySQL 足够）
|
||
- **缓存层**：`getEffectivePermissions` / `getUserViewports` 结果走 Redis 缓存（TTL 5min）
|
||
|
||
## 4. API 设计
|
||
|
||
### 4.1 REST API 完整清单（P2 目标态）
|
||
|
||
| Method | Path | 权限 | 请求体 / 参数 | 响应 | 说明 |
|
||
| ------ | ------------------------------------------ | ----------------- | ---------------------------------- | ----------------- | -------------------------------------- |
|
||
| POST | `/iam/register` | 公开 | `{email, password, name}` | `{user, tokens}` | 注册 + 自动分配 teacher 角色 |
|
||
| POST | `/iam/login` | 公开 | `{email, password}` | `{user, tokens}` | 登录 |
|
||
| POST | `/iam/refresh` | 公开 | `{refreshToken}` | `{tokens}` | 刷新令牌（轮换 + 旧 token 加入黑名单） |
|
||
| POST | `/iam/logout` | `IAM_USER_READ` | `{refreshToken}` | `{success}` | 登出（refresh token 加黑名单） |
|
||
| GET | `/iam/me` | `IAM_USER_READ` | — | `{user}` | 当前用户信息 |
|
||
| GET | `/iam/viewports` | `IAM_USER_READ` | — | `{viewports[]}` | 当前用户视口（L1 导航） |
|
||
| GET | `/iam/permissions/effective` | `IAM_USER_READ` | — | `{permissions[]}` | 当前用户有效权限 |
|
||
| GET | `/iam/.well-known/jwks.json` | 公开 | — | `{keys[]}` | RS256 公钥 JWK Set（Gateway 拉取） |
|
||
| GET | `/iam/roles` | `IAM_ROLE_MANAGE` | — | `{roles[]}` | 角色列表 |
|
||
| POST | `/iam/roles` | `IAM_ROLE_MANAGE` | `{name, description, roleType}` | `{role}` | 创建角色 |
|
||
| PUT | `/iam/roles/:id` | `IAM_ROLE_MANAGE` | `{name?, description?}` | `{role}` | 更新角色 |
|
||
| DELETE | `/iam/roles/:id` | `IAM_ROLE_MANAGE` | — | `{success}` | 删除角色（系统角色禁止删） |
|
||
| GET | `/iam/permissions` | `IAM_ROLE_MANAGE` | — | `{permissions[]}` | 权限点列表 |
|
||
| GET | `/iam/users/:id/roles` | `IAM_ROLE_MANAGE` | — | `{roles[]}` | 用户角色列表 |
|
||
| POST | `/iam/users/:id/roles` | `IAM_ROLE_MANAGE` | `{roleId}` | `{success}` | 给用户分配角色 |
|
||
| DELETE | `/iam/users/:id/roles/:roleId` | `IAM_ROLE_MANAGE` | — | `{success}` | 移除用户角色（触发缓存失效） |
|
||
| GET | `/iam/roles/:id/permissions` | `IAM_ROLE_MANAGE` | — | `{permissions[]}` | 角色权限列表 |
|
||
| POST | `/iam/roles/:id/permissions` | `IAM_ROLE_MANAGE` | `{permissionId}` | `{success}` | 给角色授予权限 |
|
||
| DELETE | `/iam/roles/:id/permissions/:permissionId` | `IAM_ROLE_MANAGE` | — | `{success}` | 移除角色权限（触发缓存失效） |
|
||
| GET | `/iam/roles/:id/viewports` | `IAM_ROLE_MANAGE` | — | `{viewports[]}` | 角色视口列表 |
|
||
| POST | `/iam/roles/:id/viewports` | `IAM_ROLE_MANAGE` | `{viewportKey, label, route, ...}` | `{viewport}` | 创建视口配置 |
|
||
| PUT | `/iam/roles/:id/viewports/:viewportId` | `IAM_ROLE_MANAGE` | `{label?, route?, ...}` | `{viewport}` | 更新视口配置 |
|
||
| DELETE | `/iam/roles/:id/viewports/:viewportId` | `IAM_ROLE_MANAGE` | — | `{success}` | 删除视口配置 |
|
||
| GET | `/iam/users/:id/parents` | `IAM_USER_READ` | — | `{parents[]}` | 学生家长列表（家长-学生关系） |
|
||
| POST | `/iam/users/:studentId/parents` | `IAM_ROLE_MANAGE` | `{parentId, relation}` | `{success}` | 绑定家长-学生关系 |
|
||
|
||
### 4.2 请求/响应结构示例
|
||
|
||
```typescript
|
||
// 注册响应
|
||
interface RegisterResponse {
|
||
success: true;
|
||
data: {
|
||
user: {
|
||
id: string;
|
||
email: string;
|
||
name: string;
|
||
roles: string[]; // ['teacher']
|
||
permissions: string[]; // ['IAM_USER_READ', 'CLASSES_READ', ...]
|
||
dataScope: "self" | "class" | "grade" | "school" | "district" | "all";
|
||
};
|
||
tokens: {
|
||
accessToken: string; // RS256 签名，15min
|
||
refreshToken: string; // RS256 签名，7day
|
||
expiresIn: 900; // 秒
|
||
};
|
||
};
|
||
}
|
||
|
||
// JWK Set 响应（RS256 公钥暴露）
|
||
interface JwkSet {
|
||
keys: Array<{
|
||
kty: "RSA";
|
||
use: "sig";
|
||
alg: "RS256";
|
||
kid: string; // 密钥 ID（支持轮换）
|
||
n: string; // modulus base64url
|
||
e: string; // exponent base64url
|
||
}>;
|
||
}
|
||
```
|
||
|
||
### 4.3 JWT Payload（RS256 签发）
|
||
|
||
```typescript
|
||
interface JwtPayload {
|
||
sub: string; // userId
|
||
email: string;
|
||
roles: string[]; // ['teacher', 'grade_leader']
|
||
dataScope: DataScope; // 'class' | 'grade' | ...
|
||
type: "access" | "refresh";
|
||
iat: number; // 签发时间
|
||
exp: number; // 过期时间
|
||
iss: "next-edu-cloud"; // 签发者
|
||
aud: "next-edu-cloud"; // 受众
|
||
jti: string; // JWT ID（用于黑名单）
|
||
}
|
||
```
|
||
|
||
## 5. 事件设计
|
||
|
||
### 5.1 我发布的领域事件
|
||
|
||
| 事件 | 触发时机 | Topic | 消费者动作 |
|
||
| ----------------- | ------------------------------ | -------------------------------- | -------------------------------------------------- |
|
||
| `UserRegistered` | 注册成功 | `edu.identity.user.created` | core-edu 初始化默认班级关联；msg 发欢迎通知 |
|
||
| `UserUpdated` | 用户信息变更（name/dataScope） | `edu.identity.user.updated` | core-edu 同步用户快照；msg 通知 |
|
||
| `UserDisabled` | 用户禁用/注销 | `edu.identity.user.deleted` | core-edu 解除关联；msg 通知；push-gateway 强制下线 |
|
||
| `UserRoleChanged` | 用户角色绑定变更 | `edu.identity.user.role_changed` | 自身 Redis 缓存失效；msg 审计日志 |
|
||
| `RoleCreated` | 角色创建 | `edu.identity.role.created` | msg 审计（仅管理端关注） |
|
||
| `RoleUpdated` | 角色权限变更 | `edu.identity.role.updated` | 所有该角色用户的缓存失效；msg 审计 |
|
||
|
||
### 5.2 事件 Schema（建议 coord 在 shared-proto 中统一定义）
|
||
|
||
```protobuf
|
||
// 建议在 packages/shared-proto/proto/events.proto 新增：
|
||
message UserEvent {
|
||
string event_id = 1; // UUID，幂等去重
|
||
string aggregate_id = 2; // userId
|
||
string event_type = 3; // 'UserRegistered' | 'UserUpdated' | ...
|
||
int64 occurred_at = 4; // 发生时间戳（ms）
|
||
string user_id = 5;
|
||
string email = 6;
|
||
string name = 7;
|
||
repeated string roles = 8;
|
||
string data_scope = 9;
|
||
string action = 10; // 'created' | 'updated' | 'disabled' | 'role_changed'
|
||
map<string, string> metadata = 11; // trace_id 等
|
||
}
|
||
|
||
message RoleEvent {
|
||
string event_id = 1;
|
||
string aggregate_id = 2; // roleId
|
||
string event_type = 3;
|
||
int64 occurred_at = 4;
|
||
string role_id = 5;
|
||
string role_name = 6;
|
||
string action = 7; // 'created' | 'updated' | 'deleted'
|
||
map<string, string> metadata = 8;
|
||
}
|
||
```
|
||
|
||
> **需 coord 在 shared-proto/events.proto 中统一定义**，iam 只负责填充字段并写入 outbox。
|
||
|
||
### 5.3 我消费的事件
|
||
|
||
- **当前**：无
|
||
- **未来**：不主动消费业务事件（iam 是权限中枢，单向发布）
|
||
|
||
### 5.4 Outbox 实现策略
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Ctl as Controller
|
||
participant Svc as IamService
|
||
participant DB as MySQL
|
||
participant Outbox as iam_outbox 表
|
||
participant Relay as OutboxRelayWorker
|
||
participant Kafka as Kafka
|
||
|
||
Ctl->>Svc: register(dto)
|
||
Svc->>DB: BEGIN TX
|
||
Svc->>DB: INSERT iam_users
|
||
Svc->>DB: INSERT iam_user_roles
|
||
Svc->>Outbox: INSERT event (status=pending)
|
||
Svc->>DB: COMMIT TX
|
||
Svc-->>Ctl: {user, tokens}
|
||
|
||
loop 每 100ms 轮询
|
||
Relay->>Outbox: SELECT * WHERE status='pending' LIMIT 100
|
||
Outbox-->>Relay: events[]
|
||
Relay->>Kafka: produce(topic, payload)
|
||
Kafka-->>Relay: ack
|
||
Relay->>Outbox: UPDATE status='published', published_at=NOW()
|
||
end
|
||
```
|
||
|
||
**Relay Worker 实现**：
|
||
|
||
- 独立 `@Injectable()` 服务，`OnModuleInit` 启动轮询
|
||
- 每 100ms 查询 `status='pending'` 的事件，批量投递 Kafka
|
||
- 投递失败重试 3 次，超过后标记 `status='failed'`，记录日志
|
||
- Kafka 未启动时不阻塞主服务（try/catch + 日志警告）
|
||
|
||
## 6. 横切关注点对齐清单
|
||
|
||
### 6.1 权限装饰器（所有端点及对应权限常量）
|
||
|
||
| 端点 | 权限常量 |
|
||
| ----------------------------------------------- | ----------------- |
|
||
| POST /iam/register | 公开（无装饰器） |
|
||
| POST /iam/login | 公开 |
|
||
| POST /iam/refresh | 公开 |
|
||
| GET /iam/.well-known/jwks.json | 公开 |
|
||
| POST /iam/logout | `IAM_USER_READ` |
|
||
| GET /iam/me | `IAM_USER_READ` |
|
||
| GET /iam/viewports | `IAM_USER_READ` |
|
||
| GET /iam/permissions/effective | `IAM_USER_READ` |
|
||
| GET /iam/users/:id/parents | `IAM_USER_READ` |
|
||
| GET /iam/roles | `IAM_ROLE_MANAGE` |
|
||
| POST /iam/roles | `IAM_ROLE_MANAGE` |
|
||
| PUT /iam/roles/:id | `IAM_ROLE_MANAGE` |
|
||
| DELETE /iam/roles/:id | `IAM_ROLE_MANAGE` |
|
||
| GET /iam/permissions | `IAM_ROLE_MANAGE` |
|
||
| GET /iam/users/:id/roles | `IAM_ROLE_MANAGE` |
|
||
| POST /iam/users/:id/roles | `IAM_ROLE_MANAGE` |
|
||
| DELETE /iam/users/:id/roles/:roleId | `IAM_ROLE_MANAGE` |
|
||
| GET /iam/roles/:id/permissions | `IAM_ROLE_MANAGE` |
|
||
| POST /iam/roles/:id/permissions | `IAM_ROLE_MANAGE` |
|
||
| DELETE /iam/roles/:id/permissions/:permissionId | `IAM_ROLE_MANAGE` |
|
||
| GET /iam/roles/:id/viewports | `IAM_ROLE_MANAGE` |
|
||
| POST /iam/roles/:id/viewports | `IAM_ROLE_MANAGE` |
|
||
| PUT /iam/roles/:id/viewports/:viewportId | `IAM_ROLE_MANAGE` |
|
||
| DELETE /iam/roles/:id/viewports/:viewportId | `IAM_ROLE_MANAGE` |
|
||
| POST /iam/users/:studentId/parents | `IAM_ROLE_MANAGE` |
|
||
|
||
**权限常量清单**（P2 完整化）：
|
||
|
||
```typescript
|
||
export const Permissions = {
|
||
// 用户管理
|
||
IAM_USER_CREATE: "IAM_USER_CREATE",
|
||
IAM_USER_READ: "IAM_USER_READ",
|
||
IAM_USER_UPDATE: "IAM_USER_UPDATE",
|
||
IAM_USER_DELETE: "IAM_USER_DELETE",
|
||
// 角色管理
|
||
IAM_ROLE_MANAGE: "IAM_ROLE_MANAGE",
|
||
// 视口管理
|
||
IAM_VIEWPORT_MANAGE: "IAM_VIEWPORT_MANAGE",
|
||
// 家长-学生关系管理
|
||
IAM_RELATION_MANAGE: "IAM_RELATION_MANAGE",
|
||
} as const;
|
||
```
|
||
|
||
### 6.2 错误码清单（带前缀）
|
||
|
||
| 错误码 | HTTP | 触发条件 |
|
||
| ----------------------- | ---- | ---------------------------------------------------- |
|
||
| `IAM_VALIDATION_ERROR` | 400 | Zod 校验失败 |
|
||
| `IAM_UNAUTHORIZED` | 401 | 未登录、密码错误、token 失效、refresh token 在黑名单 |
|
||
| `IAM_PERMISSION_DENIED` | 403 | 缺少所需权限点 |
|
||
| `IAM_NOT_FOUND` | 404 | 用户/角色/权限/视口不存在 |
|
||
| `IAM_CONFLICT` | 409 | 邮箱已注册、角色名重复、家长-学生关系已存在 |
|
||
| `IAM_BUSINESS_ERROR` | 422 | 账号禁用、系统角色禁止删除、refresh token 已撤销 |
|
||
| `IAM_RATE_LIMITED` | 429 | 登录失败次数过多（P2 可选，限流在 Gateway） |
|
||
| `IAM_DATABASE_ERROR` | 500 | Drizzle 操作失败 |
|
||
| `IAM_INTERNAL_ERROR` | 500 | 未预期异常 |
|
||
| `IAM_OUTBOX_ERROR` | 500 | Outbox 写入或投递失败 |
|
||
|
||
### 6.3 Logger 初始化位置与配置
|
||
|
||
- **位置**：`src/shared/observability/logger.ts`（已有）
|
||
- **配置**：pino，`base: { service: 'iam', version: '0.1.0' }`，`level: env.LOG_LEVEL`
|
||
- **P2 新增**：日志中注入 `traceId`（从 `x-request-id` 头读取，OTel auto-instrumentation 已覆盖）
|
||
|
||
### 6.4 Metrics 指标清单
|
||
|
||
| 指标名 | 类型 | 标签 | 描述 |
|
||
| ------------------------------------- | --------- | ------------------------ | ------------------------------ |
|
||
| `iam_requests_total` | Counter | method, endpoint, status | 请求总数（已有） |
|
||
| `iam_request_duration_seconds` | Histogram | method, endpoint | 请求延迟（已有） |
|
||
| `iam_login_attempts_total` | Counter | result(success/failure) | 登录尝试次数（P2 新增） |
|
||
| `iam_login_duration_seconds` | Histogram | — | 登录耗时（P2 新增） |
|
||
| `iam_jwt_issued_total` | Counter | type(access/refresh) | JWT 签发次数（P2 新增） |
|
||
| `iam_permission_cache_hits_total` | Counter | — | 权限缓存命中（P2 新增） |
|
||
| `iam_permission_cache_misses_total` | Counter | — | 权限缓存未命中（P2 新增） |
|
||
| `iam_outbox_pending` | Gauge | — | Outbox 待投递事件数（P2 新增） |
|
||
| `iam_outbox_publish_duration_seconds` | Histogram | — | Outbox 投递耗时（P2 新增） |
|
||
|
||
### 6.5 Tracer 初始化位置
|
||
|
||
- **位置**：`src/shared/observability/tracer.ts`（已有）
|
||
- **配置**：NodeSDK + OTLP HTTP exporter，`serviceName: 'iam'`
|
||
- **P2 保持**：auto-instrumentations 覆盖 HTTP/Express/Drizzle（mysql2）
|
||
|
||
### 6.6 /healthz 检查逻辑
|
||
|
||
- **端点**：`GET /healthz`
|
||
- **逻辑**：仅返回进程存活，不检查依赖
|
||
- **响应**：`{ status: 'ok', service: 'iam', timestamp: ISO }`
|
||
|
||
### 6.7 /readyz 检查逻辑（P2 改造）
|
||
|
||
- **端点**：`GET /readyz`
|
||
- **逻辑**（P2 新增 Redis + Kafka 检查）：
|
||
```typescript
|
||
async readiness() {
|
||
const checks = await Promise.allSettled([
|
||
this.checkDb(), // db.execute(sql`SELECT 1`)
|
||
this.checkRedis(), // redis.ping()
|
||
this.checkKafka(), // kafka.admin().listTopics()（轻量探活）
|
||
]);
|
||
const allOk = checks.every(r => r.status === 'fulfilled');
|
||
if (!allOk) throw 503;
|
||
return { status: 'ok', service: 'iam', timestamp, checks };
|
||
}
|
||
```
|
||
- **失败**：HTTP 503，响应体含失败项详情
|
||
|
||
### 6.8 优雅关闭顺序（P2 改造）
|
||
|
||
```typescript
|
||
async onApplicationShutdown(signal?: string) {
|
||
// 1. 停止接收新请求（NestJS 自动）
|
||
// 2. 停止 OutboxRelayWorker（停止轮询）
|
||
await this.relayWorker.stop();
|
||
// 3. 关闭 Kafka producer
|
||
await this.kafkaProducer.disconnect();
|
||
// 4. 关闭 Redis 连接
|
||
await this.redisClient.quit();
|
||
// 5. 关闭 MySQL 连接池
|
||
await closeDb();
|
||
// 6. 关闭 Tracer
|
||
await shutdownTracer();
|
||
}
|
||
```
|
||
|
||
## 7. 与其他模块的交互点（契约清单）
|
||
|
||
| 方向 | 对方服务 | 协议 | 接口/事件 | 用途 |
|
||
| ------ | ----------- | ----- | ------------------------------------------- | -------------------------------- |
|
||
| 被调用 | api-gateway | HTTP | `POST /iam/register` 等 | Gateway 反向代理 `/api/v1/iam/*` |
|
||
| 被调用 | teacher-bff | HTTP | `GET /iam/me`、`GET /iam/viewports` | BFF 聚合用户身份与视口 |
|
||
| 被调用 | student-bff | HTTP | `GET /iam/me`、`GET /iam/viewports` | 同上（P3） |
|
||
| 被调用 | parent-bff | HTTP | `GET /iam/me`、`GET /iam/users/:id/parents` | 同上 + 家长-学生关系（P4） |
|
||
| 被调用 | api-gateway | HTTP | `GET /iam/.well-known/jwks.json` | Gateway 拉取 RS256 公钥校验 JWT |
|
||
| 发布 | — | Kafka | `edu.identity.user.created` | core-edu / msg 消费 |
|
||
| 发布 | — | Kafka | `edu.identity.user.updated` | core-edu / msg 消费 |
|
||
| 发布 | — | Kafka | `edu.identity.user.deleted` | core-edu / msg 消费 |
|
||
| 发布 | — | Kafka | `edu.identity.user.role_changed` | 自身缓存失效 / msg 审计 |
|
||
| 发布 | — | Kafka | `edu.identity.role.created` | msg 审计 |
|
||
| 发布 | — | Kafka | `edu.identity.role.updated` | 自身缓存失效 / msg 审计 |
|
||
| 消费 | — | — | — | iam 不消费外部事件 |
|
||
|
||
### 7.1 端口分配
|
||
|
||
| 服务 | 端口 | 备注 |
|
||
| -------- | ----- | ------------------------------------------------------------ |
|
||
| iam HTTP | 3002 | 已有，REST 入口 |
|
||
| iam gRPC | 50052 | P3 引入（与 core-edu 50053 等区分，需 coord 全局端口表确认） |
|
||
|
||
### 7.2 Topic 命名（遵循 004 §7.2）
|
||
|
||
- `edu.identity.user.created`
|
||
- `edu.identity.user.updated`
|
||
- `edu.identity.user.deleted`
|
||
- `edu.identity.user.role_changed`
|
||
- `edu.identity.role.created`
|
||
- `edu.identity.role.updated`
|
||
|
||
> **需 coord 在全局 Topic 表中登记**，避免与 core-edu 的 `edu.identity.user.created` 冲突（004 §7.2 已记录 iam 为生产者）。
|
||
|
||
## 8. 风险与假设
|
||
|
||
### 8.1 架构决策点（需 coord 仲裁）
|
||
|
||
| # | 决策点 | 我的建议 | 风险 |
|
||
| --- | ------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------ |
|
||
| 1 | RS256 密钥管理 | P2 本地文件 `IAM_PRIVATE_KEY_PATH` / `IAM_PUBLIC_KEY_PATH`，P6 迁 Vault | 密钥文件权限管理；容器挂载 |
|
||
| 2 | 公钥暴露端点 | `GET /iam/.well-known/jwks.json`（JWK Set 标准） | Gateway 需实现 JWK 解析 |
|
||
| 3 | 权限缓存失效 | 角色变更时本地主动 `DEL iam:perms:{userId}` + 发事件 | 缓存与 DB 短暂不一致（< 5min TTL） |
|
||
| 4 | Outbox 实现 | iam 自建轻量 Outbox（P2 先于 core-edu 落地） | 与 core-edu P3 Outbox 模式需对齐（建议 coord 在 shared-ts 提供通用工具） |
|
||
| 5 | gRPC 引入时机 | P2 仅 REST，P3 随 core-edu 引入 gRPC server | teacher-bff P2 仍走 HTTP，P3 改 gRPC 需协调 ai03 |
|
||
| 6 | DataScope 枚举 | schema 用字符串枚举，proto 用数值枚举 L0-L5 映射 | 跨层映射需文档化 |
|
||
| 7 | `parent_student_relations` 归属 | 归 iam（身份关系优先） | core-edu 查询家长需走 iam API |
|
||
| 8 | `class_subject_teachers` 归属 | 归 core-edu（教学组织数据） | iam 只存 userId + 角色，不存任教关系 |
|
||
| 9 | PermissionGuard 改造 | DB 驱动 + Redis 缓存，废弃本地 ROLE_PERMISSIONS map | 性能：每次请求多一次缓存查询 |
|
||
| 10 | AuthMiddleware 注册 | P2 仍不注册，Controller 直读 header（与 Gateway 透传策略一致） | 多 Controller 重复读 header 代码 |
|
||
|
||
### 8.2 技术风险
|
||
|
||
| 风险 | 影响 | 缓解措施 |
|
||
| -------------------- | ---------------------------------- | -------------------------------------------------------- |
|
||
| Redis 不可用 | 权限校验回退到 DB 查询，性能下降 | `getEffectivePermissions` catch 后走 DB，不抛错 |
|
||
| Kafka 不可用 | Outbox 事件积压，下游服务感知延迟 | Relay Worker 重试 + `status='failed'` 记录，不阻塞主流程 |
|
||
| RS256 密钥泄露 | 任何人可伪造 JWT | 密钥文件权限 600 + 容器 Secret 挂载 + 定期轮换（P6） |
|
||
| 权限缓存与 DB 不一致 | 用户角色变更后 5min 内旧权限仍生效 | 角色变更主动 DEL + 事件驱动失效 + 短 TTL |
|
||
| Outbox 表膨胀 | 磁盘占用增长 | 已发布事件定期清理（保留 7 天）或归档到 ClickHouse |
|
||
|
||
### 8.3 假设
|
||
|
||
- 假设 coord 在 shared-proto/events.proto 中统一定义 `UserEvent` / `RoleEvent` message（iam 只填充字段）
|
||
- 假设 api-gateway 实现 JWK Set 拉取与 RS256 公钥校验（ai01 负责）
|
||
- 假设 teacher-bff 仍走 HTTP 调用 iam（ai03 负责，P3 改 gRPC 时协调）
|
||
- 假设 shared-ts 在 P2 不提供通用 Outbox 工具（iam 自建，P3 core-edu 落地后回写到 shared-ts）
|
||
|
||
### 8.4 未决问题（需 coord 回复）
|
||
|
||
1. shared-ts 是否在 P2 提供通用 Outbox 工具？还是 iam 自建？
|
||
2. events.proto 中 `UserEvent` / `RoleEvent` 由 coord 统一定义，还是 iam 提交 PR？
|
||
3. iam gRPC 端口 50052 是否与全局端口表冲突？
|
||
4. `class_subject_teachers` 表归属确认（我建议归 core-edu，pending-features §P2 写在 iam）
|
||
|
||
---
|
||
|
||
**AI Agent**: ai02 (iam-module)
|
||
**Branch**: main（单仓库并行模式，见 ai-allocation §9.1）
|
||
**Coordinator**: coord-ai
|