soloforge 1.0.0

package/templates/patterns//346/227/240/351/232/234/347/242/215/350/247/204/350/214/203.md

@@ -0,0 +1,33 @@
+---
+name: accessibility
+type: pattern
+when: 无障碍, 可访问性, a11y, ARIA, 键盘导航, 屏幕阅读器, 语义化, WCAG, 辅助功能
+scope: [frontend]
+products: ["*"]
+---
+
+## 决策规则
+- 表单 input 必须关联 label（htmlFor/id 或 aria-labelledby），禁止无标签输入框
+- 按钮和链接必须有可识别文本或 aria-label，禁止纯图标按钮无文字说明
+- 页面必须支持键盘导航（Tab 序列、Enter/Space 触发），焦点顺序符合视觉逻辑
+- 动态内容更新必须使用 aria-live 区域通知屏幕阅读器
+- 颜色对比度必须满足 WCAG AA 标准（文本 4.5:1，大文本 3:1）
+- 图标按钮必须提供 aria-label 或 tooltip，图标作为装饰时使用 aria-hidden="true"
+- 错误提示必须通过 aria-describedby 关联到对应表单字段
+- 所有交互元素必须有可访问的名称（aria-label 或关联 label），屏幕阅读器可识别
+- 颜色对比度必须满足 WCAG 2.1 AA 标准（正文 ≥ 4.5:1，大文本 ≥ 3:1）
+- 所有功能必须支持键盘操作（Tab 导航 + Enter/Space 触发），不能仅依赖鼠标
+- 表单必须有明确的错误提示和关联（aria-describedby），不能只用颜色标识错误
+- 图片/图标必须有替代文本（alt 属性），装饰性图片使用 alt=""
+- 页面标题（title）和标题层级（h1-h6）必须语义正确，便于辅助导航
+
+## 验收项
+- [AC-01] 表单字段有关联 label
+- [AC-02] 按钮和链接有可识别文本
+- [AC-03] 页面支持键盘导航
+- [AC-04] 颜色对比度满足 WCAG AA
+- [AC-05] 交互元素有 aria-label
+- [AC-06] 颜色对比度符合 WCAG AA
+- [AC-07] 功能支持键盘操作
+- [AC-08] 表单错误有关联提示
+- [AC-09] 图片有替代文本

package/templates/patterns//346/227/245/345/277/227/350/247/204/350/214/203.md

@@ -0,0 +1,31 @@
+---
+name: logging
+type: pattern
+when: 日志记录, 日志, log, 打日志, 链路追踪, MDC, traceId, 日志格式, 记录日志, 操作日志
+scope: [backend]
+products: ["*"]
+---
+
+## 决策规则
+- 必须使用 SLF4J + Logback，禁止 System.out.println
+- 所有请求必须有 traceId 贯穿完整链路（MDC Filter）
+- 关键业务操作（创建/修改/删除）必须记录 INFO 日志
+- 禁止日志中打印敏感信息（密码、token、身份证号），敏感字段必须脱敏
+- ERROR 日志必须包含异常堆栈（log.error("msg", e)）
+- 所有新增/修改/删除/审核/审批/发放/冻结/解冻等写操作必须有审计落点
+- 审计至少包含：操作者、操作时间、操作对象、来源入口、关键前后值或结果摘要
+- 关键路径（写操作、状态变更、外部调用、异常捕获）必须有日志，只读查询不得为满足规则而硬加日志
+- 禁止在循环中打印日志（尤其是 DEBUG 级别），防止日志洪泛
+- 异常日志必须包含完整堆栈（log.error("msg", exception)），禁止只打印 getMessage()
+- 生产环境禁止使用 DEBUG/TRACE 级别日志
+
+## 验收项
+- [AC-01] 所有请求有 traceId 贯穿
+- [AC-02] 关键操作记录 INFO 日志
+- [AC-03] 日志不含敏感信息
+- [AC-04] 无 System.out.println
+- [AC-05] 写操作有审计记录（操作者/时间/对象/来源）
+- [AC-06] 关键路径有日志且只读查询无冗余日志
+- [AC-07] 关键操作有审计日志
+- [AC-08] 日志包含 traceId
+- [AC-09] 异常日志包含完整堆栈

package/templates/patterns//346/235/203/351/231/220/350/256/244/350/257/201/350/247/204/350/214/203.md

