---
mode: new-feature
moduleCode: engineering-baseline
moduleName: 工程基线
planDate: 2026-09-01
scope: fullstack
reviewStatus: pending
reviewedAt: null
replacedBy: null
---

# 开发计划：第一阶段工程基线（新功能）

> 执行状态：配置基线、用户资料、数据归属、Agent 运行记录、最小页面和 SDK 测试替身闭环已落地。当前进入第一阶段收口，重点是质量工具环境同步、页面人工验收和 PostgreSQL 集成验证。

## 任务概述

第一阶段将当前 Django 基础骨架升级为可持续开发的应用基线。本阶段完成分环境配置、密钥隔离、用户认证、用户资料、用户数据归属边界、Agent 运行记录、最小管理及用户页面、日志、测试和代码质量工具。

本阶段不实现岗位采集、企业研究、筛选评分、Celery 调度或真实岗位研究 Agent 循环。相关能力在工程基线验收通过后按后续阶段实施。

## 技术边界

### 数据库策略

| 环境 | 默认数据库 | 约束 |
| --- | --- | --- |
| 本地开发 | SQLite | 无需额外数据库服务；数据库文件不得提交 Git |
| 自动化测试 | SQLite 测试库 | 每次测试独立创建，不使用开发或生产数据 |
| 集成验证 | 远程或本地 PostgreSQL | 通过环境变量启用；不得连接生产库执行测试 |
| 生产 | PostgreSQL | 强制配置，禁止回退到 SQLite |

- 兼容基准：业务模型和迁移同时兼容 SQLite 与 PostgreSQL。
- SQL 边界：第一阶段不使用 SQLite 专属行为、数据库方言专属 SQL 或仅由单一数据库支持的字段。
- PostgreSQL 验证：阶段结束前至少完成一次空库迁移和核心模型测试。
- 远程连接：启用 TLS，使用项目专属数据库、低权限账号和访问来源限制。
- 凭据管理：连接地址和密码通过环境变量注入，不写入仓库、日志或 Agent 上下文。

### 功能范围

- 配置：拆分基础、开发、测试和生产配置。
- 认证：使用 Django 内置用户、密码哈希、Session 和登录保护。
- 用户资料：新增与用户一对一关联的基础资料模型。
- 数据归属：为用户私有模型建立统一的所属用户边界和查询约定。
- Agent 记录：建立运行、事件、工具调用和人工确认模型。
- 页面：提供登录、退出、个人资料、运行列表和运行详情的最小页面。
- 管理：通过 Django Admin 管理用户资料和 Agent 运行记录。
- 工程质量：增加统一日志、自动化测试、静态检查和迁移检查。

## 实施策略

第一阶段采用“功能闭环驱动、模块边界承载”的纵向切片：

- 开发顺序由可运行、可验收的用户场景决定。
- `common`、`accounts`、`agent_runtime` 继续承担稳定的数据和代码归属。
- 每个切片同时完成必要的模型、服务、入口、页面和测试。
- 当前切片没有真实需求的字段、接口和抽象不提前实现。
- 每个切片通过自动验证和人工验收后，才进入下一个切片。

## 功能切片

### 切片 0：可启动的分环境工程骨架

- **输入材料**：[项目说明](../../README.md)、[架构设计](../architecture.md)、[实施路线图](../roadmap.md)。
- **实施内容**：
  - 将单文件配置拆分为 `base`、`development`、`test` 和 `production`。
  - 增加不含真实凭据的 `.env.example`，更新敏感文件忽略规则。
  - 配置中文语言、上海时区、模板目录、静态文件及登录跳转。
  - 开发和测试默认使用 SQLite，生产配置强制使用 PostgreSQL。
  - 增加可选 PostgreSQL 集成验证配置。
  - 补充 OpenAI Agents SDK、测试和代码质量依赖。
- **期望产物**：
  - `JobRadar/settings/` 分环境配置。
  - `.env.example` 和更新后的 `.gitignore`。
  - 更新后的依赖定义和开发说明。
- **当前状态**：已实现。
- **完成标志**：开发及测试配置可启动；生产配置缺少关键变量时明确失败；仓库不含真实密钥。

### 切片 1：用户可以安全登录并维护自己的资料

