# 数据对外开放接口层 - 产品需求文档

> **module**: db-external-access
> **doc_type**: PRD
> **status**: Active
> **owner**: FFOA Team
> **upstream_docs**: 无（PRD 是依赖链起点）
> **last_verified**: 2026-04-24

---

## 目标与问题

### 要解决的问题

- 其他内部系统需要访问本平台数据（如组织架构、考勤记录、人员信息），目前无正式通道
- 直接共享数据库连接串风险极高：schema 演进会静默破坏接入方、无审计、权限无法细粒度控制
- 缺乏对接入方的身份识别与吊销能力

### 项目目标

提供一套**内部 API 接入层**，使其他内部系统可以通过标准 HTTP 接口安全读取本平台数据，不暴露数据库直连，支持细粒度权限与完整审计。

### 成功标准

- 接入方只需一个 API Key + HTTP 客户端即可对接，无需了解数据库结构
- 任意接入方的访问均有日志可查（谁、何时、访问了哪些接口、返回多少条）
- 敏感字段（手机号、身份证等）不通过接口泄露
- 单个 Key 被吊销后，对应接入方立即无法访问，不影响其他 Key

---

## 功能边界

### In-scope（V1）

**API Key 管理（管理员操作）**：
- 创建 API Key：指定名称、归属接入方、绑定数据角色
- 查看 Key 列表（不展示明文，只展示前缀）
- 启用 / 停用 Key
- 删除 Key

**数据读取接口（接入方调用）**：
- 组织架构域：查询组织列表、组织成员列表
- 人员域：查询用户基本信息（脱敏）
- 考勤域：查询会议考勤汇总、现场考勤汇总（⚠️ 待评估具体字段）

**安全机制**：
- 认证：`X-Api-Key` Header，SHA-256 哈希后存库，明文仅创建时返回一次
- 授权：每个 Key 绑定一个或多个数据角色，角色控制可访问的接口域
- 限流：每个 Key 默认 100 req/min，可按需调整
- 审计日志：每次调用自动写入 `DataAccessLog`

### Out-of-scope（V1 不做）

- 写操作（创建/修改/删除数据）—— 本层只读
- GraphQL / WebSocket 接口
- 外部第三方（互联网）接入 —— V1 仅限内网/内部服务
- 数据库直连方案（Read Replica）—— 按需评估后单独立项
- 字段级行级安全策略（RLS）—— V2 按需扩展
- 接入方自助申请流程 —— V2 按需扩展

---

## 接入方场景

| 场景 | 接入方 | 需要的数据 | 数据角色 |
|------|--------|-----------|---------|
| 报表/BI 平台 | 内部数据分析系统 | 组织架构、考勤汇总 | `org-readonly` + `attendance-readonly` |
| 第三方 HR 系统同步 | 人力资源系统 | 用户信息（脱敏）、组织架构 | `org-readonly` + `user-readonly` |
| 自动化工具 | 内部 RPA / 脚本 | 组织成员列表 | `org-readonly` |

---

## 安全要求

### 认证

- 每次请求必须携带 `X-Api-Key: <key>` Header
- Key 格式：`doa_` 前缀 + 32 位随机字符串（示例：`doa_xK9mN2pQrTvW8yZaAbCdEfGhIj3lMn4o`）
- 服务端存储：SHA-256(key)，不存明文
- Key 创建后明文仅在 API 响应中返回一次，之后不可再查

### 授权 - 数据角色定义

| 数据角色 code | 可访问接口域 | 说明 |
|--------------|------------|------|
| `org-readonly` | `/data/organizations/**` | 组织架构数据 |
| `user-readonly` | `/data/users/**` | 用户基本信息（脱敏后） |
| `attendance-readonly` | `/data/attendance/**` | 考勤汇总数据 |
| `full-readonly` | 以上全部 | 仅授予高度信任的内部系统 |

### 脱敏规则

| 字段 | 规则 |
|------|------|
| 手机号 | 只返回前 3 位 + `****` + 后 4 位，如 `138****5678` |
| 邮箱 | 只返回用户名前两位 + `***@domain`，如 `zh***@example.com` |
| 身份证号 | 不返回 |
| 密码相关字段 | 不返回 |

### 限流

- 默认：100 req/min / Key
- 超限返回 HTTP 429，Header 包含 `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`

### 审计

每次请求记录以下字段（不可删除，保留至少 180 天）：
- API Key ID（不记明文）
- 接口路径 + HTTP Method
- 来源 IP
- 请求时间、响应耗时
- 返回数据条数
- HTTP 状态码

---

## 术语表

| 术语 | 说明 |
|------|------|
| Consumer | 数据接入方（一个内部系统 = 一个 Consumer） |
| API Key | 接入方的凭证，格式为 `doa_` + 32 位随机串 |
| DataRole | 数据访问角色，控制可访问的接口域 |
| AccessLog | 每次调用的审计记录 |
| 脱敏 | 接口层主动过滤/掩码敏感字段，不依赖数据库层控制 |