# 用户与组织架构模块（Organization & IAM）

> **负责人**: FFOA 开发团队  
> **模块标识**: `organization`  
> **数据库 Schema**: `platform_iam` (用户/角色/权限) + `corp_hr` (组织架构)  
> **架构版本**: ✅ v2.4 (Entra ID SSO 登录 + OIDC 授权码流程 + JIT 建账号)  
> **状态**: ✅ 已完成  
> **最后更新**: 2026-05-19

---

## 📋 文档导航

| 文档 | 状态 | 最后更新 |
|------|------|---------|
| [产品需求文档](./01-prd.md) | ✅ | 2025-12-26 |
| [用户场景](./02-user-journey.md) | ✅ | 2025-12-26 |
| [架构设计](./03-architecture.md) | ✅ | 2025-12-26 |
| [状态机](./04-state-machine.md) | ✅ | 2025-12-26 |
| [UI 交互规范](./05-ui-interaction-spec.md) | ✅ | 2025-12-26 |
| [数据模型](./06-data-model.md) | ✅ | 2025-12-26 |
| [API 接口文档](./07-api.md) | ✅ | 2025-12-26 |
| [错误码](./08-error-codes.md) | ✅ | 2025-12-26 |
| [测试场景](./09-test-scenarios.md) | ✅ | 2025-12-26 |
| [E2E 测试规范](./10-e2e-test-spec.md) | ✅ | 2026-01-05 |
| [变更日志](./99-changelog.md) | ✅ | 2025-12-26 |

**状态说明**:
- ✅ Completed/Approved - 已完成并通过评审
- 🚧 In Progress/Draft - 编写中
- ❌ Not Started - 未开始
- 📝 Need Update - 需要更新
- 📋 Planned - 已规划待执行

---

## 📌 概述

用户与组织架构模块是 FFOA 平台的核心基础设施，负责用户管理、组织架构和身份认证。

> **权限系统已拆分为独立模块**：权限与访问控制（RBAC、Scope、DataScope）的完整文档见 [docs/modules/iam/](../iam/)。

### ⚠️ 核心架构设计

> **当前版本**: ✅ **v2.4 - Entra ID SSO 登录（OIDC 授权码流程）**

**v2.4 新增功能** ⭐:
- ✅ Entra ID SSO 登录（OIDC 授权码 + PKCE）
- ✅ JIT 自动建账号（域名白名单 `SSO_ALLOWED_DOMAINS` 命中）
- ✅ 已有账号首次 SSO 自动回填 `externalId` / `externalSource`
- ✅ 与本地密码登录、LDAP 登录**三通道并存**
- ✅ 2 个新 API 端点（`/auth/sso/start` + `/auth/sso/callback`）
- ✅ **8 个新错误码**（错误码总数 51 → 59）：核心 5 个（`SSO_DOMAIN_NOT_ALLOWED` / `SSO_TOKEN_INVALID` / `SSO_EMAIL_MISSING` / `SSO_BINDING_CONFLICT` / `SSO_PROVIDER_UNAVAILABLE`）+ Entra error query 映射 3 个（`SSO_USER_CANCELLED` / `SSO_CONSENT_REQUIRED` / `SSO_PROVIDER_REJECTED`）；状态拒绝路径复用现有 `IAM_USER_SUSPENDED`
- ✅ **5 个新审计事件**（audit 事件总数 4 → 5）：`SSO_LOGIN_SUCCESS` / `SSO_JIT_CREATED` / `SSO_BINDING_FILLED` / `SSO_BINDING_UPGRADED_FROM_LDAP`（v2.4 新增第 5 个，LDAP 历史绑定升级专属） / `SSO_BINDING_CONFLICT`
- ✅ **OIDC 实现库**：`openid-client`（OpenID Foundation 官方，业界事实标准；自带 discovery / JWKS rotation / PKCE / nonce / clock skew ±5min）
- ✅ **callback 响应协议**：成功 302 至 `${sso_redirect}#accessToken=<jwt>&refreshToken=<jwt>`（URL fragment 注入）；失败 302 至 `/login?ssoError=<CODE>`（**不**用 JSON body / **不**用 HttpOnly Cookie 存 token）
- ✅ **Schema 增量**：本期含 1 个 prisma migration（`AuditAction` enum +5 / email lower-case backfill SQL）；**推翻** v2.4 早期"无 schema 变更"声明
- ⚠️ **推翻** v2.1.1「Entra 仅同步、不作为身份源」决策；v2.4 起 Entra 同时承担同步通道 + SSO 身份源双重职责
- 📋 二期承诺：通过 SCIM 实现 Entra 禁用 → FFOA session < 5 分钟失效（关闭本期 ≤ 24h 同步窗口）

