src/core/db/users/base_users.service.ts

@@ -14,13 +14,14 @@
  * - 搜索优化：搜索异常的特殊处理机制
  * 
  * 最近修改：
+ * - 2026-01-15: 代码规范优化 - 为保护方法补充@example示例 (修改者: moyin)
  * - 2026-01-07: 代码规范优化 - 完善注释规范，添加完整的文件头和方法注释
  * - 2026-01-07: 功能新增 - 添加敏感信息脱敏处理和结构化日志记录
  * 
  * @author moyin
- * @version 1.0.1
+ * @version 1.0.2
  * @since 2025-01-07
- * @lastModified 2026-01-07
+ * @lastModified 2026-01-15
  */
 
 import { Logger, ConflictException, NotFoundException, BadRequestException } from '@nestjs/common';
@@ -33,6 +34,12 @@ export abstract class BaseUsersService {
    * 
    * @param error 原始错误对象
    * @returns 格式化后的错误信息字符串
+   * 
+   * @example
+   * ```typescript
+   * const errorMsg = this.formatError(new Error('数据库连接失败'));
+   * // 返回: "数据库连接失败"
+   * ```
    */
   protected formatError(error: unknown): string {
     if (error instanceof Error) {
@@ -48,6 +55,15 @@ export abstract class BaseUsersService {
    * @param operation 操作名称
    * @param context 上下文信息
    * @throws 处理后的标准异常
+   * 
+   * @example
+   * ```typescript
+   * try {
+   *   // 业务操作
+   * } catch (error) {
+   *   this.handleServiceError(error, '创建用户', { username: 'test' });
+   * }
+   * ```
    */
   protected handleServiceError(error: unknown, operation: string, context?: Record<string, any>): never {
     const errorMessage = this.formatError(error);
@@ -78,6 +94,15 @@ export abstract class BaseUsersService {
    * @param operation 操作名称
    * @param context 上下文信息
    * @returns 空数组
+   * 
+   * @example
+   * ```typescript
+   * try {
+   *   // 搜索操作
+   * } catch (error) {
+   *   return this.handleSearchError(error, '搜索用户', { keyword: 'test' });
+   * }
+   * ```
    */
   protected handleSearchError(error: unknown, operation: string, context?: Record<string, any>): any[] {
     const errorMessage = this.formatError(error);
@@ -98,6 +123,11 @@ export abstract class BaseUsersService {
    * @param operation 操作名称
    * @param context 上下文信息
    * @param duration 操作耗时
+   * 
+   * @example
+   * ```typescript
+   * this.logSuccess('创建用户', { userId: '123', username: 'test' }, 50);
+   * ```
    */
   protected logSuccess(operation: string, context?: Record<string, any>, duration?: number): void {
     this.logger.log(`${operation}成功`, {
@@ -113,6 +143,11 @@ export abstract class BaseUsersService {
    * 
    * @param operation 操作名称
    * @param context 上下文信息
+   * 
+   * @example
+   * ```typescript
+   * this.logStart('创建用户', { username: 'test' });
+   * ```
    */
   protected logStart(operation: string, context?: Record<string, any>): void {
     this.logger.log(`开始${operation}`, {
@@ -127,6 +162,16 @@ export abstract class BaseUsersService {
    * 
    * @param data 原始数据
    * @returns 脱敏后的数据
+   * 
+   * @example
+   * ```typescript
+   * const sanitized = this.sanitizeLogData({
+   *   email: 'test@example.com',
+   *   phone: '13800138000',
+   *   password_hash: 'secret'
+   * });
+   * // 返回: { email: 'te***@example.com', phone: '138****00', password_hash: '[REDACTED]' }
+   * ```
    */
   protected sanitizeLogData(data: Record<string, any>): Record<string, any> {
     const sanitized = { ...data };

src/core/db/users/users.constants.ts

@@ -6,13 +6,19 @@
  * - 避免魔法数字，提高代码可维护性
  * - 集中管理配置参数
  * 
+ * 职责分离：
+ * - 常量定义：用户角色、字段限制、查询限制等常量值
+ * - 错误消息：统一的错误消息定义和管理
+ * - 工具类：性能监控和验证工具的封装
+ * 
  * 最近修改：
+ * - 2026-01-15: 代码规范优化 - 补充职责分离描述 (修改者: moyin)
  * - 2026-01-09: 代码质量优化 - 提取魔法数字为常量定义 (修改者: moyin)
  * 
  * @author moyin
- * @version 1.0.0
+ * @version 1.0.1
  * @since 2026-01-09
- * @lastModified 2026-01-09
+ * @lastModified 2026-01-15
  */
 
 import { ValidationError } from 'class-validator';