jsharness 1.5.0 → 1.8.0

package/.harness/commands/js/build-gates-frontend.md

@@ -0,0 +1,33 @@
+---
+name: build-gates-frontend
+description: 前端构建门槛 — TypeScript 类型检查、依赖完整性、构建验证、ESLint
+---
+
+# 前端构建门槛 (Frontend Build Gates)
+
+> **源文件**: `.harness/gate/checks/build-gates-frontend.js`
+> **类别**: B 类 — 构建门槛 (前端)
+
+适用于 `package.json` 存在的项目（Vue3/Vite 等）。
+
+## 检查项
+
+| 编号 | 检查项 | 说明 | 阻塞 |
+|------|--------|------|------|
+| F-B1 | TypeScript 类型检查 | `tsc --noEmit` | 是 |
+| F-B2 | 依赖完整性检查 | `npm/pnpm ls` | 是 |
+| F-B3 | 前端构建 | `npm run build` | 是 |
+| F-B4 | ESLint 快速检查 | `npx eslint` | 是 |
+| F-B5 | npm 安全审计 | `npm audit` | 否（可选） |
+
+## 通过条件
+
+- F-B1 ~ F-B4 全部 PASS
+- 无 HIGH/CRITICAL 安全漏洞（F-B5 可选）
+
+## 失败条件
+
+- TypeScript 编译错误 → FAIL
+- 依赖缺失或版本冲突 → FAIL
+- 构建失败 → FAIL
+- ESLint 存在 error → FAIL

package/.harness/commands/js/build-gates-java.md

@@ -0,0 +1,33 @@
+---
+name: build-gates-java
+description: Java 后端构建门槛 — Maven 编译、单元测试、Checkstyle、依赖分析
+---
+
+# Java 后端构建门槛 (Java Build Gates)
+
+> **源文件**: `.harness/gate/checks/build-gates-java.js`
+> **类别**: B 类 — 构建门槛 (Java)
+
+适用于 `pom.xml` 存在的 Spring Boot / Maven 项目（JDK21 + Spring Boot）。
+
+## 检查项
+
+| 编号 | 检查项 | 说明 | 阻塞 |
+|------|--------|------|------|
+| J-B1 | Maven 编译检查 | `mvn clean compile` | 是 |
+| J-B2 | 单元测试快速验证 | `mvn test` | 是 |
+| J-B3 | Checkstyle 代码风格检查 | `mvn checkstyle:check` | 是 |
+| J-B4 | 依赖树分析 | `mvn dependency:tree` | 否 |
+| J-B5 | SpotBugs Bug 扫描 | `mvn spotbugs:check` | 否（可选） |
+| J-B6 | JaCoCo 覆盖率门禁 | `mvn jacoco:check` | 否（可选） |
+
+## 通过条件
+
+- J-B1 ~ J-B3 全部 PASS
+- 编译零错误，单元测试全部通过
+
+## 失败条件
+
+- Maven 编译失败 → FAIL
+- 单元测试失败 → FAIL
+- Checkstyle 违规 → FAIL

package/.harness/commands/js/build-gates.md

@@ -0,0 +1,32 @@
+---
+name: build-gates
+description: 构建门槛检查 — 自动检测项目类型并分发到对应的门禁检查模块
+---
+
+# 构建门槛检查 (Build Gates)
+
+> **源文件**: `.harness/gate/checks/build-gates.js`
+> **类别**: B 类 — 构建门槛
+
+自动检测项目类型并分发到对应的门禁检查模块：
+- 检测到 `pom.xml` → 调用 build-gates-java.js (Maven/Java)
+- 检测到 `package.json` → 调用 build-gates-frontend.js (Node/前端)
+- 都没有 → 返回 warning
+
+## 检查项
+
+| 编号 | 检查项 | 说明 |
+|------|--------|------|
+| B1 | 项目类型检测 | 检测 pom.xml / package.json 确定项目类型 |
+| B2 | 前端构建 | TypeScript 类型检查 + 依赖完整性 + npm run build + ESLint |
+| B3 | Java 构建 | Maven 编译 + 单元测试 + Checkstyle + 依赖树分析 |
+
+## 通过条件
+
+- 项目类型检测成功（Java 或 Frontend）
+- 对应子模块的构建检查全部 PASS
+
+## 失败条件
+
+- 无法检测项目类型 → WARNING
+- 子模块构建失败 → FAIL

package/.harness/commands/js/engineering-consistency.md