@@ -0,0 +1,35 @@
+---
+name: auth-permission
+type: pattern
+when: 权限认证, 权限校验, 认证, 登录, 鉴权, 授权, Token, JWT, RBAC, 角色, @PreAuthorize, 登录验证, 访问控制
+scope: [backend]
+products: ["*"]
+---
+
+## 决策规则
+- 所有写接口必须有权限注解或 URL 级别鉴权
+- 禁止在 Controller 中硬编码角色判断（if role == "ADMIN"）
+- JWT Token 必须设置过期时间（建议 2-8 小时）
+- 密码必须使用 BCrypt 哈希存储，禁止明文或可逆加密
+- 前端隐藏按钮不能替代后端权限校验
+- 任何新增或修改菜单必须同步声明角色、权限标识、默认可见性和数据范围
+- 页面可见不等于可操作，按钮权限、接口权限和数据权限必须分别定义
+- 接口鉴权要求必须能回链到角色与权限模型，不能只写 auth=token
+- 禁止菜单可见性与接口可调用性解耦（菜单隐藏但接口暴露）
+- 登录失败不得提示具体原因（不区分"用户名不存在"和"密码错误"）
+- 登录接口必须有暴力破解防护（连续失败 N 次锁定或验证码）
+- Session ID 必须在登录成功后重新生成，防止会话固定攻击
+- 前端敏感操作（修改密码、删除）必须重新验证身份（re-authentication）
+- API 接口必须实现限流（Rate Limiting），防止暴力枚举和 CC 攻击
+
+## 验收项
+- [AC-01] 写接口有权限注解或鉴权
+- [AC-02] Token 有过期时间
+- [AC-03] 密码 BCrypt 哈希存储
+- [AC-04] 无硬编码角色判断
+- [AC-05] 菜单/按钮/接口/数据范围三层权限同步定义
+- [AC-06] 接口鉴权可回链到角色权限模型
+- [AC-07] 登录失败不暴露具体原因
+- [AC-08] 有暴力破解防护机制
+- [AC-09] 敏感操作重新验证身份
+- [AC-10] API 接口有限流策略

package/templates/patterns//346/236/266/346/236/204/347/272/242/347/272/277.md

@@ -0,0 +1,30 @@
+---
+name: architecture-redline
+type: pattern
+when: 架构设计, 系统架构, 模块划分, 服务边界, 架构红线, 跨模块调用, 服务拆分
+scope: [backend]
+products: ["*"]
+---
+
+## 决策规则
+- 禁止绕过统一认证和数据范围控制直接暴露业务接口
+- 禁止通过 Patch JAR、docker commit 或运行时文件替换交付代码
+- 禁止前端、Controller 或定时任务跨服务边界直接访问持久化实现
+- 禁止将事务、认证、金额、库存、安全策略或数据库 Schema 变更打包为"小修改"而无设计追溯
+- 禁止菜单可见性与接口可调用性解耦（菜单隐藏但接口暴露，或菜单存在但无权限支撑）
+- 禁止异步消息、定时任务或补偿逻辑绕过主路径审计和幂等控制
+- 所有新增写操作必须有可追溯的审计记录
+- 禁止在循环内执行数据库操作（N+1），必须使用批量查询
+- 禁止在事务内执行远程调用（HTTP/RPC），防止长事务锁表
+- 禁止 catch 后空处理，至少记录日志并标注忽略原因
+- 禁止直接使用 new Date() 获取时间，必须通过时钟服务注入便于测试
+- 禁止在 Service 层注入 HttpServletRequest/Response，保持层级清晰
+
+## 验收项
+- [AC-01] 业务接口经过统一认证
+- [AC-02] 无跨边界直接持久化访问
+- [AC-03] 菜单与接口权限同步定义
+- [AC-04] 写操作有审计记录
+- [AC-05] 无循环内数据库调用
+- [AC-06] 无事务内远程调用
+- [AC-07] 无空 catch 块

package/templates/patterns//346/265/213/350/257/225/350/264/250/351/207/217/350/247/204/350/214/203.md

