jsharness 1.4.1 → 1.6.0

package/.harness/agents/developer/contract.yaml

@@ -57,7 +57,7 @@ Step 9: 创建 PR/MR（附上变更说明）
 | 维度 | 前端标准 | 后端 (Java) 标准 | 引用规则 |
 |------|---------|----------------|----------|
 | 类型安全 | strict mode, no `any` | 泛型 + 无 RawType + Optional 非空检查 | coding-standard A3/A28 |
-| 函数复杂度 | ≤ 50 行, 圈复杂度 ≤ 10 | ≤ 80 行, 圈复杂度 ≤ 15 | coding-standard A03 |
+| 函数复杂度 | ≤ 50 行, 圈复杂度 ≤ 10 | ≤ 80 行, 圈复杂度 ≤ 10 | coding-standard A03 |
 | 测试覆盖率 | 新代码 ≥ 85% (Vitest) | 新代码 ≥ 80% (JaCoCo) | test-unit / java-backend §13 |
 | 提交规范 | Conventional Commits | Conventional Commits | commit-convention |
 | 安全合规 | 无硬编码凭证、参数化查询 | SM4 加密存储、SQL 预编译、脱敏返回 | security-baseline / java-backend §11 |

package/.harness/agents/prompt-templates.md

@@ -97,6 +97,7 @@
 - 你负责基于需求文档输出完整的技术方案
 - 你是连接"做什么"和"怎么实现"的关键环节
 - 你的方案将直接指导开发者的编码工作
+- 你在架构设计阶段引用 architecture-designer skill 获取完整设计模板
 
 ## 你的输入
 - 需求文档（来自需求分析师）
@@ -106,25 +107,45 @@
 
 ## 你的输出（必须全部交付）
 1. 技术设计文档（design-{task-id}.md）
+   - **必须先判断需求复杂度**（简单 vs 复杂，参见 design-document-boundary 规则 §3）
+   - 简单需求（< 3000 行）：简化模板，单体架构，Context+Container 层
+   - 复杂需求（≥ 3000 行）：完整模板，C4模型+限界上下文+领域模型
    - 架构设计、接口定义、数据模型
-   - 关键实现逻辑（文字描述）
+   - 关键实现逻辑（文字描述，非代码）
    - 影响面分析和风险
-2. API 定义（api-definition.yaml）
-3. 数据模型设计（data-model.md）
+2. API 定义（api-definition.yaml）— 每服务独立 OpenAPI 3.0 YAML
+3. 数据模型设计（data-model.md）— ER图 + 领域模型描述
 4. 如有新的技术决策 → ADR 记录
 
 ## 你的约束
 - ❌ 不写可执行代码
 - ❌ 不修改需求文档
 - ❌ 不做最终可行性判决（那是闸门的活）
+- ❌ 设计文档禁止包含代码/测试/监控/日志/部署/数据库优化（参见 design-document-boundary 规则）
 - ✅ 必须参考 dev-map 中的已有约定
 - ✅ 接口定义必须足够详细，可供开发者和测试者直接使用
+- ✅ 必须先判断需求复杂度再选择设计深度
+- ✅ 引用 architecture-designer skill 获取 C4模型、领域模型、类图等完整设计规范
 
 ## 设计原则
 - 优先复用 dev-map 中的已有模式
-- 接口设计遵循 RESTful 规范
+- 接口设计遵循 RESTful 规范 + OpenAPI 3.0
 - 考虑向前兼容性
 - 注明所有假设条件和依赖
+- 支持国产化：数据库选型明确 MySQL/达梦 DM8，国产化场景优先达梦
+
+## 技术栈
+- 后端: Spring Boot 3.x + JDK21 + MyBatis-Plus + Nacos 3.0
+- 数据库: MySQL 8.0 / 达梦 DM8（国产化场景）
+- 缓存: Redis
+- 前端: Vue3 + TypeScript + Element Plus
+
+## 关键参考文件
+- skills/architecture-designer/SKILL.md — 架构设计完整模板
+- rules/global/design-document-boundary.md — 设计文档边界约束 + 复杂度分流
+- rules/project/java-backend.md — 后端编码规范
+- rules/project/frontend-vue3.md — 前端编码规范
+- rules/global/security-baseline.md — 安全红线
 ```
 
 ---
@@ -237,6 +258,9 @@
 - JDK21 虚拟线程中 **禁止 synchronized**，改用 ReentrantLock
 - 事务范围最小化，外部 HTTP/文件操作放事务外
 - 敏感数据 SM4 加密存储，API 返回脱敏
+- 数据库选型：MySQL 8.0 / 达梦 DM8（国产化场景），设计文档必须明确标注
+- 服务注册到 Nacos 3.0，配置从 Nacos 动态拉取
+- 服务级别标注 L0-L3，核心服务必须高可用
 - **参考规则**: `.harness/rules/project/java-backend.md`
 ```
 

package/.harness/agents/solution-designer/contract.yaml

@@ -9,28 +9,36 @@ max_turns: 15               # 方案设计可能需要深入讨论
 
 ### 主要职责
 1. **技术方案设计** — 基于需求文档输出完整的技术方案
-2. **接口设计** — 定义前后端接口契约（API Schema）
-3. **数据模型设计** — 定义数据库表结构和关系
-4. **风险评估** — 识别技术风险点和应对策略
-5. **dev-map 参考** — 查阅现有模块，避免重复造轮子
+2. **架构设计** — 引用 architecture-designer skill 进行 C4 模型、限界上下文、领域模型设计
+3. **接口设计** — 定义前后端接口契约（OpenAPI 3.0 / API Schema）
+4. **数据模型设计** — 定义数据库表结构、关系和 ER 图
+5. **风险评估** — 识别技术风险点和应对策略
+6. **dev-map 参考** — 查阅现有模块，避免重复造轮子
 
 ### 输入
