soloforge 1.0.0

package/templates/patterns//344/272/213/344/273/266/351/251/261/345/212/250/350/247/204/350/214/203.md

@@ -0,0 +1,32 @@
+---
+name: event-driven
+type: pattern
+when: 事件驱动, 事件溯源, 领域事件, 消息队列, MQ, 异步消息, 解耦, 事件发布, Event Sourcing, CQRS, 最终一致性
+scope: [backend]
+products: ["*"]
+---
+
+## 决策规则
+- 跨模块非强一致性交互优先使用事件驱动（MQ），未使用时必须文档化原因
+- 事件必须幂等消费：消费者必须能安全处理重复消息（唯一约束/去重表/幂等键）
+- 事件消费失败必须有重试机制（建议 3 次）+ 死信队列（DLQ），禁止静默丢弃
+- 事件结构必须包含：事件类型、事件 ID（幂等键）、发生时间、聚合 ID、事件载荷
+- 禁止通过事件传递大对象（如完整订单），事件载荷只传 ID + 关键变更字段
+- 事件消费者异常不影响事件生产者（异步解耦），生产者不依赖消费者响应
+- 最终一致性场景必须定义：最大延迟容忍、补偿策略、对账机制
+- 禁止用消息队列做 RPC（同步等待响应），同步调用走 HTTP/Feign/gRPC
+- 事件消费者必须实现幂等处理，同一事件重复消费不能产生副作用
+- 事件必须包含版本号和发生时间，便于消费者兼容演进
+- 事件消费失败必须有重试机制（退避策略）和死信队列兜底
+- 关键业务事件必须持久化存储，不能只发 MQ 不落库
+- 事件体禁止包含大对象（如完整订单），应只传 ID 引用
+
+## 验收项
+- [AC-01] 跨模块交互使用事件驱动或有文档化原因
+- [AC-02] 事件消费幂等
+- [AC-03] 消费失败有重试 + 死信队列
+- [AC-04] 事件结构包含类型/ID/时间/载荷
+- [AC-05] 最终一致性有补偿和对账机制
+- [AC-06] 消费者幂等处理
+- [AC-07] 失败有重试和死信队列
+- [AC-08] 关键事件持久化

package/templates/patterns//344/272/213/345/212/241/346/250/241/345/274/217/350/247/204/350/214/203.md

@@ -0,0 +1,28 @@
+---
+name: transaction-pattern
+type: pattern
+when: 事务, @Transactional, 分布式事务, 事务传播, 事务隔离, 数据一致性, 回滚, commit, rollback, 补偿事务
+scope: [backend]
+products: ["*"]
+---
+
+## 决策规则
+- 写操作 Service 方法必须标注 @Transactional，且显式指定 rollbackFor = Exception.class
+- 禁止在 Controller 层使用事务注解，事务边界必须在 Service 层
+- @Transactional 方法禁止被同类内部调用（AOP 代理失效），必须通过注入调用
+- 事务方法必须短小快速，禁止在事务中执行外部 HTTP 调用、文件 I/O、MQ 发送
+- 只读查询方法必须标注 @Transactional(readOnly = true)，降低数据库压力
+- 跨服务分布式事务优先使用最终一致性（事件 + 补偿），禁止强依赖 2PC/XA
+- 跨服务事务必须有补偿机制：正向操作失败自动补偿或定时对账修复
+- 嵌套事务优先使用 REQUIRES_NEW 分割独立事务单元，避免大事务锁表
+- 传播行为默认 REQUIRED 即可，禁止随意使用 REQUIRES_NEW（容易产生数据不一致）
+
+## 验收项
+- [AC-01] 写操作有 @Transactional(rollbackFor = Exception.class)
+- [AC-02] 事务方法无外部调用和文件 I/O
+- [AC-03] 只读方法有 readOnly = true
+- [AC-04] 跨服务事务有补偿机制
+- [AC-05] 无同类内部调用导致 AOP 失效
+- [AC-06] rollbackFor 显式指定
+- [AC-07] 无内部调用导致事务失效
+- [AC-08] 只读查询标注 readOnly

package/templates/patterns//344/274/230/351/233/205/345/201/234/346/234/272/350/247/204/350/214/203.md

@@ -0,0 +1,30 @@
+---
+name: graceful-shutdown
+type: pattern
+when: 优雅停机, 服务下线, 优雅关闭, shutdown, 健康检查, readiness, liveness, 启停, 灰度发布, 滚动更新
+scope: [backend]
+products: ["*"]
+---
+
+## 决策规则
+- 服务必须实现优雅停机：收到 SIGTERM 后停止接收新请求，等待正在处理请求完成（建议超时 30s）
+- 必须提供健康检查端点：liveness（进程存活）和 readiness（服务就绪，依赖全部可用）
+- 滚动更新期间必须先从注册中心摘除再停机，禁止直接 kill 导致请求丢失
+- 启动时必须等待依赖组件就绪（DB 连接池、Redis、MQ）后再注册到服务发现
+- 定时任务必须在停机时中断执行并记录中断点，重启后可恢复
+- 连接池必须配置合理的超时和最大连接数，防止资源泄漏
+- Spring Boot 应用必须配置 server.shutdown=graceful + spring.lifecycle.timeout-per-shutdown-phase
+- 停机时必须等待正在处理的请求完成（graceful shutdown），设置等待超时（如 30s）
+- 线程池必须在停机时执行 shutdownNow() + awaitTermination()，确保任务不丢失
+- 定时任务必须在停机时停止调度，正在执行的任务必须完成或中断
+- 停机前必须从注册中心（如 Nacos/Eureka）注销，停止接收新流量
+- Spring Boot 必须配置 server.shutdown=graceful 和 spring.lifecycle.timeout-per-shutdown-phase
+
+## 验收项
+- [AC-01] 服务实现优雅停机（等待请求完成）
+- [AC-02] 健康检查区分 liveness/readiness
+- [AC-03] 滚动更新先摘除再停机
+- [AC-04] 启动时等待依赖就绪
+- [AC-05] 请求优雅完成
+- [AC-06] 线程池正确关闭
+- [AC-07] 从注册中心注销

package/templates/patterns//345/205/250/346/240/210/346/265/201/347/250/213/344/277/256/345/244/215.md

@@ -0,0 +1,31 @@
+---
+name: fullstack-flowheal
+type: pattern
+when: 流程修复, 全栈诊断, E2E修复, 修复流程, FlowHeal, 诊断修复, 跨层修复, 流程异常
+scope: [backend, frontend]
+products: ["*"]
+---
+
+## 决策规则
+- 必须严格遵循 5 步顺序：定义用例 → 收集证据 → 诊断 → 补丁计划 → 验证，禁止跳步
+- 证据优先、流程优先、浏览器证据优先、最小补丁、分层验证
+- 禁止将不稳定测试视为业务失败，先稳定复现再判断
+- 禁止删除断言、增加 sleep、降低覆盖率、增加 mock 来制造通过
+- 禁止用 SQL 直接写业务测试数据
+- 禁止自动修改事务/权限/金额/库存/安全策略
+- 一次只修一个问题，禁止跨层大重构同时进行
+- 高风险/低置信度/跨多服务的复杂变更上报人工决策
+- 端到端测试必须从浏览器页面出发，禁止绕过前端
+- 前后端联调必须基于接口文档（OpenAPI），禁止口头约定字段
+- 前后端字段命名不一致时以后端为准，前端通过映射层适配
+- 接口变更必须同步更新文档和前端调用，禁止只改一侧
+- 联调问题必须在缺陷系统记录根因（文档不完整/需求不明确/理解偏差），持续改进
+
+## 验收项
+- [AC-01] 遵循 5 步顺序（用例→证据→诊断→补丁→验证）
+- [AC-02] 证据包含 UI 追踪/API 调用/后端 traceId/数据状态
+- [AC-03] 修复后重新构建再验证
+- [AC-04] 最终状态显式声明（ready_to_commit/escalated/reverted）
+- [AC-05] 联调基于接口文档
+- [AC-06] 接口变更同步更新文档和前端
+- [AC-07] 联调问题记录根因

package/templates/patterns//345/210/206/351/241/265/346/237/245/350/257/242/350/247/204/350/214/203.md

@@ -0,0 +1,27 @@
+---
+name: api-pagination
+type: pattern
+when: 分页查询接口, 分页, 翻页, PageRequest, pagination, 列表查询, 数据列表, 页码, pageSize, pageNo, 查询列表
+scope: [backend]
+products: ["*"]
+---
+
+## 决策规则
+- 必须使用数据库分页查询（LIMIT/OFFSET），禁止内存 subList 分页
+- 必须限制最大 pageSize（不超过 100）
+- 排序字段必须使用白名单校验，禁止直接拼接用户输入
+- 深分页（page > 1000）必须使用游标分页替代 OFFSET
+- 分页响应必须包含 total、page、size、totalPages 字段
+- 深分页（offset > 10000）必须使用游标分页或子查询优化，禁止直接 OFFSET
+- 分页查询禁止使用 SELECT *，必须指定所需字段
+- 排序字段必须是索引列，禁止对非索引列排序导致全表扫描
+- 前端分页控件必须显示总条数和页码跳转
+
+## 验收项
+- [AC-01] page >= 1 且 1 <= size <= 100
+- [AC-02] 使用数据库分页而非内存分页
+- [AC-03] 响应含 total/page/size/totalPages
+- [AC-04] 排序字段白名单校验
+- [AC-05] 深分页有优化策略
+- [AC-06] 排序字段使用索引列
+- [AC-07] 前端有页码跳转

package/templates/patterns//345/211/215/347/253/257/346/200/247/350/203/275/350/247/204/350/214/203.md

