soloforge 1.1.40 → 1.1.43

package/templates/verify//345/217/221/345/270/203/345/220/216/345/256/241/346/237/245.md

@@ -0,0 +1,75 @@
+---
+id: ka-review-rule-发布后审查规则
+kind: guidance
+title: 发布后审查
+sync_policy: copy_to_project
+status: active
+triggers:
+  - 发布后
+  - 上线观察
+  - post-release review
+extra:
+  name: post-release-review
+  type: constraint
+  scope:
+    - backend
+    - frontend
+  products:
+    - '*'
+  lifecycle_status: active
+  authority: supporting
+  priority: P1
+  version: 1.2.0
+  last_reviewed: '2026-06-04'
+  domain: verify
+  verification_layer: L2
+  stage: verify
+  owner_mechanism: mc-delivery-gate
+---
+
+# 发布后审查规则
+
+## REL-01: 监控指标在阈值内
+
+check_hint: 发布后关键监控指标必须在正常范围内
+severity: error
+check_type: deterministic
+scope: [backend, frontend]
+description: 错误率、响应时间、吞吐量等关键指标在发布后 30 分钟内必须在历史基线 ±20% 范围内。监控指标必须通过，不得为建议项。
+evidence_required:
+  - "监控指标报告路径"
+  - "错误率/响应时间/吞吐量数值"
+  - "与基线对比结果（须在 ±20% 范围内）"
+
+## REL-02: 无新增告警
+
+check_hint: 发布后不得产生新的异常告警
+severity: warning
+check_type: deterministic
+scope: [backend, frontend]
+description: 发布后检查告警系统，不得有因本次发布新增的错误日志或异常告警
+evidence_required:
+  - "告警系统检查结果"
+  - "新增告警列表（须为空）"
+
+## REL-03: 回滚预案已验证
+
+check_hint: 回滚操作必须在发布前验证过
+severity: warning
+check_type: deterministic
+scope: [backend, frontend]
+description: 回滚预案必须经过实际演练或自动化验证，确认回滚操作可在 5 分钟内完成
+evidence_required:
+  - "回滚预案文档路径"
+  - "演练/验证记录"
+
+## REL-04: 数据一致性确认
+
+check_hint: 发布后必须验证数据一致性
+severity: warning
+check_type: deterministic
+scope: backend
+description: 涉及数据库变更的发布，发布后必须验证新老数据的一致性（数据校验脚本通过）
+evidence_required:
+  - "数据一致性校验脚本路径"
+  - "校验结果（须通过）"

package/templates/verify//345/220/216/347/253/257API.md