**v2.1.1 历史功能**（保留）:
- ✅ 身份源管理（LOCAL/LDAP/ENTRA）
- ✅ 登录安全说明（失败锁定暂不启用）
- ✅ 基于身份源的密码管理限制
- ✅ 密码复杂度要求（8位+3种字符+特殊字符）

**v2.1 架构（当前）**:
```
数据模型：
- Organization 表（独立的组织实体）
- Department 表（所有部门都归属一个组织）
  - organizationId 字段关联到 Organization
  - parentId 用于部门层级
- UserDepartment 表（用户-部门关联）
  - organizationId 冗余字段（性能优化）

示例：
Organization: FF China (id=org-1)
  ├── Department: 技术部 (organizationId=org-1, parentId=null)
  │   ├── Department: 前端组 (organizationId=org-1, parentId=技术部)
  │   └── Department: 后端组 (organizationId=org-1, parentId=技术部)
  └── Department: 产品部 (organizationId=org-1, parentId=null)

Organization: FF USA (id=org-2)
  ├── Department: 销售部 (organizationId=org-2, parentId=null)
  └── Department: 市场部 (organizationId=org-2, parentId=null)
```

**关键特性**:
1. ✅ 独立的 `Organization` 表
2. ✅ Department 通过 `organizationId` 归属组织
3. ✅ UserDepartment 包含 `organizationId` 冗余字段
4. ✅ 组织支持特有属性（法人信息、财务配置等）

**架构优势**:
- ✅ **性能**: 权限查询无需递归，速度提升 10倍
- ✅ **隔离**: 物理隔离替代逻辑隔离，数据更安全
- ✅ **扩展**: 组织特有属性易于添加（legalName, taxId 等）
- ✅ **简洁**: 区域仅与组织关联，架构更清晰
- ✅ **语义**: Organization 是一等公民，概念更清晰

### 核心功能

1. **用户管理** - 用户信息、认证、状态管理、身份源管理（v2.1.1）
2. **组织架构** - 部门、岗位、汇报关系
3. **权限控制** - RBAC + PBAC 双重权限模型
4. **角色管理** - 系统角色、流程角色
5. **多部门归属** - 支持用户同时属于多个部门
6. **区域管理** - 多区域组织架构支持
7. **身份认证** - JWT、LDAP/AD、LOCAL（v2.1.1 增强）
8. **外部同步** - Microsoft Entra ID 用户同步（仅信息同步，登录走 LDAP/AD）
9. **登录安全** - 失败锁定暂不启用（由 LDAP/AD 侧处理）

### 业务价值

- **统一身份**: 统一的用户身份和权限管理
- **灵活组织**: 支持复杂的组织架构和多部门归属
- **安全可控**: 细粒度的权限控制和审计
- **企业集成**: 支持 LDAP/AD 和 Azure Entra ID

---

## 🏗️ 技术信息

### 代码位置

- **前端**: `frontend/src/app/(authenticated)/organization/` - 组织管理页面
- **后端**: `backend/src/modules/organization/`
  - auth/ - 认证子模块（JWT、Guards）
  - ldap/ - LDAP/AD 认证
  - entra/ - Azure Entra ID 同步
  - users/ - 用户管理
  - departments/ - 部门管理
  - organizations/ - 组织管理（v2.0 新增）
  - user-departments/ - 多部门归属
  - regions/ - 区域管理
  - positions/ - 岗位管理
  - roles/ - 系统角色管理
  - permissions/ - 权限管理
  - workflow-roles/ - 流程角色管理
  - guards/ - 模块级守卫
- **数据库**: `platform_iam` Schema (认证权限) + `corp_hr` Schema (组织架构)

### API 端点

- **Base URL**: `/api/v1/`
- **权限格式**: `{resource}:{action}[:{scope}]`
  - Scope: `all`（当前仅实现 `all`）
  - 示例: `user:read`, `user:update`, `role:assign`
- **主要接口**: 
  - 组织管理: `/api/v1/organizations` (v2.0 新增)
  - 用户管理: `/api/v1/users`
  - 部门管理: `/api/v1/departments`
  - 角色管理: `/api/v1/roles`
  - 权限管理: `/api/v1/permissions`
  - 流程角色: `/api/v1/workflow-roles`
  - 组织架构同步: `/api/v1/organization/sync`
  - 区域管理: `/api/v1/regions`
  - 认证: `/api/v1/auth/login`, `/api/v1/auth/logout`, `/api/v1/auth/refresh`
  - SSO 登录（v2.4 新增）: `/api/v1/auth/sso/start`, `/api/v1/auth/sso/callback`
  - 多部门归属: `/api/v1/users/:id/departments`
- **总计**: 79 个接口（v2.4 +2 SSO 端点）

### 身份源与认证（v2.1.1）

**身份源类型**:
- **LOCAL**: 本地用户，支持密码管理
- **LDAP**: LDAP/AD 认证用户，密码由外部系统管理
- **ENTRA**: 仅用于同步用户信息（不作为身份源，登录走 LDAP/AD）

**认证流程**:
- LOCAL 用户：用户名/密码 → 验证数据库 → JWT Token
- LDAP 用户：用户名/密码 → LDAP 认证 → JWT Token
- Entra 同步用户：按 LDAP 用户认证流程登录

**登录安全**:
- 当前未启用失败锁定
- LDAP/AD 账户锁定由外部目录服务处理

### 技术栈

- **前端**: Next.js 14 + TypeScript + Tailwind CSS
- **后端**: NestJS + Prisma + PostgreSQL
- **认证**: JWT + Passport
- **外部集成**: LDAP/AD + Azure Entra ID
- **缓存**: Redis（Token 黑名单）（v2.1.1）

---

## 🔗 相关模块

### 核心依赖

- **PostgreSQL** - 数据存储
- **JWT** - 令牌认证
- **Passport** - 认证策略

### 已拆分文档域

- [钉钉模块](../dingtalk/README.md) - 钉钉同步、员工同步、审批修复、年假洞察文档已独立维护

### 被依赖模块

- **所有业务模块** - 都依赖组织架构模块进行权限控制
- [表单引擎](../form-engine/README.md) - 使用组织架构信息
- [审批引擎](../approval-engine/README.md) - 使用组织架构和流程角色
- [绩效管理模块](../performance/README.md) - 使用用户和汇报关系与组织架构

---

## 🏗️ 模块架构

```
OrganizationModule
├── AuthModule      # 认证（依赖 LdapModule）
├── LdapModule      # LDAP/AD 认证
├── EntraModule     # Azure Entra ID 同步
├── OrganizationsModule  # 组织管理（v2.0 新增）
└── PrismaModule    # 数据库访问
```

### 权限模型

**RBAC + PBAC 双重控制**

- **RBAC (Role-Based Access Control)**: 基于系统角色的权限控制
- **PBAC (Permission-Based Access Control)**: 基于细粒度权限的控制

详见 [PRD 权限模型章节](./01-prd.md)

### 预定义角色

- **Administrator**: 系统管理员 - 拥有所有权限
- **Employee**: 普通员工 - 基础查看权限

---

## 🚀 快速开始

### 核心特性

#### 1. 多部门归属
支持用户同时属于多个部门，每个归属有独立的：
- 岗位（Position）
- 汇报关系（Reports To）
- 主部门标记（Is Primary）

**API**: `/api/v1/users/:id/departments` ✅

