fix: 完善本地热更新开发环境 (#250)

启用本地 PHP 与前端资源热更新，并同步初始化脚本与健康检查。
Co-authored-by: 92451 <924518135@qq.com>
Co-committed-by: 92451 <924518135@qq.com>

LOCAL_DEPLOY.md

@@ -145,7 +145,9 @@ docker compose -f docker-compose.local.yml start
 
 ## 修改后的生效方式
 
-- PHP、配置、模块、页面模板和路由目录已经挂载到容器，通常清理缓存或重启应用即可；
+- PHP、配置、模块、页面模板和路由目录已经挂载到容器，本地 PHP OPcache 会在每次请求检查源码变更，刷新浏览器即可生效；
+- 本地 Compose 会同时启动 `frontend` watcher。修改 `resources/assets` 下的 Vue、JavaScript 或 SCSS 后，Laravel Mix 会通过轮询自动重新编译，Apache 使用共享静态资源卷提供最新文件；浏览器刷新即可看到结果。
+- 如果 watcher 构建失败，查看 `docker compose -f docker-compose.local.yml logs -f frontend`；修复源码后它会继续监听并重新编译。
 - Composer 依赖、前端依赖、Dockerfile 或构建资源发生变化时，重新执行 `bash deploy/local-init.sh`，脚本会自动重建；
 - 修改 `runtime/.env` 后，执行：
 
@@ -154,6 +156,8 @@ docker compose -f docker-compose.local.yml restart app
 docker compose -f docker-compose.local.yml exec -u www-data app php artisan optimize:clear
 ```
 
+停止本地环境时，`app`、`frontend` 和 `mysql` 会一起停止；再次运行初始化脚本会恢复 PHP 服务和前端 watcher。
+
 ## 相关文档
 
 - 新电脑接续指南：[docs/新电脑开发接续指南.md](docs/新电脑开发接续指南.md)

deploy/local-healthcheck.sh

@@ -17,5 +17,5 @@ runuser -u www-data -- php artisan app:ready --quiet
 # Artisan 能先于 Apache 启动完成；必须同时确认真实 HTTP 入口已经响应，
 # 防止初始化脚本在容器“看似健康”时过早访问并得到空响应。
 curl --fail --silent --show-error --max-time 5 \
-    http://127.0.0.1:18088/auth/login \
+    http://127.0.0.1:18088/serviceworker.js \
     >/dev/null

deploy/local-init.sh

@@ -342,7 +342,7 @@ fi
 db_host="$(read_env_value DB_HOST)"
 app_installed="$(read_env_value APP_INSTALLED | tr '[:upper:]' '[:lower:]')"
 
-docker compose -f "$compose_file" up -d --no-build app
+docker compose -f "$compose_file" up -d --no-build app frontend
 
 # 容器可能已经存在而没有重新执行 entrypoint。显式复用同一权限初始化逻辑，
 # 修复历史 root CLI 遗留目录；该命令本身不运行 Artisan。

deploy/php-local.ini

@@ -0,0 +1,3 @@
+; Local bind-mounted PHP source must be revalidated on every request.
+opcache.validate_timestamps=1
+opcache.revalidate_freq=0

docker-compose.local.yml

@@ -37,7 +37,9 @@ services:
     volumes:
       - ./runtime/.env:/var/www/html/.env
       - ./runtime/bills.sqlite:/var/www/html/runtime/bills.sqlite:ro
+      - ./deploy/php-local.ini:/usr/local/etc/php/conf.d/zz-local-dev.ini:ro
       - jiangling_storage:/var/www/html/storage
+      - jiangling_public:/var/www/html/public
       - ./app:/var/www/html/app
       - ./config:/var/www/html/config
       - ./database:/var/www/html/database
@@ -56,6 +58,23 @@ services:
       retries: 10
       start_period: 60s
 
+  # Laravel Mix watcher for local frontend development. The generated assets
+  # live in a shared volume so Apache serves the latest build immediately.
+  frontend:
+    image: jiangling_akaunting:local
+    container_name: jiangling_frontend
+    restart: unless-stopped
+    user: "www-data"
+    working_dir: /var/www/html
+    command: ["npm", "run", "watch-poll"]
+    environment:
+      NPM_CONFIG_UPDATE_NOTIFIER: "false"
+    volumes:
+      - jiangling_public:/var/www/html/public
+      - ./resources:/var/www/html/resources
+    networks:
+      - jiangling_net
+
   mysql:
     image: mysql:8.0
     container_name: jiangling_mysql
@@ -120,6 +139,8 @@ volumes:
     name: jiangling_mysql
   jiangling_clickhouse:
     name: jiangling_clickhouse
+  jiangling_public:
+    name: jiangling_public
 
 networks:
   jiangling_net: