From d3763633c20d9ebd7b07a560d8f82efbcd4d2e34 Mon Sep 17 00:00:00 2001 From: bruce Date: Wed, 16 Sep 2026 17:30:26 +0800 Subject: [PATCH] =?UTF-8?q?docs(plan):=20=E6=9B=B4=E6=96=B0=E7=AC=AC?= =?UTF-8?q?=E4=B8=80=E9=98=B6=E6=AE=B5=E7=BA=B5=E5=90=91=E5=88=87=E7=89=87?= =?UTF-8?q?=E5=9F=BA=E7=BA=BF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../engineering-baseline/backend-design.md | 21 +++---- docs/engineering-baseline/dev-plan.md | 56 +++++++++++++++---- docs/roadmap.md | 16 ++++-- 3 files changed, 65 insertions(+), 28 deletions(-) diff --git a/.craftkit/designs/engineering-baseline/backend-design.md b/.craftkit/designs/engineering-baseline/backend-design.md index 604591d..bfd4e05 100644 --- a/.craftkit/designs/engineering-baseline/backend-design.md +++ b/.craftkit/designs/engineering-baseline/backend-design.md @@ -385,20 +385,15 @@ Admin 规则： ## 12. 实施顺序 -1. 创建 `common`，实现时间戳、用户归属和领域异常。 -2. 创建 `accounts`，实现 `UserProfile`、Admin、资料服务和迁移。 -3. 增加登录、退出、资料页面和用户隔离测试。 -4. 创建 `agent_runtime` 的枚举、模型、约束和迁移。 -5. 实现 Run 状态、事件序号、工具调用和人工确认服务。 -6. 增加 Agent 运行 Admin，并限制审计记录修改。 -7. 实现 Run 列表、详情页面和访问控制。 -8. 建立 SDK Gateway、测试替身和配置边界。 -9. 增加请求关联标识、日志上下文和日志脱敏。 -10. 执行 SQLite 全量验证。 -11. 在 PostgreSQL 空库执行迁移及核心约束和并发验证。 -12. 同步 README、路线图和第一阶段状态。 +实现采用“功能闭环驱动、模块边界承载”的纵向切片，而不是依次把各技术模块全部做完： -每一步都应保持可迁移、可测试，避免在单次迁移中同时承载全部模型。 +1. 用户登录、资料维护和跨用户隔离闭环。 +2. 管理员创建测试 Run 并审计状态、事件、工具调用和人工确认的闭环。 +3. 普通用户查看自己的运行列表和运行轨迹闭环。 +4. SDK 测试替身驱动一次成功或失败持久化运行的闭环。 +5. SQLite、页面、日志、质量工具和 PostgreSQL 的完整验收闭环。 + +每个切片内部仍按模型与迁移、服务与事务、入口与页面、测试与文档的依赖顺序实施。切片必须形成可运行结果并完成相应验证，才进入下一片；没有当前需求的未来模块和抽象不提前创建。 ## 13. 测试与验收策略 diff --git a/docs/engineering-baseline/dev-plan.md b/docs/engineering-baseline/dev-plan.md index 91aff44..3bb3144 100644 --- a/docs/engineering-baseline/dev-plan.md +++ b/docs/engineering-baseline/dev-plan.md @@ -4,11 +4,14 @@ moduleCode: engineering-baseline moduleName: 工程基线 planDate: 2026-09-01 scope: fullstack +reviewStatus: pending +reviewedAt: null +replacedBy: null --- # 开发计划：第一阶段工程基线（新功能） -> 执行状态：已于 2026-09-01 开始实施；步骤 1“配置与依赖基线”已完成代码和配置落盘，下一步为步骤 2“用户认证与数据归属设计”。依赖环境同步曾因网络下载长时间无进度而中断，恢复网络后需重新执行环境更新和 Ruff/pytest 验证。 +> 执行状态：配置基线、用户资料、数据归属、Agent 运行记录、最小页面和 SDK 测试替身闭环已落地。当前进入第一阶段收口，重点是质量工具环境同步、页面人工验收和 PostgreSQL 集成验证。 ## 任务概述 @@ -44,9 +47,19 @@ scope: fullstack - 管理：通过 Django Admin 管理用户资料和 Agent 运行记录。 - 工程质量：增加统一日志、自动化测试、静态检查和迁移检查。 -## 执行步骤 +## 实施策略 -### 步骤 1：配置与依赖基线 +第一阶段采用“功能闭环驱动、模块边界承载”的纵向切片： + +- 开发顺序由可运行、可验收的用户场景决定。 +- `common`、`accounts`、`agent_runtime` 继续承担稳定的数据和代码归属。 +- 每个切片同时完成必要的模型、服务、入口、页面和测试。 +- 当前切片没有真实需求的字段、接口和抽象不提前实现。 +- 每个切片通过自动验证和人工验收后，才进入下一个切片。 + +## 功能切片 + +### 切片 0：可启动的分环境工程骨架 - **输入材料**：[项目说明](../../README.md)、[架构设计](../architecture.md)、[实施路线图](../roadmap.md)。 - **实施内容**： @@ -60,11 +73,14 @@ scope: fullstack - `JobRadar/settings/` 分环境配置。 - `.env.example` 和更新后的 `.gitignore`。 - 更新后的依赖定义和开发说明。 +- **当前状态**：已实现。 - **完成标志**：开发及测试配置可启动；生产配置缺少关键变量时明确失败；仓库不含真实密钥。 -### 步骤 2：用户认证与数据归属设计 +### 切片 1：用户可以安全登录并维护自己的资料 - **前置条件**：步骤 1 完成。 +- **用户闭环**：管理员创建用户，用户登录、查看和修改自己的资料，无法访问其他用户数据。 +- **涉及模块**：`common`、`accounts`、Django 认证与模板。 - **实施内容**： - 保留 Django 内置 `User`，新增一对一用户资料模型。 - 建立用户私有模型的抽象基类、查询方法和服务层校验约定。 @@ -74,11 +90,15 @@ scope: fullstack - `accounts` 应用的模型、服务、管理配置和迁移。 - `common` 公共归属模型或等效公共实现。 - 用户认证及跨用户隔离测试。 +- **当前状态**：代码与基础自动化测试已实现，待两个真实用户的人工页面验收。 +- **停止条件**：发现需要公开注册、自定义用户模型或复杂角色体系时停止并重新设计认证边界。 - **完成标志**：管理员可创建用户；普通用户只能读取和修改自己的资料及私有数据。 -### 步骤 3：Agent 运行持久化基线 +### 切片 2：管理员可以创建并审计最小 Agent Run -- **前置条件**：步骤 2 的用户归属边界已确定。 +- **前置条件**：切片 1 的用户归属边界已确定。 +- **用户闭环**：管理员创建测试 Run，系统记录状态、事件、工具调用和人工确认，Admin 可以审计完整过程。 +- **涉及模块**：`common`、`agent_runtime`、Django Admin。 - **实施内容**： - 建立 `AgentRun`、`AgentRunEvent`、`ToolCall` 和 `HumanApproval` 模型。 - 定义等待、运行、暂停、成功、失败和取消等运行状态。 @@ -88,11 +108,15 @@ scope: fullstack - **期望产物**： - `agent_runtime` 应用的模型、枚举、服务、管理配置和迁移。 - 状态转换、事件顺序、人工确认和用户归属测试。 +- **当前状态**：模型、迁移、服务层、状态转换、工具调用、人工确认和 Admin 已实现；关键非法转换、工具幂等及跨用户拒绝已完成自动化测试，并发压力验证留待后续集成环境执行。 +- **停止条件**：状态修改绕过服务层、事件可被普通入口改写或敏感参数进入摘要时停止交付。 - **完成标志**：最小 Agent Run 及其事件、工具调用和人工确认记录可持久化并可审计。 -### 步骤 4：最小页面与管理后台 +### 切片 3：用户可以查看自己的运行轨迹 -- **前置条件**：步骤 2 和步骤 3 完成。 +- **前置条件**：切片 1 和切片 2 完成。 +- **用户闭环**：两个用户分别登录，只能看到自己的 Run，并能在详情页按顺序查看运行事件和工具摘要。 +- **涉及模块**：`accounts`、`agent_runtime`、Django Templates。 - **实施内容**： - 增加登录、退出和个人资料页面。 - 增加当前用户的 Agent Run 列表与详情页面。 @@ -101,11 +125,15 @@ scope: fullstack - **期望产物**： - Django URL、视图、表单和模板。 - 页面访问控制及基本响应测试。 +- **当前状态**：页面、路由、登录退出、列表用户隔离和跨用户 404 测试已实现，待真实浏览器、响应式和可访问性验收。 +- **停止条件**：页面需要前后端分离或出现第一阶段未定义的写操作时停止并补充接口设计。 - **完成标志**：两个普通用户登录后只能查看各自数据；管理员可在后台检查全部运行记录。 -### 步骤 5：Agents SDK 最小接入 +### 切片 4：测试替身可以驱动一次持久化运行 -- **前置条件**：步骤 3 的持久化边界稳定。 +- **前置条件**：切片 2 的持久化边界稳定。 +- **用户闭环**：测试替身接收最小运行上下文，驱动 Run 从等待到成功或失败，并完整保存事件和脱敏结果。 +- **涉及模块**：`agent_runtime` Gateway、运行服务和配置边界。 - **实施内容**： - 建立服务端 SDK 配置读取入口和最小运行上下文。 - 建立 SDK 运行信息到本地 `AgentRun` 的适配边界。 @@ -114,11 +142,15 @@ scope: fullstack - **期望产物**： - Agent 运行配置、上下文和持久化适配代码。 - 无外部付费调用的单元测试。 +- **当前状态**：Gateway 协议、Stub、服务端配置读取和持久化编排服务已实现；成功、失败、异常脱敏及缺少密钥的自动化测试已通过。真实 Agents SDK 运行入口仍属于第二阶段。 +- **停止条件**：测试尝试真实付费调用、API Key 进入数据库或缺少 Key 导致非 Agent 页面失败时停止。 - **完成标志**：工程具备进入最小 Agent 闭环开发的稳定入口，但本阶段不执行真实岗位研究任务。 -### 步骤 6：日志、质量检查与数据库兼容验证 +### 切片 5：工程基线可以被完整验收 - **前置条件**：前五个步骤完成。 +- **验收闭环**：在无真实密钥和付费调用的条件下完成 SQLite 自动验证、页面人工验收和 PostgreSQL 空库验证。 +- **涉及模块**：全项目配置、测试、日志、迁移和文档。 - **实施内容**： - 配置包含请求或运行关联标识的结构化日志。 - 对 API Key、密码、Cookie 和敏感工具参数执行脱敏。 @@ -129,6 +161,8 @@ scope: fullstack - 日志配置、自动化测试和质量工具配置。 - SQLite 测试结果及 PostgreSQL 集成验证记录。 - 更新后的 README 和阶段状态。 +- **当前状态**：请求关联标识、递归脱敏、SQLite 迁移检查和 19 项 Django 测试已完成；当前 Conda 环境尚未安装 pytest 与 Ruff，生产配置检查、页面人工验收和 PostgreSQL 验证待完成。 +- **停止条件**：质量工具环境与依赖清单不一致、测试连接生产库或日志出现秘密时停止验收。 - **完成标志**：本计划“验收标准”全部满足，未执行项及原因有明确记录。 ## 验收标准 diff --git a/docs/roadmap.md b/docs/roadmap.md index 2a7c91c..f36420c 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -1,8 +1,14 @@ +--- +reviewStatus: pending +reviewedAt: null +replacedBy: null +--- + # JobRadar 实施路线图 ## 推进原则 -项目按可运行成果分阶段实施。每个阶段由AI直接生成代码、迁移、测试和必要文档，但只实现当前阶段所需内容；完成自动验证和用户验收后，再扩大范围。 +项目按可运行成果分阶段实施。阶段内部采用“功能闭环驱动、模块边界承载”的纵向切片：每个切片同时完成必要的数据、服务、页面和测试，形成可运行结果后再扩大范围；不先把所有模块建完，也不为了功能闭环破坏模块职责。 ## 阶段一：工程基线 @@ -10,13 +16,15 @@ - [x] 拆分开发、测试和生产配置。 - [x] 将密钥及本地配置移出版本库。 -- [ ] 接入Django用户认证和用户资料模型。 -- [ ] 为用户私有业务数据建立统一归属边界。 +- [x] 接入Django用户认证和用户资料模型。 +- [x] 为用户私有业务数据建立统一归属边界。 - [ ] 开发与测试默认使用SQLite，并建立可切换PostgreSQL的迁移基线。 - [ ] 接入OpenAI Agents SDK。 -- [ ] 建立Agent Run、运行事件、工具调用和人工确认模型。 +- [x] 建立Agent Run、运行事件、工具调用和人工确认模型。 - [ ] 增加统一日志、测试和代码质量工具。 +当前状态：用户资料、数据归属、Agent 运行持久化、最小页面及 SDK 测试替身编排闭环已经落地；真实 Agents SDK 接入仍属于第二阶段。第一阶段剩余 PostgreSQL 集成验证、Ruff/pytest 环境同步、生产配置检查及人工页面验收。 + 验收条件：开发与生产配置隔离，用户可以安全登录，SQLite下迁移和测试通过，PostgreSQL空库迁移及核心模型测试通过，最小Agent运行数据可持久化。 详细实施范围、步骤和验收口径参见[第一阶段工程基线开发计划](engineering-baseline/dev-plan.md)。