@@ -0,0 +1,45 @@
+---
+id: ka-artifact_template-backend-api
+kind: artifact
+title: 后端API
+sync_policy: copy_to_project
+status: active
+extra:
+  name: backend-api
+  scope:
+    - backend
+  products:
+    - '*'
+  lifecycle_status: active
+  authority: supporting
+  priority: P2
+  version: 1.1.0
+  last_reviewed: '2026-06-01'
+  consumes: []
+  emits:
+    - acceptance_report
+  type: artifact
+  domain: verify
+  requires_context: []
+  stage: verify
+  owner_mechanism: mc-backend-implementation-contract
+---
+
+## 验收项
+- [AC-01] Controller 层无业务逻辑（无 if/else 分支、计算、状态机） (check: grep -rn 'if\s*(.*>.*)\|if\s*(.*< .*)' {file} --include='*Controller.java')
+- [AC-02] DTO 与 Entity 分离，请求/响应使用 DTO，不直接暴露 Entity (check: grep -c 'Entity\|@Table' {file} && grep -c 'class.*DTO\|class.*Request\|class.*Response' {file})
+- [AC-03] 写操作 Service 方法有 @Transactional 注解 (check: grep -B2 'public.*save\|public.*update\|public.*delete\|public.*create' {file} | grep -c '@Transactional')
+- [AC-04] 批量操作使用 batch SQL，无循环内逐条调用 (check: grep -A5 'for\s*(' {file} | grep -c 'mapper\.\|repository\.\|dao\.')
+- [AC-05] 删除操作记录操作人和原因 (check: grep -A5 'delete\|remove' {file} | grep -c 'operator\|reason\|操作人')
+- [AC-06] 所有异常经全局异常处理器返回，无散落 try-catch 吞异常 (check: grep -c 'catch\s*(.*Exception\s*\w*)\s*\{\s*\}' {file})
+- [AC-07] 接口有 @Valid 或手动参数校验，不信任外部输入 (check: grep -c '@Valid\|@NotNull\|@NotBlank\|@Size\|validate' {file})
+- [AC-08] 关键写操作有 INFO 级别审计日志（操作者/时间/对象） (check: grep -c 'log\.info\|auditLog\|操作日志' {file})
+- [AC-09] 日志中无敏感信息（密码/token/身份证号） (check: grep -ic 'password\|token\|secret\|idcard\|身份证' {file})
+- [AC-10] 权限检查注解到位（@PreAuthorize 或自定义鉴权） (check: grep -c '@PreAuthorize\|@RequiresPermissions\|checkPermission' {file})
+- [AC-11] API 是否有版本号路径前缀（/api/v1/） (check: grep -c '@RequestMapping.*"/api/v[0-9]' {file})
+- [AC-12] 写接口是否有幂等设计（幂等键或唯一约束） (check: grep -c 'Idempotent\|幂等\|idempotent' {file})
+- [AC-13] 分页接口是否返回标准分页结构（total、list、pageNum、pageSize） (check: grep -c 'PageResult\|PageInfo\|PageResponse\|total.*list' {file})
+- [AC-14] 是否有全局统一错误码体系 (check: grep -c 'ErrorCode\|BizCode\|ResultCode\|错误码' {file})
+- [AC-15] 接口文档是否与实现同步（Swagger/OpenAPI 注解完整） (check: grep -c '@ApiOperation\|@Schema\|summary' {file})
+- [AC-16] 是否有速率限制保护 (check: grep -c '@RateLimit\|RateLimiter\|限流\|rate' {file})
+- [AC-17] 批量操作是否有数量上限（≤ 500 条） (check: grep -c '@Size.*max\|MAX_BATCH\|batchSize\|批量上限' {file})

package/templates/verify//345/242/236/345/210/240/346/224/271/346/237/245.md

@@ -0,0 +1,49 @@
+---
+id: ka-pattern-crud-operation
+kind: knowledge
+title: 增删改查
+sync_policy: copy_to_project
+status: active
+extra:
+  name: crud-operation
+  scope:
+    - backend
+  products:
+    - '*'
+  lifecycle_status: active
+  authority: supporting
+  priority: P2
+  version: 1.1.0
+  last_reviewed: '2026-06-01'
+  consumes: []
+  emits: []
+  type: knowledge
+  domain: verify
+  verification_layer: L2
+  stage: verify
+  owner_mechanism: mc-backend-pattern
+---
+
+## 决策规则
+- 必须遵循 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/verify//345/244/226/351/203/250/344/276/235/350/265/226.md

@@ -0,0 +1,47 @@
+---
+id: ka-pattern-external-dependency
+kind: knowledge
+title: 外部依赖
+sync_policy: copy_to_project
+status: active
+extra:
+  name: external-dependency
+  scope:
+    - backend
+  products:
+    - '*'
+  lifecycle_status: active
+  authority: supporting
+  priority: P2
+  version: 1.1.0
+  last_reviewed: '2026-06-01'
+  consumes: []
+  emits: []
+  type: knowledge
+  domain: verify
+  verification_layer: L2
+  stage: verify
+  owner_mechanism: mc-backend-pattern
+---
+
+## 决策规则
+- 每个外部依赖调用必须定义超时时间，禁止无限等待
+- 需要重试时必须同时定义幂等或去重策略，避免重复副作用
+- 需要降级时必须定义：降级行为、用户提示、恢复条件
+- 新增配置项必须文档化：默认值、环境差异、灰度方式、回滚策略
+- 外部调用失败必须有区别于业务异常的错误码和用户提示
+- 外部依赖必须设置合理的超时时间（连接超时 + 读超时），禁止无限等待
+- 外部依赖调用必须有熔断保护，连续失败 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/verify//345/245/221/347/272/246/345/205/274/345/256/271.md