@@ -0,0 +1,33 @@
+---
+name: frontend-performance
+type: pattern
+when: 前端性能, 页面加载, 首屏时间, 性能优化, 懒加载, 代码分割, bundle, 白屏时间, FCP, LCP, 内存泄漏
+scope: [frontend]
+products: ["*"]
+---
+
+## 决策规则
+- 路由级别必须使用懒加载（React.lazy / dynamic import），禁止首屏加载所有页面代码
+- 大型第三方库（图表、富文本编辑器）必须按需加载，禁止全量引入
+- 图片必须使用懒加载（Intersection Observer 或 loading="lazy"），大图必须压缩和适配分辨率
+- 列表数据超过 100 条必须使用虚拟滚动（react-window / react-virtualized）
+- 组件卸载时必须清理副作用（定时器、WebSocket、事件监听），防止内存泄漏
+- useEffect 依赖数组必须准确，禁止无依赖导致每次渲染执行
+- 重复渲染必须用 React.memo / useMemo / useCallback 优化，但禁止过度优化（简单组件不需要 memo）
+- 首屏关键资源必须预加载，非关键资源延迟加载
+- 首屏加载时间必须 ≤ 3s（Fast 3G），超过时必须优化（懒加载、代码分割、CDN）
+- 列表渲染超过 100 行必须使用虚拟滚动（react-window / vue-virtual-scroller）
+- 组件重渲染必须有明确优化（React.memo / useMemo / shouldComponentUpdate）
+- 图片资源必须使用 WebP 格式 + CDN 加速 + 懒加载
+- 生产构建必须开启 Tree Shaking + Code Splitting + Gzip 压缩
+
+## 验收项
+- [AC-01] 路由级别懒加载
+- [AC-02] 大型库按需引入
+- [AC-03] 组件卸载清理副作用
+- [AC-04] useEffect 依赖准确无冗余执行
+- [AC-05] 长列表使用虚拟滚动
+- [AC-06] 首屏 ≤ 3s
+- [AC-07] 长列表虚拟滚动
+- [AC-08] 图片 WebP + CDN + 懒加载
+- [AC-09] 生产构建优化开启

package/templates/patterns//345/221/275/345/220/215/350/247/204/350/214/203.md

@@ -0,0 +1,32 @@
+---
+name: naming-convention
+type: pattern
+when: 命名规范, 命名约定, 变量命名, 类命名, 接口命名, 表命名, 字段命名, API路径命名
+scope: [backend, frontend]
+products: ["*"]
+---
+
+## 决策规则
+- Java 类名使用 UpperCamelCase，方法/变量使用 lowerCamelCase，常量使用 UPPER_SNAKE_CASE
+- 数据库表名使用 snake_case，字段名使用 snake_case，主键统一命名为 id
+- API 路径使用 kebab-case 复数名词（如 /api/v1/user-orders），禁止在路径中使用动词
+- 前端组件文件名使用 PascalCase，CSS 类名使用 kebab-case，路由路径使用 kebab-case
+- 禁止使用无业务含义的命名（data、info、result、temp、list、item、obj）
+- Boolean 变量/方法必须以 is/has/can/should 开头（如 isActive、hasPermission）
+- 接口/抽象类命名应体现行为意图（如 UserRepository、PaymentService）
+- 枚举类名使用名词，枚举值使用 UPPER_SNAKE_CASE
+- 包名使用全小写点分隔（com.company.module.service），禁止下划线或大写
+- 常量必须定义在常量类或枚举中，禁止散落在业务代码各处
+- 方法名应为动词或动词短语（getUserById、calculateTotalAmount）
+- 泛型类型参数使用大写单字母或简写（T、E、K、V、R、REQ、RESP）
+- 配置项 key 使用点分隔的 kebab-case（spring.datasource.url）
+
+## 验收项
+- [AC-01] Java 类/方法/变量/常量命名风格一致
+- [AC-02] 数据库表名/字段名统一 snake_case
+- [AC-03] API 路径 kebab-case + 复数名词
+- [AC-04] 前端组件 PascalCase、CSS kebab-case
+- [AC-05] 无无含义命名（data/info/result/temp）
+- [AC-06] Boolean 变量 is/has/can 前缀
+- [AC-07] 方法名为动词短语
+- [AC-08] 枚举值 UPPER_SNAKE_CASE

package/templates/patterns//345/233/275/351/231/205/345/214/226/350/247/204/350/214/203.md

