# kn-logic-property-resolver 开发实施指南

> **说明**：本文档提供 kn-logic-property-resolver 的开发指南，包括项目结构、已完成工作、待实现任务清单等。

---

## 📁 项目文件结构

```
server/
├── interfaces/
│   ├── kn_logic_property_resolver.go     # 接口定义、请求/响应结构
│   ├── driven_agent.go                   # Agent 接口定义（已扩展）
│   └── driven_ontology_manager.go        # Ontology Manager 接口（已扩展）
├── driveradapters/
│   ├── knlogicpropertyresolver/
│   │   └── index.go                      # HTTP Handler 层
│   └── rest_private_handler.go           # 路由注册（已更新）
├── logics/
│   └── knlogicpropertyresolver/
│       └── index.go                      # 业务逻辑层（Service）
├── drivenadapters/
│   ├── agent_app.go                      # Agent 平台适配器（已扩展）
│   ├── ontology_manager.go               # Ontology Manager 适配器
│   └── ontology_query.go                 # Ontology Query 适配器
└── infra/
    └── config/
        └── config.go                     # 配置管理（已添加 Agent Key）
```

---

## 🎯 已完成的工作

### 1. 接口定义（interfaces 层）

已定义以下核心结构：

**请求结构**：
- `ResolveLogicPropertiesRequest`：请求参数（kn_id, ot_id, query, unique_identities, properties, additional_context, options）
- `ResolveOptions`：可选配置（return_debug, max_repair_rounds, max_concurrency）

**响应结构**：
- `ResolveLogicPropertiesResponse`：成功响应（datas, debug）
- `MissingParamsError`：缺参错误响应
- `MissingPropertyParams`：缺失的属性参数
- `MissingParam`：缺失的参数详情

**Service 接口**：
- `IKnLogicPropertyResolverService`：业务逻辑接口

**Agent 接口扩展**：
- `MetricDynamicParamsGeneratorAgent`：Metric 参数生成 Agent
- `OperatorDynamicParamsGeneratorAgent`：Operator 参数生成 Agent
- `MetricDynamicParamsGeneratorReq`：Metric Agent 请求结构
- `OperatorDynamicParamsGeneratorReq`：Operator Agent 请求结构

**Ontology Manager 接口扩展**：
- `LogicPropertyDef`：逻辑属性定义（已迁移并强类型化）
- `PropertyParameter`：属性参数定义
- `LogicPropertyType`：逻辑属性类型枚举（Metric/Operator）

### 2. HTTP Handler 层（driveradapters 层）

已实现：
- 参数绑定（Header + JSON Body）
- 参数校验（validator）
- 默认值设置（defaults）
- 统一错误处理（rest.ReplyError）
- 统一成功响应（rest.ReplyOK）

### 3. 业务逻辑层（logics 层）

已搭建主流程框架：

```go
ResolveLogicProperties() {
    1. 参数校验 ✅
    2. 获取对象类定义 ✅
    3. 提取逻辑属性定义 ✅
    4. 生成 dynamic_params ✅（使用 Agent 平台）
       ├── generateSinglePropertyParams ✅
       ├── generateMetricParams ✅（调用 Metric Agent）
       └── generateOperatorParams ✅（调用 Operator Agent）
    5. 参数校验 ✅（validateMetricParams 已实现）/ 🔲（validateOperatorParams TODO）
    6. 调用 ontology-query 查询 ✅（queryLogicProperties 已实现）
    7. 构建响应 ✅
}
```

### 4. Agent 平台集成（drivenadapters 层）

已实现：
- `MetricDynamicParamsGeneratorAgent`：调用 Metric Agent 生成参数
- `OperatorDynamicParamsGeneratorAgent`：调用 Operator Agent 生成参数
- Agent 输出解析逻辑（支持成功和缺参两种格式）
- 缺参信息解析（`parseMetricMissingParamsFromError`）

### 5. 配置管理

已添加 Agent Key 配置：
- `MetricDynamicParamsGeneratorKey`
- `OperatorDynamicParamsGeneratorKey`

### 6. 路由注册

已注册路由：
- `POST /api/kn/logic-property-resolver`（与 `/api/kn/semantic-search` 保持一致）

---

## 📝 待实现的 TODO

### Phase 1：基础数据流程（优先级 P0）

#### ✅ 1. extractLogicProperties() - 提取逻辑属性定义

**状态**：已实现

