docs(login-log): 添加用户登录日志功能文档

- 编写用户登录日志功能说明,包括查询和详情查看
- 详细描述用户界面设计,涵盖搜索区域、操作按钮和数据表格
- 说明请求与响应的数据模型结构及字段定义
- 介绍API接口,包括列表查询和详情获取
- 分析主要Vue组件实现及其状态管理与交互流程
- 绘制交互流程图及组件调用序列图方便理解
- 引用相关代码文件链接促进文档的可追溯性
This commit is contained in:
danial
2025-11-14 23:15:29 +08:00
parent d1cae61cdd
commit efe6f3ec2b
3 changed files with 1588 additions and 985 deletions

View File

@@ -0,0 +1,210 @@
# 京东Cookie管理
<cite>
**本文档引用文件**
- [index.vue](file://src/views/jd-order/cookie/index.vue)
- [jdcookie-management-api.ts](file://src/api/generated/apis/jdcookie-management-api.ts)
- [card-jd-account.ts](file://src/api/card-jd-account.ts)
</cite>
## 目录
1. [项目结构](#项目结构)
2. [核心组件分析](#核心组件分析)
3. [架构概述](#架构概述)
4. [详细组件分析](#详细组件分析)
5. [依赖分析](#依赖分析)
## 项目结构
京东Cookie管理功能主要位于前端项目的 `src/views/jd-order/cookie/` 目录下,其核心文件为 `index.vue`该文件实现了Cookie管理的用户界面和交互逻辑。该功能依赖于API生成层和业务逻辑层进行数据交互。
**Diagram sources**
- [index.vue](file://src/views/jd-order/cookie/index.vue#L1-L472)
```mermaid
graph TD
A[京东Cookie管理界面] --> B[API客户端]
B --> C[jdcookie-management-api.ts]
C --> D[后端服务]
A --> E[业务逻辑层]
E --> F[card-jd-account.ts]
```
**Section sources**
- [index.vue](file://src/views/jd-order/cookie/index.vue#L1-L472)
## 核心组件分析
京东Cookie管理的核心功能由 `index.vue` 组件实现该组件提供了完整的Cookie生命周期管理功能包括查询、添加、编辑、删除和批量操作。该组件通过 `jdCookieClient` 实例与后端API进行通信实现了数据的增删改查。
**Section sources**
- [index.vue](file://src/views/jd-order/cookie/index.vue#L186)
- [jdcookie-management-api.ts](file://src/api/generated/apis/jdcookie-management-api.ts#L1189-L1355)
## 架构概述
京东Cookie管理功能采用典型的前后端分离架构。前端通过Vue 3框架构建用户界面利用Axios库与后端API进行异步通信。API接口由OpenAPI Generator自动生成确保了类型安全和代码一致性。整体架构分为三层视图层、业务逻辑层和API客户端层。
```mermaid
graph TB
subgraph "前端"
A[视图层] --> B[业务逻辑层]
B --> C[API客户端层]
end
C --> D[后端服务]
```
**Diagram sources**
- [index.vue](file://src/views/jd-order/cookie/index.vue#L186)
- [jdcookie-management-api.ts](file://src/api/generated/apis/jdcookie-management-api.ts#L1189-L1355)
## 详细组件分析
### Cookie管理界面分析
Cookie管理界面是一个功能完整的CRUD创建、读取、更新、删除操作界面提供了丰富的用户交互功能。
#### 界面功能分析
```mermaid
flowchart TD
A[页面加载] --> B[初始化分页参数]
B --> C[调用API获取Cookie列表]
C --> D[渲染表格数据]
D --> E{用户操作}
E --> F[搜索]
E --> G[添加]
E --> H[编辑]
E --> I[删除]
E --> J[批量删除失效Cookie]
F --> K[调用查询API]
G --> L[打开添加弹窗]
H --> M[打开编辑弹窗]
I --> N[调用删除API]
J --> O[调用批量删除API]
```
**Diagram sources**
- [index.vue](file://src/views/jd-order/cookie/index.vue#L306-L323)
- [index.vue](file://src/views/jd-order/cookie/index.vue#L379-L386)
- [index.vue](file://src/views/jd-order/cookie/index.vue#L405-L465)
#### API接口分析
```mermaid
classDiagram
class JDCookieManagementApi {
+apiJdCookieAccountListGet(requestParameters, options) AxiosPromise~KamiApiJdCookieV1ListAccountRes~
+apiJdCookieAccountGetGet(requestParameters, options) AxiosPromise~KamiApiJdCookieV1GetAccountRes~
+apiJdCookieAccountCreatePost(requestParameters, options) AxiosPromise~KamiApiJdCookieV1CreateAccountRes~
+apiJdCookieAccountUpdatePut(requestParameters, options) AxiosPromise~object~
+apiJdCookieAccountDeleteDelete(requestParameters, options) AxiosPromise~object~
+apiJdCookieAccountDeleteInvalidDelete(options) AxiosPromise~KamiApiJdCookieV1DeleteInvalidRes~
+apiJdCookieAccountValidatePost(requestParameters, options) AxiosPromise~KamiApiJdCookieV1ValidateCookieRes~
+apiJdCookieAccountBatchCreatePost(requestParameters, options) AxiosPromise~KamiApiJdCookieV1BatchCreateRes~
+apiJdCookieAccountBatchValidatePost(requestParameters, options) AxiosPromise~KamiApiJdCookieV1BatchValidateCookieRes~
}
class KamiApiJdCookieV1ListAccountRes {
+list? KamiApiJdCookieV1CookieAccountInfo[]
+total? number
}
class KamiApiJdCookieV1CookieAccountInfo {
+id? number
+cookieId? string
+cookieValue? string
+accountName? string
+status? number
+failureCount? number
+lastUsedAt? string
+suspendUntil? string
+createdAt? string
+updatedAt? string
+deletedAt? string
+remark? string
}
JDCookieManagementApi --> KamiApiJdCookieV1ListAccountRes : "返回"
KamiApiJdCookieV1ListAccountRes --> KamiApiJdCookieV1CookieAccountInfo : "包含"
```
**Diagram sources**
- [jdcookie-management-api.ts](file://src/api/generated/apis/jdcookie-management-api.ts#L1076-L1079)
- [jdcookie-management-api.ts](file://src/api/generated/models/kami-api-jd-cookie-v1-list-account-res.ts#L18-L27)
- [jdcookie-management-api.ts](file://src/api/generated/models/kami-api-jd-cookie-v1-cookie-account-info.ts#L14-L63)
**Section sources**
- [index.vue](file://src/views/jd-order/cookie/index.vue#L306-L323)
- [jdcookie-management-api.ts](file://src/api/generated/apis/jdcookie-management-api.ts#L1076-L1079)
### 业务逻辑层分析
业务逻辑层封装了与京东Cookie相关的业务操作提供了更高级别的API调用接口。
#### 业务逻辑接口分析
```mermaid
classDiagram
class card-jd-account {
+addJDCard(data) Promise
+updateJDCard(data) Promise
+deleteJDCard(params) Promise
+updateJDCardStatus(data) Promise
+queryJDCardList(params) Promise~CommonPageResult~JdCardUpdateRecord~~
+queryJDAccountWalletList(params) Promise~CommonPageResult~JDAccountListItem~~
+refreshJDCardStatus(data) Promise
+downloadJDCardData() Promise
+batchAdd(data) Promise
+downloadDataList() Promise
}
class JdCardUpdateRecord {
+name string
+cookie string
+status number
+maxAmountLimit number
+wsKey? string
+remark? string
+id string
}
card-jd-account --> JdCardUpdateRecord : "使用"
```
**Diagram sources**
- [card-jd-account.ts](file://src/api/card-jd-account.ts#L31-L110)
- [card-jd-account.ts](file://src/api/card-jd-account.ts#L8-L19)
**Section sources**
- [card-jd-account.ts](file://src/api/card-jd-account.ts#L31-L110)
## 依赖分析
京东Cookie管理功能依赖于多个前端组件和API服务形成了清晰的依赖关系。
```mermaid
graph TD
A[index.vue] --> B[jdcookie-management-api.ts]
A --> C[card-jd-account.ts]
B --> D[axios]
C --> D[axios]
A --> E[arco-design]
A --> F[vue]
```
**Diagram sources**
- [index.vue](file://src/views/jd-order/cookie/index.vue#L186)
- [index.vue](file://src/views/jd-order/cookie/index.vue#L181)
- [card-jd-account.ts](file://src/api/card-jd-account.ts#L1)
**Section sources**
- [index.vue](file://src/views/jd-order/cookie/index.vue#L186)
- [card-jd-account.ts](file://src/api/card-jd-account.ts#L1)

View File

@@ -0,0 +1,321 @@
# 用户登录日志
<cite>
**Referenced Files in This Document**
- [index.vue](file://src/views/user-center/login-log/index.vue)
- [detail-modal.vue](file://src/views/user-center/login-log/components/detail-modal.vue)
- [kami-api-sys-user-login-log-v1-login-log-query-req.ts](file://src/api/generated/models/kami-api-sys-user-login-log-v1-login-log-query-req.ts)
- [kami-api-sys-user-login-log-v1-login-log-query-res.ts](file://src/api/generated/models/kami-api-sys-user-login-log-v1-login-log-query-res.ts)
- [kami-internal-model-entity-v1-sys-user-login-log.ts](file://src/api/generated/models/kami-internal-model-entity-v1-sys-user-login-log.ts)
- [default-api.ts](file://src/api/generated/apis/default-api.ts)
</cite>
## 目录
1. [简介](#简介)
2. [功能概述](#功能概述)
3. [用户界面](#用户界面)
4. [数据模型](#数据模型)
5. [API接口](#api接口)
6. [组件分析](#组件分析)
7. [交互流程](#交互流程)
## 简介
用户登录日志功能为系统管理员提供了查看和管理用户登录历史的界面。该功能允许管理员通过多种条件查询用户的登录记录,包括登录名、登录状态和时间范围等,并可以查看单条登录记录的详细信息。
**Section sources**
- [index.vue](file://src/views/user-center/login-log/index.vue#L1-L335)
## 功能概述
用户登录日志功能主要包含两个核心部分登录日志列表展示和登录日志详情查看。管理员可以通过搜索表单筛选登录记录系统会根据筛选条件展示相应的登录日志列表。每条记录包含登录名、IP地址、登录地点、浏览器、操作系统、登录状态等关键信息。点击"查看详情"按钮可以查看某条登录记录的完整详细信息。
该功能支持分页显示每页可显示10、20、50或100条记录并提供了搜索、重置和分页导航等操作功能。搜索表单支持登录名模糊匹配、登录状态筛选登录成功/登录失败)以及时间范围选择,其中时间选择器提供了"今天"、"昨天"、"最近7天"和"最近30天"等快捷选项。
**Section sources**
- [index.vue](file://src/views/user-center/login-log/index.vue#L1-L335)
## 用户界面
用户登录日志界面采用标准的列表页面布局,包含搜索区域、操作按钮和数据表格三部分。
### 搜索区域
搜索区域包含三个字段:
- **登录名**:文本输入框,用于输入要查询的用户名
- **登录状态**:下拉选择框,可选择"登录成功"或"登录失败"
- **登录时间**:日期范围选择器,支持选择开始时间和结束时间
### 操作按钮
操作区域包含两个按钮:
- **搜索**:根据当前搜索条件查询登录日志
- **重置**:清空所有搜索条件并重新加载数据
### 数据表格
数据表格展示登录日志的核心信息,包含以下列:
- 序号
- 登录名
- 登录IP
- 登录地点
- 浏览器带tooltip显示完整的User Agent
- 操作系统
- 登录状态(以标签形式显示,绿色表示成功,红色表示失败)
- 登录时长
- 登录时间
- 操作(包含"查看详情"按钮)
**Section sources**
- [index.vue](file://src/views/user-center/login-log/index.vue#L1-L335)
## 数据模型
用户登录日志功能涉及多个数据模型,这些模型定义了前端与后端交互的数据结构。
### 请求模型
`KamiApiSysUserLoginLogV1LoginLogQueryReq` 接口定义了查询登录日志的请求参数:
```typescript
export interface KamiApiSysUserLoginLogV1LoginLogQueryReq {
userId?: string;
loginName?: string;
status?: number;
startTime?: string;
endTime?: string;
current: number;
pageSize: KamiApiSysUserLoginLogV1LoginLogQueryReqPageSizeEnum;
}
```
其中 `pageSize` 枚举定义了可选的每页显示数量:
```typescript
export enum KamiApiSysUserLoginLogV1LoginLogQueryReqPageSizeEnum {
NUMBER_5 = 5,
NUMBER_10 = 10,
NUMBER_15 = 15,
NUMBER_20 = 20,
NUMBER_50 = 50,
NUMBER_100 = 100
}
```
### 响应模型
`KamiApiSysUserLoginLogV1LoginLogQueryRes` 接口定义了查询登录日志的响应数据结构:
```typescript
export interface KamiApiSysUserLoginLogV1LoginLogQueryRes {
total?: number;
list?: Array<KamiInternalModelEntityV1SysUserLoginLog>;
}
```
### 登录日志实体
`KamiInternalModelEntityV1SysUserLoginLog` 接口定义了单条登录日志的详细信息:
```typescript
export interface KamiInternalModelEntityV1SysUserLoginLog {
id?: number;
userId?: string;
loginName?: string;
ipAddr?: string;
loginLocation?: string;
userAgent?: string;
browser?: string;
os?: string;
createdAt?: string;
status?: number;
message?: string;
loginTime?: string;
module?: string;
}
```
**Section sources**
- [kami-api-sys-user-login-log-v1-login-log-query-req.ts](file://src/api/generated/models/kami-api-sys-user-login-log-v1-login-log-query-req.ts#L14-L52)
- [kami-api-sys-user-login-log-v1-login-log-query-res.ts](file://src/api/generated/models/kami-api-sys-user-login-log-v1-login-log-query-res.ts#L19-L21)
- [kami-internal-model-entity-v1-sys-user-login-log.ts](file://src/api/generated/models/kami-internal-model-entity-v1-sys-user-login-log.ts#L15-L47)
## API接口
用户登录日志功能通过两个API接口与后端进行数据交互。
### 查询登录日志列表
`apiSysUserLoginLogListGet` 接口用于获取登录日志列表数据。该接口接受分页参数和筛选条件,返回分页的登录日志数据。
**接口参数:**
- `current`: 当前页码
- `pageSize`: 每页数量
- `userId`: 用户ID可选
- `loginName`: 登录名(可选)
- `status`: 登录状态(可选)
- `startTime`: 开始时间(可选)
- `endTime`: 结束时间(可选)
**返回数据:**
- `total`: 总记录数
- `list`: 登录日志数据列表
### 查询登录日志详情
`apiSysUserLoginLogDetailGet` 接口用于获取单条登录日志的详细信息。该接口仅需要传入登录日志的ID即可获取完整的详细信息。
**接口参数:**
- `id`: 登录日志ID
**返回数据:**
- `data`: 登录日志详细信息
**Section sources**
- [default-api.ts](file://src/api/generated/apis/default-api.ts#L29456-L29472)
- [default-api.ts](file://src/api/generated/apis/default-api.ts#L29440-L29447)
## 组件分析
用户登录日志功能由两个主要Vue组件构成主列表组件和详情模态框组件。
### 主列表组件 (index.vue)
主列表组件负责展示登录日志列表和处理用户交互。该组件包含以下核心功能:
- **状态管理**:使用`ref``reactive`定义组件状态,包括搜索表单数据、分页信息、表格数据和加载状态
- **数据获取**`fetchData`方法负责调用API获取登录日志数据并处理响应结果
- **搜索功能**`search`方法重置页码并执行新的搜索
- **重置功能**`reset`方法清空所有搜索条件并重新加载数据
- **分页处理**`onPageChange``onPageSizeChange`方法处理分页变化
- **详情查看**`showDetail`方法在用户点击"查看详情"时触发,显示详情模态框
```mermaid
flowchart TD
A[组件初始化] --> B[获取数据]
B --> C{数据获取成功?}
C --> |是| D[更新表格数据]
C --> |否| E[显示错误消息]
D --> F[显示数据]
E --> F
F --> G[用户交互]
G --> H{用户操作}
H --> |搜索| I[执行搜索]
H --> |重置| J[重置表单]
H --> |分页| K[更新分页]
H --> |查看详情| L[显示详情模态框]
I --> B
J --> B
K --> B
L --> M[详情模态框]
```
**Diagram sources**
- [index.vue](file://src/views/user-center/login-log/index.vue#L268-L333)
**Section sources**
- [index.vue](file://src/views/user-center/login-log/index.vue#L123-L335)
### 详情模态框组件 (detail-modal.vue)
详情模态框组件负责展示单条登录日志的详细信息。该组件的主要特点包括:
- **属性接收**:通过`props`接收`visible`(显示状态)和`loginLogId`登录日志ID两个参数
- **事件发射**:通过`emit`发射`update:visible`事件来控制模态框的显示和隐藏
- **数据获取**`fetchDetail`方法根据传入的ID获取登录日志详情
- **数据格式化**`formatDateTime`方法将ISO格式的日期时间转换为本地化显示格式
- **生命周期监听**:使用`watch`监听`visible`属性的变化,当模态框显示时自动获取详情数据
```mermaid
classDiagram
class DetailModal {
+visible : boolean
+loginLogId : number
-loading : boolean
-loginLogData : KamiInternalModelEntityV1SysUserLoginLog
+fetchDetail(id : number) : Promise~void~
+formatDateTime(dateTime : string) : string
+handleCancel() : void
}
DetailModal --> KamiInternalModelEntityV1SysUserLoginLog : "显示"
DetailModal --> apiClient : "调用"
```
**Diagram sources**
- [detail-modal.vue](file://src/views/user-center/login-log/components/detail-modal.vue#L87-L166)
**Section sources**
- [detail-modal.vue](file://src/views/user-center/login-log/components/detail-modal.vue#L87-L166)
## 交互流程
用户登录日志功能的交互流程如下:
1. **页面初始化**:组件挂载时自动调用`fetchData`方法获取第一页的登录日志数据
2. **搜索流程**
- 用户填写搜索条件并点击"搜索"按钮
- 执行`search`方法重置页码为1并调用`fetchData`
- 根据当前表单值构建请求参数
- 调用`apiSysUserLoginLogListGet`接口获取数据
- 更新表格数据和分页信息
3. **重置流程**
- 用户点击"重置"按钮
- 执行`reset`方法,清空所有搜索条件
- 调用`fetchData`重新加载数据
4. **分页流程**
- 用户切换页码或每页数量
- 触发`onPageChange``onPageSizeChange`方法
- 调用`fetchData`获取新页码的数据
5. **查看详情流程**
- 用户点击某条记录的"查看详情"按钮
- 执行`showDetail`方法,设置`selectedLoginLogId`并显示详情模态框
- 详情模态框组件监听到`visible`变为true调用`fetchDetail`获取详情数据
- 在模态框中展示详细信息
```mermaid
sequenceDiagram
participant User as 用户
participant List as 主列表组件
participant Detail as 详情模态框
participant API as 后端API
User->>List : 页面加载
List->>API : apiSysUserLoginLogListGet(current=1, pageSize=20)
API-->>List : 返回第一页数据
List->>User : 显示登录日志列表
User->>List : 输入搜索条件并点击搜索
List->>API : apiSysUserLoginLogListGet(搜索参数)
API-->>List : 返回匹配的数据
List->>User : 更新列表显示
User->>List : 点击"查看详情"
List->>Detail : 显示模态框传入ID
Detail->>API : apiSysUserLoginLogDetailGet(id)
API-->>Detail : 返回详细信息
Detail->>User : 显示详细信息
```
**Diagram sources**
- [index.vue](file://src/views/user-center/login-log/index.vue#L268-L333)
- [detail-modal.vue](file://src/views/user-center/login-log/components/detail-modal.vue#L110-L129)
**Section sources**
- [index.vue](file://src/views/user-center/login-log/index.vue#L268-L333)
- [detail-modal.vue](file://src/views/user-center/login-log/components/detail-modal.vue#L110-L129)

File diff suppressed because one or more lines are too long