IDD意图驱动开发之构块规格说明书

📦 文档定位

本文档是《系统规格说明书》中定义的单个构块 的完整技术规格。它是人类工程师与AI生成引擎之间的终极开发契约，所有实现代码、测试、配置均应严格源自本文档。

📄 Markdown 模板

markdown 复制代码

## BLOCK-[ID]: [构块名称] 规格说明书

### 1. 元信息
| 项目 | 内容 |
| :--- | :--- |
| **构块ID** | `BLOCK-PAY-001` （全局唯一） |
| **构块名称** | 智能支付路由 |
| **构块类型** | 🏗️ 标准构块 / 🤖 **智能体构块** （二选一） |
| **所属子系统** | `SUBSYSTEM-TRANSACTION-CORE` （交易核心） |
| **来源依据** | 依据《系统规格说明书》第3章 - `BLOCK-PAY-001` 行 |
| **负责人** | @张三 |
| **状态** | **草案** | 评审中 | 已基线 | 已实现 |

### 2. 功能概要
**一句话价值**：
> 作为支付系统的智能决策中枢，通过实时分析支付通道的健康度、成本与成功率，为每一笔交易选择最优路径，以最大化支付成功率和成本效益。

### 3. 接口契约
#### 3.1 输入接口
**主触发端点**：
```yaml
协议: HTTP POST
路径: /v1/payment/intelligent-routing
请求头:
  - Authorization: Bearer <用户令牌>
  - X-Request-ID: string # 用于全链路追踪
请求体 (application/json):
  orderId: string # 订单号
  amount: number # 支付金额（元）
  currency: string # 币种，默认CNY
  userId: string # 用户ID

异步回调接收：

yaml 复制代码

协议: Webhook (POST)
路径: /internal/webhook/channel-callback
安全: 基于IP白名单及签名验证

3.2 输出与响应

同步响应：

yaml 复制代码

成功 (200 OK):
  {
    "transactionId": "txn_20250320123456",
    "selectedChannel": "channel_alipay_pro",
    "status": "PROCESSING",
    "nextAction": {
      "type": "REDIRECT",
      "url": "https://gateway.alipay.com/redirect/..."
    }
  }
业务错误 (400 Bad Request):
  {
    "code": "INSUFFICIENT_BALANCE",
    "message": "用户账户余额不足"
  }

4. 数据模型

4.1 核心领域实体

yaml 复制代码

PaymentRoutingDecision:
  - transactionId: string (PK)
  - orderId: string
  - userId: string
  - amount: number
  - selectedChannel: string
  - candidateScores: map<string, number> # 通道及其评分
  - decisionReason: string # AI决策依据摘要
  - status: enum[PROCESSING, SUCCESS, FAILED]
  - createdAt: timestamp

4.2 数据持久化要求

存储：所有路由决策记录必须持久化至 payment_routing_decisions 表，保留 180天 以供审计与分析。
性能：该表的 orderId、userId 字段需建立索引，以满足按订单或用户查询的需求。

5. 业务规则与逻辑

5.1 通道选择算法

python 复制代码

### 伪代码逻辑描述
def select_channel(available_channels, historical_data, current_risk):
    for channel in available_channels:
        # 规则1: 基础健康度过滤
        if channel.health_score < 0.95:
            continue
        # 规则2: 成本与成功率的综合评分 (核心公式)
        score = channel.success_rate * 0.7 + (1 - channel.fee_ratio) * 0.3
        # 规则3: 高风险交易强制路由至高安全通道
        if current_risk == 'HIGH' and channel.security_level < 'HIGH':
            continue
    return max_score_channel

5.2 异常处理规则

规则R001 ：若所有主要通道均不可用，则启用降级备用通道 channel_fallback，并发出 P2级告警。
规则R002 ：单笔交易路由决策时间超过 500ms，则自动取消，返回"系统繁忙"，防止阻塞。

6. 智能体定义 (仅当类型为🤖智能体构块时填写)

6.1 智能体目标

角色扮演：

你是一个专业的支付风控与效率专家。你的核心目标是：在保证支付安全（资损率<0.001%）的前提下，为每笔交易选择成功率最高、成本最低的支付通道。

6.2 工作流与规划

对于每个支付请求，你必须按序执行以下步骤：

感知：调用 get_channel_health_tool() 获取所有可用通道的实时状态（成功率、延迟、费率）。
推理：基于 业务规则5.1 计算评分，并结合风控系统提供的 get_risk_level_tool(userId, amount) 结果。
决策：选择最高分通道。如果出现平局，选择 成本更低 的通道。
执行：调用 execute_payment_tool(channel, requestData) 执行支付。
学习：将本次决策的结果（成功/失败）及上下文记录至学习日志，供后续模型优化。

6.3 授权工具集

工具名	调用方式	用途	输出示例
`get_channel_health_tool`	gRPC: `ChannelHealthService/GetRealTimeStats`	获取通道实时指标	`{channel_alipay: {success_rate:0.998, fee:0.006}}`
`execute_payment_tool`	HTTP POST: `内部支付网关`	向指定通道发送支付指令	`{status: "SUCCESS", externalId:"..."}`

7. 非功能性需求

需求类型	具体指标	验收方式
性能	P95延迟 < 150ms （从接受到返回决策）	压力测试
可用性	服务可用性 >= 99.99%	监控系统
弹性	依赖的任一通道服务挂掉，不应导致本构块完全不可用。	混沌工程测试
安全	所有决策日志需脱敏（掩码用户ID、订单号）。	代码审计

8. 验收条件

8.1 功能验收场景

gherkin 复制代码

场景: 正常交易智能路由成功
  假如 通道"Alipay_Pro"的健康度为0.99，费率为0.006；通道"WeChat_Fast"的健康度为0.98，费率为0.005
  当 收到一笔金额为100元、风险等级为LOW的支付请求
  那么 应选择通道"WeChat_Fast"
  而且 返回的响应中应包含 `transactionId` 和 `status: PROCESSING`

8.2 集成验收点

能在 SUBSYSTEM-TRANSACTION-CORE 的部署环境中成功部署。
能与 BLOCK-ORD-002（订单状态机）通过定义的事件格式正常通信。

文档签署：

架构师确认：___________ 日期：___
开发负责人确认：___________ 日期：___

🎯 模板核心设计思想与使用指南

1. 模块化设计：每个章节解决一个独立关切点

元信息：管理与追溯。
功能概要：统一认知，防止偏差。
接口契约：定义系统边界，是集成基础。
数据模型：定义信息核心，是业务逻辑的载体。
业务规则：是构块的"大脑"，尤其对于智能体。
非功能性需求：定义质量底线。
验收条件：定义完成的客观标准。

2. 为AI生成优化的关键字段

结构化数据 ：大量使用 YAML 和 表格，机器极易解析。
伪代码描述：在"业务规则"部分，用伪代码描述逻辑，AI能更好地理解并转化为真实代码。
明确的工具调用 ：对于智能体，授权工具集 部分直接对应LangChain等框架的Tool定义，可一键生成。
可执行的验收条件：Gherkin格式的验收场景可直接转化为自动化测试用例。

3. 工作流建议

创建：架构师或负责工程师，根据《系统规格说明书》的分解，复制此模板 创建 BLOCK-XXX.md。
编写与澄清：在编写过程中，遇到模糊点应立即与产品负责人或相关构块负责人澄清，并更新文档。
AI生成 ：将完成的 BLOCK-XXX.md 输入AI，使用指令： "请根据这份详细的构块规格说明书，生成一个完整的、生产就绪的 [Go/Java/Python] 微服务代码仓库。请特别注意第6章'智能体定义'和第5章'业务规则'，确保它们被准确实现。代码应包含完整的错误处理、日志、指标和单元测试。"
人工评审与迭代 ：重点评审AI生成的业务规则和智能体工作流实现 。如果发现偏差，应回头修改规格说明书 ，然后让AI重新生成或局部修正。切勿直接大规模修改AI生成的代码，那会失去可持续性。

此模板将《系统规格说明书》中的一行抽象定义，扩展为一份独立、自包含、可执行的开发任务书 。它是实现 "规格驱动开发" ，将人类高层意图无损转化为高质量代码的关键枢纽。