jsharness 1.0.0

package/.harness/rules/project/java-backend.md

@@ -0,0 +1,460 @@
+# Java Spring Boot 后端开发规范 (java-backend)
+
+> **级别**: 项目级强制 | **适用范围**: 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
+
+---
+
+## 1. 架构约束 — 双服务分层与依赖规则
+
+### 1.1 双服务架构
+
+| 服务 | 定位 | 职责 |
+|------|------|------|
+| `app` | 面向用户 | 用户侧功能入口 |
+| `dashboard` | 后台管理 | 管理侧功能入口 |
+
+两服务共享 `domain` 和 `common` 模块。
+
+### 1.2 模块依赖链（强制方向）
+
+```
+controller → service → mapper → database
+    ↑           ↑
+    └──→ common ←──┘
+         ↑
+    integration（第三方集成）
+```
+
+**依赖规则**:
+- ✅ 允许: `controller → service → mapper`
+- ❌ 禁止: controller 直接调用 mapper
+- ❌ 禁止: 反向依赖（mapper 依赖 service）
+- ❌ 禁止: 跨层跳跃依赖
+
+### 1.3 Controller 职责边界
+
+Controller 层 **只** 负责:
+1. 路由分发（`@RequestMapping` / `@PostMapping`）
+2. 参数校验（JSR 303 注解）
+3. 权限校验（注解或拦截器）
+4. 统一返回 JSON 格式
+
+Controller **禁止**:
+- ❌ 编写业务逻辑
+- ❌ 直接操作数据库
+- ❌ 处理 HTTP 请求/响应对象细节（如直接写 HttpServletResponse）
+
+---
+
+## 2. Maven 四层模块结构与包命名
+
+### 2.1 四层模块划分
+
+| 模块 | 职责 | 内容 |
+|------|------|------|
+| `app` | 启动入口、配置类 | Application 主类、配置文件 |
+| `domain` | 业务逻辑核心 | entity, dto, vo, service, mapper, controller |
+| `integration` | 第三方集成 | 外部 API 客户端、消息队列生产者/消费者 |
+| `common` | 公共工具 | 工具类、常量、枚举、异常定义、通用组件 |
+
+### 2.2 包名规范
+
+| 规则 | 要求 | 违规后果 |
+|------|------|----------|
+| 基础包名 | 必须为 `com.jieshun` | Code Review FAIL |
+| 禁止包名 | 禁止使用 `com.jscicd` | Code Review FAIL |
+
+### 2.3 类后缀规范（9 种标准后缀）
+
+| 层级 | 后缀 | 示例 | 说明 |
+|------|------|------|------|
+| 实体 | Entity | `UserEntity` | 数据库表映射 |
+| 数据传输对象 | DTO | `UserDTO` | 跨层数据传输 |
+| 视图对象 | VO | `UserVO` | 向前端展示的数据 |
+| 请求对象 | ReqVO | `UserCreateReqVO` | 接收前端请求参数 |
+| 响应对象 | RespVO | `UserRespVO` | 返回给前端的响应数据 |
+| 枚举 | Enum | `UserStatusEnum` | 状态码/类型码 |
+| 服务接口 | Service | `UserService` | 业务接口定义 |
+| 服务实现 | ServiceImpl | `UserServiceImpl` | 业务实现类 |
+| 控制器 | Controller | `UserController` | REST API 入口 |
+| 数据访问 | Mapper | `UserMapper` | 数据库操作接口 |
+
+---
+
+## 3. Controller 层编码规范
+
+### 3.1 标准注解组合
+
+```java
+@RestController
+@RequestMapping("/api/v1/user")
+@RequiredArgsConstructor
+@Tag(name = "用户管理")
+public class UserController {
+
+    private final UserService userService;
+
+    @PostMapping("/create")
+    @Operation(summary = "创建用户")
+    public CommonResult<UserRespVO> create(@Valid @RequestBody UserCreateReqVO reqVO) {
+        return success(userService.createUser(reqVO));
+    }
+
+    @PostMapping("/page")
+    @Operation(summary = "分页查询用户")
+    public CommonResult<PageResult<UserRespVO>> page(@Valid UserPageReqVO reqVO) {
+        return success(userService.getUserPage(reqVO));
+    }
+}
+```
+
+### 3.2 参数校验规范
+
+- **必须** 使用 JSR 303/349 校验注解：`@NotNull`, `@NotEmpty`, `@Size`, `@Pattern`, `@Min`, `@Max`
+- 入参对象使用 `@Valid` 或 `@Validated` 触发级联校验
+- HTTP 方法统一使用 `@PostMapping`（RESTful 风格但 POST 优先）
+
+### 3.3 分层参数传递
+
+| 规则 | 要求 | 违规后果 |
+|------|------|----------|
+| 入参格式 | 必须为 ReqVO 对象（经过校验的请求对象） | Code Review WARNING |
+| 出参格式 | 封装为 RespVO 对象（不直接暴露 Entity） | Code Review WARNING |
+| 禁止 Map | 禁止使用 Map 作为方法参数或返回值 | Code Review FAIL |
+| 禁止 Entity | 禁止将 Entity 对象直接返回给前端 | Code Review FAIL |
+| 统一封装 | 必须使用统一的 Result 包装类（如 `CommonResult<T>`） | Code Review WARNING |
+
+---
+
+## 4. Service 层编码规范
+
+### 4.1 接口与实现分离模式
+
+```java
+// 接口定义
+public interface UserService {
+    Long createUser(UserCreateReqVO reqVO);
+    PageResult<UserRespVO> getUserPage(UserPageReqVO reqVO);
+}
+
+// 实现
+@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. 参数校验与转换
+        // 2. 业务逻辑编排
+        // 3. 数据持久化
+        // 4. 返回结果
+    }
+}
+```
+
+### 4.2 Service 职责定位
+
+Service 层负责 **业务编排**：
+- 协调多个 Mapper 完成数据操作
+- 协调外部服务完成集成调用
+- 编排事务边界内的操作序列
+
+**禁止**:
+- ❌ 在 Service 中直接操作 HTTP 请求/响应对象
+- ❌ 在 Service 中进行参数校验注解之外的校验逻辑（应在 Controller）
+
+---
+
+## 5. Mapper 层与数据库规范
+
+### 5.1 Mapper 接口定义
+
+| 规则 | 要求 |
+|------|------|
+| 接口形态 | Mapper 为纯接口，**不继承 BaseMapper** |
+| SQL 位置 | 复杂 SQL 必须写在 XML 映射文件中 |
+| 注解限制 | 禁止使用 `@Select/@Insert/@Update/@Delete` 写复杂 SQL |
+
+```java
+// 正确示例
+public interface UserMapper {
+    List<UserDO> selectList(@Param("reqVO") UserPageReqVO reqVO);
+    UserDO selectById(@Param("id") Long id);
+    void insert(@Param("entity") UserDO entity);
+}
+```
+
+### 5.2 分页查询
+
+- 使用 MyBatis-Plus 分页拦截器自动追加 LIMIT
+- 手动 SQL 中 **禁止** 自行写 LIMIT 子句
+
+### 5.3 数据库设计规范
+
+| 规则 | 要求 | 原因 |
+|------|------|------|
+| 字符集 | utf8mb4 | 支持完整 Unicode（含 emoji）|
+| 外键约束 | 禁止使用 | 应用层维护引用完整性，避免性能问题 |
+| 表结构变更 | 必须通过 ALTER 脚本执行 | 不可删除重建表 |
+| 时间字段 | 必须使用 `LocalDateTime` | 禁止 `Date` 或 `Timestamp` |
+
+---
+
+## 6. 错误码与异常处理体系
+
+### 6.1 错误码段分配（7 个模块段）
+
+| 模块 | 错误码范围 | 示例 |
+|------|-----------|------|
+| 用户模块 | 1000-1999 | 1001=用户不存在, 1002=密码错误 |
+| 权限模块 | 2000-2999 | |
+| 内容模块 | 3000-3999 | |
+| 订单模块 | 4000-4999 | |
+| 支付模块 | 5000-5999 | |
+| 系统模块 | 9000-9999 | |
+| ... | （按需扩展） | |
+
+### 6.2 异常抛出规范
+
+```java
+// ✅ 正确：统一使用业务异常
+throw new JscicdBizException(ErrorCode.USER_NOT_FOUND);
+
+// ❌ 错误：禁止直接 throw RuntimeException
+throw new RuntimeException("用户不存在");
+
+// ❌ 错误：禁止返回错误码数字
+return Result.fail(1001);  // 应该用枚举常量
+```
+
+### 6.3 异常分层捕获策略
+
+| 异常类型 | 处理方式 | 全局处理器行为 |
+|---------|----------|---------------|
+| BusinessException | 返回业务错误信息（含错误码和消息） | 直接透传 message |
+| SystemException | 记录日志 + 返回通用错误信息 | 隐藏内部细节 |
+| 未预期异常 | 记录完整堆栈 + 返回安全错误信息 | 保护系统信息不外泄 |
+
+---
+
+## 7. 日志规范
+
+| 规则 | 要求 | 示例 |
+|------|------|------|
+| 占位符 | 必须使用 `{}` 占位符（SLF4J 参数化） | `log.info("用户登录 userId={}", userId)` |
+| 禁止拼接 | 禁止字符串拼接（影响性能） | ❌ `"用户" + id + "登录"` |
+| 单条长度 | 不超过 1KB | 大对象序列化为摘要信息 |
+| 链路追踪 | 必须包含 `traceId` 和 `spanId` | 用于全链路追踪 |
+| 异常保留 | catch 时必须保留异常对象 e | `log.error("描述", e)` |
+
+```java
+// ✅ 正确示例
+log.info("[createUser][reqVO({})]", reqVO);
+log.warn("[loginFail][mobile({})][reason({})]", mobile, reason);
+log.error("[queryUser][id({})] error", id, e);
+
+// ❌ 错误示例
+log.info("创建用户: " + reqVO.toString());  // 字符串拼接
+log.error("查询失败: " + e.getMessage());     // 丢失堆栈信息
+```
+
+---
+
+## 8. Redis 使用规范
+
+| # | 规则 | 要求 | 违规后果 |
+|---|------|------|----------|
+| R-01 | 定位 | Redis 仅用于 **缓存** 用途，禁止作为持久存储 | Code Review FAIL |
+| R-02 | TTL | 必须 设置过期时间，禁永不过期的 key | Gate FAIL |
+| R-03 | Hash 容量 | 单个 Hash 的 field 数量 ≤ 50000 | Code Review WARNING |
+| R-04 | Key 命名 | 统一定义到 `RedisKeyConstants` 常量类 | Code Review WARNING |
+| R-05 | Key 格式 | `模块:业务:唯一标识`（如 `user:login:token:{userId}`） | Code Review WARNING |
+| R-06 | 分布式锁 | 必须使用 Redisson 客户端，禁止手写 SETNX+EXPIRE | Code Review FAIL |
+
+**RedisKeyConstants 示例**:
+```java
+public final class RedisKeyConstants {
+    public static final String USER_LOGIN_TOKEN = "user:login:token:%s";
+    public static final String USER_CAPTCHA = "user:captcha:%s";
+    public static final String CACHE_PREFIX = "cache:%s:%s";  // 模块:唯一标识
+}
+```
+
+---
+
+## 9. JDK 21 虚拟线程规范
+
+| # | 规则 | 要求 | 原因 |
+|---|------|------|------|
+| VT-01 | 启用配置 | `spring.threads.virtual.enabled=true` 必须开启 | 启用虚拟线程支持 |
+| VT-02 | 禁 synchronized | **虚拟线程中禁止使用 synchronized 关键字** | synchronized 导致 pinning（固定到平台线程），失去虚拟线程优势 |
+| VT-03 | 替代方案 | 改用 `ReentrantLock` 替代 synchronized | ReentrantLock 不导致 pinning |
+
+```java
+// ✅ 正确：虚拟线程中使用 ReentrantLock
+private final ReentrantLock lock = new ReentrantLock();
+
+public void processWithVirtualThread() {
+    lock.lock();
+    try {
+        // 业务逻辑
+    } finally {
+        lock.unlock();
+    }
+}
+
+// ❌ 错误：虚拟线程中使用 synchronized
+public synchronized void badMethod() { // 导致 pinning！
+    // ...
+}
+```
+
+---
+
+## 10. 事务管理规范
+
+| # | 规则 | 要求 | 原因 |
+|---|------|------|------|
+| TX-01 | 最小化 | 事务范围最小化 | 减少锁持有时间 |
+| TX-02 | 外部调用放事务外 | 禁止在事务中进行 HTTP 调用、文件操作、消息发送 | 避免长事务 |
+| TX-03 | 分批提交 | 批量操作每批 ≤ 500 条 | 避免长时间持锁 |
+| TX-04 | rollbackFor | `@Transactional(rollbackFor = Exception.class)` | 确保所有异常回滚 |
+
+```java
+// ✅ 正确：外部调用在事务外
+@Transactional(rollbackFor = Exception.class)
+public Long createUser(UserCreateReqVO reqVO) {
+    // 1. DB 操作（在事务内）
+    Long userId = userMapper.insert(entity);
+    
+    // 2. 返回后在外部发送消息/调用HTTP（在事务外）
+    return userId;  // 调用方负责后续操作
+}
+```
+
+---
+
+## 11. 安全规范 — 国密 SM4 与脱敏
+
+### 11.1 敏感数据加密存储
+
+| 数据类型 | 加密方式 | 要求 |
+|---------|---------|------|
+| 手机号 | 国密 SM4 | 存储前加密，查询时解密 |
+| 身份证号 | 国密 SM4 | 全字段加密 |
+| 密码 | bcrypt（不可逆哈希） | cost ≥ 12 |
+| 银行卡号 | 国密 SM4 | 仅存后4位明文，其余加密 |
+
+**强制**: 敏感信息 **必须** 使用国密 SM4 算法加密后存库，禁止明文存储。
+
+### 11.2 API 响应脱敏格式
+
+| 数据类型 | 脱敏格式 | 示例 |
+|---------|---------|------|
+| 手机号 | 中间4位* | `138****1234` |
+| 密码 | 返回 null 或 `******` | null |
+| 邮箱 | @前部分脱敏 | `u***@example.com` |
+| 身份证 | 中间* | `110***********1234` |
+| 银行卡号 | 显示后4位 | `************5678` |
+
+### 11.3 SQL 注入防护
+
+| 规则 | 要求 | 违规后果 |
+|------|------|----------|
+| 预编译 | 必须 使用 `#{}` 预编译参数绑定 | **安全红线 FAIL** |
+| 禁拼接 | 禁止 `${}` 直接拼接 SQL | **安全红线 FAIL** |
+| 例外 | 动态表名等特殊场景需有白名单校验 | 必须代码审查确认 |
+
+---
+
+## 12. Nacos 配置规范
+
+| 规则 | 要求 |
+|------|------|
+| 本地配置最小化 | 本地仅保留 Nacos 连接地址等最小必要配置 |
+| 配置拉取 | 其他配置从 Nacos 动态拉取 |
+| Key 格式 | camelCase 驼峰格式 |
+| 禁 shared-configs | 避免共享过多公共配置，按需显式引入 |
+
+---
+
+## 13. 测试规范
+
+| 规则 | 要求 |
+|------|------|
+| 测试框架 | JUnit 5 + Mockito |
+| 测试路径 | 测试类路径对应源码目录结构 |
+| 行覆盖率 | ≥ **80%** |
+| 核心业务覆盖率 | ≥ **90%** |
+| 覆盖率收集工具 | JaCoCo |
+
+```xml
+<!-- pom.xml JaCoCo 配置 -->
+<plugin>
+    <groupId>org.jacoco</groupId>
+    <artifactId>jacoco-maven-plugin</artifactId>
+    <executions>
+        <execution><goals><goal>prepare-agent</goal></goals></execution>
+        <execution><id>report</id><phase>test</phase><goals><goal>report</goal></goals></execution>
+    </executions>
+</plugin>
+```
+
+---
+
+## 14. 后端代码审查 22 项检查清单
+
+### 架构与分层（第 1-4 项）
+
+| # | 检查项 | 标准 |
+|---|--------|------|
+| JB-01 | Controller 是否只做路由和校验 | 无业务逻辑 |
+| JB-02 | Service 是否做业务编排 | 非 CRUD 直通 |
+| JB-03 | Mapper 是否纯接口且 SQL 在 XML 中 | 不继承 BaseMapper，无注解 SQL |
+| JB-04 | 模块依赖方向是否正确 | 无循环/反向/跨层跳跃依赖 |
+
+### 命名与规范（第 5-9 项）
+
+| # | 检查项 | 标准 |
+|---|--------|------|
+| JB-05 | 包名是否为 `com.jieshun` | 非 com.jscicd |
+| JB-06 | 类后缀是否符合 9 种标准后缀 | Entity/DTO/VO/ReqVO/RespVO/Enum/ServiceImpl/Controller/Mapper |
+| JB-07 | 是否有完整的 Javadoc 注释 | public 类必须有 |
+| JB-08 | 方法命名是否清晰表达意图 | 动词开头，语义明确 |
+| JB-09 | 常量是否使用 UPPER_SNAKE_CASE | 枚举值除外 |
+
+### 参数与返回值（第 10-13 项）
+
+| # | 检查项 | 标准 |
+|---|--------|------|
+| JB-10 | Controller 参数是否有 JSR303 校验注解 | @Valid/@Validated |
+| JB-11 | 是否使用了 ReqVO/RespVO 分层传参 | 禁 Map/Entity 直通 |
+| JB-12 | 禁止 Map 和 Entity 直接暴露 | 必须转换 |
+| JB-13 | 返回值是否用统一 Result 封装 | CommonResult<T> |
+
+### 数据库与 SQL（第 14-16 项）
+
+| # | 检查项 | 标准 |
+|---|--------|------|
+| JB-14 | SQL 是否使用 `#{}` 预编译 | 防 SQL 注入 |
+| JB-15 | 分页是否使用拦截器 | 非手动 LIMIT |
+| JB-16 | 表结构变更是否有 ALTER 脚本 | 不可删重建表 |
+
+### 安全与质量（第 17-22 项）
+
+| # | 检查项 | 标准 |
+|---|--------|------|
+| JB-17 | 敏感数据是否 SM4 加密存储 | 手机号/身份证等 |
+| JB-18 | 响应数据是否已脱敏 | 手机号/邮箱/身份证格式 |
+| JB-19 | Redis key 是否有 TTL | 禁永不过期 |
+| JB-20 | 日志是否使用 `{}` 参数化 | 禁字符串拼接 |
+| JB-21 | 事务范围是否最小化 | 外部调用放事务外 |
+| JB-22 | 虚拟线程中是否无 synchronized | 改用 ReentrantLock |

