jsharness 1.0.0

package/.harness/docs/team-guidelines/rd-team.md

@@ -0,0 +1,714 @@
+# 研发团队 (RD) Harness 使用规范
+
+> **适用角色**: 前端开发、后端开发、全栈开发  
+> **对应 Agent**: 开发实现 Agent (developer) + 代码审查 Agent (code-reviewer)  
+> **模型档位**: Standard（开发）/ Strong（审查）  
+> **参考契约**: `.harness/agents/developer/contract.yaml` + `.harness/agents/code-reviewer/contract.yaml`  
+> **核心规则**: `rules/global/coding-standard.md` / `rules/global/security-baseline.md` / `rules/global/commit-convention.md`  
+
+---
+
+## 一、角色定位：你是质量的创造者
+
+### 1.1 双重身份
+
+每个研发人员在 Harness 中承担 **两个角色**：
+
+```
+┌─────────────────────────────────────────────────┐
+│              研发人员的双重身份                    │
+├──────────────────┬──────────────────────────────┤
+│   🔨 开发者       │    🔍 代码审查者               │
+│   (Developer)    │   (Code Reviewer)             │
+├──────────────────┼──────────────────────────────┤
+│ 写代码            │ 审查同事代码                    │
+│ 写单元测试        │ 给出 PASS/条件PASS/FAIL 裁决   │
+│ 跑 Gate 自检      │ 识别安全和性能风险              │
+│ 更新 dev-map      │ 提供改进建议                    │
+│ 创建 PR/MR        │ 保护主分支质量                  │
+└──────────────────┴──────────────────────────────┘
+```
+
+**重要原则**: 你不能审查自己的 PR/MR。必须由另一位开发者进行交叉审查。
+
+### 1.2 绝对禁止做的事
+
+| # | 禁止行为 | 触发后果 |
+|---|---------|---------|
+| 1 | **硬编码密钥/token/密码** | Gate D 类 FAIL + 安全事件通报 |
+| 2 | **提交带 console.log/debugger 的代码** | Gate A 类 WARNING → 累积 3 次 FAIL |
+| 3 | **裸 `any` 类型无注释说明** | Code Review A 类扣分 |
+| 4 | **跳过任意一步自检流程** | PR 直接打回 |
+| 5 | **自行合并自己的 PR/MR** | 严重违规，撤销合并 |
+| 6 | **引入未声明的依赖** | Code Review FAIL |
+| 7 | **修改上游文档**（需求/设计） | 流程违规警告 |
+| 8 | **覆盖率不达标就提交 PR** | Gate C 类 FAIL |
+
+---
+
+## 二、开发实现阶段规范（开发者身份）
+
+### 2.1 标准工作流（8 步，一步都不能少）
+
+```
+收到设计文档 ──→ ①阅读理解 ──→ ②编码实现 ──→ ③编写单元测试 
+     ↓                                                    │
+  dev-map 参考                                          ④Build 检查
+     ↓                                              编译失败→回②
+  Rule/Skill 参考                                          ↓
+     │                                              ⑤单元测试执行
+     │                                            失败→回②/③
+     │                                                  ↓
+     │                                              ⑥Lint 检查
+     │                                            有warning→修复重跑
+     │                                                  ↓
+     │                                              ⑦更新dev-map
+     │                                            （有结构变化时）
+     │                                                  ↓
+     │                                              ⑧Commit+创建PR
+     │                                           格式不符→修正重提
+     ↓                                                  ↓
+  全部PASS ✓ ───────────────────────────────→ 进入代码审查阶段
+```
+
+#### Step ①: 阅读理解
+
+**必读文件清单**：
+
+| 序号 | 文件 | 位置 | 目的 |
+|-----|------|------|------|
+| 1 | 技术设计文档 | `{deliverables}/design-{id}.md` | 了解实现方案 |
+| 2 | API 定义 | `{deliverables}/api-definition.yaml` | 明确接口规格 |
+| 3 | 数据模型 | `{deliverables}/data-model.md` | 了解数据结构 |
+| 4 | dev-map 相关分区 | `.harness/dev-map/{frontend,backend}/` | 了解现有约定 |
+| 5 | 编码规范 | `.harness/rules/global/coding-standard.md` | 遵循代码风格 |
+
+**阅读后应确认**：
+- [ ] 理解了所有接口的输入输出
+- [ ] 知道代码应该放在哪个目录
+- [ ] 了解现有的命名约定和模式
+- [ ] 识别出可能的风险点和疑问（如有，先问再动手）
+
+#### Step ②: 编码实现
+
+**编码规范速查**：
+
+```javascript
+// ✅ 正确示例
+interface UserProfile {
+  id: string;           // 用户唯一标识
+  name: string;         // 用户显示名
+  email: string;        // 登录邮箱
+  createdAt: Date;      // 注册时间
+}
+
+// ❌ 错误示例
+// 裸 any —— 必须注释说明为什么无法确定类型
+const data: any = fetchData();
+
+// ❌ 错误示例
+// 硬编码密钥
+const API_KEY = 'sk-abc123456789';
+// 应该用环境变量 process.env.API_KEY
+```
+
+**文件命名约定**：
+
+| 类型 | 约定 | 示例 |
+|-----|------|------|
+| 组件文件 | PascalCase + .tsx | `UserProfile.tsx` |
+| 工具函数 | camelCase + .ts | `formatDate.ts` |
+| 类型定义 | camelCase + .types.ts | `user.types.ts` |
+| 常量 | UPPER_SNAKE_CASE.ts | `API_ENDPOINTS.ts` |
+| 测试文件 | *.test.ts / *.spec.ts | `UserProfile.test.ts` |
+| Hook 文件 | use + PascalCase | `useUserProfile.ts` |
+
+#### Step ③: 编写/更新单元测试
+
+**测试覆盖率要求**：
+
+| 代码类型 | 行覆盖率目标 | 分支覆盖率目标 |
+|---------|------------|--------------|
+| 核心业务逻辑 | ≥ 85% | ≥ 75% |
+| 工具函数 | ≥ 90% | ≥ 80% |
+| 组件渲染 | ≥ 70% | ≥ 60% |
+| 配置/常量 | ≥ 50% | - |
+
+**测试命名约定**：
+
+```typescript
+// ✅ 正确：describe + it 清晰表达意图
+describe('UserProfile', () => {
+  describe('getUserById', () => {
+    it('当用户存在时返回用户信息', async () => {...});
+    it('当用户不存在时抛出 NotFoundError', async () => {...});
+    it('当 ID 格式无效时抛出 ValidationError', async () => {...});
+  });
+});
+
+// ❌ 错误：模糊的测试名
+it('should work', () => {...});
+it('test user', () => {...});
+```
+
+#### Step ④: Build 检查
+
+```bash
+# 前端项目
+npm run build          # 或 pnpm build
+# 或 TypeScript 类型检查
+npx tsc --noEmit
+
+# 后端项目
+npm run compile        # 或对应编译命令
+```
+
+**通过标准**：
+- ✅ 零编译错误
+- ✅ 零 TypeScript 类型错误（error 级别）
+- ⚠️ warning 可以存在但建议修复
+
+#### Step ⑤: 单元测试执行
+
+```bash
+# 运行全部测试
+npm test              # 或 npm run test:unit
+
+# 运行特定文件的测试
+npm test -- --grep "UserProfile"
+
+# 生成覆盖率报告
+npm test -- --coverage
+```
+
+**通过标准**：
+- ✅ 所有测试用例通过
+- ✅ 覆盖率达到上述目标值
+- ⚠️ 覆盖率低于基线但高于最低门槛 → WARNING
+
+#### Step ⑥: Lint 检查
+
+```bash
+# ESLint 检查
+npx eslint src/ --ext .ts,.tsx
+
+# Prettier 格式化检查
+npx prettier --check "src/**/*.{ts,tsx}"
+
+# 一键修复（自动修复的问题）
+npx eslint src/ --ext .ts,.tsx --fix
+npx prettier --write "src/**/*.{ts,tsx}"
+```
+
+**通过标准**：
+- ✅ ESLint: 零 error，零 warning（理想状态）
+- ✅ Prettier: 格式完全符合
+- ⚠️ 存在 warning 时必须说明理由（加 // eslint-disable-next-line 注释）
+
+#### Step ⑦: 更新 dev-map
+
+**何时必须更新**：
+- 新增了模块/目录/页面
+- 修改了公共组件的接口
+- 变更了 API 路由
+- 修改了数据库表结构
+- 变更了状态管理方式
+
+**不需要更新的情况**：
+- 只改了组件内部实现
+- 修复了 bug 未涉及结构变化
+- 调整了样式
+
+**更新格式**：
+
+```markdown
+<!-- 在对应的 dev-map 文件中追加 -->
+
+### {日期} 更新记录
+- **更新人**: {姓名}
+- **变更类型**: 新增模块 / 接口变更 / 结构调整
+- **变更内容**: 
+  - 新增 `src/features/user-profile/` 目录
+  - 新增 API: GET /api/users/:id
+  - 更新 User 类型定义
+- **影响范围**: 前端用户模块、后端用户 API
+```
+
+#### Step ⑧: 规范 Commit + 创建 PR
+
+**Commit Message 规范（Conventional Commits）**：
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+**Type 列表**：
+
+| Type | 用途 | 示例 |
+|------|------|------|
+| feat | 新功能 | `feat(auth): add OAuth2 login support` |
+| fix | Bug 修复 | `fix(api): resolve timeout issue in user fetch` |
+| docs | 文档变更 | `docs(readme): update installation steps` |
+| style | 代码格式（不影响功能） | `style(button): fix indentation` |
+| refactor | 重构（非新功能非修复） | `refactor(service): extract validation logic` |
+| perf | 性能优化 | `perf(list): virtualize long list rendering` |
+| test | 测试相关 | `test(user): add edge case tests` |
+| chore | 构建/工具变更 | `chore(deps): update eslint to v9` |
+
+**PR/MR 模板**：
+
+```markdown
+## 变更概述
+{简要描述这个 PR 做了什么}
+
+## 关联需求
+- 需求文档: #{Issue链接}
+- 设计文档: {design-{id}.md}
+
+## 变更类型
+- [ ] 新功能
+- [ ] Bug 修复
+- [ ] 重构
+- [ ] 文档更新
+- [ ] 其他: ___
+
+## 测试清单
+- [ ] 单元测试已添加/更新并通过
+- [ ] 覆盖率达标: __%
+- [ ] 手动测试通过
+- [ ] 无 console.log/debugger 残留
+
+## 自检报告
+- Build: ✅ PASS / ❌ FAIL
+- Test: ✅ PASS (覆盖率 __%) / ❌ FAIL
+- Lint: ✅ PASS / ❌ FAIL (___ warnings)
+
+## 影响面分析
+- 涉及模块: ___
+- 潜在风险: ___
+- dev-map 更新: [是/否] ({文件路径})
+
+## 截图/Demo（UI 变更必填）
+{附截图或 Demo 链接}
+```
+
+---
+
+## 三、代码审查规范（审查者身份）
+
+### 3.1 审查维度与权重
+
+| 维度 | 权重 | 检查项 |
+|-----|------|-------|
+| **A. 代码质量** | 30% | A1 命名清晰度、A2 复杂度控制、A3 类型安全、A4 错误处理、A5 DRY原则、A6 可读性 |
+| **B. 规范遵循** | 15% | B1 Commit 规范、B2 分支策略、B3 PR 描述完整性、B4 文档同步、B5 文件组织 |
+| **C. 安全与风险** | 25% | C1 凭证管理、C2 注入防护、C3 权限控制、C4 敏感数据处理、C5 依赖安全 |
+| **D. 性能考量** | 10% | D1 N+1 查询、D2 内存泄漏、D3 包体积、D4 渲染性能 |
+| **E. 测试覆盖** | 20% | E1 测试存在性、E2 覆盖率达标、E3 测试质量 |
+
+### 3.2 裁决标准
+
+#### FAIL（直接打回）— 以下任一条件触发
+
+- [ ] **C 类安全检查不通过**（最高优先级）
+- [ ] **A 类总分 < 60%**
+- [ ] **新代码完全没有测试**
+- [ ] **单 PR > 1000 行且无合理拆分理由**
+- [ ] **测试覆盖率回归 > 5%**
+
+#### CONDITIONAL_PASS（修后可通过）
+
+- [ ] 总分 ≥ 80%，但存在 **必修问题**
+- [ ] 必须列出：
+  - 🔴 **必修问题**（必须修才能合入）
+  - 🟡 **建议改进**（本轮可不修，建议开跟踪 Issue）
+
+#### PASS（直接通过）
+
+- [ ] 总分 ≥ 90%
+- [ ] 无安全问题
+- [ ] 无必修问题
+- [ ] 覆盖率达标或提升
+
+### 3.3 审查评论规范
+
+```markdown
+## 🔴 必修问题
+
+### C1-凭证泄露风险
+**位置**: `src/api/client.ts:23`
+**问题**: API Key 不应出现在代码中，应使用环境变量。
+**建议**: 改为 `process.env.API_KEY`
+**严重程度**: 高
+
+## 🟡 建议改进
+
+### A1-变量命名
+**位置**: `src/utils/helper.ts:45`
+**问题**: 变量名 `data` 过于泛型
+**建议**: 改为更具描述性的名字如 `userData`
+**严重程度**: 低（可选）
+
+---
+**审查结论**: CONDITIONAL_PASS
+**总分**: 82/100
+**必修问题数**: 1
+**建议改进数**: 2
+```
+
+---
+
+## 四、Gate 门禁检查详解
+
+### 4.1 五类检查一览
+
+| 类别 | 检查脚本 | 检查内容 | 失败后果 |
+|-----|---------|---------|---------|
+| **A 静态规范** | `static-compliance.js` | ESLint/Prettier/console残留/硬编码/TODO/命名/Secret | WARNING/FAIL |
+| **B 构建门槛** | `build-gates.js` | 前端build/后端编译/Docker构建/TS类型检查/依赖安装 | **FAIL** |
+| **C 测试合规** | `test-compliance.js` | 单元测试/E2E/API集成/测试数量对比 | **FAIL** |
+| **D 安全质量** | `security-quality.js` | CVE依赖审计/CR Approval状态 | **FAIL** |
+| **E 一致性** | `engineering-consistency.js` | CHANGELOG/迁移文件/dev-map/配置同步 | WARNING/FAIL |
+
+### 4.2 运行门禁检查
+
+```bash
+# 完整检查
+node .harness/gate/index.js
+
+# 只生成报告
+node .harness/gate/index.js --report
+
+# 与基线对比（检测回归）
+node .harness/gate/index.js --baseline
+
+# 保存当前状态为新基线
+node .harness/gate/index.js --save-baseline
+```
+
+### 4.3 基线对比机制
+
+**首次运行**：
+```bash
+# 在项目稳定状态下保存基线
+node .harness/gate/index.js --save-baseline
+# → 生成 .harness/gate/baseline.json
+```
+
+**后续对比**：
+```bash
+# 每次 PR 前对比基线
+node .harness/gate/index.js --baseline
+# → 输出 REGRESSION（退化）或 IMPROVEMENT（改进）标记
+```
+
+**回归判定规则**：
+- 测试覆盖率下降 > 5% → **REGRESSION 自动打回**
+- 新增 A/B 类 FAIL → **自动打回**
+- 安全高危问题 → **立即阻断**
+
+---
+
+## 五、dev-map 维护规范
+
+### 5.1 原则：谁改代码谁改地图
+
+```
+你修改了代码 → 检查是否影响 dev-map → 是 → 更新 → 提交时包含 dev-map 变更
+                                    → 否 → 继续正常提交
+```
+
+### 5.2 dev-map 目录结构
+
+```
+.harness/dev-map/
+├── overview.md              # 总览索引 ← PM 维护
+├── frontend/
+│   ├── structure.md         # 目录结构与路由 ← 前端开发维护
+│   ├── components.md        # 组件库与复用模式 ← 前端开发维护
+│   ├── state-management.md  # 状态管理 ← 前端开发维护
+│   ├── api-integration.md   # 前端 API 调用 ← 前端+后端共同维护
+│   └── conventions.md       # 前端编码惯例 ← 前端开发维护
+├── backend/
+│   ├── structure.md         # 模块划分与分层 ← 后端开发维护
+│   ├── database.md          # 数据模型与迁移 ← 后端开发维护
+│   ├── api-definition.md    # API 设计规范 ← 后端开发维护
+│   ├── auth-security.md     # 认证与安全 ← 后端+安全组维护
+│   └── conventions.md       # 后端编码惯例 ← 后端开发维护
+└── decisions.md             # ADR 决策记录 ← 架构师+开发者共同维护
+```
+
+### 5.3 更新 Checklist
+
+提交代码前自查：
+
+- [ ] 我修改/新增了哪些文件？
+- [ ] 这些变更是否影响了已有的架构描述？
+- [ ] 是否新增了需要记录的 API 端点？
+- [ ] 是否引入了新的依赖或技术选型？（需要 ADR 吗？）
+- [ ] 如果以上任一为"是"，dev-map 是否已同步更新？
+
+---
+
+## 六、绩效考核关联指标
+
+| 指标 | 目标值 | 权重 | 数据来源 |
+|-----|-------|------|---------|
+| 代码质量评分（CR A类） | ≥ 75% | 20% | Code Review 记录 |
+| 安全违规次数 | = 0 高危 | 20%（一票否决） | Gate D 类 + CR C类 |
+| 单元测试覆盖率 | 达标率 ≥ 90% | 15% | Gate C 类报告 |
+| 自检通过率（首次） | ≥ 70% | 15% | PR 打回记录 |
+| dev-map 同步率 | ≥ 95% | 10% | 抽查 |
+| Code Review 及时性 | ≤ 24h 响应 | 10% | CR 响应时间 |
+| Commit 规范遵循 | 100% 符合 | 10% | Git log 抽查 |
+
+---
+
+## 七、常用命令速查
+
+```bash
+# === 开发日常 ===
+npm run dev              # 启动开发服务器
+npm run build            # 构建检查
+npm test                 # 运行测试
+npm run lint             # ESLint 检查
+npm run format           # Prettier 格式化
+
+# === Gate 检查 ===
+node .harness/gate/index.js                     # 完整检查
+node .harness/gate/index.js --save-baseline     # 保存基线
+node .harness/gate/index.js --baseline          # 对比基线
+
+# === Workflow 校验 ===
+node .harness/workflow/validate.js              # 校验流程完整性
+
+# === 规则查询 ===
+cat .harness/rules/global/coding-standard.md   # 编码规范
+cat .harness/rules/global/security-baseline.md  # 安全红线
+cat .harness/rules/global/commit-convention.md  # 提交规范
+
+# === Skill 参考 ===
+cat .harness/skills/build.md                    # 构建技能
+cat .harness/skills/code-review.md              # 审查技能
+cat .harness/skills/test-unit.md                # 单测技能
+```
+
+---
+
+## 八、开发者自查清单
+
+### 提交 PR 前（必须逐条确认）
+
+#### 代码质量
+- [ ] 命名清晰有意义（无 a/b/tmp 之类）
+- [ ] 无裸 `any` 类型（或有充分注释说明理由）
+- [ ] 函数/方法长度合理（一般不超过 50 行）
+- [ ] 无重复代码（DRY 原则）
+- [ ] 错误处理完善（try-catch / Result 类型）
+
+#### 安全检查
+- [ ] 无硬编码密钥/token/密码
+- [ ] 无 SQL 注入/XSS 风险
+- [ ] 敏感数据有脱敏处理
+- [ ] API 调用有权限校验
+
+#### 测试
+- [ ] 新增代码有对应单元测试
+- [ ] 覆盖率达到目标值
+- [ ] 测试命名清晰表达意图
+- [ ] 无跳过的测试（skip/it.skip）
+
+#### 规范
+- [ ] Commit message 符合 Conventional Commits
+- [ ] PR 描述完整（使用了模板）
+- [ ] 分支名符合规范（feature/xxx, fix/xxx 等）
+- [ ] 无 console.log / debugger 残留
+- [ ] 无 TODO/FIXME 残留（或有跟踪 Issue）
+
+#### 文档
+- [ ] dev-map 已更新（如有结构性变化）
+- [ ] 复杂逻辑有注释说明"为什么"而非"是什么"
+
+---
+
+## 九、Java 后端开发者附加指南
+
+> **参考规则**: `rules/project/java-backend.md` | **构建技能**: `skills/java-build.md` | **Dev-map**: `dev-map/backend/conventions-java.md`
+
+### 9.1 日常开发 Checklist
+
+```bash
+# === 编译 ===
+mvn clean compile                    # 编译检查
+
+# === 测试 ===
+mvn test                             # 运行全部单元测试
+mvn test -Dtest=UserServiceTest      # 指定测试类
+mvn test jacoco:report               # 生成覆盖率报告（目标 ≥80%）
+
+# === 打包 ===
+mvn package -DskipTests              # 跳过测试打包
+
+# === 快速诊断 ===
+mvn clean compile -e                 # 显示完整错误堆栈
+mvn dependency:tree                  # 查看依赖树
+```
+
+### 9.2 各层自检要点
+
+| 层级 | 自检要点 | 参考规则 |
+|------|---------|----------|
+| Controller | 只做路由+校验？@PostMapping？@Valid？返回 CommonResult？ | JB-A1, JB-C1/C4 |
+| Service | 接口+impl 分离？@RequiredArgsConstructor？事务最小化？外部调用放事务外？ | JB-A2, JB-E5 |
+| Mapper | 纯接口？SQL 在 XML？#{}` 预编译？无 @Select 注解？ | JB-A3, JB-D1/D2 |
+| Entity/VO | 类后缀正确？字段 private？时间用 LocalDateTime？ | JB-B2, A28 |
+
+### 9.3 提交 PR 前 — 后端 22 项自查清单
+
+#### 架构与分层（4 项）
+- [ ] Controller 只做路由和参数校验，无业务逻辑
+- [ ] Service 做业务编排（非 CRUD 直通 Mapper）
+- [ ] Mapper 为纯接口且 SQL 在 XML 中
+- [ ] 模块依赖方向正确（无循环/反向/跨层跳跃）
+
+#### 命名与规范（5 项）
+- [ ] 包名为 `com.jieshun`
+- [ ] 类后缀符合 9 种标准后缀
+- [ ] public 类有完整 Javadoc
+- [ ] 方法命名清晰表达意图
+- [ ] 常量使用 UPPER_SNAKE_CASE
+
+#### 参数与返回值（4 项）
+- [ ] Controller 参数有 JSR303 校验注解
+- [ ] 使用 ReqVO/RespVO 分层传参
+- [ ] 禁止 Map 和 Entity 直接暴露
+- [ ] 返回值使用统一 Result 封装
+
+#### 数据库与 SQL（3 项）
+- [ ] SQL 使用 `#{}` 预编译
+- [ ] 分页使用拦截器（非手动 LIMIT）
+- [ ] 表结构变更已有 ALTER 脚本
+
+#### 安全与质量（6 项）
+- [ ] 敏感数据 SM4 加密存储
+- [ ] 响应数据已脱敏
+- [ ] Redis key 有 TTL
+- [ ] 日志使用 `{}` 参数化
+- [ ] 事务范围最小化
+- [ ] 虚拟线程中无 synchronized（改 ReentrantLock）
+
+### 9.4 虚拟线程注意事项
+
+```java
+// ✅ 正确：虚拟线程 + ReentrantLock
+private final ReentrantLock lock = new ReentrantLock();
+
+// ❌ 错误：虚拟线程 + synchronized → 导致 pinning！
+public synchronized void badMethod() { ... }
+```
+
+**核心原则**: JDK21 虚拟线程环境下，**synchronized 会导致 pinning**（固定到平台线程），失去虚拟线程优势。必须使用 `ReentrantLock` 替代。
+
+### 9.5 Redis 操作常见坑点
+
+| 坑点 | 正确做法 |
+|------|---------|
+| 忘记设置 TTL | 写入时 **必须** 设置过期时间 |
+| 手写 SETNX 实现锁 | 使用 **Redisson** 的 RLock |
+| Key 命名随意 | 统一定义在 **RedisKeyConstants** 常量类 |
+| 把 Redis 当数据库用 | Redis **仅用于缓存**，禁止持久化场景 |
+
+---
+
+## 十、Vue3 前端开发者附加指南
+
+> **参考规则**: `rules/project/frontend-vue3.md` | **构建技能**: `skills/vue-frontend-build.md` | **Dev-map**: `dev-map/frontend/conventions.md`
+
+### 10.1 日常开发 Checklist
+
+```bash
+# === 开发服务器 ===
+npm run dev                          # 启动 Vite 开发服务器
+
+# === 类型检查 ===
+npx vue-tsc --noEmit                 # TypeScript 类型检查
+
+# === 构建 ===
+npm run build                        # 生产构建
+npm run build -- --mode analyze      # 构建分析（包体积）
+
+# === Lint + Format ===
+npx eslint src/ --ext .ts,.tsx,.vue  # ESLint 检查
+npx prettier --write "src/**/*.{ts,vue}"  # 格式化
+npm run lint:fix                     # 自动修复
+
+# === 测试 ===
+npm test / npx vitest run           # Vitest 单元测试
+npx vitest run --coverage            # 带覆盖率
+```
+
+### 10.2 组件编写自检要点
+
+| 检查项 | 要求 |
+|--------|------|
+| API 用法 | `<script setup lang="ts">` |
+| Props 定义 | TS interface 或 `defineProps<T>()` |
+| 类型安全 | 无裸 any（或注释说明理由）|
+| Element Plus | ElMessage 反馈、v-loading 加载、图标包裹 |
+| Pinia Store | 跨组件状态走 Store，禁 prop drilling > 2 层 |
+| 变量命名 | camelCase(变量) / UPPER_SNAKE_CASE(常量) / is前缀(布尔) / handle前缀(事件) |
+
+### 10.3 提交 PR 前 — 前端自查清单
+
+- [ ] 全部使用 Composition API（无 Options API）
+- [ ] Props 有明确 TS 类型定义
+- [ ] 无裸 any 类型（或有注释说明）
+- [ ] Element Plus 组件规范使用正确
+- [ ] 文件命名符合 PascalCase（组件）+ kebab-case（目录）
+- [ ] `npx vue-tsc --noEmit` 零 Type Error
+- [ ] `npm run build` 构建成功
+- [ ] ESLint 零 error，零 warning（理想状态）
+- [ ] 新增代码有对应单测，覆盖率达标
+- [ ] 无 console.log / debugger 残留
+
+### 10.4 Pinia Store 使用规范
+
+```typescript
+// ✅ 正确：标准 Store 结构
+export const useUserStore = defineStore('user', {
+  state: () => ({ userInfo: null, token: '' }),   // 有类型
+  getters: {
+    isLoggedIn: (state) => !!state.token,          // 计算属性派生
+    isAdmin: (state) => state.permissions.includes('admin'),
+  },
+  actions: {
+    async login(credentials) { /* ... */ },         // 异步操作
+    logout() { this.$reset(); },                    // 重置
+  },
+});
+```
+
+**Store 规范**:
+- State 字段必须有 TS 类型
+- Getters 用于计算派生数据
+- Actions 用于异步操作和批量修改
+- 禁止在组件外直接修改 State（通过 Actions 修改）
+
+### 10.5 Element Plus 常见用法速查
+
+| 场景 | 用法 |
+|------|------|
+| 成功提示 | `ElMessage.success('操作成功')` |
+| 错误提示 | `ElMessage.error('操作失败')` |
+| 确认弹窗 | `await ElMessageBox.confirm('确定?', '提示', {...})` |
+| 加载状态 | `<div v-loading="isLoading">内容</div>` |
+| 表单校验 | `<el-form :model="form" :rules="rules">` |
+| 分页 | `<el-pagination :total="total" @current-change="handlePageChange" />` |
+
+---
+
+*本规范是研发团队在 Harness 体系中的完整操作指南。请严格遵守，保护代码质量和团队协作效率。*