diff --git a/docs/STRUCTURE.md b/docs/STRUCTURE.md deleted file mode 100644 index 7053a36..0000000 --- a/docs/STRUCTURE.md +++ /dev/null @@ -1,83 +0,0 @@ -```text -. -├── app/ # 核心框架层:加载/调度/执行/后台/安全/适配器 -│ ├── main.py # FastAPI 入口;挂载 SQLAdmin;启动时确保 key 与 DB schema -│ ├── admin/ # SQLAdmin 管理后台 -│ │ ├── views.py # Job/JobLog 的管理视图、校验、动作按钮、模板选择 -│ │ ├── routes.py # Admin 自定义 POST 路由(Retry/Run 等) -│ │ └── templates/ # 覆盖/扩展 SQLAdmin 的模板(list/details/edit 等) -│ ├── core/ # 运行时基础设施(配置/日志/上下文/捕获) -│ │ ├── config.py # Settings(从 .env 读取);DB_URL/REDIS_URL/FERNET_KEY_PATH 等 -│ │ ├── logging.py # 全局日志配置(stdout + 可选文件) -│ │ ├── log_capture.py # “尽力捕获”本次执行日志到 JobLog.run_log(不影响执行) -│ │ └── log_context.py # 将 job_id/log_id 写入日志上下文(便于追踪) -│ ├── db/ # 数据层(SQLAlchemy) -│ │ ├── models.py # Job / JobLog 模型定义 -│ │ ├── engine.py # create_engine + SessionLocal -│ │ ├── crud.py # 基础 CRUD(读 Job、写 JobLog、清理日志等) -│ │ └── schema.py # 轻量 schema 自升级(create_all + 补列) -│ ├── security/ # 安全模块 -│ │ └── fernet.py # Fernet key 管理 + JSON 加解密(兼容脏数据) -│ ├── plugins/ # 插件加载 -│ │ └── manager.py # handler_path -> import -> BaseJob 子类校验 -> instantiate -│ ├── jobs/ # 插件规范 -│ │ └── base.py # BaseJob 抽象基类(run(params, secrets)) -│ ├── integrations/ # 适配器/SDK:业务 Job 禁止直接写 HTTP -│ │ ├── base.py # BaseClient(超时/重试/日志;统一 request/get_json/post_json) -│ │ ├── seeyon.py # SeeyonClient:致远 OA token 认证 + 自动携带 token header -│ │ └── didi.py # (若存在)滴滴侧 SDK/适配器封装 -│ └── tasks/ # Celery 任务引擎 -│ ├── celery_app.py # Celery 配置(broker/backend、timezone、beat_schedule 等) -│ ├── dispatcher.py # 定时调度:每分钟 tick,cron_expr 命中则触发 execute_job -│ └── execute.py # 统一执行入口:读库->解密->加载插件->run->写 JobLog -├── extensions/ # 业务插件层(必须独立于框架层) -│ ├── __init__.py -│ └── sync_oa_to_didi/ # 示例插件:仅演示 token 获取日志 -│ ├── __init__.py -│ └── job.py # SyncOAToDidiTokenJob(调用 SeeyonClient.authenticate 并记录日志) -├── docker/ # 镜像构建 -│ └── Dockerfile # Python 镜像 + APT 镜像源切换 + 安装依赖 -├── docker-compose.yml # 生产基线:backend/worker/beat/redis/postgres + ./data 挂载 -├── docker-compose.dev.yml # 开发叠加:源码挂载 + backend reload + worker/beat watchfiles 重启 -├── env.example # 环境变量示例(本地复制为 .env) -├── connecthub.sh # 一键脚本:build/start/restart/stop + dev-* + log -├── pyproject.toml # Python 依赖(FastAPI/Celery/SQLAdmin/psycopg/cryptography 等) -├── README.md # “开发手册”主文档(运行指南、Admin 使用、示例配置) -└── data/ # 运行数据目录(建议仅作为 volume,不作为源码管理) - ├── logs/ # 应用日志落点 - ├── pgdata/ # PostgreSQL 数据目录(volume) - └── connecthub.db # 旧 SQLite 残留(若已切换 PG,可视情况清理) -``` - ---- - -## 核心执行链路(从 Job 到 JobLog) - -1. **Job 定义**在 DB 表 `jobs`:`id/cron_expr/handler_path/public_cfg/secret_cfg` -2. **Beat** 每分钟触发一次 `dispatcher.tick`:读取 `jobs`,用 `cron_expr` 判断是否到点 -3. 到点后 `dispatcher` 调用 `execute_job.delay(job_id=...)` -4. **Worker** 执行 `execute_job`: - - 读 Job -> 解密 `secret_cfg`(Fernet,仅内存) - - PluginManager 动态加载 `handler_path` 指向的 `BaseJob` 子类 - - 调用 `job.run(params, secrets)` - - 捕获/汇总日志(run_log)与异常(traceback),写入 `job_logs`(Admin 可视化查看/重试) - ---- - -## 框架层 vs 插件层(边界提示) - -- **框架层(app/)**:只提供通用能力(调度、执行、加解密、日志、管理后台、适配器基类),不包含具体业务流程。 -- **插件层(extensions/)**:只放“具体业务 Job”,例如“同步员工/同步部门/同步 OA→滴滴”等,必须继承 `BaseJob`。 -- **外部系统调用**:禁止在 Job 内直接写 HTTP;必须通过 `app/integrations/*` 下的 Client。 - ---- - -## 运行数据与持久化(data/) - -`data/` 是运行时 volume: -- `data/pgdata/`:PostgreSQL 持久化数据 -- `data/logs/`:应用日志 -- `data/fernet.key`:Fernet key(正式环境必须固定,否则历史 secret_cfg 无法解密) - -建议:`data/` 仅作为挂载目录,不当作源码文件纳入版本管理。 -