@@ -0,0 +1,31 @@
+---
+name: i18n-l10n
+type: pattern
+when: 国际化, 多语言, i18n, l10n, 语言切换, 多语言支持, 本地化, 翻译, locale, 中英文
+scope: [frontend]
+products: ["*"]
+---
+
+## 决策规则
+- 所有用户可见文案禁止硬编码，必须使用 i18n key（如 t('user.login.title')）
+- 日期格式必须按 locale 显示（中文 yyyy-MM-dd，英文 MM/dd/yyyy），禁止固定格式
+- 金额必须按 locale 格式化（符号位置、千位分隔符、小数位数）
+- 后端接口返回的錙误码必须映射为前端多语言提示，禁止直接展示后端錙误消息
+- 语言资源文件必须按模块拆分，禁止单一大文件（建议 pages/common/components 分目录）
+- 新增语言只需新增资源文件，不修改业务代码
+- 接口返回的业务数据（枚举、状态名）由后端提供多语言字段，前端不维护业务数据翻译
+- 所有用户可见文本必须通过 i18n 资源文件管理，禁止硬编码字符串
+- 日期/时间必须根据用户时区显示，禁止使用服务端固定时区
+- 数字/货币格式必须根据 locale 格式化（如 1,234.56 vs 1.234,56）
+- 文案翻译必须由专业翻译完成，禁止机器翻译直接上线
+- 多语言文案禁止拼装（如 "欢迎" + userName），应使用带占位符的完整模板
+
+## 验收项
+- [AC-01] 用户可见文案通过 i18n key 引用
+- [AC-02] 日期和金额按 locale 格式化
+- [AC-03] 錙误码映射为多语言提示
+- [AC-04] 资源文件按模块拆分
+- [AC-05] 无硬编码用户可见文本
+- [AC-06] 日期时间按时区显示
+- [AC-07] 数字货币按 locale 格式化
+- [AC-08] 无拼装多语言文案

package/templates/patterns//345/242/236/345/210/240/346/224/271/346/237/245/350/247/204/350/214/203.md

@@ -0,0 +1,31 @@
+---
+name: crud-operation
+type: pattern
+when: CRUD, 增删改查, 新建接口, 修改数据, 删除数据, 查询详情, 编辑, 保存, 入库, 新增功能
+scope: [backend]
+products: ["*"]
+---
+
+## 决策规则
+- 必须遵循 Controller → Service → Mapper/Repository 三层分离
+- 禁止 Controller 包含业务逻辑（if/else 分支、计算、状态机）
+- 禁止 DTO 和 Entity 混用，外部请求不可直接操作数据库字段
+- 批量操作禁止在循环中逐条调用数据库
+- 写操作 Service 方法必须有 @Transactional 注解
+- 删除操作必须记录操作人和原因
+- 列表查询接口必须返回分页结构（total、list、pageNum、pageSize），禁止返回全量数据
+- 创建/更新接口必须返回完整实体或 ID，禁止返回 void
+- 逻辑删除必须使用统一字段（如 is_deleted），禁止物理删除业务数据
+- 并发更新场景必须使用乐观锁（version 字段或更新时间条件），防止数据覆盖
+- 批量更新/删除操作必须有数量上限（如 ≤ 500 条），防止大批量锁表
+
+## 验收项
+- [AC-01] Controller 无业务逻辑
+- [AC-02] DTO/Entity 分离
+- [AC-03] 写操作有事务注解
+- [AC-04] 批量操作使用 batch SQL
+- [AC-05] 删除有审计记录
+- [AC-06] 列表查询返回分页结构
+- [AC-07] 创建/更新返回完整数据
+- [AC-08] 逻辑删除而非物理删除
+- [AC-09] 并发更新有乐观锁保护

package/templates/patterns//345/244/226/351/203/250/344/276/235/350/265/226/350/247/204/350/214/203.md

@@ -0,0 +1,29 @@
+---
+name: external-dependency
+type: pattern
+when: 外部依赖, 第三方接口, 外部服务调用, HTTP客户端, Feign, RPC, 微服务调用, 超时, 重试, 降级
+scope: [backend]
+products: ["*"]
+---
+
+## 决策规则
+- 每个外部依赖调用必须定义超时时间，禁止无限等待
+- 需要重试时必须同时定义幂等或去重策略，避免重复副作用
+- 需要降级时必须定义：降级行为、用户提示、恢复条件
+- 新增配置项必须文档化：默认值、环境差异、灰度方式、回滚策略
+- 外部调用失败必须有区别于业务异常的错误码和用户提示
+- 外部依赖必须设置合理的超时时间（连接超时 + 读超时），禁止无限等待
+- 外部依赖调用必须有熔断保护，连续失败 N 次自动熔断
+- 外部依赖必须有降级策略（返回缓存数据/默认值），不能因为依赖故障拖垮主流程
+- 第三方库版本必须锁定（package-lock.json / Gradle version），禁止使用 latest 或范围版本
+- 外部依赖的健康检查必须纳入监控，响应时间/成功率异常时触发告警
+
+## 验收项
+- [AC-01] 外部调用有超时配置
+- [AC-02] 重试操作有幂等/去重策略
+- [AC-03] 降级场景有用户提示和恢复条件
+- [AC-04] 外部调用失败有独立错误码
+- [AC-05] 外部调用有超时配置
+- [AC-06] 有熔断和降级策略
+- [AC-07] 依赖版本锁定
+- [AC-08] 依赖健康检查有监控

