chore(release): v2.4.1

AI-DOCS/SUMMARY.md

@@ -1,107 +1,52 @@
-# AI-DOCS 文档结构优化完成报告
-
-## 1. 项目概述
-
-已成功创建标准化的AI-DOCS文档结构，并完成现有文档的迁移。
-
-## 2. 目录结构
-
-```
-AI-DOCS/
-├── PRD/                    # 产品需求文档 (32个文件)
-├── Technical/              # 技术文档 (14个文件)
-├── Testing/                # 测试文档 (待填充)
-├── Deployment/             # 部署文档
-├── User/                   # 用户文档
-├── Development/            # 开发文档
-├── Archive/                # 归档文档 (包含原docs文件夹)
-└── assets/                 # 公共资源 (图片、模板)
-```
-
-## 3. 迁移统计
-
-- **总文件数**: 553个
-- **PRD文档**: 32个
-- **技术文档**: 14个
-- **归档文档**: 包含原docs文件夹所有内容
-- **图片资源**: 包含所有手册截图
-
-## 4. 文档规范
-
-### 4.1 命名规范
-- PRD文档: `{模块名称}PRD-v{版本号}.md`
-- 技术文档: `{主题名称}.md`
-- 测试文档: `{模块名称}测试{文档类型}-v{版本号}.md`
-
-### 4.2 版本管理
-- 使用语义化版本号
-- 旧版本文档移至Archive目录
-- 保持文档与代码同步
-
-## 5. 模板创建
-
-已创建以下文档模板：
-- PRD模板
-- 技术文档模板
-- 测试文档模板
-- 部署文档模板
-- 用户文档模板
-- 开发文档模板
-
-## 6. 链接更新
-
-已更新以下文件中的文档链接：
-- README.md
-- CONTRIBUTING.md
-- SKILL.md
-- docs-site/ (多个文件)
-
-## 7. 后续建议
-
-### 7.1 文档维护
-1. 定期更新文档，保持与代码同步
-2. 废弃文档及时归档
-3. 使用版本控制管理文档变更
-
-### 7.2 文档审查
-1. PRD需要产品经理审查
-2. 技术文档需要架构师审查
-3. 测试文档需要测试负责人审查
-
-### 7.3 文档工具
-1. 支持Markdown编写
-2. 支持图表 (Mermaid, PlantUML)
-3. 支持代码高亮
-
-## 8. 注意事项
-
-1. 原docs文件夹已移动至 `AI-DOCS/Archive/docs-original`
-2. 所有文档链接已更新指向AI-DOCS
-3. 文档模板位于 `AI-DOCS/assets/templates/`
-4. 每个目录都有README.md说明文档规范
-
-## 9. 文件清单
-
-### 主要目录
-- `AI-DOCS/PRD/` - 产品需求文档
-- `AI-DOCS/Technical/` - 技术文档
-- `AI-DOCS/Testing/` - 测试文档
-- `AI-DOCS/Deployment/` - 部署文档
-- `AI-DOCS/User/` - 用户文档
-- `AI-DOCS/Development/` - 开发文档
-- `AI-DOCS/Archive/` - 归档文档
-- `AI-DOCS/assets/` - 公共资源
-
-### 模板文件
-- `AI-DOCS/assets/templates/PRD-template.md`
-- `AI-DOCS/assets/templates/Technical-template.md`
-- `AI-DOCS/assets/templates/Testing-template.md`
-- `AI-DOCS/assets/templates/Deployment-template.md`
-- `AI-DOCS/assets/templates/User-template.md`
-- `AI-DOCS/assets/templates/Development-template.md`
-
----
-
-**完成时间**: 2026-05-29
-**执行者**: AI Assistant
-**状态**: 已完成
+# AI-DOCS 分类索引
+
+`AI-DOCS` 保存产品需求、技术专题、测试证据、部署材料和历史归档。与当前代码直接对应的架构、模块、API、操作和运维文档统一维护在 `docs-site`。
+
+## 当前规模
+
+截至 2026-07-14，`AI-DOCS` 共 177 个 Markdown 文件：
+
+| 分类 | 文件数 | 定位 |
+| --- | ---: | --- |
+| `PRD` | 32 | 产品目标、范围、流程和验收标准 |
+| `Technical` | 22 | 技术专题、面试亮点和设计说明 |
+| `Development` | 8 | 环境、规范和贡献材料 |
+| `Testing` | 5 | 测试计划、用例和报告 |
+| `User` | 4 | 用户材料和 FAQ |
+| `Deployment` | 3 | 部署专题材料 |
+| `assets` | 7 | 模板和文档资源 |
+| `Archive` | 95 | 历史版本、废弃方案和原始文档快照 |
+| 根索引 | 1 | 本页 |
+
+## 分类入口
+
+- [PRD](./PRD/README.md)：需求和验收边界。
+- [技术专题](./Technical/README.md)：架构专题、技术亮点和专项分析。
+- [开发材料](./Development/README.md)：环境、规范和贡献流程。
+- [测试材料](./Testing/README.md)：测试计划、用例和结果证据。
+- [用户材料](./User/README.md)：用户手册与 FAQ 原始资料。
+- [部署材料](./Deployment/README.md)：部署专题和交付说明。
+- [历史归档](./Archive/README.md)：不再作为当前实现依据的文档。
+- [资源与模板](./assets/README.md)：PRD、技术、测试和交付模板。
+
+## 与 VitePress 的关系
+
+| 内容 | 默认入口 |
+| --- | --- |
+| 当前系统架构、模块、API 和运维事实 | `docs-site` |
+| 产品需求和设计背景 | `AI-DOCS/PRD`、`AI-DOCS/Technical` |
+| 测试过程和交付证据 | `AI-DOCS/Testing` |
+| 历史方案和旧版本副本 | `AI-DOCS/Archive` |
+
+当一份专题材料影响当前开发或运维流程时，在 VitePress 中写一份简洁、可执行的现行说明，并链接到这里的背景材料。不要直接把归档文档加入主导航。
+
+## 维护规则
+
+1. 新文档进入最具体的分类目录，不放在 `AI-DOCS` 根目录。
+2. 文件名说明主题；需要独立版本管理的 PRD 使用语义化版本号。
+3. 当前实现发生变化时，优先更新 `docs-site`，再更新相关专题材料。
+4. 废弃方案移动到 `Archive`，并在标题或开头标明状态。
+5. 每个分类的 `README.md` 维护入口和新增规则。
+6. 不在两处维护相同的接口表、模块数、数据库表数或环境变量清单。
+
+VitePress 的分类和校验规则见 `docs-site/guide/documentation-maintenance.md`。

