1. 项目背景

PaperFlow 的定位不是通用内容社区，而是面向 AI 研究者的科研内容平台基础底座。项目目标是将论文内容浏览、PDF 阅读、评论互动、学习路径规划和可视化探索纳入统一工程体系，形成可演示、可联调、可迭代的前后端闭环，并分阶段接入更完整的 Agent 能力。

本阶段目标如下：

• 前端需要具备完整页面骨架，支持登录、内容浏览、个人中心、管理后台、AI 阅读与 Pathfinder。
• 后端需要以统一网关为入口，收敛鉴权、限流、错误归一化和服务路由。
• 用户服务负责身份体系与资料管理，内容服务负责帖子、评论、互动行为、学习路径、AI 对话等业务。
• 工程层面需要支持本地开发、Mock 联调、Docker Compose 部署与多环境切换。

本阶段建设重点是打通前后端主链路并建立可持续扩展的工程底座，不以一次性覆盖全部科研 Agent 场景为目标。

2. 建设目标

2.1 业务目标

• 为科研内容平台提供统一 Web 入口。
• 建立基础账号体系，支撑普通用户与管理员两类角色。
• 提供帖子阅读、评论互动、收藏、足迹沉淀等基础内容能力。
• 为论文阅读与学习路径规划预留 AI 扩展空间。

2.2 技术目标

• 前端与后端彻底解耦，支持 Mock 模式和真实网关模式并行开发。
• 后端采用网关 + 业务服务拆分，避免前端直接耦合多个服务。
• 数据层通过 Flyway 迁移脚本维护结构变更，保证开发环境可复现。
• 使用脚本与 Compose 统一本地启动、构建和部署路径。

2.3 成功标准

• 用户能够完成登录、进入帖子流、查看详情、发表评论。
• 管理员能够进入用户管理、评论审核、帖子评论策略和邮件模板配置页面。
• 论文阅读页可以调用统一 AI 对话接口，Pathfinder 页面可以生成并保存学习路径。
• 前端可以在 Mock 模式跑通页面，也可以切换到真实网关做联调。

3. 当前阶段边界

为明确范围边界，现定义本阶段已实现能力与未纳入范围如下。

3.1 当前已实现能力

• React SPA 已具备完整路由、鉴权守卫和管理员页面入口。
• API Gateway 已配置用户服务、内容服务、AI 与 Pathfinder 等路由。
• 用户服务已具备注册、登录、找回密码、资料维护、头像上传、外部绑定预留能力。
• 内容服务已具备帖子、评论、审核、点赞、收藏、足迹、Pathfinder 会话、AI 对话、论文资产缓存等能力。
• Docker、脚本、文档体系已经形成，可支撑本地开发与部署。

3.2 当前阶段边界

• Python 侧五 Agent 工作流存在代码骨架，但不属于当前 Web 主业务链路的核心交付。
• 仓库没有证据表明已完成生产级知识图谱、成熟 RAG 向量检索平台或完整多租户体系。
• 网关为 Agent 服务预留了转发入口，但 Agent 下游业务本体不在本次交付范围内。

3.3 后续可扩展方向

• 引入更完整的论文知识库、向量检索与引用追踪能力。
• 把 Python Agent 工作流与现有 Java 内容服务做更稳定的契约集成。
• 补充自动化回归测试、审计日志和生产级观测能力。

4. 总体架构

当前系统采用前后端分层架构：

浏览器 / React SPA
        │
        ▼
API Gateway（统一入口）
   ├── User Service
   └── Content Service
        │
        ▼
PostgreSQL / H2（开发默认）

扩展侧：
Python FastAPI + Five-Agent Workflow（独立演进）

该架构的职责划分如下：

• 前端只面向 /api/v1 契约开发，不直接感知后端服务拆分细节。
• 网关统一处理 JWT、限流、错误包装和服务路由。
• 用户服务聚焦身份与账号域，内容服务聚焦帖子、评论、互动和 AI 相关业务。
• Python Agent 可以独立演进，不会直接污染当前主站 Web 链路。

5. 前端需求与方案设计

5.1 技术栈选择

前端位于 apps/paperflow-web，技术栈组成如下：

• React 18：负责页面组件化与状态驱动渲染。
• React Router 6：负责页面路由与鉴权守卫。
• Vite 5：提供开发服务器与构建能力。
• TypeScript：保证接口类型和页面模型约束。
• D3：用于可视化页面。
• pdfjs-dist：用于论文 PDF 阅读能力。

前端技术栈选型依据包括开发效率、类型约束能力、可视化支持能力和构建性能。

5.2 页面需求拆分

前端页面体系如下：

• 公共页面：登录页、帖子列表页、帖子详情页、可视化页、Pathfinder 页、论文阅读页。
• 登录后页面：个人中心、收藏页、足迹页。
• 管理页面：用户管理、评论审核、帖子评论策略、邮件模板配置。

前端系统需支持用户角色管理、后台治理能力和 AI 功能扩展入口。

5.3 鉴权与权限需求

前端通过 AuthContext 管理登录态，核心约束包括：

