后端成熟模板化改造说明

目标

服务端后端不再继续把所有配置、鉴权、审计、页面入口和业务接口堆在 main.py 里，而是逐步改成成熟 FastAPI 后台项目常见的分层结构。

参考方向：

FastAPI 官方 full-stack 模板：后端工程结构、配置、JWT、数据库模型、迁移、Docker。
FastAPI Users：用户、认证、JWT、密码哈希、用户管理。
现有 SimCAE 业务：版本发布、Manifest 签名、License、设备、崩溃报告、日志审计。

当前已落地

已经新增模板化目录：

app/
  api/
    router.py
    routes/
      admin_license.py
      admin_policy.py
      admin_version.py
      admin_app_channel.py
      admin_crash_report.py
      admin_device.py
      admin_logs.py
      admin_config.py
      admin_publish.py
      client_update.py
      crash_api.py
      frontend.py
  core/
    config.py
    security.py
    audit.py
  db/
  repositories/
    app_channel_repository.py
    crash_report_repository.py
    device_repository.py
    license_repository.py
    log_repository.py
    policy_repository.py
    version_repository.py
    client_update_repository.py
    publish_repository.py
  schemas/
    license.py
    policy.py
    version.py
    app_channel.py
    device.py
    log.py
    admin_config.py
    client_update.py
  services/
    common_service.py
    license_service.py
    signing_service.py
    admin_config_service.py
    device_credential_service.py
    publish_service.py
    crash_api_service.py

当前已经从 main.py 抽出的通用能力：

app/core/config.py：统一读取 .env、路径配置和基础 settings。
app/core/security.py：后台令牌校验、令牌摘要、.env 写入工具。
app/core/audit.py：管理后台写操作审计中间件。
app/api/routes/frontend.py：管理后台静态页面、favicon、platform-config、health 路由。
app/api/routes/admin_license.py：License 创建、列表、禁用/启用、软删除接口。
app/api/routes/admin_policy.py：渠道更新策略查询和保存接口。
app/api/routes/admin_version.py：版本列表、设为最新、删除、客户端协议修改、离线包下载接口。
app/api/routes/admin_app_channel.py：应用列表、应用创建、渠道列表、渠道保存接口。
app/api/routes/admin_logs.py：升级日志、下载日志、管理员审计日志的列表、删除和清空接口。
app/api/routes/admin_crash_report.py：崩溃报告管理列表和附件下载接口。
app/api/routes/admin_device.py：设备列表和设备禁用/恢复接口。
app/api/routes/admin_config.py：管理员令牌校验/变更、运行时配置、客户端配置生成接口。
app/api/routes/admin_publish.py：管理端发布新版本接口，包含发布锁和管理员鉴权。
app/api/routes/client_update.py：客户端设备登记、更新检测、下载链接、Manifest、下载日志和升级结果上报接口。
app/api/routes/crash_api.py：崩溃报告健康检查、报告上传/下载和符号包上传接口。
app/schemas/：License、策略、版本管理接口的 Pydantic 请求模型。
app/services/common_service.py：渠道校验、版本号比较、策略行转换等通用业务函数。
app/services/license_service.py：License Key 加密保存和解密展示。
app/services/signing_service.py：Manifest、策略、设备身份签名。
app/services/admin_config_service.py：管理端运行时配置和客户端配置默认值生成。
app/services/device_credential_service.py：客户端设备凭证验签、有效性校验和 last_seen 更新。
app/services/publish_service.py：发布包表单解析、Release 目录校验、压缩包解压、空间检查和 MinIO 上传。
app/services/crash_api_service.py：崩溃报告接口鉴权、multipart 校验、文件落盘、幂等校验和符号包处理。
app/repositories/：管理后台已迁移接口的数据库读写层，route 不再直接拼 SQL 或打开数据库连接。
app/api/router.py：统一注册基础路由。
main.py：已经压缩为服务入口，只保留生命周期、MinIO 初始化、静态挂载和全局客户端鉴权。

当前业务接口路径保持不变，避免影响 Launcher、Updater 和已部署管理页面。

后续迁移路线

后续不建议一次性重写全部后端，而是按下面顺序迁移：

接入成熟用户认证模块，例如 FastAPI Users。
将 ADMIN_TOKEN 替换成管理员用户名/密码登录、JWT、refresh token。
增加用户、角色、权限、菜单权限、API 权限表。
管理后台常用业务接口、客户端更新接口、版本发布接口、崩溃报告接口已经按领域拆到 app/api/routes/，并将 SQL 下沉到 app/repositories/。
继续将请求/响应 dict 改成 app/schemas/ 下的 Pydantic 模型。
继续补齐请求/响应模型、权限模型、异常模型，让接口契约更清晰。
继续细化 repository，后续可把 SQLite SQL 逐步迁到 ORM 或统一查询层。
引入 ORM 和迁移工具，例如 SQLModel/SQLAlchemy + Alembic。
保持客户端接口 /api/v1/... 尽量兼容，避免客户端 SDK 重编。

为什么不是直接删除 main.py

main.py 原来包含大量已经跑通的业务逻辑：

版本发布和压缩包解包。
Manifest 哈希和签名。
MinIO 文件上传、下载授权。
设备身份签发和校验。
License 管理。
崩溃报告上传、查询和下载。

这些是 SimCAE 自有业务，GitHub 模板不会直接提供。当前已经完成第一轮“搬家式重构”：业务模块进入 routes/services/repositories，入口文件不再堆业务代码。后续可以继续做更深的工程化，例如 ORM、JWT 用户体系、角色权限和 Alembic 数据库迁移。

5.8 KiB Raw Blame History Unescape Escape

后端成熟模板化改造说明

目标

当前已落地

后续迁移路线

为什么不是直接删除 main.py

5.8 KiB

Raw Blame History