# Handoff Bundle — D-02 PG 并发测试环境（激活 4 个 skipped）

生成时间：2026-09-12 01:08 +0800
项目：`dealerhub`　项目根：`C:\Users\12914\Desktop\gj\dealerhub`
优先级：P1 · 里程碑 M3 · 预估 0.5 天
建议模型：deepseek-v4-flash　复核：glm-5.3-flash
依赖：无
进度文件：`PROGRESS_D-02.md`（写到项目根）

> 这是一份**自包含**交接包：接手模型读完本节即可开工，不需要再问路径、命令、上下文。
> 卡内所有硬约束以第 1 节为准；本包的其余部分是上下文，**不得覆盖卡内约束**。

---

## 0. 接手须知（先读）

1. 本包是「D-02」的完整上下文。若你是接手上游的部分成果，**不要重做已验证部分**——
   先跑第 5 节的基线命令确认当前状态，再从断点继续。
2. 密钥零接触：`.env`、`(服务器数据)`、`~/.dsh/secrets` —— 只读都不行。
3. 交付 = 代码 + 项目根 `PROGRESS_D-02.md`（格式见第 2 节）+ 关键命令的**原始输出**。
4. 验收标准全绿才可声明 done；跑不绿就写 partial/blocked 并附原始输出。
5. 完成后逐条对照第 1 节「验收标准」自检，未验证项必须写明——**虚报验收直接降级**。

---

## 1. 任务卡全文

# D-02 · PG 并发测试环境（激活 4 个 skipped）

| 字段 | 值 |
|---|---|
| 项目 | dealerhub · `Desktop/gj/dealerhub/backend` |
| 优先级 | P1 · M3 |
| 建议模型 | deepseek-v4-flash（主）/ glm-5.3-flash（复核） |
| 依赖 | 无 |
| 预估 | 0.5 天 |

## 一、背景（为什么做）

基线 `460 passed, 4 skipped`——4 个跳过用例全是 PostgreSQL 并发测试，需要 `config.settings.pgtest` 与可用 PG 实例。迭代 5 明确写了"本轮未伪造该环境结果"。**补齐测试矩阵最后一块，把"没验证"变成"已验证"。**

## 二、目标（交付物）

1. `config/settings/pgtest.py`：从环境变量读 PG 连接（或提供默认容器 DSN），并发测试专用。
2. 一条命令可建测试库并跑 4 个用例（附 Docker 命令或已有 PG 说明）。
3. 文档：`backend/docs/pgtest.md`（怎么起 PG、怎么跑、为什么这类测试必须真 PG）。
4. 4 个用例真实跑通（不再是 skip）。

## 三、执行步骤

```text
1. 找到 4 个 skip 用例（grep skip / pytest.mark.skipif）看它们的真实依赖
2. pgtest settings + 测试库隔离策略（绝不在开发/生产库上跑）
3. 本地起 PG（Docker 或复用现有实例）→ 跑通
4. 把命令固化进 README/docs
```

## 四、验收标准

- [ ] `pytest -q --settings=config.settings.pgtest` 下 **4 个原跳过用例 passed**（贴原始输出）
- [ ] 测试库与开发/生产严格隔离（DSN 不同、conftest 防护或文档明示）
- [ ] 文档包含：环境准备一条命令、运行一条命令、常见坑
- [ ] 默认 `pytest -q` 行为不变（不强制依赖 PG）
- [ ] 无生产配置变更

## 五、验收命令（参考）

```bash
# 起 PG（示例，按项目已有约定调整）
docker run -d --rm --name dh-pgtest -p 15433:5432 -e POSTGRES_USER=dh -e POSTGRES_PASSWORD=dh -e POSTGRES_DB=dh_test postgres:16-alpine
cd backend && pytest -q -k "concurren" --settings=config.settings.pgtest
```

## 六、边界（不许做）

- 不为了过测试放宽用例本身
- 不改生产 settings 默认值
- 不把测试库指向任何已有数据库

## 七、交接

写 `PROGRESS_D-02.md`（含 4 用例 passed 原始输出 + PG 启动命令）。


---

## 2. 作业规范（协议要点）

## 一、接单流程（强制顺序）