@@ -0,0 +1,46 @@
+---
+id: ka-pattern-contract-compatibility
+kind: knowledge
+title: 契约兼容
+sync_policy: copy_to_project
+status: active
+extra:
+  name: contract-compatibility
+  scope:
+    - backend
+  products:
+    - '*'
+  lifecycle_status: active
+  authority: supporting
+  priority: P2
+  version: 1.1.0
+  last_reviewed: '2026-06-01'
+  consumes: []
+  emits: []
+  type: knowledge
+  domain: verify
+  verification_layer: L2
+  stage: verify
+  owner_mechanism: mc-backend-pattern
+---
+
+## 决策规则
+- 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/verify//345/256/232/346/227/266/344/273/273/345/212/241.md

@@ -0,0 +1,43 @@
+---
+id: ka-pattern-scheduled-task
+kind: knowledge
+title: 定时任务
+sync_policy: copy_to_project
+status: active
+extra:
+  name: scheduled-task
+  scope:
+    - backend
+  products:
+    - '*'
+  lifecycle_status: active
+  authority: supporting
+  priority: P2
+  version: 1.1.0
+  last_reviewed: '2026-06-01'
+  consumes: []
+  emits: []
+  type: knowledge
+  domain: verify
+  verification_layer: L2
+  stage: verify
+  owner_mechanism: mc-backend-pattern
+---
+
+## 决策规则
+- 多实例部署的定时任务必须使用分布式锁，禁止裸 @Scheduled
+- 每次执行必须记录状态（开始/结束时间、结果、错误信息）
+- 执行失败必须有告警通知（钉钉/邮件/Slack）
+- 任务执行时间不得超过调度间隔的一半，防止堆积
+- 失败任务必须有重试机制（建议最多 3 次）
+- 定时任务必须配置超时时间，防止任务卡死影响后续调度
+- 定时任务禁止使用固定间隔执行长事务，必须拆分为小批次处理
+- 定时任务必须有手动触发入口（管理后台或 API），便于紧急修复数据
+
+## 验收项
+- [AC-01] 分布式锁防重复执行
+- [AC-02] 每次执行记录状态
+- [AC-03] 失败有告警通知
+- [AC-04] 执行时间不超调度间隔一半
+- [AC-05] 任务有超时配置
+- [AC-06] 有手动触发入口

package/templates/verify//345/256/236/346/227/266/346/216/250/351/200/201.md

@@ -0,0 +1,52 @@
+---
+id: ka-pattern-websocket-realtime
+kind: knowledge
+title: 实时推送
+sync_policy: copy_to_project
+status: active
+extra:
+  name: websocket-realtime
+  scope:
+    - backend
+    - frontend
+  products:
+    - '*'
+  lifecycle_status: active
+  authority: supporting
+  priority: P2
+  version: 1.1.0
+  last_reviewed: '2026-06-01'
+  consumes: []
+  emits: []
+  type: knowledge
+  domain: verify
+  verification_layer: L2
+  stage: verify
+  owner_mechanism: mc-general-pattern
+---
+
+## 决策规则
+- 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/verify//345/256/241/346/237/245/346/221/230/350/246/201.md

@@ -0,0 +1,64 @@
+---
+id: ka-artifact_template-审查摘要
+kind: artifact
+title: 审查摘要
+sync_policy: copy_to_project
+status: active
+extra:
+  name: review-summary
+  scope:
+    - '*'
+  products:
+    - '*'
+  lifecycle_status: active
+  authority: supporting
+  priority: P2
+  version: 1.2.0
+  last_reviewed: '2026-06-04'
+  consumes: []
+  emits:
+    - acceptance_report
+  type: artifact
+  domain: verify
+  requires_context: []
+  stage: verify
+  owner_mechanism: mc-verifier
+---
+
+## 摘要格式规范
+
+每个白盒审查项必须生成压缩摘要，格式为:
+`[文件名:行号] 维度: 标题`
+
+示例:
+```text
+[llm_gateway.ts:156] security: Token 预算未检查
+[evolver.ts:42] quality: 知识提取逻辑缺失空值守卫
+```
+
+## 维度覆盖
+维度覆盖: 安全✅ 性能✅ 并发✅ 架构✅ SOLID✅ 契约✅ 可维护性✅ 交付✅ 决策❌ 交叉验证✅
+AI 盲区维度: [列出未覆盖维度及建议补充方式]
+
+## 汇报格式
+
+```text
+审查结果: X 项发现
+- 白盒 (可跳过): N 项 — [一句话汇总]
+- 灰盒 (需签署): N 项 — [逐项展示 + 抽检回溯摘要流]
+- 黑盒 (强制签署): N 项 — [逐项展示 + 等待 [Human-Audit: APPROVED]]
+```
+
+## 抽检哨兵规则
+
+- 每处理 10 个白盒项，强制随机升级 1 个为灰盒
+- 升级时自动渲染前置白盒摘要流（spot_check_backtrace）
+- 摘要流格式: 连续的白盒项摘要，供人类快速回溯
+- 人类审计时随机提问: 基于任务摘要生成是/否问题，校验审计真实性
+
+## 回溯链路
+
+1. 白盒项分类时自动缓存到 summaryCache（模块级 Map）
+2. 抽检哨兵触发时从缓存渲染所有白盒摘要
+3. renderSummaryBacktrace(taskId) 支持回溯任意历史任务
+4. 回溯摘要附加到 CodeReviewResult.spot_check_backtrace

