---
mode: new-feature
moduleCode: engineering-baseline
moduleName: 工程基线
planDate: 2026-09-01
scope: fullstack
---

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

> 执行状态：已于 2026-09-01 开始实施；步骤 1“配置与依赖基线”已完成代码和配置落盘，下一步为步骤 2“用户认证与数据归属设计”。依赖环境同步曾因网络下载长时间无进度而中断，恢复网络后需重新执行环境更新和 Ruff/pytest 验证。

## 任务概述

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

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

## 技术边界

### 数据库策略

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

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

### 功能范围

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

## 执行步骤

### 步骤 1：配置与依赖基线

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

### 步骤 2：用户认证与数据归属设计

- **前置条件**：步骤 1 完成。
- **实施内容**：
  - 保留 Django 内置 `User`，新增一对一用户资料模型。
  - 建立用户私有模型的抽象基类、查询方法和服务层校验约定。
  - 明确管理员和普通用户边界，默认关闭公开注册。
  - 明确跨用户访问的拒绝行为和测试用例。
- **期望产物**：
  - `accounts` 应用的模型、服务、管理配置和迁移。
  - `common` 公共归属模型或等效公共实现。
  - 用户认证及跨用户隔离测试。
- **完成标志**：管理员可创建用户；普通用户只能读取和修改自己的资料及私有数据。

### 步骤 3：Agent 运行持久化基线

- **前置条件**：步骤 2 的用户归属边界已确定。
- **实施内容**：
  - 建立 `AgentRun`、`AgentRunEvent`、`ToolCall` 和 `HumanApproval` 模型。
  - 定义等待、运行、暂停、成功、失败和取消等运行状态。
  - 通过服务层管理状态转换、事件序号和工具调用记录。
  - 保存脱敏输入输出摘要、trace 标识、耗时、用量和错误摘要。
  - 为工具调用预留幂等键和版本字段。
- **期望产物**：
  - `agent_runtime` 应用的模型、枚举、服务、管理配置和迁移。
  - 状态转换、事件顺序、人工确认和用户归属测试。
- **完成标志**：最小 Agent Run 及其事件、工具调用和人工确认记录可持久化并可审计。

### 步骤 4：最小页面与管理后台

- **前置条件**：步骤 2 和步骤 3 完成。
- **实施内容**：
  - 增加登录、退出和个人资料页面。
  - 增加当前用户的 Agent Run 列表与详情页面。
  - 在运行详情中按顺序展示事件和工具调用摘要。
  - 在 Django Admin 中注册用户资料和 Agent 运行模型。
- **期望产物**：
  - Django URL、视图、表单和模板。
  - 页面访问控制及基本响应测试。
- **完成标志**：两个普通用户登录后只能查看各自数据；管理员可在后台检查全部运行记录。

### 步骤 5：Agents SDK 最小接入

- **前置条件**：步骤 3 的持久化边界稳定。
- **实施内容**：
  - 建立服务端 SDK 配置读取入口和最小运行上下文。
  - 建立 SDK 运行信息到本地 `AgentRun` 的适配边界。
  - 使用测试替身验证运行创建、事件记录和异常落库。
  - 缺少 API Key 时，非 Agent 页面和管理功能仍可正常运行。
- **期望产物**：
  - Agent 运行配置、上下文和持久化适配代码。
  - 无外部付费调用的单元测试。
- **完成标志**：工程具备进入最小 Agent 闭环开发的稳定入口，但本阶段不执行真实岗位研究任务。

### 步骤 6：日志、质量检查与数据库兼容验证

- **前置条件**：前五个步骤完成。
- **实施内容**：
  - 配置包含请求或运行关联标识的结构化日志。
  - 对 API Key、密码、Cookie 和敏感工具参数执行脱敏。
  - 增加测试、静态检查、覆盖率和迁移检查命令。
  - 在 SQLite 上执行完整测试。
  - 在远程或本地 PostgreSQL 空库执行迁移和核心模型测试。
- **期望产物**：
  - 日志配置、自动化测试和质量工具配置。
  - SQLite 测试结果及 PostgreSQL 集成验证记录。
  - 更新后的 README 和阶段状态。
- **完成标志**：本计划“验收标准”全部满足，未执行项及原因有明确记录。

## 验收标准

### 自动化验收

```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 配置边界、依赖定义及质量工具配置；环境依赖同步因网络中断待补跑。 |