---
description: 本地开发启动/停止约定：工作目录、单实例、按端口杀进程树，避免孤儿进程与头像 404
alwaysApply: true
---

# 本地开发环境

## 后端启动（必须遵守）

规范命令与 `start.bat` / `start.sh` 一致：

```
cd backend
go run ./cmd/jiang13
```

- 数据目录**只有** `backend/data/`（头像在 `backend/data/uploads/avatars/`）
- 配置文件是 `backend/app.ini`，不是仓库根、也不是 `cmd/jiang13/`
- **禁止**在仓库根、`backend/cmd/jiang13/` 或其他目录执行 `go run`（会另建一套 data，DB 里头像 URL 对不上文件）
- **禁止**同时跑两个后端。启动前若 `:3001` 已在听，沿用现有进程，或先停再启；不要再开一个
- 启动日志必须含 `workPath=.../backend` 且 `dataDir=.../backend/data`。若不是，立刻停掉重来
- 覆盖工作目录只用环境变量 `JIANG13_WORK_PATH`（指向 `backend/`）

## 前端

```
cd frontend
npm.cmd run dev
```

`:3000` 把 `/uploads` rewrite 到 `:3001`。头像 404 先查后端 `dataDir`，不要改前端。

## 进程生命周期（Windows 孤儿进程）

根因：Cursor/agent 停掉的往往是 **shell 父进程**；`go run` / `npm` 拉起的 `go.exe`/`node.exe`/编译产物仍在听端口，任务管理器里才看得见。

### Agent 必须遵守

1. **先查再启**：启动前用端口探测；`:3000`/`:3001` 已在听 → **复用**，禁止再开一份
2. **停服务优先跑脚本**（仓库根）：
   - Windows：`stop.bat`（内部调用 `stop.ps1`）
   - Unix：`./stop.sh`
3. **禁止**只依赖「结束终端 / Ctrl+C / 杀 shell PID」当作已停干净
4. 无脚本时，Windows 用 **按端口 + 进程树** 清理（PowerShell）：
   ```powershell
   foreach ($port in 3000,3001) {
     Get-NetTCPConnection -LocalPort $port -State Listen -EA SilentlyContinue |
       Select-Object -ExpandProperty OwningProcess -Unique |
       ForEach-Object { if ($_ -gt 0) { taskkill /T /F /PID $_ } }
   }
   ```
5. 声称已停止后，**再查一次**端口是否空闲；仍占用则继续 `/T` 杀树，勿让用户去任务管理器
6. 默认**不动** Docker Postgres；用户要停库再 `docker compose down`
7. 会话结束前若本会话启动过前后端：主动清理或明确告知用户执行 `stop.bat`

### 用户侧

双击 / 运行仓库根 `stop.bat`（或 `./stop.sh`）即可，无需开任务管理器。

### Windows `.bat` 编码

`cmd.exe` 按系统 ANSI（中文 Windows 多为 GBK）解析 `.bat`，**禁止**在 `.bat` 里写 UTF-8 中文（会乱码断行，出现 `'/' 不是内部或外部命令`）。`.bat` 保持 ASCII；中文提示放 `stop.ps1`（UTF-8 BOM）或英文。

## 遗留目录

`backend/cmd/jiang13/data/` 是错误 cwd 的产物，禁止当数据源。发现后把 `uploads/` 合并进 `backend/data/uploads/`，再删遗留目录。

## 官方运行时（与本地开发分开）

生产交付在 `deploy/`（Next standalone + Go + Postgres，反代自备），契约见 `deploy/CONTRACT.md`。仓库根 `docker-compose.yml` **只**给本地 Postgres 用。禁止把 `start.bat` / `go run` / `npm run dev` 改成必须打应用镜像；禁止对开发库执行 `deploy` 目录的 `docker compose down -v`。