worklog/doc/架构设计文档.md

# 工作日志服务平台 - 架构设计文档

**版本号**：V1.0  
**编写日期**：2026-02-24  
**文档状态**：初稿  
**项目代号**：WorkLog Platform

---

## 1. 项目概述

### 1.1 项目背景

本项目旨在构建一套轻量级、多终端的工作日志服务平台，配合 2026 年公司人员管理数字化升级需求。通过规范员工日常工作记录，沉淀工作成果，并通过模板化管理提高日志填写的效率与质量。

### 1.2 设计目标

1. **规范化架构**：遵循架构设计规范，确保代码结构清晰、可维护性强
2. **轻量高效**：聚焦核心功能，系统响应快速，维护成本低
3. **多端支持**：PC 管理后台 + 移动端 H5，满足不同场景需求
4. **安全可靠**：保障数据安全，符合 2026 年数据安全合规要求

### 1.3 技术选型

| 层级 | 技术选型 | 说明 |
|------|----------|------|
| **后端框架** | Spring Boot 3.2 | 主流 Java 开发框架 |
| **数据库** | MySQL 8.0 | 关系型数据库 |
| **缓存** | Redis 7.x | 缓存 Token、提升性能 |
| **ORM框架** | MyBatis-Plus 3.5 | 简化数据访问层开发 |
| **管理后台** | Vue 3 + TypeScript + Element Plus | 现代化前端技术栈 |
| **移动端** | Vue 3 + Vite 5 + Vant 4 | H5 移动端解决方案 |

---

## 2. 系统架构设计

### 2.1 整体架构

```mermaid
graph TB
    subgraph "客户端层"
        A1[管理后台 Web]
        A2[移动端 H5]
    end
    
    subgraph "应用层"
        B1[worklog-api<br/>统一服务]
    end
    
    subgraph "数据层"
        C1[(MySQL 8.0)]
        C2[(Redis 7.x)]
    end
    
    A1 -->|HTTPS| B1
    A2 -->|HTTPS| B1
    B1 --> C1
    B1 --> C2
```

**说明**：
- **当前架构**：采用单体应用架构，满足轻量化需求和快速上线目标
- **前后端分离**：管理后台和移动端共用统一 API
- **缓存设计**：Redis 用于 Token 存储和缓存热点数据
- **架构演进**：当前为单体应用，如未来业务增长需拆分为微服务，将遵循架构设计规范中的OpenFeign服务调用规范

### 2.2 应用分层架构

```mermaid
graph TB
    A[Controller 层] --> B[Service 层]
    B --> C[DataService 层]
    C --> D[Mapper 层]
    D --> E[(数据库)]
    
    style A fill:#e1f5ff
    style B fill:#fff4e1
    style C fill:#e8f5e9
    style D fill:#f3e5f5
```

**职责划分**：
1. **Controller 层**：接收请求，参数校验，调用 Service
2. **Service 层**：业务逻辑处理，事务控制，DTO/VO 转换
3. **DataService 层**：封装数据访问，提供 CRUD 方法
4. **Mapper 层**：数据库操作接口

---

## 3. 模块设计

### 3.1 模块划分

```mermaid
graph LR
    A[工作日志平台] --> B[系统管理模块]
    A --> C[日志管理模块]
    A --> D[模板管理模块]
    
    B --> B1[人员管理]
    B --> B2[认证授权]
    
    C --> C1[日志编写]
    C --> C2[日志查询]
    C --> C3[日志统计]
    
    D --> D1[模板配置]
    D --> D2[模板应用]
```

### 3.2 目录结构设计

遵循架构设计规范，项目目录结构如下：

```text
worklog-api/
├── src/main/java/com/wjbl/worklog/
│   ├── WorklogApplication.java          # 启动类
│   ├── config/                          # 配置类
│   │   ├── SecurityConfig.java
│   │   ├── RedisConfig.java
│   │   └── MybatisPlusConfig.java
│   ├── controller/                      # 控制器层
│   │   ├── UserController.java
│   │   ├── LogController.java
│   │   └── TemplateController.java
│   ├── service/                         # 业务服务层
│   │   ├── UserService.java
│   │   ├── LogService.java
│   │   ├── TemplateService.java
│   │   └── impl/
│   │       ├── UserServiceImpl.java
│   │       ├── LogServiceImpl.java
│   │       └── TemplateServiceImpl.java
│   ├── data/                            # 数据访问层（遵循架构设计规范）
│   │   ├── entity/
│   │   │   ├── User.java
│   │   │   ├── WorkLog.java
│   │   │   └── LogTemplate.java
│   │   ├── mapper/
│   │   │   ├── UserMapper.java
│   │   │   ├── WorkLogMapper.java
│   │   │   └── LogTemplateMapper.java
│   │   └── service/                     # DataService层（XxxDataService命名规范）
│   │       ├── UserDataService.java
│   │       ├── WorkLogDataService.java
│   │       ├── LogTemplateDataService.java
│   │       └── impl/
│   │           ├── UserDataServiceImpl.java
│   │           ├── WorkLogDataServiceImpl.java
│   │           └── LogTemplateDataServiceImpl.java
│   ├── dto/                             # 数据传输对象
│   │   ├── UserCreateDTO.java
│   │   ├── UserUpdateDTO.java
│   │   ├── LogCreateDTO.java
│   │   └── TemplateCreateDTO.java
│   ├── vo/                              # 视图对象
│   │   ├── UserVO.java
│   │   ├── LogVO.java
│   │   └── TemplateVO.java
│   ├── enums/                           # 枚举类
│   │   ├── UserStatus.java
│   │   └── TemplateStatus.java
│   └── common/                          # 公共类
│       ├── Result.java
│       ├── PageResult.java
│       └── exception/
│           └── BusinessException.java
├── src/main/resources/
│   ├── application.yml
│   └── logback-spring.xml
└── pom.xml
```

