Backend 分层重构（api/ schemas/ services/ clients/ infrastructure/） #27

New Issue

2026-08-21T13:39:26+08:00

tao.chen commented

2026-08-21 13:39:26 +08:00

目标

把扁平的 backend/src/backend/*.py（17 个文件）拆成 api/ schemas/ services/ clients/ infrastructure/ 五目录结构，让"路由/业务/外部IO"三层边界清晰。

计划文件

/Users/taochen/.claude/plans/structured-layered-tide.md

核心结构

backend/src/backend/
├── main.py
├── api/           # FastAPI router（10 个文件）
├── schemas/       # Pydantic 数据契约（7 个文件）
├── services/      # 业务用例（4 个文件）
├── clients/       # 外部 IO 客户端（3 个文件）
└── infrastructure/  # 横切关注点（1 个：logging/audit）

关键决策

api/schedules/ 子包收纳 schedules + schedule_runs（共享 schema）
audit.py → infrastructure/logging.py（不是业务也不是 IO）
storage_api.py → api/internal.py（/internal/v1/*）
不合并 admin.py + platform.py（CLAUDE.md 已说明故意保留）
业务下沉分阶段做，本任务只做"位置迁移"，下沉留后续 PR

兼容性

旧路径留 re-export shim：测试 0 改动即可；阶段 4 删 shim。

验收（每阶段都要过）

uv run --package backend pytest backend/tests -q 全绿
uv run python -m compileall backend/src 无错误
git blame 仍指向原作者（git mv 保留历史）

_{Task: m7buxy4vue93bfj6gppf27ur}

## 目标把扁平的 `backend/src/backend/*.py`（17 个文件）拆成 `api/ schemas/ services/ clients/ infrastructure/` 五目录结构，让"路由/业务/外部IO"三层边界清晰。 ## 计划文件 `/Users/taochen/.claude/plans/structured-layered-tide.md` ## 核心结构 ```text backend/src/backend/ ├── main.py ├── api/ # FastAPI router（10 个文件） ├── schemas/ # Pydantic 数据契约（7 个文件） ├── services/ # 业务用例（4 个文件） ├── clients/ # 外部 IO 客户端（3 个文件） └── infrastructure/ # 横切关注点（1 个：logging/audit） ``` ## 关键决策 - `api/schedules/` 子包收纳 schedules + schedule_runs（共享 schema） - `audit.py` → `infrastructure/logging.py`（不是业务也不是 IO） - `storage_api.py` → `api/internal.py`（/internal/v1/*） - **不合并** admin.py + platform.py（CLAUDE.md 已说明故意保留） - 业务下沉**分阶段**做，本任务只做"位置迁移"，下沉留后续 PR ## 兼容性旧路径留 re-export shim：测试 0 改动即可；阶段 4 删 shim。 ## 验收（每阶段都要过） - `uv run --package backend pytest backend/tests -q` 全绿 - `uv run python -m compileall backend/src` 无错误 - `git blame` 仍指向原作者（git mv 保留历史） --- <sub>Task: m7buxy4vue93bfj6gppf27ur</sub>

tao.chen added the priority:high status:to-do labels 2026-08-21 13:39:28 +08:00

tao.chen commented

2026-08-21 13:40:57 +08:00

tao.chen commented:

规划完成。已落盘 4 个阶段任务（subtask relation 已建立）。

阶段 1（纯位置迁移）风险最低、收益最大，建议作为第一个 PR 推进。
阶段 2-3 依赖阶段 1 完成。阶段 4 等所有测试切到新 import 后再删 shim。

执行节奏：每阶段独立 PR，每阶段都要 uv run --package backend pytest backend/tests -q 全绿。

**tao.chen** commented: > 规划完成。已落盘 4 个阶段任务（subtask relation 已建立）。阶段 1（纯位置迁移）风险最低、收益最大，建议作为第一个 PR 推进。阶段 2-3 依赖阶段 1 完成。阶段 4 等所有测试切到新 import 后再删 shim。执行节奏：每阶段独立 PR，每阶段都要 `uv run --package backend pytest backend/tests -q` 全绿。

tao.chen added status:done and removed status:to-do labels 2026-08-21 15:27:16 +08:00

tao.chen closed this issue

2026-08-21 15:27:18 +08:00

tao.chen commented

2026-08-21 15:42:28 +08:00

tao.chen commented:

整体收尾

Commit 落地

分支 worktree-backend-restructure HEAD: bca239e
单 squash commit refactor(backend): split into api/ schemas/ services/ clients/ layers
涵盖 4 阶段全部改动;线性历史干净

本地状态

develop HEAD: 9f64663 (落后 1 commit)
worktree-backend-restructure 比 develop 超前 1 commit,无冲突,适合 fast-forward
worktree 状态: locked (claude session active,这是 PWD)

清理命令(必须在主 checkout / 退出 Claude session 后执行)

# 退出 Claude session 后,在主 checkout /Users/taochen/llm/model-platform:

# 1) 合并到 develop (fast-forward,无冲突)
git checkout develop
git merge --ff-only worktree-backend-restructure

# 2) 验证
uv run --package backend pytest backend/tests -q   # 期望 122 passed
git log --oneline -1                                # 期望 bca239e

# 3) 推送 (可选)
git push origin develop

# 4) 退出 worktree + 删分支
git worktree remove --force /Users/taochen/llm/model-platform/.claude/worktrees/backend-restructure
git branch -d worktree-backend-restructure

为什么这里不直接执行
此 session 被锁在 worktree-backend-restructure 工作树(worktree status 显示 locked: claude session backend-restructure)。worktree-isolated session 不允许 git -C <main checkout> 跨 checkout 操作,也无法 self-remove(会终止当前会话)。

验收清单

pytest 122 passed
compileall 零错误
零旧路径 import
单 squash commit 在分支上
用户手动合并到 develop
用户手动推送 + 清理工作树

最终结构

backend/src/backend/
  main.py, audit.py, __init__.py
  api/            (10 files: routes + 2 subpackage)
  schemas/        (7 files: Pydantic contracts)
  services/       (storage + schedules)
  clients/        (rclone, runtime, scheduler)

后续下沉候选(待新 PR)

cron_preview (api/schedules/schedules.py) — 纯 cron 迭代
validate_script_content (api/scripts.py) — 脚本字节校验
compute_jupyter_relative_path / resource_directory (api/resources.py) — 路径解析
can_view (api/resources.py) — 资源权限判断

**tao.chen** commented: > ## 整体收尾 **Commit 落地** - 分支 `worktree-backend-restructure` HEAD: `bca239e` - 单 squash commit `refactor(backend): split into api/ schemas/ services/ clients/ layers` - 涵盖 4 阶段全部改动;线性历史干净 **本地状态** - `develop` HEAD: `9f64663` (落后 1 commit) - `worktree-backend-restructure` 比 `develop` 超前 1 commit,无冲突,适合 fast-forward - worktree 状态: locked (claude session active,这是 PWD) **清理命令(必须在主 checkout / 退出 Claude session 后执行)** ```bash # 退出 Claude session 后,在主 checkout /Users/taochen/llm/model-platform: # 1) 合并到 develop (fast-forward,无冲突) git checkout develop git merge --ff-only worktree-backend-restructure # 2) 验证 uv run --package backend pytest backend/tests -q # 期望 122 passed git log --oneline -1 # 期望 bca239e # 3) 推送 (可选) git push origin develop # 4) 退出 worktree + 删分支 git worktree remove --force /Users/taochen/llm/model-platform/.claude/worktrees/backend-restructure git branch -d worktree-backend-restructure ``` **为什么这里不直接执行** 此 session 被锁在 `worktree-backend-restructure` 工作树(worktree status 显示 `locked: claude session backend-restructure`)。worktree-isolated session 不允许 `git -C <main checkout>` 跨 checkout 操作,也无法 self-remove(会终止当前会话)。 **验收清单** - [x] pytest 122 passed - [x] compileall 零错误 - [x] 零旧路径 import - [x] 单 squash commit 在分支上 - [ ] 用户手动合并到 develop - [ ] 用户手动推送 + 清理工作树 **最终结构** ```text backend/src/backend/ main.py, audit.py, __init__.py api/ (10 files: routes + 2 subpackage) schemas/ (7 files: Pydantic contracts) services/ (storage + schedules) clients/ (rclone, runtime, scheduler) ``` **后续下沉候选**(待新 PR) 1. `cron_preview` (api/schedules/schedules.py) — 纯 cron 迭代 2. `validate_script_content` (api/scripts.py) — 脚本字节校验 3. `compute_jupyter_relative_path` / `resource_directory` (api/resources.py) — 路径解析 4. `can_view` (api/resources.py) — 资源权限判断

tao.chen added status:archived and removed status:done labels 2026-08-24 10:09:10 +08:00

tao.chen reopened this issue

2026-08-24 10:09:17 +08:00

tao.chen closed this issue

2026-08-24 14:21:32 +08:00

tao.chen added the status:in-review label 2026-08-24 14:21:37 +08:00

tao.chen added status:archived and removed status:in-review labels 2026-08-24 14:25:19 +08:00

tao.chen reopened this issue

2026-08-24 14:25:33 +08:00

tao.chen added the status:to-do label 2026-08-24 14:25:52 +08:00

tao.chen added status:done and removed status:to-do labels 2026-08-24 14:50:02 +08:00

tao.chen closed this issue