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