jsharness 1.5.0 → 1.6.0

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

@@ -1,8 +1,8 @@
 # 后端分区 — Java 编码惯例 (conventions-java)
 
-> **来源**: `files/java-backend-coding-standards/SKILL.md` (JSCICD 项目后端 Java 规范)
+> **来源**: `files/java-backend-coding-standards/SKILL.md` (已重构为 jieshun 项目后端 Java 规范)
 > **归档日期**: 2026-05-21
-> **技术栈**: Spring Boot 3.2.12 / JDK 21 (虚拟线程) / MySQL 8.0 / Redis 5.x / MyBatis-Plus
+> **技术栈**: Spring Boot 3.2.12 / JDK 21 (虚拟线程) / MySQL 8.0 / 达梦 DM8 / Redis 5.x / MyBatis-Plus
 
 ## 技术栈版本速查
 
@@ -17,20 +17,22 @@
 | Redisson | 3.x | 分布式锁/Redis 客户端 |
 | Hutool | 5.x | 工具库（按需使用）|
 | Knife4j/Swagger | OpenAPI 3 | API 文档 |
-| Nacos | 2.x | 配置中心 + 注册中心 |
+| Nacos | 3.0 | 配置中心 + 注册中心 |
+| 达梦 DM8 | 8.x | 国产化/信创数据库（替代 MySQL）|
+| MapStruct | 1.5.x | 对象转换（Entity ↔ VO/DTO）|
 
 ---
 
 ## Maven 四层模块详细结构
 
 ```
-jscicd-project/
+jieshun-project/
 ├── pom.xml                          # 父 POM（统一依赖版本管理）
 ├── app/                             # 启动入口模块
 │   ├── pom.xml
 │   └── src/main/java/com/jieshun/
 │       └── app/
-│           ├── JscicdApplication.java    # @SpringBootApplication
+│           ├── JieshunApplication.java    # @SpringBootApplication
 │           └── config/                     # 启动配置类
 │               └── WebMvcConfig.java
 │
@@ -48,12 +50,12 @@ jscicd-project/
 │           │   └── impl/                  # 实现类子包
 │           │       └── UserServiceImpl.java
 │           ├── mapper/                   # Mapper 层
-│           │   ├── UserMapper.java         # Mapper 接口
+│           │   ├── UserMapper.java         # Mapper 接口（纯接口，不继承 BaseMapper）
 │           │   └── xml/                    # XML 映射文件目录
 │           │       └── UserMapper.xml
 │           ├── data/                     # 数据对象层
-│           │   ├── entity/                # 数据库实体
-│           │   │   └── UserDO.java
+│           │   ├── entity/                # 数据库实体（XML resultType 映射，无需 @TableName）
+│           │   │   └── UserEntity.java
 │           │   ├── vo/                    # 视图对象
 │           │   │   ├── UserVO.java
 │           │   │   ├── UserRespVO.java     # 响应对象
@@ -75,11 +77,11 @@ jscicd-project/
     ├── pom.xml
     └── src/main/java/com/jieshun/common/
         ├── constant/                  # 常量
-        │   ├── ErrorCodeConstants.java   # 错误码枚举
+        │   ├── ErrorCodeConstants.java   # 错误码常量（引用 ErrorCode 枚举）
         │   └── RedisKeyConstants.java     # Redis Key 常量
         ├── exception/                # 异常定义
-        │   ├── ServiceException.java
-        │   └── JscicdBizException.java    # 业务异常基类
+        │   ├── ServiceException.java      # 系统服务异常（不可恢复，隐藏内部细节）
+        │   └── BusinessException.java    # 业务异常基类（可恢复，透传错误信息给前端）
         ├── util/                      # 工具类
         │   └── ObjectUtils.java
         └── enums/                     # 通用枚举
@@ -97,45 +99,46 @@ jscicd-project/
  * 用户管理 Controller
  *
  * @description 提供用户 CRUD 和分页查询接口
- * @author jscicd-backend-team
+ * @author jieshun-backend-team
  */
 @RestController
-@RequestMapping("/api/v1/user")
+@RequestMapping("/api/v1/users")
 @RequiredArgsConstructor
 @Tag(name = "用户管理")
 public class UserController {
 
     private final UserService userService;
 
-    @PostMapping("/create")
+    @PostMapping
     @Operation(summary = "创建用户")
     public CommonResult<Long> create(@Valid @RequestBody UserCreateReqVO reqVO) {
         return success(userService.createUser(reqVO));
     }
 
-    @PostMapping("/update")
+    @PutMapping("/{id}")
     @Operation(summary = "更新用户")
-    public CommonResult<Boolean> update(@Valid @RequestBody UserUpdateReqVO reqVO) {
+    public CommonResult<Boolean> update(@PathVariable("id") Long id,
+                                        @Valid @RequestBody UserUpdateReqVO reqVO) {
         userService.updateUser(reqVO);
         return success(true);
     }
 
-    @PostMapping("/delete")
+    @DeleteMapping("/{id}")
     @Operation(summary = "删除用户")
-    public CommonResult<Boolean> delete(@RequestParam("id") Long id) {
+    public CommonResult<Boolean> delete(@PathVariable("id") Long id) {
         userService.deleteUser(id);
         return success(true);
     }
 
-    @PostMapping("/page")
+    @GetMapping
     @Operation(summary = "分页查询用户")
     public CommonResult<PageResult<UserRespVO>> page(@Valid UserPageReqVO reqVO) {
         return success(userService.getUserPage(reqVO));
     }
 
-    @GetMapping("/get")
+    @GetMapping("/{id}")
     @Operation(summary = "获取用户详情")
-    public CommonResult<UserRespVO> get(@RequestParam("id") Long id) {
+    public CommonResult<UserRespVO> get(@PathVariable("id") Long id) {
         return success(userService.getUser(id));
     }
 }
@@ -144,7 +147,7 @@ public class UserController {
 **Controller 要点**:
 - `@RestController` + `@RequestMapping` 定义路由前缀
 - `@RequiredArgsConstructor` 构造器注入
-- HTTP 方法统一用 `@PostMapping`（RESTful 风格但 POST 优先）
+- HTTP 方法按 RESTful 语义使用：查询用 GET，创建用 POST，更新用 PUT/PATCH，删除用 DELETE
 - 参数校验使用 JSR303：`@Valid` / `@Validated`
 - 返回值统一包装为 `CommonResult<T>`
 - Swagger/OpenAPI 注解：`@Tag`, `@Operation`
@@ -197,7 +200,7 @@ public class UserServiceImpl implements UserService {
     public Long createUser(UserCreateReqVO reqVO) {
         // 1. 参数校验与转换
         // TODO: 校验手机号唯一性
-        UserDO entity = UserConvert.INSTANCE.convert(reqVO);
+        UserEntity entity = UserConvert.INSTANCE.convert(reqVO);
 
         // 2. 业务逻辑编排
         // （如：发送欢迎短信 — 在事务外调用）
@@ -211,15 +214,15 @@ public class UserServiceImpl implements UserService {
 
     @Override
     public PageResult<UserRespVO> getUserPage(UserPageReqVO reqVO) {
-        // 分页参数设置
-        PageHelper.startPage(reqVO.getPageNo(), reqVO.getPageSize());
+        // 分页参数设置（MyBatis-Plus 分页拦截器自动追加 LIMIT）
+        Page<UserEntity> page = new Page<>(reqVO.getPageNo(), reqVO.getPageSize());
 
         // 执行查询
-        List<UserDO> list = userMapper.selectList(reqVO);
+        Page<UserEntity> result = userMapper.selectPage(page, reqVO);
 
         // 转换返回
-        return new PageResult<>(UserConvert.INSTANCE.convertList(list),
-            new PageInfo<>(list).getTotal());
+        return new PageResult<>(UserConvert.INSTANCE.convertList(result.getRecords()),
+            result.getTotal());
     }
 }
 ```
