【项目实训个人工作记录（二）】—— 前后端架构实现与AI接口预留

本阶段重心是搭好前后端可运行骨架、定栈、并为大模型能力预留清晰边界：传统阅读与用户数据留在 Spring Boot；与生成式模型强相关的推理与编排放在独立 ai-service（FastAPI）；Vue 3 + Vite 仅通过同源 /api 与后端对话，不直连 Python，降低跨域与安全配置成本。

在架构上，考虑到 AI 推理、编排与 Python 生态结合更自然，未将大模型实现嵌入 Java 业务层，而是单独维护 ai-service（FastAPI），在 Java 后端通过 HTTP JSON 调用该中台。整体可概括为三层：frontend（Vue 3 + Vite）、backend（Spring Boot）、ai-service（Python FastAPI）。这样，传统的阅读、计时等业务流程仍留在Java后端，而AI相关功能在pyhton服务端，代码架构边界清晰。

开发环境下前端经 Vite 将 /api、/uploads 代理到 http://localhost:8080，浏览器只与同源代理交互；与 AI 相关的请求先到 Spring Boot，再由 AiBridgeService + RestTemplate 转发到 application.yml 中配置的 vistaread.ai-service.base-url，对应 FastAPI 侧如 /v1/chat/role、/v1/knowledge/outline、/v1/plot/advance 等路由。传统阅读、用户、数据库等业务仍集中在 Java；AI 能力在 Python 侧迭代，职责边界清晰，便于后续接真实 LLM 或流式 SSE。

层级	目录 / 服务名	主要技术	职责概要	典型对外/被调边界
前端	`frontend/`（vistaread-frontend）	Vue 3、Vite 5、Vue Router 4、Pinia、Axios、Element Plus 等	SPA 界面与交互；经 Axios 请求同源 `/api`、`/uploads`	浏览器 → Vite 开发服务器；不直连 Python
开发代理	`frontend/vite.config.js` 中 `server.proxy`	Vite proxy	将 `/api`、`/uploads` 转发到后端	`/api` → `http://localhost:8080`；`/uploads` → `http://localhost:8080`
后端	`backend/`（vistaread-backend）	Spring Boot 3、Java 17、MyBatis-Plus、MySQL、JJWT 等	用户/阅读等业务 REST；JWT 鉴权；AI 桥接	对外：`/api/**` 等；对内 HTTP：`vistaread.ai-service.base-url`（默认 `http://localhost:8000`）
AI 中台	`ai-service/`（FastAPI）	Python、FastAPI、Pydantic	大模型相关占位/实现：剧情、角色对话、知识大纲等	被 Java 调用：`/v1/plot/advance`、`/v1/chat/role`、`/v1/knowledge/outline` 等

二、任务与范围

（一）需求或功能目标

本阶段的核心任务是搭建项目基础框架：完成前后端联调通过的基础骨架，确定统一技术栈与工程结构；通过配置化管理、AI 桥接层与 FastAPI 占位路由，完整预留 AI 调用链路；确保业务主流程与 AI 中台完全解耦，支持服务独立启停与团队并行开发，为项目后续迭代建立规范、稳定、可扩展的底层架构。

（二）涉及模块

前端： frontend/，Vite 代理、路由、Pinia、Axios、页面与布局。
后端： backend/，Spring Boot、MyBatis-Plus、JWT、AiBridgeService、AiFeatureController、PlotController/PlotService 等对 AI 的调用。
数据库： MySQL，application.yml 数据源与 schema.sql 等脚本。
AI 中台： ai-service/main.py，/health 与 /v1/... 占位接口。

三、技术实现

（一）搭建前后端框架

前端：采用 Vue 3 单页应用，Vite 5 作为开发与构建工具；使用 Vue Router 4 做路由、Pinia 管理全局状态、Axios 发起 HTTP 请求；UI 层使用 Element Plus 及 @element-plus/icons-vue 等，并结合 Tiptap、ECharts 等依赖支撑富文本与数据可视化等扩展场景。

前端代码架构：