• Access Token 存在本地，用于访问受保护接口。
• 页面初始化时主动拉取 /api/v1/users/me 校验身份有效性。
• 普通登录用户才能进入收藏、足迹、个人中心。
• 只有带 ADMIN 角色的用户才能进入管理页面。

前端权限控制采用分层机制：路由守卫控制页面访问权限，Bearer Token 控制受保护接口访问，管理动作授权由服务端执行最终校验。

5.4 前端接口协作需求

前端 API 封装采用统一入口，覆盖以下接口类别：

• 认证与账号：登录、注销、注册邮箱验证码、注册、找回密码。
• 用户资料：获取个人信息、修改资料、上传头像。
• 内容互动：帖子列表、帖子详情、评论、点赞、收藏、足迹。
• 管理后台：用户管理、评论审核、邮件模板配置、帖子评论策略。
• AI 能力：统一 AI 对话接口与 Pathfinder 会话接口。

前端应维持统一 API 封装规范，页面层仅负责调用业务函数，不分散实现请求逻辑。

5.5 前端重点能力

5.5.1 内容消费链路

• 首页默认跳转到帖子流。
• 帖子流支持进入详情页。
• 详情页承载评论与交互逻辑。
• 用户可以对帖子执行点赞、收藏，对评论执行点赞。

5.5.2 论文阅读链路

• 独立的论文阅读页使用 /papers/:postId 路由。
• 前端已经区分普通帖子详情和 PDF 阅读详情两种体验。
• AI 对话与翻译统一走 /api/v1/ai/chat，避免把学习路径规划接口误用成聊天接口。

5.5.3 Pathfinder 学习路径链路

• Pathfinder 页面独立存在，不与普通帖子阅读混在一起。
• 前端支持生成学习计划、保存会话、查询历史会话和收藏路径。
• 会话模型中已经包含目标、模型、阶段、对话消息和当前激活阶段等字段。

5.5.4 Mock 与真实联调双模式

前端联调模式要求如下：

• npm run dev:mock 同时拉起前端与 Mock API。
• 切换真实环境时只需要调整 API Base，前端页面层不需要改代码。

该模式用于降低并行开发阶段的接口依赖阻塞问题。

6. 后端需求与方案设计

后端采用 Spring Boot 多服务拆分，核心目录是 backend/services。

6.1 API Gateway 需求

API Gateway 除路由转发外，还承担统一鉴权、限流、错误归一化和扩展接入职责，具体如下：

