zhangjf ae33bd4d6a feat: 初始化工作日志服务平台项目

- 项目文档：PRD、SRS、架构设计文档、前后端详细设计文档、架构设计规范
- 数据库脚本：用户创建和数据库初始化脚本
- 后端框架：Spring Boot 3.2 + MyBatis-Plus 3.5 基础架构
- 公共组件：统一返回结果、分页封装、全局异常处理
- 基础功能：链路追踪、API日志、健康检查接口
- 配置文件：application.yml.example 配置模板
- 开发规范：遵循架构设计规范，data目录存放MyBatis-Plus文件

2026-02-24 14:47:26 +08:00

14 KiB

Raw Blame History

工作日志服务平台 - 后端模块详细设计文档

版本号：V1.0
编写日期：2026-02-24
文档状态：初稿
适用范围：后端核心业务模块详细设计

1. 文档说明

本文档在总体架构的基础上，对核心业务模块进行更细粒度的设计，包括职责划分、主要流程、类结构与接口协作方式。各模块均遵循《架构设计规范》中关于目录结构、命名规范和分层规则。

1.1 基础模块说明

当前项目架构：

本项目采用单体应用架构，所有模块（Controller、Service、DataService、Mapper等）均在同一个应用 worklog-api 中。

基础模块使用规范：

按照架构设计规范，如果项目抽取公共能力到独立的 common 模块或其他基础模块，必须遵循以下规范：

强制要求：基础模块必须采用 Maven/Gradle 项目依赖方式引入

<!-- 在业务服务的 pom.xml 中引入基础模块 -->
<dependency>
    <groupId>com.wjbl.worklog</groupId>
    <artifactId>worklog-common</artifactId>
    <version>${project.version}</version>
</dependency>

禁止方式：
- ❌ 禁止拷贝代码到项目中
- ❌ 禁止直接引入 JAR 包
优势说明：
- 统一版本管理，避免基础代码不一致
- 便于基础能力的统一升级和维护
- 支持 Maven 的传递依赖管理

2. 人员管理模块（User Module）

2.1 模块职责

维护系统使用者的基础档案（账号、姓名、联系方式、职位等）。
提供账号启用/禁用能力，支撑权限控制与登录拦截。
为日志模块提供用户基础信息（用于展示、统计等）。

2.2 主要用例

用例编号	用例名称	发起方	说明
U01	查看人员列表	管理员	按姓名、职位、状态筛选人员列表
U02	新增人员	管理员	创建新账号，设置初始密码及角色
U03	编辑人员	管理员/本人	管理员可修改全字段，本人可修改联系方式、邮箱、描述
U04	启用/禁用人员	管理员	控制账号登录权限
U05	删除人员	管理员	建议逻辑删除，保留日志关联

2.3 分层设计

Controller 层：UserController
- /api/v1/user/page：分页查询人员列表
- /api/v1/user：创建人员
- /api/v1/user/{id}：修改人员信息
- /api/v1/user/{id}/status：启用/禁用人员
- /api/v1/user/{id}：删除人员
Service 层：UserService / UserServiceImpl
- 负责业务规则，例如：
  - 校验账号唯一性
  - 控制本人 vs 管理员的可编辑字段
  - 调用密码加密组件生成密码摘要
DataService 层：UserDataService / UserDataServiceImpl
- 继承 IService<User> 和 ServiceImpl<UserMapper, User>
- 封装用户的 CRUD 与常用查询（如按状态统计）。
Mapper 层：UserMapper
- 继承 BaseMapper<User>，可定义复杂查询 SQL。

2.4 类与DTO/VO设计

实体类：User
- 对应表：sys_user
- 主键：id，String 类型，存储雪花算法生成的 ID
- 字段：username、password、name、phone、email、position、description、status、role 等
DTO：
- UserCreateDTO：用于新增用户
- UserUpdateDTO：用于更新用户可编辑字段
VO：
- UserVO：用于列表/详情返回，隐藏敏感字段（如密码摘要）。

2.5 关键业务规则

账号唯一性：username 必须全局唯一。
密码存储：使用 BCrypt 加密，业务层不返回密码明文。
状态控制：当 status=0 时，登录拦截器拒绝所有业务请求。
软删除：deleted=1 时用户不再出现在列表中，但保留日志关联数据。

2.6 重复数据检测

