Skip to content

Web 架构与演进边界 ​

ColorVision Web 由 React 前端与 Flask 后端组成,提供公共门户、插件/更新分发和管理页面。前端构建产物由后端托管;制品文件系统是发布内容来源,SQLite 负责索引、缓存、账号、审计和任务等数据。

本页说明跨模块责任及演进约束。运行配置和命令见后端组成与 CLI,具体接口以各功能主题为准。

当前模块责任 ​

责任当前实现
组成根app_setup.py:create_app_and_context 创建 Flask、服务、数据库和依赖;register_all_blueprints 装配 HTTP 路由
可执行/兼容入口app.py 调用组成根,保留旧全局变量和无状态 helper 转发,主入口处理 CLI 和调度线程启动
依赖传递MarketplaceContext 持有运行配置访问器、数据库、缓存和服务;市场路由使用较小的 MarketplaceApiRouteContext
HTTP 适配routes/ 处理请求/响应与认证声明;市场核心路由仍位于根目录 marketplace_api_routes.py
用例与策略services/ 和根目录的 marketplace_services.py 等模块组织业务,已分离的策略接收显式请求身份与依赖
持久化ports/ 声明接口,db/repositories/ 提供对应 SQLite 实现;schema 演进归 db/schema_version.py
页面与客户端Frontend/src/App.tsx 组织路由,pages/、layouts/、components/、services/、types/、utils/ 承载当前前端
静态托管routes/frontend_spa.py 服务 Frontend/dist 和已知 SPA 路径,保留 API/文件路由的独立响应

组成根可以装配各层。新增 HTTP handler 应把业务操作交给服务,并将 SQL 放进所属 repository;已分离的服务通过参数接收身份、时间和路径,不读取 Flask request、session 或 g。不要因新增目录或接口就把所有旧模块宣称为已迁移。

app.py 的兼容访问器仍允许旧调用方改变运行配置、存储或数据库目标;组成根不反向导入 app。只有测试、脚本和外部 WSGI 消费方都完成迁移后,才可移除旧全局变量或导入转发。具体启动副作用见后端组成。

已有持久化接口 ​

接口所属边界
IndexStateRepository索引状态、签名、耗时与错误的读写;不是所有制品查询 SQL 的统一接口
JobRepository内置任务定义、运行登记、单飞、恢复与历史保留
OperationsAdminQuery运维管理页的有界只读投影
OperationsSupportStore支持会话状态与事件的持久化

各接口定义在 Web/Backend/ports/,实现在 db/repositories/。当前 services/ 仍主要是平铺模块,前端也仍使用 pages/ 等目录;features/marketplace 或 services/releases/ 这样的功能目录属于后续组织方向。

直接 SQL 的过渡范围 ​

直接调用 execute、executemany 或 executescript 的过渡范围限于现有 handler:

  • routes/admin_api.py:stats_overview。
  • routes/operations_relay.py:heartbeat、poll_tasks、create_task、task_receipt、list_hosts、list_receipts、list_support_events。

create_api_key 不在例外范围内。新增功能应通过服务或 repository 访问数据库,迁移后的 handler 随之退出过渡范围。

跨模块契约 ​

边界维护方式
HTTP 制品交付endpoint 负责认证和安全路径解析,交给 ArtifactDeliveryService 与 Flask adapter 处理表示、Range 和完成回调,详见交付契约
身份与权限AuthPolicy 处理凭据和范围判断,Flask adapter 处理请求上下文与响应,详见HTTP 认证
上传后的索引services/storage_events.py 按路径分派刷新;当前仍有中央条件分支,文件、索引和缓存并非一次原子提交,详见公共读模型
调度与刷新互斥任务运行登记由 SQLite repository 提供;插件全量及制品作用域刷新另有进程内锁,不能把任务单飞推定为多 WSGI worker 下全部刷新路径已互斥,详见任务与插件索引
观测数据HTTP、SPA 导航、下载完成和审计各有口径与保留范围;身份 HMAC、代理地址和查询字段限制见访问及性能观测

扩展处理器由受信任的应用代码静态注册,上传的插件包或制品不能作为服务器 Python 扩展被动态执行。

API 兼容原则 ​

公共、管理、发布、下载及旧路径适配器都有消费者,变更时核对 WPF 客户端、React 客户端和发布脚本。保留仍被依赖的默认字段与错误语义;需要减少大响应时可增加显式 compact/分页视图。总量、当前页条数和 hasMore/游标须有准确含义。

不能兼容的新增表示应明确版本边界,例如 /api/v1/...;当前并非所有 API 已统一版本化。后端契约、前端请求代码/类型与相关测试需在同一变更中同步。各接口实际采用 SQL 分页、先构造再裁剪或文件回退,由公共读模型和插件目录说明,不能仅从 compact 名字推定效率。

性能预算与现有检查 ​

开发时避免把制品哈希、全量目录扫描、索引重建或统计事务阻塞放进公共请求关键路径。当前部分回退仍有磁盘读取、哈希或存储修复;这是一项演进约束,不能当成所有 GET 的现状保证。

检查或目标范围
已接入构建:管理首页 gzip ≤ 450 KiBcheck-dashboard-bundle.mjs 从 Vite manifest 的 index.html、AdminLayout.tsx、Dashboard.tsx 三个根追踪静态 imports,按去重后的文件统计 .gz 大小;没有变体时计原始字节,超限失败
静态压缩校验precompress-static.mjs 为可压缩的 HTML/CSS/JS/JSON/SVG 生成更小的 gzip/Brotli 文件,并解压比对原文;这是文件正确性检查
设计预算:非分页 JSON ≤ 256 KiB针对会随数据增长的响应,需用实际接口样本或 focused benchmark 验证
设计预算:公共入口 preload ≤ 550 KiB gzip与管理首页 450 KiB 的根集合不同,不能混作同一个构建门禁
设计预算:请求内同步文件系统工作 ≤ 50 ms需在明确硬件、目录规模和冷/热状态下测量,构建通过不证明已达到

管理首页检查不会自动计入未作为根的动态路由,也不包括 CSS、图片、接口数据或完整浏览器加载时间。它是静态模块依赖预算。超出设计预算时应说明实测原因并给出针对性的回归证据,不能把历史数字当成当前结果。

前端使用按路由懒加载和请求取消来控制入口体积及过期响应;静态变体的 HTTP 协商归 frontend_spa.py。性能复测需分别记录表示字节数、冷/热耗时和真实页面加载行为。历史测量见Web 性能基线。

验证范围 ​

在隔离环境核对运行时权限和实际下载。前端构建只写本地 dist。

powershell
Push-Location Web\Frontend
try {
    npm run lint
    if ($LASTEXITCODE -ne 0) { throw 'Frontend lint failed.' }
    npm run build
    if ($LASTEXITCODE -ne 0) { throw 'Frontend build failed.' }
}
finally { Pop-Location }

性能敏感变更按相同环境和数据复测流式交付、存储一致性或浏览器行为。

基于 MIT License 发布。