feat: deliver agent foundation day 1

document/development/agent week plan/day_1_foundation_models.md

@@ -1,316 +1,74 @@
-# Day 1：基础模型与工程骨架 TODO
+# Day 1：基础模型与工程骨架
 
-目标：建立后续 6 天开发所需的后端地基。Day 1 不做复杂业务逻辑，只做稳定模型、API 骨架、种子数据、基础审计和可运行验证。
+## 当前状态
 
-参考文档：
+- [x] ~~Day 1 已完成（2026-05-11）。~~
+- [x] ~~后端基础模型、API 骨架、种子数据、审计能力和 Day 2 联调入口均已落地。~~
 
-- `document/development/agent plan/01_overall_architecture.md`
-- `document/development/agent plan/02_semantic_ontology.md`
-- `document/development/agent plan/06_data_contracts_and_governance.md`
-- `document/development/agent plan/07_capability_registry.md`
-- `document/development/agent plan/08_permission_confirmation.md`
-- `document/development/agent plan/09_observability_and_trace.md`
+## 今天的大开发点
 
-## 0. 开始前检查
+Day 1 只做地基，不做复杂 Agent 智能。
 
-- [ ] 确认当前分支和工作区状态。
-- [ ] 确认后端目录位置，例如 `/app/server`。
-- [ ] 确认前端目录位置，例如 `/app/web`。
-- [ ] 确认后端使用的框架、ORM、迁移方式。
-- [ ] 找到现有数据库模型目录。
-- [ ] 找到现有 API 路由目录。
-- [ ] 找到现有启动入口。
-- [ ] 找到现有测试目录。
-- [ ] 找到现有种子数据或初始化脚本。
-- [ ] 记录不应修改的无关文件。
+核心是把后面 6 天都会用到的基础对象建出来：资产、版本、审核、运行日志、工具调用日志、语义解析日志、审计日志，以及最小财务业务数据来源。
 
-## 1. 统一命名和边界
+## 为什么第一天做这个
 
-- [ ] 确认统一模块名使用 `agent_assets`。
-- [ ] 确认资产类型枚举为 `rule`、`skill`、`mcp`、`task`。
-- [ ] 确认资产状态枚举为 `draft`、`review`、`active`、`disabled`。
-- [ ] 确认审核状态枚举为 `pending`、`approved`、`rejected`。
-- [ ] 确认 Agent 枚举为 `orchestrator`、`user_agent`、`hermes`。
-- [ ] 确认运行来源枚举为 `user_message`、`schedule`、`system_event`。
-- [ ] 确认权限级别枚举为 `read`、`draft_write`、`approval_required`、`forbidden`。
-- [ ] 确认所有主键、外键、时间字段命名符合现有代码风格。
+如果没有稳定的数据模型，后面的任务规则中心、语义本体、Orchestrator、User Agent、Hermes 都会各自临时造结构，后期会很难合并。
 
-验收证据：
+## 今天主要交付
 
-- [ ] 枚举命名在模型、Schema、服务层保持一致。
-- [ ] 没有同时出现 `schedule` 和 `task` 两套用户可见命名。
+- [x] ~~统一资产模型：规则、技能、MCP、任务。~~
+- [x] ~~版本模型：规则 Markdown 和其他资产配置快照。~~
+- [x] ~~审核模型：未审核不能上线。~~
+- [x] ~~Agent 运行日志：所有 Agent 执行都有 `run_id`。~~
+- [x] ~~工具调用日志：MCP、数据库、LLM、OCR、规则引擎调用都可追踪。~~
+- [x] ~~语义解析日志：后续语义本体结果可回放。~~
+- [x] ~~审计日志：所有写操作可追责。~~
+- [x] ~~最小财务业务数据来源：报销、应收、应付。~~
 
-## 2. 建立 AgentAsset 模型
+## 实际落地结果
 
