jsharness 1.0.0

package/.harness/dev-map/backend/conventions-java.md

@@ -0,0 +1,471 @@
+# 后端分区 — Java 编码惯例 (conventions-java)
+
+> **来源**: `files/java-backend-coding-standards/SKILL.md` (JSCICD 项目后端 Java 规范)
+> **归档日期**: 2026-05-21
+> **技术栈**: Spring Boot 3.2.12 / JDK 21 (虚拟线程) / MySQL 8.0 / Redis 5.x / MyBatis-Plus
+
+## 技术栈版本速查
+
+| 组件 | 推荐版本 | 说明 |
+|------|---------|------|
+| Spring Boot | 3.2.x | 主框架 |
+| JDK | 21 | 虚拟线程支持 |
+| MySQL | 8.0+ | 数据库 |
+| Redis | 5.x / 6.x | 缓存 |
+| MyBatis-Plus | 3.5.x | ORM 框架 |
+| Lombok | 1.18.x | 注解简化 |
+| Redisson | 3.x | 分布式锁/Redis 客户端 |
+| Hutool | 5.x | 工具库（按需使用）|
+| Knife4j/Swagger | OpenAPI 3 | API 文档 |
+| Nacos | 2.x | 配置中心 + 注册中心 |
+
+---
+
+## Maven 四层模块详细结构
+
+```
+jscicd-project/
+├── pom.xml                          # 父 POM（统一依赖版本管理）
+├── app/                             # 启动入口模块
+│   ├── pom.xml
+│   └── src/main/java/com/jieshun/
+│       └── app/
+│           ├── JscicdApplication.java    # @SpringBootApplication
+│           └── config/                     # 启动配置类
+│               └── WebMvcConfig.java
+│
+├── domain/                          # 业务核心模块
+│   ├── pom.xml
+│   └── src/main/java/com/jieshun/
+│       └── domain/
+│           ├── controller/               # Controller 层
+│           │   ├── admin/                 # 后台管理 Controller
+│           │   │   └── UserController.java
+│           │   └── app/                   # 用户侧 Controller
+│           │       └── AppUserController.java
+│           ├── service/                  # Service 层
+│           │   ├── UserService.java        # 接口定义
+│           │   └── impl/                  # 实现类子包
+│           │       └── UserServiceImpl.java
+│           ├── mapper/                   # Mapper 层
+│           │   ├── UserMapper.java         # Mapper 接口
+│           │   └── xml/                    # XML 映射文件目录
+│           │       └── UserMapper.xml
+│           ├── data/                     # 数据对象层
+│           │   ├── entity/                # 数据库实体
+│           │   │   └── UserDO.java
+│           │   ├── vo/                    # 视图对象
+│           │   │   ├── UserVO.java
+│           │   │   ├── UserRespVO.java     # 响应对象
+│           │   │   └── UserCreateReqVO.java # 请求对象
+│           │   └── dto/                    # 数据传输对象
+│           │       └── UserDTO.java
+│           └── enums/                    # 枚举定义
+│               └── UserStatusEnum.java
+│
+├── integration/                     # 第三方集成模块
+│   ├── pom.xml
+│   └── src/main/java/com/jieshun/integration/
+│       ├── client/                    # 外部 API 客户端
+│       │   └── sms/SmsClient.java      # 短信服务客户端
+│       └── mq/                        # 消息队列
+│           └── producer/MqProducer.java
+│
+└── common/                          # 公共工具模块
+    ├── pom.xml
+    └── src/main/java/com/jieshun/common/
+        ├── constant/                  # 常量
+        │   ├── ErrorCodeConstants.java   # 错误码枚举
+        │   └── RedisKeyConstants.java     # Redis Key 常量
+        ├── exception/                # 异常定义
+        │   ├── ServiceException.java
+        │   └── JscicdBizException.java    # 业务异常基类
+        ├── util/                      # 工具类
+        │   └── ObjectUtils.java
+        └── enums/                     # 通用枚举
+            └── CommonStatusEnum.java
+```
+
+---
+
+## 标准代码模板
+
+### Controller 标准模板
+
+```java
+/**
+ * 用户管理 Controller
+ *
+ * @description 提供用户 CRUD 和分页查询接口
+ * @author jscicd-backend-team
+ */
+@RestController
+@RequestMapping("/api/v1/user")
+@RequiredArgsConstructor
+@Tag(name = "用户管理")
+public class UserController {
+
+    private final UserService userService;
+
+    @PostMapping("/create")
+    @Operation(summary = "创建用户")
+    public CommonResult<Long> create(@Valid @RequestBody UserCreateReqVO reqVO) {
+        return success(userService.createUser(reqVO));
+    }
+
+    @PostMapping("/update")
+    @Operation(summary = "更新用户")
+    public CommonResult<Boolean> update(@Valid @RequestBody UserUpdateReqVO reqVO) {
+        userService.updateUser(reqVO);
+        return success(true);
+    }
+
+    @PostMapping("/delete")
+    @Operation(summary = "删除用户")
+    public CommonResult<Boolean> delete(@RequestParam("id") Long id) {
+        userService.deleteUser(id);
+        return success(true);
+    }
+
+    @PostMapping("/page")
+    @Operation(summary = "分页查询用户")
+    public CommonResult<PageResult<UserRespVO>> page(@Valid UserPageReqVO reqVO) {
+        return success(userService.getUserPage(reqVO));
+    }
+
+    @GetMapping("/get")
+    @Operation(summary = "获取用户详情")
+    public CommonResult<UserRespVO> get(@RequestParam("id") Long id) {
+        return success(userService.getUser(id));
+    }
+}
+```
+
+**Controller 要点**:
+- `@RestController` + `@RequestMapping` 定义路由前缀
+- `@RequiredArgsConstructor` 构造器注入
+- HTTP 方法统一用 `@PostMapping`（RESTful 风格但 POST 优先）
+- 参数校验使用 JSR303：`@Valid` / `@Validated`
+- 返回值统一包装为 `CommonResult<T>`
+- Swagger/OpenAPI 注解：`@Tag`, `@Operation`
+
+### Service 接口 + Impl 标准模板
+
+```java
+// ========== 接口 ==========
+public interface UserService {
+    /**
+     * 创建用户
+     *
+     * @param reqVO 创建请求参数
+     * @return 用户 ID
+     */
+    Long createUser(UserCreateReqVO reqVO);
+
+    /**
+     * 更新用户信息
+     */
+    void updateUser(UserUpdateReqVO reqVO);
+
+    /**
+     * 删除用户
+     */
+    void deleteUser(Long id);
+
+    /**
+     * 分页查询用户
+     */
+    PageResult<UserRespVO> getUserPage(UserPageReqVO reqVO);
+
+    /**
+     * 获取用户详情
+     */
+    UserRespVO getUser(Long id);
+}
+
+// ========== 实现类 ==========
+@Service
+@RequiredArgsConstructor
+@Slf4j
+public class UserServiceImpl implements UserService {
+
+    private final UserMapper userMapper;
+    private final RedisKeyConstants redisKeys;
+
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public Long createUser(UserCreateReqVO reqVO) {
+        // 1. 参数校验与转换
+        // TODO: 校验手机号唯一性
+        UserDO entity = UserConvert.INSTANCE.convert(reqVO);
+
+        // 2. 业务逻辑编排
+        // （如：发送欢迎短信 — 在事务外调用）
+
+        // 3. 数据持久化
+        userMapper.insert(entity);
+
+        // 4. 返回结果
+        return entity.getId();
+    }
+
+    @Override
+    public PageResult<UserRespVO> getUserPage(UserPageReqVO reqVO) {
+        // 分页参数设置
+        PageHelper.startPage(reqVO.getPageNo(), reqVO.getPageSize());
+
+        // 执行查询
+        List<UserDO> list = userMapper.selectList(reqVO);
+
+        // 转换返回
+        return new PageResult<>(UserConvert.INSTANCE.convertList(list),
+            new PageInfo<>(list).getTotal());
+    }
+}
+```
+
+**Service 要点**:
+- 接口和实现分离，实现放在 `service/impl/` 子包
+- 使用 `@RequiredArgsConstructor` + Lombok 构造注入
+- `@Slf4j` 日志注解
+- 事务方法加 `@Transactional(rollbackFor = Exception.class)`
+- 外部调用（HTTP/消息）放事务外
+
+### Mapper + XML 标准模板
+
+```java
+// Mapper 接口
+public interface UserMapper {
+    List<UserDO> selectList(@Param("reqVO") UserPageReqVO reqVO);
+    UserDO selectById(@Param("id") Long id);
+    void insert(@Param("entity") UserDO entity);
+    void updateById(@Param("entity") UserDO entity);
+    void deleteById(@Param("id") Long id);
+}
+```
+
+```xml
+<!-- XML 映射文件: resources/mapper/user/UserMapper.xml -->
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
+    "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
+<mapper namespace="com.jieshun.domain.mapper.UserMapper">
+
+    <sql id="selectFields">
+        id, username, nickname, mobile, email, status,
+        create_time, update_time, deleted
+    </sql>
+
+    <select id="selectList" resultType="com.jieshun.domain.data.entity.UserDO">
+        SELECT <include refid="selectFields"/>
+        FROM system_users
+        <where>
+            <if test="reqVO.username != null and reqVO.username != ''">
+                AND username LIKE CONCAT('%', #{reqVO.username}, '%')
+            </if>
+            <if test="reqVO.status != null">
+                AND status = #{reqVO.status}
+            </if>
+            AND deleted = 0
+        </where>
+        ORDER BY create_time DESC
+    </select>
+
+</mapper>
+```
+
+**Mapper 要点**:
+- 纯接口，不继承 BaseMapper
+- SQL 全部写在 XML 中，使用 `<sql>` 复制公共字段
+- 参数绑定必须用 `#{}`，禁止 `${}`
+- 分页由拦截器自动处理，XML 中不写 LIMIT
+
+### Entity/DTO/VO 定义模板
+
+```java
+// ========== Entity ==========
+@Data
+@TableName("system_users")
+public class UserDO {
+    /** 用户 ID */
+    private Long id;
+    /** 用户名 */
+    private String username;
+    /** 昵称 */
+    private String nickname;
+    /** 手机号（SM4 加密存储）*/
+    private String mobile;
+    /** 邮箱 */
+    private String email;
+    /** 状态（0=正常 1=停用）*/
+    private Integer status;
+    /** 创建时间 */
+    private LocalDateTime createTime;
+    /** 更新时间 */
+    private LocalDateTime updateTime;
+    /** 是否删除 */
+    private Boolean deleted;
+}
+
+// ========== ReqVO ==========
+@Data
+public class UserCreateReqVO {
+    @NotBlank(message = "用户名不能为空")
+    @Size(min = 2, max = 20, message = "用户名长度为 2-20 位")
+    private String username;
+
+    @NotBlank(message = "手机号不能为空")
+    @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不正确")
+    private String mobile;
+
+    private String nickname;
+}
+
+// ========== RespVO ==========
+@Data
+public class UserRespVO {
+    private Long id;
+    private String username;
+    private String nickname;
+
+    /** 手机号脱敏显示 */
+    private String mobile;  // 格式: 138****1234
+
+    private Integer status;
+    private LocalDateTime createTime;
+}
+```
+
+### 异常处理标准模板
+
+```java
+// ========== 统一异常处理器 ==========
+@RestControllerAdvice
+@Slf4j
+public class GlobalExceptionHandler {
+
+    /** 业务异常 — 直接透传错误信息 */
+    @ExceptionHandler(JscicdBizException.class)
+    public CommonResult<?> handleBizException(JscicdBizException e) {
+        log.warn("[handleBizException][code({})message({})]", e.getCode(), e.getMessage());
+        return CommonResult.error(e.getCode(), e.getMessage());
+    }
+
+    /** 系统异常 — 记录日志 + 返回通用错误信息 */
+    @ExceptionHandler(Exception.class)
+    public CommonResult<?> handleException(Exception e) {
+        log.error("[handleException]", e);
+        return CommonResult.error(ErrorCode.SYSTEM_ERROR.getCode(),
+                                 ErrorCode SYSTEM_ERROR.getMessage());
+    }
+}
+
+// ========== 业务异常抛出 ==========
+try {
+    // 业务逻辑
+} catch (SpecificBusinessException e) {
+    log.warn("[createUser]业务异常: context={}", context, e);
+    throw e;  // 向上抛出，由全局处理器统一处理
+} catch (Exception e) {
+    log.error("[createUser]系统异常: context={}", context, e);
+    throw new SystemException(ErrorCode.SYSTEM_ERROR);
+}
+```
+
+---
+
+## 错误码分配表
+
+| 模块 | 前缀 | 错误码范围 | 示例 |
+|------|------|-----------|------|
+| 用户模块 | USER_ | 1000-1999 | `USER_NOT_FOUND`=1001, `MOBILE_EXISTS`=1002 |
+| 权限模块 | AUTH_ | 2000-2999 | `AUTH_UNAUTHORIZED`=2001, `FORBIDDEN`=2003 |
+| 内容模块 | CONTENT_ | 3000-3999 | |
+| 订单模块 | ORDER_ | 4000-4999 | |
+| 支付模块 | PAYMENT_ | 5000-5999 | |
+| 文件模块 | FILE_ | 6000-6999 | |
+| 系统模块 | SYS_ | 9000-9999 | `SYSTEM_ERROR`=9999, `PARAM_INVALID`=9001 |
+
+```java
+/** 错误码常量示例 */
+public interface ErrorCodeConstants {
+
+    ErrorCode USER_NOT_FOUND = new ErrorCode(1001, "用户不存在");
+    ErrorCode MOBILE_EXISTS = new ErrorCode(1002, "手机号已被注册");
+    ErrorCode AUTH_TOKEN_EXPIRED = new ErrorCode(2001, "登录已过期");
+    ErrorCode SYSTEM_ERROR = new ErrorCode(9999, "系统繁忙，请稍后重试");
+}
+```
+
+---
+
+## Redis Key 命名约定表
+
+| 用途 | Key 模式 | TTL | 示例 |
+|------|---------|-----|------|
+| 登录 Token | `user:login:token:{userId}` | 7天 | `user:login:token:1001` |
+| 验证码 | `user:captcha:{mobile}:{scene}` | 5分钟 | `user:captcha:13800138000:LOGIN` |
+| 用户缓存 | `cache:user:info:{userId}` | 30分钟 | `cache:user:info:1001` |
+| 接口限流 | `limit:{api}:{ip}:{minute}` | 60秒 | `limit:/api/user/create:192.168.1.1:202401011200` |
+| 分布式锁 | `lock:{business}:{key}` | 自动释放 | `lock:order:create:ORD20240101001` |
+
+```java
+/** Redis Key 常量类 */
+public final class RedisKeyConstants {
+    private RedisKeyConstants() {}
+
+    public static final String USER_LOGIN_TOKEN = "user:login:token:%s";
+    public static final String USER_CAPTCHA = "user:captcha:%s:%s";
+    public static final String CACHE_USER_INFO = "cache:user:info:%s";
+
+    // TTL 定义（秒）
+    public static final long TOKEN_EXPIRE_SECONDS = 7 * 24 * 3600L;  // 7 天
+    public static final long CAPTCHA_EXPIRE_SECONDS = 300L;          // 5 分钟
+    public static final long CACHE_EXPIRE_SECONDS = 1800L;           // 30 分钟
+}
+```
+
+---
+
+## 数据库设计约定
+
+| 规则 | 要求 | 说明 |
+|------|------|------|
+| 字符集 | utf8mb4 | 支持完整 Unicode（含 emoji）|
+| 引擎 | InnoDB | 默认引擎 |
+| 禁止外键 | 不在数据库层面创建外键 | 应用层维护引用完整性 |
+| 时间字段 | `datetime` 类型（对应 LocalDateTime） | 禁止 timestamp（时区问题）|
+| 主键 | bigint unsigned 自增或雪花算法 | 分布式环境推荐雪花 |
+| 软删除 | 必须有 deleted 字段（tinyint/boolean） | 禁物理删除业务数据 |
+| 审计字段 | 必须有 create_time / update_time | 由框架自动填充 |
+| 表结构变更 | 通过 ALTER DDL 脚本执行 | 禁止删重建表 |
+
+---
+
+## Nacos 配置组织方式
+
+```yaml
+# 本地 bootstrap.yml — 仅保留最小必要配置
+spring:
+  application:
+    name: jscicd-app-server
+  cloud:
+    nacos:
+      discovery:
+        server-addr: ${NACOS_ADDR:localhost:8848}
+      config:
+        server-addr: ${NACOS_ADDR:localhost:8848}
+        file-extension: yaml
+
+# Nacos 远程配置 key 规范（camelCase）：
+# - spring.datasource.url
+# - spring.redis.host
+# - jscicd.security.sm4-secret-key
+# - logging.level.com.jieshun.domain
+```
+
+**配置规范**:
+- 本地只保留 Nacos 连接地址
+- 其他所有配置从 Nacos 拉取
+- Key 使用 camelCase 格式
+- 禁止使用 shared-configs 共享过多公共配置

