# Day 3：语义本体 MVP TODO

本文件是周计划 Day 3 的具体执行细则。路线图见 `document/development/agent week plan/day_3_semantic_ontology_mvp.md`。

目标：建立用户问题的语义解析层，输出稳定的 8 个核心字段，让 User Agent、Hermes 和 Orchestrator 都能使用同一套语义结构。

参考文档：

- `document/development/agent plan/02_semantic_ontology.md`
- `document/development/agent plan/14_financial_document_canonical_model.md`
- `document/development/agent plan/06_data_contracts_and_governance.md`

## 0. 开始前检查

- [ ] 确认 Day 1 的 `SemanticParseLog` 可用。
- [ ] 确认 Day 1 的 `AgentRun` 可用。
- [ ] 确认 Day 2 的资产 API 可用。
- [ ] 找到后端服务层目录。
- [ ] 找到现有 LLM 调用或 Mock 调用方式。
- [ ] 确认当前是否允许真实调用 LLM。
- [ ] 如果不能调用真实 LLM，准备规则解析加 Mock 解析。

## 1. 定义 8 个核心字段

- [ ] 定义字段 `scenario`，表示业务场景。
- [ ] 定义字段 `intent`，表示用户意图。
- [ ] 定义字段 `entities`，表示业务对象。
- [ ] 定义字段 `time_range`，表示时间范围。
- [ ] 定义字段 `metrics`，表示指标或金额口径。
- [ ] 定义字段 `constraints`，表示过滤条件。
- [ ] 定义字段 `risk_flags`，表示风险信号。
- [ ] 定义字段 `permission`，表示动作权限。
- [ ] 为每个字段写清楚类型。
- [ ] 为每个字段写清楚是否必填。
- [ ] 为每个字段写清楚默认值。
- [ ] 为每个字段写清楚示例。

验收证据：

- [ ] 8 个字段在 Schema、服务层、日志中名字一致。

## 2. 设计字段枚举

- [ ] `scenario` 支持 `expense`。
- [ ] `scenario` 支持 `accounts_receivable`。
- [ ] `scenario` 支持 `accounts_payable`。
- [ ] `scenario` 支持 `knowledge`。
- [ ] `scenario` 支持 `unknown`。
- [ ] `intent` 支持 `query`。
- [ ] `intent` 支持 `explain`。
- [ ] `intent` 支持 `compare`。
- [ ] `intent` 支持 `risk_check`。
- [ ] `intent` 支持 `draft`。
- [ ] `intent` 支持 `operate`。
- [ ] `permission.level` 支持 `read`。
- [ ] `permission.level` 支持 `draft_write`。
- [ ] `permission.level` 支持 `approval_required`。
- [ ] `permission.level` 支持 `forbidden`。

验收证据：

- [ ] 未识别的问题不会抛异常，返回 `unknown`。

## 3. 建立 Schema

- [ ] 定义 `OntologyParseRequest`。
- [ ] `OntologyParseRequest` 包含 `query`。
- [ ] `OntologyParseRequest` 包含 `user_id`。
- [ ] `OntologyParseRequest` 包含 `context_json`。
- [ ] 定义 `OntologyParseResult`。
- [ ] `OntologyParseResult` 包含 8 个核心字段。
- [ ] `OntologyParseResult` 包含 `confidence`。
- [ ] `OntologyParseResult` 包含 `clarification_required`。
- [ ] `OntologyParseResult` 包含 `clarification_question`。
- [ ] `OntologyParseResult` 包含 `run_id`。
- [ ] 定义字段级错误结构。

验收证据：

- [ ] OpenAPI 中可以看到语义解析请求和响应。

## 4. 实现解析服务

- [ ] 新增 `SemanticOntologyService` 或同等服务。
- [ ] 实现 `parse(query, user_context)` 主函数。
- [ ] 先做关键词规则解析。
- [ ] 报销关键词映射到 `expense`。
- [ ] 应收、回款、客户欠款映射到 `accounts_receivable`。
- [ ] 应付、供应商、付款映射到 `accounts_payable`。
- [ ] 风险、异常、重复、超标映射到 `risk_check`。
- [ ] 为什么、依据、规则映射到 `explain`。
- [ ] 统计、汇总、多少映射到 `query`。
- [ ] 生成、创建、发起映射到 `draft` 或 `operate`。
- [ ] 无法识别时返回低置信度和澄清问题。

验收证据：

- [ ] “查一下本周报销超标风险”能识别为 expense + risk_check。
- [ ] “客户 A 这个月还有多少应收”能识别为 accounts_receivable + query。
- [ ] “供应商 B 明天要付多少钱”能识别为 accounts_payable + query。

