目录测试h2-h5

第一章：概述

本文档用于测试 Markdown 渲染器对 2 至 5 级标题 的目录生成与跳转支持情况。文档结构覆盖了从 H2 到 H5 的完整层级，并在每个层级下提供了真实正文内容，而非空白占位。

良好的文档层级设计能显著提升长文档的可读性，建议在实际项目中将标题深度控制在 3 级以内，超过 4 级往往意味着需要拆分文档。

第二章：系统架构

在开始详细功能说明之前，本章先从宏观角度介绍系统的整体设计思路与技术选型依据。

2.1 整体设计

系统采用前后端分离架构，通过标准 REST API 进行通信，前端负责渲染与交互，后端专注于业务逻辑与数据持久化。

2.1.1 分层模型

系统在垂直方向上分为四个标准层次，各层职责明确，互不耦合。

2.1.1.1 表现层

表现层负责所有与用户直接交互的界面逻辑，包括页面路由、组件渲染、状态管理和用户输入校验。技术栈采用 Vue 3 + Pinia，构建产物通过 CDN 分发。

• 单向数据流：状态只能由 Action 触发变更，禁止组件直接修改 Store
• 懒加载路由：所有二级页面均采用动态 import，首屏 JS 体积控制在 200KB 以内
• 组件粒度：原子组件不超过 150 行，复合组件不超过 300 行

2.1.1.2 业务层

业务层承载核心逻辑，包括流程编排、规则校验、事务管理。采用 Domain-Driven Design（DDD）划分聚合根，每个聚合根对应独立的服务类。

• 无状态服务：所有 Service 类不持有实例变量，支持水平扩展
• 异常统一处理：通过全局 ExceptionHandler 拦截并转换为标准错误码
• 事务边界：事务注解只允许出现在 ApplicationService 层，禁止下沉至 Repository

2.1.2 模块划分

系统按业务域划分为以下独立模块，每个模块拥有独立的数据库 Schema 和 API 前缀：

2.2 技术选型

选型原则优先考虑社区活跃度、团队熟悉程度和长期维护成本，以下为最终确认的技术栈：

• 前端：Vue 3 / TypeScript / Vite / Pinia
• 后端：Spring Boot 3 / Java 21
• 数据库：PostgreSQL 16（主库）+ Redis 7（缓存）
• 消息队列：RabbitMQ
• 容器化：Docker + Kubernetes

第三章：核心功能

3.1 用户管理

用户管理模块覆盖从注册到注销的完整生命周期，并提供细粒度的权限控制能力。

3.1.1 注册与登录

系统支持多种注册与登录方式，统一颁发 JWT Token，有效期为 7 天，支持无感刷新。

3.1.1.1 手机号注册

用户通过手机号 + 短信验证码完成注册，流程如下：

1. 用户输入手机号，点击「获取验证码」
2. 系统校验手机号格式，调用短信服务商发送 6 位验证码（有效期 5 分钟）
3. 用户输入验证码，系统校验通过后创建账户
4. 返回 JWT Token 及用户基础信息

安全策略：同一手机号每分钟最多发送 1 条短信，每日上限 10 条；验证码错误超过 5 次锁定 30 分钟；所有密码使用 bcrypt（cost=12）存储，禁止明文或 MD5。

3.1.1.2 第三方登录

目前支持微信、GitHub 两种 OAuth 2.0 登录方式。首次登录自动完成账户创建并关联第三方身份，再次登录直接匹配已有账户。

用户点击登录 → 跳转第三方授权页 → 授权成功回调 →
服务端换取 AccessToken → 获取用户信息 →
匹配或创建本地账户 → 颁发 JWT → 重定向前端

⚠️ 注意：微信登录需要企业资质认证，个人开发者账号无法使用网页授权登录，仅可使用扫码登录。

3.1.2 权限控制

系统采用 RBAC（基于角色的访问控制）模型，角色与权限通过管理后台动态配置，无需重启服务生效。内置角色：SUPER_ADMIN / ADMIN / MEMBER / GUEST，权限粒度细化至单个 API 端点。

3.2 数据管理

数据管理模块提供标准的增删改查操作，并支持批量导入（CSV / Excel）和导出（JSON / CSV）。单次导入上限为 5000 条，超出建议拆分文件或使用异步任务接口。

第四章：部署指南

生产环境推荐使用 Docker Compose 进行单机部署，或使用提供的 Helm Chart 部署至 Kubernetes 集群。

# 拉取镜像
docker pull example/app:latest

# 启动服务（含数据库、缓存、应用）
docker compose -f docker-compose.prod.yml up -d

# 查看运行状态
docker compose ps

首次部署完成后，访问 http://<your-ip>:8080/admin 使用初始账号 admin / Admin@123 登录，请立即修改默认密码。

第五章：附录

5.1 错误码对照表

5.2 参考文档

• Vue 3 官方文档
• Spring Boot 官方文档
• PostgreSQL 16 发行说明

文档版本：v1.0.0 ｜ 最后更新：2025 年 3 月