# db-external-access 模块

企业内部数据开放接口层（Internal Data Open API），为其他内部应用提供安全、可控、可审计的数据读取能力，不暴露数据库直连。

## 当前状态

| 阶段 | 状态 | 日期 |
|------|------|------|
| 需求文档（v1） | ✅ 完成 | 2026-04-24 |
| 数据模型（v1） | ✅ 完成 | 2026-04-24 |
| API 规格（v1） | ✅ 完成 | 2026-04-24 |
| 后端实现 | ⏳ 待实现 | - |
| L1 集成测试 | ⏳ 待实现 | - |
| L2 E2E 验证 | ⏳ 待实现 | - |

## 文档索引

| 文档 | 说明 | 何时读取 |
|------|------|----------|
| [01-prd.md](01-prd.md) | 产品需求：功能边界、接入方场景、安全要求 | 始终 |
| [06-data-model.md](06-data-model.md) | 数据模型：ApiKey 表、AccessLog 表、权限设计 | 涉及数据结构时 |
| [07-api.md](07-api.md) | API 规格：管理接口 + 数据读取接口完整清单 | 涉及前后端契约或接入方对接时 |

## 核心概念

- **Consumer**：数据接入方，每个 Consumer 持有一个独立 API Key
- **API Key**：不可逆哈希存储，明文仅在创建时返回一次
- **DataRole（数据角色）**：控制一个 Key 能访问哪些域的数据（如 `org-readonly`、`attendance-readonly`）
- **AccessLog**：每次请求自动记录，不可篡改，用于审计
- **脱敏规则**：手机号、身份证等敏感字段在接口层主动过滤，不透传原始值

## 架构示意

```
其他内部系统 A ─┐
其他内部系统 B ─┤── X-Api-Key Header ──▶ DataOpenModule ──▶ 业务数据库（只读查询）
报表/分析平台  ─┘                         │
                                          └──▶ AccessLog 表（审计）
```

## 后端代码位置（待实现）

| 位置 | 路径 |
|------|------|
| 模块 | `backend/src/modules/data-open/` |
| Schema | `backend/prisma/schema/platform_data_open.prisma` |
| Guard | `backend/src/modules/data-open/guards/api-key.guard.ts` |
| 集成测试 | `testing/backend/integration/data-open/` |