**目录设计说明**：

1. **data 目录**：按照架构设计规范，MyBatis-Plus 相关文件统一存放在 data 目录下
2. **DataService 命名**：使用 `XxxDataService`/`XxxDataServiceImpl` 命名，避免与业务 Service 冲突
3. **分层职责**：
   - Controller → Service → DataService → Mapper
   - 业务 Service 必须通过 DataService 访问数据，禁止直接注入 Mapper

---

## 4. 数据库设计

### 4.1 数据库表设计

#### 4.1.1 用户表 (sys_user)

```sql
CREATE TABLE sys_user (
    id              VARCHAR(20)     NOT NULL PRIMARY KEY COMMENT '用户ID',
    username        VARCHAR(50)     NOT NULL UNIQUE COMMENT '登录账号',
    password        VARCHAR(100)    NOT NULL COMMENT '登录密码（加密）',
    name            VARCHAR(50)     NOT NULL COMMENT '姓名',
    phone           VARCHAR(20)     DEFAULT NULL COMMENT '联系方式',
    email           VARCHAR(100)    DEFAULT NULL COMMENT '电子邮箱',
    position        VARCHAR(50)     DEFAULT NULL COMMENT '职位',
    description     VARCHAR(500)    DEFAULT NULL COMMENT '描述',
    status          TINYINT(1)      NOT NULL DEFAULT 1 COMMENT '状态（0-禁用，1-启用）',
    role            VARCHAR(20)     NOT NULL DEFAULT 'USER' COMMENT '角色（USER-普通用户，ADMIN-管理员）',
    created_by      VARCHAR(20)     NOT NULL COMMENT '创建人ID',
    created_time    DATETIME        NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    updated_by      VARCHAR(20)     NOT NULL COMMENT '更新人ID',
    updated_time    DATETIME        NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    deleted         TINYINT(1)      NOT NULL DEFAULT 0 COMMENT '逻辑删除（0-未删除，1-已删除）',
    INDEX idx_username (username),
    INDEX idx_status (status),
    INDEX idx_deleted (deleted)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='系统用户表';
```

#### 4.1.2 日志模板表 (log_template)

```sql
CREATE TABLE log_template (
    id              VARCHAR(20)     NOT NULL PRIMARY KEY COMMENT '模板ID',
    template_name   VARCHAR(100)    NOT NULL COMMENT '模板名称',
    template_content TEXT           NOT NULL COMMENT '模板内容（Markdown格式）',
    instruction     VARCHAR(500)    DEFAULT NULL COMMENT '使用说明',
    status          TINYINT(1)      NOT NULL DEFAULT 1 COMMENT '状态（0-禁用，1-启用）',
    created_by      VARCHAR(20)     NOT NULL COMMENT '创建人ID',
    created_time    DATETIME        NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    updated_by      VARCHAR(20)     NOT NULL COMMENT '更新人ID',
    updated_time    DATETIME        NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    deleted         TINYINT(1)      NOT NULL DEFAULT 0 COMMENT '逻辑删除（0-未删除，1-已删除）',
    INDEX idx_status (status),
    INDEX idx_deleted (deleted)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='日志模板表';
```

#### 4.1.3 工作日志表 (work_log)

```sql
CREATE TABLE work_log (
    id              VARCHAR(20)     NOT NULL PRIMARY KEY COMMENT '日志ID',
    user_id         VARCHAR(20)     NOT NULL COMMENT '记录人ID',
    log_date        DATE            NOT NULL COMMENT '日志日期',
    record_time     DATETIME        NOT NULL COMMENT '记录时间',
    content         TEXT            NOT NULL COMMENT '日志内容（Markdown格式，最大2000汉字）',
    template_id     VARCHAR(20)     DEFAULT NULL COMMENT '使用模板ID',
    created_by      VARCHAR(20)     NOT NULL COMMENT '创建人ID',
    created_time    DATETIME        NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    updated_by      VARCHAR(20)     NOT NULL COMMENT '更新人ID',
    updated_time    DATETIME        NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    deleted         TINYINT(1)      NOT NULL DEFAULT 0 COMMENT '逻辑删除（0-未删除，1-已删除）',
    INDEX idx_user_id (user_id),
    INDEX idx_log_date (log_date),
    INDEX idx_deleted (deleted),
    FOREIGN KEY (user_id) REFERENCES sys_user(id),
    FOREIGN KEY (template_id) REFERENCES log_template(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='工作日志表';
```

### 4.2 数据库设计说明