package/templates/patterns//345/245/221/347/272/246/345/205/274/345/256/271/350/247/204/350/214/203.md

@@ -0,0 +1,28 @@
+---
+name: contract-compatibility
+type: pattern
+when: 接口变更, API变更, 合同变更, 接口兼容, 向后兼容, 废弃接口, 版本迁移
+scope: [backend]
+products: ["*"]
+---
+
+## 决策规则
+- API 契约是前后端对齐的唯一信源，每次变更必须有 diff 记录和版本说明
+- 变更必须前向兼容，破坏性变更必须标记 deprecated 并提供至少一个完整版本的过渡期
+- 新增必填请求字段、删除字段、改变字段类型、修改路径、改变错误码含义均为破坏性变更，需要废弃流程
+- 每次契约变更必须同步更新接口文档和 schema 定义
+- 禁止前后端口头约定替代正式契约变更
+- 新增可选字段必须设默认值，保证旧客户端兼容
+- 枚举类型新增值必须评估对所有消费方的影响
+- 删除字段必须分阶段：先标记 @Deprecated → 确认无消费方 → 下版本移除
+- 数据库字段变更必须兼容旧代码（先加新字段 → 迁移数据 → 再删旧字段）
+- API 路径变更必须保留旧路径并重定向，给予消费方充足迁移时间
+
+## 验收项
+- [AC-01] 接口变更有 diff 记录
+- [AC-02] 破坏性变更有 deprecated 过渡期
+- [AC-03] 文档与 schema 同步更新
+- [AC-04] 无口头约定的非正式变更
+- [AC-05] 新字段有默认值
+- [AC-06] 删除字段分阶段进行
+- [AC-07] 数据库变更兼容旧代码

package/templates/patterns//345/256/232/346/227/266/344/273/273/345/212/241/350/247/204/350/214/203.md

@@ -0,0 +1,25 @@
+---
+name: scheduled-task
+type: pattern
+when: 定时任务, 异步任务, cron, 调度, @Scheduled, 异步执行, 重试, 延迟任务, 周期任务, 后台任务, 定时执行
+scope: [backend]
+products: ["*"]
+---
+
+## 决策规则
+- 多实例部署的定时任务必须使用分布式锁，禁止裸 @Scheduled
+- 每次执行必须记录状态（开始/结束时间、结果、错误信息）
+- 执行失败必须有告警通知（钉钉/邮件/Slack）
+- 任务执行时间不得超过调度间隔的一半，防止堆积
+- 失败任务必须有重试机制（建议最多 3 次）
+- 定时任务必须配置超时时间，防止任务卡死影响后续调度
+- 定时任务禁止使用固定间隔执行长事务，必须拆分为小批次处理
+- 定时任务必须有手动触发入口（管理后台或 API），便于紧急修复数据
+
+## 验收项
+- [AC-01] 分布式锁防重复执行
+- [AC-02] 每次执行记录状态
+- [AC-03] 失败有告警通知
+- [AC-04] 执行时间不超调度间隔一半
+- [AC-05] 任务有超时配置
+- [AC-06] 有手动触发入口

package/templates/patterns//345/256/236/346/227/266/346/216/250/351/200/201/350/247/204/350/214/203.md

@@ -0,0 +1,33 @@
+---
+name: websocket-realtime
+type: pattern
+when: WebSocket, 实时推送, 实时通知, 在线状态, 即时通讯, SSE, Server-Sent Events, 消息推送, 长连接
+scope: [backend, frontend]
+products: ["*"]
+---
+
+## 决策规则
+- WebSocket 连接必须有心跳机制（建议 30s），检测断线并自动重连
+- 重连必须使用指数退避策略（1s/2s/4s/8s/max 30s），禁止无限重试
+- 消息必须有序号或时间戳，消费端处理乱序和去重
+- 连接异常断开时，未确认消息必须有补偿机制（重新拉取 / 离线消息队列）
+- 后端推送频率必须有熔断保护，防止消息风暴压垮客户端
+- 单向推送优先使用 SSE（更简单），双向通信才使用 WebSocket
+- 生产环境 WebSocket 必须通过 Nginx 反向代理，配置超时和连接数限制
+- 前端组件卸载时必须关闭 WebSocket 连接，防止内存泄漏
+- WebSocket 连接必须有自动重连机制（指数退避策略），断线后自动恢复
+- 推送消息必须携带消息 ID 和时间戳，支持客户端去重和排序
+- 服务端必须实现消息缓冲，用户短暂离线后重连可获取未读消息
+- 推送消息体必须精简（≤ 4KB），大数据通过接口拉取，不通过推送传输
+- 必须支持优雅降级（WebSocket → SSE → 轮询），兼容不同网络环境
+
+## 验收项
+- [AC-01] 有心跳和自动重连机制
+- [AC-02] 重连使用指数退避
+- [AC-03] 消息有去重处理
+- [AC-04] 组件卸载关闭连接
+- [AC-05] 未确认消息有补偿机制
+- [AC-06] 自动重连机制
+- [AC-07] 消息去重和排序
+- [AC-08] 离线消息缓冲
+- [AC-09] 降级策略（WS→SSE→轮询）