- **前置条件**：步骤 1 完成。
- **用户闭环**：管理员创建用户，用户登录、查看和修改自己的资料，无法访问其他用户数据。
- **涉及模块**：`common`、`accounts`、Django 认证与模板。
- **实施内容**：
  - 保留 Django 内置 `User`，新增一对一用户资料模型。
  - 建立用户私有模型的抽象基类、查询方法和服务层校验约定。
  - 明确管理员和普通用户边界，默认关闭公开注册。
  - 明确跨用户访问的拒绝行为和测试用例。
- **期望产物**：
  - `accounts` 应用的模型、服务、管理配置和迁移。
  - `common` 公共归属模型或等效公共实现。
  - 用户认证及跨用户隔离测试。
- **当前状态**：代码与基础自动化测试已实现，待两个真实用户的人工页面验收。
- **停止条件**：发现需要公开注册、自定义用户模型或复杂角色体系时停止并重新设计认证边界。
- **完成标志**：管理员可创建用户；普通用户只能读取和修改自己的资料及私有数据。

### 切片 2：管理员可以创建并审计最小 Agent Run

- **前置条件**：切片 1 的用户归属边界已确定。
- **用户闭环**：管理员创建测试 Run，系统记录状态、事件、工具调用和人工确认，Admin 可以审计完整过程。
- **涉及模块**：`common`、`agent_runtime`、Django Admin。
- **实施内容**：
  - 建立 `AgentRun`、`AgentRunEvent`、`ToolCall` 和 `HumanApproval` 模型。
  - 定义等待、运行、暂停、成功、失败和取消等运行状态。
  - 通过服务层管理状态转换、事件序号和工具调用记录。
  - 保存脱敏输入输出摘要、trace 标识、耗时、用量和错误摘要。
  - 为工具调用预留幂等键和版本字段。
- **期望产物**：
  - `agent_runtime` 应用的模型、枚举、服务、管理配置和迁移。
  - 状态转换、事件顺序、人工确认和用户归属测试。
- **当前状态**：模型、迁移、服务层、状态转换、工具调用、人工确认和 Admin 已实现；关键非法转换、工具幂等及跨用户拒绝已完成自动化测试，并发压力验证留待后续集成环境执行。
- **停止条件**：状态修改绕过服务层、事件可被普通入口改写或敏感参数进入摘要时停止交付。
- **完成标志**：最小 Agent Run 及其事件、工具调用和人工确认记录可持久化并可审计。

### 切片 3：用户可以查看自己的运行轨迹

- **前置条件**：切片 1 和切片 2 完成。
- **用户闭环**：两个用户分别登录，只能看到自己的 Run，并能在详情页按顺序查看运行事件和工具摘要。
- **涉及模块**：`accounts`、`agent_runtime`、Django Templates。
- **实施内容**：
  - 增加登录、退出和个人资料页面。
  - 增加当前用户的 Agent Run 列表与详情页面。
  - 在运行详情中按顺序展示事件和工具调用摘要。
  - 在 Django Admin 中注册用户资料和 Agent 运行模型。
- **期望产物**：
  - Django URL、视图、表单和模板。
  - 页面访问控制及基本响应测试。
- **当前状态**：页面、路由、登录退出、列表用户隔离和跨用户 404 测试已实现，待真实浏览器、响应式和可访问性验收。
- **停止条件**：页面需要前后端分离或出现第一阶段未定义的写操作时停止并补充接口设计。
- **完成标志**：两个普通用户登录后只能查看各自数据；管理员可在后台检查全部运行记录。

### 切片 4：测试替身可以驱动一次持久化运行

- **前置条件**：切片 2 的持久化边界稳定。
- **用户闭环**：测试替身接收最小运行上下文，驱动 Run 从等待到成功或失败，并完整保存事件和脱敏结果。
- **涉及模块**：`agent_runtime` Gateway、运行服务和配置边界。
- **实施内容**：
  - 建立服务端 SDK 配置读取入口和最小运行上下文。
  - 建立 SDK 运行信息到本地 `AgentRun` 的适配边界。
  - 使用测试替身验证运行创建、事件记录和异常落库。
  - 缺少 API Key 时，非 Agent 页面和管理功能仍可正常运行。
- **期望产物**：
  - Agent 运行配置、上下文和持久化适配代码。
  - 无外部付费调用的单元测试。
