artifact-chain-assistant 0.8.0

package/templates/extended/contracts/data_contract/starter.md

@@ -0,0 +1,88 @@
+---
+id: {DATA_ID}
+title: {数据契约名称}
+status: draft
+version: {v1}
+related_features: []
+---
+
+# {DATA_ID}: {数据契约名称}
+
+<!-- 本模板是插件 starter 指导，项目本地模板可完全覆盖 -->
+<!-- 插件模板是入门指导，项目本地模板是权威 -->
+
+## 概述
+
+{描述这个数据契约的用途、数据来源和消费方}
+
+## 基础信息
+
+- **版本**：{version}
+- **数据格式**：JSON / Avro / Protobuf / Parquet
+- **生产者**：{数据生产服务}
+- **消费者**：{数据消费服务列表}
+
+## 数据模型
+
+### Schema 定义
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "field1": {
+      "type": "string",
+      "description": "字段描述"
+    },
+    "field2": {
+      "type": "integer",
+      "minimum": 0
+    }
+  },
+  "required": ["field1"]
+}
+```
+
+### 字段说明
+
+| 字段 | 类型 | 必填 | 描述 | 约束 |
+|------|------|------|------|------|
+| field1 | string | 是 | {描述} | max: 255 |
+| field2 | integer | 否 | {描述} | min: 0 |
+
+## 数据质量规则
+
+| 规则 | 描述 | 验证方式 |
+|------|------|---------|
+| 完整性 | {规则描述} | {验证方法} |
+| 一致性 | {规则描述} | {验证方法} |
+| 时效性 | {规则描述} | {验证方法} |
+
+## 版本兼容性
+
+### 兼容变更
+
+- 添加可选字段
+- 放宽字段约束
+
+### 破坏性变更
+
+- 删除字段
+- 修改字段类型
+- 收紧字段约束
+
+## 数据血缘
+
+{描述数据流转路径和依赖关系}
+
+## 关联制品
+
+- 功能特性：{related_features}
+- 设计文档：{related_designs}
+
+## 变更日志
+
+| 日期 | 版本 | 变更 | 作者 |
+|------|------|------|------|
+| {YYYY-MM-DD} | v1 | 初始版本 | {作者} |

package/templates/extended/contracts/integration_contract/review-checklist.md

@@ -0,0 +1,77 @@
+# Integration Contract 审查清单
+
+<!-- 本清单是插件通用基线，项目本地审查规则可覆盖 -->
+
+## 结构完整性
+
+- [ ] `id` 字段存在且符合项目 ID 模式（如 `INT-{nnn}`）
+- [ ] `title` 清晰描述集成范围
+- [ ] `version` 字段存在且符合语义化版本
+- [ ] `status` 字段存在且为有效值
+- [ ] `protocol` 字段存在且为有效协议
+- [ ] `external_system` 字段存在
+
+## 连接配置
+
+- [ ] 端点信息完整（开发 / 测试 / 生产）
+- [ ] 认证方式已说明
+- [ ] 凭证管理策略已定义
+- [ ] 超时配置已定义（连接 / 读取 / 写入）
+
+## 接口质量
+
+- [ ] 所有接口有清晰描述
+- [ ] 请求格式完整且示例正确
+- [ ] 响应格式完整且示例正确
+- [ ] 错误码覆盖常见异常场景
+- [ ] 错误处理策略已说明
+
+## 重试与熔断
+
+- [ ] 重试规则已定义（最大次数、间隔、退避策略）
+- [ ] 熔断配置已定义（阈值、时长、半开状态）
+- [ ] 重试场景已分类
+- [ ] 重试与熔断的边界已说明
+
+## 错误处理
+
+- [ ] 错误分类已定义（网络 / 认证 / 业务 / 系统）
+- [ ] 每类错误的处理策略已说明
+- [ ] 降级策略已定义
+- [ ] 降级触发条件已明确
+- [ ] 恢复策略已说明
+
+## 幂等性
+
+- [ ] 幂等键生成规则已定义
+- [ ] 幂等存储方案已说明
+- [ ] 幂等过期策略已定义
+- [ ] 幂等性边界已说明
+
+## 数据映射
+
+- [ ] 字段映射表完整
+- [ ] 类型转换规则已定义
+- [ ] 数据格式转换逻辑已说明
+- [ ] 枚举值映射已列出
+
+## 监控与告警
+
+- [ ] 关键监控指标已定义（成功率、响应时间、错误率）
+- [ ] 告警规则已定义
+- [ ] 告警级别和通知方式已说明
+- [ ] 监控阈值合理
+
+## 追溯性
+
+- [ ] 关联功能特性存在
+- [ ] 集成可追溯到业务需求
+- [ ] 版本变更可追溯
+- [ ] 关联设计文档存在
+
+## 实现一致性
+
+- [ ] 与实现代码一致
+- [ ] 文档与实际行为匹配
+- [ ] 测试覆盖核心场景
+- [ ] 性能满足要求

package/templates/extended/contracts/integration_contract/starter.md

@@ -0,0 +1,158 @@
+---
+id: {INT_ID}
+title: {集成名称}
+status: draft
+version: {v1}
+protocol: {协议类型}
+external_system: {外部系统名称}
+related_features: []
+---
+
+# {INT_ID}: {集成名称}
+
+<!-- 本模板是插件 starter 指导，项目本地模板可完全覆盖 -->
+<!-- 插件模板是入门指导，项目本地模板是权威 -->
+
+## 概述
+
+{描述这个集成的目的、业务场景和主要能力}
+
+## 基础信息
+
+- **版本**：{version}
+- **协议**：REST / SOAP / gRPC / Message Queue / WebSocket / FTP / SFTP
+- **外部系统**：{外部系统名称和版本}
+- **环境**：开发 / 测试 / 预生产 / 生产
+- **SLA**：{服务等级协议，如"99.9% 可用性"}
+
+## 连接配置
+
+### 端点信息
+
+| 环境 | URL / 地址 | 端口 | 说明 |
+|------|-----------|------|------|
+| 开发 | {url} | {port} | {说明} |
+| 测试 | {url} | {port} | {说明} |
+| 生产 | {url} | {port} | {说明} |
+
+### 认证方式
+
+- **类型**：Basic Auth / OAuth2 / API Key / mTLS / JWT
+- **凭证管理**：{凭证存储位置，如"Vault / 环境变量"}
+- **刷新策略**：{Token 刷新策略，如"过期前 5 分钟自动刷新"}
+
+### 超时配置
+
+| 阶段 | 超时时间 | 说明 |
+|------|---------|------|
+| 连接建立 | {timeout} | {说明} |
+| 读取响应 | {timeout} | {说明} |
+| 写入数据 | {timeout} | {说明} |
+
+## 接口列表
+
+### {接口名称}
+
+**描述**：{接口用途}
+
+**请求**：
+
+```json
+{
+  "field1": "type",
+  "field2": "type"
+}
+```
+
+**响应**：
+
+```json
+{
+  "success": true,
+  "data": {}
+}
+```
+
+**错误码**：
+
+| 错误码 | 描述 | 处理策略 |
+|--------|------|---------|
+| {error_code} | {描述} | {重试 / 告警 / 降级} |
+
+## 重试策略
+
+### 重试规则
+
+| 场景 | 最大重试次数 | 重试间隔 | 退避策略 | 说明 |
+|------|------------|---------|---------|------|
+| {场景名称} | {次数} | {间隔} | 固定 / 指数 / 退避 | {说明} |
+
+### 熔断配置
+
+- **失败阈值**：{连续失败次数触发熔断}
+- **熔断时长**：{熔断持续时间}
+- **半开状态**：{半开状态下的试探请求数}
+
+## 错误处理
+
+### 错误分类
+
+| 错误类型 | 示例 | 处理策略 |
+|---------|------|---------|
+| 网络错误 | 连接超时、DNS 解析失败 | 重试 + 告警 |
+| 认证错误 | Token 过期、凭证无效 | 刷新凭证 + 重试 |
+| 业务错误 | 数据校验失败、状态冲突 | 记录日志 + 人工介入 |
+| 系统错误 | 服务不可用、限流 | 重试 + 熔断 + 降级 |
+
+### 降级策略
+
+- **降级触发条件**：{如"外部系统不可用超过 5 分钟"}
+- **降级行为**：{如"返回缓存数据 / 返回默认值 / 拒绝请求"}
+- **恢复策略**：{如"自动探测恢复 / 人工确认恢复"}
+
+## 幂等性
+
+- **幂等键**：{幂等键的生成规则，如"请求ID + 业务ID"}
+- **幂等存储**：{幂等键的存储位置，如"Redis / 数据库"}
+- **幂等过期**：{幂等键的过期时间}
+
+## 数据映射
+
+### 字段映射
+
+| 内部字段 | 外部字段 | 类型转换 | 说明 |
+|---------|---------|---------|------|
+| {internal_field} | {external_field} | {转换规则} | {说明} |
+
+### 数据转换
+
+{描述数据格式转换逻辑，如"日期格式转换、枚举值映射等"}
+
+## 监控与告警
+
+### 监控指标
+
+| 指标名称 | 类型 | 阈值 | 说明 |
+|---------|------|------|------|
+| 调用成功率 | Gauge | 99% | {说明} |
+| 响应时间 | Histogram | P99 < 500ms | {说明} |
+| 错误率 | Counter | < 1% | {说明} |
+
+### 告警规则
+
+| 告警名称 | 条件 | 级别 | 通知方式 |
+|---------|------|------|---------|
+| {告警名称} | {条件} | P0 / P1 / P2 | {钉钉 / 邮件 / 短信} |
+
+## 关联制品
+
+- 功能特性：{related_features}
+- 设计文档：{related_designs}
+- 决策：{related_decisions}
+- 数据契约：{related_data_contracts}
+
+## 变更日志
+
+| 日期 | 版本 | 变更 | 作者 |
+|------|------|------|------|
+| {YYYY-MM-DD} | v1 | 初始版本 | {作者} |

package/templates/extended/contracts/ipc_contract/review-checklist.md

@@ -0,0 +1,78 @@
+# IPC Contract 审查清单
+
+<!-- 本清单是插件通用基线，项目本地审查规则可覆盖 -->
+
+## 结构完整性
+
+- [ ] `id` 字段存在且符合项目 ID 模式（如 `IPC-{nnn}`）
+- [ ] `title` 清晰描述 IPC 通道范围
+- [ ] `version` 字段存在且符合语义化版本
+- [ ] `status` 字段存在且为有效值
+
+## 消息定义
+
+- [ ] 请求消息结构完整
+- [ ] 响应消息结构完整
+- [ ] 事件消息定义清晰（如适用）
+- [ ] 消息类型定义使用 TypeScript 接口
+
+## 通道规范
+
+- [ ] 通道名称明确
+- [ ] 通信方向清晰（前端→后端/后端→前端/双向）
+- [ ] 请求和响应示例完整
+- [ ] 错误码覆盖常见异常场景
+
+## 序列化规范
+
+- [ ] 数据格式明确（JSON/MessagePack/Protobuf）
+- [ ] 类型映射表完整
+- [ ] 日期和数字精度有说明
+- [ ] 字符编码有说明
+
+## 边界规则
+
+- [ ] 前端职责范围明确
+- [ ] 后端职责范围明确
+- [ ] 禁止事项有明确说明
+- [ ] 前后端边界清晰无歧义
+
+## 错误处理
+
+- [ ] 错误码定义完整
+- [ ] 错误消息用户友好
+- [ ] 错误恢复方式明确
+- [ ] 不暴露内部实现细节
+
+## 性能要求
+
+- [ ] 延迟指标有明确目标
+- [ ] 大数据传输策略有说明
+- [ ] 并发限制有说明
+- [ ] 超时设置有说明
+
+## 安全性
+
+- [ ] 输入验证规则完整
+- [ ] 权限控制机制明确
+- [ ] 敏感信息处理有说明
+- [ ] 防攻击措施有说明
+
+## 版本兼容
+
+- [ ] 向后兼容规则明确
+- [ ] 破坏性变更有处理流程
+- [ ] 版本迁移有说明
+- [ ] 旧版本兼容期有定义
+
+## 追溯性
+
+- [ ] 关联功能特性存在
+- [ ] IPC 通道可追溯到业务需求
+- [ ] 与 UI 契约关联清晰
+
+## 实现一致性
+
+- [ ] 与实际实现代码一致
+- [ ] 文档与实际行为匹配
+- [ ] 类型定义与代码类型一致

package/templates/extended/contracts/ipc_contract/starter.md

@@ -0,0 +1,214 @@
+---
+id: {IPC_ID}
+title: {IPC 通道名称}
+status: draft
+version: {v1}
+related_features: []
+---
+
+# {IPC_ID}: {IPC 通道名称}
+
+<!-- 本模板是插件 starter 指导，项目本地模板可完全覆盖 -->
+<!-- 插件模板是入门指导，项目本地模板是权威 -->
+
+## 概述
+
+{描述这个 IPC 通道的用途、通信方向和主要能力}
+
+## 基础信息
+
+- **版本**：{version}
+- **通信方向**：Frontend → Backend / Backend → Frontend / 双向
+- **通道名称**：{channel_name}
+- **框架**：Tauri / Electron / 自定义
+
+## 消息定义
+
+### 请求消息
+
+```typescript
+interface {RequestName} {
+  // 请求标识
+  id: string;
+  // 请求类型
+  type: "{request_type}";
+  // 请求载荷
+  payload: {
+    field1: string;
+    field2: number;
+    field3?: boolean;  // 可选字段
+  };
+}
+```
+
+### 响应消息
+
+```typescript
+interface {ResponseName} {
+  // 对应请求 ID
+  requestId: string;
+  // 响应状态
+  status: "success" | "error";
+  // 成功时的数据
+  data?: {
+    result: string;
+    metadata?: Record<string, unknown>;
+  };
+  // 错误时的信息
+  error?: {
+    code: string;
+    message: string;
+    details?: unknown;
+  };
+}
+```
+
+### 事件消息（后端主动推送）
+
+```typescript
+interface {EventName} {
+  // 事件类型
+  type: "{event_type}";
+  // 事件载荷
+  payload: {
+    timestamp: number;
+    data: unknown;
+  };
+}
+```
+
+## 通道列表
+
+### {channel_name}
+
+**描述**：{通道描述}
+
+**方向**：{Frontend → Backend / Backend → Frontend / 双向}
+
+**请求示例**：
+
+```typescript
+// 前端发送
+invoke("{channel_name}", {
+  param1: "value",
+  param2: 123
+});
+
+// 后端响应
+{
+  requestId: "req_123",
+  status: "success",
+  data: { result: "processed" }
+}
+```
+
+**错误处理**：
+
+| 错误码 | 描述 | 前端处理 |
+|--------|------|---------|
+| INVALID_PARAM | 参数无效 | 提示用户修正输入 |
+| TIMEOUT | 请求超时 | 重试或提示稍后 |
+| PERMISSION_DENIED | 权限不足 | 提示用户授权 |
+| INTERNAL_ERROR | 内部错误 | 记录日志，提示联系支持 |
+
+## 序列化规范
+
+### 数据格式
+
+- **编码**：JSON / MessagePack / Protobuf
+- **字符编码**：UTF-8
+- **日期格式**：ISO 8601 或 Unix 时间戳
+- **数字精度**：整数 i64，浮点 f64
+
+### 类型映射
+
+| TypeScript | Rust/后端 | 说明 |
+|-----------|----------|------|
+| string | String | UTF-8 字符串 |
+| number | i64 / f64 | 整数或浮点 |
+| boolean | bool | 布尔值 |
+| Array<T> | Vec<T> | 数组 |
+| object | Struct | 对象 |
+| null | Option::None | 可选值 |
+
+## 边界规则
+
+### 前端职责
+
+- UI 状态管理
+- 用户输入验证
+- 错误展示
+- 加载状态
+
+### 后端职责
+
+- 业务逻辑处理
+- 数据持久化
+- 文件系统访问
+- 系统 API 调用
+- 安全验证
+
+### 禁止事项
+
+- ❌ 前端直接访问文件系统
+- ❌ 前端存储敏感信息（密码、Token 明文）
+- ❌ 后端直接操作 DOM
+- ❌ 绕过 IPC 通道的通信
+
+## 性能要求
+
+| 指标 | 目标值 | 说明 |
+|------|-------|------|
+| 单次调用延迟 | < {X} ms | 本地调用 |
+| 大数据传输 | 分片传输 | 超过 1MB 的数据 |
+| 并发调用 | 限制 {N} 个 | 防止资源耗尽 |
+| 超时时间 | {X} 秒 | 默认超时 |
+
+## 安全考虑
+
+### 输入验证
+
+- [ ] 所有输入参数在后端验证
+- [ ] 防止路径遍历攻击
+- [ ] 防止注入攻击
+- [ ] 限制输入长度和大小
+
+### 权限控制
+
+- [ ] 敏感操作需要权限确认
+- [ ] 最小权限原则
+- [ ] 权限检查在后端执行
+
+### 错误信息
+
+- [ ] 不暴露内部实现细节
+- [ ] 错误码和消息分离
+- [ ] 敏感信息不记录日志
+
+## 版本兼容
+
+### 向后兼容规则
+
+- 新增字段使用可选类型
+- 不删除已有字段
+- 不改变字段类型
+- 新增通道不影响已有通道
+
+### 破坏性变更处理
+
+- 版本号递增
+- 迁移指南文档
+- 旧版本兼容期
+- 客户端升级提示
+
+## 关联制品
+
+- 功能特性：{related_features}
+- 设计文档：{related_designs}
+- UI 契约：{related_ui_contracts}
+
+## 变更日志
+
+| 日期 | 版本 | 变更 | 作者 |
+|------|------|------|------|
+| {YYYY-MM-DD} | v1 | 初始版本 | {作者} |

package/templates/extended/contracts/report_contract/review-checklist.md

@@ -0,0 +1,61 @@
+# Report Contract 审查清单
+
+<!-- 本清单是插件通用基线，项目本地审查规则可覆盖 -->
+
+## 结构完整性
+
+- [ ] `id` 字段存在且符合项目 ID 模式（如 `RPT-{nnn}`）
+- [ ] `title` 清晰描述报告范围
+- [ ] `version` 字段存在且符合语义化版本
+- [ ] `status` 字段存在且为有效值
+- [ ] `output_format` 字段存在且为有效格式
+
+## 数据源质量
+
+- [ ] 所有数据源已列出
+- [ ] 数据源类型明确（数据库 / API / 文件）
+- [ ] 数据刷新频率已定义
+- [ ] 数据源可靠性已评估
+
+## 字段定义
+
+- [ ] 所有字段有清晰的中文/英文名称
+- [ ] 字段类型明确（string / number / date / boolean）
+- [ ] 聚合逻辑已定义（SUM / AVG / COUNT / MAX / MIN / NONE）
+- [ ] 字段含义有详细说明
+
+## 时间窗口
+
+- [ ] 报告周期已定义
+- [ ] 时间粒度已明确（小时 / 天 / 周 / 月）
+- [ ] 时区已指定
+- [ ] 截止规则已说明
+
+## 聚合逻辑
+
+- [ ] 关键指标计算规则完整
+- [ ] 过滤条件已列出
+- [ ] 排序规则已定义
+- [ ] 边界情况处理已说明（如空值、零值）
+
+## 性能与安全
+
+- [ ] 生成时间要求已定义
+- [ ] 数据量级已评估
+- [ ] 并发支持已说明
+- [ ] 数据权限已定义
+- [ ] 敏感字段已标记并说明脱敏方式
+
+## 追溯性
+
+- [ ] 关联功能特性存在
+- [ ] 报告可追溯到业务需求
+- [ ] 版本变更可追溯
+- [ ] 关联数据契约存在
+
+## 实现一致性
+
+- [ ] 报告输出与定义一致
+- [ ] 字段计算逻辑与实现匹配
+- [ ] 性能满足要求
+- [ ] 测试覆盖核心场景