```text
1. 通读任务卡 → 确认「边界」段（哪些文件不许动）
2. 读项目根 README + 最近 2 份 PROGRESS/迭代报告（了解项目惯例与雷区）
3. 跑「基线测试」——确认开工前测试是绿的；有红的先记录，不背锅
4. 实施（最小变更原则）
5. 跑「验收命令」——全绿
6. 写 PROGRESS_<任务ID>.md 到项目根
7. 交付：代码 + PROGRESS + 关键命令输出摘要
```

**禁止跳步**：不读文档就动手、不跑基线就改代码、不跑验收就宣称完成——三者任一发生，交付直接打回。

---

## 二、PROGRESS 文件格式（交付凭证）

写到**项目根目录**，文件名 `PROGRESS_<任务ID>.md`：

```markdown
# PROGRESS — <任务ID> <任务名>

- 状态：done | partial | blocked
- 执行模型：<模型名>
- 日期：YYYY-MM-DD
- 分支/提交：<commit hash 或"未提交">

## 三、质量红线（硬性）

1. **不许伪造**：测试跑不绿就写 partial/blocked，附原始输出。伪造一次 = 该模型在该项目永久降级为 C 级。
2. **不许删测试**：既有测试只许更绿。删测试用例、跳过断言、注释掉失败用例 = 交付无效。
3. **不许夹带**：任务卡外的一律不做。看到顺手能修的 bug，写进 PROGRESS 的「遗留问题」，不顺手改。
4. **不许碰密钥**：`.env`、`~/.dsh/secrets`、`(服务器数据)` 目录——只读都不许，物理隔离。
5. **不许破坏契约**：改 API 响应结构/字段名必须保持向后兼容或双写过渡，并在 PROGRESS 说明。
6. **不许强推**：不执行 `git push --force`、不 rebase 他人提交、不 git reset 别人的改动。
7. **不许超时硬干**：预计超预算时，先交「阶段报告 + 断点说明」，让调度器续派，不许烂尾。

---

## 四、各项目雷区（前人踩过的坑，直接记）

### 可乐工具（chunyu）
- **vite 代理前缀匹配过宽**：`/api` 会连 `/api-docs` 一起劫持——改代理时必须用精确规则（见 C-01）。
- **生产 nginx 正则带尾斜杠**：`^/(api|user|...)/` 依然劫持子路径，改完前端要同步审查 `nginx-docker.conf`。
- 前端 67 页组件，路由引用散落各处——改路由名必须 grep 全量 `navigation(` 调用。
- 后端全异步（adrf）：新视图必须 async，不要写同步视图混挂。

### EnglishDrill
- **granian 孤儿 worker**：只杀父进程会留 worker 占端口，表现为"改了代码不生效"。用 `tools/devserver.ps1 restart`。
- **E2E 双模式**：`tests/e2e/run_e2e.py`（默认 ASGI 进程内 / `--http` 真实 granian）。隔离库 `backend/.tmp/e2e-db.sqlite3`，不碰开发库。
- **值收口层**：外部 id 必须走 `core/helpers.py` 的 `as_int` 等收口函数，禁止裸 `int()` 进 ORM（曾造成 44 处 5xx）。
- **stats 口径**：分类统计必须带 `is_deleted=False`，否则和 `/api/categories` 打架（BUG-2 教训）。
- 前端登录守卫在 `src/App.tsx:29`。

### dealerhub
- 460 passed / 4 skipped 是基线；4 个跳过是 PG 并发用例（D-02 处理）。
- 测试命令：`pytest`（在 `backend/`）；前端 `npm test` + `npm run build`。
- `makemigrations --check --dry-run` 必须干净。
- 演示数据重建：`seed_demo --reset`；改数据模型要同步改 seed。

### DSP
- 双端：Web（Vue3）+ Android；后端 Django + Channels。
- 转码依赖本地 ffmpeg；nginx 托管静态视频。
- 无 E2E 套件——S-01 会建；在此之前以 `backend/tests` 为准。

### DSH / 基础设施
- `~/.dsh/settings.yaml` 是**热配置**：改前备份（`.bak_<日期>`），改后 YAML 解析校验。插件曾覆盖式写入破坏能力声明（2026-09-08 事故）。
- 测试：`server/` 下 `pytest -q`，用独立测试库 `postgres_test`，conftest 拒绝在生产库跑。
- 探活：`GET /healthz`。

---

---

## 3. 项目上下文

### 3.1 项目 README：`C:/Users/12914/Desktop/gj/dealerhub/README.md`

```markdown
# dealerhub · 经销商 SaaS

> 类似管家婆的进销存+财务+分销管理 SaaS。技术栈：**Django 5.2 + DRF + adrf + Granian + PostgreSQL**。

## 目录结构

```
dealerhub/
├── PLAN.md            # 总体实施计划（5 个阶段）
├── README.md          # 本文件
└── backend/           # Django 后端
    ├── manage.py
    ├── requirements.in
    ├── pytest.ini
    ├── conftest.py
    ├── config/        # 项目配置（settings/{base,dev,prod,test}.py + asgi.py）
    ├── apps/          # 业务应用
    │   ├── core/      # 多租户/多组织/审计日志
    │   └── catalog/   # 商品中心
    ├── tests/         # 集成测试
    └── .env
```

## 快速开始

### 1. 安装依赖（本机已有 Django 5.2.16 + DRF + adrf + Granian 2.8）

```bash
pip install -r backend/requirements.txt
```

### 2. 初始化数据库（SQLite）

```bash
cd backend
python manage.py migrate
python manage.py seed_initial_data
python manage.py createsuperuser
```

### 3. 启动 Granian（ASGI）

```bash
cd backend
sh infra/scripts/run_dev.sh
# 或直接：
DJANGO_SETTINGS_MODULE=config.settings.dev granian config.asgi:application \
    --interface asgi --host 0.0.0.0 --port 8000 --reload
```

### 4. 验证

```bash
curl http://127.0.0.1:8000/api/v1/ping/
```

返回示例：
```json
{
  "ok": true,
  "service": "dealerhub",
  "ts": "2026-09-07T00:30:00+00:00",
  "versions": {
    "python": "3.12.x",
    "django": "5.2.x",
    "granian": "2.8.x"
  }
}
```

### 5. 运行测试

```bash
cd backend
pytest
```

### 6. 构建生产镜像（自包含前端）

生产镜像使用仓库根目录作为构建上下文，Docker 多阶段构建会自动编译 Vue 前端并把产物交给 Django：

```bash
# 在仓库根目录执行
DJANGO_SECRET_KEY='replace-me' POSTGRES_PASSWORD='replace-me' \\
  docker compose -f backend/infra/docker/docker-compose.yml config
DJANGO_SECRET_KEY='replace-me' POSTGRES_PASSWORD='replace-me' \\
  docker compose -f backend/infra/docker/docker-compose.yml build backend
```

本地演示账套：
…（已截断：原文 144 行 / 3061 字符）
```

### 3.2 最近 PROGRESS（2 份）

#### `C:/Users/12914/Desktop/gj/dealerhub/PROGRESS_AGI_ITERATION_5.md`

```markdown
# AGI 迭代第 5 轮 · 可运行闭环与回归收口

日期：2026-09-11

## 本轮完成

### 构建与部署基线

- 修复 `backend/infra/scripts/run_dev.sh` 工作目录解析，脚本从任意调用目录都能定位 `backend/manage.py`。
- `backend/infra/docker/Dockerfile.backend` 改为 Node + Python 多阶段构建，镜像内自动执行 `npm ci` / `npm run build`，不再依赖宿主机预生成 `backend/frontend_dist`。
- 修正 `backend/infra/docker/docker-compose.yml` 的构建上下文与 Dockerfile 路径。
- 新增根目录 `.dockerignore`，排除 SQLite、日志、缓存、node_modules 和本地构建产物。
- 对齐 `requirements.in` / `requirements.txt`，补齐 `python-dateutil`，统一 psycopg 安装声明。
- 修复 PostgreSQL 准备脚本把探测到的密码传入迁移阶段的问题。
- 清理 `apps/finance/management/__init__.py` 中重复的 management command 实现。

### 演示数据

- `seed_demo --reset` 现在会清理商城订单、订单行、商城账号和商品授权，避免重建残留。
- 演示账龄数据补齐 `0-30`、`31-60`、`61-90`、`91-180`、`181-365`、`365+` 六个桶。
- 回归测试覆盖完整 storefront reset 和六桶账龄。

### 交易与库存

- 销售页保留用户手工改价，不因数量/客户刷新而覆盖；重新取价改为显式操作。
- 最低售价统一按基本单位价格比较，修复 source unit 重复换算。
- 采购页使用成本价而非销售价，并按录入单位显示金额，提交 `source_quantity`。
- 商品单位接口为换算单位返回对应 `cost_price`，同时保留销售价。
- 批次页近效期筛选改为后端过滤并重置分页；新增 `near_expiry` / `expiry_days` 参数。
- 新增前端 `src/utils/transaction.js` 和 Node 原生单测，固定单位换算、金额和边界校验口径。

### 通知与会话

- 通知列表只返回当前租户广播和当前用户通知。
- `mark-read` 不能修改其他用户的私有通知。
- `mark-all-read` 只处理广播和当前用户通知，不再批量改动其他用户状态。
- 普通登录和退出时清理演示只读、商城会话状态；主布局监听 storage 变化，租户/只读标签不再陈旧。

### 开放平台与表单

- 商品新增表单增加必填与正价格校验。
- API Key 管理页显示过期时间并支持确认吊销。
- 前端增加 `npm test`，覆盖交易金额、换算和边界校验。

## 验证结果

```text
backend: 460 passed, 4 skipped
frontend: npm run build ✅
frontend: npm test ✅ (3 tests)
Django check ✅
makemigrations --check --dry-run ✅
bash -n backend/infra/scripts/run_dev.sh ✅
```

4 个跳过用例是 PostgreSQL 并发测试，需要 `config.settings.pgtest` 与可用的 PostgreSQL 实例；本轮未伪造该环境结果。Dockerfile/Compose 配置已通过静态路径与插值检查，完整镜像构建需启动 Docker Desktop。

## 下一轮最高价值项

1. 为用户—租户增加服务端 membership/授权关系，补跨租户切换回归。
2. 把收款/付款分配 service 接入 REST action，并补 API 集成测试。
3. 在 PostgreSQL 上执行并发过账、库存和核销测试，审查 `EXPLAIN ANALYZE`。
4. 补齐前端 Voucher、Channel、StorefrontAdmin 的完整表单校验与分页。
5. 实现审计日志保留/归档策略和正式部署 readiness gate。
…（已截断：原文 64 行 / 1929 字符）
```

#### `C:/Users/12914/Desktop/gj/dealerhub/PROGRESS_AGI_ITERATION_4.md`

```markdown
# dealerhub · AGI 自主迭代报告（第 4 轮 · 并发序列 + N+1 优化）

> **承接**：第 3 轮报告末尾提出的"`_generate_bill_no` 用 count()+1 取序号，并发下有竞态"。
> 本轮坐实并修复，同时扫描出**另外 4 处同类问题**；顺带做性能基线，
> 发现并修复列表接口的 **N+1**（5.3 倍提速）。
> **回归**：SQLite **454 passed** / PostgreSQL **458 passed**，`check` 0 issues。

---

## 一、单号生成竞态（PG 实测坐实）

### 症状

9 个并发建单 → **多个拿到同一单号**：

```
IntegrityError: 重复键违反唯一约束 "sales_bill_tenant_id_bill_no_uniq"
DETAIL: 键值"(tenant_id, bill_no)=(1, XS202609110001)" 已经存在
```

### 根因：`count() + 1` 有两个缺陷

```python
seq = Model.objects.filter(tenant=tenant, bill_no__startswith=head).count() + 1
```

1. **并发撞号**：两个事务同时 `count()` 拿到同一个数 → 生成相同单号
2. **删除后复用**（更隐蔽）：建了 001/002 后删掉 001 → `count()=1` → 下一张又是 002
   → 撞唯一约束（因为 002 已存在）

### 修复：`MAX(序号)+1` + 唯一约束重试

新增共享工具（`apps/core/services.py`）：

```python
next_bill_no(tenant, prefix, model, *, date_str=None, field="bill_no")
    # 扫已有单号取 MAX(序号)，而非 count() —— 删除后不回退

create_with_unique_bill_no(model, *, tenant, prefix, defaults, field="bill_no")
    # 取号 → 尝试创建（保存点包裹）→ 撞唯一约束则换号重试，最多 20 次
```

**为什么用重试而不是锁**：`select_for_update()` **锁不住不存在的行**
（这是第 3 轮修库存竞态时学到的教训）。乐观重试更适合"创建时取名"场景。

**保存点必不可少**：`IntegrityError` 会把外层事务标记为 aborted，
后续任何查询都报 `TransactionManagementError`。

### 修复范围：5 处同类序列

| 位置 | 用途 | 修复方式 |
|---|---|---|
| `sales.services._generate_bill_no` | 销售单 XS | `create_with_unique_bill_no` |
| `purchase.services._generate_bill_no` | 进货单 PB | 同上 |
| `storefront.services._next_order_no` | 商城单 HD | 同上（`field="order_no"`） |
| `channel.services` | 电商转单 SO | `create_with_unique_bill_no` |
| `finance.services._generate_ar_ap_no` | 应收/应付 RC/PY | `next_bill_no` + 凭证号重试 |
| `finance.services` 凭证号 V | 记账凭证 | 保存点 + 换号重试 |

### 验证（3 个场景）

```python
# 1. 并发
test_concurrent_bill_no_generation_unique   # 9 线程并发建单，单号必须全唯一
# 2. 删除后不复用
test_bill_no_not_reused_after_deletion      # 建 001/002/003 → 删 001 → 新单必须是 004
# 3. 空洞不回退
test_bill_no_survives_gap                   # 人工造 0099 → 新单必须是 0100（不填空洞）
```

…（已截断：原文 303 行 / 7825 字符）
```

---

## 4. 相关源码清单

卡内点名过的路径，逐个核实：

（卡内未点名具体文件）

**未解析的线索**（卡里提到但当前树中找不到 —— 可能是路径漂移，接手时按候选或自行搜索确认）：

- `config/settings/pgtest.py` —— 近似候选：C:/Users/12914/Desktop/gj/dealerhub/backend/config/settings/pgtest.py
- `backend/docs/pgtest.md`
- `PROGRESS_D-02.md`

**项目根一级结构**（先看哪儿）：

- `C:/Users/12914/Desktop/gj/dealerhub` → backend/，docs/，frontend/，NEXT_PLAN.md，PLAN.md，PROGRESS.md，PROGRESS_AGI_ITERATION_1.md，PROGRESS_AGI_ITERATION_2.md，PROGRESS_AGI_ITERATION_3.md，PROGRESS_AGI_ITERATION_4.md，PROGRESS_AGI_ITERATION_5.md，PROGRESS_BATCH_A.md，PROGRESS_BATCH_BC.md，PROGRESS_BATCH_D.md…

---

## 5. 基线测试命令与输出

打包时未执行（默认不跑，避免拖慢打包）。接手模型**必须先自己跑一遍**，把开工前的真实状态记进 PROGRESS 的「基线对照」：

- **后端测试**（重）

```bash
cd C:/Users/12914/Desktop/gj/dealerhub/backend && python -m pytest -q
```
  期望：460 passed, 4 skipped（4 个 skipped 是 PG 并发用例，D-02 处理）

- **迁移检查**

```bash
cd C:/Users/12914/Desktop/gj/dealerhub/backend && python manage.py makemigrations --check --dry-run
```
  期望：No changes detected

---

## 6. 收工检查（提交前逐条打勾）

```text
[ ] 第 1 节「验收标准」逐条已满足，且每条都有原始命令输出支撑
[ ] 「边界」段列出的文件一个都没动
[ ] 既有测试没被删/没被跳过（只许更绿）
[ ] 卡外的一律没夹带（顺手发现的 bug 写进 PROGRESS「遗留问题」）
[ ] PROGRESS_D-02.md 已写到项目根，格式符合第 2 节
[ ] 基线对照写了「开工前 → 完工后」两段真实数字
[ ] 未验证项已明确标注（不许虚报）
```

---
*本包由 `PLANNING/tools/handoff_bundle.py` 生成 · 规范见 `PLANNING/03-执行协议.md` §七*