AI-DOCS/Technical/04-异步化与线程池治理.md

@@ -12,24 +12,23 @@
 
 ## 30 秒答法
 
-我在项目里把大量耗时链路做了异步化治理，一方面沉淀了 ThreadPoolUtils，把批量并发、超时控制、失败快速返回、指数退避重试、调度任务等能力统一封装；另一方面把 OJ 判题、通知发送、抽奖后置事件、计划提醒等链路接入 RabbitMQ，实现接口快速返回、削峰解耦和延迟投递，整体提升了系统吞吐和接口稳定性。
+我在项目里把耗时链路分成进程内并发和跨模块异步两层治理。进程内使用 Spring 托管的有界执行器，并在调用服务中显式设置超时和降级；具有独立容量模型的任务使用模块专用执行器。跨模块则把 OJ 判题、通知、抽奖后置事件和计划提醒接入 RabbitMQ，实现快速返回、削峰解耦和失败重试。
 
 ## 1 分钟展开答法
 
-项目里一开始有很多典型问题，比如接口里同步做通知、同步做判题、同步扫任务，这会导致请求耗时不稳定，而且某个下游一慢就会拖垮主链路。所以我做了两层治理。第一层是进程内并发能力，把常见异步模式统一沉淀成 ThreadPoolUtils，按 CPU 密集型、IO 密集型、调度型线程池拆分，补上超时、重试、并发限制、批量并行处理和链式异步调用能力；第二层是跨模块异步解耦，把判题、通知、抽奖后置事件和计划提醒这些链路接入 RabbitMQ，主接口只做最小必要操作，耗时任务交给消费者执行，同时支持延迟投递和失败重试。
+项目里一开始有很多同步通知、同步判题和同步扫任务，导致请求耗时不稳定，下游变慢时还会拖累主链路。第一层治理是让 Spring 统一管理线程生命周期和容量：通用 I/O 使用有界的 `applicationIoExecutor`，特殊场景使用模块命名执行器，超时与降级留在具体服务中。第二层是用 RabbitMQ 解耦跨模块任务，主接口只做最小必要操作，消费者负责延迟执行和失败重试。
 
 ## 你在项目里具体做了什么
 
 ### 1. 为什么要统一线程池
 
 - 很多项目喜欢在业务代码里直接 `new Thread` 或零散用 `@Async`。
 - 这样的问题是线程资源不可控，参数不统一，也难做监控和治理。
