Litefs 框架开发任务清单

当前版本: v0.9.0 目标版本: v1.0.0（方案见 release-roadmap.md，待评审） 更新日期: 2026-10-21 基线 Commit: cb2988f

阶段进度：P0 ✅ → P1 ✅ → P2 ✅ → P3 ✅（v0.9.0 已发布）→ 0.x.x 路线待评审

路线调整（2026-10-21）：v1.0.0 硬性标准拆分为 6 个 0.x.x 版本逐步交付。 硬性标准未全部达成前，不升级到 v1.0。

Generated by TRAE SOLO at 2026-10-20 16:32

项目现状（v0.8.3 基线）

指标	数值	说明
源码规模	约 22,500 行 / 88 个模块	`src/litefs`
测试覆盖率	46%（5643 语句，缺失 2817）	`coverage.json`
性能基准	Hello World 较 FastAPI 快 1.4~2.0 倍	8 核 20,976 req/s
Python 支持	3.8 ~ 3.12	`setup.py`

已完成能力

服务器: 自研 epoll / greenlet / asyncio HTTP 服务器，WSGI 1.0 / ASGI 3.0 兼容
路由: RadixTree 路由已集成（routing/router.py）
认证: JWT + OAuth2（GitHub / Google / 微信 / 企业微信 Provider 齐全）
中间件: 日志、安全头、CORS、CSRF、限流、健康检查、增强日志
数据: SQLAlchemy 连接池、多级缓存（Memory/Tree/Redis/Memcache/DB）、会话多后端
生态: WebSocket、Celery、OpenAPI/Swagger、插件系统、调试工具栏、热重载

v0.9.0 升级开发计划

P0 质量与稳定性（先行，为后续功能打底）

任务	内容	验收标准	状态
core.py 拆分	拆分为 `app/` 包（helpers + 4 个 Mixin + server_cli），core.py 保留装配与再导出	单文件 ≤ 600 行，行为不变	✅ 2026-10-20 完成（1216 → 105 行）
覆盖率提升	新增 20 个测试模块约 640 用例，修复 5 处源码 bug	46% → 70%（v0.9.0），85%（v1.0）	✅ 2026-10-20 完成阶段目标（70%，详见 unit-tests.md）
类型注解完善	核心模块 type hints	mypy 核心目录零错误	✅ 2026-10-20 完成（app/ 包 + core.py，81 → 0，详见 type-hints.md）
静态检查流水线	flake8 + ruff + mypy 纳入 CI	全部通过方可合并	✅ 2026-10-21 完成（`src/` 全量三工具零告警，CI 门禁已上线，详见 static-checks.md）

P1 可观测性与数据工具

任务	内容	状态
Prometheus 监控	PrometheusMiddleware、请求计数/延迟直方图/错误率、连接池与缓存命中指标、`/metrics` 端点、可选依赖懒加载	✅ 2026-10-21 完成（指标 7 项、路由模板低基数标签，详见 prometheus-monitoring.md） 2026-10-21 修复原生 Socket 链路指标未采集缺陷
数据库迁移	Alembic 封装（当前 `litefs db` 仅为提示占位），实现 `db init/migrate/upgrade/downgrade/current/history`	✅ 2026-10-21 完成（嵌套子命令 + 保留旧扁平入口，详见 database-migrations.md）

P2 功能扩展

任务	内容	状态
邮件发送	smtplib 封装、Message 类、Mako 模板邮件、附件、Celery 异步发送	✅ 2026-10-21 完成（零新增依赖，MIME 三态结构、TLS/SSL、指数退避重试、Celery 不可用自动降级，详见 mail-service.md）
i18n 国际化	gettext 封装、请求级 locale 协商、模板翻译函数	✅ 2026-10-21 完成（零新增依赖，四级 locale 协商优先级、线程局部隔离、恒等函数保障零行为变化，详见 i18n.md） 2026-10-21 修复原生 Socket 链路 `Content-Language` 与 locale Cookie 未写入缺陷

P3 工程化收尾

任务	内容	状态
性能回归基准	以 `benchmarks/` 为基础固化阈值，防止发布回退	✅ 2026-10-21 完成（16 组场景 / 32 项检查，RPS ≥ 基线 85%、P99 ≤ 基线 130%，零新增依赖，详见 performance-regression.md）
示例与文档同步	新功能各配 1 个示例 + 对应 docs 页面，更新 `index.rst`	✅ 2026-10-21 完成（新增 4 个可运行示例，重写 `examples/README.md`，修复 3 处失效交叉引用，详见 project-structure.md）
依赖安全审计	pip-audit 定期扫描	✅ 2026-10-21 完成（`scripts/audit_deps.py` + `make audit` + CI `security` job，审计面收敛至运行时依赖，详见 dependency-audit.md）

版本发布