- **当前状态**：Gateway 协议、Stub、服务端配置读取和持久化编排服务已实现；成功、失败、异常脱敏及缺少密钥的自动化测试已通过。真实 Agents SDK 运行入口仍属于第二阶段。
- **停止条件**：测试尝试真实付费调用、API Key 进入数据库或缺少 Key 导致非 Agent 页面失败时停止。
- **完成标志**：工程具备进入最小 Agent 闭环开发的稳定入口，但本阶段不执行真实岗位研究任务。

### 切片 5：工程基线可以被完整验收

- **前置条件**：前五个步骤完成。
- **验收闭环**：在无真实密钥和付费调用的条件下完成 SQLite 自动验证、页面人工验收和 PostgreSQL 空库验证。
- **涉及模块**：全项目配置、测试、日志、迁移和文档。
- **实施内容**：
  - 配置包含请求或运行关联标识的结构化日志。
  - 对 API Key、密码、Cookie 和敏感工具参数执行脱敏。
  - 增加测试、静态检查、覆盖率和迁移检查命令。
  - 在 SQLite 上执行完整测试。
  - 在远程或本地 PostgreSQL 空库执行迁移和核心模型测试。
- **期望产物**：
  - 日志配置、自动化测试和质量工具配置。
  - SQLite 测试结果及 PostgreSQL 集成验证记录。
  - 更新后的 README 和阶段状态。
- **当前状态**：请求关联标识、递归脱敏、SQLite 迁移检查和 19 项 Django 测试已完成；当前 Conda 环境尚未安装 pytest 与 Ruff，生产配置检查、页面人工验收和 PostgreSQL 验证待完成。
- **停止条件**：质量工具环境与依赖清单不一致、测试连接生产库或日志出现秘密时停止验收。
- **完成标志**：本计划“验收标准”全部满足，未执行项及原因有明确记录。

## 验收标准

### 自动化验收

```powershell
python manage.py check
python manage.py check --deploy --settings=JobRadar.settings.production
python manage.py makemigrations --check --dry-run
python manage.py migrate
pytest
ruff check .
```

- SQLite 下所有迁移和自动化测试通过。
- PostgreSQL 空库迁移通过，核心模型约束和用户隔离测试通过。
- 生产配置缺少密钥或数据库配置时拒绝启动。
- Git 差异不包含 `.env`、数据库文件、API Key、密码或 Cookie。

### 人工验收

1. 管理员能够创建两个普通用户。
2. 两个用户均可正常登录和退出。
3. 用户 A 无法访问用户 B 的资料和 Agent Run。
4. 管理员能够创建并查看最小 Agent Run。
5. 运行详情按顺序展示事件和工具调用摘要。
6. 日志不包含密码、API Key 和完整敏感参数。
7. 未提供 OpenAI API Key 时，非 Agent 功能仍可运行。

## 非目标

- 不实现招聘网站采集器、岗位模型和企业研究。
- 不实现硬性筛选、权重评分和推荐报告。
- 不接入 Celery、Redis 或定时调度。
- 不实现真实岗位研究 Agent 循环或付费模型调用。
- 不开放用户注册，不建设复杂角色权限体系。
- 不引入 Django REST Framework、Vue、多 Agent、RAG 或向量数据库。
- 不实施公网部署，但生产配置必须为后续部署保留安全边界。

## 开发决策项

第一阶段开发可以直接开始，以下事项采用默认策略，不构成启动阻塞：

| 决策项 | 第一阶段默认策略 | 最迟确认时间 |
| --- | --- | --- |
| PostgreSQL 位置 | 日常开发使用 SQLite；阶段验收时使用远程或本地 PostgreSQL | 步骤 6 前 |
| OpenAI 模型 | 仅提供环境变量配置，不固定付费模型 | 第二阶段启动前 |
| OpenAI API Key | 仅从环境变量注入；第一阶段测试使用替身 | 真实调用前 |
| 部署平台和域名 | 第一阶段不部署 | 第六阶段启动前 |
| 首个招聘网站 | 第一阶段不接入 | 第三阶段启动前 |

## 变更历史

| 日期 | 版本 | 说明 |
| --- | --- | --- |
| 2026-09-01 | 初稿 | 建立第一阶段工程基线开发计划，确认 SQLite 优先、PostgreSQL 集成验证和生产强制 PostgreSQL 的数据库策略。 |
| 2026-09-01 | 步骤 1 | 完成分环境配置、密钥隔离、SQLite/PostgreSQL 配置边界、依赖定义及质量工具配置；环境依赖同步因网络中断待补跑。 |