X-Financial/document/development/agent week plan/day_1_foundation_models.md

# Day 1：基础模型与工程骨架 TODO

目标：建立后续 6 天开发所需的后端地基。Day 1 不做复杂业务逻辑，只做稳定模型、API 骨架、种子数据、基础审计和可运行验证。

参考文档：

- `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. 开始前检查

- [ ] 确认当前分支和工作区状态。
- [ ] 确认后端目录位置，例如 `/app/server`。
- [ ] 确认前端目录位置，例如 `/app/web`。
- [ ] 确认后端使用的框架、ORM、迁移方式。
- [ ] 找到现有数据库模型目录。
- [ ] 找到现有 API 路由目录。
- [ ] 找到现有启动入口。
- [ ] 找到现有测试目录。
- [ ] 找到现有种子数据或初始化脚本。
- [ ] 记录不应修改的无关文件。

## 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`。
- [ ] 确认所有主键、外键、时间字段命名符合现有代码风格。

验收证据：

- [ ] 枚举命名在模型、Schema、服务层保持一致。
- [ ] 没有同时出现 `schedule` 和 `task` 两套用户可见命名。

## 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` 增加索引。

验收证据：

- [ ] 能创建一条规则资产。
- [ ] 能创建一条技能资产。
- [ ] 能创建一条 MCP 资产。
- [ ] 能创建一条任务资产。

## 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 快照。

验收证据：

- [ ] 同一个资产不能重复创建同一个版本号。
- [ ] 资产详情能拿到最近 5 个版本。

## 4. 建立 AgentAssetReview 模型

- [ ] 定义 `AgentAssetReview`。
- [ ] 增加字段 `id`。
- [ ] 增加字段 `asset_id`。
- [ ] 增加字段 `version`。
- [ ] 增加字段 `reviewer`。
- [ ] 增加字段 `review_status`。
- [ ] 增加字段 `review_note`。
- [ ] 增加字段 `reviewed_at`。
- [ ] 增加字段 `created_at`。
- [ ] 建立资产、版本、审核之间的查询关系。
- [ ] 增加服务层校验：没有 `approved` 审核时不能把规则置为 `active`。

验收证据：

- [ ] `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 前端联调需要使用的接口地址。