chore: split dev and production deployment env

README.md

@@ -44,11 +44,18 @@
 ├── AGENTS.md                       # Codex/Agent 入口指令，当前指向 RTK.md
 ├── RTK.md                          # 项目协作规则和开发约定
 ├── docs/
-│   └── API.md                      # 前端对接接口文档
+│   ├── API.md                      # 前端对接接口文档
+│   └── ENVIRONMENT_DEPLOYMENT.md   # 测试/生产环境拆分与 Jenkins 规则
 ├── deploy/
+│   ├── env/
+│   │   ├── test.env.example        # 测试环境变量示例，不包含真实密码
+│   │   └── production.env.example  # 生产环境变量示例，不包含真实密码
+│   ├── jenkins/
+│   │   └── deploy-backend.sh       # Jenkins 后端部署脚本
 │   └── server/
-│       ├── create-env.sh              # 在服务器生成真实 .env 和 .env.production
-│       └── docker-compose.mysql.yml   # 服务器 MySQL Compose 模板
+│       ├── create-env.sh              # 在服务器生成测试/生产真实环境变量
+│       ├── docker-compose.mysql.test.yml       # 测试 MySQL Compose 模板
+│       └── docker-compose.mysql.production.yml # 生产 MySQL Compose 模板
 ├── migrations/                 # 数据库迁移 SQL
 │   ├── 001_initial_schema.sql   # 创建基础表结构
 │   ├── 002_seed_demo_data.sql   # 初始化演示门店和角色
@@ -78,6 +85,7 @@
 │   │   └── tasks/               # 任务后台管理和员工端任务模块
 │   └── shared/                  # 通用响应结构和业务错误
 ├── docker-compose.yml           # 本地 MySQL
+├── Jenkinsfile                  # Jenkins 测试自动部署、生产手动 Tag 部署规则
 ├── package.json
 ├── pnpm-lock.yaml
 ├── README.md
@@ -95,7 +103,10 @@
 | `AGENTS.md` | Agent 工具读取的入口文件，当前通过 `@RTK.md` 引入项目规则。 |
 | `RTK.md` | 本项目的协作规则，例如使用中文说明、保持分层、改目录时同步 README。 |
 | `docs/API.md` | 面向前端对接的完整接口文档，包含认证、权限、字段约束、示例请求响应和错误码。 |
-| `deploy/server/` | 服务器部署辅助文件。`create-env.sh` 在服务器本地生成真实环境变量，`docker-compose.mysql.yml` 用于启动服务器 MySQL。 |
+| `docs/ENVIRONMENT_DEPLOYMENT.md` | 测试/生产环境拆分、Jenkins 参数、Tag 发布和服务器路径约定。 |
+| `deploy/env/` | 测试/生产环境变量示例，只给字段结构，不提交真实密码。 |
+| `deploy/jenkins/` | Jenkins 部署脚本。当前 `deploy-backend.sh` 会按环境发布到独立目录。 |
+| `deploy/server/` | 服务器部署辅助文件。`create-env.sh` 在服务器本地生成测试/生产真实环境变量，Compose 模板分别启动测试和生产 MySQL。 |
 | `migrations/` | 数据库迁移目录。所有建表、改表、初始化基础数据的 SQL 都放在这里。 |
 | `src/app.ts` | 创建 Fastify 应用，注册路由，处理健康检查和全局错误。 |
 | `src/server.ts` | 真正启动 HTTP 服务，监听端口，并处理优雅停机。 |
@@ -113,6 +124,7 @@
 | `src/modules/tasks/` | 任务模块，负责后台任务管理、员工端任务处理和任务事件日志。 |
 | `src/shared/` | 跨模块复用的响应结构和业务错误类型。 |
 | `docker-compose.yml` | 本地开发用 MySQL 容器配置。 |