@@ -0,0 +1,29 @@
+---
+name: engineering-consistency
+description: 工程一致性检查 — CHANGELOG 更新、dev-map 一致性、配置同步
+---
+
+# 工程一致性检查 (Engineering Consistency)
+
+> **源文件**: `.harness/gate/checks/engineering-consistency.js`
+> **类别**: E 类 — 工程一致性
+
+## 检查项
+
+| 编号 | 检查项 | 说明 |
+|------|--------|------|
+| E1 | CHANGELOG 更新检查 | 检查 Unreleased 区域是否有内容 |
+| E2 | dev-map 一致性检查 | 检查 dev-map 与实际代码是否一致 |
+| E3 | 配置同步检查 | 检查各配置文件是否同步 |
+
+## 通过条件
+
+- CHANGELOG Unreleased 区域有内容
+- dev-map 与代码一致
+- 配置文件同步
+
+## 失败条件
+
+- CHANGELOG 未更新 → WARNING
+- dev-map 不一致 → WARNING
+- 配置不同步 → WARNING

package/.harness/commands/js/security-quality.md

@@ -0,0 +1,27 @@
+---
+name: security-quality
+description: 安全与质量检查 — CVE 依赖审计、Code Review Approval 状态
+---
+
+# 安全与质量检查 (Security & Quality)
+
+> **源文件**: `.harness/gate/checks/security-quality.js`
+> **类别**: D 类 — 安全与质量
+
+## 检查项
+
+| 编号 | 检查项 | 说明 |
+|------|--------|------|
+| D1 | npm audit 安全审计 | 检测 CVE 漏洞（HIGH/CRITICAL 级别） |
+| D2 | Code Review Approval | 检查代码审查状态（通过 Git 信息判断） |
+
+## 通过条件
+
+- 安全评分 ≥ 80 分
+- 无 CRITICAL 级别 CVE 漏洞
+- HIGH 级别漏洞有修复计划
+
+## 失败条件
+
+- 存在 CRITICAL 级别漏洞 → FAIL
+- 安全评分 < 60 分 → FAIL

package/.harness/commands/js/static-compliance.md

@@ -0,0 +1,35 @@
+---
+name: static-compliance
+description: 静态合规检查 — ESLint、Prettier、console.log 残留、硬编码字符串、Secret 泄露检测
+---
+
+# 静态合规检查 (Static Compliance)
+
+> **源文件**: `.harness/gate/checks/static-compliance.js`
+> **类别**: A 类 — 静态合规
+
+## 检查项
+
+| 编号 | 检查项 | 说明 |
+|------|--------|------|
+| A1 | ESLint 检查 | 零 error，零 warning |
+| A2 | Prettier 格式化 | 格式化后无 diff 变更 |
+| A3 | console.log / debugger 残留 | 禁止残留到生产代码 |
+| A4 | 硬编码字符串检测 | 检测未国际化的中文字符串 |
+| A5 | TODO/FIXME 残留 | 检测遗留的 TODO/FIXME |
+| A6 | 命名规范检查 | 检查文件名/变量名是否符合规范 |
+| A7 | 文件长度限制 | 单文件不超过 300 行 |
+| A8 | Secret 泄露检测 | 检测硬编码的密钥/Token/密码 |
+
+## 通过条件
+
+- ESLint 零错误
+- Prettier 格式一致
+- 无 console.log / debugger 残留
+- 无 Secret 泄露
+
+## 失败条件
+
+- ESLint 存在 error → FAIL
+- Secret 泄露检测命中 → FAIL（安全红线）
+- console.log / debugger 残留 → FAIL

package/.harness/commands/js/task-board-maintenance.md

@@ -0,0 +1,68 @@
+---
+name: task-board-maintenance
+description: TaskBoard 维护命令 — 任务注册/状态流转/周报生成/看板同步
+alwaysApply: false
+enabled: true
+---
+
+# TaskBoard 维护 Command
+
+> **执行角色**: PM Agent / 工作流引擎
+> **触发时机**: 任务状态变更时、每日定时、周报生成前
+> **源文件**: `.harness/skills/task-board-maintenance/SKILL.md` (已迁移为 command)
+
+---
+
+## 操作清单
+
+### 1. 新任务注册
+
+当 PM 收到新需求时：
+
+- 分配 Task ID（格式：TASK-YYYYMMDD-NNN）
+- 判断流程变体类型：
+  - 新功能 → 标准七阶段流程
+  - Bug 修复 → Bug 修复轻量流程
+  - P0/P1 生产问题 → 热修最快路径
+  - 文档/配置变更 → 微型流程
+  - 安全漏洞 → 安全响应流程
+- 在「待开始任务」表添加一行
+- 检查是否与历史任务重复
+- 如有关联的 Issue/PR，填入对应编号
+- 更新「新增需求」计数器
+
+### 2. 状态推进
+
+当一个阶段完成，需要推入下一阶段：
+
+- 从当前区域移动目标任务到下一区域
+- 更新「当前阶段」字段
+- 更新「负责Agent」字段为下一个角色
+- 更新「上次更新」为当前时间
+- 在备注中记录简要原因
+- 如果是打回，在「备注」中注明打回原因和来源角色
+
+### 3. 交付归档
+
+测试 PASS 后：
+
+- 移动到「已完成」区域
+- 填写「交付结论」（PASS / CONDITIONAL_PASS）
+- 计算「实际周期」
+- 填写「归档日期」
+- 收集各阶段文档链接
+- 更新度量指标
+
+### 4. 定期维护
+
+**每日检查**（PM Agent 自动执行）：
+- 检查是否有超时未更新的任务（超过 48 小时）
+- 检查是否有阻塞超过 24 小时的任务
+- 更新「最后更新」时间戳
+
+**每周清理**（PM Agent 手动执行）：
+- 清理已取消或合并的重复条目
+- 确认已完成任务都已正确归档
+- 生成周度度量报告
+- 识别瓶颈阶段
+- 汇总流程违规情况并提出改进建议