@@ -234,12 +237,13 @@ public class UserServiceImpl implements UserService {
 ### Mapper + XML 标准模板
 
 ```java
-// Mapper 接口
+// Mapper 接口（纯接口，不继承 BaseMapper）
 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);
+    Page<UserEntity> selectPage(Page<UserEntity> page, @Param("reqVO") UserPageReqVO reqVO);
+    List<UserEntity> selectList(@Param("reqVO") UserPageReqVO reqVO);
+    UserEntity selectById(@Param("id") Long id);
+    void insert(@Param("entity") UserEntity entity);
+    void updateById(@Param("entity") UserEntity entity);
     void deleteById(@Param("id") Long id);
 }
 ```
@@ -256,7 +260,7 @@ public interface UserMapper {
         create_time, update_time, deleted
     </sql>
 
-    <select id="selectList" resultType="com.jieshun.domain.data.entity.UserDO">
+    <select id="selectList" resultType="com.jieshun.domain.data.entity.UserEntity">
         SELECT <include refid="selectFields"/>
         FROM system_users
         <where>
@@ -285,8 +289,7 @@ public interface UserMapper {
 ```java
 // ========== Entity ==========
 @Data
-@TableName("system_users")
-public class UserDO {
+public class UserEntity {
     /** 用户 ID */
     private Long id;
     /** 用户名 */
@@ -303,8 +306,8 @@ public class UserDO {
     private LocalDateTime createTime;
     /** 更新时间 */
     private LocalDateTime updateTime;
-    /** 是否删除 */
-    private Boolean deleted;
+    /** 是否删除（0=未删除 1=已删除）*/
+    private Integer deleted;
 }
 
 // ========== ReqVO ==========
@@ -345,8 +348,8 @@ public class UserRespVO {
 public class GlobalExceptionHandler {
 
     /** 业务异常 — 直接透传错误信息 */
-    @ExceptionHandler(JscicdBizException.class)
-    public CommonResult<?> handleBizException(JscicdBizException e) {
+    @ExceptionHandler(BusinessException.class)
+    public CommonResult<?> handleBizException(BusinessException e) {
         log.warn("[handleBizException][code({})message({})]", e.getCode(), e.getMessage());
         return CommonResult.error(e.getCode(), e.getMessage());
     }
@@ -374,26 +377,35 @@ try {
 
 ---
 
-## 错误码分配表
+## 错误码规范
 
-| 模块 | 前缀 | 错误码范围 | 示例 |
-|------|------|-----------|------|
-| 用户模块 | 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 |
+统一响应中 `code` 字段采用 HTTP 状态码风格：
 
-```java
-/** 错误码常量示例 */
-public interface ErrorCodeConstants {
+| code | 含义 | 说明 |
+|------|------|------|
+| 200 | 成功 | 请求成功 |
+| 400 | 参数错误 | 请求参数校验失败 |
+| 401 | 未授权 | Token 无效或已过期 |
+| 403 | 禁止访问 | 无权限访问该资源 |
+| 404 | 资源不存在 | 请求的资源未找到 |
+| 409 | 资源冲突 | 如用户名已存在 |
+| 500 | 服务器内部错误 | 不可预期的系统异常 |
 
-    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, "系统繁忙，请稍后重试");
+**业务细粒度错误码**：在 HTTP 状态码基础上，通过 `message` 字段和业务异常枚举（ErrorCode）提供更细粒度的错误描述。
+
+```java
+/** 错误码枚举示例 */
+public enum ErrorCode {
+    USER_NOT_FOUND(404, "用户不存在"),
+    USER_PASSWORD_ERROR(400, "密码错误"),
+    USER_ALREADY_EXISTS(409, "用户名已存在"),
+    TOKEN_EXPIRED(401, "Token 已过期"),
+    SYSTEM_ERROR(500, "系统繁忙，请稍后重试"),
+    // ... 按业务需求扩展
+    ;
+
+    private final int code;
+    private final String message;
 }
 ```
 
@@ -436,7 +448,7 @@ public final class RedisKeyConstants {
 | 禁止外键 | 不在数据库层面创建外键 | 应用层维护引用完整性 |
 | 时间字段 | `datetime` 类型（对应 LocalDateTime） | 禁止 timestamp（时区问题）|
 | 主键 | bigint unsigned 自增或雪花算法 | 分布式环境推荐雪花 |
-| 软删除 | 必须有 deleted 字段（tinyint/boolean） | 禁物理删除业务数据 |
+| 软删除 | 必须有 deleted 字段（Integer: 0/1） | 禁物理删除业务数据 |
 | 审计字段 | 必须有 create_time / update_time | 由框架自动填充 |
 | 表结构变更 | 通过 ALTER DDL 脚本执行 | 禁止删重建表 |
 
@@ -448,7 +460,7 @@ public final class RedisKeyConstants {
 # 本地 bootstrap.yml — 仅保留最小必要配置
 spring:
   application:
-    name: jscicd-app-server
+    name: jieshun-app-server
   cloud:
     nacos:
       discovery:
@@ -460,7 +472,7 @@ spring:
 # Nacos 远程配置 key 规范（camelCase）：
 # - spring.datasource.url
 # - spring.redis.host
-# - jscicd.security.sm4-secret-key
+# - jieshun.security.sm4-secret-key
 # - logging.level.com.jieshun.domain
 ```
 

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

@@ -1,192 +1,156 @@
-# 后端分区 — 编码惯例
+# 后端分区 — Java 编码惯例
 
-## TypeScript 规范
+> **来源**: `files/java-backend-coding-standards/SKILL.md` (已重构为 jieshun 项目后端 Java 规范)
+> **归档日期**: 2026-05-21
+> **技术栈**: Spring Boot 3.2 / JDK 21 (虚拟线程) / MySQL 8.0 / 达梦 DM8 / Redis 5.x / MyBatis-Plus
+
+## Java 编码规范
 
 ### 严格模式
 
-```jsonc
-// tsconfig.json
-{
-  "compilerOptions": {
-    "strict": true,
-    "noImplicitAny": true,
-    "strictNullChecks": true,
-    "strictFunctionTypes": true,
-    "noUncheckedIndexedAccess": true,
-    "exactOptionalPropertyTypes": true
-  }
-}
+```java
+// ✅ 所有公开类/接口必须有 JavaDoc
+// ✅ 必须使用 Lombok @Data/@RequiredArgsConstructor 等简化代码
+// ✅ 禁止裸 any/Object 等模糊类型
 ```
 
-### 类型定义优先级
+### 命名约定
 
 ```
-Interface > Type Alias > Class（纯数据类型场景）
-Class > Interface（需要实例化的场景）
+类命名: PascalCase + 标准后缀
+  Entity:    UserEntity        # 数据库表映射
+  DTO:       UserDTO           # 跨层数据传输
+  VO:        UserVO             # 视图对象（通用）
+  ReqVO:     UserCreateReqVO    # 请求对象（JSR303 校验）
+  RespVO:    UserRespVO         # 响应对象（脱敏后返回前端）
+  Enum:      UserStatusEnum     # 状态码/类型码
+  Service:   UserService        # 业务接口定义
+  ServiceImpl: UserServiceImpl   # 业务实现类
+  Controller: UserController     # REST API 入口
+  Mapper:    UserMapper          # 数据库操作接口
+
+方法命名:
+  selectPage / selectById / insert / updateById / deleteById   # Mapper 方法
+  createUser / getUserPage / getUser                            # Service 方法
+  create / page / get / update / delete                         # Controller 方法
+
+变量命名:
+  camelCase:  userId, isLoading, mobile
+  常量:       UPPER_SNAKE_CASE: MAX_RETRY_COUNT, API_BASE_URL
+  布尔变量:   is/has/can 前缀: isActive, hasPermission
 ```
 
-```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
-```
+### 代码风格 — Controller/Service/Mapper 分层
+
+```java
+// ✅ 推荐：清晰的 Controller 注解堆叠
+@RestController
+@RequestMapping("/api/v1/users")
+@RequiredArgsConstructor
+@Tag(name = "用户管理")
+public class UserController {
+    private final UserService userService;
+
+    @PostMapping
+    @Operation(summary = "创建用户")
+    public CommonResult<Long> create(@Valid @RequestBody UserCreateReqVO reqVO) {
+        return success(userService.createUser(reqVO));
+    }
 
-## 代码风格
-
-### 类/装饰器风格（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);
-  }
+    @GetMapping
+    @Operation(summary = "分页查询用户")
+    public CommonResult<PageResult<UserRespVO>> page(@Valid UserPageReqVO reqVO) {
+        return success(userService.getUserPage(reqVO));
+    }
 }
 ```
 
 ### 错误处理规范
 
-```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 };
+```java
+// ✅ 统一使用项目自定义业务异常
+throw new BusinessException(ErrorCode.USER_NOT_FOUND);
+throw new BusinessException(ErrorCode.USER_PASSWORD_ERROR);
+throw new BusinessException(ErrorCode.USER_ALREADY_EXISTS);
+
+// ✅ 系统异常使用 ServiceException（隐藏内部细节）
+try {
+    // 外部调用
+} catch (ExternalServiceException e) {
+    log.error("[callExternal][params({})] error", params, e);
+    throw new ServiceException(ErrorCode.SYSTEM_ERROR);
 }
 
-// ✅ 并行请求使用 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 };
-}
+// ❌ 禁止直接 throw RuntimeException
+// ❌ 禁止返回错误码数字 return Result.fail(1001);
 ```
 
-## 日志规范
-
-```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;
+### 异常分层体系
+
+| 异常类 | 用途 | 全局处理器行为 |
+|--------|------|---------------|
+| `BusinessException` | 业务规则违反（可恢复） | 直接透传错误码和消息给前端 |
+| `ServiceException` | 系统服务异常（不可恢复） | 记录日志 + 返回通用错误信息，隐藏内部细节 |
+| 未预期 `Exception` | 不可预期的系统异常 | 记录完整堆栈 + 返回安全错误信息 |
+
+### 日志规范（SLF4J + Logback）
+
+```java
+@Service
+@Slf4j
+public class UserServiceImpl implements UserService {
+
+    @Override
+    public Long createUser(UserCreateReqVO reqVO) {
+        log.info("[createUser][reqVO({})]", reqVO);
+        try {
+            Long userId = userMapper.insert(entity);
+            log.debug("[createUser][userId({})]", userId);
+            return userId;
+        } catch (DuplicateKeyException e) {
+            log.warn("[createUser][mobile({})][reason({})]", reqVO.getMobile(), "重复注册");
+            throw new BusinessException(ErrorCode.USER_ALREADY_EXISTS);
+        }
     }
-  }
 }
 
 // 日志级别使用规范：
-// logger.debug()  — 详细调试信息（仅开发环境输出）
-// logger.log()    — 一般业务日志
-// logger.warn()    — 需要注意但不致命的情况
-// logger.error()   — 错误信息（必须包含 stack trace）
-// logger.verbose() — 更多细节（通常不用）
+// log.debug()  — 详细调试信息（仅开发环境输出）
+// log.info()   — 一般业务日志
+// log.warn()   — 需要注意但不致命的情况
+// log.error()  — 错误信息（必须保留异常对象 e）
 
 // ⚠️ 禁止：日志中出现敏感信息
-// ❌ logger.info(`Login success: ${password}`);   // 绝不记录密码
-// ✅ logger.info(`Login success: userId=${user.id}`); // 只记录必要标识
+// ❌ log.info("Login success: password={}", password);   // 绝不记录密码
+// ✅ log.info("Login success: userId={}", userId);        // 只记录必要标识
+// ❌ log.info("创建用户: " + reqVO.toString());            // 禁止字符串拼接
+// ✅ log.info("[createUser][reqVO({})]", reqVO);          // 使用 {} 参数化
 ```
 
-## 环境变量使用
-
-```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,
-    };
-  }
-}
+### 配置规范（Nacos 3.0）
+
+```yaml
+# 本地 bootstrap.yml — 仅保留最小必要配置
+spring:
+  application:
+    name: jieshun-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
+# - jieshun.security.sm4-secret-key
+# - logging.level.com.jieshun.domain
 ```
+
+**配置规范**:
+- 本地只保留 Nacos 连接地址
+- 其他所有配置从 Nacos 拉取
+- Key 使用 camelCase 格式
+- 禁止使用 shared-configs 共享过多公共配置