package/templates/patterns//345/267/245/347/250/213/347/272/252/345/276/213.md

@@ -0,0 +1,39 @@
+---
+name: engineering-discipline
+type: pattern
+when: 工程纪律, 工作原则, 开发原则, 证据优先, 变更追溯, 缺陷预防, 设计落地, 推论与事实
+scope: [backend, frontend]
+products: ["*"]
+---
+
+## 决策规则
+- 每行代码变更必须可追溯到任务卡片、设计决策或缺陷根因，禁止无来源的孤立变更
+- 解释不替代证据，"理论上修好了"不可接受，必须有执行证据
+- 推论不得冒充事实，必须显式区分已确认事实、推论和未知项
+- 未知项必须显式记录并跟进，禁止静默跳过
+- 规则只从真实缺陷中提取，禁止凭空捏造预防性规则
+- 复发缺陷必须产出至少一条规则或检查项（防复发闭环）
+- 设计必须提供可实施锚点（数据结构、接口定义、状态机），禁止只给抽象原则
+- 先验证后判断，禁止先下结论再找理由
+- 一级证据（运行时、真实部署、真实浏览器）优先于二级文档，禁止用 dry-run/静态分析/AI 摘要冒充运行时证据
+- 根因定位先于代码修改，禁止试错式补丁叠补丁
+- 自动修复循环上限 3 轮，同一错误 >=2 次触发回填，>=4 次记录为复发缺陷
+- 超出范围边界时立即上报，禁止自行决定扩范围
+- 编译告警必须全部处理，禁止忽略（设置 -Werror 或 CI 编译告警数阈值）
+- 代码提交前必须本地通过编译和单元测试，禁止把明显错误提交到远端
+- 依赖升级必须逐个进行并验证，禁止批量升级多个依赖
+- 线上配置变更必须通过配置中心（Nacos/Apollo），禁止直接修改配置文件重启
+- 每次发布必须有回滚方案和验证清单，不能"改了就上线"
+
+## 验收项
+- [AC-01] 代码变更可追溯到任务或缺陷
+- [AC-02] 推论与事实有显式区分标记
+- [AC-03] 缺陷修复有执行证据
+- [AC-04] 复发缺陷有防复发规则
+- [AC-05] 运行时证据替代 dry-run/AI 摘要
+- [AC-06] 自动修复循环未超过 3 轮
+- [AC-07] 超范围变更有上报记录
+- [AC-08] 编译告警全部处理
+- [AC-09] 提交前本地验证
+- [AC-10] 依赖逐个升级
+- [AC-11] 发布有回滚方案

package/templates/patterns//345/271/266/345/217/221/346/216/247/345/210/266/350/247/204/350/214/203.md

@@ -0,0 +1,34 @@
+---
+name: concurrency-control
+type: pattern
+when: 并发控制, 并发, 锁, 乐观锁, 悲观锁, 分布式锁, 竞态条件, 超卖, 库存扣减, 重复提交, 原子操作, 幂等, 去重
+scope: [backend]
+products: ["*"]
+---
+
+## 决策规则
+- 涉及金额、库存、配额、计数器等可变共享状态的操作必须显式声明并发控制策略
+- 乐观锁适用于读多写少场景（版本号字段 + CAS），悲观锁适用于写多竞争激烈场景（SELECT FOR UPDATE）
+- 分布式环境必须使用分布式锁（Redis SETNX / Redisson / ZooKeeper），禁止依赖 JVM 级锁跨实例
+- 锁粒度必须最小化：锁具体资源而非整个表，锁业务 ID 而非全局锁
+- 分布式锁必须设置超时时间（防止死锁），建议默认 30 秒
+- 幂等方案优先于加锁：唯一约束、去重表、Token 机制比分布式锁更可靠
+- 超卖/超扣场景必须使用数据库原子操作（UPDATE SET stock = stock - 1 WHERE stock >= 1），禁止先查后改
+- 乐观锁冲突必须有用户可见提示（"数据已被修改，请刷新重试"），禁止静默失败
+- 批量并发操作必须限制并发度（信号量/线程池），禁止无限制并发
+- ThreadLocal 必须在请求结束时 remove()，否则线程池复用导致数据串线
+- 锁的获取和释放必须在同一个 try-finally 块中，防止异常导致死锁
+- 分布式锁必须设置过期时间（如 30s），防止持有者崩溃导致永久死锁
+- 原子操作优先使用 CAS（AtomicInteger/LongAdder），无竞争场景性能优于锁
+- 线程池必须通过 ThreadPoolExecutor 构造函数创建，禁止使用 Executors（避免 OOM）
+
+## 验收项
+- [AC-01] 共享可变状态操作有显式并发控制策略
+- [AC-02] 分布式锁有超时设置
+- [AC-03] 超卖场景使用原子操作而非先查后改
+- [AC-04] 乐观锁冲突有用户提示
+- [AC-05] 批量并发操作有并发度限制
+- [AC-06] ThreadLocal 请求结束清理
+- [AC-07] 锁释放 try-finally 保护
+- [AC-08] 分布式锁有超时时间
+- [AC-09] 线程池显式创建