@@ -0,0 +1,30 @@
+---
+name: testing-quality
+type: pattern
+when: 测试质量, 测试规范, 测试策略, 单元测试, 集成测试, 测试覆盖, E2E测试, 测试反模式
+scope: [backend, frontend]
+products: ["*"]
+---
+
+## 决策规则
+- 每个接口至少覆盖：正常流程、参数缺失、权限不足、业务异常、边界值
+- 端到端业务测试必须从浏览器页面模拟真实用户操作，直接 API 调用只能补充不能替代
+- 测试失败必须在源逻辑修复，禁止修改测试来适配 Bug
+- 测试数据准备必须走业务 API 或页面操作，禁止直接 SQL INSERT 业务数据
+- 禁止在测试脚本中硬编码凭据，必须从环境变量或配置文件读取
+- Docker 部署必须从全新镜像构建，禁止 docker commit 和热补丁
+- 单元测试覆盖率核心逻辑必须 ≥ 80%，关键路径（支付/权限）必须 100%
+- 测试方法命名必须清晰表达测试场景（如 shouldReturn401WhenTokenExpired）
+- 测试数据必须使用工厂方法或 Builder 构建，禁止硬编码 magic values
+- 集成测试必须使用测试容器（Testcontainers）或内存数据库，禁止依赖外部环境
+- 每个修复的 bug 必须有对应的回归测试，防止问题复现
+
+## 验收项
+- [AC-01] 接口测试覆盖正常+异常+边界
+- [AC-02] E2E 测试从浏览器模拟用户操作
+- [AC-03] 测试失败修复源逻辑而非改测试
+- [AC-04] 测试数据走业务 API 非 SQL 直写
+- [AC-05] 核心逻辑覆盖率 ≥ 80%
+- [AC-06] 测试方法名清晰表达场景
+- [AC-07] 测试数据工厂构建
+- [AC-08] Bug 修复有回归测试

package/templates/patterns//347/206/224/346/226/255/351/231/215/347/272/247/350/247/204/350/214/203.md

@@ -0,0 +1,33 @@
+---
+name: circuit-breaker
+type: pattern
+when: 服务降级, 熔断, 限流, 降级, 级联故障, 服务雪崩, Sentinel, Hystrix, Resilience4j, 服务保护, 容错
+scope: [backend]
+products: ["*"]
+---
+
+## 决策规则
+- 外部依赖（第三方 API、中间件、其他微服务）必须配置超时时间，禁止无限等待
+- 核心链路的外部调用必须配置熔断器：失败率阈值（建议 50%）、熔断时长（建议 30s）、半开探测数（建议 5）
+- 熔断触发后必须有降级策略：返回缓存数据/默认值/友好提示，禁止直接抛异常给用户
+- 接口必须有限流保护（令牌桶/漏桶），防止突发流量击穿服务
+- 降级方案必须提前定义：降级行为、用户提示文案、数据一致性保障、恢复条件
+- 重试必须满足幂等性，重试间隔必须使用指数退避（initial 100ms, multiplier 2, max 3 次）
+- 线程池隔离：不同外部依赖使用独立线程池，防止一个慢服务拖垮所有请求
+- 必须有服务健康检查端点（/actuator/health），包含依赖组件状态（DB/Redis/MQ）
+- 熔断器必须配置 half-open 状态的探测请求量（如允许 5 个请求通过测试），成功后才恢复
+- 降级 fallback 必须返回有意义的默认值或缓存数据，禁止返回 null 或空对象
+- 熔断/降级事件必须触发监控告警，不能静默降级
+- 外部调用必须设置独立的超时时间（不依赖全局超时），与熔断器配合使用
+- 熔断器状态变化必须有日志记录（closed → open → half-open → closed）
+
+## 验收项
+- [AC-01] 外部调用有超时和熔断配置
+- [AC-02] 熔断后有降级策略和用户提示
+- [AC-03] 重试有指数退避和幂等保障
+- [AC-04] 有限流保护
+- [AC-05] 健康检查端点包含依赖状态
+- [AC-06] half-open 探测机制配置
+- [AC-07] fallback 返回有意义的值
+- [AC-08] 熔断事件有监控告警
+- [AC-09] 外部调用有独立超时

package/templates/patterns//347/212/266/346/200/201/346/265/201/350/275/254/350/247/204/350/214/203.md

@@ -0,0 +1,29 @@
+---
+name: state-transition
+type: pattern
+when: 状态机, 状态流转, 状态变更, 状态转换, 审批流, 工单状态, 订单状态, 流程引擎
+scope: [backend]
+products: ["*"]
+---
+
+## 决策规则
+- 仅列出状态列表不够，每个状态转换必须定义：触发条件、守卫条件、失败/回滚动作
+- 金额、库存、配额、计数器等并发敏感节点默认需要并发控制
+- 并发敏感操作必须显式声明：并发控制方式（乐观锁/悲观锁/幂等键/去重表）、重试策略、重复提交处理、用户可见失败反馈
+- 跨模块或跨服务状态变更必须显式声明最终一致性和补偿策略
+- 集成测试必须覆盖：至少一次成功转换、一次守卫失败、一次失败恢复或升级路径
+- 状态流转必须通过状态机框架（如 Spring Statemachine）或显式流转表校验，禁止硬编码 if-else
+- 每次状态变更必须记录流转日志（原状态→新状态、操作人、时间、原因）
+- 并发状态变更必须使用乐观锁或分布式锁，防止状态覆盖
+- 状态流转失败必须返回明确的错误原因，告知用户当前状态和允许的下一步操作
+- 状态定义必须包含初始状态和终态，禁止出现无法流转的"悬挂状态"
+
+## 验收项
+- [AC-01] 状态转换有触发条件、守卫条件、回滚动作
+- [AC-02] 并发敏感操作有显式并发控制声明
+- [AC-03] 跨服务状态变更有补偿策略
+- [AC-04] 集成测试覆盖成功和失败路径
+- [AC-05] 状态机校验（非硬编码）
+- [AC-06] 状态变更审计日志
+- [AC-07] 并发状态变更防护
+- [AC-08] 无悬挂状态

package/templates/patterns//347/272/246/346/235/237/345/256/236/347/216/260/350/247/204/350/214/203.md

@@ -0,0 +1,32 @@
+---
+name: constrained-implementation
+type: pattern
+when: 编码实现, 写代码, 修改代码, 代码变更, 实现, 编码, coding, 代码修改, 修bug, 修代码
+scope: [backend, frontend]
+products: ["*"]
+---
+
+## 决策规则
+- 必须在修改代码前定位根因，解释根因、修改边界和验证方式后再编码
+- 只修改任务卡/补丁计划/白名单明确范围内的文件
+- 禁止补丁叠补丁或试错式堆叠修复
+- 禁止删除断言、放宽测试、增加 sleep、让测试适应错误行为
+- 禁止顺手重构或范围外的"清理"
+- 每个代码变更必须追溯到任务卡、补丁计划或阻塞性缺陷
+- 范围超出白名单或需要变更接口/DDL/权限/菜单时，立即上报而非自行决定
+- 必须完成本地验证并产出结构化证据后再结束
+- 唯一约束必须同时在数据库和应用层校验，防止并发场景下的重复数据
+- 外键约束在微服务架构中不建议使用物理外键，应通过应用层保证数据一致性
+- 乐观锁必须使用 version 字段而非 update_time（后者可能因精度问题失效）
+- 软删除数据必须排除在唯一约束之外（如添加 is_deleted 条件索引）
+- 数据库约束的校验失败必须返回用户友好的错误消息，而非数据库原始报错
+
+## 验收项
+- [AC-01] 变更范围与白名单完全匹配
+- [AC-02] 根因已确认再编码（非先改再试）
+- [AC-03] 无顺手重构或范围外变更
+- [AC-04] 本地验证执行完毕有结果
+- [AC-05] 超范围变更已上报
+- [AC-06] 唯一约束双层校验
+- [AC-07] 乐观锁用 version 字段
+- [AC-08] 软删除与唯一约束兼容

package/templates/patterns//347/274/223/345/255/230/347/255/226/347/225/245/350/247/204/350/214/203.md

