2026-09-09 关于近期建站已完成的工作（二）

更新一：工具库「速记速查」模块上线
#

功能概述：后台工具管理体系新增「速记速查」子模块，面向知识点快速浏览与碎片化记忆场景，原生支持多站点数据隔离。
技术实现方案：

• 数据层：采用分类-条目二级表结构，新增站点标识字段实现多站点数据天然隔离，通过外键关联保证数据一致性。
  
• 服务层：采用标准 MVC 分层架构，Entity/Service/Mapper/DTO/VO 全链路抽象，统一控制器对外提供公开查询与管理操作两类接口。
  
• 前端层：管理端实现分类标签切换、条目全量 CRUD、搜索分页与图片压缩上传；用户端实现友链式网格列表、深色全屏详情页，支持随机刷新、历史浏览栈、视觉样式自定义与全屏交互。
  
• 接入层：通过反向代理配置静态资源路由与 API 转发规则，统一注入站点标识头实现多站点精准路由。
  

问题与解决：

• 多源码目录不一致：梳理并统一前端主源码目录，归档历史备份目录，避免修改仅单处生效。
  
• 多站点异步竞态：站点快速切换时异步回调可能覆盖全局站点标识，通过回调中增加当前站点一致性校验解决。
  

更新二：工具库「论文阅记」模块落地
#

功能概述：工具库新增论文管理能力，支持 PDF 上传、自动转静态 HTML、文章撰写编辑、分类检索、一键复制与标注能力。
技术实现方案：

• 核心处理链路：PDF 文件上传至对象存储，调用 PDF 处理工具链转换为静态 HTML 并回传存储；仅 PDF 内容变更时触发转换，临时文件自动清理。
  
• 数据与逻辑层：分类与论文二级表结构，支持标题、关键词、摘要全局模糊搜索；复制操作共享存储文件仅新建数据库记录，删除操作仅软删数据保留文件。
  
• 前端交互：管理端提供分类管理、论文表格、富文本编辑与 PDF 预览；用户端提供双列/单列布局的分类页、支持 Canvas 涂鸦高亮的预览页。
  

问题与解决：

• 菜单权限与编码异常：补全角色-菜单关联关系，修正双重编码导致的中文乱码。
  
• 跨站点数据为空：前后端站点标识不匹配导致查询为空，通过显式传递站点参数、为不同站点初始化对应数据解决。
  
• 对象存储上传 403：上传文件未设置公开读取权限导致访问失败，通过上传时指定公共读 ACL 修复。
  
• 运行环境兼容：固定 Java 基础镜像版本，并预装 PDF 处理工具链，避免版本反复切换。
  

更新三：实验集合·音色评估项目接入
#

功能概述：工具导航新增「实验集合」分类，首发「音色评估」实验项目，独立部署的算法应用通过反向代理接入站点体系，新标签页打开保证隔离性。
技术实现方案：

• 前端接入：工具导航页新增实验分类入口，新标签页打开独立项目，实现应用间隔离。
  
• 服务部署：基于 Python Web 框架 + 深度学习框架部署算法服务，前端图表库实现可视化交互，监听本地端口提供服务。
  
• 接入层：反向代理配置独立路径转发至实验服务，统一透传客户端真实 IP 与主机头。
  

问题与解决：

• 部署包权限问题：对象存储中的部署包未开启公开读取，调整权限后正常下载。
  
• 页面渲染覆盖：并行加载的 DOM 操作互相覆盖，改为顺序异步执行保证渲染优先级。
  
• 反向代理 502：容器内代理地址指向自身回环口，改为容器网桥网关地址实现容器到宿主机的通路。
  
• 静态资源 404：服务模板使用绝对路径脱离代理前缀，全部改为相对路径适配。
  
• 图表交互异常：修正雷达图数据源格式与坐标轴范围，固定画布尺寸避免悬停重绘缩放。
  

更新四：「今日计划」效率模块上线
#

功能概述：用户端右侧栏新增今日计划卡片，后台配套完整管理能力，支持单次、每日、周期三种任务类型，内置自动生成副本机制。
技术实现方案：

• 任务生成机制：单次任务当日有效；每日任务保存后自动生成未来 3 天同名副本；周期任务按星期条件生成未来 7 天内副本；删除操作同步清理后续未完成副本。
  