package/templates/patterns//345/274/202/346/255/245/345/257/274/345/207/272/350/247/204/350/214/203.md

@@ -0,0 +1,27 @@
+---
+name: async-export
+type: pattern
+when: 异步导出, 数据导出, 批量导出, 报表导出, CSV, Excel, PDF, 下载, 文件导出, 导出功能
+scope: [backend]
+products: ["*"]
+---
+
+## 决策规则
+- 超过 1000 条数据必须走异步导出，返回任务 ID
+- 异步导出任务必须有状态追踪（PENDING/PROCESSING/COMPLETED/FAILED）
+- 导出文件必须存储在对象存储，禁止堆积在本地磁盘
+- 导出文件必须设置过期时间（建议 24 小时），到期自动清理
+- 导出文件必须包含表头行，字段名对齐业务术语
+- 大数据量导出必须异步执行，通过 WebSocket/轮询通知完成状态
+- 导出数据量必须有上限（如单次 ≤ 100 万行），超限提示用户缩小范围
+- 导出过程必须有进度反馈（已完成 X/Y 条），提升用户体验
+- 导出失败必须通知用户并提供重试机制
+
+## 验收项
+- [AC-01] 大数据量走异步导出返回任务 ID
+- [AC-02] 任务有状态追踪
+- [AC-03] 文件 24 小时内自动清理
+- [AC-04] 导出文件含表头行
+- [AC-05] 大导出异步执行并有通知
+- [AC-06] 导出文件有过期清理
+- [AC-07] 有进度反馈

package/templates/patterns//346/216/245/345/217/243/345/245/221/347/272/246/350/247/204/350/214/203.md

@@ -0,0 +1,30 @@
+---
+name: interface-contract
+type: pattern
+when: 接口文档, API文档, 接口契约, Swagger, 接口定义, 接口规范, 字段定义, 接口评审
+scope: [backend]
+products: ["*"]
+---
+
+## 决策规则
+- 每个接口必须有完整定义：路径、方法、认证、请求、响应、错误码
+- 页面交互与接口必须有映射表确保一一对应
+- 每个接口至少定义：校验失败、权限不足、业务异常、资源不存在四种错误
+- 所有枚举字段必须列出完整值集和含义，禁止无枚举定义的 type/status/flag 字段
+- 每个接口必须显式声明幂等性和认证属性
+- 接口契约中鉴权要求必须能回链到角色与权限模型
+- 接口文档必须与代码同步更新，禁止文档与实现不一致
+- 破坏性变更必须通过版本号隔离（如 /v1/ → /v2/），保证旧客户端兼容
+- 接口响应时间必须有 SLA 约定（如 P99 < 500ms），超时触发告警
+- 接口必须定义错误码体系（业务错误码 + HTTP 状态码），客户端可区分处理
+- 接口变更必须通知所有消费方，并给予充足的迁移时间
+
+## 验收项
+- [AC-01] 接口文档包含完整定义（路径/方法/认证/请求/响应/错误）
+- [AC-02] 页面交互与接口有映射表
+- [AC-03] 枚举字段有完整值集定义
+- [AC-04] 接口声明了幂等性和认证属性
+- [AC-05] 文档与代码同步
+- [AC-06] 破坏性变更版本隔离
+- [AC-07] 有 SLA 约定和监控
+- [AC-08] 错误码体系完整

package/templates/patterns//346/220/234/347/264/242/346/250/241/345/274/217/350/247/204/350/214/203.md

@@ -0,0 +1,32 @@
+---
+name: search-pattern
+type: pattern
+when: 搜索, 全文搜索, 搜索功能, 筛选, 过滤, 查询条件, 多条件查询, 动态查询, Elasticsearch, 搜索引擎, 模糊搜索
+scope: [backend, frontend]
+products: ["*"]
+---
+
+## 决策规则
+- 列表筛选条件超过 3 个必须封装为 SearchRequest 对象，禁止平铺查询参数
+- 动态查询必须使用 MyBatis 动态 SQL 或 JPA Specification，禁止字符串拼接 SQL
+- 模糊搜索（LIKE）必须考虑前缀匹配和索引利用，禁止全表扫描 `%keyword%`
+- 大数据量全文搜索必须使用 Elasticsearch，禁止数据库 LIKE 性能瓶颈
+- 搜索结果必须分页，禁止返回全量匹配结果
+- 搜索条件组合必须明确 AND/OR 语义，禁止歧义
+- 搜索接口响应时间目标 < 200ms，超过时必须优化（索引/缓存/ES）
+- 前端搜索框必须有防抖（建议 300ms），禁止每次按键触发请求
+- 搜索接口必须支持分页，禁止无限制返回结果
+- 搜索结果必须高亮关键词，提升用户定位效率
+- 搜索字段必须建立索引（Elasticsearch mapping 或数据库索引），禁止全表扫描
+- 搜索关键词必须做长度限制和特殊字符过滤，防止恶意查询
+- 搜索结果必须按相关度排序，支持用户自定义排序条件
+
+## 验收项
+- [AC-01] 筛选条件封装为对象
+- [AC-02] 动态查询无 SQL 拼接
+- [AC-03] 搜索结果分页
+- [AC-04] 搜索接口响应 < 200ms
+- [AC-05] 前端搜索有防抖
+- [AC-06] 搜索接口分页
+- [AC-07] 关键词高亮
+- [AC-08] 搜索字段有索引