-- [ ] 新增或扩展模型文件，定义 `AgentAsset`。
-- [ ] 增加字段 `id`。
-- [ ] 增加字段 `asset_type`，取值 `rule | skill | mcp | task`。
-- [ ] 增加字段 `code`，作为业务编码。
-- [ ] 增加字段 `name`。
-- [ ] 增加字段 `description`。
-- [ ] 增加字段 `domain`，例如 `expense | ar | ap | knowledge | system`。
-- [ ] 增加字段 `scenario_json`，保存适用场景。
-- [ ] 增加字段 `owner`。
-- [ ] 增加字段 `reviewer`。
-- [ ] 增加字段 `status`。
-- [ ] 增加字段 `current_version`。
-- [ ] 增加字段 `config_json`。
-- [ ] 增加字段 `created_at`。
-- [ ] 增加字段 `updated_at`。
-- [ ] 给 `code` 增加唯一约束。
-- [ ] 给 `asset_type` 增加索引。
-- [ ] 给 `status` 增加索引。
-- [ ] 给 `domain` 增加索引。
+- [x] ~~新增 `AgentAsset`、`AgentAssetVersion`、`AgentAssetReview`、`AgentRun`、`AgentToolCall`、`SemanticParseLog`、`AuditLog`、`ExpenseClaim`、`ExpenseClaimItem`、`AccountsReceivableRecord`、`AccountsPayableRecord`。~~
+- [x] ~~新增 `/api/v1/agent-assets`、`/api/v1/agent-runs`、`/api/v1/audit-logs` 相关接口。~~
+- [x] ~~种子数据已覆盖 3 条规则、2 条技能、2 条 MCP、3 条任务，以及报销 / 应收 / 应付示例数据。~~
+- [x] ~~旧开发库启动时会自动补齐新增资产和版本，不需要手动清库。~~
 
-验收证据：
+## 对应执行细则
 
-- [ ] 能创建一条规则资产。
-- [ ] 能创建一条技能资产。
-- [ ] 能创建一条 MCP 资产。
-- [ ] 能创建一条任务资产。
+- [Day 1 执行细则](<../agent plan/weekly_execution_details/day_1_foundation_models.md>)
 
-## 3. 建立 AgentAssetVersion 模型
+相关架构文档：
 
-- [ ] 定义 `AgentAssetVersion`。
-- [ ] 增加字段 `id`。
-- [ ] 增加字段 `asset_id`。
-- [ ] 增加字段 `version`，例如 `v1.0.0`。
-- [ ] 增加字段 `content`。
-- [ ] 增加字段 `content_type`，取值 `markdown | json`。
-- [ ] 增加字段 `change_note`。
-- [ ] 增加字段 `created_by`。
-- [ ] 增加字段 `created_at`。
-- [ ] 增加 `asset_id + version` 唯一约束。
-- [ ] 建立 `AgentAsset` 到 `AgentAssetVersion` 的关系。
-- [ ] 约定规则资产的 `content` 保存 Markdown。
-- [ ] 约定技能、MCP、任务资产的 `content` 保存 JSON 快照。
+- [整体架构](<../agent plan/01_overall_architecture.md>)
+- [语义本体](<../agent plan/02_semantic_ontology.md>)
+- [数据契约与治理](<../agent plan/06_data_contracts_and_governance.md>)
+- [能力注册](<../agent plan/07_capability_registry.md>)
+- [权限与确认](<../agent plan/08_permission_confirmation.md>)
+- [观测与 Trace](<../agent plan/09_observability_and_trace.md>)
+- [财务单据标准模型](<../agent plan/14_financial_document_canonical_model.md>)
 
-验收证据：
+## 当天验收门槛
 
-- [ ] 同一个资产不能重复创建同一个版本号。
-- [ ] 资产详情能拿到最近 5 个版本。
+- [x] ~~数据库或等价存储能创建基础对象。~~
+- [x] ~~API 服务能启动。~~
+- [x] ~~资产列表能返回规则、技能、MCP、任务。~~
+- [x] ~~规则资产能关联 Markdown 当前版本。~~
+- [x] ~~未审核规则不能上线。~~
+- [x] ~~AgentRun 能保存一条运行记录。~~
+- [x] ~~AuditLog 能保存一条写操作记录。~~
 
-## 4. 建立 AgentAssetReview 模型
+## Day 2 联调入口
 
-- [ ] 定义 `AgentAssetReview`。
-- [ ] 增加字段 `id`。
-- [ ] 增加字段 `asset_id`。
-- [ ] 增加字段 `version`。
-- [ ] 增加字段 `reviewer`。
-- [ ] 增加字段 `review_status`。
-- [ ] 增加字段 `review_note`。
-- [ ] 增加字段 `reviewed_at`。
-- [ ] 增加字段 `created_at`。
-- [ ] 建立资产、版本、审核之间的查询关系。
-- [ ] 增加服务层校验：没有 `approved` 审核时不能把规则置为 `active`。
+- `GET /api/v1/agent-assets`
+- `GET /api/v1/agent-assets/{asset_id}`
+- `GET /api/v1/agent-assets/{asset_id}/versions?limit=5`
+- `POST /api/v1/agent-assets/{asset_id}/reviews`
+- `POST /api/v1/agent-assets/{asset_id}/activate`
+- `GET /api/v1/audit-logs`
 