@@ -0,0 +1,31 @@
+---
+name: caching
+type: pattern
+when: 缓存策略, 缓存, cache, Redis, 热点数据, 查询优化, 缓存穿透, 缓存雪崩, @Cacheable, 缓存一致性
+scope: [backend]
+products: ["*"]
+---
+
+## 决策规则
+- 所有缓存必须设置 TTL，禁止永久缓存
+- 热点数据 TTL 必须加随机偏移防止雪崩
+- 缓存 key 格式必须统一：模块:业务:id
+- 查询不存在的数据必须缓存空值或使用布隆过滤器防止穿透
+- 写操作必须同步更新或失效缓存，保证一致性
+- 缓存重建必须使用分布式锁或 singleflight 模式，防止缓存击穿导致 DB 过载
+- 缓存值禁止存储大对象（建议 ≤ 1MB），大对象应只缓存 key 引用
+- 缓存操作必须设置超时时间，防止 Redis 阻塞拖垮业务线程
+- 禁止缓存中存储敏感信息（密码、token、身份证号），或必须加密后存储
+- 缓存命中率必须纳入监控，命中率低于阈值时触发告警
+- 本地缓存（Caffeine/Guava）与分布式缓存的数据一致性策略必须明确
+
+## 验收项
+- [AC-01] 所有缓存 key 有 TTL
+- [AC-02] 热点数据 TTL 加随机偏移
+- [AC-03] 缓存 key 格式统一
+- [AC-04] 有穿透/雪崩防护措施
+- [AC-05] 缓存重建有分布式锁保护
+- [AC-06] 缓存值不超过 1MB
+- [AC-07] 缓存操作有超时设置
+- [AC-08] 缓存中无明文敏感信息
+- [AC-09] 缓存命中率有监控告警

package/templates/patterns//347/274/226/347/240/201/350/264/250/351/207/217/350/247/204/350/214/203.md

@@ -0,0 +1,31 @@
+---
+name: coding-quality
+type: pattern
+when: 编码质量, 代码规范, 代码评审, 代码质量, 重构, over-engineering, 过度设计, 代码异味
+scope: [backend, frontend]
+products: ["*"]
+---
+
+## 决策规则
+- 50 行能解决的问题禁止写 200 行；禁止为单次使用场景过度设计
+- 每行代码变更必须可追溯到任务卡片中的显式需求，禁止"顺手"重构相邻代码
+- 实现记录必须显式声明业务入口集成状态（菜单/路由/权限）
+- Bug 修复必须针对根因，禁止在破损代码上叠加 workaround
+- 方法必须按业务步骤拆分为单一职责的私有方法
+- 新增/修改类必须文档化业务职责、边界和关键协作者
+- 仅在"非显而易见"的关键行添加注释说明 why，禁止对简单赋值加噪声注释
+- 方法长度不超过 80 行，超过时拆分为子方法
+- 方法参数不超过 5 个，超过时封装为请求对象
+- 单个类职责单一（SRP），超过 500 行的类应考虑拆分
+- 条件嵌套不超过 3 层，超过时使用卫语句、策略模式或 Optional 链重构
+- 禁止使用魔法数字，必须提取为命名常量或枚举
+
+## 验收项
+- [AC-01] 代码变更可追溯到任务需求
+- [AC-02] 业务入口集成状态已声明
+- [AC-03] Bug 修复针对根因而非 workaround
+- [AC-04] 无过度设计（50行能解决的不写200行）
+- [AC-05] 方法不超过 80 行
+- [AC-06] 参数不超过 5 个
+- [AC-07] 嵌套不超过 3 层
+- [AC-08] 无魔法数字

package/templates/patterns//347/274/272/351/231/267/347/256/241/347/220/206/350/247/204/350/214/203.md

@@ -0,0 +1,30 @@
+---
+name: defect-management
+type: pattern
+when: 缺陷管理, Bug修复, 缺陷闭环, 回归测试, 缺陷预防, 缺陷归因, 质量改进
+scope: [backend, frontend]
+products: ["*"]
+---
+
+## 决策规则
+- 每个缺陷必须归因到最小责任阶段（需求/设计/任务拆解/实现/测试/门禁）
+- 修复必须附带证据，"理论上修好了"不可接受
+- 有复现价值的缺陷必须产出至少一项回填动作：规则、模板、检查项或知识条目
+- 同一缺陷若在案例库中已出现过，自动升级为深层缺陷（方法论级别）
+- 报告必须在修复之前编写，禁止先改规则后写报告
+- 缺陷结论必须区分：已完成 / 未完成 / 未验证 / 未知，无真实证据不得标记为已完成
+- 缺陷必须包含完整的复现步骤、预期结果、实际结果和环境信息
+- 每个缺陷必须有优先级（P0-P4）和严重程度（S1-S4）分类
+- 修复缺陷必须包含根因分析，禁止只修表面症状
+- P0/P1 缺陷修复后必须经过回归测试，不能直接上线
+- 缺陷关闭必须由提单人确认，修复人不能自行关闭
+
+## 验收项
+- [AC-01] 缺陷有归因阶段
+- [AC-02] 修复附带执行证据
+- [AC-03] 有复现价值的缺陷有回填动作
+- [AC-04] 结论区分已完成/未完成/未验证/未知
+- [AC-05] 缺陷有完整复现信息
+- [AC-06] 有优先级和严重程度
+- [AC-07] 修复包含根因分析
+- [AC-08] 高优先级缺陷有回归测试