package/templates/patterns//346/225/260/346/215/256/351/232/220/347/247/201/350/247/204/350/214/203.md

@@ -0,0 +1,31 @@
+---
+name: data-privacy
+type: pattern
+when: 数据隐私, 脱敏, 敏感数据, 个人信息, PII, GDPR, 数据保护, 数据安全, 手机号, 身份证, 银行卡, 数据加密
+scope: [backend, frontend]
+products: ["*"]
+---
+
+## 决策规则
+- 手机号、身份证号、银行卡号、邮箱、地址等 PII 字段必须脱敏展示（手机号 138****1234，身份证 310***********1234）
+- 数据库中密码必须 BCrypt 哈希，身份证/银行卡等必须 AES 加密存储，禁止明文
+- 日志中禁止打印完整 PII 字段，必须脱敏或掩码处理
+- 接口响应中敏感字段必须默认脱敏，需要明文的场景必须单独授权接口
+- 数据导出（Excel/CSV）包含 PII 字段时必须有权限控制和操作审计
+- 用户注销/数据删除请求必须级联清理所有关联 PII 数据，包括备份中的软删除标记
+- 数据查询接口禁止支持全量导出 PII 数据，必须分页且有导出上限
+- 前端禁止在 URL 参数、LocalStorage 明文存储敏感信息
+- 个人敏感信息（身份证、手机号、银行卡）存储必须加密或脱敏
+- 数据删除必须支持真删除（不只是软删除标记），满足 GDPR/个人信息保护法要求
+- 用户注销必须清除或匿名化关联个人数据，不能只禁用账号
+- 用户数据导出必须经过审批，导出文件必须加密传输
+
+## 验收项
+- [AC-01] PII 字段展示时有脱敏处理
+- [AC-02] 敏感字段加密存储非明文
+- [AC-03] 日志不含完整 PII 数据
+- [AC-04] 数据导出有权限控制和审计
+- [AC-05] 用户注销关联数据已清理
+- [AC-06] 敏感信息加密存储
+- [AC-07] 接口/日志中敏感信息脱敏
+- [AC-08] 支持数据真删除和匿名化

package/templates/patterns//346/226/207/344/273/266/344/270/212/344/274/240/350/247/204/350/214/203.md

@@ -0,0 +1,31 @@
+---
+name: file-upload
+type: pattern
+when: 文件上传, 上传文件, 文件存储, OSS, 图片上传, 附件上传, multipart, 文件下载, 对象存储
+scope: [backend]
+products: ["*"]
+---
+
+## 决策规则
+- 文件必须存储到对象存储（OSS/MinIO/S3），禁止存本地磁盘
+- 必须校验文件类型白名单（禁止 .exe/.sh/.jsp 等）
+- 必须限制文件大小（默认 10MB）
+- 禁止使用原始文件名，必须 UUID 重命名防路径遍历
+- 上传接口必须校验文件 MIME 类型和扩展名双重验证
+- 图片类上传必须校验实际文件头（magic bytes），不能只依赖扩展名
+- 必须配置上传文件总容量限制（单个用户/租户），防止存储滥用
+- 下载链接必须使用签名 URL 或一次性 token，禁止永久公开 URL
+- 禁止上传目录有执行权限（chmod -x），防止上传的脚本被服务器执行
+- 文件上传必须异步处理（先上传再后台扫描），大文件必须支持断点续传
+- 必须记录文件上传/下载审计日志（操作人、时间、文件名、大小）
+
+## 验收项
+- [AC-01] 文件类型白名单校验
+- [AC-02] 文件大小限制（默认 10MB）
+- [AC-03] UUID 重命名文件
+- [AC-04] 存储在对象存储而非本地磁盘
+- [AC-05] 文件头 magic bytes 校验
+- [AC-06] 用户/租户存储容量限制
+- [AC-07] 下载链接签名或一次性 token
+- [AC-08] 上传目录无执行权限
+- [AC-09] 上传/下载审计日志