package/templates/verify//345/267/245/344/275/234/346/265/201.md

@@ -0,0 +1,42 @@
+---
+id: ka-checklist-工作流验收清单
+kind: artifact
+title: 工作流
+sync_policy: copy_to_project
+status: active
+extra:
+  name: workflow-acceptance
+  type: artifact
+  scope:
+    - '*'
+  products:
+    - '*'
+  lifecycle_status: active
+  authority: supporting
+  priority: P1
+  emits: []
+  version: 1.1.0
+  last_reviewed: '2026-06-01'
+  domain: verify
+  verification_layer: L2
+  stage: verify
+  owner_mechanism: mc-workflow-contract
+---
+
+# 工作流验收清单
+
+## 必检项
+
+- [ ] 工作流 ID 在 Workflow Contract Registry 中已注册
+- [ ] required_mechanisms 中的每个机制在 Mechanism Contract Registry 中存在
+- [ ] 知识注入边界 (mc-knowledge-injection-boundary) 被引用
+- [ ] workflow scope 覆盖所有预期产出文件
+- [ ] read-only 工作流无 mutation 产出
+- [ ] 验证策略 (verification_strategy) 已声明
+- [ ] 交付门禁 (delivery_gate) 已声明
+
+## 禁止项
+
+- [ ] 未注册的工作流 ID
+- [ ] 缺失 required_mechanisms
+- [ ] 读写权限不一致

package/templates/verify//345/271/266/345/217/221/345/256/241/346/237/245.md