-- 所以我把并发能力收口到 `ThreadPoolUtils`：
-  - 通用线程池
-  - IO 线程池
-  - CPU 线程池
-  - 调度线程池
-  - 虚拟线程兼容支持
+- 所以我把线程资源收口到 Spring 容器：
+  - 通用 I/O 使用有界 `applicationIoExecutor`
+  - 热榜刷新等独立负载使用模块命名执行器
+  - 线程数、队列、拒绝策略和关闭等待统一配置
+  - 超时与降级由调用服务显式声明
 
 你要强调：
 
@@ -125,4 +124,4 @@
 
 ## 一句话背诵版
 
-我把项目里的并发和异步能力分成了两层治理：进程内通过 ThreadPoolUtils 统一封装批量并发、超时、重试和调度能力，分布式层通过 RabbitMQ 对判题、通知、抽奖后置事件和提醒任务做削峰解耦，从而同时提升接口响应和系统稳定性。
+我把并发和异步能力分成两层治理：进程内由 Spring 管理有界执行器，并在业务调用点声明超时和降级；分布式层通过 RabbitMQ 对判题、通知、抽奖后置事件和提醒任务做削峰解耦，从而同时改善接口响应和系统稳定性。

AI-DOCS/Technical/线程池与并发工具类使用指南.md

@@ -1,15 +1,27 @@
-# 线程池与并发工具类使用指南
+# 旧版线程池与并发工具迁移指南
 
-本项目提供了两个核心并发工具类，用于简化多线程编程和并发控制。
+> 版本说明：`ThreadPoolUtils` 和 `ConcurrentUtils` 已在 v2.4.1 删除。本文保留旧 API 示例用于迁移审查，当前代码应注入 Spring 管理的 `applicationIoExecutor`；具有独立容量模型的任务使用模块自有执行器，锁、限流和熔断由业务模块按领域语义实现。
+
+## 当前迁移映射
+
+| 旧能力 | 当前做法 |
+| --- | --- |
+| 通用 I/O 线程池 | 构造器注入 `@Qualifier("applicationIoExecutor") Executor` |
+| 模块专用线程池 | 在模块配置中声明命名执行器，例如 `hotTopicExecutor` |
+| 超时和降级 | 调用服务内使用 `CompletableFuture` 明确声明时间预算和降级值 |
+| 锁、限流、熔断 | 由所属业务服务直接实现或使用对应基础库 |
+| Redis 值与计数器 | 使用 `RedisValueStore`；集合和锁直接使用 Redisson |
+
+以下章节均描述 v2.4.1 之前的旧实现，不应在新代码中引用。
 
 ## 目录
 