frontend/
├── index.html                 # HTML 入口
├── package.json
├── package-lock.json
├── vite.config.js             # Vite 配置
└── src/
    ├── main.js                # JS 入口，创建应用
    ├── App.vue                # 根组件
    ├── router/
    │   └── index.js           # 路由定义
    ├── stores/
    │   └── user.js            # Pinia 用户状态
    ├── api/
    │   ├── http.js            # Axios 实例与请求封装
    │   └── notification.js    # 通知相关接口
    ├── layouts/
    │   ├── MainLayout.vue     # 主站布局
    │   └── AdminLayout.vue    # 管理端布局
    ├── components/            # 可复用组件
    │   ├── CommentComponent.vue
    │   ├── FocusTimer.vue
    │   └── RichTextEditor.vue
    ├── views/                 # 页面级视图
    │   ├── Home.vue
    │   ├── Login.vue
    │   ├── BookList.vue
    │   ├── Reader.vue
    │   ├── Community.vue
    │   ├── PostsDetail.vue
    │   ├── MyPosts.vue
    │   ├── MyLikes.vue
    │   ├── Notifications.vue
    │   ├── Sentence.vue
    │   ├── Knowledge.vue
    │   ├── Upload.vue
    │   ├── Profile.vue
    │   ├── AiChat.vue
    │   ├── PlotBranch.vue
    │   ├── EditorDemo.vue
    │   ├── admin/             # 管理端页面
    │   │   ├── AdminHome.vue
    │   │   ├── AdminBooks.vue
    │   │   ├── AdminPosts.vue
    │   │   ├── AdminComments.vue
    │   │   ├── AdminUsers.vue
    │   │   └── AdminStatistics.vue
    │   └── old/
    │       └── Reader.vue     # 旧版阅读器（保留）
    ├── styles/
    │   ├── global.css
    │   ├── tiptap-content.css
    │   └── README_Tiptap_Content.md
    └── utils/
        └── html.js

后端：以 Spring Boot 3.2.5、Java 17 为基础；数据访问采用 MyBatis-Plus；安全方面使用 JJWT（jjwt-api / jjwt-impl / jjwt-jackson）签发与校验 Token，配合自定义 JwtUtil 等满足登录态校验；数据源为 MySQL（application.yml 中配置 vistaread 库）。

后端代码架构：

backend/
├── pom.xml                                 # Maven 依赖与构建
└── src/
    ├── main/
    │   ├── java/com/vistaread/
    │   │   ├── VistaReadApplication.java   # Spring Boot 启动类
    │   │   ├── controller/                 # REST 控制器（HTTP 入口）
    │   │   │   ├── AuthController.java
    │   │   │   ├── UserController.java
    │   │   │   ├── BookController.java
    │   │   │   ├── ChapterController.java
    │   │   │   ├── ReadingController.java
    │   │   │   ├── ReadingCalendarController.java
    │   │   │   ├── CommunityController.java
    │   │   │   ├── CommentController.java
    │   │   │   ├── LikeController.java
    │   │   │   ├── NotificationController.java
    │   │   │   ├── CoinController.java
    │   │   │   ├── PlotController.java
    │   │   │   ├── SentenceController.java
    │   │   │   ├── StatisticsController.java  # 管理端统计等
    │   │   │   ├── PhotoUploadController.java
    │   │   │   ├── AiFeatureController.java     # 与 AI 服务桥接
    │   │   │   └── HealthController.java
    │   │   ├── service/                    # 业务逻辑（接口 + 实现分离处见 impl）
    │   │   │   ├── impl/                     # 如 UserServiceImpl、CommentServiceImpl 等
    │   │   │   ├── AuthService、UserService、BookService、ChapterService
    │   │   │   ├── ReadingService、ReadingCalendarService
    │   │   │   ├── CommunityService、CommentService、LikeService
    │   │   │   ├── NotificationService、PlotService、SentenceService
    │   │   │   ├── CoinWalletService、CoinCheckInService
    │   │   │   ├── AiBridgeService
    │   │   │   └── Admin*Service              # 管理端（帖子/用户/评论等）
    │   │   ├── mapper/                      # MyBatis-Plus Mapper（表访问）
    │   │   ├── entity/                      # 与表对应的实体（@TableName 等）
    │   │   ├── dto/                          # 请求/响应、分页查询等传输对象
    │   │   ├── config/                      # 配置
    │   │   │   ├── SecurityConfig、WebConfig
    │   │   │   ├── JwtAuthInterceptor、AppProperties
    │   │   │   └── MybatisPlusConfig
    │   │   ├── common/                      # 通用工具（如 ApiResult、解析工具）
    │   │   └── security/                    # JWT 等
    │   │       └── JwtUtil.java
    │   └── resources/
    │       ├── application.yml                # 数据源、JWT、上传限制、ai-service 地址等
    │       ├── schema.sql                    # 基础表结构与示例数据
    │       ├── update_*.sql                 # 增量库结构脚本
    │       ├── add_post_img_field*.sql
    │       └── mapper/CommentMapper.xml     # 需自定义 SQL 的 MyBatis 映射
    └── test/
        └── java/com/vistaread/              # 单元/集成测试（如 Coin、阅读日历、商城等）

前后端请求路径（与代码一致）：浏览器 → Vite（5173）→ 代理 /api、/uploads → Spring Boot（8080）→ 需要 AI 时由 AiBridgeService 再请求 FastAPI（8000）。

（二）预留AI接口