**位置**：`logics/knlogicpropertyresolver/index.go`

**功能**：
- 从 ObjectType 中提取 logic_properties
- 检查请求的 properties 是否都存在
- 返回 `map[propertyName]*LogicPropertyDef`

---

#### ✅ 2. queryLogicProperties() - 调用 ontology-query

**状态**：已实现

**位置**：`logics/knlogicpropertyresolver/index.go`

**功能**：
- 调用 ontology-query 的 properties 接口
- `POST /api/ontology-query/in/v1/knowledge-networks/{kn_id}/object-types/{ot_id}/properties`
- Body: `{ unique_identities, properties, dynamic_params }`

---

### Phase 2：参数校验（优先级 P0）

#### ✅ 3. validateMetricParams() - 校验 metric 参数

**状态**：已实现

**位置**：`logics/knlogicpropertyresolver/index.go`

**功能**：
- 检查 instant/start/end/step 是否存在
- step 枚举校验（day/week/month/quarter/year）
- instant=true 时，step 必须不存在
- instant=false 时，step 必须存在
- start/end 必须是毫秒时间戳（int64）

---

#### 🔲 4. validateOperatorParams() - 校验 operator 参数

**状态**：待实现

**位置**：`logics/knlogicpropertyresolver/index.go:467`

**任务**：
```go
// 校验 operator 类型的参数
// 1. 检查所有 value_from="input" 的参数是否都存在
// 2. 参数类型校验（基础类型/对象/数组）
// 3. 必填参数检查
```

**参考**：
- PRD: `prd/feature-799460/07-operator参数生成提示词设计.md`

---

### Phase 3：增强功能（优先级 P1）

#### 🔲 5. now_ms 解析和服务端兜底

**状态**：部分实现（服务端生成已实现，但未从 additional_context 中解析）

**位置**：`logics/knlogicpropertyresolver/index.go`

**当前实现**：
```go
// 在 generateMetricParams 中，直接使用当前时间
nowMs := time.Now().UnixMilli()
```

**待优化**：
- 优先从 `additional_context` 中解析 `now_ms`（如果有的话）
- 如果没有，再使用当前时间作为兜底

---

#### 🔲 6. trace_id 获取

**状态**：待实现

**位置**：`logics/knlogicpropertyresolver/index.go`

**任务**：
```go
// 从 context 中获取 trace_id（由 middleware 设置）
func getTraceID(ctx context.Context) string {
    if traceID, ok := ctx.Value("trace_id").(string); ok {
        return traceID
    }
    return uuid.New().String()  // 如果没有，生成一个新的
}
```

---

#### ~~🔲 7. object_instances 获取~~（已移除）

**状态**：已移除

**说明**：
- `object_instances` 不再作为独立参数传递
- 对象实例信息统一通过 `additional_context` 传递给 Agent
- 这样简化了接口设计，由调用方在 `additional_context` 中组织所需的上下文信息

---

#### 🔲 8. 完善错误处理

**状态**：待实现

**位置**：`logics/knlogicpropertyresolver/index.go`

**任务**：
- 实现其他错误码（参考 `prd/feature-799460/06-错误码清单与处理策略.md`）
- 完善错误信息的结构化返回

---

## 🧪 测试建议

### 1. 单元测试

创建测试文件：
- `server/logics/knlogicpropertyresolver/index_test.go`
- `server/driveradapters/knlogicpropertyresolver/index_test.go`
- `server/drivenadapters/agent_app_test.go`

测试内容：
- `TestExtractLogicProperties`：测试逻辑属性提取
- `TestGenerateSinglePropertyParams`：测试单个属性参数生成
- `TestGenerateDynamicParams`：测试并发参数生成
- `TestValidateMetricParams`：测试 metric 参数校验
- `TestValidateOperatorParams`：测试 operator 参数校验
- `TestParseAgentOutput`：测试 Agent 输出解析

### 2. 集成测试

测试完整流程：
1. Mock ontology-manager 响应（对象类定义）
2. Mock Agent 响应（dynamic_params）
3. Mock ontology-query 响应（逻辑属性值）
4. 验证最终响应结构

### 3. E2E 测试

使用真实服务测试：
- 部署 Metric Agent 和 Operator Agent
- 配置真实的 Agent Key
- 验证完整的参数生成和查询流程
- 验证缺参错误返回

---

## 📚 相关文档

### PRD 文档