1. **主键策略**：所有表主键使用 `VARCHAR(20)` 存储雪花算法生成的 19 位数字 ID
2. **审计字段**：统一包含 `created_by`、`created_time`、`updated_by`、`updated_time`、`deleted`
3. **逻辑删除**：使用 `deleted` 字段实现软删除，保留历史数据
4. **索引设计**：为常用查询字段建立索引，提升查询性能
5. **字符集**：统一使用 `utf8mb4`，支持 emoji 等特殊字符

---

## 5. API 接口设计

### 5.1 接口规范

遵循 RESTful 风格，URL 格式：`/api/v1/{资源}/{动作}`

### 5.2 认证授权接口

#### 5.2.1 用户登录

```http
POST /api/v1/auth/login
Content-Type: application/json

{
  "username": "string",
  "password": "string"
}

Response:
{
  "code": 200,
  "message": "success",
  "data": {
    "token": "string",
    "userInfo": {
      "id": "string",
      "username": "string",
      "name": "string",
      "role": "USER|ADMIN"
    }
  },
  "success": true
}
```

#### 5.2.2 用户登出

```http
POST /api/v1/auth/logout
Authorization: Bearer {token}

Response:
{
  "code": 200,
  "message": "success",
  "data": null,
  "success": true
}
```

### 5.3 人员管理接口

#### 5.3.1 人员列表（分页）

```http
GET /api/v1/user/page?pageNum=1&pageSize=10&keyword=张三&status=1
Authorization: Bearer {token}

Response:
{
  "code": 200,
  "message": "success",
  "data": {
    "pageNum": 1,
    "pageSize": 10,
    "total": 100,
    "list": [
      {
        "id": "string",
        "username": "string",
        "name": "string",
        "phone": "string",
        "email": "string",
        "position": "string",
        "status": 1,
        "role": "USER"
      }
    ]
  },
  "success": true
}
```

#### 5.3.2 创建人员

```http
POST /api/v1/user
Authorization: Bearer {token}
Content-Type: application/json

{
  "username": "string",      // 必填
  "password": "string",      // 必填
  "name": "string",          // 必填
  "phone": "string",         // 选填
  "email": "string",         // 选填
  "position": "string",      // 选填
  "description": "string",   // 选填
  "role": "USER"             // 必填
}

Response:
{
  "code": 200,
  "message": "success",
  "data": "1234567890123456789", // 用户ID
  "success": true
}
```

#### 5.3.3 更新人员信息

```http
PUT /api/v1/user/{id}
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "string",
  "phone": "string",
  "email": "string",
  "position": "string",
  "description": "string"
}

Response:
{
  "code": 200,
  "message": "success",
  "data": null,
  "success": true
}
```

#### 5.3.4 启用/禁用用户

```http
PUT /api/v1/user/{id}/status
Authorization: Bearer {token}
Content-Type: application/json

{
  "status": 1  // 0-禁用，1-启用
}

Response:
{
  "code": 200,
  "message": "success",
  "data": null,
  "success": true
}
```

#### 5.3.5 删除人员

```http
DELETE /api/v1/user/{id}
Authorization: Bearer {token}

Response:
{
  "code": 200,
  "message": "success",
  "data": null,
  "success": true
}
```

### 5.4 模板管理接口

#### 5.4.1 模板列表

```http
GET /api/v1/template/list?status=1
Authorization: Bearer {token}

Response:
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": "string",
      "templateName": "string",
      "templateContent": "string",
      "instruction": "string",
      "status": 1
    }
  ],
  "success": true
}
```

#### 5.4.2 创建模板

```http
POST /api/v1/template
Authorization: Bearer {token}
Content-Type: application/json

{
  "templateName": "string",       // 必填
  "templateContent": "string",    // 必填，Markdown格式
  "instruction": "string"         // 选填
}

Response:
{
  "code": 200,
  "message": "success",
  "data": "1234567890123456789",
  "success": true
}
```

### 5.5 日志管理接口

#### 5.5.1 日志列表（分页）

```http
GET /api/v1/log/page?pageNum=1&pageSize=10&startDate=2026-01-01&endDate=2026-01-31
Authorization: Bearer {token}

Response:
{
  "code": 200,
  "message": "success",
  "data": {
    "pageNum": 1,
    "pageSize": 10,
    "total": 50,
    "list": [
      {
        "id": "string",
        "userId": "string",
        "userName": "string",
        "logDate": "2026-01-15",
        "contentPreview": "今日完成...",
        "templateName": "研发日报",
        "recordTime": "2026-01-15 18:30:00"
      }
    ]
  },
  "success": true
}
```

#### 5.5.2 创建日志

```http
POST /api/v1/log
Authorization: Bearer {token}
Content-Type: application/json

{
  "logDate": "2026-01-15",       // 必填
  "content": "string",           // 必填，最大2000汉字
  "templateId": "string"         // 选填
}

Response:
{
  "code": 200,
  "message": "success",
  "data": "1234567890123456789",
  "success": true
}
```

#### 5.5.3 查看日志详情

```http
GET /api/v1/log/{id}
Authorization: Bearer {token}

Response:
{
  "code": 200,
  "message": "success",
  "data": {
    "id": "string",
    "userId": "string",
    "userName": "string",
    "logDate": "2026-01-15",
    "content": "string",           // Markdown格式
    "contentHtml": "string",       // 渲染后的HTML
    "templateId": "string",
    "templateName": "string",
    "recordTime": "2026-01-15 18:30:00"
  },
  "success": true
}
```