• 统一入口：所有前端请求优先进入网关。
• 路由分发：把用户相关请求转发到 user-service，把内容相关请求转发到 content-service。
• JWT 能力：统一鉴权配置，避免每个服务重复实现一套前置认证。
• 限流能力：区分匿名、认证用户、公共 GET 等不同维度的访问频率。
• 错误归一化：对前端输出统一的 requestId + data/error 结构。
• 预留扩展：为 /api/v1/agents/** 提供下游接入口。

网关层用于保持前端访问入口稳定，并隔离后端服务拆分带来的契约变更。

6.2 用户服务需求

用户服务负责账号域核心能力，至少包括以下内容：

• 登录、注销、刷新令牌。
• 基于邮箱验证码的注册流程。
• 找回密码与确认重置。
• 用户资料维护，包括显示名、头像、简介等字段。
• 用户状态与角色管理。
• QQ / 微信绑定等第三方能力预留。
• 邮件模板配置，支持多模板类型。

用户服务数据模型除基础用户信息外，还应覆盖 refresh token、验证码记录、外部绑定和邮件模板配置。

6.3 内容服务需求

内容服务覆盖以下业务能力：

• 帖子列表与详情查询。
• 评论发布、评论审核、评论树结构。
• 帖子点赞、评论点赞。
• 收藏与足迹沉淀。
• 每日内容生成能力。
• 帖子评论审核策略开关。
• Pathfinder 会话持久化与收藏。
• AI 聊天统一接口。
• 论文资源缓存。

当前阶段，内容服务集中承载社区内容、论文阅读支撑和学习路径能力；后续可根据业务规模评估拆分方案。

6.4 Python Agent 扩展能力

app 目录下的 FastAPI 应用提供以下扩展能力：

• 支持 PDF 上传、解析、任务查询与原文件访问。
• 提供划词翻译接口。
• 提供五 Agent 工作流运行接口和运行记录查询接口。
• 提供面向 PDF 语料的 Sage 问答接口。

Python Agent 相关能力定义为扩展能力，不纳入当前 Java 网关主链路的核心交付范围。

7. 前后端接口协作设计

7.1 统一接口前缀

前后端接口统一使用 /api/v1 作为版本前缀，用于支持后续版本管理与灰度演进。

7.2 登录链路

登录链路如下：

1. 前端调用 /api/v1/auth/login。
2. 网关转发到用户服务。
3. 用户服务校验账号密码并签发 Access Token。
4. 前端保存 Token，再调用 /api/v1/users/me 获取资料和角色。
5. 后续页面守卫依据角色决定是否开放管理页面。

7.3 内容浏览与评论链路

帖子与评论链路如下：

1. 前端调用 /api/v1/posts 获取分页帖子流。
2. 进入详情后继续调用 /api/v1/posts/{postId} 和 /api/v1/comments。
3. 用户发表评论时携带 Bearer Token。
4. 网关完成鉴权后，把用户身份透传给内容服务。
5. 内容服务按帖子策略决定评论是否需要审核。

7.4 AI 阅读与学习路径链路

AI 聊天能力与学习路径规划能力必须使用独立接口，不得混用。

• 阅读页、帖子详情页的问答或翻译统一走 /api/v1/ai/chat。
• Pathfinder 规划单独走 /api/v1/pathfinder/sessions/plan。
• 生成后的路径可通过会话接口持久化、分页查询和收藏。

接口分离要求用于保持提示词职责边界清晰和接口语义稳定。

8. 数据库设计要点

8.1 用户域数据

用户域核心表结构包括：

• pf_user：用户基础信息、角色、时间戳。
• pf_refresh_token：刷新令牌记录。
• pf_user_verification：验证码与验证记录。
• 其他增量字段：头像、简介、手机号、邮箱验证时间、QQ 绑定信息、微信绑定信息。

账号体系应覆盖认证、资料管理、验证和外部绑定四类能力。

8.2 内容域数据

内容域核心表结构包括：

• pf_post：帖子主表。
• pf_comment：评论主表，并已经支持父子评论关系。
• pf_post_favorite：帖子收藏。
• pf_post_footprint：用户足迹。
• pf_post_like：帖子点赞。
• pf_comment_like：评论点赞。
• pf_pathfinder_session：学习路径会话。
• pf_paper_asset：论文资源缓存。

内容域数据按帖子、评论、互动行为、学习路径会话和论文资源分别建模，以支持独立索引优化与统计分析。

8.3 数据设计结论

基于当前数据模型，形成以下数据设计要求：

• 平台已经不是单纯的“帖子表 + 评论表”结构，而是具备用户行为沉淀能力。
• Pathfinder 已经不是前端临时状态，而是后端持久化实体。
• 论文阅读资源已经开始进入独立缓存管理，而不是散落在静态文件目录中。

9. 非功能需求

9.1 安全性

• JWT 密钥、数据库地址、邮件配置、OAuth 参数、模型 Key 都通过环境变量注入。
• 管理页面基于角色控制访问，避免普通用户误入后台。
• 网关统一处理认证与限流，降低业务服务裸露风险。

9.2 可维护性

• 前端接口封装集中管理。
• 后端配置通过 application.yml 统一维护。
• 数据库变更通过 Flyway 迁移脚本管理。
• 脚本目录覆盖本地启动、部署、文档生成和数据准备流程。

9.3 可扩展性

• 网关路由天然支持后续继续拆服务。
• 内容服务已预留 AI、Pathfinder、内部 Agent 接口入口。
• Python Agent 服务独立存在，便于后续进行更强的实验迭代。

9.4 可观测性与排障

• 网关文档要求统一返回 requestId，便于前后端联合排查。
• 多环境配置与脚本入口相对固定，可降低环境一致性问题的排查成本。

10. 部署运维与开发流程需求

10.1 本地开发流程

开发流程应包含以下阶段：

1. 先用前端 Mock 模式验证页面与交互。
2. 再启动网关、用户服务、内容服务做真实联调。
3. 最后验证 Pathfinder、AI 对话、管理后台等高耦合页面。

10.2 当前可直接复用的命令

cd F:\Gitee\PaperFlow\PaperFlow

# 前端 Mock
.\scripts\run-spa-mock.ps1

# 前端接真实网关
.\scripts\run-spa.ps1

# 本地整体启动
.\scripts\run-local.bat up

# 多环境部署
.\scripts\deploy.ps1 -Env dev

10.3 Docker 部署要求

开发环境 Docker 编排要求如下：

• PostgreSQL 作为统一数据库基础设施。
• user-service、content-service、api-gateway 分别独立构建。
• 网关通过环境变量感知下游服务地址。
• 数据库密码、JWT 密钥、限流阈值等通过环境变量注入。

该编排方案用于保证基础环境一致性，并为后续生产环境扩展提供基础。

11. 测试与验收要求

验收范围分为页面验收、接口验收和数据验收三类：

11.1 页面验收

• 登录页能完成认证闭环。
• 帖子流、详情页、收藏页、足迹页可正常展示。
• 管理员登录后可见后台菜单并执行关键操作。
• Pathfinder 页面可生成并保存学习路径。

11.2 接口验收

• /api/v1/auth/* 认证接口可正常调用。
• /api/v1/posts、/api/v1/comments 主链路可用。
• /api/v1/admin/* 接口在管理员身份下可用。
• /api/v1/ai/chat 与 /api/v1/pathfinder/sessions/* 契约稳定。

11.3 数据验收

• Flyway 迁移脚本可成功初始化数据库。
• 用户、帖子、评论、互动行为、Pathfinder 会话均可持久化。
• 收藏、足迹、点赞等行为具备正确索引与查询基础。