唯一性依据：username（登录账号）字段在系统内必须唯一。
后端实现约定：
- 数据库层对 username 建立唯一索引；
- Service 层在创建用户前先查询是否已存在相同 username；
- 在修改用户时，如修改了 username，也需进行相同的唯一性校验；
- 若重复，返回 code = 400，message 类似"账号已存在，请更换后再试"。

3. 日志模板管理模块（Template Module）

3.1 模块职责

管理日志模板的创建、修改、启用/禁用和删除。
为日志编写界面提供可选模板列表，提高日志填写效率和一致性。

3.2 主要用例

用例编号	用例名称	发起方	说明
T01	查看模板列表	管理员/普通用户	管理员查看全部，普通用户仅查看启用模板
T02	新增模板	管理员	创建新的日志模板（名称+内容+说明）
T03	编辑模板	管理员	修改模板内容和说明，新建日志使用最新版本
T04	启用/禁用模板	管理员	控制模板在前端是否可选
T05	删除模板	管理员	若已被使用，建议仅禁用，不物理删除

3.3 分层设计

Controller 层：TemplateController
- /api/v1/template/list：按状态查询模板列表
- /api/v1/template：创建模板
- /api/v1/template/{id}：更新/删除模板（REST 风格拆分接口）
Service 层：TemplateService / TemplateServiceImpl
- 业务规则：
  - 模板名称唯一性校验
  - 禁用模板时不影响历史日志展示，仅影响新建时是否可选
DataService 层：LogTemplateDataService / LogTemplateDataServiceImpl
- 继承 IService<LogTemplate>，封装模板数据访问逻辑。
Mapper 层：LogTemplateMapper

3.4 实体与字段约束

实体类：LogTemplate
- 对应表：log_template
- templateName：唯一，非空
- templateContent：文本型，存储 Markdown 内容
- instruction：选填，文本
- status：0-禁用，1-启用

3.5 缓存策略

启用中的模板列表可缓存到 Redis：template:enabled:list，TTL 30分钟。
在模板增删改后，主动失效缓存，保持数据一致。

3.6 重复数据检测

唯一性依据：templateName（模板名称）在系统内必须唯一。
后端实现约定：
- 数据库层对 template_name 建立唯一索引；
- Service 层在创建模板前校验名称是否已存在；
- 在修改模板时，如变更了 templateName，也需进行相同的唯一性校验；
- 若重复，返回 code = 400，message 类似"模板名称已存在"。

4. 工作日志管理模块（WorkLog Module）

4.1 模块职责

提供员工日常工作日志的创建、编辑、删除、查看能力。
支持按日期范围、关键字等条件查询日志列表。
支持与模板的关联使用，保留历史日志内容快照。

4.2 主要用例

用例编号	用例名称	发起方	说明
L01	日志列表查询	管理员/普通用户	普通用户仅查看本人日志，管理员可查看全部
L02	新建日志	普通用户	支持选择模板并编辑内容，限制 2000 汉字
L03	编辑日志	普通用户	仅允许修改自己的日志，规则可配置（如只允许当日）
L04	删除日志	普通用户/管理员	普通用户删除自己的日志，管理员可删除任意日志
L05	查看日志详情	管理员/普通用户	渲染 Markdown 内容，展示模板名称

4.3 分层设计

Controller 层：LogController
- /api/v1/log/page：分页查询日志
- /api/v1/log：创建日志
- /api/v1/log/{id}：查看、更新、删除日志
Service 层：LogService / LogServiceImpl
- 负责业务规则：
  - 校验操作人是否为日志所有者（或管理员）
  - 校验字数限制（<= 2000 汉字）
  - 控制可编辑时间范围（如仅当日或未锁定日志）
DataService 层：WorkLogDataService / WorkLogDataServiceImpl
- 提供按用户、日期范围、关键字等条件的封装查询方法。
Mapper 层：WorkLogMapper

4.4 字段与约束

logDate：日期字段，允许补填过去日期
recordTime：日志记录时间，必须为服务器当前时间
content：文本字段，业务上限制为 2000 汉字（前后端双重校验）
templateId：可空，引用 log_template.id

4.5 日志编写流程概述

用户发起"新建日志"请求，前端可选模板（可选）。
前端加载模板内容填入编辑器，用户编辑并提交。
后端校验：登录态、字数限制、日期格式等。
持久化日志数据，记录 recordTime 为当前服务器时间。
返回成功结果，前端跳转至列表或详情页。

4.6 重复数据检测

当前版本说明：不对日志内容或日期做"重复日志"判定；
允许同一用户在同一天写多条日志；
如后续需要增加"同一天仅一条日志"或"内容完全相同视为重复"的规则，将在 PRD/SRS 中补充后，再同步更新本设计。

