From 3db6d83e04b23fc5ac1bb4eafad280fba62584db Mon Sep 17 00:00:00 2001
From: bruce <brucesun0304@outlook.com>
Date: Tue, 1 Sep 2026 14:05:01 +0800
Subject: [PATCH] =?UTF-8?q?docs(engineering-baseline):=20=E6=98=8E?=
 =?UTF-8?q?=E7=A1=AE=E7=AC=AC=E4=B8=80=E9=98=B6=E6=AE=B5=E6=95=B0=E6=8D=AE?=
 =?UTF-8?q?=E5=BA=93=E4=B8=8E=E5=AE=9E=E6=96=BD=E5=9F=BA=E7=BA=BF?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md                             |   9 +-
 docs/architecture.md                  |   2 +-
 docs/engineering-baseline/dev-plan.md | 186 ++++++++++++++++++++++++++
 docs/roadmap.md                       |   8 +-
 4 files changed, 198 insertions(+), 7 deletions(-)
 create mode 100644 docs/engineering-baseline/dev-plan.md

diff --git a/README.md b/README.md
index 3180c89..ba1b377 100644
--- a/README.md
+++ b/README.md
@@ -22,8 +22,8 @@ JobRadar 是一套面向个人使用、以 Agent 为核心的智能岗位发现
 | --- | --- | --- |
 | 开发语言 | Python 3.13 | 已配置 |
 | Web 框架 | Django 6.0.8 | 已配置 |
-| 当前数据库 | SQLite | 已配置，仅用于开发起步 |
-| 目标数据库 | PostgreSQL | 规划中 |
+| 开发与测试数据库 | SQLite | 第一阶段默认使用 |
+| 集成与生产数据库 | 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 判断必须保存来源、判断时间和置信度；信息不足时应标记为待人工复核。
 
diff --git a/docs/architecture.md b/docs/architecture.md
index a11a4d6..afc8cf4 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -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 集成验证保证迁移兼容性。
 
 ## 目标架构
 
diff --git a/docs/engineering-baseline/dev-plan.md b/docs/engineering-baseline/dev-plan.md
new file mode 100644
index 0000000..919e921
--- /dev/null
+++ b/docs/engineering-baseline/dev-plan.md
@@ -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 的数据库策略。 |
diff --git a/docs/roadmap.md b/docs/roadmap.md
index d2d2f7e..b3a5e47 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -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. 首个目标招聘网站及允许使用的访问方式。