#### 5.5.4 更新日志

```http
PUT /api/v1/log/{id}
Authorization: Bearer {token}
Content-Type: application/json

{
  "content": "string",
  "templateId": "string"
}

Response:
{
  "code": 200,
  "message": "success",
  "data": null,
  "success": true
}
```

#### 5.5.5 删除日志

```http
DELETE /api/v1/log/{id}
Authorization: Bearer {token}

Response:
{
  "code": 200,
  "message": "success",
  "data": null,
  "success": true
}
```

---

## 6. 安全设计

### 6.1 认证机制

采用 **UUID Token + Redis** 方案：

1. **Token 生成**：用户登录成功后，生成 UUID 作为 Token
2. **Token 存储**：Token 存储到 Redis，Key 为 `auth:token:{token}`，Value 为用户信息
3. **Token 有效期**：24 小时，支持续期
4. **Token 传递**：请求头 `Authorization: Bearer {token}`

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

### 6.2 权限控制

| 角色 | 权限范围 |
|------|----------|
| **普通用户** | 1. 查看/修改本人信息<br>2. 创建/查看/编辑/删除本人日志<br>3. 查看启用的模板 |
| **管理员** | 1. 普通用户所有权限<br>2. 人员管理（全部权限）<br>3. 模板管理（全部权限）<br>4. 查看所有日志 |

### 6.3 数据安全

1. **密码加密**：使用 BCrypt 算法加密存储，加密强度 10
2. **传输加密**：全站 HTTPS，防止中间人攻击
3. **SQL 防注入**：使用 MyBatis-Plus 预编译，防止 SQL 注入
4. **XSS 防护**：Markdown 渲染时进行 HTML 过滤
5. **敏感信息脱敏**：日志中不记录密码等敏感信息

### 6.4 接口鉴权

```java
// 白名单路径（无需Token）
/api/v1/auth/login
/api/v1/auth/health

// 需要认证的路径
/api/v1/**

// 需要管理员权限的路径
/api/v1/user/**
/api/v1/template/**
```

---

## 7. 日志与追踪设计

### 7.1 日志配置

按照架构设计规范，日志配置如下：

```text
logs/
├── app.log               # 应用主日志（所有级别）
├── error.log             # ERROR 级别日志
├── sql.log               # MyBatis-Plus SQL 日志
└── aop.log               # API 请求日志
```

### 7.2 链路追踪

所有日志必须包含 TraceId 和 SpanId：

```text
日志格式：
%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.3 HTTP Header 透传

| Header | 说明 |
|--------|------|
| `X-Trace-Id` | 全链路追踪 ID |
| `X-Span-Id` | 当前服务 Span |
| `X-User-Id` | 用户 ID |
| `X-Username` | 用户名 |

---

## 8. 性能优化设计

### 8.1 缓存策略

使用 Redis 缓存以下数据：

1. **Token 信息**：`auth:token:{token}`，TTL 24小时
2. **启用的模板列表**：`template:enabled:list`，TTL 30分钟
3. **用户基本信息**：`user:info:{userId}`，TTL 1小时

### 8.2 数据库优化

1. **索引优化**：为常用查询字段建立索引
2. **分页查询**：使用 MyBatis-Plus 分页插件
3. **字段限制**：日志内容最大 2000 汉字，防止数据膨胀
4. **连接池配置**：HikariCP，最小连接数 5，最大连接数 20

### 8.3 前端优化

1. **列表分页**：默认每页 10 条，支持 10/20/50 切换
2. **日志预览**：列表仅显示前 50 字摘要
3. **Markdown 渲染**：使用客户端渲染，减轻服务器压力
4. **图片懒加载**：大列表场景下使用懒加载

---

## 9. 部署架构

### 9.1 服务器配置

**最小配置**（支持 50 人同时在线）：
- CPU: 2 核
- 内存: 4GB
- 磁盘: 50GB SSD
- 带宽: 5Mbps

**推荐配置**（支持 500 人同时在线）：
- CPU: 4 核
- 内存: 8GB
- 磁盘: 100GB SSD
- 带宽: 10Mbps

### 9.2 部署结构

```text
/opt/worklog/
├── worklog-api/                # 后端服务
│   ├── bin/
│   │   ├── start.sh
│   │   ├── stop.sh
│   │   └── restart.sh
│   ├── lib/
│   │   └── worklog-api.jar
│   └── conf/
│       ├── application.yml
│       └── logback-spring.xml
├── worklog-admin/              # 管理后台前端
│   └── dist/
├── worklog-mobile/             # 移动端前端
│   └── dist/
└── logs/                       # 日志目录
    ├── app.log
    ├── error.log
    └── sql.log