- **需求澄清**：`prd/feature-799460/08-需求澄清结果汇总.md`
- **方案设计**：`prd/feature-799460/03-方案设计.md`
- **实现架构**：`prd/feature-799460/09-实现架构设计.md`
- **Metric 提示词**：`prd/feature-799460/04-metric参数生成提示词设计.md`
- **Operator 提示词**：`prd/feature-799460/07-operator参数生成提示词设计.md`
- **并发策略**：`prd/feature-799460/05-并发策略与超时配置.md`
- **错误码清单**：`prd/feature-799460/06-错误码清单与处理策略.md`
- **OpenAPI 定义**：`prd/feature-799460/kn-logic-property-resolver.openapi.yaml`

### 依赖接口文档

- **Ontology Manager**：`prd/feature-799460/99-依赖接口/ontology-manager-object-type.json`
- **Ontology Query**：`prd/feature-799460/99-依赖接口/ontology_query_object_proteries.yaml`

---

## 🚀 快速开始

### 编译

```bash
cd /root/codes/agent-retrieval
go build -o bin/agent-retrieval ./server
```

### 配置

在 `config.yaml` 中添加 Agent Key：

```yaml
deploy_agent:
  concept_intention_analysis_agent_key: "xxx"
  concept_retrieval_strategist_agent_key: "xxx"
  metric_dynamic_params_generator_key: "你已开发的metric_agent_key"
  operator_dynamic_params_generator_key: "待开发的operator_agent_key"
```

### 运行

```bash
./bin/agent-retrieval
```

### 测试接口

```bash
curl -X POST http://localhost:8080/api/kn/logic-property-resolver \
  -H "Content-Type: application/json" \
  -H "x-account-id: test_account" \
  -H "x-account-type: user" \
  -H "x-kn-id: kn_medical" \
  -d '{
    "kn_id": "kn_medical",
    "ot_id": "company",
    "query": "注册资金大于100万人民币的企业有哪些？想知道这些药企的药品上市情况，并且这些企业的健康度怎么样？",
    "unique_identities": [{"company_id": "company_000001"}],
    "properties": ["approved_drug_count", "business_health_score"],
    "additional_context": "company_id=company_000001，registered_capital=2000000；registered_capital > 1000000；now_ms=1762996342241",
    "options": {
      "return_debug": true,
      "max_concurrency": 4
    }
  }'
```

---

## ✅ 开发进度清单

### 基础架构

- [x] 接口定义（interfaces 层）
- [x] HTTP Handler 层（driveradapters 层）
- [x] 业务逻辑层框架（logics 层）
- [x] 路由注册
- [x] 编译通过

### Agent 集成

- [x] Agent 接口定义
- [x] Agent 配置管理
- [x] Metric Agent 调用实现
- [x] Operator Agent 调用实现
- [x] Agent 输出解析（成功/缺参）

### 核心功能

- [x] 获取对象类定义
- [x] 提取逻辑属性定义
- [x] 并发参数生成架构
- [x] Metric 参数校验
- [ ] Operator 参数校验（TODO）
- [x] Ontology Query 调用
- [x] 缺参错误处理

### 增强功能

- [x] now_ms 服务端生成（基础实现）
- [ ] now_ms 从 additional_context 解析
- [ ] trace_id 获取
- [x] ~~object_instances 获取~~（已移除，改用 AdditionalContext 传递）
- [ ] 完整错误码支持

### 测试

- [ ] 单元测试
- [ ] 集成测试
- [ ] E2E 测试

---

## 🔄 开发迭代建议

### 第一轮：完成基础流程（P0）

1. ~~实现 `validateMetricParams()`~~ ✅ 已完成
2. 实现 `validateOperatorParams()` 🔲 TODO
3. ~~实现 `queryLogicProperties()`~~ ✅ 已完成
4. 端到端测试（使用已开发的 Metric Agent）

### 第二轮：增强功能（P1）

1. 优化 `now_ms` 解析逻辑
2. 实现 `trace_id` 获取
3. ~~实现 `object_instances` 获取~~ ✅ 已移除（改用 AdditionalContext）
4. 完善错误处理

### 第三轮：测试和优化（P2）

1. 补充单元测试
2. 性能测试和优化
3. 文档完善

---

**当前状态**：✅ 基础流程已打通（Metric 参数校验 + Ontology Query 调用已完成）

**下一步**：实现 Operator 参数校验（validateOperatorParams），完善增强功能