package/.harness/dev-map/backend/conventions.md

@@ -0,0 +1,192 @@
+# 后端分区 — 编码惯例
+
+## TypeScript 规范
+
+### 严格模式
+
+```jsonc
+// tsconfig.json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true
+  }
+}
+```
+
+### 类型定义优先级
+
+```
+Interface > Type Alias > Class（纯数据类型场景）
+Class > Interface（需要实例化的场景）
+```
+
+```typescript
+// ✅ 推荐：DTO 使用 Interface
+interface CreateUserDTO {
+  email: string;
+  password: string;
+  name: string;
+  role?: Role;  // 可选属性
+}
+
+// ✅ 推荐：API 响应使用 Interface
+interface ApiResponse<T> {
+  code: number;
+  data: T;
+  message: string;
+  timestamp: number;
+}
+
+// ⚠️ 可接受：联合类型使用 Type
+type UserRole = 'admin' | 'editor' | 'viewer' | 'user';
+type ID = string;  // UUID alias
+```
+
+## 代码风格
+
+### 类/装饰器风格（NestJS）
+
+```typescript
+// ✅ 推荐：清晰的装饰器堆叠
+@Controller('api/v1/users')
+@UseGuards(JwtAuthGuard)
+@ApiTags('users')
+export class UserController {
+  constructor(private readonly userService: UserService) {}
+
+  @Get()
+  @ApiOperation({ summary: '获取用户列表' })
+  @ApiResponse({ status: 200, type: [User] })
+  async findAll(@Query() query: QueryUserDTO): Promise<PaginatedResult<User>> {
+    return this.userService.findAll(query);
+  }
+
+  @Get(':id')
+  @ApiParam({ name: 'id' })
+  async findOne(@Param('id') id: string): Promise<User> {
+    return this.userService.findById(id);
+  }
+}
+```
+
+### 错误处理规范
+
+```typescript
+// ✅ 统一抛出 NestJS 内置异常
+throw new BadRequestException('邮箱格式无效');
+throw new NotFoundException(`用户 ${id} 不存在`);
+throw new ForbiddenException('没有权限执行此操作');
+throw new ConflictException('该邮箱已被注册');
+throw new InternalServerErrorException('操作失败，请重试');
+
+// ✅ 自定义业务异常
+export class BusinessException extends HttpException {
+  constructor(code: string, message: string, statusCode = 400) {
+    super({ code, message }, statusCode);
+  }
+}
+// throw new BusinessException('USER.NOT_FOUND', '用户不存在');
+```
+
+### 异步编程规范
+
+```typescript
+// ✅ 全部使用 async/await
+async function getUserWithOrders(userId: string): Promise<UserWithOrders> {
+  const user = await this.userRepo.findById(userId);
+  if (!user) throw new NotFoundException('User not found');
+  
+  const orders = await this.orderRepo.findByUserId(userId);
+  
+  return { ...user, orders };
+}
+
+// ✅ 并行请求使用 Promise.all
+async function getDashboardData(userId: string) {
+  const [profile, notifications, stats] = await Promise.all([
+    this.userService.getProfile(userId),
+    this.notificationService.getUnread(userId),
+    this.statsService.getUserStats(userId),
+  ]);
+  
+  return { profile, notifications, stats };
+}
+```
+
+## 日志规范
+
+```typescript
+// 使用 Logger (NestJS 内置)
+@Injectable()
+export class UserService {
+  private readonly logger = new Logger(UserService.name);
+
+  async createUser(dto: CreateUserDTO): Promise<User> {
+    this.logger.log(`Creating user with email: ${dto.email}`);
+    try {
+      const user = await this.userRepo.create(dto);
+      this.logger.debug(`User created: ${user.id}`);
+      return user;
+    } catch (error) {
+      this.logger.error(`Failed to create user: ${error.message}`, error.stack);
+      throw error;
+    }
+  }
+}
+
+// 日志级别使用规范：
+// logger.debug()  — 详细调试信息（仅开发环境输出）
+// logger.log()    — 一般业务日志
+// logger.warn()    — 需要注意但不致命的情况
+// logger.error()   — 错误信息（必须包含 stack trace）
+// logger.verbose() — 更多细节（通常不用）
+
+// ⚠️ 禁止：日志中出现敏感信息
+// ❌ logger.info(`Login success: ${password}`);   // 绝不记录密码
+// ✅ logger.info(`Login success: userId=${user.id}`); // 只记录必要标识
+```
+
+## 环境变量使用
+
+```typescript
+// config/app.config.ts
+@register()
+export class AppConfig {
+  @IsString()
+  @IsUrl()
+  APP_URL: string;
+
+  @IsInt()
+  @Min(1)
+  PORT: number;
+
+  @IsEnum(['development', 'staging', 'production'])
+  NODE_ENV: string;
+
+  @IsString()
+  JWT_SECRET: string;  // 必填
+  @IsString()
+  JWT_EXPIRES_IN: string = '15m';
+
+  DATABASE_URL: string;  // 必填
+  REDIS_URL: string;    // 必填
+}
+
+// 使用
+@Injectable()
+export class MyService {
+  constructor(@Inject(AppConfig) private config: AppConfig) {}
+
+  getJwtConfig() {
+    return {
+      secret: this.config.JWT_SECRET,
+      expiresIn: this.config.JWT_EXPIRES_IN,
+    };
+  }
+}
+```