IAM 项目指南

IAM 是基于 Better Auth 的企业统一身份认证中心，作为 OAuth 2.1 / OpenID Connect Provider，为内部应用提供统一登录、用户身份、应用准入与角色 claims。

当前技术栈

• Web：Next.js 16、React 19、Tailwind CSS 4、shadcn/ui、TanStack Query/Table
• API：Hono、tRPC、Better Auth 1.7.1
• 数据：PostgreSQL（Neon）、Drizzle ORM
• 基础设施：Cloudflare Workers、Service Binding、R2、Email Binding
• 工程化：pnpm 10、Turborepo、oxlint、oxfmt、Vitest、Playwright

系统架构

graph LR
    Browser[浏览器] --> Web[iam-web / Next.js]
    Web -->|AUTH_API Service Binding| Server[iam-api / Hono]
    Server --> Auth[Better Auth + OAuth Provider]
    Server --> TRPC[tRPC]
    Server --> R2[R2 UPLOADS]
    Auth --> DB[(PostgreSQL)]
    TRPC --> DB
    Auth --> Email[Cloudflare EMAIL]
    WeCom[企业微信] --> Server

生产公开入口统一为 https://iam.cq-i.cn。浏览器访问同源 /api/*，由 Web Worker 转发到 iam-api，避免认证 Cookie 和 issuer 跨域分裂。

指南导航

了解项目

• 系统概览：当前已实现能力与产品边界
• 产品需求说明：五项 P0 核心功能与验收标准，以及 P1、P2 后续规划
• 快速开始：环境变量、数据库和本地启动
• 项目结构：应用、package 与依赖方向
• 架构边界改造：前后端边界决策记录

开发与验证

• 开发工作流：命令、代码约定与调试
• API 开发：tRPC 和文件接口
• 数据库管理：schema 与 migration 流程
• 测试指南：Vitest 与 Playwright
• 版本管理：Changesets 发布流程

认证与集成

• 认证系统：登录、邮件、会话、限流和平台角色
• OAuth 2.1 Provider：客户端、PKCE、claims 与授权流程

应用对接

• 对接方式总览：身份登录与账户与访问权限同步两个对接面，以及该读哪篇文档
• 账户与访问权限同步协议：HMAC 签名头、规范串、事件负载与快照接口
• CRM 后端与 MySQL 接入 IAM：CRM Laravel 后端和 MySQL 数据库接入统一身份认证的实施与验收清单
• CRM 账户同步本地验收：IAM 部门授权、CRM 角色映射、首次登录与撤权的本地配置和验收步骤
• OA 后端与 MySQL 接入 IAM：oacn-api、oain-web 和 OA MySQL 接入统一身份认证的接口、迁移与验收清单
• 考试系统 OIDC 接入：第三方系统接入示例
• OIDC 排障报告：签名上下文与 Cookie 链路排查

部署与维护

• 部署指南：Cloudflare 双 Worker 部署
• 常见任务：常见开发和运行问题
• UI 组件库：现有前端组件用法

项目状态和后续工作以仓库根目录 TODO.md 为准。