root/Neo-ZQYY
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
6f8f12314fde7aa0370c2cd0ae3ffd2b6e38705c
Neo-ZQYY/docs/deployment/EXPORT-PATHS.md
Neo 6f8f12314f feat: 累积功能变更 — 聊天集成、租户管理、小程序更新、ETL 增强、迁移脚本 
包含多个会话的累积代码变更：
- 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>
2026-04-06 00:03:48 +08:00

348 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Export 输出路径规范
> 最后更新：2026-03-23
> 本文档描述 `export/` 目录的统一结构、各子目录用途、对应的 `.env` 变量、以及代码中的读取方式。
---
## 目录总览
```
export/
├── ETL-Connectors/feiqiu/
│ ├── JSON/ — API 原始 JSON 导出（ODS 抓取落盘）
│ ├── LOGS/ — ETL 运行日志（每次 run 一个 .log）
│ └── REPORTS/ — ETL 质检/完整性报告（JSON 格式）
├── SYSTEM/
│ ├── LOGS/ — 系统级运维日志（预留）
│ ├── REPORTS/
│ │ ├── dataflow_analysis/ — 数据流结构分析报告（Markdown + 采集中间产物）
│ │ ├── field_audit/ — 字段排查报告（Markdown）
│ │ └── full_dataflow_doc/ — 全链路数据流文档（Markdown）
│ └── CACHE/
│ └── api_samples/ — API 样本缓存（24h 有效，gen_full_dataflow_doc 使用）
├── BACKEND/
│ ├── LOGS/ — 后端结构化日志（预留，待 5.3 后端日志改造后启用）
│ └── avatars/ — 用户头像文件（{user_id}.jpg，覆盖式保存）
└── dev-trace-logs/ — 开发调试全链路日志（DevTrace 模块）
└── YYYY-MM-DD/ — 按日期分子目录
└── trace_YYYY-MM-DD_HH.jsonl — 按小时分文件（JSON Lines）
```
> 服务器部署时不保留 `export/`（通过 `setup-server-git.py` 排除），仅开发机留存。
> 服务器的输出路径由各环境 `.env` 独立配置，指向 `repo/export/` 下对应子目录。
---
## 环境变量与目录映射
| 环境变量 | 默认值（开发机） | 对应目录 | 说明 |
|----------|------------------|----------|------|
| `EXPORT_ROOT` | `C:/NeoZQYY/export/ETL-Connectors/feiqiu/JSON` | `ETL-Connectors/feiqiu/JSON/` | ODS 抓取 JSON 落盘根目录 |
| `LOG_ROOT` | `C:/NeoZQYY/export/ETL-Connectors/feiqiu/LOGS` | `ETL-Connectors/feiqiu/LOGS/` | ETL 运行日志 |
| `FETCH_ROOT` | `C:/NeoZQYY/export/ETL-Connectors/feiqiu/JSON` | `ETL-Connectors/feiqiu/JSON/` | FETCH_ONLY 模式 JSON 输出（通常与 EXPORT_ROOT 相同） |
| `ETL_REPORT_ROOT` | `C:/NeoZQYY/export/ETL-Connectors/feiqiu/REPORTS` | `ETL-Connectors/feiqiu/REPORTS/` | ETL 质检/完整性报告 |
| `SYSTEM_ANALYZE_ROOT` | `C:/NeoZQYY/export/SYSTEM/REPORTS/dataflow_analysis` | `SYSTEM/REPORTS/dataflow_analysis/` | 数据流结构分析报告 |
| `FIELD_AUDIT_ROOT` | `C:/NeoZQYY/export/SYSTEM/REPORTS/field_audit` | `SYSTEM/REPORTS/field_audit/` | 字段排查报告 |
| `FULL_DATAFLOW_DOC_ROOT` | `C:/NeoZQYY/export/SYSTEM/REPORTS/full_dataflow_doc` | `SYSTEM/REPORTS/full_dataflow_doc/` | 全链路数据流文档 |
| `API_SAMPLE_CACHE_ROOT` | `C:/NeoZQYY/export/SYSTEM/CACHE/api_samples` | `SYSTEM/CACHE/api_samples/` | API 样本缓存 |
| `SYSTEM_LOG_ROOT` | `C:/NeoZQYY/export/SYSTEM/LOGS` | `SYSTEM/LOGS/` | 系统级运维日志 |
| `BACKEND_LOG_ROOT` | `C:/NeoZQYY/export/BACKEND/LOGS` | `BACKEND/LOGS/` | 后端结构化日志 |
| `DEV_TRACE_LOG_DIR` | `export/dev-trace-logs` | `dev-trace-logs/` | 开发调试全链路日志（DevTrace 模块） |
| `AVATAR_EXPORT_PATH` | `C:/NeoZQYY/export/BACKEND/avatars` | `BACKEND/avatars/` | 用户头像文件存储目录 |
---
## 各目录详细说明与代码配合
### 1. ETL-Connectors/feiqiu/JSON — API 原始 JSON 导出
环境变量：`EXPORT_ROOT`、`FETCH_ROOT`
配置加载链路：
```
.env EXPORT_ROOT=...
→ env_parser.py ENV_MAP["EXPORT_ROOT"] → ("io.export_root",)
→ defaults.py io.export_root 默认 ""（空字符串，强制要求 .env 配置）
→ AppConfig.get("io.export_root")
```
代码使用：
- `utils/json_store.py` 的 `dump_json()` 负责写入 JSON 文件
- `tasks/ods/ods_json_archive_task.py` 调用 `dump_json()` 将 API 原始响应落盘
- 目录结构：`{EXPORT_ROOT}/{TASK_CODE}/{TASK_CODE}-{run_id}-{timestamp}/`
- 每个子目录包含按 endpoint 命名的 `.json` 文件和 `manifest.json`
示例输出：
```
export/ETL-Connectors/feiqiu/JSON/
└── ODS_PAYMENT/
└── ODS_PAYMENT-abc123-20260219_1430/
├── payment_transactions.json
└── manifest.json
```
---
### 2. ETL-Connectors/feiqiu/LOGS — ETL 运行日志
环境变量：`LOG_ROOT`
配置加载链路：
```
.env LOG_ROOT=...
→ env_parser.py ENV_MAP["LOG_ROOT"] → ("io.log_root",)
→ defaults.py io.log_root 默认 ""（空字符串，强制要求 .env 配置）
→ AppConfig.get("io.log_root") 或 config["io"]["log_root"]
```
代码使用：
- `orchestration/task_executor.py` 的 `_attach_run_file_logger()` 方法
- 读取 `self.config["io"]["log_root"]`
- 创建 `{LOG_ROOT}/{run_uuid}.log`
- 每次 ETL 运行生成一个以 run_uuid 命名的日志文件
- `utils/logging_utils.py` 的 `configure_logging()` 上下文管理器
- 接收 `log_file: Path` 参数，支持同时输出到控制台和文件
示例输出：
```
export/ETL-Connectors/feiqiu/LOGS/
├── 37f16195960649b384a6bf1e3bdb092c.log
├── 7b6d77fe8a6a4503a0ce4374e3864be9.log
└── ecc3684e2c794d1ba30b6748b999593c.log
```
---
### 3. ETL-Connectors/feiqiu/REPORTS — ETL 质检/完整性报告
环境变量：`ETL_REPORT_ROOT`
当前代码行为（已适配）：
- `quality/integrity_service.py` 的 `write_report()` 函数
- 读取 `ETL_REPORT_ROOT` 环境变量作为输出根目录
- 环境变量缺失时抛出 `KeyError`
- 支持 `report_path` 参数覆盖
- `quality/integrity_checker.py` 的 `_default_report_path()` 函数
- 读取 `ETL_REPORT_ROOT` 环境变量
- 环境变量缺失时抛出 `KeyError`
- `tasks/dwd/dwd_quality_task.py` 的 `DwdQualityTask`
- `REPORT_PATH` 从 `ETL_REPORT_ROOT` 环境变量读取
- 环境变量缺失时 `load()` 抛出 `RuntimeError`
- `scripts/debug/generate_report.py`
- `REPORTS_DIR` 从 `ETL_REPORT_ROOT` 环境变量读取
- 环境变量缺失时抛出 `KeyError`
- ETL 内部脚本（`check/`、`repair/`、`debug/`、`scripts/`）
- 均通过 `os.environ.get("ETL_REPORT_ROOT")` 读取
- 环境变量缺失时抛出 `KeyError`
---
### 4. SYSTEM/REPORTS/dataflow_analysis — 数据流结构分析报告
环境变量：`SYSTEM_ANALYZE_ROOT`
代码使用：
- `scripts/ops/gen_dataflow_report.py` 的 `resolve_data_dir()` 函数
- 通过 `_env_paths.get_output_path("SYSTEM_ANALYZE_ROOT")` 读取
- 环境变量缺失时抛出 `KeyError`
- 支持 `--output-dir` CLI 参数覆盖
- `scripts/ops/analyze_dataflow.py` 的 `resolve_output_dir()` 函数
- 通过 `_env_paths.get_output_path("SYSTEM_ANALYZE_ROOT")` 读取
- 环境变量缺失时抛出 `KeyError`
目录内容：
```
export/SYSTEM/REPORTS/dataflow_analysis/
├── bd_descriptions/ — 业务描述 JSON（每表一个）
├── db_schemas/ — 数据库表结构 JSON（ODS + DWD）
├── field_mappings/ — 字段映射 JSON
├── json_trees/ — API JSON 结构树
├── collection_manifest.json — 采集清单
└── dataflow_YYYY-MM-DD_HHMMSS.md — 最终报告
```
已适配：代码直接读取 `SYSTEM_ANALYZE_ROOT`，无需改动。
---
### 5. SYSTEM/REPORTS/field_audit — 字段排查报告
环境变量：`FIELD_AUDIT_ROOT`
当前代码行为（已适配）：
- `scripts/ops/field_audit.py`
- 通过 `_env_paths.get_output_path("FIELD_AUDIT_ROOT")` 读取
- 环境变量缺失时抛出 `KeyError`
- 支持 `--output` 参数覆盖
- `scripts/ops/export_dwd_field_review.py`
- 通过 `_env_paths.get_output_path("FIELD_AUDIT_ROOT")` 读取
- 环境变量缺失时抛出 `KeyError`
---
### 6. SYSTEM/REPORTS/full_dataflow_doc — 全链路数据流文档
环境变量：`FULL_DATAFLOW_DOC_ROOT`
当前代码行为（已适配）：
- `scripts/ops/gen_full_dataflow_doc.py`
- `OUT` 通过 `_env_paths.get_output_path("FULL_DATAFLOW_DOC_ROOT")` 读取
- `SAMPLE_DIR` 通过 `_env_paths.get_output_path("API_SAMPLE_CACHE_ROOT")` 读取
- 环境变量缺失时抛出 `KeyError`
- `scripts/ops/gen_dataflow_doc.py`
- `OUT` 通过 `_env_paths.get_output_path("FULL_DATAFLOW_DOC_ROOT")` 读取
- 环境变量缺失时抛出 `KeyError`
- `scripts/ops/gen_api_field_mapping.py`
- `INPUT_DOC` 通过 `_env_paths.get_output_path("FULL_DATAFLOW_DOC_ROOT")` 读取
- 环境变量缺失时抛出 `KeyError`
---
### 7. SYSTEM/CACHE/api_samples — API 样本缓存
环境变量：`API_SAMPLE_CACHE_ROOT`
当前代码行为（已适配）：
- `scripts/ops/gen_full_dataflow_doc.py`
- `SAMPLE_DIR` 通过 `_env_paths.get_output_path("API_SAMPLE_CACHE_ROOT")` 读取
- 环境变量缺失时抛出 `KeyError`
- 缓存 24 小时有效，超时重新从 API 获取
---
### 8. BACKEND/LOGS — 后端结构化日志
环境变量：`BACKEND_LOG_ROOT`（预留）
当前状态：
- 后端仅使用 uvicorn 默认日志，无文件输出
- 对应 LAUNCH-CHECKLIST 第 5.3 项"后端结构化日志"
启用时机：
- 后端接入结构化日志后，配置 `BACKEND_LOG_ROOT` 指向此目录
---
### 9. SYSTEM/LOGS — 系统级运维日志
环境变量：`SYSTEM_LOG_ROOT`（预留）
当前状态：
- 预留给未来的系统级运维脚本日志输出
- 如监控系统（LAUNCH-CHECKLIST 7.2）上线后的采集器日志
---
### 10. dev-trace-logs — 开发调试全链路日志
环境变量：`DEV_TRACE_LOG_DIR`
默认值：`export/dev-trace-logs`（相对于项目根目录）
用途：
- DevTrace 模块的全链路请求追踪日志输出目录
- 覆盖 HTTP 请求、SSE 流式响应、WebSocket 连接、后台 Job、异常/错误、数据库连接生命周期、中间件层
- 仅用于开发调试，不影响生产环境
目录结构：
```
export/dev-trace-logs/
├── _index.json — 索引文件（文件列表、记录数、文件大小）
├── 2026-03-23/ — 按日期分子目录
│ ├── trace_2026-03-23_08.jsonl — 按小时分文件（JSON Lines 格式）
│ ├── trace_2026-03-23_09.jsonl
│ ├── trace_2026-03-23_09_001.jsonl — 单文件超 10MB 自动轮转
│ └── ...
└── 2026-03-22/
└── ...
```
自动清理：
- 由 `DEV_TRACE_LOG_RETENTION_DAYS` 环境变量控制保留天数（默认 7 天）
- 每日凌晨自动检查并删除超期日期目录
- 也可通过 `POST /api/admin/dev-trace/cleanup` 手动按日期范围清理
相关环境变量：
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `DEV_TRACE_ENABLED` | `true` | 总开关，关闭后不采集任何 trace |
| `DEV_TRACE_LOG_DIR` | `export/dev-trace-logs` | 日志输出目录 |
| `DEV_TRACE_LOG_RETENTION_DAYS` | `7` | 自动清理保留天数 |
| `DEV_TRACE_LOG_SQL` | `true` | 是否记录完整 SQL 语句 |
| `DEV_TRACE_LOG_PARAMS` | `true` | 是否记录函数参数值 |
代码使用：
- `apps/backend/app/trace/config.py` 的 `TraceConfig` 类读取上述环境变量
- `apps/backend/app/trace/writer.py` 的 `TraceWriter` 负责写入 `.jsonl` 文件
- `apps/backend/app/trace/cleanup.py` 负责自动清理过期目录
---
## 配置优先级
所有路径变量遵循项目统一的配置优先级：
```
defaults.py 默认值（路径类均为空字符串）< 根 .env < 应用 .env（如 feiqiu/.env）< 环境变量 < CLI 参数
```
ETL 模块的路径变量通过 `env_parser.py` 的 `ENV_MAP` 映射到 `AppConfig` 的 `io.*` 配置节。
`defaults.py` 中所有 `io.*` 路径默认值已清空为 `""`，如果 `.env` 未配置，下游代码会因空路径而失败。
系统级脚本直接通过 `os.environ.get()` 或 `python-dotenv` 读取。
---
## 代码适配状态
| 目录 | 环境变量 | 代码已适配 | 备注 |
|------|----------|-----------|------|
| ETL JSON | `EXPORT_ROOT` | ✅ | `env_parser.py` → `io.export_root` |
| ETL LOGS | `LOG_ROOT` | ✅ | `env_parser.py` → `io.log_root` |
| ETL FETCH | `FETCH_ROOT` | ✅ | `env_parser.py` → `io.fetch_root` |
| ETL REPORTS | `ETL_REPORT_ROOT` | ✅ | `integrity_service.py` / `dwd_quality_task.py` 已适配 |
| dataflow_analysis | `SYSTEM_ANALYZE_ROOT` | ✅ | `gen_dataflow_report.py` 已读取 |
| field_audit | `FIELD_AUDIT_ROOT` | ✅ | `field_audit.py` 已适配 |
| full_dataflow_doc | `FULL_DATAFLOW_DOC_ROOT` | ✅ | `gen_full_dataflow_doc.py` 已适配 |
| api_samples | `API_SAMPLE_CACHE_ROOT` | ✅ | `gen_full_dataflow_doc.py` 已适配 |
| SYSTEM LOGS | `SYSTEM_LOG_ROOT` | — | 预留 |
| BACKEND LOGS | `BACKEND_LOG_ROOT` | — | 预留 |
| dev-trace-logs | `DEV_TRACE_LOG_DIR` | ✅ | `app/trace/config.py` → `TraceConfig`，`app/trace/writer.py` 写入 |
| BACKEND avatars | `AVATAR_EXPORT_PATH` | ✅ | `app/config.py` → `AVATAR_EXPORT_PATH`，`xcx_avatar.py` 读写 |
---
## 服务器环境配置示例
开发机（`C:\NeoZQYY\.env`）：
```env
EXPORT_ROOT=C:/NeoZQYY/export/ETL-Connectors/feiqiu/JSON
LOG_ROOT=C:/NeoZQYY/export/ETL-Connectors/feiqiu/LOGS
FETCH_ROOT=C:/NeoZQYY/export/ETL-Connectors/feiqiu/JSON
ETL_REPORT_ROOT=C:/NeoZQYY/export/ETL-Connectors/feiqiu/REPORTS
SYSTEM_ANALYZE_ROOT=C:/NeoZQYY/export/SYSTEM/REPORTS/dataflow_analysis
BACKEND_LOG_ROOT=C:/NeoZQYY/export/BACKEND/LOGS
AVATAR_EXPORT_PATH=C:/NeoZQYY/export/BACKEND/avatars
```
服务器测试环境（`D:\NeoZQYY\test\repo\.env`）：
```env
EXPORT_ROOT=D:/NeoZQYY/test/repo/export/ETL-Connectors/feiqiu/JSON
LOG_ROOT=D:/NeoZQYY/test/repo/export/ETL-Connectors/feiqiu/LOGS
FETCH_ROOT=D:/NeoZQYY/test/repo/export/ETL-Connectors/feiqiu/JSON
ETL_REPORT_ROOT=D:/NeoZQYY/test/repo/export/ETL-Connectors/feiqiu/REPORTS
SYSTEM_ANALYZE_ROOT=D:/NeoZQYY/test/repo/export/SYSTEM/REPORTS/dataflow_analysis
BACKEND_LOG_ROOT=D:/NeoZQYY/test/repo/export/BACKEND/LOGS
```
服务器正式环境（`D:\NeoZQYY\prod\repo\.env`）：
```env
EXPORT_ROOT=D:/NeoZQYY/prod/repo/export/ETL-Connectors/feiqiu/JSON
LOG_ROOT=D:/NeoZQYY/prod/repo/export/ETL-Connectors/feiqiu/LOGS
FETCH_ROOT=D:/NeoZQYY/prod/repo/export/ETL-Connectors/feiqiu/JSON
ETL_REPORT_ROOT=D:/NeoZQYY/prod/repo/export/ETL-Connectors/feiqiu/REPORTS
SYSTEM_ANALYZE_ROOT=D:/NeoZQYY/prod/repo/export/SYSTEM/REPORTS/dataflow_analysis
BACKEND_LOG_ROOT=D:/NeoZQYY/prod/repo/export/BACKEND/LOGS
```
Reference in New Issue View Git Blame Copy Permalink