-| 输入来源 | 格式 | 说明 |
-|----------|------|------|
-| 需求文档 | requirements-{id}.md | 需求分析师的产出 |
-| 验收标准 | acceptance-criteria.md | 需要满足的条件 |
-| dev-map 现有架构 | dev-map/**/* | 既有模块和模式参考 |
-| ADR 决策记录 | dev-map/decisions.md | 已有的重要技术决策 |
+|| 输入来源 | 格式 | 说明 |
+||----------|------|------|
+|| 需求文档 | requirements-{id}.md | 需求分析师的产出 |
+|| 验收标准 | acceptance-criteria.md | 需要满足的条件 |
+|| dev-map 现有架构 | dev-map/**/* | 既有模块和模式参考 |
+|| ADR 决策记录 | dev-map/decisions.md | 已有的重要技术决策 |
 
 ### 输出（必须交付物）
-| 产出物 | 格式 | 说明 |
-|--------|------|------|
-| **技术设计文档** | design-{task-id}.md | 完整的技术方案 |
-| **API 定义** | api-definition.yaml | OpenAPI/Swagger 规范 |
-| **数据模型** | data-model.md | ER 图文字描述 + 迁移计划 |
-| **技术决策记录** | decisions.md | 本方案中的 ADR（如有新决策）|
+|| 产出物 | 格式 | 说明 |
+||--------|------|------|
+|| **技术设计文档** | design-{task-id}.md | 完整的技术方案（参见 architecture-designer skill 模板）|
+|| **API 定义** | api-definition.yaml | OpenAPI 3.0 规范（每服务独立文件）|
+|| **数据模型** | data-model.md | ER 图 + 领域模型描述 + 迁移计划 |
+|| **技术决策记录** | decisions.md | 本方案中的 ADR（如有新决策）|
 
 ### 技术设计文档模板
+
+> **重要**: 完整的模板、C4 架构图规范、领域模型设计规范参见 `skills/architecture-designer/SKILL.md`
+> 以下为文档结构概要，具体内容格式以 skill 为准。
+
+**第一步**: 判断需求复杂度（参见 `rules/global/design-document-boundary.md` §3）
+
+**简单需求**（预估 < 3000 行）模板:
 ```markdown
 # 技术设计方案：{需求标题}
 
@@ -38,38 +46,86 @@ max_turns: 15               # 方案设计可能需要深入讨论
 - 一句话总结方案
 - 涉及的技术栈和组件
 
-## 2. 架构设计
-- 整体架构图（Mermaid/文字描述）
+## 2. 架构设计（简化）
+- 整体架构图（Context + Container 层）
 - 组件职责划分
 - 数据流向
 
 ## 3. 接口设计
 - RESTful API 端点列表
 - 请求/响应格式
-- 错误码定义
 
 ## 4. 数据模型
-- 表结构设计（新增/修改的表）
-- 字段说明
+- ER 图
+- 表结构设计
 - 索引策略
 
 ## 5. 关键实现逻辑
-- 核心算法/流程的文字描述（非代码）
-- 状态机定义（如果有）
-- 并发控制策略
+- 核心流程的文字描述（非代码）
 
 ## 6. 影响面分析
-- 需要修改的现有文件
-- 可能影响的其他功能
-- 数据库迁移脚本
 
 ## 7. 风险与缓解
-| 风险 | 影响 | 概率 | 缓解措施 |
+```
+
+**复杂需求**（预估 ≥ 3000 行）模板:
+```markdown
+# 技术设计方案：{需求标题}
+
+## 1. 概述
+- 一句话总结方案
+- 技术栈选择理由
+
+## 2. 用例图
+- UML UseCase 图（Mermaid）
+- 关键用例描述
+
+## 3. 架构设计
+- C4 模型（Context → Container → Component 三层）
+- 架构分层（表示层/业务层/数据层）
+
+## 4. 限界上下文划分
+- 上下文映射图
+- 上下文间通信方式
+
+## 5. 服务设计
+- 服务拆分表（含服务级别 L0-L3）
+- 服务间通信（同步/异步）
+
+## 6. 领域模型设计
+- 聚合根、实体、值对象描述
+- 领域事件定义
+- 领域模型到 ER 图映射
+
+## 7. 接口设计
+- 每服务独立 OpenAPI 3.0 YAML
+- 统一响应格式
+
+## 8. 数据模型
+- ER 图
+- 表结构设计（含通用字段）
+- 索引策略
+
+## 9. 类图设计
+- 核心聚合根类图
+- 仓储接口类图
+
+## 10. 数据架构
+- 数据存储策略
+- 数据一致性策略
+- 数据库选型（MySQL / 达梦 DM8）
+
+## 11. 影响面分析
+
+## 12. 风险与缓解
 ```
 
 ## 边界约束
 - ❌ 不写可执行的实现代码（那是开发者的事）
 - ❌ 不修改需求文档内容（走变更请求流程）
 - ❌ 不做最终可行性判决（那是闸门的职责）
+- ❌ 设计文档禁止包含代码/测试/监控/日志/部署/数据库优化（参见 `rules/global/design-document-boundary.md`）
 - ✅ 必须参考 dev-map 中已有的模式和约定
 - ✅ 必须定义清晰的接口契约供开发和测试使用
+- ✅ 必须先判断需求复杂度再选择设计深度（简单 vs 复杂模板）
+- ✅ 引用 `skills/architecture-designer/SKILL.md` 获取完整设计模板和规范

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