package/templates/patterns//350/260/203/350/257/225/346/226/271/346/263/225/350/256/272.md

@@ -0,0 +1,28 @@
+---
+name: debugging-methodology
+type: pattern
+when: 调试, debug, 排查问题, 修复Bug, 定位错误, 根因分析, 排障, 故障排查
+scope: [backend, frontend]
+products: ["*"]
+---
+
+## 决策规则
+- 一次只验证一个假设，一次只改一个变量，记录所有结果包括被否定的假设
+- 禁止从观察直接跳到修复，必须经过假设验证
+- 修复范围只覆盖确认的根因，禁止顺手改其他代码
+- 同一现象修复失败 3 次后停止猜测，重新审视假设，考虑是否为架构问题而非 Bug
+- 使用 RED-GREEN 回归验证：回退修复 → 确认失败 → 恢复修复 → 确认通过
+- 禁止通过删除断言、增加 sleep、降低覆盖率、增加 mock 来制造通过
+- 调试必须先复现问题（确定环境、数据、步骤），禁止在未复现的情况下猜测修改
+- 必须使用二分法定位问题范围（注释一半代码/回退一半提交），禁止全量排查
+- 线上问题排查必须优先查看日志和监控，禁止直接登录服务器修改代码
+- 修复后必须验证根因是否消除，而非只验证症状消失
+
+## 验收项
+- [AC-01] 调试过程有假设-验证记录
+- [AC-02] 修复范围仅限确认的根因
+- [AC-03] 3次失败后重新审视假设
+- [AC-04] 使用 RED-GREEN 回归验证
+- [AC-05] 先复现再排查
+- [AC-06] 使用二分法定位
+- [AC-07] 修复后验证根因消除

package/templates/patterns//350/276/223/345/205/245/346/240/241/351/252/214/350/247/204/350/214/203.md

@@ -0,0 +1,30 @@
+---
+name: input-validation
+type: pattern
+when: 参数校验, 输入验证, 字段验证, 合法性校验, 入参校验, 必填, 格式校验, 参数检查, @Valid, @NotNull
+scope: [backend]
+products: ["*"]
+---
+
+## 决策规则
+- 必须使用 Bean Validation 注解（@NotBlank、@Size、@Min 等）声明式校验
+- 禁止手写 if-else 逐字段校验（跨字段业务规则除外）
+- 创建和更新必须使用分组校验（CreateGroup/UpdateGroup）
+- 校验失败必须返回 400 + 具体字段名和错误消息
+- 后端必须校验，禁止仅依赖前端校验
+- 数组/集合参数必须校验非空且限制最大长度（防止批量攻击）
+- 枚举类型参数必须校验是否为合法枚举值，禁止直接信任前端传入
+- 日期参数必须指定格式（@DateTimeFormat）并校验合理性（不能是未来日期等）
+- 富文本输入必须使用白名单标签过滤（如 jsoup Whitelist），禁止直接存储原始 HTML
+- 正则表达式校验必须限制输入长度和复杂度，防止 ReDoS 攻击
+- URL 参数必须校验协议白名单（仅允许 http/https），防止 SSRF
+
+## 验收项
+- [AC-01] 所有 DTO 字段有校验注解
+- [AC-02] 创建/更新使用分组校验
+- [AC-03] 校验失败返回 400 + 字段详情
+- [AC-04] 无手写 if-else 参数校验
+- [AC-05] 集合参数有长度限制
+- [AC-06] 枚举参数校验合法值
+- [AC-07] 富文本经过白名单过滤
+- [AC-08] URL 参数校验协议白名单

package/templates/patterns//351/224/231/350/257/257/345/244/204/347/220/206/350/247/204/350/214/203.md