-验收证据：
+## 今天不做
 
-- [ ] `pending` 规则上线会被拒绝。
-- [ ] `rejected` 规则上线会被拒绝。
-- [ ] `approved` 规则可以上线。
-
-## 5. 建立 AgentRun 模型
-
-- [ ] 定义 `AgentRun`。
-- [ ] 增加字段 `id`。
-- [ ] 增加字段 `run_id`。
-- [ ] 增加字段 `agent`。
-- [ ] 增加字段 `source`。
-- [ ] 增加字段 `user_id`。
-- [ ] 增加字段 `task_id`。
-- [ ] 增加字段 `ontology_json`。
-- [ ] 增加字段 `route_json`。
-- [ ] 增加字段 `permission_level`。
-- [ ] 增加字段 `status`，取值 `running | succeeded | failed | blocked`。
-- [ ] 增加字段 `result_summary`。
-- [ ] 增加字段 `error_message`。
-- [ ] 增加字段 `started_at`。
-- [ ] 增加字段 `finished_at`。
-- [ ] 给 `run_id` 增加唯一约束。
-- [ ] 给 `agent`、`status`、`started_at` 增加索引。
-
-验收证据：
-
-- [ ] 创建任意 Agent 执行记录时必须生成 `run_id`。
-- [ ] 失败执行能保存错误信息。
-
-## 6. 建立 AgentToolCall 模型
-
-- [ ] 定义 `AgentToolCall`。
-- [ ] 增加字段 `id`。
-- [ ] 增加字段 `run_id`。
-- [ ] 增加字段 `tool_type`，例如 `mcp | database | llm | ocr | rule_engine`。
-- [ ] 增加字段 `tool_name`。
-- [ ] 增加字段 `request_json`。
-- [ ] 增加字段 `response_json`。
-- [ ] 增加字段 `status`。
-- [ ] 增加字段 `duration_ms`。
-- [ ] 增加字段 `error_message`。
-- [ ] 增加字段 `created_at`。
-- [ ] 建立 `AgentRun` 到 `AgentToolCall` 的关系。
-
-验收证据：
-
-- [ ] 一个 `run_id` 下可以记录多个工具调用。
-- [ ] 工具调用失败时不影响主运行日志保存。
-
-## 7. 建立 SemanticParseLog 模型
-
-- [ ] 定义 `SemanticParseLog`。
-- [ ] 增加字段 `id`。
-- [ ] 增加字段 `run_id`。
-- [ ] 增加字段 `user_id`。
-- [ ] 增加字段 `raw_query`。
-- [ ] 增加字段 `scenario`。
-- [ ] 增加字段 `intent`。
-- [ ] 增加字段 `entities_json`。
-- [ ] 增加字段 `time_range_json`。
-- [ ] 增加字段 `metrics_json`。
-- [ ] 增加字段 `constraints_json`。
-- [ ] 增加字段 `risk_flags_json`。
-- [ ] 增加字段 `permission_json`。
-- [ ] 增加字段 `confidence`。
-- [ ] 增加字段 `created_at`。
-
-验收证据：
-
-- [ ] 能保存一条完整 8 字段语义解析日志。
-- [ ] 能按 `run_id` 查询语义解析结果。
-
-## 8. 建立 AuditLog 模型
-
-- [ ] 定义 `AuditLog`。
-- [ ] 增加字段 `id`。
-- [ ] 增加字段 `actor`。
-- [ ] 增加字段 `action`。
-- [ ] 增加字段 `resource_type`。
-- [ ] 增加字段 `resource_id`。
-- [ ] 增加字段 `before_json`。
-- [ ] 增加字段 `after_json`。
-- [ ] 增加字段 `request_id`。
-- [ ] 增加字段 `created_at`。
-- [ ] 为规则保存、审核、上线、任务执行创建审计记录接口。
-
-验收证据：
-
-- [ ] 保存规则 Markdown 时有审计日志。
-- [ ] 审核规则时有审计日志。
-- [ ] 修改任务状态时有审计日志。
-
-## 9. 建立 Schema / DTO
-
-- [ ] 定义 `AgentAssetCreate`。
-- [ ] 定义 `AgentAssetUpdate`。
-- [ ] 定义 `AgentAssetRead`。
-- [ ] 定义 `AgentAssetListItem`。
-- [ ] 定义 `AgentAssetVersionRead`。
-- [ ] 定义 `AgentAssetReviewRead`。
-- [ ] 定义 `RuleMarkdownUpdate`。
-- [ ] 定义 `AgentRunRead`。
-- [ ] 定义 `AgentToolCallRead`。
-- [ ] 定义 `SemanticParseRead`。
-- [ ] 所有 JSON 字段在 DTO 中保持结构化，不返回字符串化 JSON。
-
-验收证据：
-
-- [ ] OpenAPI 文档能展示新增 Schema。
-- [ ] 列表 DTO 不返回大块 Markdown 内容。
-- [ ] 详情 DTO 返回当前版本内容。
-
-## 10. 建立 API 骨架
-
-- [ ] 新增 `GET /api/agent-assets`。
-- [ ] 新增 `GET /api/agent-assets/{asset_id}`。
-- [ ] 新增 `POST /api/agent-assets`。
-- [ ] 新增 `PATCH /api/agent-assets/{asset_id}`。
-- [ ] 新增 `GET /api/agent-assets/{asset_id}/versions`。
-- [ ] 新增 `POST /api/agent-assets/{asset_id}/versions`。
-- [ ] 新增 `POST /api/agent-assets/{asset_id}/reviews`。
-- [ ] 新增 `POST /api/agent-assets/{asset_id}/activate`。
-- [ ] 新增 `GET /api/agent-runs`。
-- [ ] 新增 `GET /api/agent-runs/{run_id}`。
-- [ ] 新增 `GET /api/audit-logs`。
-- [ ] 所有接口先返回真实数据库结果，不使用前端硬编码数据作为最终结果。
-
-验收证据：
-
-- [ ] 能调用资产列表接口。
-- [ ] 能调用资产详情接口。
-- [ ] 能调用版本接口。
-- [ ] 能调用运行日志接口。
-
-## 11. 建立服务层
-
-- [ ] 新增资产查询服务。
-- [ ] 新增资产保存服务。
-- [ ] 新增版本创建服务。
-- [ ] 新增审核服务。
-- [ ] 新增上线校验服务。
-- [ ] 新增 Agent Run 创建服务。
-- [ ] 新增 Tool Call 记录服务。
-- [ ] 新增审计日志服务。
-- [ ] 所有服务函数返回明确错误，不直接把数据库异常暴露给前端。
-
-验收证据：
-
-- [ ] API 路由中不堆业务判断。
-- [ ] 上线校验逻辑在服务层。
-- [ ] 审计日志通过统一服务写入。
-
-## 12. 建立种子数据
-
-- [ ] 创建至少 3 条规则资产。
-- [ ] 每条规则资产至少有 2 个版本。
-- [ ] 至少 1 条规则为 `active`。
-- [ ] 至少 1 条规则为 `review`。
-- [ ] 至少 1 条规则为 `draft`。
-- [ ] 创建至少 2 条技能资产。
-- [ ] 创建至少 2 条 MCP 资产。
-- [ ] 创建至少 3 条任务资产。
-- [ ] 为 active 规则创建 approved 审核记录。
-- [ ] 为 review 规则创建 pending 审核记录。
-
-验收证据：
-
-- [ ] 资产列表按类型筛选时四类都有数据。
-- [ ] 规则详情能看到版本和审核者。
-
-## 13. 最小测试
-
-- [ ] 编写资产模型创建测试。
-- [ ] 编写版本唯一约束测试。
-- [ ] 编写未审核不能上线测试。
-- [ ] 编写资产列表接口测试。
-- [ ] 编写资产详情接口测试。
-- [ ] 编写 AgentRun 创建测试。
-- [ ] 编写 AuditLog 写入测试。
-
-验收证据：
-
-- [ ] 后端核心测试通过。
-- [ ] 测试失败时能定位到具体服务。
-
-## 14. Day 1 验收
-
-- [ ] 数据库能创建所有新增表或等价结构。
-- [ ] API 服务能启动。
-- [ ] OpenAPI 能看到新增接口。
-- [ ] 资产列表接口返回规则、技能、MCP、任务。
-- [ ] 规则资产有 Markdown 当前版本。
-- [ ] 规则资产有最近版本列表。
-- [ ] 未审核规则不能上线。
-- [ ] AgentRun 能保存一条运行记录。
-- [ ] AuditLog 能保存一条写操作记录。
-- [ ] 所有完成项已用 `[x] ~~...~~` 标记。
-
-## 阻塞记录
-
-- [ ] 暂无。
-
-## 日终交接
-
-- [ ] 写明已完成模型。
-- [ ] 写明已完成 API。
-- [ ] 写明未完成问题。
-- [ ] 写明 Day 2 前端联调需要使用的接口地址。
+- 不做完整 Agent 对话。
+- 不做完整 Hermes 调度。
+- 不做真实 OCR。
+- 不做复杂规则推理。