@@ -0,0 +1,134 @@
+---
+id: ka-review-rule-并发审查规则
+kind: guidance
+title: 并发审查
+triggers:
+  - 并发
+  - 线程
+  - 锁
+  - 异步
+  - 线程安全
+sync_policy: copy_to_project
+status: active
+extra:
+  name: concurrency-rules
+  type: constraint
+  scope:
+    - backend
+  products:
+    - '*'
+  lifecycle_status: active
+  authority: supporting
+  priority: P1
+  version: 1.2.0
+  last_reviewed: '2026-06-04'
+  domain: verify
+  verification_layer: L2
+  stage: verify
+  owner_mechanism: mc-generic-review
+---
+
+## CON-01: 共享可变状态无并发保护
+languages: [java]
+pattern: /synchronized|ReentrantLock|AtomicInteger|volatile/
+severity: error
+check_type: deterministic
+scope: backend
+description: 涉及金额、库存、计数器的操作必须显式声明并发控制策略。若未使用任何并发控制原语，标记为需人工确认
+evidence_required:
+  - "扫描结果：含共享可变状态的文件路径+行号"
+  - "并发控制策略声明"
+
+## CON-02: 分布式环境使用 JVM 级锁
+languages: [java]
+pattern: /synchronized\s*\(|ReentrantLock/
+severity: warning
+check_type: deterministic
+scope: backend
+description: 多实例部署场景下 synchronized/ReentrantLock 无法跨 JVM，必须使用分布式锁（Redis/Redisson）
+evidence_required:
+  - "扫描结果：含 JVM 级锁的文件路径+行号"
+  - "部署架构确认（单实例/多实例）"
+
+## CON-03: 先查后改未用原子操作
+languages: [通用]
+pattern: /SELECT.*stock|SELECT.*count|SELECT.*amount.*WHERE/
+severity: warning
+check_type: deterministic
+scope: backend
+description: 库存/余额/计数器等场景禁止先 SELECT 再 UPDATE，必须使用原子操作（UPDATE SET x = x - 1 WHERE x >= 1）
+evidence_required:
+  - "扫描结果：含先查后改模式的文件路径+行号"
+
+## CON-04: @Transactional 同类内部调用
+languages: [java]
+pattern: /this\.|@Transactional/
+severity: warning
+check_type: deterministic
+scope: backend
+description: @Transactional 方法被同类内部 this.xxx() 调用时 AOP 代理失效，事务不生效
+evidence_required:
+  - "扫描结果：含 this 调用事务方法的文件路径+行号"
+
+## CON-05: 事务内执行外部调用
+languages: [java]
+pattern: /RestTemplate|FeignClient|HttpClient|WebClient/
+severity: info
+check_type: deterministic
+scope: backend
+description: 事务方法中执行外部 HTTP 调用会延长事务持有时间，建议移到事务外或使用 REQUIRES_NEW 隔离
+evidence_required:
+  - "扫描结果：事务内外部调用的文件路径+行号"
+
+## CON-06: SimpleDateFormat 非线程安全
+languages: [java]
+pattern: /SimpleDateFormat/
+severity: warning
+check_type: deterministic
+scope: backend
+description: SimpleDateFormat 非线程安全，多线程共享会导致日期解析错误，使用 DateTimeFormatter 或 ThreadLocal
+evidence_required:
+  - "扫描结果：含 SimpleDateFormat 的文件路径+行号"
+
+## CON-07: ThreadLocal 未清理导致内存泄漏
+languages: [java]
+pattern: /ThreadLocal\s*<|new\s+ThreadLocal/
+severity: warning
+check_type: deterministic
+scope: backend
+description: ThreadLocal 必须在请求结束时 remove()，否则线程池复用会导致内存泄漏和数据串线
+evidence_required:
+  - "扫描结果：含 ThreadLocal 的文件路径+行号"
+  - "remove() 调用确认"
+
+## CON-08: 非线程安全的集合用作类成员变量
+languages: [java]
+pattern: /private\s+(?:static\s+)?(?:final\s+)?(?:HashMap|ArrayList|LinkedList|HashSet)\s*</
+severity: warning
+check_type: deterministic
+scope: backend
+description: 类级别的共享集合必须使用 ConcurrentHashMap/CopyOnWriteArrayList 等线程安全实现
+evidence_required:
+  - "扫描结果：含非线程安全集合的文件路径+行号"
+
+## CON-09: CompletableFuture 未处理异常
+languages: [java]
+pattern: /CompletableFuture.*(?:thenApply|thenAccept|thenCompose)\s*\(/
+severity: warning
+check_type: deterministic
+scope: backend
+description: CompletableFuture 链必须以 exceptionally() 或 handle() 结尾，防止异常被静默吞掉
+evidence_required:
+  - "扫描结果：含 CompletableFuture 的文件路径+行号"
+  - "异常处理链确认"
+
+## CON-10: 线程池未正确配置拒绝策略
+languages: [java]
+pattern: /new\s+ThreadPoolExecutor\s*\(/
+severity: warning
+check_type: deterministic
+scope: backend
+description: 线程池必须显式配置拒绝策略（CallerRunsPolicy/自定义），禁止使用默认 AbortPolicy
+evidence_required:
+  - "扫描结果：含线程池创建的文件路径+行号"
+  - "拒绝策略配置确认"

package/templates/verify//345/274/202/346/255/245/345/257/274/345/207/272.md

@@ -0,0 +1,45 @@
+---
+id: ka-pattern-async-export
+kind: knowledge
+title: 异步导出
+sync_policy: copy_to_project
+status: active
+extra:
+  name: async-export
+  scope:
+    - backend
+  products:
+    - '*'
+  lifecycle_status: active
+  authority: supporting
+  priority: P2
+  version: 1.1.0
+  last_reviewed: '2026-06-01'
+  consumes: []
+  emits: []
+  type: knowledge
+  domain: verify
+  verification_layer: L2
+  stage: verify
+  owner_mechanism: mc-backend-pattern
+---
+
+## 决策规则
+- 超过 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] 有进度反馈