@@ -0,0 +1,32 @@
+---
+name: error-handling
+type: pattern
+when: 异常处理, 错误处理, 全局异常, 错误码, Exception, BusinessException, 状态码, 报错, 异常捕获, 错误响应
+scope: [backend]
+products: ["*"]
+---
+
+## 决策规则
+- 必须使用 @ControllerAdvice 全局异常处理器，禁止散落的 try-catch 吞异常
+- 业务异常必须使用自定义 BusinessException 携带错误码和消息
+- 禁止将异常堆栈信息返回给前端
+- 系统异常必须记录 ERROR 日志并返回通用提示，不暴露内部细节
+- 参数校验失败必须返回 HTTP 400
+- 每个用户可见写操作必须定义失败反馈：提示文案、重试建议、是否可恢复
+- 权限失败、校验失败、资源不存在、冲突失败、系统异常必须有区别化处理
+- 前端提示与接口错误码必须可回链，不得一个写"无权限"、一个写"操作失败"
+- 若失败后需要用户补动作（刷新、重新登录、补齐字段、稍后重试），必须写明
+- 全局异常处理器必须区分业务异常（可预期）和系统异常（不可预期），分别返回不同错误码
+- 错误响应必须包含 traceId，便于日志追踪关联
+- 前端必须对每个 API 调用做错误处理（toast/notification），禁止静默失败
+
+## 验收项
+- [AC-01] 所有异常经全局处理器返回
+- [AC-02] 业务异常返回具体错误码和消息
+- [AC-03] 系统异常不暴露堆栈给前端
+- [AC-04] 校验失败返回 400 + 字段错误详情
+- [AC-05] 用户可见写操作有失败反馈（提示+重试建议）
+- [AC-06] 前端提示与后端错误码可回链
+- [AC-07] 业务异常与系统异常分别处理
+- [AC-08] 错误响应包含 traceId
+- [AC-09] 前端 API 调用有错误提示

package/templates/patterns//351/224/231/350/257/257/350/276/271/347/225/214/350/247/204/350/214/203.md

@@ -0,0 +1,24 @@
+---
+name: error-boundary
+type: pattern
+when: 错误边界, 错误处理, 白屏, 页面崩溃, ErrorBoundary, 异常捕获, 全局错误, 前端异常, componentDidCatch, fallback
+scope: [frontend]
+products: ["*"]
+---
+
+## 决策规则
+- React 应用必须在路由级别包裹 ErrorBoundary，防止单个组件崩溃导致整个页面白屏
+- 必须提供全局未捕获异常处理（window.onerror / window.addEventListener('error')）
+- ErrorBoundary 的 fallback UI 必须包含：错误提示、重试按钮、返回首页链接
+- 异步请求错误（网络、超时、服务端）统一在 axios 拦截器处理，禁止每个组件单独 try-catch
+- Promise 未捕获 rejection 必须有全局监听（unhandledrejection event）
+- 错误信息禁止暴露技术细节给用户（堆栈、SQL、内部 IP）
+- 生产环境必须上报错误到监控服务（Sentry / 自建），禁止只在控制台打印
+- loading / error / empty 三态必须完整处理，禁止只处理成功状态
+
+## 验收项
+- [AC-01] 路由级别有 ErrorBoundary 包裹
+- [AC-02] fallback UI 有重试和返回首页
+- [AC-03] 异步错误统一在拦截器处理
+- [AC-04] loading/error/empty 三态完整
+- [AC-05] 生产错误上报到监控服务

package/templates/patterns//351/242/206/345/237/237/351/251/261/345/212/250/350/256/276/350/256/241/350/247/204/350/214/203.md

@@ -0,0 +1,29 @@
+---
+name: ddd-design
+type: pattern
+when: 领域驱动设计, DDD, 领域模型, 聚合根, 值对象, 领域事件, 充血模型, 贫血模型, 模块设计
+scope: [backend]
+products: ["*"]
+---
+
+## 决策规则
+- 简单 CRUD 使用贫血模型，禁止在领域不复杂时强行使用充血模型
+- 不教条式应用 DDD，仅在领域真正复杂时采用充血领域模型
+- 一个模块/类应该只有一个变更原因（SRP），两个方法被不同需求修改即为 SRP 违反
+- 跨模块非强一致性流程应优先事件驱动架构，未采用事件驱动必须文档化原因
+- 高层模块必须依赖抽象而非具体实现（DIP），Service 依赖 Repository 接口而非具体 DAO
+- 写操作涉及金额、库存、状态流转等关键逻辑应考虑封装在领域服务中
+- 聚合根必须有明确的边界，聚合间通过 ID 引用而非对象嵌套
+- 领域事件必须由聚合根产生，跨聚合操作通过事件最终一致性
+- 值对象必须不可变（immutable），使用新的值对象表示变更
+- 仓储（Repository）只对聚合根提供存取，聚合内部实体不独立持久化
+- 领域服务只在跨聚合或需要外部资源时使用，单一聚合逻辑放在聚合根内
+
+## 验收项
+- [AC-01] CRUD 场景使用贫血模型
+- [AC-02] 跨模块交互有明确的依赖方向
+- [AC-03] Service 依赖接口而非具体实现
+- [AC-04] 事件驱动决策有文档记录
+- [AC-05] 聚合边界清晰，聚合间 ID 引用
+- [AC-06] 值对象不可变
+- [AC-07] 仓储仅对聚合根