-- [ThreadPoolUtils - 线程池工具类](#threadpoolutils---线程池工具类)
-- [ConcurrentUtils - 并发控制工具类](#concurrentutils---并发控制工具类)
+- [ThreadPoolUtils - 旧版线程池工具类](#threadpoolutils---旧版线程池工具类)
+- [ConcurrentUtils - 旧版并发控制工具类](#concurrentutils---旧版并发控制工具类)
 
 ---
 
-## ThreadPoolUtils - 线程池工具类
+## ThreadPoolUtils - 旧版线程池工具类
 
 **包路径**: `com.xiaou.common.utils.ThreadPoolUtils`
 
@@ -250,7 +262,7 @@ ThreadPoolExecutor executor = ThreadPoolUtils.PoolConfig.builder()
 
 ---
 
-## ConcurrentUtils - 并发控制工具类
+## ConcurrentUtils - 旧版并发控制工具类
 
 **包路径**: `com.xiaou.common.utils.ConcurrentUtils`
 

CHANGELOG.md

@@ -6,6 +6,32 @@
 
 ## [Unreleased]
 
+## [v2.4.1] - 2026-07-15
+
+### Added
+
+- 新增独立的 `code-nest-design-system` 包，由用户端和管理端共享组件、主题、设计令牌与组合式函数。
+- 新增可注入的 `RedisValueStore` 和 Spring 托管的有界 `applicationIoExecutor`。
+- 新增学习驾驶舱、WebSocket 票据、Redis 值存储和朋友圈核心服务的聚焦回归测试。
+- 重构 VitePress 文档中心，新增分类首页、响应式工程手册主题、动态同步基线和导航完整性审计。
+
+### Changed
+
+- 学习驾驶舱、社区热点与摘要、朋友圈、摸鱼工具、抽奖和验证码等热点链路减少重复查询、缓存往返与无边界并发。
+- 缓存、锁、限流和执行器改为依赖注入或模块自有实现，明确基础设施与领域语义边界。
+- 129 个 Markdown 页面重组为开始、架构、模块、API、运维和资料六个一级入口。
+- 后端 Maven、共享设计系统、管理端前端、用户端前端、文档站和部署示例统一升级到 `v2.4.1`。
+
+### Removed
+
+- 删除双前端内重复的设计系统源码，统一从 `code-nest-design-system` 引用。
+- 删除静态 `RedisUtil`、`ThreadPoolUtils` 和 `ConcurrentUtils`，避免全局状态与无边界资源管理。
+
+### Migration
+
+- 本版本不新增数据库迁移、环境变量或对外 API 兼容性要求。
+- 前端依赖仍通过仓库内 `file:../code-nest-design-system` 安装，无需发布外部 npm 包。
+
 ## [v2.4.0] - 2026-07-14
 
 ### Added

README.md

@@ -1,6 +1,6 @@
 # Code Nest
 
-![Version](https://img.shields.io/badge/version-v2.4.0-blue.svg)
+![Version](https://img.shields.io/badge/version-v2.4.1-blue.svg)
 ![Java](https://img.shields.io/badge/java-17-orange.svg)
 ![Spring Boot](https://img.shields.io/badge/spring%20boot-3.4.4-brightgreen.svg)
 ![Vue](https://img.shields.io/badge/vue-3.x-4fc08d.svg)
@@ -16,6 +16,20 @@ Code Nest 是一个面向开发者的成长型社区与知识运营平台，采
 - **vue3-user-front**：面向开发者的用户端，提供刷题、简历制作、动态广场、博客阅读、代码分享、学习资产沉淀、通知消息等场景。
 - **xiaou-application**：多模块聚合的 Spring Boot API，整合 `xiaou-*` 业务模块，对外暴露统一的 `/api` 网关、鉴权、日志与监控。
 
+## v2.4.1 Architecture And Documentation Hardening
+
+`v2.4.1` 聚焦共享基础设施、热点链路和工程文档治理，在不改变对外 API 与数据库结构的前提下减少重复实现，并补强可验证性。
+
+### 本次版本完成
+
+- **共享设计系统**：抽取独立的 `code-nest-design-system`，用户端和管理端复用同一套组件、主题、设计令牌与组合式函数。
+- **缓存边界收敛**：新增可注入的 `RedisValueStore`，移除静态 `RedisUtil`，集合、锁和业务语义继续由模块直接使用 Redisson 表达。
+- **线程池治理**：通用 I/O 任务使用 Spring 托管的有界 `applicationIoExecutor`，独立负载保留模块专用执行器，删除静态线程池与通用并发工具。
+- **热点链路优化**：学习驾驶舱、社区热点与摘要、朋友圈、摸鱼工具、抽奖和验证码等链路减少重复查询、缓存往返与无边界并发。
+- **聚焦回归测试**：补充学习驾驶舱、WebSocket 票据、Redis 值存储和朋友圈核心服务测试。
+- **文档中心重构**：129 个 Markdown 页面按开始、架构、模块、API、运维和资料重新组织，并新增响应式主题、动态同步基线与导航审计。
+- **版本基线统一**：Maven、共享设计系统、双前端、文档站、Jar 命令与 Docker 示例统一升级到 `v2.4.1`。
+
 ## v2.4.0 Unified Backend Agent Runtime
 
 `v2.4.0` 将管理员自然语言操作收口为后端统一 Agent 运行时。管理端只调用 `POST /admin/agent/chat`，后端负责 LLM 规划、工具注册、权限与策略、预览、强确认、执行和审计。
@@ -359,7 +373,7 @@ mvn clean package -DskipTests
 mvn -pl xiaou-application -am spring-boot:run
 
 # 或直接运行打包后的 jar
-java -jar xiaou-application/target/xiaou-application-v2.4.0.jar --spring.profiles.active=prod
+java -jar xiaou-application/target/xiaou-application-v2.4.1.jar --spring.profiles.active=prod
 ```
 
 - API 根地址：`http://localhost:9999/api`
@@ -527,15 +541,15 @@ management:
 
 ```bash
 # 构建镜像
-docker build -t code-nest:v2.4.0 -f docker/Dockerfile .
+docker build -t code-nest:v2.4.1 -f docker/Dockerfile .
 
 # 运行容器
 docker run -d \
   --name code-nest \
   -p 9999:9999 \
   -e SPRING_PROFILES_ACTIVE=prod \
   --env-file docker/env/example.env \
-  code-nest:v2.4.0
+  code-nest:v2.4.1
 ```
 
 如果要把 MySQL / Redis / Java 主服务 / `llamaindex-service` 一起编排起来，推荐使用：
@@ -605,6 +619,15 @@ server {
 
 仅列出最近版本，更多历史可查看 `git log`。
 
+### v2.4.1 Architecture And Documentation Hardening
+
+- **共享前端基础**：双前端改为复用独立设计系统包，避免组件与主题继续双份漂移。
+- **缓存与并发治理**：使用可注入缓存边界和 Spring 托管执行器替代静态全局工具。
+- **热点链路优化**：学习、社区、朋友圈、摸鱼、抽奖和验证码链路减少重复查询与缓存往返。
+- **测试补强**：为学习驾驶舱、WebSocket 票据、Redis 值存储和朋友圈服务新增回归覆盖。
+- **文档工程化**：129 个页面完成分类重组，VitePress 增加响应式主题、动态基线和自动审计。
+- **版本基线升级**：Maven、共享设计系统、双前端、文档站、Jar 与 Docker 示例统一升级到 `v2.4.1`。
+
 ### v2.4.0 Unified Backend Agent Runtime
 
 - **统一后端编排**：单一聊天接口完成 LLM 规划、工具注册、策略、执行和审计，前端保持薄边界。

RELEASE.md

@@ -1,5 +1,34 @@
 # 发布流程
 
+## v2.4.1
+
+`v2.4.1` 是架构与文档治理补丁版本，重点收敛共享前端基础设施、缓存与线程池边界，优化热点业务链路，并把现行 Markdown 与 VitePress 文档纳入可持续审计。
+
+### Highlights
+
+- 双前端统一复用 `code-nest-design-system`，移除长期漂移的重复组件、主题和设计令牌。
+- 使用 `RedisValueStore`、Spring 托管执行器和模块专用 Redisson 能力替代静态缓存与并发工具。
+- 学习驾驶舱、社区热点与摘要、朋友圈、摸鱼工具、抽奖和验证码等热点链路减少重复查询与缓存往返。
+- 为学习驾驶舱、WebSocket 票据、Redis 值存储和朋友圈核心服务补充聚焦回归测试。
+- 129 个 VitePress 页面完成分类重组，新增响应式主题、暗色模式、动态同步基线和导航完整性审计。
+
+### Migration
+
+- 本版本不新增数据库脚本，不改变对外 API，也不新增生产环境变量。
+- 双前端通过仓库内 `file:../code-nest-design-system` 解析共享包，部署流程继续执行各前端的 `npm ci` 与生产构建即可。
+
+### Verification
+
+- 本地 `scripts/code-nest-eval.ps1 -Tier release` 已通过：生成 `xiaou-application-v2.4.1.jar`，双前端与文档站构建成功，发布脚本语法检查通过。
+- 本地 `scripts/code-nest-eval.ps1 -Tier hygiene` 已通过：空白、密钥占位符和文本 NUL 字节检查无阻断项。
+- GitHub PR 必须通过后端测试与打包、双前端契约测试与构建、文档构建、RAG 测试和仓库卫生检查。
+- VitePress 已覆盖桌面、390px 移动端、暗色模式、搜索、长表格和键盘焦点浏览器验收。
+
+### Risks And Rollback
+
+- 主要风险是共享设计系统本地包解析、缓存 key 行为和异步执行时序；发布门禁覆盖双前端构建及相关后端测试。
+- 本版本无数据库回滚动作；如需回退，使用既有发布备份恢复 `v2.4.0` 后端 Jar 和双前端静态资源。
+
 ## v2.4.0
 
 `v2.4.0` 发布管理员端统一后端 Agent 运行时。本版本的范围是单一聊天入口和当前 26 个已注册生产工具，不表示尚未注册的所有业务接口都已支持自然语言操作。