```

### 9.3 Nginx 配置

```nginx
server {
    listen 80;
    server_name worklog.company.com;
    
    # 管理后台
    location /admin/ {
        alias /opt/worklog/worklog-admin/dist/;
        try_files $uri $uri/ /admin/index.html;
    }
    
    # 移动端
    location /mobile/ {
        alias /opt/worklog/worklog-mobile/dist/;
        try_files $uri $uri/ /mobile/index.html;
    }
    
    # 后端API
    location /api/ {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}
```

### 9.4 开发环境配置

本节提供开发环境的配置信息，用于本地开发和测试。

#### 9.4.1 MySQL 配置

```yaml
# application-dev.yml
spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:3306/worklog?useUnicode=true&characterEncoding=utf8mb4&serverTimezone=Asia/Shanghai&useSSL=false
    username: worklog
    password: Wlog@123
```

**配置说明**：
- **主机地址**：localhost
- **端口**：3306
- **数据库名**：worklog
- **数据库用户**：worklog
- **数据库密码**：Wlog@123
- **认证插件**：caching_sha2_password（MySQL 8.0 默认）
- **安装模式**：service（系统服务方式）

**数据库用户创建**：

```sql
-- 创建数据库用户
CREATE USER 'worklog'@'localhost' IDENTIFIED WITH caching_sha2_password BY 'Wlog@123';
CREATE USER 'worklog'@'%' IDENTIFIED WITH caching_sha2_password BY 'Wlog@123';

-- 授予权限
GRANT ALL PRIVILEGES ON worklog.* TO 'worklog'@'localhost';
GRANT ALL PRIVILEGES ON worklog.* TO 'worklog'@'%';

-- 刷新权限
FLUSH PRIVILEGES;
```

#### 9.4.2 Redis 配置

```yaml
# application-dev.yml
spring:
  data:
    redis:
      host: localhost
      port: 6379
      password: zjf@123456
      database: 0
      timeout: 5000ms
      lettuce:
        pool:
          max-active: 8
          max-wait: -1ms
          max-idle: 8
          min-idle: 0
```

**配置说明**：
- **主机地址**：localhost
- **端口**：6379
- **密码**：zjf@123456
- **数据库索引**：0（默认使用 DB0）
- **安装模式**：service（系统服务方式）

#### 9.4.3 Nacos 配置

```yaml
# bootstrap.yml
spring:
  cloud:
    nacos:
      discovery:
        server-addr: localhost:8848
        username: nacos
        password: nacos
        namespace: worklog-dev
      config:
        server-addr: localhost:8848
        username: nacos
        password: nacos
        namespace: worklog-dev
        file-extension: yml
        group: DEFAULT_GROUP
```

**配置说明**：
- **主机地址**：localhost
- **服务端口**：8848
- **控制台端口**：8048
- **用户名**：nacos
- **密码**：nacos
- **安装路径**：/home/along/MyApp/nacos
- **安装模式**：local（本地单机模式）
- **命名空间**：worklog-dev（开发环境隔离）

**访问地址**：
- Nacos 控制台：http://localhost:8048/nacos

#### 9.4.4 腾讯云 COS 配置（可选）

如项目需要使用对象存储服务，可配置腾讯云 COS：

```yaml
# application-dev.yml
tencent:
  cos:
    app-id: 1308258046
    secret-id: AKIDukKfkY5LK2SbU6QTM7csugCSSDjzyiDS
    secret-key: 0lHXYIn20jDRP7ZlhNnyub3GEwObZHjw
    bucket-name: test-1308258046
    bucket-host: https://test-1308258046.cos.ap-beijing.myqcloud.com
    region: ap-beijing
```

**配置说明**：
- **AppId**：1308258046
- **SecretId**：AKIDukKfkY5LK2SbU6QTM7csugCSSDjzyiDS
- **SecretKey**：0lHXYIn20jDRP7ZlhNnyub3GEwObZHjw
- **存储桶名称**：test-1308258046
- **访问域名**：https://test-1308258046.cos.ap-beijing.myqcloud.com
- **所属地域**：ap-beijing（北京）

**用途说明**：
- 用于存储用户上传的附件、图片等文件（V2.0 功能）
- 开发环境使用测试存储桶
- 生产环境需配置独立的生产存储桶

#### 9.4.5 配置文件分离架构（遵循架构设计规范第7章）

本项目采用配置文件分离架构，将统一环境配置和服务个性化配置分离，提高配置管理的灵活性和可维护性。

##### 9.4.5.1 配置文件结构

**开发阶段**配置文件位于 `src/main/resources/conf/` 目录：

```text
worklog-api/src/main/resources/
├── application.yml              # 主配置文件（Spring Boot 配置）
├── bootstrap.yml                # 启动配置（Nacos 配置中心，可选）
├── logback-spring.xml           # 日志配置（从环境变量读取参数）
└── conf/                        # 配置文件目录（开发阶段）
    ├── env.properties           # 统一环境配置
    ├── service.properties       # 服务个性化配置
    ├── env.properties.example   # 环境配置模板
    └── service.properties.example # 服务配置模板
```

**生产部署阶段**配置文件组织结构（打包后）：

```text
worklog-api/
├── bin/                          # 脚本目录
│   ├── start.sh                  # 启动脚本（含配置加载逻辑）
│   ├── stop.sh                   # 停止脚本
│   ├── restart.sh                # 重启脚本
│   └── status.sh                 # 状态查看脚本
├── lib/                          # JAR 包目录
│   └── worklog-api.jar
├── conf/                         # 配置文件目录（部署阶段）
│   ├── env.properties            # 统一环境配置（所有服务共用）
│   ├── service.properties        # 服务个性化配置（当前服务独立）
│   ├── env.properties.example    # 环境配置模板
│   └── service.properties.example # 服务配置模板
└── logs/                         # 日志目录（扁平结构）
    ├── app.log                   # 应用主日志
    ├── sql.log                   # SQL 日志
    └── console.log               # 控制台日志
```

**说明**：
- 开发阶段：配置文件直接在 `src/main/resources/` 目录下，跟随源码管理
- 部署阶段：通过 Maven Assembly 插件打包后，配置文件输出到 `conf/` 目录，位于应用根目录

开发环境配置文件结构：

```text
src/main/resources/
├── application.yml              # 主配置文件（Spring Boot 配置）
├── application.yml.example      # 主配置模板
├── bootstrap.yml                # 启动配置（Nacos 配置中心，可选）
├── logback-spring.xml           # 日志配置（从环境变量读取参数）
├── env.properties               # 统一环境配置（敏感信息，不提交）
├── env.properties.example       # 环境配置模板
├── service.properties           # 服务个性化配置（敏感信息，不提交）
└── service.properties.example   # 服务配置模板
```

##### 9.4.5.2 配置加载顺序

启动脚本 [`start.sh`](file:///home/along/MyCode/wanjiabuluo/worklog/deploy/scripts/start.sh) 按以下顺序加载配置（后加载覆盖先加载）：

1. **加载统一环境配置** [`conf/env.properties`](file:///home/along/MyCode/wanjiabuluo/worklog/worklog-api/src/main/resources/conf/env.properties)
2. **加载服务个性化配置** [`conf/service.properties`](file:///home/along/MyCode/wanjiabuluo/worklog/worklog-api/src/main/resources/conf/service.properties)
3. **启动 Spring Boot 应用**，配置项通过环境变量传递

```bash
# 配置加载逻辑（start.sh 中实现）
load_properties "${APP_HOME}/conf/env.properties"
load_properties "${APP_HOME}/conf/service.properties"
```

##### 9.4.5.3 统一环境配置（env.properties）

统一环境配置包含所有服务共用的配置项，主要包括：

**数据库配置**：
- `DB_HOST`：数据库主机地址（localhost）
- `DB_PORT`：数据库端口（3306）
- `DB_NAME`：数据库名称（worklog）
- `DB_USERNAME`：数据库用户名（worklog）
- `DB_PASSWORD`：数据库密码（Wlog@123）
- 连接池参数：`DB_POOL_MIN_IDLE`、`DB_POOL_MAX_SIZE` 等

**Redis 配置**：
- `REDIS_HOST`：Redis 主机地址（localhost）
- `REDIS_PORT`：Redis 端口（6379）
- `REDIS_PASSWORD`：Redis 密码（zjf@123456）
- `REDIS_DATABASE`：数据库索引（0）
- 连接池参数：`REDIS_POOL_MAX_ACTIVE`、`REDIS_POOL_MAX_IDLE` 等

**Nacos 配置**：
- `NACOS_SERVER_ADDR`：Nacos 服务地址（localhost:8848）
- `NACOS_NAMESPACE`：命名空间（worklog-dev）
- `NACOS_GROUP`：分组（DEFAULT_GROUP）
- `NACOS_USERNAME`、`NACOS_PASSWORD`：认证信息

**文件上传配置**：
- `FILE_UPLOAD_MAX_SIZE`：单个文件最大大小（50MB）
- `FILE_UPLOAD_MAX_REQUEST_SIZE`：请求最大大小（100MB）
- `FILE_STORAGE_PATH`：文件存储路径（./uploads）

**日志配置**：
- `LOG_PATH`：日志路径（./logs，扁平目录结构）
- `LOG_LEVEL_ROOT`：根日志级别（INFO）
- `LOG_LEVEL_APP`：应用日志级别（DEBUG）
- `LOG_FILE_MAX_SIZE`：日志文件最大大小（100MB）
- `LOG_FILE_MAX_HISTORY`：日志保留天数（30）

**JVM 配置**：
- `JVM_XMS`、`JVM_XMX`：堆内存配置（512m/1024m）
- `JVM_METASPACE_SIZE`、`JVM_MAX_METASPACE_SIZE`：元空间配置
- `JVM_GC_TYPE`：GC 类型（G1GC）
- `JVM_MAX_GC_PAUSE_MILLIS`：最大 GC 停顿时间（200ms）

**业务配置**：
- `TOKEN_EXPIRE_TIME`：Token 有效期（86400秒，24小时）
- `TOKEN_PREFIX`：Token 缓存前缀（auth:token:）
- `WORKLOG_MAX_CONTENT_LENGTH`：日志内容最大长度（2000字符）
- `UPLOAD_ALLOWED_EXTENSIONS`：允许上传的文件扩展名

配置示例详见：[`conf/env.properties.example`](file:///home/along/MyCode/wanjiabuluo/worklog/worklog-api/src/main/resources/conf/env.properties.example)

##### 9.4.5.4 服务个性化配置（service.properties）

服务个性化配置包含当前服务独立的配置项，主要包括：

**服务基本信息**：
- `APP_NAME`：服务名称（worklog-api）
- `INSTANCE_NAME`：实例名称，多租户场景使用，默认与 `APP_NAME` 相同
- `TENANT_ID`：租户标识，多租户场景用于路由，单租户留空

**服务端口配置**：
- `SERVER_PORT`：服务端口，可覆盖 application.yml 中的端口配置（8080）

**环境标识**：
- `SPRING_PROFILES_ACTIVE`：运行环境（dev-开发，test-测试，prod-生产）

**个性化覆盖配置（可选）**：
- `LOG_PATH`：如需使用不同的日志路径，可在此覆盖
- `LOG_LEVEL_APP`：如需使用不同的日志级别，可在此覆盖

配置示例详见：[`conf/service.properties.example`](file:///home/along/MyCode/wanjiabuluo/worklog/worklog-api/src/main/resources/conf/service.properties.example)

##### 9.4.5.5 日志配置集中化

日志配置遵循架构设计规范第7.4节要求：

1. **日志文件命名**：
   - 主日志文件统一命名为 `app.log`
   - SQL 日志独立输出到 `sql.log`（强制要求）
   - 所有日志文件输出到 `logs/` 目录（扁平结构，无子目录）

2. **日志格式要求**：
   - 所有日志必须包含 `traceId` 和 `spanId`，便于链路追踪
   - 日志格式：`%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] [%X{traceId:-}][%X{spanId:-}] %-5level %logger{50} - %msg%n`

3. **配置参数化**：
   - [`logback-spring.xml`](file:///home/along/MyCode/wanjiabuluo/worklog/worklog-api/src/main/resources/logback-spring.xml) 从环境变量读取关键参数
   - 支持的环境变量：`LOG_PATH`、`LOG_LEVEL_ROOT`、`LOG_LEVEL_APP`

##### 9.4.5.6 配置文件安全管理

**版本控制策略**：

- **不提交到仓库**：实际配置文件（包含敏感信息）
  - `src/main/resources/conf/env.properties`
  - `src/main/resources/conf/service.properties`
  - `src/main/resources/application.yml`
  - `src/main/resources/bootstrap.yml`

- **提交到仓库**：配置模板文件
  - `src/main/resources/conf/env.properties.example`
  - `src/main/resources/conf/service.properties.example`

**部署流程**：

1. 在服务器上复制模板文件为实际配置文件
2. 根据实际环境修改配置参数
3. 启动脚本自动加载配置并启动应用

```bash
# 部署时操作
cp conf/env.properties.example conf/env.properties
cp conf/service.properties.example conf/service.properties
vim conf/env.properties  # 修改实际配置
vim conf/service.properties  # 修改实际配置
./bin/start.sh  # 启动应用
```

#### 9.4.6 环境配置文件管理（开发环境）

开发环境配置文件建议按以下结构组织：

```text
src/main/resources/
├── application.yml              # 主配置文件
├── bootstrap.yml                # 启动配置（Nacos）
└── logback-spring.xml           # 日志配置
```

**注意**：开发环境不使用多环境配置分离（application-dev.yml、application-test.yml 等），统一使用 application.yml。

**配置优先级**：
1. bootstrap.yml（最先加载，用于 Nacos 配置中心，默认禁用）
2. application.yml（通用配置，开发环境使用）
3. 生产环境通过 conf/env.properties 和 conf/service.properties 配置

**激活开发环境**：

开发环境直接使用 application.yml，无需配置环境标识。

生产环境通过启动参数激活：

```bash
java -jar worklog-api.jar --spring.profiles.active=prod
```

#### 9.4.7 安全注意事项

⚠️ **重要提示**：

1. **密码安全**：
   - 实际配置文件（包含敏感信息）不应提交到代码仓库
   - 使用 [`.gitignore`](file:///home/along/MyCode/wanjiabuluo/worklog/.gitignore) 忽略实际配置文件
   - 敏感信息使用环境变量或配置中心管理

2. **配置示例**：
   ```gitignore
   # .gitignore 配置
   application.yml
   bootstrap.yml
   src/main/resources/conf/env.properties
   src/main/resources/conf/service.properties
   ```

3. **配置模板**：
   - 提供 `env.properties.example` 和 `service.properties.example` 作为模板
   - 开发人员/运维人员复制模板并修改为实际配置文件
   - 填入实际配置信息（数据库密码、Redis 密码等）

4. **配置文件权限**（生产环境）：
   ```bash
   # 限制配置文件访问权限
   chmod 600 conf/env.properties
   chmod 600 conf/service.properties
   ```

---

## 10. 数据备份与恢复

### 10.1 备份策略

1. **增量备份**：每日凌晨 2:00 自动执行
2. **全量备份**：每周日凌晨 1:00 执行
3. **备份保留**：增量备份保留 7 天，全量备份保留 4 周

### 10.2 备份脚本示例

```bash
#!/bin/bash
# 数据库备份脚本