package/templates/scaffolds/react/Form.tsx.hbs

@@ -0,0 +1,16 @@
+import React from 'react';
+import { {{ModuleName}} } from './types';
+
+interface {{ModuleName}}FormProps {
+  initialData?: Partial<{{ModuleName}}>;
+  onSubmit: (data: {{ModuleName}}) => void;
+}
+
+export const {{ModuleName}}Form: React.FC<{{ModuleName}}FormProps> = ({ initialData, onSubmit }) => {
+  // TODO: 实现表单组件
+  return (
+    <form>
+      {/* TODO: 添加表单字段 */}
+    </form>
+  );
+};

package/templates/scaffolds/react/List.tsx.hbs

@@ -0,0 +1,28 @@
+import React from 'react';
+import { {{ModuleName}} } from './types';
+
+interface {{ModuleName}}ListProps {
+  data: {{ModuleName}}[];
+  onEdit?: (item: {{ModuleName}}) => void;
+  onDelete?: (id: number) => void;
+}
+
+export const {{ModuleName}}List: React.FC<{{ModuleName}}ListProps> = ({ data, onEdit, onDelete }) => {
+  // TODO: 实现列表组件
+  return (
+    <table>
+      <thead>
+        <tr>
+          {/* TODO: 添加表头 */}
+        </tr>
+      </thead>
+      <tbody>
+        {data.map((item) => (
+          <tr key={item.id}>
+            {/* TODO: 添加数据列 */}
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+};

package/templates/scaffolds/react/Page.test.tsx.hbs

@@ -0,0 +1,10 @@
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/react';
+import { {{ModuleName}}Page } from './Page';
+
+describe('{{ModuleName}}Page', () => {
+  it('renders without crashing', () => {
+    const { container } = render(<{{ModuleName}}Page />);
+    expect(container).toBeTruthy();
+  });
+});

package/templates/scaffolds/react/Page.tsx.hbs

@@ -0,0 +1,14 @@
+import React from 'react';
+import { {{ModuleName}} } from './types';
+import { {{moduleName}}Service } from './service';
+
+export const {{ModuleName}}Page: React.FC = () => {
+  // TODO: 实现页面组件
+  return (
+    <div>
+      <h1>{{ModuleName}} 管理</h1>
+    </div>
+  );
+};
+
+export default {{ModuleName}}Page;

package/templates/scaffolds/react/README.md.hbs

@@ -0,0 +1,44 @@
+# {{ModuleName}} 模块
+
+> 自动生成于 {{date}}
+
+## 概述
+
+{{ModuleName}} 模块提供 {{moduleNameLower}} 的增删改查功能。
+
+## 文件结构
+
+```
+src/pages/{{ModuleName}}/
+├── Page.tsx          # 主页面组件
+├── Form.tsx          # 表单组件
+├── List.tsx          # 列表组件
+├── service.ts        # API 调用层
+├── types.ts          # 类型定义
+└── use{{ModuleName}}.ts  # 数据 Hook
+```
+
+## API 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | {{basePath}} | 查询列表（分页） |
+| GET | {{basePath}}/:id | 查询详情 |
+| POST | {{basePath}} | 创建 |
+| PUT | {{basePath}}/:id | 更新 |
+| DELETE | {{basePath}}/:id | 删除 |
+
+## 使用示例
+
+```tsx
+import { {{ModuleName}}Page } from './pages/{{ModuleName}}/Page';
+
+// 在路由中注册
+<Route path="/{{module_name}}" element={<{{ModuleName}}Page />} />
+```
+
+## 注意事项
+
+- 列表使用服务端分页，默认每页 20 条
+- 表单提交前会进行前端校验
+- 删除操作有二次确认弹窗