package/.harness/commands/js/test-compliance.md

@@ -0,0 +1,30 @@
+---
+name: test-compliance
+description: 测试合规检查 — 单元测试执行与覆盖率、E2E 测试、API 集成测试
+---
+
+# 测试合规检查 (Test Compliance)
+
+> **源文件**: `.harness/gate/checks/test-compliance.js`
+> **类别**: C 类 — 测试合规
+
+## 检查项
+
+| 编号 | 检查项 | 说明 |
+|------|--------|------|
+| C1 | 单元测试 | `npm run test -- --coverage` |
+| C2 | E2E 关键路径测试 | 可选 |
+| C3 | API 集成测试 | 可选 |
+| C4 | 测试数量对比 | 基线模式，检测测试是否减少 |
+
+## 通过条件
+
+- 单元测试全部 PASS
+- 覆盖率不低于基线
+- 测试数量未减少
+
+## 失败条件
+
+- 单元测试失败 → FAIL
+- 覆盖率低于基线 → WARNING
+- 测试数量减少 → WARNING

package/.harness/dev-map/backend/api-definition.md

@@ -25,7 +25,7 @@ POST   /api/v1/orders/:id/cancel    # 取消订单
 POST   /api/v1/auth/refresh          # 刷新 Token
 
 # 过滤/排序/分页