任务	内容	状态
版本号统一	消除源码版本号硬编码，版本号升至 v0.9.0	✅ 2026-10-21 完成（消除 7 处硬编码，`_version.py` 为唯一权威源；新增 `server_software` 常量区分 WSGI `SERVER_SOFTWARE` 语义，两条响应链路输出格式不变）
发布物料	`CHANGELOG.md` + `RELEASE_v0.9.0.md`	✅ 2026-10-21 完成（`CHANGELOG.md` 为 Keep a Changelog 格式，已通过 `{include}` 引入 Sphinx 文档 `changelog.md`）
文档告警清零	Sphinx 构建告警	✅ 2026-10-21 完成（30 → 0，详见 `RELEASE_v0.9.0.md` 文档章节）

v1.0.0 升级计划（0.x.x 分步路线）

完整方案见 release-roadmap.md（含行业对标基线、15 条硬性标准、破坏性变更分配、验收门禁）定位：生产就绪 —— API 稳定承诺 + 质量硬指标达标对标对象：Starlette（近 8 年唯一真正走完 0.x → 1.0 的同代 ASGI 框架）

原则：硬性标准（H1–H15）全部达成前，不升级到 v1.0.0。 每一版 0.x 均为独立可发布版本（含 CHANGELOG、Release Notes、全量回归、性能基线不回退）。

版本路线

版本	主题	核心交付	绑定硬性标准	工作量	状态
v0.10.0	契约与结构重构	API 稳定性与 SemVer 政策、548 符号分级冻结（stable/provisional/internal 三级）、弃用机制与时间表、拆分 5 个超 600 行文件	H1 H2 H3 H6	≈7d	✅ 已完成
v0.11.0	类型系统与打包契约	`py.typed` 落盘、mypy `--strict` 全量零豁免（53 个）、公共 API 标注补齐	H4 H5	≈6d	⬜ 待启动
v0.12.0	测试基础设施与质量基线	核心服务器覆盖率 ≥80%、`conftest.py` + `TestClient`、整体覆盖率 ≥85%、pytest `filterwarnings=error`	H7 H8 H9 H10	≈12d	⬜ 待启动
v0.13.0	ASGI 协议与插件生态	ASGI lifespan、原生 streaming、ASGI 中间件签名兼容、`entry_points` 插件发现	H11 H12	≈10.5d	⬜ 待启动
v0.14.0	工程化与 Python 基线收敛	GitHub PR 级 CI 门禁、删除 `setup.py`、核心依赖 optional 化、extras 重整、Python 3.10–3.14	H13	≈8d	⬜ 待启动
v0.15.0	发布基础设施与安全闭环	`SECURITY.md`、SBOM 与签名、版本化文档站、LTS 政策、迁移指南	H14 H15	≈7d	⬜ 待启动
v1.0.0	稳定性声明发布	API 冻结宣告、政策定稿、破坏性变更汇总专章、打标签发布、`1.0` 稳定分支	H1–H15 全达成	≈4d	⬜ 待启动

关键差距快照

指标	当前	目标	交付版本
测试覆盖率	72.2%	≥85%（核心模块 ≥80%）	v0.12.0
mypy 豁免模块	53 个	0 个（`--strict`）	v0.11.0
`py.typed`	❌ 无	✅ 随 wheel 分发	v0.11.0
`TestClient` / `conftest.py`	❌ 无	✅ 具备	v0.12.0
ASGI lifespan	❌ 报错	✅ 支持	v0.13.0
插件发现	仅目录扫描	✅ entry_points	v0.13.0
GitHub PR CI	❌ 无	✅ 三级门禁	v0.14.0
超 600 行文件	0 个	0 个	✅ v0.10.0 已达成
Python 基线	3.8–3.12	3.10–3.14	v0.14.0
`SECURITY.md` / SBOM / 签名	❌ 无	✅ 就绪	v0.15.0

版本里程碑

里程碑	内容
v0.9.0-alpha	P0 完成：core.py 拆分、覆盖率 ≥ 60%、CI 流水线
v0.9.0-beta	P1 完成：Prometheus + Alembic 迁移
v0.9.0-rc	P2 完成：邮件 + i18n，回归测试通过
v0.9.0	文档补齐、示例更新、正式发布 ✅ 2026-10-21
v0.10.0 – v0.15.0	硬性标准分步交付（契约 → 类型 → 质量 → 协议 → 工程 → 发布）
v1.0.0	稳定性声明发布（H1–H15 全达成后）

风险与对策

风险	影响	对策
core.py 拆分引入回归	高	拆分前先补齐对应模块测试，行为快照对照
Prometheus 依赖侵入核心	中	设计为可选依赖 + 懒加载导入
Alembic 与 SQLAlchemy 版本耦合	低	现有 `SQLAlchemy>=2.0.0` 已满足 Alembic 要求

备注

架构约束：HTTPS 不在框架内实现，生产环境由 Nginx/HAProxy 做 SSL 终止
所有新功能需附带单元测试并同步文档，遵循语义化版本与向后兼容
每周五评审进度

文档维护: 开发团队