数字资源管理入库系统产品系统Vibe Coding

一、 行业背景
随着出版行业数字化转型的持续深化，盘活历史纸质图书存量资源、构建高质量数字资产库，已成为出版机构提升知识服务能力的核心战略。当前，历史图书数字化业务通常涉及出版社内部与多家外包转码公司的跨组织协同。然而，传统的业务流转高度依赖电子邮件与共享网盘，这种松散的协作模式缺乏统一的技术规范与流程管控，已难以适应当前大规模、高标准、严要求的现代数字出版生产与资产管理需求。
二、 立项原因
现有业务模式在实际运行中暴露出显著的管理痛点与技术瓶颈，亟需通过系统性建设予以彻底解决：
1. 现有流程存在多重管理与业务痛点：传统流转方式导致各方交接标准不一致、任务进度缺乏透明度、核心元数据缺失严重；同时，生产过程中的异常问题无法有效追溯，且历史数字资源的检索与复用效率极低，严重制约了业务效能。
2. 亟需构建全流程闭环与海量数据支撑能力：为破除上述瓶颈，亟需立项建设一套统一的“历史图书数字化资源管理平台”。该平台旨在将原稿上传、任务发布、外包处理、成果回传、内部校验、验收归档、异常隔离至检索分析的全生命周期收敛于单一系统内，实现全链路的标准化与闭环管理。此外，针对约 100TB 级的海量历史资源规模，必须从底层架构设计上保障系统的长期稳定运行与高效查询能力，从而全面提升数字化资源的管理效能与长期业务价值。

一、软件功能与核心功能模块
系统为模块化单体的企业级 Web 后台，前台使用角色为出版社人员与转码公司人员，核心模块包括：
1. 图书与元数据模块：以规范化书号 canonical_book_no 作为图书唯一标识，维护图书、版本与文件资产；书号、作者等元数据由 EPUB 提取而非人工录入。
2. 任务协作模块：出版社发布转码任务，转码公司处理并回传成果，任务状态经状态机受控流转，禁止直接改状态；转码公司侧只呈现待处理、处理中、已回传、已退回、已作废五态，内部校验与验收状态不外泄。
3. 文件与上传模块：受控本地文件存储，支持大文件分片上传、断点续传与对账补传，下载走浏览器原生与 HTTP Range 分片。
4. 校验验收与异常治理模块：成果 EPUBCheck 校验、验收通过或退回、异常隔离与返工闭环，全流程留痕。
5. 归档与检索模块：对归档成果做结构化解析、切片与检索单元生成，并导出只读知识投影。
6. 权限与审计模块：组织级 RBAC、幂等键与 X-Request-Id、操作审计与状态变更事件。
7. 运行健康看板与统计报表：监控数据库、向量库、各类 worker 与后端服务状态。
二、业务流程与功能路径
典型路径为：出版社上传原稿 → 发布转码任务 → 转码公司下载原稿（首次下载触发任务进入处理中）→ 回传成果包（先上传文件资产、再创建提交批次）→ 系统自动校验 → 出版社验收（通过则归档，不通过则退回返工）→ 归档后重建切片、生成知识投影用于检索分析。异常文件进入隔离区，处理完成后回到任务流；每一次状态变更都会同步写入状态事件与审计日志，保证全流程可追溯。

一、整体架构与设计思路
采用模块化单体架构，前后端分离。前端 React + TypeScript + Ant Design Pro + Vite，TanStack Query 管服务端状态、Zustand 管会话状态；后端 Python + FastAPI + Pydantic 校验 + SQLAlchemy 2.x + Alembic 迁移；数据库 PostgreSQL（预留 pgvector），异步任务与缓存用 Redis + Celery。文件本体不进数据库，进入受控本地存储，库内只存元数据、状态、索引与存储定位字段；大文件处理、校验、OCR、向量化一律走异步 worker。设计上坚持先冻结契约再写代码：实体模型、数据库 schema、API 契约、前后端设计五份文档冻结后才进入实现，状态变更一律走业务动作端点。
二、我负责的模块和结果
我负责系统从 0 到 1 的设计与实现，覆盖需求契约冻结、后端核心服务、前端后台与归档派生能力。量化结果：仓库累计 277 次提交（2026-05-06 至 09-30）；后端 190 个 Python 文件、20 个 API 模块、15 个服务包、67 个测试文件，阶段一 pytest 288 项全通过；前端 106 个 TS/TSX 文件、39 个测试文件，覆盖 81 个路由入口；EPUB 结构化解析把 14 本样书解析出 4264 个结构节点、33414 条证据记录、3584 个资产；开发库 14 个知识投影结构检查全部通过，统计 6605 个检索单元、31739 条 Canonical 证据；切片/向量化/静态契约定向测试 106 项通过；完成 FMS 与 WeKnora 生产网关打通，首次投影同步已在生产进入 running。