worklog/doc/后端模块详细设计文档.md

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

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

---

## 1. 文档说明

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

### 1.1 基础模块说明

**当前项目架构**：

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

**基础模块使用规范**：

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

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

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

2. **禁止方式**：
   - ❌ 禁止拷贝代码到项目中
   - ❌ 禁止直接引入 JAR 包

3. **优势说明**：
   - 统一版本管理，避免基础代码不一致
   - 便于基础能力的统一升级和维护
   - 支持 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 关键业务规则

1. **账号唯一性**：`username` 必须全局唯一。
2. **密码存储**：使用 BCrypt 加密，业务层不返回密码明文。
3. **状态控制**：当 `status=0` 时，登录拦截器拒绝所有业务请求。
4. **软删除**：`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 日志编写流程概述

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

### 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 登录流程

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

### 5.4 授权规则

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

### 5.5 Token 存储结构

```java
// 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 示例**：
```json
{
  "code": 200,
  "message": "success",
  "data": { ... },
  "success": true
}
```

**PageResult 示例**：
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "pageNum": 1,
    "pageSize": 10,
    "total": 100,
    "list": [ ... ]
  },
  "success": true
}
```

### 6.2 异常处理

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

**异常处理流程**：
```java
@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**，便于进行日志跟踪。

**日志格式**：
```text
%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] [%X{traceId:-}][%X{spanId:-}] %-5level %logger{50} - %msg%n
```

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

---

## 7. 附录

### 7.1 相关文档

- [架构设计文档](./架构设计文档.md)
- [前端详细设计文档](./前端详细设计文档.md)
- [架构设计规范](./规范/架构设计规范.md)
- [产品需求文档 PRD](./产品需求文档PRD.md)
- [需求规格说明书 SRS](./需求规格说明书SRS.md)

### 7.2 目录结构参考

```text
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 | 从架构设计文档中独立模块详细设计 | ______ |