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