# Stack 模式目录规范

本目录用于维护"模式化生效文件"，由 `php think admin:stack:mode` 命令读取并覆盖到仓库根目录。

## 目录结构

- `source/stack/stack.json`：全局清单，定义 `default_mode`、`managed_files`、`modes` 元数据。
- `source/stack/default/`：默认行为基线目录（`php think run`，纯 PHP 内置服务器运行）。
- `source/stack/{mode}/`：具体模式目录，按"仓库相对路径"放置文件。

## default 目录规则（强约束）

- `source/stack/default/` 必须与代码库默认行为一致。
- 默认行为为 `php think run`（ThinkPHP 内置服务器），不依赖 Docker。
- 当默认行为文件变更时（如 `.gitea/workflows/build-and-deploy.yml`），必须同步更新 `default` 目录对应文件。
- 该规则通过目录维护规范与代码评审保障，不作为每次切换命令的运行时阻断条件。

## 模式覆盖规则

- 仅允许覆盖 `stack.json` 的 `managed_files` 中声明的文件。
- 切换时按以下优先级解析最终文件：
  - 目标模式提供某文件：使用目标模式文件；
  - 目标模式未提供某文件：回落使用 `default` 目录对应文件；
  - 两者均未提供：从根目录删除该文件（带备份，可回滚）。

## 可用模式

| 模式 | 说明 |
|------|------|
| `default` | 默认基线，`php think run` 运行，无 Docker 文件 |
| `docker-serve` | Docker 部署模式（基于基础镜像，nginx+php-fpm） |
| `full` | 全量构建模式（兼容历史行为，从 PHP 镜像从头构建） |
| `base-build` | 基础镜像 + 应用构建模式（author_only） |
| `docker-dev` | Docker 开发模式（nginx+php-fpm+MySQL+Redis+phpMyAdmin+Xdebug） |
| `docker-dev-sync` | Docker 开发模式 - Windows I/O 优化（rsync 定时同步，避免 bind mount 慢速问题） |

## 基础镜像说明

- `base-build/docker/Dockerfile.base` 为基础镜像构建文件，默认标记为作者维护范围（`author_only=true`）。
- 推荐标签策略：`latest` + 时间戳（如 `20260424120000`）。