Neo
6f8f12314f
包含多个会话的累积代码变更： - backend: AI 聊天服务、触发器调度、认证增强、WebSocket、调度器最小间隔 - admin-web: ETL 状态页、任务管理、调度配置、登录优化 - miniprogram: 看板页面、聊天集成、UI 组件、导航更新 - etl: DWS 新任务（finance_area_daily/board_cache）、连接器增强 - tenant-admin: 项目初始化 - db: 19 个迁移脚本（etl_feiqiu 11 + zqyy_app 8） - packages/shared: 枚举和工具函数更新 - tools: 数据库工具、报表生成、健康检查 - docs: PRD/架构/部署/合约文档更新 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
100 lines
5.3 KiB
Markdown
100 lines
5.3 KiB
Markdown
# 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 数据导出，定义支持导出的页面清单、导出格式、权限规则、导出日志记录要求
|