docs(engineering-baseline): 明确第一阶段数据库与实施基线

2026-09-01 14:05:01 +08:00
parent b7db30ec84
commit 3db6d83e04
4 changed files with 198 additions and 7 deletions
@@ -22,8 +22,8 @@ JobRadar 是一套面向个人使用、以 Agent 为核心的智能岗位发现
 | --- | --- | --- |
 | 开发语言 | Python 3.13 | 已配置 |
 | Web 框架 | Django 6.0.8 | 已配置 |
-| 当前数据库 | SQLite | 已配置，仅用于开发起步 |
+| 开发与测试数据库 | SQLite | 第一阶段默认使用 |
-| 目标数据库 | PostgreSQL | 规划中 |
+| 集成与生产数据库 | PostgreSQL | 集成验证可使用远程或本地实例，生产环境强制使用 |
 | 页面采集 | Playwright | 环境已安装，尚未接入 |
 | 普通请求 | HTTPX | 规划中 |
 | 异步任务 | Celery + Redis | 规划中 |
@@ -146,7 +146,10 @@ python -m playwright install chromium
 - 本地开发密钥、数据库密码、招聘网站 Cookie 和模型 API Key 不得提交到 Git。
 - 当前 `settings.py` 仍是 Django 生成的开发配置，不可直接用于生产环境。
- 接入 PostgreSQL 前，应先增加本地配置文件或环境隔离方案，并提供不含真实密钥的示例配置。
+- 第一阶段本地开发和自动化测试默认使用 SQLite，数据库文件不得提交到版本库。
 - PostgreSQL 通过环境变量按需启用；阶段结束前至少完成一次空库迁移和核心模型测试。
 - 远程 PostgreSQL 必须使用 TLS、项目专属数据库和低权限账号，自动化测试不得连接生产库。
 - 生产环境必须使用 PostgreSQL，不允许静默回退到 SQLite。
 - 采集器必须设置并发、频率、超时和指数退避，不能绕过验证码、登录保护或访问控制。
 - 企业性质及 AI 判断必须保存来源、判断时间和置信度；信息不足时应标记为待人工复核。
@@ -2,7 +2,7 @@
 ## 设计原则
-JobRadar 采用 Agent 原生的模块化单体架构。Django 负责公网产品外壳、用户系统、业务数据和运行记录；OpenAI Agents SDK 负责 Agent 循环、工具调用、结构化输出、运行状态和追踪；Celery Worker 承载耗时运行。各模块共享 PostgreSQL，避免为了展示效果提前拆分微服务。
+JobRadar 采用 Agent 原生的模块化单体架构。Django 负责公网产品外壳、用户系统、业务数据和运行记录；OpenAI Agents SDK 负责 Agent 循环、工具调用、结构化输出、运行状态和追踪；Celery Worker 承载耗时运行。生产环境各模块共享 PostgreSQL，避免为了展示效果提前拆分微服务；第一阶段本地开发和自动化测试允许使用 SQLite，并通过 PostgreSQL 集成验证保证迁移兼容性。
 ## 目标架构
@@ -0,0 +1,186 @@
 ---
 mode: new-feature
 moduleCode: engineering-baseline
 moduleName: 工程基线
 planDate: 2026-09-01
 scope: fullstack
 ---
 # 开发计划：第一阶段工程基线（新功能）
 ## 任务概述
 第一阶段将当前 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 的数据库策略。 |
@@ -12,12 +12,14 @@
 - [ ] 将密钥及本地配置移出版本库。
 - [ ] 接入Django用户认证和用户资料模型。
 - [ ] 为用户私有业务数据建立统一归属边界。
- [ ] 接入PostgreSQL并建立迁移基线。
+- [ ] 开发与测试默认使用SQLite，并建立可切换PostgreSQL的迁移基线。
 - [ ] 接入OpenAI Agents SDK。
 - [ ] 建立Agent Run、运行事件、工具调用和人工确认模型。
 - [ ] 增加统一日志、测试和代码质量工具。
-验收条件：开发与生产配置隔离，用户可以安全登录，PostgreSQL迁移通过，最小Agent运行数据可持久化。
+验收条件：开发与生产配置隔离，用户可以安全登录，SQLite下迁移和测试通过，PostgreSQL空库迁移及核心模型测试通过，最小Agent运行数据可持久化。
 详细实施范围、步骤和验收口径参见[第一阶段工程基线开发计划](engineering-baseline/dev-plan.md)。
 ## 阶段二：最小Agent闭环
@@ -92,7 +94,7 @@
 ## 第一阶段启动前待确认
-1. PostgreSQL运行位置和连接方式。
+1. PostgreSQL运行位置和连接方式可延后至阶段一集成验证前确认；日常开发与自动化测试默认使用SQLite。
 2. OpenAI模型、调用预算和API Key注入方式。
 3. 公网部署平台、域名和HTTPS证书管理方式。
 4. 首个目标招聘网站及允许使用的访问方式。