考虑到AI功能实现的复杂性，我在搭建框架时并未直接实现AI相关功能，而是在后端预留了对应的接口并创建以python代码为主的ai-service作为之后的实现。在后端中，我通过增加 AiFeatureController 和 AiBridgeService 文件，在配置项（application.yml）中使用vistaread:ai-service:base-url:指向中台根地址，最后HTTP JSON 调用中台的相关路由。通过以上实现，我为整个系统架构实现的AI接口的预留，后续项目AI对应功能的完成可在ai-service中实现。

1.配置解耦

vistaread.ai-service.base-url 指向中台根地址；通过 AppProperties（@ConfigurationProperties(prefix = "vistaread")）注入运行时配置，避免地址写死在业务代码中。

2. 桥接层

AiBridgeService 使用 RestTemplate 对 ai-service 发起 POST + application/json，封装 chatRole、knowledgeOutline、plotAdvance 等方法；捕获 RestClientException 时返回带 offline、占位文案或简化结构的降级结果，保证中台未启动时主流程仍可演示、前端不易因未捕获异常而中断。

3. 对外 REST 边界

AiFeatureController（/api/ai）：POST /api/ai/chat/role、POST /api/ai/knowledge/outline，内部委托 AiBridgeService 转发至 /v1/chat/role、/v1/knowledge/outline。
剧情推演：由 PlotController / PlotService 等业务入口组装请求体后调用 AiBridgeService.plotAdvance，对应 Python /v1/plot/advance（与「全部 AI 都挂在 AiFeatureController」的表述区分，更符合当前分层）。

4. ai-service

main.py 中 FastAPI 注册 /health 及上述 /v1/... 占位实现（如 knowledge_outline 返回可供前端渲染的 mindmap_json 结构）；文件头注释已说明后续可替换为真实 LLM 调用。

@app.post("/v1/knowledge/outline")
def knowledge_outline(body: KnowledgeIn):
    """占位：输出可供前端图渲染的 JSON 结构。"""
    snippet = (body.text or "").strip()[:200]
    mindmap = {
        "root": {
            "label": "阅读提炼",
            "children": [
                {"label": "主题", "children": [{"label": snippet or "（无文本）"}]},
                {"label": "人物", "children": [{"label": "待 LLM 抽取"}]},
                {"label": "冲突", "children": [{"label": "待 LLM 抽取"}]},
            ],
        }
    }
    return {"mindmap_json": mindmap, "style": body.style}

四、问题与解决

1. 前端请求 404，但浏览器地址栏仍是 localhost:5173

现象：控制台里访问 /api 返回 404。

原因分析：后端实际 context-path 与前端路径不一致。

处理：确认 Spring Boot 控制器前缀是否为 /api。

2. Java 报连接超时或 RestClientException，日志指向 ai-service

现象：后端日志出现连接失败，前端得到降级 JSON。

原因分析：仅启动了前后端，未启动FastAPI。

解决方式：保证三进程同机时 base-url 为 http://localhost:8000。

五、界面展示

登录界面：

主页：

六、AI prompt记录

使用AI：cursor

以下为便于复现与归档的prompt记录：

在传统 Java 后端与 AI 能力并存的前提下，给出 Java 业务层 + 独立 Python 中台的分层架构及联调思路。
结合当前项目，说明 Vite 如何把 /api 转发到 Spring Boot，以及 vistaread.ai-service.base-url 在 application.yml 中的作用。
在不破坏现有分层的前提下，为 ai-service 增加占位路由，并说明 Java 侧如何从现有 AiBridgeService 调用。
根据任务书与现有代码完善实现、修 bug；约束示例：最小改动、改动前与用户确认、不随意改数据库配置、改后可运行。

七、优化思路

桥接层健壮性：为 RestTemplate 配置连接/读超时，避免 Python 侧卡死时拖垮 Tomcat 线程；中台返回非 2xx 时与「进程不可达」区分处理，便于日志定位。
契约类型化：当前桥接多使用 Map<String, Object>，后续可将 AI 入参/出参收敛为 DTO + 校验，与 FastAPI 的 Pydantic 模型对齐，减少字段拼写错误。
可观测性：对 AiBridgeService 关键路径打结构化日志（书 id、路由、耗时、是否降级），并在管理端或运维侧预留健康检查聚合（Java 调 ai-service /health）。
配置与环境：使用 application-dev.yml / application-prod.yml 分离 base-url 与 JWT 密钥，避免生产误用开发默认值。

八、总结反馈

通过本阶段工作，有两点体会较深。第一，用配置项解耦中台地址（base-url）有利于本地开发、联调与部署环境切换，避免把 Python 服务地址写死在业务代码里。第二，在桥接层做降级与统一 JSON 契约，能在中台未启动或大模型未接入时仍跑通主流程，降低前后端并行开发的阻塞；后续在 ai-service 内替换真实模型时，只要保持路由与字段约定稳定，Java 侧改动面可控制在较小范围。