+| `Jenkinsfile` | 流水线入口。`develop` 合并自动部署测试环境；生产环境只能手动选择 Tag 部署。 |
 | `package.json` | 项目信息、依赖和常用脚本；脚本会读取现有 `.env.development`。 |
 | `pnpm-lock.yaml` | pnpm 锁文件，保证依赖版本一致。 |
 | `tsconfig.json` | TypeScript 编译配置。 |
@@ -227,55 +239,77 @@ curl http://localhost:3500/health
 
 服务器部署时不要直接使用本地 `.env.development`，也不要把本机 `.env.*` 打进部署包。真实密码只应该在服务器本地生成和保存。
 
+当前服务器按测试环境和生产环境拆分，默认路径如下：
+
+| 环境 | 应用目录 | 默认端口 | 数据目录 |
+| --- | --- | --- | --- |
+| 测试环境 | `/srv/www/test/access-manage` | `3501` | `/srv/data/test/access-manage/mysql` |
+| 生产环境 | `/srv/www/production/access-manage` | `3500` | `/srv/data/production/access-manage/mysql` |
+
 1. 生成服务器真实环境变量：
 
 ```bash
-cd /srv/www/access-manage
-bash deploy/server/create-env.sh /srv/www/access-manage
+cd /srv/www/test/access-manage
+bash deploy/server/create-env.sh /srv/www/test/access-manage test
+
+cd /srv/www/production/access-manage
+bash deploy/server/create-env.sh /srv/www/production/access-manage production
 ```
 
-这个脚本会生成两个不提交到仓库的文件：
+这个脚本会生成不提交到仓库的文件：
 
 ```text
-/srv/www/access-manage/.env
-/srv/www/access-manage/.env.production
+/srv/www/test/access-manage/.env.test.mysql
+/srv/www/test/access-manage/.env.test
+/srv/www/production/access-manage/.env.production.mysql
+/srv/www/production/access-manage/.env.production
 ```
 
-其中 `.env` 给 MySQL 容器使用，`.env.production` 给 Node 后端使用。如果 `.env` 已经存在，脚本会读取现有 `MYSQL_PASSWORD`，只补 `.env.production`；如果 `.env.production` 已经存在，脚本会拒绝覆盖。
+其中 `.env.*.mysql` 给 MySQL 容器使用，`.env.test` / `.env.production` 给 Node 后端使用。如果应用 env 已存在，脚本会拒绝覆盖。
 
 2. 启动服务器 MySQL：
 
 ```bash
-docker-compose -f deploy/server/docker-compose.mysql.yml up -d mysql
+cd /srv/www/test/access-manage
+docker-compose --env-file .env.test.mysql -f deploy/server/docker-compose.mysql.test.yml up -d mysql
+
+cd /srv/www/production/access-manage
+docker-compose --env-file .env.production.mysql -f deploy/server/docker-compose.mysql.production.yml up -d mysql
 ```
 
-服务器模板会把 MySQL 数据持久化到：
+服务器模板会把 MySQL 数据分别持久化到：
 
 ```text
-/srv/data/access-manage/mysql
+/srv/data/test/access-manage/mysql
+/srv/data/production/access-manage/mysql
 ```
 
 当前模板默认后端通过服务器本机端口连接 MySQL：
 
 ```env
 DB_HOST=127.0.0.1
-DB_PORT=3307
+DB_PORT=3308 # 测试
+DB_PORT=3307 # 生产
 ```
 
 3. 安装生产依赖、迁移、启动：
 
 ```bash
 pnpm install --prod --frozen-lockfile
+pnpm db:migrate:test
+pnpm start:test
+
 pnpm db:migrate:prod
 pnpm start:prod
 ```
 
-`pnpm build:dev` 和 `pnpm build:pro` 只生成编译后的 `dist/` 目录。服务器上不需要再执行 `pnpm build`。
+`pnpm build:dev`、`pnpm build:test` 和 `pnpm build:pro` 只生成编译后的 `dist/` 目录。服务器上不需要再执行 `pnpm build`。
 
 4. 健康检查：
 
 ```bash
-curl http://127.0.0.1:3500/health
+curl http://127.0.0.1:3501/health # 测试
+curl http://127.0.0.1:3500/health # 生产
 ```
 
 只有返回里出现 `database: "up"`，才代表后端服务和 MySQL 都连通。