详见：[用户场景 - 多部门归属](./02-user-journey.md#场景-4-多部门归属)

#### 2. 多区域支持
支持多区域组织架构：
- **CN** (China) - 中国区
- **US** (United States) - 美国区
- **UAE** (United Arab Emirates) - 阿联酋区

v2.0 架构：区域与组织关联（OrganizationRegion），部门通过组织继承区域信息。

详见：[PRD - 多区域支持](./01-prd.md#多区域支持)

#### 3. 认证方式（v2.4 更新）
1. **本地认证（LOCAL）**: 用户名/密码 + JWT，支持密码修改（v2.1.1）
2. **LDAP/AD**: 企业目录服务集成，密码由 LDAP/AD 管理（v2.1.1）
3. **Azure Entra ID（SSO 登录通道 + 同步通道）** ⭐ v2.4：
   - **SSO 登录通道**：OIDC 授权码流程（前端浏览器跳转 Microsoft 完成认证），自签 FFOA JWT
   - **同步通道**：定时拉取 Entra 用户信息，与原有同步逻辑一致
   - 推翻 v2.1.1「Entra 仅同步、不作为身份源」决策

**v2.4 身份源 / 通道映射**:
| 身份源 / 通道 | 创建方式 | 认证方式 | 密码管理 | v2.4 变化 |
|--------|---------|---------|---------|---------|
| **LOCAL** | 本地创建 | 本地认证 | 可修改密码 | 不变 |
| **LDAP** | Entra 同步创建 | LDAP 认证 | 不可修改（由 LDAP/AD 管理） | 不变 |
| **ENTRA** | 同步通道 + JIT 建账号（v2.4） | **SSO 登录通道（OIDC）+ 同步通道** | 不适用（依赖 Entra） | ⭐ 新增 SSO 登录角色 |

详见：[用户场景 - 用户登录](./02-user-journey.md#场景-9-用户登录) 和 [用户场景 - 修改密码](./02-user-journey.md#场景-10-修改密码)

#### 4. 双重权限模型
- **RBAC** (Role-Based Access Control): 基于系统角色
- **PBAC** (Permission-Based Access Control): 基于细粒度权限

详见：[PRD - 权限模型](./01-prd.md#权限模型)

#### 5. 登录安全说明（v2.1.1 新增）⭐
- 当前未启用失败锁定机制
- LDAP/AD 账户锁定由外部目录服务处理

**密码复杂度要求**:
- 最少 8 位字符
- 包含至少 3 种字符类型（大写、小写、数字、特殊字符）
- 必须包含特殊字符

详见：[PRD - 登录安全](./01-prd.md#功能8-身份认证)

---

## 🔐 权限系统

### v2.1 组织级权限隔离 ⭐️

**核心特性**：
- ✅ 角色按**组织**隔离，而非区域
- ✅ 用户在不同组织可以有不同角色
- ✅ 支持全局角色（系统管理员）
- ✅ **两个维度**的权限控制：`organizationId`（横向隔离）+ `scope`（纵向控制）

**快速示例**：
```typescript
// 用户在 FF China 是 HR管理员（可以管理整个组织）
UserRole: { 
  userId: "user-001", 
  roleId: "role-hr", 
  organizationId: "org-ff-china"  // ← 横向隔离
}
Role.permissions: ["user:read:organization"]  // ← 纵向控制（scope）

// 同一用户在 FF USA 是普通员工（只能看自己）
UserRole: { 
  userId: "user-001", 
  roleId: "role-employee", 
  organizationId: "org-ff-usa" 
}
Role.permissions: ["user:read:own"]

// 系统管理员（跨所有组织）
UserRole: { 
  userId: "admin-001", 
  roleId: "role-admin", 
  organizationId: null  // ← null = 全局
}
Role.permissions: ["user:read"]
```

**📚 详细文档**：
- [完整权限模型和规范](./01-prd.md#权限模型) - 业务需求、使用场景、最佳实践
- [权限系统技术架构](./03-architecture.md#权限校验流程) - 实现细节、代码示例
- [权限 Scope 控制系统](./03-architecture.md) - v2.1 完整实现指南（集成在架构文档中）⭐️
- [API 接口文档](./07-api.md) - 权限相关 API

---

### 权限模型概览

**RBAC + PBAC 双重控制**：
- **RBAC** (Role-Based): 基于系统角色的权限控制
- **PBAC** (Permission-Based): 基于细粒度权限的控制

**权限格式**：
```
{resource}:{action}[:{scope}]

示例：
- user:read:own          → 查看自己
- user:read:department   → 查看本部门
- user:read:organization → 查看本组织（v2.1 按 organizationId 隔离）
- user:read              → 查看所有组织
```

**权限范围（Scope）**：

| Scope | 说明 | 典型角色 |
|-------|------|---------|
| `own` | 仅自己的数据 | 普通员工 |
| `department` | 本部门数据 | 部门经理 |
| `organization` | 本组织数据 | HR 管理员 |
| `all` | 全局数据 | 系统管理员 |

**v2.1 关键优化**：
- `organizationId` 提供**横向隔离**（组织之间互不影响）
- `scope` 提供**纵向控制**（组织内部数据访问范围）
- 两个维度配合，实现精细的权限控制

**详细说明**：参见 [PRD - 权限管理](./01-prd.md#功能5-权限管理v21-核心改进) 和 [架构设计 - 权限系统](./03-architecture.md#权限系统)

---

### Guards（守卫）

位于 `backend/src/modules/organization/auth/guards/`：

- **JwtAuthGuard**: JWT 令牌验证
- **PermissionsGuard**: 细粒度权限验证（v2.1 支持组织上下文）
- **RolesGuard**: 角色验证

通过 `OrganizationModule` 导出供其他模块使用。

---

## 🧪 测试

### 测试覆盖

- **单元测试**: 60% - 核心业务逻辑测试
- **集成测试**: 30% - API 和数据库集成测试
- **E2E 测试**: 10% - 完整用户流程测试

### 运行测试

```bash
# 后端单元测试
cd testing && npm run test:backend:unit

# 后端集成测试
cd testing && npm run test:backend:integration

# E2E 测试
按 `docs/modules/organization/10-e2e-test-spec.md` 执行（Agent + Playwright MCP）

# 测试覆盖率报告
cd testing && npm run test:backend:all:cov
```

### 测试文档

详见 [测试场景文档](./09-test-scenarios.md) - 包含完整的测试用例和测试策略。

---

## 📚 详细文档

### 需求与设计
- [产品需求文档](./01-prd.md) - 产品目标、用户需求、功能定义（v2.1 按模板重构）⭐️
- [用户场景](./02-user-journey.md) - 用户旅程、操作流程、交互设计
- [架构设计](./03-architecture.md) - 技术架构、**权限系统实现**（v2.1 更新）⭐️
- [状态机](./04-state-machine.md) - 用户状态流转、部门归属管理

### 实现与规范
- [UI 交互规范](./05-ui-interaction-spec.md) - UI组件设计、交互规范
- [数据模型](./06-data-model.md) - 完整数据库设计、Prisma Schema（v2.1 更新）
- [API 接口文档](./07-api.md) - 完整 API 定义、权限矩阵（v2.1 更新）

### v2.1 专项文档
- [架构设计](./03-architecture.md) - 组织级权限隔离与 Scope 控制实现 ⭐️
- [API 接口文档](./07-api.md) - 组织级权限相关 API 变更 ⭐️

### 运维与测试
- [错误码](./08-error-codes.md) - 错误码定义、处理建议
- [测试场景](./09-test-scenarios.md) - 单元测试、集成测试、E2E测试
- [E2E 测试规范](./10-e2e-test-spec.md) - 页面级测试明细与选择器清单
- [变更日志](./99-changelog.md) - 版本历史和重要变更（v2.1 更新）

---

## 🎯 开发状态

### 当前版本：v2.4

### 已完成功能

- ✅ 用户管理（CRUD、状态管理）
- ✅ 组织管理（CRUD、组织信息）(v2.0 新增)
- ✅ 部门管理（层级结构）
- ✅ 岗位管理
- ✅ 区域管理
- ✅ 角色和权限管理（RBAC + PBAC）
- ✅ 流程角色管理
- ✅ 多部门归属（完整 CRUD）
- ✅ JWT 认证
- ✅ LDAP/AD 集成
- ✅ Azure Entra ID 同步
- ✅ 权限 Guards（Jwt、Permissions、Roles）
- ✅ API 权限控制
- ✅ **组织级权限隔离**（v2.1 新增）
- ✅ **身份源管理**（LOCAL/LDAP/ENTRA）（v2.1.1 新增）⭐
- ✅ **登录安全说明**（失败锁定暂不启用）（v2.1.1 新增）⭐
- ✅ **密码管理限制**（基于身份源）（v2.1.1 新增）⭐

### 核心特性

- ✅ **多部门归属**: 用户可同时属于多个部门
- ✅ **多组织支持**: 独立的组织表，支持多组织架构（v2.0）
- ✅ **组织级权限**: 角色按组织隔离，支持全局角色（v2.1）⭐️
- ✅ **身份源管理**: LOCAL/LDAP/ENTRA 三种身份源（v2.1.1）⭐️
- ✅ **登录安全**: 失败锁定暂不启用（v2.1.1）⭐️
- ✅ **多区域支持**: CN/US/UAE 多区域架构
- ✅ **外部同步**: Microsoft Entra ID 用户同步（登录走 LDAP/AD）
- ✅ **细粒度权限**: 资源级别的权限控制
- ✅ **流程角色**: 支持审批流程中的动态角色
- ✅ **高性能**: 权限查询性能提升 10倍（v2.0）

### v2.1 重点改进

- ✅ **权限系统升级**: 从区域隔离升级为组织隔离
- ✅ **Prisma Schema 更新**: UserRole 表添加 organizationId 字段
- ✅ **文档完善**: 新增权限系统详细指南
- ✅ **代码实现**: PermissionsGuard 支持组织上下文（已实现）
- ✅ **API 更新**: 角色分配 API 支持组织参数（已实现）

### v2.1.1 重点改进 ⭐

- ✅ **身份源管理**: 支持 LOCAL/LDAP/ENTRA 三种身份源
- ✅ **登录安全**: 失败锁定暂不启用（LDAP/AD 侧处理）
- ✅ **密码管理**: 基于身份源的密码管理限制（只有 LOCAL 用户可修改）
- ✅ **密码策略**: 8位+3种字符+特殊字符的复杂度要求
- ✅ **错误码**: 对齐 IAM 错误码说明
- ✅ **UI 规范**: 新增登录页和修改密码页完整规范
- ✅ **测试场景**: 新增 15 个测试场景（身份源、密码修改）
- ✅ **文档更新**: 9 个核心文档升级到 v2.1.1

### v2.4 重点改进（新增）⭐

- ✅ **Entra ID SSO 登录**: OIDC 授权码 + PKCE 流程，浏览器跳转 Microsoft 完成认证，自签 FFOA JWT
- ✅ **JIT 自动建账号**: 域名命中 `SSO_ALLOWED_DOMAINS` 白名单 → 自动建 User（Employee 角色 + 默认组织）
- ✅ **双通道并存**: 本地密码登录 / LDAP 登录 / Entra SSO 三通道并存，互不影响
- ✅ **不迁移 source 字段**: SSO 成功仅回填 `externalId` + `externalSource='entra'`，保持现有同步逻辑不变
- ✅ **5 个新错误码**: `SSO_DOMAIN_NOT_ALLOWED` / `SSO_TOKEN_INVALID` / `SSO_EMAIL_MISSING` / `SSO_BINDING_CONFLICT` / `SSO_PROVIDER_UNAVAILABLE`
- ✅ **4 个新审计事件**: `SSO_LOGIN_SUCCESS` / `SSO_JIT_CREATED` / `SSO_BINDING_FILLED` / `SSO_BINDING_CONFLICT`
- ⚠️ **决策推翻**: v2.1.1「Entra 仅同步、不作为身份源」 → v2.4「Entra 同时是同步通道 + SSO 身份源」
- 📋 **二期承诺**: 通过 SCIM 协议关闭 ≤ 24h 同步窗口，Entra 禁用 → FFOA session < 5 分钟失效

---

## 📊 模块统计

| 指标 | 数量 |
|------|------|
| **子模块** | 14个 |
| **API 端点** | 79（v2.4 +2 SSO 端点）|
| **数据表** | 17+ |
| **权限点** | 60+ |
| **预定义角色** | 2个 |
| **支持区域** | 3个 |
| **身份源类型** | 3个（LOCAL/LDAP/ENTRA；v2.4 起 ENTRA 同时作 SSO 登录通道）|
| **登录通道** | 3个（LOCAL / LDAP / Entra OIDC SSO，v2.4 +1）|
| **错误码** | 51个（v2.4 新增 5 个 SSO_* 错误码，详见 08-error-codes）|
| **审计事件（SSO 相关）** | 4个（SSO_LOGIN_SUCCESS / SSO_JIT_CREATED / SSO_BINDING_FILLED / SSO_BINDING_CONFLICT）|

---

## 👥 贡献者

- **创建者**: FFOA Team
- **维护者**: Backend Team
- **最后更新**: 2026-05-19

---

## 📖 文档完整性

| 文档类型 | 完成度 | 说明 |
|---------|--------|------|
| 需求文档 | 100% | PRD 完整，包含所有功能需求 |
| 用户场景 | 100% | 详细用户旅程和操作流程 |
| 架构设计 | 100% | 完整技术架构和设计决策 |
| 状态机 | 100% | 用户和实体状态流转规则 |
| UI规范 | 100% | 所有页面规范已完善 |
| 数据模型 | 100% | 完整数据库设计和Schema |
| API文档 | 100% | 77 个 API 接口定义 |
| 错误码 | 100% | 完整错误码和处理建议 |
| 测试场景 | 100% | 单元/集成/E2E测试用例 |

---

**创建时间**: 2025-11-01  
**更新时间**: 2026-05-19  
**状态**: ✅ v2.4 Entra ID SSO 登录架构落地（OIDC 授权码流程 + JIT 建账号 + 三通道并存）  
**版本**: v2.4 (Entra ID SSO 登录)