-GET    /api/v1/users?role=admin&page=1&pageSize=20&sort=createdAt-desc
+GET    /api/v1/users?role=admin&pageNo=1&pageSize=20&sort=createdAt-desc
 ```
 
 ### 统一响应格式
@@ -34,7 +34,7 @@ GET    /api/v1/users?role=admin&page=1&pageSize=20&sort=createdAt-desc
 
 ```json
 {
-  "code": 0,
+  "code": 200,
   "data": { ... },
   "message": "success",
   "timestamp": 1700000000000
@@ -45,15 +45,13 @@ GET    /api/v1/users?role=admin&page=1&pageSize=20&sort=createdAt-desc
 
 ```json
 {
-  "code": 0,
+  "code": 200,
   "data": {
-    "items": [ ... ],
-    "pagination": {
-      "page": 1,
-      "pageSize": 20,
-      "total": 150,
-      "totalPages": 8
-    }
+    "list": [ ... ],
+    "total": 150,
+    "pageNo": 1,
+    "pageSize": 20,
+    "pages": 8
   },
   "message": "success",
   "timestamp": 1700000000000
@@ -64,7 +62,7 @@ GET    /api/v1/users?role=admin&page=1&pageSize=20&sort=createdAt-desc
 
 ```json
 {
-  "code": 20001,
+  "code": 400,
   "message": "参数校验失败",
   "details": [
     {
@@ -99,7 +97,7 @@ GET    /api/v1/users?role=admin&page=1&pageSize=20&sort=createdAt-desc
 
 | 参数 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
-| `page` | integer | 1 | 页码（从 1 开始）|
+| `pageNo` | integer | 1 | 页码（从 1 开始）|
 | `pageSize` | integer | 20 | 每页数量（最大 100）|
 | `sort` | string | `-createdAt` | 排序字段（`-` 表示降序）|
 

package/.harness/dev-map/backend/auth-security.md

@@ -62,21 +62,42 @@
 | `viewer` | 只读访问 | 只读用户 |
 | `user` | 自身数据的读写 | 普通注册用户 |
 
-### 权限守卫实现
-
-```typescript
-@UseGuards(JwtAuthGuard)
-@Roles(Role.ADMIN, Role.EDITOR)
-@Controller('admin/posts')
-export class AdminPostController {
-  // 只有 admin 和 editor 才能访问
-  @Post()
-  createPost() {}
+### Spring Security 权限校验实现
+
+```java
+// ========== 权限注解使用 ==========
+@RestController
+@RequestMapping("/api/v1/admin/users")
+@RequiredArgsConstructor
+public class AdminUserController {
+
+    @PreAuthorize("hasRole('ADMIN') or hasRole('SUPER_ADMIN')")
+    @GetMapping
+    @Operation(summary = "分页查询用户（后台管理）")
+    public CommonResult<PageResult<UserRespVO>> page(@Valid UserPageReqVO reqVO) {
+        return success(userService.getUserPage(reqVO));
+    }
+
+    @PreAuthorize("hasRole('SUPER_ADMIN')")
+    @DeleteMapping("/{id}")
+    @Operation(summary = "删除用户")
+    public CommonResult<Boolean> delete(@PathVariable("id") Long id) {
+        userService.deleteUser(id);
+        return success(true);
+    }
 }
 
-@Roles(Role.ADMIN)  // 只有 admin
-@Delete(':id')
-deletePost() {}
+// ========== 方法级资源权限校验 ==========
+@Service
+@RequiredArgsConstructor
+public class ProjectServiceImpl implements ProjectService {
+
+    @Override
+    @PreAuthorize("hasPermission(#projectId, 'project', 'edit')")
+    public void updateProject(Long projectId, ProjectUpdateReqVO reqVO) {
+        // 只有项目成员才能编辑
+    }
+}
 ```
 
 ### 权限矩阵
@@ -90,42 +111,46 @@ deletePost() {}
 | 数据查看 | ✅ | ✅ | ✅ | ✅ | 自身 |
 | 系统配置 | ✅ | ❌ | ❌ | ❌ | ❌ |
 
-## 安全中间件链
+## Spring Security 过滤器链
 
 ```
 请求进入
   │
-  ├── Helmet (安全头设置)
+  ├── SecurityHeadersFilter (安全头设置)
   │   ├── X-Frame-Options: DENY
   │   ├── X-Content-Type-Options: nosniff
   │   └── X-XSS-Protection: 1; mode=block
   │
-  ├── Rate Limiter (速率限制)
+  ├── RateLimitFilter (速率限制 — 基于 Redis + Redisson)
   │   ├── 全局: 100 req/min
   │   ├── 登录: 5 req/min (同一 IP)
   │   └── API: 60 req/min (同一用户)
   │
-  ├── CORS (跨域控制)
+  ├── CorsFilter (跨域控制 — Spring 配置)
   │   ├── Allow-Origin: [白名单]
   │   ├── Allow-Methods: GET,POST,PUT,DELETE
   │   └── Credentials: true
   │
-  ├── JwtAuthGuard (JWT 认证)
-  │   ├── 白名单路径跳过: /health, /public/*
-  │   └── 提取 payload → 注入 request.user
+  ├── JwtAuthenticationFilter (JWT 认证)
+  │   ├── 白名单路径跳过: /health, /public/*, /api/v1/auth/login
+  │   └── 解析 Token → 设置 SecurityContext
   │
-  └── RolesGuard (角色鉴权)
-      ├── 检查用户角色是否匹配 @Roles()
+  └── @PreAuthorize (方法级鉴权)
+      ├── 检查用户角色是否匹配
       └── 不匹配 → 403 Forbidden
 ```
 
 ## 安全 Checklist
 
-- [ ] 所有敏感接口都有认证保护
+- [ ] 所有敏感接口都有认证保护（`@PreAuthorize`）
 - [ ] Password 使用 bcrypt (cost ≥ 12) 哈希存储
-- [ ] Refresh Token 支持吊销（logout 时失效）
+- [ ] 敏感数据（手机号/身份证）使用国密 SM4 加密存储
+- [ ] Refresh Token 支持吊销（logout 时从 DB 删除）
 - [ ] 登录限制：连续 5 次失败锁定 15 分钟
-- [ ] CSRF Token 保护写操作（如果使用 Cookie）
-- [ ] SQL 注入防护：全部参数化查询
-- [ ] XSS 防护：输出转义、CSP 策略
-- [ ] 日志脱敏：不记录 password/token 等敏感字段
+- [ ] CSRF 防护：SameSite Cookie 或 CSRF Token
+- [ ] SQL 注入防护：MyBatis 全部使用 `#{}` 预编译参数绑定
+- [ ] XSS 防护：响应数据脱敏、CSP 策略
+- [ ] 日志脱敏：不记录 password/token/手机号明文等敏感字段
+- [ ] API 响应脱敏：手机号中间4位*、身份证中间*、密码返回 null
+- [ ] Redis key 必须设置 TTL，禁止永不过期
+- [ ] 虚拟线程中禁止使用 synchronized，改用 ReentrantLock