package/.harness/rules/project/web-specific.md

@@ -0,0 +1,231 @@
+# Web 应用特有规则 (web-specific)
+
+> **级别**: 必须遵守 | **适用范围**: Web 全栈项目
+
+## 1. 前端 i18n 合规要求
+
+### 1.1 国际化基础规范
+
+```typescript
+// ❌ 硬编码中文字符串（无法国际化）
+<Button>提交</Button>
+<span>暂无数据</span>
+alert('操作成功');
+
+// ✅ 正确：使用 i18n 工具函数
+<Button>{t('common.submit')}</Button>
+<span>{t('message.noData')}</span>
+toast.success(t('toast.operationSuccess'));
+```
+
+### 1.2 i18n 文件组织结构
+
+```
+locales/
+├── zh-CN.json          # 简体中文（默认语言）
+├── en-US.json          # 英语
+├── ja-JP.json          # 日语（按需扩展）
+└── index.ts            # 导出 i18n 实例
+```
+
+### 1.3 特殊情况处理
+
+```typescript
+// ✅ 占位符插值
+t('greeting', { name: userName })  // "你好，{{name}}"
+
+// ✅ 复数形式
+t('itemCount', { count: items.length })  // "{{count}} 个项目"
+
+// ⚠️ 允许硬编码的场景（需注释说明）
+// 技术标识符、CSS 类名、日志 key、测试数据
+const TEST_USER_ID = 'test-user-001'; // Test fixture, no need to i18n
+```
+
+---
+
+## 2. API 调用规范
+
+### 2.1 统一客户端封装
+
+```typescript
+// 所有 API 调用必须经过统一封装层，禁止直接使用 fetch/axios
+
+// ✅ 正确：使用封装的 apiClient
+import { apiClient } from '@/lib/api-client';
+
+const users = await apiClient.get('/users', { params: { page: 1 } });
+
+// 封装层应内置：
+// - 自动附加认证 token
+// - 统一错误处理
+// - 请求/响应拦截器
+// - 请求取消支持（AbortController）
+// - 重试机制（幂等接口自动重试）
+```
+
+### 2.2 接口调用约定
+
+| 约定 | 要求 |
+|------|------|
+| **错误处理** | 使用统一的错误边界组件或 hook |
+| **Loading 状态** | 每次请求必须展示 loading 态 |
+| **缓存策略** | GET 请求默认缓存（Pinia Plugin / keepAlive）|
+| **乐观更新** | 写操作支持乐观更新（mutation）|
+| **请求去重** | 相同请求在 pending 时不重复发送 |
+
+### 2.3 RESTful URL 规范
+
+```
+# 资源命名：名词复数
+GET    /api/v1/users          # 获取用户列表
+GET    /api/v1/users/:id      # 获取单个用户
+POST   /api/v1/users          # 创建用户
+PUT    /api/v1/users/:id      # 全量更新
+PATCH  /api/v1/users/:id      # 部分更新
+DELETE /api/v1/users/:id      # 删除用户
+
+# 动作命名：动词
+POST   /api/v1/users/:id/activate    # 激活用户
+POST   /api/v1/orders/:id/cancel     # 取消订单
+
+# 过滤/排序/分页
+GET    /api/v1/users?role=admin&page=1&pageSize=20&sort=createdAt-desc
+```
+
+---
+
+## 3. 前后端接口约定
+
+### 3.1 统一响应格式
+
+```typescript
+// 成功响应
+interface SuccessResponse<T> {
+  code: 0;
+  data: T;
+  message: string;
+  timestamp: number;
+}
+
+// 错误响应
+interface ErrorResponse {
+  code: number;         // 业务错误码（非 HTTP 状态码）
+  message: string;      // 可展示给用户的错误信息
+  details?: ErrorDetail[];
+  timestamp: number;
+}
+```
+
+### 3.2 业务错误码规范
+
+| 错误码范围 | 含义 | 示例 |
+|-----------|------|------|
+| 0 | 成功 | - |
+| 1xxxx | 参数错误 | 10001: 缺少必填参数 |
+| 2xxxx | 认证/授权错误 | 20001: Token 已过期 |
+| 3xxxx | 业务逻辑错误 | 30001: 用户名已存在 |
+| 4xxxx | 资源错误 | 40001: 资源不存在 |
+| 5xxxx | 第三方服务错误 | 50001: 支付网关超时 |
+| 9xxxx | 系统内部错误 | 90001: 数据库连接失败 |
+
+### 3.3 版本控制
+
+- URL 中携带版本号：`/api/v1/...`
+- 向后兼容：新增字段不影响旧版本
+- 废弃接口保留至少 2 个大版本周期
+- Response Header 中标注 API 版本
+
+---
+
+## 4. 前端性能规则
+
+### 4.1 打包体积约束
+
+| 指标 | 限制 |
+|------|------|
+| 首屏 JS bundle | ≤ 200KB（gzip 后）|
+| 单页面路由 chunk | ≤ 100KB（gzip 后）|
+| 图片大小 | ≤ 200KB（压缩后），WebP 格式优先 |
+| 字体文件 | ≤ 50KB（subset 后）|
+| 总资源体积（首屏）| ≤ 1MB |
+
+### 4.2 渲染性能
+
+```typescript
+// ✅ 正确：大数据量列表必须虚拟滚动
+import { useVirtualList } from '@vueuse/core';
+const { list, containerProps, wrapperProps } = useVirtualList(items, { itemHeight: 48 });
+
+// ✅ 正确：避免不必要的重渲染（Vue3 组件默认细粒度更新，无需额外 memo）
+// Vue3 使用 shallowRef / triggerRef 控制深层响应式开销
+
+// ✅ 正确：图片懒加载
+<img loading="lazy" :src="url" :alt="description" />
+
+// ❌ 禁止：内联大对象作为 prop（每次创建新引用）
+<List :items="[...largeArray]" />
+
+// ✅ 正确：computed 稳定引用
+const items = computed(() => largeArray.map(transform));
+```
+
+### 4.3 SEO 与元数据
+
+每个公共页面必须设置：
+
+```tsx
+<Head>
+  <title>{pageTitle} - {siteName}</title>
+  <meta name="description" content={pageDescription} />
+  <meta property="og:title" content={pageTitle} />
+  <meta property="og:description" content={pageDescription} />
+  <link rel="canonical" href={canonicalUrl} />
+</Head>
+```
+
+---
+
+## 5. 响应式设计规则
+
+### 断点标准（Tailwind CSS）
+
+| 断点名称 | 最小宽度 | 设备 |
+|----------|---------|------|
+| `sm` | 640px | 大屏手机 |
+| `md` | 768px | 平板竖屏 |
+| `lg` | 1024px | 平板横屏/小笔记本 |
+| `xl` | 1280px | 桌面显示器 |
+| `2xl` | 1536px | 大屏桌面 |
+
+### 设计原则
+
+- **Mobile First**：默认样式适配移动端，媒体查询向上扩展
+- **触控友好**：点击区域最小 44×44px
+- **字体缩放**：使用 `rem` 单位，尊重系统字号偏好设置
+
+---
+
+## 6. 浏览器兼容性
+
+| 目标浏览器 | 最低版本 |
+|-----------|---------|
+| Chrome | 最近 2 个主版本 |
+| Firefox | 最近 2 个主版本 |
+| Safari | 最近 2 个主版本 |
+| Edge | 最近 2 个主版本 |
+| IE | **不支持**（明确声明） |
+
+---
+
+## 7. Web 安全专项（补充 security-baseline）
+
+| 检查项 | 要求 |
+|--------|------|
+| CSP 策略 | 生产环境启用 Content-Security-Policy |
+| X-Frame-Options | DENY 或 SAMEORIGIN |
+| X-Content-Type-Options | nosniff |
+| Referrer-Policy | strict-origin-when-cross-origin |
+| Permissions-Policy | 限制摄像头/麦克风/地理位置等 |
+| CORS | 明确指定允许的 Origin，避免 `*` |
+| Cookie 安全 | Secure; HttpOnly; SameSite=Strict（生产环境）|