BACKUP_DIR="/backup/mysql"
DATE=$(date +%Y%m%d_%H%M%S)
DB_NAME="worklog"

# 全量备份
mysqldump -u root -p${MYSQL_PASSWORD} \
  --single-transaction \
  --routines \
  --triggers \
  ${DB_NAME} > ${BACKUP_DIR}/full_${DATE}.sql

# 压缩
gzip ${BACKUP_DIR}/full_${DATE}.sql
```

---

## 11. 监控与运维

### 11.1 监控指标

| 指标类型 | 监控项 | 阈值 |
|----------|--------|------|
| **系统指标** | CPU 使用率 | < 80% |
| | 内存使用率 | < 80% |
| | 磁盘使用率 | < 85% |
| **应用指标** | 接口响应时间 | < 1000ms |
| | 错误率 | < 1% |
| | QPS | 记录峰值 |
| **数据库指标** | 连接数 | < 80% |
| | 慢查询 | < 10/min |
| | 锁等待 | < 5s |

### 11.2 告警机制

1. **系统告警**：CPU/内存/磁盘超阈值
2. **应用告警**：接口错误率高、响应慢
3. **业务告警**：登录失败次数过多
4. **告警方式**：邮件 + 短信（紧急）

---

## 12. 风险与应对

### 12.1 技术风险

| 风险点 | 描述 | 应对策略 |
|--------|------|----------|
| **单点故障** | 单体应用，服务器故障导致全站不可用 | 1. 做好数据备份<br>2. 准备灾备服务器<br>3. 快速恢复流程 |
| **数据丢失** | 数据库故障或误操作 | 1. 每日自动备份<br>2. 采用逻辑删除<br>3. 主从复制（可选） |
| **性能瓶颈** | 并发量超预期 | 1. 增加缓存<br>2. 数据库读写分离<br>3. 升级服务器配置 |

### 12.2 业务风险

| 风险点 | 描述 | 应对策略 |
|--------|------|----------|
| **字数限制** | 2000 字可能不够用 | 1. V1.0 严格执行<br>2. 收集用户反馈<br>3. V2.0 评估是否支持附件 |
| **移动端体验** | Markdown 编辑体验差 | 1. 提供简化工具栏<br>2. 支持富文本模式<br>3. 优化键盘交互 |
| **权限管理** | 角色权限过于简单 | 1. V1.0 满足基本需求<br>2. V2.0 增加部门权限 |

---

## 13. 开发计划

### 13.1 开发阶段

| 阶段 | 时间 | 交付物 | 负责人 |
|------|------|--------|--------|
| **阶段一** | 第1月 | 数据库设计、后端框架搭建、认证模块 | 后端 |
| **阶段二** | 第2月 | 人员管理、日志管理、模板管理接口 | 后端 |
| **阶段三** | 第2-3月 | 管理后台前端开发 | 前端 |
| **阶段四** | 第3月 | 移动端 H5 开发 | 前端 |
| **阶段五** | 第3月 | 联调测试、性能优化、安全加固 | 全员 |
| **上线** | 第4月初 | 生产环境部署、用户培训 | 运维 |

### 13.2 里程碑

- **M1（第1月末）**：后端核心接口完成，Postman 测试通过
- **M2（第2月末）**：管理后台基本功能完成，内部试用
- **M3（第3月末）**：移动端完成，全功能测试通过
- **M4（第4月初）**：正式上线，全员推广

---

## 14. 附录

### 15.1 技术栈版本清单

| 技术 | 版本 | 说明 |
|------|------|------|
| JDK | 21 | LTS 版本 |
| Spring Boot | 3.2.x | 最新稳定版 |
| MyBatis-Plus | 3.5.x | 数据访问框架 |
| MySQL | 8.0.x | 数据库 |
| Redis | 7.x | 缓存 |
| Vue | 3.x | 前端框架 |
| Element Plus | 2.x | 管理后台 UI |
| Vant | 4.x | 移动端 UI |

### 15.2 相关文档

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

### 15.3 架构设计规范遵循说明

本项目严格遵循《架构设计规范》的各项要求：

| 规范项 | 遵循说明 | 文档位置 |
|--------|----------|----------|
| **模块目录结构** | data 目录统一存放 MyBatis-Plus 相关文件 | 3.2节 目录结构设计 |
| **DataService 命名** | 使用 XxxDataService/XxxDataServiceImpl 命名规范 | 3.2节、后端模块详细设计 |
| **分层职责** | Controller → Service → DataService → Mapper | 2.2节 应用分层架构 |
| **主键策略** | VARCHAR(20) 存储雪花算法生成的19位ID | 4.1节 数据库表设计 |
| **审计字段** | 统一包含 created_by、created_time、updated_by、updated_time、deleted | 4.1节 数据库表设计 |
| **日志配置** | app.log、sql.log、error.log 扁平目录结构 | 7.1节 日志配置 |
| **链路追踪** | 所有日志包含 traceId 和 spanId | 7.2节 链路追踪 |
| **API 设计** | RESTful 风格，统一 Result<T> 返回格式 | 5节 API 接口设计 |
| **前端 API 管理** | 独立 api 目录，禁止硬编码 URL | 前端详细设计文档 2.1节、3.1节 |
| **密码加密** | BCrypt 算法加密存储 | 6.3节 数据安全 |
| **Token 认证** | UUID Token + Redis，有效期24小时 | 6.1节 认证机制 |
| **架构演进** | 当前单体应用，未来微服务遵循 OpenFeign 规范 | 2.1节 整体架构 |
| **基础模块依赖** | 如抽取 common 模块，必须通过 Maven/Gradle 依赖 | 后端模块详细设计 1.1节 |

---

**文档审批**

| 角色 | 姓名 | 签字 | 日期 |
|------|------|------|------|
| 架构师 | ______ | ______ | ______ |
| 技术负责人 | ______ | ______ | ______ |
| 产品经理 | ______ | ______ | ______ |

**变更记录**

| 版本 | 日期 | 变更内容 | 变更人 |
|------|------|----------|--------|
| V1.0 | 2026-02-24 | 初稿完成 | ______ |