iam 下一步工作与上下游依赖（Next Steps）
模块：iam（身份与访问管理服务，端口 3002 HTTP + 50052 gRPC）
负责人：ai06
更新日期：2026-07-13
关联文档：
1. 模块当前状态
iam 服务已完成 P2–P6 全部批次，包含 15 个 gRPC RPC + 完整 REST CRUD + TOTP 2FA + 审计日志 + Outbox 事件发布 + Redis 权限缓存（含 Prometheus 指标）。本地 Docker 验证通过（真实 MySQL/Redis/Kafka，无 mock 数据）。
1.1 本地 Docker 验证结果（2026-07-13）
测试环境：edu-iam-test 容器（NODE_ENV=production, DEV_MODE=true），接入 edu-full_default 网络，直连 edu-mysql / edu-redis / edu-kafka。
| 验证项 |
状态 |
说明 |
| Docker 镜像构建 |
✅ |
node:20-alpine + shared-ts 预编译 + pnpm install --frozen-lockfile |
| /healthz 健康检查 |
✅ |
200 {"status":"ok","service":"iam"} |
| /metrics Prometheus 指标 |
✅ |
含 iam_permission_cache_hits/misses/invalidations 三个新指标 |
| gRPC 50052 启动 |
✅ |
日志 IAM service started (HTTP + gRPC dual entry) |
| GET /.well-known/jwks.json |
✅ |
返回 RS256 公钥（kid=iam-rs256-v1） |
| POST /v1/iam/register |
✅ |
创建用户 + 返回 JWT token 对 |
| POST /v1/iam/login |
✅ |
邮箱密码登录 + 返回 JWT token 对 |
| GET /v1/iam/me |
✅ |
返回当前用户信息 |
| PATCH /v1/iam/me |
✅ |
更新个人资料（name/email） |
| POST /v1/iam/change-password |
✅ |
密码强度校验 + 历史重用检查 + token 撤销 |
| GET /v1/iam/viewports |
✅ |
返回视口列表（含 level + componentConfig 字段） |
| GET /v1/iam/permissions/effective |
✅ |
返回用户有效权限列表 |
| GET /v1/iam/children |
✅ |
返回家长-学生关系 |
| GET /v1/iam/users（分页） |
✅ |
返回用户列表 + total 总数 |
| PATCH /v1/iam/users/:id |
✅ |
管理员更新用户 |
| PATCH /v1/iam/users/:id/status |
✅ |
用户状态切换 |
| GET /v1/iam/roles |
✅ |
返回角色列表（含三层角色模型） |
| POST /v1/iam/roles |
✅ |
创建角色（system/organization/temporary） |
| PATCH /v1/iam/roles/:id |
✅ |
更新角色 |
| PATCH /v1/iam/roles/:id/permissions |
✅ |
批量更新角色权限 |
| POST/DELETE /v1/iam/roles/:roleId/permissions/:permissionId |
✅ |
单条授权/撤销 |
| GET /v1/iam/permissions |
✅ |
返回权限点列表 |
| POST /v1/iam/permissions |
✅ |
创建权限点 |
| PATCH /v1/iam/permissions/:id |
✅ |
更新权限点 |
| DELETE /v1/iam/permissions/:id |
✅ |
删除权限点（级联清理 role_permissions） |
| POST /v1/iam/viewports |
✅ |
创建视口（含 level + componentConfig） |
| PATCH /v1/iam/viewports/:id |
✅ |
更新视口 |
| DELETE /v1/iam/viewports/:id |
✅ |
删除视口 |
| POST /v1/iam/totp/enable |
✅ |
生成 TOTP 密钥 + QR URL + 10 个备份码 |
| POST /v1/iam/totp/verify |
✅ |
验证 TOTP 码（pending → active） |
| POST /v1/iam/totp/disable |
✅ |
禁用 TOTP |
| typecheck + lint |
✅ |
两项零错误 |
1.2 已完成的关键能力
| # |
能力 |
实现详情 |
| 1 |
15 个 gRPC RPC |
Register/Login/RefreshToken/Logout/GetUserInfo/GetUserProfile/UpdateProfile/ChangePassword/BatchGetUsers/GetEffectivePermissions/GetEffectiveAccess/GetEffectiveDataScope/GetViewports/GetPublicKey/GetChildrenByParent |
| 2 |
REST CRUD 完整 |
角色/权限/视口/用户/TOTP 全部 CRUD 端点 |
| 3 |
三层角色模型 |
system（level=0）/ organization（level=1）/ temporary（level=2） |
| 4 |
DataScope 6 级 |
self/subject/class/grade/school/all |
| 5 |
视口 4 层 + L4 数据级配置 |
admin/teacher/student/parent + componentConfig JSON |
| 6 |
密码策略 |
bcrypt cost 12 + 强度校验 + 5 次历史重用限制 |
| 7 |
TOTP 2FA |
RFC 6238 HMAC-SHA1 纯 JS 实现 + 10 备份码 |
| 8 |
审计日志 |
ip/userAgent/traceId 从请求头提取 + Outbox 事件发布 |
| 9 |
JWKS 端点 |
GET /v1/iam/.well-known/jwks.json 暴露 RS256 公钥 |
| 10 |
Redis 权限缓存 |
TTL 5min + 角色变更失效 + hit/miss/invalidation 指标 |
| 11 |
Outbox 模式 |
iam_outbox 表 + Kafka publisher（edu.iam.user.events / edu.iam.role.events / edu.iam.audit.created） |
| 12 |
AuthMiddleware |
从 Gateway 注入的 x-user-* 头部解析用户身份 |
| 13 |
PermissionGuard |
APP_GUARD + DB 驱动 + Redis 缓存 + dataScope=all 跳过校验 |
2. 上游依赖（iam 依赖谁）
iam 作为身份基础设施服务，运行时依赖以下组件：
2.1 MySQL（基础设施）— P0
| 项 |
内容 |
| 依赖内容 |
用户/角色/权限/视口/审计日志/密码历史/TOTP/Outbox 表 |
| 端点 |
mysql://edu:changeme@edu-mysql:3306/next_edu_cloud |
| 用途 |
所有业务数据持久化 |
| 当前状态 |
✅ 本地 Docker edu-mysql 已就绪 |
| 环境变量 |
DATABASE_URL=mysql://edu:changeme@edu-mysql:3306/next_edu_cloud |
2.2 Redis（基础设施）— P0
| 项 |
内容 |
| 依赖内容 |
权限缓存 + token 黑名单 |
| 端点 |
redis://edu-redis:6379 |
| 用途 |
1) 用户权限缓存（TTL 5min）2) 角色变更失效广播 |
| 当前状态 |
✅ 本地 Docker edu-redis 已就绪 |
| 环境变量 |
REDIS_URL=redis://edu-redis:6379 |
2.3 Kafka（基础设施）— P1
| 项 |
内容 |
| 依赖内容 |
Outbox 事件投递（edu.iam.user.events / edu.iam.role.events / edu.iam.audit.created） |
| 端点 |
kafka:29092（容器内 INSIDE listener） |
| 用途 |
事务性事件发布（用户注册/登录/角色变更/审计日志） |
| 当前状态 |
✅ 本地 Docker edu-kafka 已就绪 |
| 环境变量 |
KAFKA_BROKERS=kafka:29092、KAFKA_CLIENT_ID=iam-service |
| 降级策略 |
Kafka 不可用时 Outbox 表持续累积，Kafka 恢复后自动投递 |
2.4 shared-proto（协调 AI 维护）— P0
| 项 |
内容 |
| 依赖内容 |
packages/shared-proto/proto/iam.proto 契约定义 |
| 用途 |
gRPC 服务定义 + proto-loader 运行时加载 |
| 当前状态 |
✅ 15 个 RPC 全部声明 |
2.5 shared-ts（协调 AI 维护）— P0
| 项 |
内容 |
| 依赖内容 |
@edu/shared-ts/outbox OutboxModule + OutboxService |
| 用途 |
事务性事件发布框架 |
| 当前状态 |
✅ 已构建并集成 |
3. 下游依赖（谁依赖 iam）
以下 9 个模块依赖 iam 服务：
3.1 api-gateway（ai01 负责）— P0
| # |
依赖项 |
用途 |
状态 |
| 1 |
GET /v1/iam/.well-known/jwks.json |
RS256 公钥集（JWKS），TTL 5min 缓存 |
✅ 已就绪 |
| 2 |
RS256 JWT 签发 |
api-gateway 用 JWKS 公钥校验 access_token |
✅ 已就绪 |
| 3 |
GET /healthz 端点 |
/readyz 下游健康检查 |
✅ 已就绪 |
| 4 |
JWT claims 含 role/data_scope |
api-gateway 注入 x-user-roles / x-user-data-scope 头 |
✅ 已就绪 |
验证结果：JWKS 端点返回有效公钥，JWT token 可被 RS256 验签。
3.2 push-gateway（ai09 负责）— P0
| # |
依赖项 |
用途 |
状态 |
| 1 |
GET /v1/iam/.well-known/jwks.json |
WebSocket /ws 连接时校验客户端 JWT 签名 |
✅ 已就绪 |
| 2 |
shared-go/jwks Fetcher 每 5 分钟刷新缓存 |
JWKS 缓存刷新 |
✅ 已就绪 |
环境变量：JWKS_URL=http://iam:3002/v1/iam/.well-known/jwks.json
3.3 teacher-bff（ai03 负责）— P0
| # |
依赖项 |
用途 |
状态 |
| 1 |
gRPC GetUserInfo(userId) :50052 |
currentUser/me 查询 |
✅ 已就绪 |
| 2 |
gRPC BatchGetUsers(userIds) :50052 |
adminUsers 查询 |
✅ 已就绪 |
| 3 |
gRPC GetEffectivePermissions(userId) :50052 |
用户有效权限列表 |
✅ 已就绪 |
| 4 |
gRPC GetEffectiveDataScope(userId) :50052 |
用户数据范围 |
✅ 已就绪 |
| 5 |
gRPC GetViewports(userId) :50052 |
adminViewports 查询 |
✅ 已就绪 |
| 6 |
gRPC GetPublicKey() :50052 |
RS256 公钥 |
✅ 已就绪 |
| 7 |
gRPC GetChildrenByParent(parentId) :50052 |
家长端学生列表 |
✅ 已就绪 |
| 8 |
REST GET /v1/iam/roles :3002 |
adminRoles 查询 |
✅ 已就绪 |
| 9 |
REST GET /v1/iam/permissions :3002 |
adminPermissions 查询 |
✅ 已就绪 |
| 10 |
REST GET /v1/iam/audit :3002 |
auditLogs 查询 |
✅ 已就绪 |
| 11 |
REST GET /v1/iam/viewports :3002 |
adminViewports 查询（备选） |
✅ 已就绪 |
| 12 |
REST GET /v1/iam/permissions/effective :3002 |
用户有效权限（备选） |
✅ 已就绪 |
| 13 |
GET /.well-known/jwks.json :3002 |
RS256 JWKS |
✅ 已就绪 |
| 14 |
POST /v1/iam/register / POST /v1/iam/login |
用户注册/登录 |
✅ 已就绪 |
| 15 |
PATCH /v1/iam/users/:id |
用户更新 |
✅ 已就绪 |
| 16 |
POST /v1/iam/roles / PATCH /v1/iam/roles/:id |
角色创建/更新 |
✅ 已就绪 |
环境变量：IAM_GRPC_TARGET=iam:50052、IAM_SERVICE_URL=http://iam:3002
3.4 student-bff（ai04 负责）— P0
| # |
gRPC 方法 |
用途 |
状态 |
| 1 |
GetUserProfile |
myProfile Query |
✅ 已就绪 |
| 2 |
UpdateProfile |
updateProfile Mutation |
✅ 已就绪 |
| 3 |
ChangePassword |
changePassword Mutation |
✅ 已就绪 |
proto 位置：packages/shared-proto/proto/iam.proto
3.5 parent-bff（ai05 负责）— P0
| # |
RPC 方法 |
用途 |
状态 |
| 1 |
getUserInfo(userId) |
获取家长个人信息 |
✅ 已就绪 |
| 2 |
getChildrenByParent(parentId) |
获取家长绑定的孩子列表 |
✅ 已就绪 |
| 3 |
getViewports(userId) |
获取家长可见视口 |
✅ 已就绪 |
| 4 |
getEffectivePermissions(userId) |
获取家长有效权限 |
✅ 已就绪 |
| 5 |
GET /healthz 端点 |
/readyz 下游健康检查 |
✅ 已就绪 |
| 6 |
GET /.well-known/jwks.json |
RS256 公钥集 |
✅ 已就绪 |
环境变量：IAM_GRPC_TARGET=iam:50052
3.6 teacher-portal（ai13 负责）— P1
| # |
依赖项 |
用途 |
状态 |
| 1 |
JWT RS256 签发 |
登录后获取 access_token + refresh_token |
✅ 已就绪 |
| 2 |
POST /v1/iam/login |
教师登录 |
✅ 已就绪 |
| 3 |
POST /v1/iam/refresh |
刷新 token |
✅ 已就绪 |
| 4 |
POST /v1/iam/logout |
登出 |
✅ 已就绪 |
| 5 |
GET /v1/iam/me |
获取当前用户信息 |
✅ 已就绪 |
| 6 |
GET /v1/iam/viewports |
获取视口配置（含 level + componentConfig） |
✅ 已就绪 |
| 7 |
GET /v1/iam/permissions/effective |
获取有效权限 |
✅ 已就绪 |
3.7 student-portal（ai14 负责）— P1
| # |
依赖项 |
用途 |
状态 |
| 1 |
JWT RS256 签发 |
学生登录 |
✅ 已就绪 |
| 2 |
POST /v1/iam/login |
学生登录 |
✅ 已就绪 |
| 3 |
PATCH /v1/iam/me |
更新个人资料 |
✅ 已就绪 |
| 4 |
POST /v1/iam/change-password |
修改密码 |
✅ 已就绪 |
3.8 parent-portal（ai15 负责）— P1
| # |
依赖项 |
用途 |
状态 |
| 1 |
JWT RS256 签发 |
家长登录 |
✅ 已就绪 |
| 2 |
POST /v1/iam/login |
家长登录 |
✅ 已就绪 |
| 3 |
GET /v1/iam/children |
获取绑定的学生列表 |
✅ 已就绪 |
| 4 |
GET /v1/iam/me |
获取家长个人信息 |
✅ 已就绪 |
3.9 admin-portal（ai16 负责）— P0
| # |
依赖项 |
用途 |
状态 |
| 1 |
GET /v1/iam/users |
用户管理列表（分页 + 搜索） |
✅ 已就绪 |
| 2 |
PATCH /v1/iam/users/:id |
用户更新 |
✅ 已就绪 |
| 3 |
PATCH /v1/iam/users/:id/status |
用户状态切换 |
✅ 已就绪 |
| 4 |
POST/PATCH/DELETE /v1/iam/roles |
角色 CRUD |
✅ 已就绪 |
| 5 |
POST/PATCH/DELETE /v1/iam/permissions |
权限 CRUD |
✅ 已就绪 |
| 6 |
POST/PATCH/DELETE /v1/iam/viewports |
视口 CRUD |
✅ 已就绪 |
| 7 |
POST /v1/iam/totp/enable / verify / disable |
TOTP 2FA 管理 |
✅ 已就绪 |
| 8 |
GET /v1/iam/audit |
审计日志查询 |
✅ 已就绪 |
4. 剩余工作
4.1 已完成
| 工作项 |
状态 |
| P2-P6 全部批次 |
✅ |
| 15 个 gRPC RPC |
✅ |
| REST CRUD 完整 |
✅ |
| TOTP 2FA |
✅ |
| 密码策略 + 历史重用 |
✅ |
| 审计日志 + Outbox |
✅ |
| Redis 权限缓存 + 指标 |
✅ |
| JWKS 端点 |
✅ |
| Docker 本地测试通过 |
✅ |
| typecheck + lint 零错误 |
✅ |
4.2 待办（非阻塞）
| # |
工作项 |
优先级 |
阻塞条件 |
| 1 |
单元测试 + 集成测试覆盖率 ≥ 80% |
P2 |
无 |
| 2 |
生产环境 JWT 密钥轮换流程 |
P3 |
生产部署前 |
| 3 |
Kafka topic 创建自动化（edu.iam.user.events / role.events / audit.created） |
P3 |
K8s 部署阶段 |
| 4 |
数据库迁移脚本（drizzle-kit） |
P3 |
生产部署前 |
5. 联调待办
| # |
联调项 |
对端模块 |
状态 |
| 1 |
api-gateway JWKS 真实验签 |
api-gateway (ai01) |
✅ 已就绪 |
| 2 |
push-gateway JWKS 真实验签 |
push-gateway (ai09) |
✅ 已就绪 |
| 3 |
teacher-bff gRPC 全量调用 |
teacher-bff (ai03) |
✅ 已就绪 |
| 4 |
student-bff GetUserProfile/UpdateProfile/ChangePassword |
student-bff (ai04) |
✅ 已就绪 |
| 5 |
parent-bff getUserInfo/getChildrenByParent/getViewports |
parent-bff (ai05) |
✅ 已就绪 |
| 6 |
admin-portal RBAC CRUD 全量 |
admin-portal (ai16) |
✅ 已就绪 |
| 7 |
teacher-portal 登录 + 视口 |
teacher-portal (ai13) |
✅ 已就绪 |
| 8 |
student-portal 登录 + 个人资料 |
student-portal (ai14) |
✅ 已就绪 |
| 9 |
parent-portal 登录 + 孩子列表 |
parent-portal (ai15) |
✅ 已就绪 |
本文件由 ai06 维护。iam 服务已全量就绪，所有下游模块可开始真实联调。