## 5. 解析业务对象

- [ ] 从问题中提取员工姓名。
- [ ] 从问题中提取部门。
- [ ] 从问题中提取客户。
- [ ] 从问题中提取供应商。
- [ ] 从问题中提取项目。
- [ ] 从问题中提取单据号。
- [ ] 从问题中提取金额。
- [ ] 从问题中提取费用类型。
- [ ] 无法提取时返回空数组，不返回 null。

验收证据：

- [ ] “张三 4 月差旅报销”能提取员工、月份、费用类型。

## 6. 解析时间范围

- [ ] 支持今天。
- [ ] 支持昨天。
- [ ] 支持本周。
- [ ] 支持上周。
- [ ] 支持本月。
- [ ] 支持上月。
- [ ] 支持本季度。
- [ ] 支持今年。
- [ ] 支持明确日期。
- [ ] 支持日期区间。
- [ ] 解析结果包含 `start_date` 和 `end_date`。
- [ ] 日期使用 ISO 格式。

验收证据：

- [ ] “本周”能解析为当前周起止日期。
- [ ] “2026 年 4 月”能解析为 `2026-04-01` 到 `2026-04-30`。

## 7. 解析指标与约束

- [ ] 识别金额指标。
- [ ] 识别数量指标。
- [ ] 识别超标指标。
- [ ] 识别逾期指标。
- [ ] 识别重复报销指标。
- [ ] 识别部门过滤条件。
- [ ] 识别状态过滤条件。
- [ ] 识别金额阈值过滤条件。
- [ ] 识别排序要求。
- [ ] 识别 Top N 要求。

验收证据：

- [ ] “列出金额最高的 10 笔报销”能识别排序和 Top 10。

## 8. 解析风险与权限

- [ ] 重复报销映射到 `duplicate_expense`。
- [ ] 发票异常映射到 `invoice_anomaly`。
- [ ] 金额超标映射到 `amount_over_limit`。
- [ ] 逾期应收映射到 `ar_overdue`。
- [ ] 逾期应付映射到 `ap_overdue`。
- [ ] 查询类问题权限为 `read`。
- [ ] 生成草稿权限为 `draft_write`。
- [ ] 审批、上线、付款类动作权限为 `approval_required`。
- [ ] 越权动作权限为 `forbidden`。

验收证据：

- [ ] “帮我直接付款”不能被标为可直接执行。

## 9. API 接口

- [ ] 新增 `POST /api/ontology/parse`。
- [ ] 请求参数包含用户问题。
- [ ] 请求参数包含用户上下文。
- [ ] 响应包含 8 个字段。
- [ ] 响应包含 `run_id`。
- [ ] 响应包含置信度。
- [ ] 响应包含澄清问题。
- [ ] 每次调用写入 `SemanticParseLog`。
- [ ] 每次调用写入 `AgentRun` 或关联已有 `AgentRun`。

验收证据：

- [ ] 连续调用 5 次都能在日志中查到。

## 10. 前端调试入口

- [ ] 在合适页面增加语义解析调试入口。
- [ ] 输入框支持自然语言问题。
- [ ] 点击解析后调用 API。
- [ ] 展示 8 个字段。
- [ ] 展示 JSON 原始结果。
- [ ] 展示置信度。
- [ ] 展示澄清问题。
- [ ] 展示 `run_id`。
- [ ] 错误时展示错误信息。

验收证据：

- [ ] 产品和开发可以直接在页面验证解析结果。

## 11. 评测集

- [ ] 创建至少 5 条报销问题。
- [ ] 创建至少 5 条应收问题。
- [ ] 创建至少 5 条应付问题。
- [ ] 创建至少 3 条知识库问题。
- [ ] 创建至少 3 条越权操作问题。
- [ ] 为每条问题写期望 `scenario`。
- [ ] 为每条问题写期望 `intent`。
- [ ] 为每条问题写期望权限级别。
- [ ] 编写评测脚本或测试。

验收证据：

- [ ] 核心场景识别准确率达到当天设定阈值，例如 80%。

## 12. Day 3 验收

- [ ] 语义解析 API 可用。
- [ ] 8 个核心字段完整返回。
- [ ] 解析日志可查询。
- [ ] 低置信度问题有澄清问题。
- [ ] 越权动作不会被标为可执行。
- [ ] 前端调试入口可用。
- [ ] 评测集可运行。
- [ ] 所有完成项已用 `[x] ~~...~~` 标记。

## 阻塞记录

- [ ] 暂无。

## 日终交接

- [ ] 写明已支持的关键词。
- [ ] 写明识别不准的样例。
- [ ] 写明 Day 4 Orchestrator 可以直接复用的响应结构。
