docs: complete Chinese project documentation

docs/product/enterprise-identity.md

@@ -0,0 +1,106 @@
+# 企业身份接入与验收
+
+## 工程边界
+
+当前仓库已经提供企业身份工程基线：
+
+- OpenID Connect 授权码登录，服务端保存授权状态并校验 `state`、`nonce` 和 ID Token。
+- 身份提供方配置、客户端密钥加密保存、启停和安全审计。
+- 以 `(provider, subject)` 唯一绑定本地用户，不以可变邮箱作为默认身份主键。
+- 首次登录可创建无本地密码账号；停用账号不能通过企业登录恢复访问。
+- 企业组织声明只同步管理员显式登记的业务用户组映射，不覆盖其他手工用户组。
+- 标准化目录记录可幂等批量同步，并保存完成、部分成功或失败的运行结果。
+- LDAP 提供连接配置和标准化目录适配边界，尚未在应用进程内实现 LDAP 搜索或轮询。
+
+工程完成不等于企业环境验收完成。真实 IdP、LDAP 目录、网络出口、证书和组织声明仍需按本文
+最后的清单联调。
+
+## 部署配置
+
+1. 配置稳定的 `AI_CREDENTIAL_ENCRYPTION_KEY`。身份提供方密钥与模型、渠道凭据共用这套
+   Fernet 加密能力；密钥丢失后已有密文不可恢复。
+2. 将 `FRONTEND_APP_URL` 设置为用户访问的前端 HTTPS 根地址。
+3. 将 `OIDC_CALLBACK_BASE_URL` 设置为企业 IdP 可访问的后端 HTTPS 根地址。留空时，服务端
+   会从当前请求推导根地址。
+4. 执行迁移和治理初始化：
+
+   ```bash
+   python manage.py migrate
+   python manage.py bootstrap_governance
+   ```
+
+5. 在“系统治理 → 企业身份”新增 OIDC 提供方，并在 IdP 登记精确回调地址：
+
+   ```text
+   https://<后端域名>/api/identity/auth/oidc/<provider-slug>/callback
+   ```
+
+生产 OIDC 地址必须使用 HTTPS；仅在 Django 调试模式下允许本机 `localhost` 或
+`127.0.0.1` 使用 HTTP。
+
+## OIDC 声明
+
+默认声明映射如下，可在治理页按企业 IdP 的实际声明修改：
+
+| 平台字段 | 默认声明 | 说明 |
+|---|---|---|
+| 稳定身份 | `sub` | 必填，同一提供方内不可变化 |
+| 登录账号 | `preferred_username` | 首次创建本地账号时使用，冲突会生成唯一后缀 |
+| 邮箱 | `email` | 用于资料同步，不默认用于绑定已有账号 |
+| 显示名称 | `name` | 同步到本地显示名称 |
+| 企业组织 | `groups` | 只匹配已登记的组织映射 |
+
+默认禁止按邮箱自动链接已有账号，以避免邮箱声明错误导致账号接管。确需迁移存量账号时，应由
+管理员评估 IdP 的邮箱验证策略后，在提供方 `configuration` 中显式启用
+`allow_email_linking`，并先用脱敏账号演练。
+
+## 目录适配器契约
+
+治理页和 `POST /api/identity/providers/{id}/directory-sync` 接收标准化成员数组：
+
+```json
+{
+  "records": [
+    {
+      "subject": "employee-1001",
+      "username": "zhangsan",
+      "email": "zhangsan@example.com",
+      "display_name": "张三",
+      "active": true,
+      "groups": ["IT-Support"]
+    }
+  ]
+}
+```
+
+- `subject` 是必填稳定标识。
+- 同一提供方和 `subject` 重复提交只会更新原身份。
+- 单次最多 1000 条，单条冲突会记录在同步运行中，不会伪造整批成功。
+- `active=false` 会停用对应本地账号。
+- 连接 LDAP、HR 或 IAM 的可信适配器负责读取企业目录并转换为上述结构；浏览器和审计日志
+  不保存 Bind password。
+
+## 接口与权限
+
+| 接口 | 权限/用途 |
+|---|---|
+| `GET /api/identity/auth/providers` | 匿名读取已启用 OIDC 登录入口 |
+| `GET /api/identity/auth/oidc/{slug}/start` | 启动授权码登录 |
+| `GET /api/identity/auth/oidc/{slug}/callback` | IdP 回调、身份同步并建立 Django 会话 |
+| `GET/POST/PATCH /api/identity/providers` | `system.setting.manage` 管理提供方 |
+| `GET/POST/DELETE .../group-mappings` | `system.setting.manage` 管理受控组织映射 |
+| `POST .../directory-sync` | `system.setting.manage` 执行标准化目录同步 |
+
+密钥不会通过管理接口返回；操作审计只记录修改字段、提供方、计数和错误类型，不记录令牌、
+Client secret 或 Bind password。
+
+## 真实企业环境验收
+
+- [ ] IdP 发现文档、JWKS 和令牌端点均通过受信任 HTTPS 证书访问。
+- [ ] 正常授权码登录成功，篡改 `state`、错误 `nonce`、过期或错误签名 ID Token 均被拒绝。
+- [ ] 同一 `sub` 重复登录只关联一个本地账号，账号名冲突不会串号。
+- [ ] 停用提供方、停用本地账号和无效组织声明都按预期阻断或忽略。
+- [ ] 企业组织新增、移除后只改变已登记映射对应的业务用户组。
+- [ ] IdP 不可用时，本地受控管理员账号仍可完成应急登录。
+- [ ] 登录成功、失败、提供方修改、映射变更和目录同步均可在审计日志追溯。
+- [ ] LDAP/目录适配器在真实目录完成分页、超时、证书、增量和停用成员演练。