# P10-NS4-03：数据导出功能的规范

## 简要结论
- 状态：❌ 未解决
- 租户管理后台（tenant-admin）无任何业务数据导出功能。后端无导出端点，前端无导出按钮，数据库无导出日志表。现有的"下载"功能仅限 Excel 空白模板下载和系统管理后台的环境配置导出，均与业务数据导出无关。

## 详细审查

### 数据库端

搜索范围：`db/zqyy_app/` 全部 SQL 文件

结果：
- **无导出日志表**：`biz` schema 下无 `export_log`、`download_log` 等导出记录表
- **现有表**：`biz.excel_upload_log` 仅记录 Excel **上传**操作（upload_type: expense/platform_income/salary_adj/recharge_commission），无导出相关字段
- **无导出审计字段**：任何现有表均未包含导出时间、导出人、导出格式等审计字段

### 后端代码

搜索范围：`apps/backend/app/routers/` 全部 tenant_*.py 文件 + 全部路由文件

逐文件审查结果：

| 路由文件 | 导出相关端点 | 说明 |
|----------|-------------|------|
| `tenant_auth.py` | 无 | 仅登录/鉴权 |
| `tenant_users.py` | 无 | 用户审核+管理，无导出 |
| `tenant_excel.py` | `GET /template/{type}` | **模板下载**（空白 Excel 模板），非数据导出 |
| `tenant_clues.py` | 无 | 线索 CRUD，无导出 |
| `env_config.py` | `GET /export` | **环境配置导出**（admin-web 专用），非业务数据 |

关键发现：
1. `tenant_excel.py` 包含 `download_template()` 函数，使用 `openpyxl` + `StreamingResponse` 生成空白模板文件，仅含表头和格式说明，不含任何业务数据
2. 后端无通用导出工具模块（无 `export_to_excel`、`export_to_csv` 等工具函数）
3. 全局搜索 `def.*export` 仅命中 `env_config.py` 的 `export_env_config()`（系统管理后台功能）

### 前端代码

#### tenant-admin（租户管理后台）

搜索范围：`apps/tenant-admin/src/` 全部文件

页面清单与导出功能：

| 页面 | 路径 | 导出按钮 | 说明 |
|------|------|---------|------|
| Login | `pages/Login/` | 无 | 登录页 |
| UserApproval | `pages/UserApproval/` | 无 | 用户审核 |
| UserManagement | `pages/UserManagement/` | 无 | 用户管理 |
| ExcelUpload | `pages/ExcelUpload/` | 无 | 仅有模板**下载**按钮（`DownloadOutlined` + `handleDownloadTemplate`） |
| RetentionClues | `pages/RetentionClues/` | 无 | 维客线索管理 |

结论：5 个页面均无数据导出功能。ExcelUpload 页面的 `DownloadOutlined` 图标用于下载空白模板，非数据导出。

#### admin-web（系统管理后台，参考）

搜索范围：`apps/admin-web/src/` 全部文件

- `EnvConfig.tsx`：有"导出"按钮，调用 `exportEnvConfig()` 导出去敏感值的 `.env` 配置文件 → 运维功能，非业务数据导出
- `OpsPanel.tsx`：`CloudDownloadOutlined` 用于 Git Pull 操作 → 非数据导出
- **无业务数据导出功能可参考**

### 差距分析

review-report.md 中 P10→NS4 缺失项 #3 指出：P10 §数据导出 位置隐含了管理后台应支持数据导出，但 NS4 完全未提及。

作为管理后台，以下场景存在合理的导出需求但均未实现：

| 导出场景 | 数据源 | 潜在用户需求 | 当前状态 |
|----------|--------|-------------|---------|
| 用户列表导出 | `auth.users` | 租户管理员需要离线查看/统计用户信息 | ❌ 无 |
| 审核记录导出 | `auth.user_applications` | 审核工作量统计、合规审计 | ❌ 无 |
| Excel 上传历史导出 | `biz.excel_upload_log` | 上传操作追溯、数据核对 | ❌ 无 |
| 维客线索导出 | `member_retention_clue` | 线索数据离线分析、交接 | ❌ 无 |
| 助教奖罚明细导出 | `biz.salary_adjustments` | 工资核算、财务对账 | ❌ 无 |

补充说明：
- P10 spec 本身也未明确列出"数据导出"功能（无 AC、无任务项），但 review-report 将其标记为隐含需求
- P7-NS1-10 审查（绩效明细导出）结论同样为 ❌ 未解决，说明整个项目目前缺乏通用的数据导出基础设施

### 建议

1. **明确需求优先级**：数据导出为隐含需求，建议在 NS4 spec 中明确标注为"后续迭代项"或"MVP 不含"，避免歧义

2. **如需实现，建议分两步**：
   - **Step 1 — 通用导出基础设施**：
     - 后端新增 `apps/backend/app/utils/export_helper.py`，封装 openpyxl 生成 Excel 的通用逻辑（列定义、数据填充、StreamingResponse 包装）
     - 新建 `biz.export_log` 表记录导出操作（who/when/what/row_count），满足审计要求
   - **Step 2 — 逐页面接入**：
     - 用户列表：`GET /api/tenant/users/export?format=xlsx`
     - 审核记录：`GET /api/tenant/applications/export?status=&format=xlsx`
     - 维客线索：`GET /api/tenant/customers/{member_id}/clues/export`
     - 上传历史：`GET /api/tenant/excel/logs/export`

3. **权限控制**：导出操作应复用现有的 `require_tenant_admin()` 鉴权 + `site_id IN (管辖列表)` 数据隔离，确保导出数据不越权

4. **导出格式**：建议统一 `.xlsx`（已有 openpyxl 依赖），暂不支持 CSV（避免中文编码问题）

5. **NS4 spec 补充建议**：在 NS4 文档"三、功能详细设计"中新增 §3.5 数据导出，定义支持导出的页面清单、导出格式、权限规则、导出日志记录要求