• 批量保存逻辑：基于前端传入的保留 ID 列表，增量删除不在列表中的周期类任务，避免误删。
  
• 前端交互：管理端实现日期选择、拖拽排序、任务类型切换与每日总结；用户端右侧栏组件展示任务进度与总结区域，进度条统一使用主题色。
  

问题与解决：

• 菜单配置异常：修正表字段不匹配、图标不存在导致的菜单显示问题。
  
• API 通路缺失：补全请求路径前缀与反向代理规则，将硬编码的站点标识改为动态透传。
  
• 任务重复生成：重构批量保存逻辑，先清空当日周期任务再重建，解决重复保存问题。
  
• 副本生成失效：新建任务 ID 为空导致判断失效，改为基于任务名称与类型判断是否为新建。
  
• 构建缓存失效：容器分层缓存导致新代码不生效，使用无缓存构建强制更新镜像。
  
• 数据类型不匹配：修正计数查询返回值类型与接收类型不一致的编译错误。
  

更新五：站点体验与工程体系优化
#

视觉交互升级

1. 引用块样式重构：统一 Markdown 渲染的引用块样式，移除默认双引号装饰，改为左侧装饰条设计，优化阅读体验。
   
2. 导航栏体系升级：顶部导航新增「工具」一级类目，整合工具库与实验集合入口，完善信息架构。
   
3. 进度条视觉统一：今日计划进度条全程使用主题色，替代未完成状态的灰色样式，提升视觉一致性。
   

产品能力扩展

1. 游客评论待开放：调整评论系统权限配置，支持游客身份发表评论，降低用户互动门槛。
   
2. 社交栏配置待完善：补全社交栏子菜单（友链、留言），优化社交入口布局。
   

工程体系建设

1. 数据一致性治理：清理周期类任务的重复数据，保留最小 ID 记录，保证数据唯一性。
   
2. 自动化构建机制：服务端数据变更后自动触发前端构建，通过文件监控实现后端驱动前端发布，减少手动操作。
   

严重问题一：PDF 静态页面嵌入跨域与标注瓶颈
#

问题根因：PDF 转换后的静态 HTML 通过 iframe 嵌入时，对象存储跨域配置不当，导致父页面无法与 iframe 内文档通信，涂鸦标注的画布叠加层无法正常工作。
根治与方案：

• 采用 Canvas 叠加层方案，通过矩形绘制替代 DOM 操作绕开跨域限制，实现基础高亮与涂鸦能力。
  
• 标注数据暂存本地，预留后续持久化扩展能力。
  
• 跑通 PDF 转 HTML 全链路，转换效果与加载速度满足基础使用需求。
  

严重问题二：对象存储全线上传 403 权限故障
#

问题根因：存储桶默认私有读写，上传前的文件存在性检查需要读取权限，且上传后的文件未显式设置公开访问权限，导致全链路上传功能中断。
根治与方案：

• 重构上传逻辑，使用标准请求对象显式设置公共读 ACL，保证新上传文件可公开访问。
  
• 上传前的存在性检查增加异常捕获，权限不足时降级为直接上传，避免流程中断。
  
• 形成技术规范：对象存储上传必须显式指定文件访问权限，禁止依赖存储桶默认配置。
  

严重问题三：容器构建缓存导致代码更新不生效
#

问题根因：容器镜像采用分层缓存机制，当构建产物文件名未变化时，会直接复用历史缓存层，导致代码修改后重新构建，容器内运行的仍是旧版本代码。
根治与方案：

• 代码变更后强制使用无缓存模式构建镜像，禁用分层缓存复用，确保代码变更全量生效。
  
• 建立构建后校验机制：镜像构建完成后，通过解压容器内产物、检索特征关键字，验证代码是否实际更新。
  
• 规范发布流程：禁止仅凭构建成功与服务运行状态判断代码生效，必须经过产物校验。
  

严重问题四：反向代理地址错误导致服务 502 故障
#

问题根因：容器内反向代理使用本地回环地址指向宿主机服务，受容器网络隔离限制，地址实际指向容器自身，导致端口无法连通。
根治与方案：

• 制定容器网络通信规范：容器间互相访问使用容器网络的服务别名；容器访问宿主机服务通过容器网桥网关地址。
  
• 禁止在跨容器、跨主机场景下使用本地回环地址。
  
• 统一反向代理地址配置标准，避免同类问题复现。