概要
独立交付论文检索任务平台,围绕手机号认证、任务创建、Worker 共享表对接、SSE 状态同步、额度流水、支付宝升级和管理后台形成测试验收版闭环。
业务价值
把甲方论文检索 Worker 与用户侧平台边界隔离,用户只需要创建任务、观察进度、下载结果和管理额度,便于测试验收和后续生产联调。
工程深度
覆盖异步任务契约、PostgreSQL 触发器、LISTEN/NOTIFY、SSE 推送、额度流水、支付宝回调、FastAPI 分层、React 功能模块和 pytest/Vitest/Playwright 回归。
证据来源
本地仓库 README / docs/架构说明 / docs/交付文档 / apps/api / apps/web / tests
仓库 · 置信度 高 · 验证时间 2026-05-17
- 证据级别:严格复核(核心区仅展示可复核指标)
- 来源类型:仓库/代码记录
- 来源链接:未提供公开链接,需结合履历或交付记录复核
- 验证时间:2026-05-17(距今 0 天,时效性高)
判定原因:判定为高置信度:按严格口径整理,可回溯到仓库或代码记录,验证时间距今 0 天。
背景
平台需要为用户提供论文检索任务入口,但实际检索由甲方 Worker 通过共享 PostgreSQL tasks 表执行,系统必须清晰隔离用户侧和 Worker 边界。
挑战
任务执行是异步且跨系统的:用户需要看到实时进度,Worker 需要按数据库契约回写结果,额度又不能在任务失败或重复通知时被误扣。
行动与成果
解决方案
- 搭建全栈平台:用 FastAPI + React/Vite 交付登录、任务工作台、个人中心、额度流水、支付升级和管理后台。
- 固化 Worker 契约:通过 Alembic check constraint 和触发器约束任务状态流转、终态字段和结果数,避免 Worker 回写破坏用户侧假设。
- 实现状态同步:使用 PostgreSQL
pg_notify + asyncpg LISTEN 唤醒 SSE,前端同时保留轮询兜底,覆盖单任务、多任务和全局活动任务。 - 治理额度与支付:成功任务再扣减额度,使用锁与唯一事件防重复;支付宝支付成功后恢复 Pro 额度,并在额度流水中留痕。
成果
交付测试验收版论文检索平台,形成用户认证、任务提交、状态同步、结果下载、额度流水、支付升级和管理后台的完整闭环。
关键指标
基于 FastAPI、SQLAlchemy、Alembic、PostgreSQL、Redis 和 React/Vite 搭建用户端、管理端、任务、支付、额度与健康检查等核心模块。 在甲方 Worker 只读写共享 `tasks` 表的约束下,设计 `pending -> running -> success/failed` 状态契约,并通过数据库触发器约束终态回退、完成时间和成功结果数。 实现任务状态 LISTEN/NOTIFY 监听、按任务 SSE、多任务 SSE、全局活动任务 SSE 与轮询兜底,减少用户侧等待时的状态盲区。 将额度扣减延后到任务成功后执行,结合 `SELECT ... FOR UPDATE`、唯一额度事件、并发测试和月度额度流水,避免任务失败或重复通知造成额度误扣。 技术栈
PythonFastAPIAsyncIOSQLAlchemyPostgreSQLRedisAlembicReact 19TypeScriptViteZustandSWRPlaywright