# news

**Repository Path**: whqet123/news

## Basic Information

- **Project Name**: news
- **Description**: vibe coding。
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 43
- **Created**: 2026-03-06
- **Last Updated**: 2026-10-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# NewsHub 新闻管理系统

Vue 3 + Spring Boot 全栈新闻内容平台，同时可作为前后端分离教学项目。覆盖 **内容消费 → 内容生产 → 内容治理** 完整闭环，附加分发与数据回流。

| 项 | 说明 |
|---|---|
| 当前版本 | **v2.6.0**（2026-10-13，准生产优化版） |
| 后端端口 | `http://localhost:8081` |
| 前端地址 | `http://localhost:3000`（Vite 开发服务器，端口定义于 `frontend/vite.config.js`） |
| 数据库 | MySQL 8 · 库名 `news_management` · utf8mb4 · utf8mb4_unicode_ci |
| 缓存 | Redis **可选**（未安装时设 `CACHE_MEMORY_ONLY=true` 走纯内存） |
| 文档 | 见 [§9 文档索引](#9-文档索引) |

> **端口口径**：`3000` 是唯一权威值（代码事实）。`playwright.config.js` 中的 `baseURL` 仍写着 `5173`，属已知缺陷，见 [§12 已知问题](#12-当前状态与已知遗留)。

---

## 1. 技术栈

### 1.1 后端

| 组件 | 版本/选型 | 说明 |
|---|---|---|
| Java | 17 | `backend/pom.xml` |
| Spring Boot | **3.2.0** | Web / Validation / AOP / Mail / Data Redis |
| MyBatis-Plus | 3.5.5（`mybatis-plus-spring-boot3-starter`） | ORM，分页插件 |
| MySQL Connector | `mysql-connector-j`（BOM 管理） | JDBC |
| Flyway | Community 9.22.3（BOM 管理） | 迁移基线 `baseline-version: 3`，执行 V4 及以后 |
| Redis | spring-data-redis + Lettuce | Cache-aside，失败自动降级内存 |
| JWT | jjwt **0.12.3**（api / impl / jackson） | 自制过滤器 + 角色拦截器（**非** Spring Security） |
| OpenAPI | springdoc **2.3.0** | `/swagger-ui.html` |
| 其他 | EasyExcel 3.3.2、Jsoup 1.17.2、Thumbnailator 0.4.20、Lombok 1.18.30、spring-websocket 6.1.6、spring-security-crypto | Excel 导入、富文本净化、图片处理、密码 BCrypt |

### 1.2 前端

| 组件 | 声明版本 | 说明 |
|---|---|---|
| Vue 3 | `^3.4.0`（锁定 3.5.29） | Composition API，**全部路由组件懒加载** |
| Vite 5 | `^5.0.0`（锁定 5.4.21） | dev 端口 3000，代理 `/api` 与 `/ws` |
| vue-router 4 | `^4.2.0`（锁定 4.6.4） | history 模式 |
| Element Plus | `^2.13.6` | **按需引入**（message / message-box / icon / empty） |
| WangEditor 5 | `^5.1.23` | 富文本 |
| ECharts 5 | `^5.6.0` + `echarts-wordcloud ^2.1.0` | 数据大屏、标签词云（按需动态 import，不进首屏） |
| DOMPurify | `^3.3.2` | 富文本净化（前端侧） |
| xlsx / html2pdf.js | `^0.18.5` / `^0.14.0` | 报表导出 |
| @iconify/vue | `^5.0.0` | 图标 |
| 状态管理 | 自制 `reactive` 单例 | `store/user.js`、`store/theme.js`、`store/aiNews.js`，**无 Pinia / Vuex** |

### 1.3 测试与质量工具

| 工具 | 版本 | 用途 |
|---|---|---|
| JUnit 5 / Mockito | Boot BOM | 后端单测与集成测试（surefire 3.0.0） |
| SpotBugs | `4.8.3.0`（effort=Max，threshold=High，failOnError=true） | 后端静态分析 |
| Vitest | `^1.0.0`（锁定 1.6.1） | 前端单测（jsdom） |
| Playwright | `^1.64.0`（锁定 1.64.0） | E2E（仅 chromium） |
| ESLint / Prettier | 8.57.0 / 3.3.3 | 前端 lint 与格式化 |

---

## 2. 环境要求

- JDK 17+（**注意：`start-all.sh` 的提示文案写的是 JDK 21，与实际不符，以本文为准**）
- Maven 3.8+
- Node.js 18+（推荐 20+）与 npm
- MySQL 8.x（**下限 ≥ 5.7.6**，全文索引依赖 ngram 解析器）
- Redis 6+（**可选**，见 [§6 缓存与可选依赖](#6-缓存与可选依赖)）

---

## 3. 快速开始

### 3.1 一键启动

**Windows**（项目根目录双击或执行）：

```bat
start-all.bat
```

**Linux / macOS**：

```bash
./start-all.sh          # 启动前后端
./start-all.sh status   # 查看运行状态
./start-all.sh logs     # 跟踪日志（Ctrl+C 退出）
./start-all.sh stop     # 停止服务
./start-all.sh restart  # 重启
```

两者差异：

| | `start-all.bat` | `start-all.sh` |
|---|---|---|
| 进程管理 | 新开 cmd 窗口，需手动关闭 | `nohup` 后台运行，`stop` 统一停止 |
| 依赖预检 | 无 | 检查 java / mvn / node / npm |
| 端口检测 | 无 | 启动前检测 3000 / 8081 占用 |
| 就绪等待 | 固定 5 秒 | 轮询等待后端 8081 真正监听（最多 60s） |
| 日志 | 各窗口内可见 | `.logs/backend.log`、`.logs/frontend.log` |

### 3.2 分步启动

**① 数据库**

```bash
# 创建库（字符集 utf8mb4）
mysql -uroot -p -e "CREATE DATABASE IF NOT EXISTS news_management DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# 导入基线 DDL（含 6 张基线表与种子数据）
mysql -uroot -p news_management < docs/4.init_database_final.sql
```

> `docs/4.init_database_final.sql` 是**唯一**的 SQL 初始化脚本，含 `CREATE DATABASE` + `USE` + 6 张基线表（`user` / `category` / `news` / `comment` / `news_like` / `operation_log`）+ 种子数据 + 8 条验证 SELECT。
> 其余 **18 张表**由 Flyway 迁移创建，在后端启动时自动执行。

**② 后端环境变量**

复制并编辑 `backend/.env`（已被 `.gitignore` 忽略，**不会提交**）：

```bash
cp backend/.env.example backend/.env
```

必填项（**缺失将导致启动失败或功能不可用**）：

| 变量 | 缺失后果 |
|---|---|
| `DB_PASSWORD` | Hikari `initialization-fail-timeout: 1` → **启动直接失败**（`Access denied for user 'root'@'localhost'`） |
| `JWT_SECRET` | 长度 < 32 字符时 `JwtUtil` 抛 `IllegalStateException` → 所有鉴权接口 fail-closed |
| `AI_API_KEY` | `AiConfig.isConfigured()` 为 false → `/api/ai/*` 全部返回 **503** |

**③ 启动后端**

```bash
cd backend
mvn spring-boot:run
```

**④ 启动前端**

```bash
cd frontend
npm install
npm run dev
```

浏览器打开 `http://localhost:3000`。

---

## 4. 环境变量完整清单

代码读取的全部环境变量（`backend/src/main/resources/application.yml` 与配置类）：

### 4.1 必填

| 变量 | 默认值 | 说明 |
|---|---|---|
| `DB_PASSWORD` | 空 | MySQL 密码，fail-fast |
| `JWT_SECRET` | 空 | ≥32 字符，fail-closed |
| `AI_API_KEY` | 空 | 智谱 API Key，缺失则 AI 功能 503 |

### 4.2 数据库 / 服务器 / 缓存

| 变量 | 默认值 | 说明 |
|---|---|---|
| `DB_HOST` | `localhost` | |
| `DB_PORT` | `3306` | |
| `DB_NAME` | `news_management` | |
| `DB_USERNAME` | `root` | |
| `SERVER_PORT` | `8081` | |
| `REDIS_HOST` / `REDIS_PORT` / `REDIS_PASSWORD` | `localhost` / `6379` / 空 | |
| `CACHE_MEMORY_ONLY` | `false` | `true` = 完全跳过 Redis，纯内存缓存 |
| `UPLOAD_PATH` | `uploads/` | 上传目录 |
| `CORS_ALLOWED_ORIGINS` | 空 | 逗号分隔白名单；**空 = 不放行任何跨域** |
| `SITE_BASE_URL` | `http://localhost:8081` | RSS 链接与邮件验证链接前缀 |

### 4.3 AI

| 变量 | 默认值 |
|---|---|
| `AI_API_URL` | `https://open.bigmodel.cn/api/paas/v4/chat/completions` |
| `AI_MODEL` | `glm-4.7-flash` |
| `AI_TEMPERATURE` | `0.7` |
| `AI_MAX_TOKENS` | `4000` |

### 4.4 邮件（可选，不配置则降级为仅 log 链接）

`SPRING_MAIL_HOST`（空）/ `SPRING_MAIL_PORT`（587）/ `SPRING_MAIL_USERNAME`（空）/ `SPRING_MAIL_PASSWORD`（空）/ `SPRING_MAIL_FROM`（空）/ `SPRING_MAIL_AUTH`（true）/ `SPRING_MAIL_STARTTLS`（false）

---

## 5. 功能概览

**当前规模**：23 个 Controller · **141 个端点** · 24 张表 · 21 个 Flyway 迁移（V1.1 ~ V18） · 18 个前端页面 · 46 个组件 · 40 条路由。

### 5.1 前台（游客 / 读者 / 作者）

| 能力 | 路由 / 接口要点 |
|---|---|
| 首页、分类版面、热榜 | `/`、`/category/:id`（2026-10：分类点击跳转独立版面页），`GET /api/news/page`（带 categoryId）、`/api/news/hot` |
| 新闻详情 | `/news/:id`，相关推荐 `GET /api/news/{id}/related` |
| 全文搜索 | `/search`，`GET /api/news/search`（MySQL ngram FULLTEXT）；搜索增强 `GET /api/search/hot`、`/api/search/suggest` |
| 标签云 / 标签聚合 | `/tags`、`/tag/:id` |
| 专题合集 | `/topics`、`/topic/:slug` |
| 作者主页 | `/author/:id` |
| RSS 订阅源 | `GET /api/rss`、`GET /api/rss/category/{id}` |
| 邮件订阅 | `/subscribe`，`POST /api/subscribe` + 验证 / 退订 |
| 喜欢 / 收藏 / 阅读历史 | `GET /api/like/...`、`/api/favorite/...`、`/api/view/...` |
| 关注 / 通知 | `/api/follow/...`、`/api/notification/...`（WebSocket `/ws/notify`） |
| 评论、点赞评论、表情回应 | `/api/comment/...`，支持置顶 / 精华 / 关闭 / `/{id}/emoji` |
| 内容纠错 | `POST /api/correction` |
| 投稿与审核 | 作者投稿 → 状态 `2`（待审核）；管理员审核 / 驳回（带 `reject_reason`） |
| 修订与恢复 | `GET/POST /api/news/{id}/revisions...` |
| 静态页 | `/about`、`/contact`、`/privacy` |

**新闻状态机**：`0` 草稿 · `1` 已发布 · `2` 待审核 · `3` 已下架。

### 5.2 后台（`/admin`）

| 模块 | 路由 | 说明 |
|---|---|---|
| 审核队列 | `/admin/audit-queue` | 待审内容、驳回理由 |
| 新闻管理 | `/admin/news` | 发布 / 下架 / 精选 / 置顶 |
| 用户管理 | `/admin/users` | 列表 / 审核 / 角色 / 密码重置 / 批量导入（Excel） |
| 分类 / 标签 | `/admin/categories`、`/admin/tags` | CRUD、排序、词云、打标 |
| 评论管理 | `/admin/comments` | 置顶 / 精华 / 关闭 / 批量删除 |
| 举报 / 敏感词 | `/admin/report-management`、`/admin/sensitive-words` | 治理闭环：审核 → 处理举报 → 词库扫描 |
| 纠错管理 | `/admin/corrections` | 读者纠错处理 |
| 专题管理 | `/admin/topics` | 专题合集编排 |
| 数据看板 | `/admin/dashboard` | ECharts 大屏，**服务端单次聚合** |
| 报表中心 | `/admin/reports` | 服务端导出 CSV / XLS |
| 操作日志 | `/admin/logs` | AOP 审计，分页 / 筛选 / 清理 |
| AI 辅助创作 | `/admin/ai-news` | 摘要、润色、标题优化、大纲、关键词、参考文档 |

个人中心（任意登录用户）：`/admin/profile`、`/admin/my-news`、`/admin/my-comments`、`/admin/my-likes`、`/admin/my-favorites`、`/admin/my-history`、`/admin/my-follows`、`/admin/notifications`。

### 5.3 设计系统与体验

- **双皮肤 × 双明暗**：`data-skin`（`editorial` 报刊风 / `tech` 科技风）× `data-theme`（`light` / `dark`），全站 `ThemeToggle` 切换，登录后与服务端偏好同步
- **防 FOUC**：`frontend/index.html` 内联脚本在首屏渲染前写入 `data-skin` / `data-theme`
- **壳层**：`SiteHeader` / `SecondaryMasthead` / `SiteFooter` / `BrandLogo`；后台 `ConsolePageHeader`
- **三态组件**：`StateBox`（loading / empty / error）
- **无障碍**：`a11y.css` 全局焦点环、skip-link、`prefers-reduced-motion`、`sr-only`、`tabular-nums`
- 契约详见 `frontend/DESIGN.md` 与根目录 `PRODUCT.md`

### 5.4 安全要点

- 密码：BCrypt；登录失败 5 次锁定 30 分钟
- JWT：默认密钥已移除，`JWT_SECRET` 强制注入且 ≥32 字符；有效期 2h，`POST /api/user/refresh` 静默续期（7 天窗口）
- 鉴权：**自制 `JwtAuthenticationFilter` + `RoleAuthorizationInterceptor`**（非 Spring Security）
  - 白名单（任意方法）：`/api/user/login`、`/register`、`/refresh`、`/uploads/`、`/error`、`/api/subscribe`、`/api/track`
  - 匿名只读白名单（仅 GET）：`/api/news/`、`/api/category/`、`/api/tag/`、`/api/comment/listByNews/`、`/api/search/`、`/api/rss`、`/api/topic/`、`/api/subscribe/`
- 写接口标注 `@RequireRole`，方法注解优先于类注解；越权返回 **403**
- CORS：白名单由 `CORS_ALLOWED_ORIGINS` 控制，空值不放行任何跨域
- 富文本净化：后端 Jsoup `Safelist` + 前端 DOMPurify
- 上传防护：扩展名白名单（jpg/jpeg/png/gif/webp）+ 魔数校验 + 业务上限 5MB + 路径穿越校验
- AI 限流：`/api/ai/*` 非 GET 请求 **10 次 / 分钟**，超限 **429**
- 操作日志：`@OperationLogAnnotation` + AOP 横切，操作人取 JWT 解析所得 `userId`

---

## 6. 缓存与可选依赖

| 场景 | 做法 |
|---|---|
| 已安装 Redis（默认 `localhost:6379`） | 正常使用 Cache-aside |
| **未安装 Redis** | 设置 `CACHE_MEMORY_ONLY=true`，完全跳过连接探测 |
| Redis 不稳定 | `RedisCache` 连接 / 命令超时 **2s**，失败后熔断 **60s**，期间走 `ConcurrentHashMap` 内存缓存 |

缓存 TTL：新闻详情 1800s · 新闻分页 600s · 热榜 300s · 分类列表 3600s · 数据看板 60s · 通用默认 1800s。

```bash
# Windows PowerShell（当前会话）
$env:CACHE_MEMORY_ONLY="true"
cd backend
mvn spring-boot:run
```

或写入 `backend/.env`：`CACHE_MEMORY_ONLY=true`。

---

## 7. 数据库与 Flyway

- 基线：`spring.flyway.baseline-version: 3`，`baseline-on-migrate: true`，`validate-on-migrate: true`
- 迁移目录：`backend/src/main/resources/db/migration/`，共 **21 个脚本（V1.1 ~ V18）**

| 版本 | 内容 |
|---|---|
| V1.1 / V1.2 / V1.3 | 分类排序、点赞表、浏览表 |
| V2 / V3 | 用户头像、敏感词表 |
| V4 / V4.1 | 索引与 `content` 列调整、敏感词表兜底 |
| V5 | 收藏 / 通知 / 全文索引（ngram） |
| V6 | 关注 / 举报 / 评论点赞 |
| V7 / V8 / V9 | 新闻作者维度、新闻修订、发布时间字段 |
| V10 | 用户主题偏好（`skin` / `theme`） |
| V11 | 新闻驳回理由（`reject_reason`） |
| V12 | 搜索关键词日志（`search_log`） |
| V13 / V17 | 邮件订阅（`subscription`）与令牌有效期 |
| V14 | 专题合集（`topic` + `topic_news`） |
| V15 | 内容纠错（`correction`） |
| V16 | 评论表情（`comment_emoji`） |
| V18 | 事件埋点（`user_event`，刻意不含 `user_id` 列） |

> V4 及以后的脚本普遍使用**存储过程包裹 + `information_schema` 判断**实现幂等；V1.1 / V1.2 / V1.3 / V2 / V10 为裸 `ALTER TABLE`，依赖 `baseline-version: 3` 才会被跳过。

表结构设计见 [docs/2.数据库设计.md](docs/2.数据库设计.md)（24 张表逐字段）；基线 DDL 见 [docs/4.init_database_final.sql](docs/4.init_database_final.sql)。

---

## 8. 目录结构

```
news/
├── backend/                          # Spring Boot 后端
│   ├── src/main/java/com/news/
│   │   ├── annotation/  aspect/      # @RequireRole、@OperationLogAnnotation、审计切面
│   │   ├── common/  config/           # ResponseResult、PageResult、RedisCache、CORS、JWT、WS
│   │   ├── controller/                # 23 个 Controller，141 个端点
│   │   ├── converter/  dto/  entity/  mapper/  vo/
│   │   ├── exception/                 # BusinessException、GlobalExceptionHandler
│   │   ├── service/  service/impl/
│   │   ├── task/                      # 定时发布扫描、埋点 30 天清理
│   │   └── util/                      # JwtUtil、HtmlSanitizer、UploadValidator
│   ├── src/main/resources/
│   │   ├── application.yml
│   │   └── db/migration/              # Flyway V1.1 ~ V18（21 个脚本）
│   ├── src/test/java/com/news/        # 47 个测试类
│   ├── .env / .env.example            # 本地密钥（.env 不入库）
│   └── pom.xml
├── frontend/                         # Vue 3 + Vite
│   ├── src/
│   │   ├── api/                       # axios 封装（401 静默续期）+ 21 个业务模块
│   │   ├── components/common/         # 22 个通用组件
│   │   ├── components/admin/          # 24 个后台组件
│   │   ├── composables/               # useTrendChart / useMessage / useDialogA11y 等 5 个
│   │   ├── router/  store/  utils/
│   │   ├── styles/                    # variables / theme / a11y / components / common / auth / utilities
│   │   └── views/                     # 17 个页面
│   ├── e2e/                           # Playwright E2E（3 个 spec / 9 个用例）
│   ├── DESIGN.md                      # 设计系统契约
│   ├── vite.config.js                 # dev 端口 3000，代理 /api /ws
│   └── package.json
├── docs/                              # 需求 / 接口 / 数据库 / 测试 / 部署 + superpowers 归档
├── designs/                           # 高保真原型与 UI 规范 v3 / v4 / v5（已被 .gitignore 忽略）
├── PRODUCT.md                         # 产品战略：品牌性格、设计原则、有意例外
├── .github/workflows/ci.yml           # CI 流水线（3 个 job）
├── docker-compose.yml                 # Docker 一键编排（mysql + backend + frontend）
├── .env.example                       # Docker 环境变量模板
├── start-all.bat / start-all.sh       # 一键启动
└── README.md
```

---

## 9. 常用命令

```bash
# ── Docker 一键部署 ──
cp .env.example .env          # 编辑 DB_PASSWORD / JWT_SECRET
docker-compose up --build     # 构建 + 启动 mysql + backend + frontend
docker-compose down           # 停止
docker-compose logs -f backend

# ── 后端 ──
cd backend
mvn spring-boot:run
mvn test                      # 运行测试（集成测试需 MySQL）
mvn spotbugs:check            # 静态分析
mvn -DskipTests package       # 产出 target/news-management-2.6.0.jar

# ── 前端 ──
cd frontend
npm install
npm run dev                   # 开发服务器（端口 3000）
npm run build                 # 生产构建
npm run test:run              # Vitest 单元测试（52 个）
npm run test:e2e              # Playwright E2E（9 个，需前后端运行）
npm run lint / lint:fix
npm run format

# 构建冒烟（不污染 dist/）
npx vite build --outDir dist-check
```

---

## 10. 文档索引

> 以下为 `docs/` 下**实际存在**的全部文档。

| 文档 | 说明 |
|---|---|
| [docs/1.需求分析.md](docs/1.需求分析.md) | 用户画像、FR / NFR、数据模型概览、已知边界与路线图，v2.6.0 |
| [docs/2.数据库设计.md](docs/2.数据库设计.md) | 24 张表逐字段、索引、状态枚举、关系模型、种子数据，v3.0 |
| [docs/3.接口文档.md](docs/3.接口文档.md) | 23 个 Controller / 141 个端点，鉴权、权限总表、错误码，v2.6.0 |
| [docs/4.init_database_final.sql](docs/4.init_database_final.sql) | 基线 DDL（6 张表 + 种子数据 + 验证查询） |
| [docs/5.测试计划.md](docs/5.测试计划.md) | 测试范围、策略、资源、进度、缺陷管理 |
| [docs/6.测试用例.md](docs/6.测试用例.md) | 100 条用例 + 自动化测试基线 |
| [docs/7.部署文档.md](docs/7.部署文档.md) | Docker / 手动部署、环境变量、健康检查、CI、故障排查 |
| `docs/superpowers/specs/2026-10-11-admin-data-and-stats-design.md` | v2.6.0 管理端统计聚合设计规格（归档） |
| `docs/superpowers/plans/2026-10-11-admin-data-stats-impl.md` | v2.6.0 实施计划（归档，含完成状态标注） |
| [PRODUCT.md](PRODUCT.md) | 产品战略层：定位、品牌性格、设计原则、有意例外 |
| `frontend/DESIGN.md` | 前端设计系统契约与新页面检查清单 |

---

## 11. 默认种子账号

来自 `docs/4.init_database_final.sql`（三个账号的 BCrypt 口令**逐字相同**，均为 `123456` 的哈希）：

| 用户名 | 角色 | 说明 |
|---|---|---|
| `admin` | 管理员 | 后台入口 `/admin` |
| `editor` | 管理员 | |
| `reader` | 普通用户 | |

> 仅用于本地教学演示。生产环境务必修改全部默认口令，并注入 `JWT_SECRET`、`AI_API_KEY`。

---

## 12. 当前状态与已知遗留

### 12.1 测试现状（2026-10-13 核验）

| 层次 | 数量 | 证据 |
|---|---|---|
| 后端 surefire | **278 通过 / 0 失败**（41 个测试类，2026-10-13 00:39） | `backend/target/surefire-reports/` |
| 后端源码 `@Test` 注解 | 279（47 个测试类） | 其中 1 个工具类 `GenerateBCryptPassword` 文件名不匹配 `*Test`，未被 surefire 收录 |
| ├ Controller 集成测试 | 53 | `controller/` 目录 |
| └ 安全回归测试 | 22（5 个文件） | `test/security/` |
| 前端单元测试 | **52 通过**（8 个文件） | `npm run test:run` |
| E2E | **9 个**（3 个 spec，仅 chromium） | `npm run test:e2e`，需前后端运行 |

> 根目录 `test-output.txt` / `test-output-utf8.txt` 记录的是 **2026-10-12 的 214 例**，早于上表的 278 例，属**过期日志**。
> 前端测试仅覆盖 API 层与 6 个通用组件，相对 17 个页面 / 46 个组件**覆盖率仍很低**。

### 12.2 代码缺陷清单（本轮仅记录，未修改代码）

| # | 位置 | 问题 | 影响 |
|---|---|---|---|
| 1 | `frontend/playwright.config.js:27` | `baseURL` 为 `http://localhost:5173`，实际 dev 端口是 **3000** | E2E 连不上开发服务器 |
| 2 | `frontend/playwright.config.js:11` | 注释同样写 5173 | 同上 |
| 3 | `.github/workflows/ci.yml` | 触发分支为 `main` / `dev`，实际分支是 **`master`** | 推送到 master 不触发 CI |
| 4 | `.github/workflows/ci.yml` `backend-test` | 无 `services:` 段，**未提供 MySQL**，而大量测试是 `@SpringBootTest` 集成测试 | CI 上集成测试会连接失败 |
| 5 | `backend/.env` | 缺 `DB_PASSWORD` 与 `AI_API_KEY` | 后端无法启动 / AI 全部 503 |
| 6 | `backend/target/` | 残留 `news-management-1.0.0.jar`，与 `pom.xml` 的 `2.6.0` 不符 | 易误用陈旧产物，建议 `mvn clean` |
| 7 | `application.yml:135-146` | `security.password.*` 5 个配置项**无任何 `@Value` 消费者** | 死配置，密码策略实际未生效 |
| 8 | `config/WebSocketConfig.java:40` | `setAllowedOrigins("*")`，与 `WebConfig` 的 CORS 白名单策略冲突 | WebSocket 无来源校验 |
| 9 | `config/RedisConfig.java` vs `common/RedisCache.java:35` | 声明 `RedisTemplate<String,Object>`，注入 `RedisTemplate<String,String>` | 泛型擦除未报错但语义隐患 |
| 10 | `config/AiConfig.java:35,49` | 代码内默认 `glm-4` / `2000`，`application.yml` 默认 `glm-4.7-flash` / `4000` | 双套默认值，易误判 |
| 11 | `start-all.sh:125` | 依赖预检提示「请安装 **JDK 21**」，项目实为 **JDK 17** | 误导性提示 |
| 12 | `backend/.env.example:18` | `CORS_ALLOWED_ORIGINS` 示例值（3000/3001）与同文件注释（5173）自相矛盾 | 已按本文统一为 3000 |
| 13 | `docs/superpowers/plans/...impl.md` | G3 组（运行时指标）5 个文件未落地：后端无 `/api/admin/metrics/runtime` 端点；前端 `api/stats.js:11` 虽定义了 `statsApi.runtime()`，但**全项目无调用点**（`Dashboard.vue` 只调 `statsApi.dashboard()`） | 缓存命中率 / 在线人数无法获取；无死代码风险 |
| 14 | `frontend/src/views/TopicDetail.vue`、`components/admin/Profile.vue`、`components/common/TagCloud.vue`、`composables/useAutoGrowTextarea.js` | **4 个孤儿文件，全项目零 import**：分别被 `TopicPage.vue` / `UserProfile.vue` / `WordCloud.vue`（注意是 WordCloud，非 TagCloud）取代；`NewsDetail.vue` 自带 `AUTO_GROW_MIN/MAX` 实现 | 冗余，易误改；且 `router/index.js:68` 的路由 `name` 仍叫 `TopicDetail` 却指向 `TopicPage.vue`，更易混淆 |
| 15 | 根目录 `test-output*.txt`（380 KB） | 构建日志已被 git 追踪，而 `.gitignore` 只忽略 `/backend/test-output.txt` | 仓库体积膨胀 |
| 16 | `.editorconfig` (`end_of_line = lf`) vs `.gitattributes` (`*.bat eol=crlf`) | 同一文件两套换行约定 | EditorConfig 冲突（Git 属性优先） |
| 17 | 无障碍：36px 触控规范 | `a11y.css` **无全局尺寸下限**；`.btn-xs`、`.op-btn` 为 28px，多处 32 / 34px 交互元素 | 未完全达到 WCAG 2.5.5 |
| 18 | `backend/src/main/resources/db/migration/` | `tag` / `news_tag` 两表**无任何 CREATE TABLE**，依赖基线库已存在 | 全新空库缺这两表 |

---

## 13. 许可与用途

教学与内部开发用途。v2.6.0 已完成安全加固（越权防护、XSS 净化、路径穿越防护、JWT 密钥强制注入），可用于准生产部署。生产环境请务必修改默认口令并注入 `JWT_SECRET`、`AI_API_KEY`。