5. 认证与授权模块（Auth Module）

5.1 模块职责

提供用户登录、登出能力，并下发/校验 Token。
对业务接口进行权限拦截，确保普通用户与管理员权限边界清晰。

5.2 组件设计

AuthController：登录/登出接口
TokenService：
- 生成 Token（UUID）
- 存储 Token 到 Redis
- 解析 Token 并还原用户上下文
AuthFilter / AuthInterceptor：
- 拦截所有受保护的 /api/v1/** 请求
- 从 Authorization: Bearer {token} 中读取 Token
- 校验 Token 是否存在、是否过期
- 将用户信息放入上下文（如 UserContextHolder）

5.3 登录流程

用户调用 /api/v1/auth/login，提交账号与密码。
系统根据用户名查询用户记录，验证状态是否启用。
使用 BCrypt 对比密码。
生成 Token，写入 Redis：auth:token:{token}。
返回 Token 和用户基础信息。

5.4 授权规则

普通用户只能操作自己的日志和个人信息。
管理员可操作所有用户和日志、模板。
授权逻辑在 Service 层统一校验（如检查当前用户角色和操作对象归属）。

5.5 Token 存储结构

// Token 存储结构
Key: auth:token:{token}
Value: {
  "userId": "string",
  "username": "string",
  "role": "USER|ADMIN",
  "expireTime": timestamp
}
TTL: 24小时

6. 公共组件模块（Common Module）

6.1 统一返回结构

Result<T>：统一接口返回格式，包含：code、message、data、success。
PageResult<T>：分页返回结构，包含：pageNum、pageSize、total、list。

Result 示例：

{
  "code": 200,
  "message": "success",
  "data": { ... },
  "success": true
}

PageResult 示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "pageNum": 1,
    "pageSize": 10,
    "total": 100,
    "list": [ ... ]
  },
  "success": true
}

6.2 异常处理

BusinessException：用于表达可预期的业务错误。
GlobalExceptionHandler：
- 捕获 BusinessException，返回明确的业务错误码与提示文案。
- 捕获全局 Exception，记录错误日志并返回通用错误信息。

异常处理流程：

@ControllerAdvice
public class GlobalExceptionHandler {
    
    @ExceptionHandler(BusinessException.class)
    public Result<?> handleBusinessException(BusinessException e) {
        return Result.error(e.getCode(), e.getMessage());
    }
    
    @ExceptionHandler(Exception.class)
    public Result<?> handleException(Exception e) {
        log.error("系统异常", e);
        return Result.error(500, "系统异常，请稍后重试");
    }
}

6.3 AOP 日志

通过 AOP 切面统一记录 API 请求日志（方法、参数、耗时、结果）。
日志输出到 aop.log 或通过 MDC 注入到统一日志格式中。
所有日志必须包含 traceId 和 spanId，便于进行日志跟踪。

日志格式：

%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] [%X{traceId:-}][%X{spanId:-}] %-5level %logger{50} - %msg%n

日志示例：

2026-02-24 10:15:30.123 [http-nio-8080-exec-1] [a1b2c3d4...][1234abcd] INFO  c.c.w.controller.LogController - 创建日志成功

7. 附录

7.1 相关文档

7.2 目录结构参考

worklog-api/
├── src/main/java/com/company/worklog/
│   ├── controller/                      # 控制器层
│   │   ├── UserController.java
│   │   ├── LogController.java
│   │   └── TemplateController.java
│   ├── service/                         # 业务服务层
│   │   ├── UserService.java
│   │   ├── LogService.java
│   │   ├── TemplateService.java
│   │   └── impl/
│   ├── data/                            # 数据访问层
│   │   ├── entity/
│   │   ├── mapper/
│   │   └── service/                     # DataService层
│   │       ├── UserDataService.java
│   │       ├── WorkLogDataService.java
│   │       └── LogTemplateDataService.java
│   ├── dto/                             # 数据传输对象
│   ├── vo/                              # 视图对象
│   └── common/                          # 公共类
│       ├── Result.java
│       ├── PageResult.java
│       └── exception/

文档审批

角色	姓名	签字	日期
架构师	______	______	______
技术负责人	______	______	______

变更记录

版本	日期	变更内容	变更人
V1.0	2026-02-24	从架构设计文档中独立模块详细设计	______

14 KiB Raw Blame History Unescape Escape