@@ -288,7 +322,15 @@ curl http://127.0.0.1:3500/health
 pnpm build:dev
 ```
 
-命令执行完成后会得到最新的 `dist/`。如果需要压缩上传，由部署者手动选择要打包的文件；正式生产构建时可以执行 `pnpm build:pro`。
+命令执行完成后会得到最新的 `dist/`。如果需要压缩上传，由部署者手动选择要打包的文件；测试构建可执行 `pnpm build:test`，正式生产构建时执行 `pnpm build:pro`。
+
+## Jenkins 环境规则
+
+流水线规则见 [docs/ENVIRONMENT_DEPLOYMENT.md](./docs/ENVIRONMENT_DEPLOYMENT.md)。
+
+- 测试环境：`develop` 合并后自动触发，部署到 `/srv/www/test/access-manage/current`。
+- 生产环境：禁止代码合并自动触发，只能在 Jenkins 手动选择 `DEPLOY_ENV=production` 并填写 Gitea 项目 Tag。
+- 生产部署会先 checkout 到 `RELEASE_TAG` 对应的提交，再构建和部署。
 
 ## package.json 脚本说明
 
@@ -299,11 +341,14 @@ pnpm build:dev
 | `pnpm dev`        | 使用现有 `.env.development` 启动开发服务，并通过 `tsx watch` 监听代码变化。 | 日常开发接口时使用。                               |
 | `pnpm build`      | 使用 `tsc` 编译 TypeScript，输出到 `dist/`。                            | 准备运行编译产物或发布前验证时使用。               |
 | `pnpm build:dev` | 清空旧 `dist/`，再执行 `pnpm build` 生成新的 `dist/`。 | 准备开发/测试服务器部署产物时使用。 |
+| `pnpm build:test` | 清空旧 `dist/`，再执行 `pnpm build` 生成新的 `dist/`。 | Jenkins 测试环境构建时使用。 |
 | `pnpm build:pro` | 清空旧 `dist/`，再执行 `pnpm build` 生成新的 `dist/`。 | 准备正式生产部署产物时使用。 |
 | `pnpm start`      | 使用现有 `.env.development` 运行 `dist/server.js`。                         | 已经执行过 `pnpm build` 后，用编译产物启动服务。 |
+| `pnpm start:test` | 使用 `.env.test` 运行 `dist/server.js`。                              | 服务器测试环境启动编译产物时使用。                 |
 | `pnpm start:prod` | 使用 `.env.production` 运行 `dist/server.js`。                              | 服务器生产环境启动编译产物时使用。                 |
 | `pnpm typecheck`  | 执行 `tsc --noEmit`，只检查类型，不生成文件。                             | 改 TypeScript 代码后快速确认类型是否正确。         |
 | `pnpm db:migrate` | 使用现有 `.env.development` 运行 `src/db/migrate.ts`，按顺序执行 `migrations/*.sql`。 | 第一次启动项目、拉到新迁移、改数据库结构后使用。   |
+| `pnpm db:migrate:test` | 使用 `.env.test` 运行 `dist/db/migrate.js`，按顺序执行 `migrations/*.sql`。 | 服务器测试环境建表、升级表结构或初始化基础数据时使用。 |
 | `pnpm db:migrate:prod` | 使用 `.env.production` 运行 `dist/db/migrate.js`，按顺序执行 `migrations/*.sql`。 | 服务器生产环境建表、升级表结构或初始化基础数据时使用。 |
 | `pnpm db:shell`   | 进入 Docker 容器里的 MySQL 命令行。                                         | 需要手动查看表结构或查询数据时使用。               |
 | `pnpm mysql:up`   | 启动本地 MySQL 容器。                                                       | 开发前先启动数据库。                               |