From 65e3717cb9493ef0f67fbcd8ad5d895f26e9d604 Mon Sep 17 00:00:00 2001
From: zensgit <77236085+zensgit@users.noreply.github.com>
Date: Wed, 24 Sep 2025 10:20:49 +0800
Subject: [PATCH 1/8] ci: surface docs-only fast path in summary and wire
 summary to changes job

---
 .github/workflows/ci.yml | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index b3bdd0e8..8382e5bd 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -661,8 +661,10 @@ jobs:
     name: CI Summary
     runs-on: ubuntu-latest
     timeout-minutes: 10
-    needs: [flutter-test, rust-test, rust-core-check, field-compare, rust-api-clippy, cargo-deny, rustfmt-check]
+    needs: [changes, flutter-test, rust-test, rust-core-check, field-compare, rust-api-clippy, cargo-deny, rustfmt-check]
     if: always()
+    env:
+      DOCS_ONLY: ${{ needs.changes.outputs.docs_only }}
 
     steps:
     - name: Download all artifacts
@@ -676,6 +678,9 @@ jobs:
         echo "- Branch: ${{ github.ref_name }}" >> ci-summary.md
         echo "- Commit: ${{ github.sha }}" >> ci-summary.md
         echo "" >> ci-summary.md
+        echo "## Optimization" >> ci-summary.md
+        echo "- Docs-only fast path: ${DOCS_ONLY}" >> ci-summary.md
+        echo "" >> ci-summary.md
 
         echo "## Test Results" >> ci-summary.md
         echo "- Flutter Tests: ${{ needs.flutter-test.result }}" >> ci-summary.md

From 6e89a1c46c3b7f26302eaabe3ffa88e016081a81 Mon Sep 17 00:00:00 2001
From: zensgit <77236085+zensgit@users.noreply.github.com>
Date: Wed, 24 Sep 2025 11:57:33 +0800
Subject: [PATCH 2/8] chore(dev): align docker-compose.dev ports with manager
 (5433/6380/9080); add Makefile hooks target

---
 .pids/api.mode                  | 1 +
 Makefile                        | 6 ++++++
 jive-api/docker-compose.dev.yml | 6 +++---
 3 files changed, 10 insertions(+), 3 deletions(-)
 create mode 100644 .pids/api.mode

diff --git a/.pids/api.mode b/.pids/api.mode
new file mode 100644
index 00000000..38f8e886
--- /dev/null
+++ b/.pids/api.mode
@@ -0,0 +1 @@
+dev
diff --git a/Makefile b/Makefile
index 5f96f818..75a57972 100644
--- a/Makefile
+++ b/Makefile
@@ -159,6 +159,12 @@ api-safe:
 	@echo "启动完整版 API (安全 CORS 模式, 端口 $${API_PORT:-8012})..."
 	@cd jive-api && unset CORS_DEV && API_PORT=$${API_PORT:-8012} cargo run --bin jive-api
 
+# Enable local git hooks to run pre-commit (api-lint)
+.PHONY: hooks
+hooks:
+	@git config core.hooksPath .githooks
+	@echo "Git hooks enabled (pre-commit will run make api-lint)"
+
 # 代码格式化
 format:
 	@echo "格式化 Rust 代码..."
diff --git a/jive-api/docker-compose.dev.yml b/jive-api/docker-compose.dev.yml
index b3b5b9de..279dad72 100644
--- a/jive-api/docker-compose.dev.yml
+++ b/jive-api/docker-compose.dev.yml
@@ -10,7 +10,7 @@ services:
       POSTGRES_DB: jive_money
       POSTGRES_HOST_AUTH_METHOD: md5
     ports:
-      - "15432:5432"  # 修改为15432避免与本地5433冲突
+      - "5433:5432"  # 对齐本地开发默认端口 5433（jive-manager）
     volumes:
       - postgres_dev_data:/var/lib/postgresql/data
       - ./migrations:/docker-entrypoint-initdb.d:ro
@@ -28,7 +28,7 @@ services:
     container_name: jive-redis-dev
     restart: unless-stopped
     ports:
-      - "16379:6379"  # 修改为16379避免与本地6380冲突
+      - "6380:6379"  # 对齐本地开发默认端口 6380（jive-manager）
     volumes:
       - redis_dev_data:/data
     networks:
@@ -69,7 +69,7 @@ services:
     container_name: jive-adminer-dev
     restart: unless-stopped
     ports:
-      - "19080:8080"  # 修改为19080避免与本地8080冲突
+      - "9080:8080"  # 对齐管理脚本使用的 Adminer 端口 9080
     environment:
       ADMINER_DEFAULT_SERVER: postgres
       ADMINER_DESIGN: pepa-linha

From 894a3ae1050e132fb41173d15e171697de039f23 Mon Sep 17 00:00:00 2001
From: zensgit <77236085+zensgit@users.noreply.github.com>
Date: Wed, 24 Sep 2025 12:16:32 +0800
Subject: [PATCH 3/8] chore: remove runtime file .pids/api.mode from VCS

---
 .pids/api.mode | 1 -
 1 file changed, 1 deletion(-)
 delete mode 100644 .pids/api.mode

diff --git a/.pids/api.mode b/.pids/api.mode
deleted file mode 100644
index 38f8e886..00000000
--- a/.pids/api.mode
+++ /dev/null
@@ -1 +0,0 @@
-dev

From 915910981f66b7d7fe92a6d90ce146dc5003e3ce Mon Sep 17 00:00:00 2001
From: zensgit <77236085+zensgit@users.noreply.github.com>
Date: Wed, 24 Sep 2025 12:18:36 +0800
Subject: [PATCH 4/8] ci: short-circuit Flutter job when no Flutter changes;
 reduce flakiness while keeping required checks

---
 .github/workflows/ci.yml | 31 +++++++++++++++++++++----------
 1 file changed, 21 insertions(+), 10 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 282dc7b1..d8029a85 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -31,6 +31,7 @@ jobs:
     runs-on: ubuntu-latest
     outputs:
       docs_only: ${{ steps.out.outputs.docs_only }}
+      flutter_changed: ${{ steps.out.outputs.flutter_changed }}
     steps:
     - uses: actions/checkout@v4
     - name: Paths filter
@@ -48,6 +49,9 @@ jobs:
             - 'PR_DESCRIPTIONS/**'
           code:
             - '!**/*.md'
+          flutter:
+            - 'jive-flutter/**'
+            - 'jive-flutter/pubspec.yaml'
     - name: Set outputs
       id: out
       run: |
@@ -56,6 +60,7 @@ jobs:
         else
           echo "docs_only=false" >> "$GITHUB_OUTPUT"
         fi
+        echo "flutter_changed=${{ steps.filter.outputs.flutter }}" >> "$GITHUB_OUTPUT"
   rustfmt-check:
     name: Rustfmt Check
     runs-on: ubuntu-latest
@@ -122,19 +127,25 @@ jobs:
     needs: [changes]
     env:
       DOCS_ONLY: ${{ needs.changes.outputs.docs_only }}
+      FLUTTER_CHANGED: ${{ needs.changes.outputs.flutter_changed }}
 
     steps:
     - uses: actions/checkout@v4
 
+    - name: No Flutter changes detected (short-circuit)
+      if: env.DOCS_ONLY != 'true' && env.FLUTTER_CHANGED != 'true'
+      run: |
+        echo "No Flutter changes; skipping analysis/tests to keep pipeline efficient."
+
     - name: Setup Flutter
-      if: env.DOCS_ONLY != 'true'
+      if: env.DOCS_ONLY != 'true' && env.FLUTTER_CHANGED == 'true'
       uses: subosito/flutter-action@v2
       with:
         flutter-version: ${{ env.FLUTTER_VERSION }}
         channel: 'stable'
 
     - name: Cache Flutter dependencies
-      if: env.DOCS_ONLY != 'true'
+      if: env.DOCS_ONLY != 'true' && env.FLUTTER_CHANGED == 'true'
       uses: actions/cache@v4
       with:
         path: |
@@ -146,18 +157,18 @@ jobs:
           ${{ runner.os }}-flutter-
 
     - name: Install dependencies
-      if: env.DOCS_ONLY != 'true'
+      if: env.DOCS_ONLY != 'true' && env.FLUTTER_CHANGED == 'true'
       working-directory: jive-flutter
       run: flutter pub get
 
     - name: Generate code (build_runner)
-      if: env.DOCS_ONLY != 'true'
+      if: env.DOCS_ONLY != 'true' && env.FLUTTER_CHANGED == 'true'
       working-directory: jive-flutter
       run: |
         flutter pub run build_runner build --delete-conflicting-outputs || true
 
     - name: Analyze code (non-fatal for now)
-      if: env.DOCS_ONLY != 'true'
+      if: env.DOCS_ONLY != 'true' && env.FLUTTER_CHANGED == 'true'
       working-directory: jive-flutter
       run: |
         set -o pipefail
@@ -165,14 +176,14 @@ jobs:
         flutter analyze --no-fatal-warnings 2>&1 | tee ../flutter-analyze-output.txt || true
 
     - name: Upload analyzer output
-      if: always()
+      if: always() && env.FLUTTER_CHANGED == 'true'
       uses: actions/upload-artifact@v4
       with:
         name: flutter-analyze-output
         path: flutter-analyze-output.txt
 
     - name: Run tests
-      if: env.DOCS_ONLY != 'true'
+      if: env.DOCS_ONLY != 'true' && env.FLUTTER_CHANGED == 'true'
       working-directory: jive-flutter
       run: |
         # Generate machine-readable test results (non-fatal for reporting)
@@ -185,7 +196,7 @@ jobs:
         flutter test test/settings_manual_overrides_navigation_test.dart --machine > ../flutter-widget-manual-overrides.json || true
 
     - name: Upload manual-overrides widget test output
-      if: always()
+      if: always() && env.FLUTTER_CHANGED == 'true'
       uses: actions/upload-artifact@v4
       with:
         name: flutter-manual-overrides-widget
@@ -193,7 +204,7 @@ jobs:
         if-no-files-found: ignore
 
     - name: Generate test report
-      if: always()
+      if: always() && env.FLUTTER_CHANGED == 'true'
       working-directory: jive-flutter
       run: |
         echo "# Flutter Test Report" > ../test-report.md
@@ -217,7 +228,7 @@ jobs:
         fi
 
     - name: Upload test report
-      if: always()
+      if: always() && env.FLUTTER_CHANGED == 'true'
       uses: actions/upload-artifact@v4
       with:
         name: test-report

From 37bc60880667dc090790f72d6d1d3b242d1fd2b8 Mon Sep 17 00:00:00 2001
From: zensgit <77236085+zensgit@users.noreply.github.com>
Date: Wed, 24 Sep 2025 13:35:29 +0800
Subject: [PATCH 5/8] chore: ignore .pids/ runtime dir to avoid accidental
 commits

---
 .gitignore | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.gitignore b/.gitignore
index 02b4d33a..da352938 100644
--- a/.gitignore
+++ b/.gitignore
@@ -59,6 +59,7 @@ Cargo.lock
 # 日志文件
 *.log
 logs/
+/.pids/
 *.pid
 *.seed
 *.pid.lock

From cf09a1a8d01f019ef4b7541f446053f39f026634 Mon Sep 17 00:00:00 2001
From: zensgit <77236085+zensgit@users.noreply.github.com>
Date: Wed, 24 Sep 2025 13:36:20 +0800
Subject: [PATCH 6/8] ci: make field-compare resilient to missing Flutter
 artifacts; gate compare on flutter_changed

---
 .github/workflows/ci.yml | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index d8029a85..c3020bd3 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -549,7 +549,9 @@ jobs:
     name: Field Comparison Check
     runs-on: ubuntu-latest
     timeout-minutes: 10
-    needs: [flutter-test, rust-test]
+    needs: [changes, flutter-test, rust-test]
+    env:
+      FLUTTER_CHANGED: ${{ needs.changes.outputs.flutter_changed }}
 
     steps:
     - uses: actions/checkout@v4
@@ -559,15 +561,17 @@ jobs:
       with:
         name: test-report
         path: .
+        if-no-files-found: ignore
 
     - name: Download Flutter analyzer output
       uses: actions/download-artifact@v4
       with:
         name: flutter-analyze-output
         path: .
+        if-no-files-found: ignore
 
     - name: Upload analyzer output for comparison
-      if: always()
+      if: always() && env.FLUTTER_CHANGED == 'true'
       uses: actions/upload-artifact@v4
       with:
         name: flutter-analyze-output-comparison
@@ -579,6 +583,7 @@ jobs:
         sudo apt-get install -y jq
 
     - name: Compare Flutter and Rust fields
+      if: env.FLUTTER_CHANGED == 'true'
       run: |
         echo "# Field Comparison Report" > field-compare-report.md
         echo "## Flutter vs Rust Model Comparison" >> field-compare-report.md
@@ -617,7 +622,7 @@ jobs:
         fi
 
     - name: Upload field comparison report
-      if: always()
+      if: always() && env.FLUTTER_CHANGED == 'true'
       uses: actions/upload-artifact@v4
       with:
         name: field-compare-report

From 630b46e1ee7d5195930d57854de7b83f33b8c913 Mon Sep 17 00:00:00 2001
From: zensgit <77236085+zensgit@users.noreply.github.com>
Date: Wed, 24 Sep 2025 13:40:04 +0800
Subject: [PATCH 7/8] ci: add full_run input; gate heavy jobs on manual
 dispatch; include event in concurrency key

---
 .github/workflows/ci.yml | 27 ++++++++++++++++-----------
 1 file changed, 16 insertions(+), 11 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index c3020bd3..941ef346 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -12,6 +12,11 @@ on:
         description: 'Enable debug mode'
         required: false
         default: false
+      full_run:
+        type: boolean
+        description: 'Run all heavy jobs on manual dispatch'
+        required: false
+        default: false
 
 permissions:
   contents: read
@@ -22,7 +27,7 @@ env:
   RUST_VERSION: '1.89.0'
 
 concurrency:
-  group: core-ci-${{ github.ref }}
+  group: core-ci-${{ github.ref }}-${{ github.event_name }}
   cancel-in-progress: true
 
 jobs:
@@ -78,13 +83,13 @@ jobs:
         toolchain: ${{ env.RUST_VERSION }}
         components: rustfmt
     - name: Check formatting (jive-api)
-      if: env.DOCS_ONLY != 'true'
+      if: env.DOCS_ONLY != 'true' && (github.event_name != 'workflow_dispatch' || inputs.full_run == 'true')
       working-directory: jive-api
       run: |
         cargo fmt --all -- --check
 
     - name: Check formatting (jive-core)
-      if: env.DOCS_ONLY != 'true'
+      if: env.DOCS_ONLY != 'true' && (github.event_name != 'workflow_dispatch' || inputs.full_run == 'true')
       working-directory: jive-core
       run: |
         cargo fmt --all -- --check
@@ -101,13 +106,13 @@ jobs:
     steps:
     - uses: actions/checkout@v4
     - name: Install cargo-deny
-      if: env.DOCS_ONLY != 'true'
+      if: env.DOCS_ONLY != 'true' && (github.event_name != 'workflow_dispatch' || inputs.full_run == 'true')
       run: |
         curl -sSfL https://github.com/EmbarkStudios/cargo-deny/releases/download/0.14.24/cargo-deny-0.14.24-x86_64-unknown-linux-musl.tar.gz | tar xz
         sudo mv cargo-deny*/cargo-deny /usr/local/bin/cargo-deny
         cargo-deny --version
     - name: Run cargo-deny (API)
-      if: env.DOCS_ONLY != 'true'
+      if: env.DOCS_ONLY != 'true' && (github.event_name != 'workflow_dispatch' || inputs.full_run == 'true')
       working-directory: jive-api
       run: |
         set -o pipefail
@@ -138,14 +143,14 @@ jobs:
         echo "No Flutter changes; skipping analysis/tests to keep pipeline efficient."
 
     - name: Setup Flutter
-      if: env.DOCS_ONLY != 'true' && env.FLUTTER_CHANGED == 'true'
+      if: env.DOCS_ONLY != 'true' && env.FLUTTER_CHANGED == 'true' && (github.event_name != 'workflow_dispatch' || inputs.full_run == 'true')
       uses: subosito/flutter-action@v2
       with:
         flutter-version: ${{ env.FLUTTER_VERSION }}
         channel: 'stable'
 
     - name: Cache Flutter dependencies
-      if: env.DOCS_ONLY != 'true' && env.FLUTTER_CHANGED == 'true'
+      if: env.DOCS_ONLY != 'true' && env.FLUTTER_CHANGED == 'true' && (github.event_name != 'workflow_dispatch' || inputs.full_run == 'true')
       uses: actions/cache@v4
       with:
         path: |
@@ -157,18 +162,18 @@ jobs:
           ${{ runner.os }}-flutter-
 
     - name: Install dependencies
-      if: env.DOCS_ONLY != 'true' && env.FLUTTER_CHANGED == 'true'
+      if: env.DOCS_ONLY != 'true' && env.FLUTTER_CHANGED == 'true' && (github.event_name != 'workflow_dispatch' || inputs.full_run == 'true')
       working-directory: jive-flutter
       run: flutter pub get
 
     - name: Generate code (build_runner)
-      if: env.DOCS_ONLY != 'true' && env.FLUTTER_CHANGED == 'true'
+      if: env.DOCS_ONLY != 'true' && env.FLUTTER_CHANGED == 'true' && (github.event_name != 'workflow_dispatch' || inputs.full_run == 'true')
       working-directory: jive-flutter
       run: |
         flutter pub run build_runner build --delete-conflicting-outputs || true
 
     - name: Analyze code (non-fatal for now)
-      if: env.DOCS_ONLY != 'true' && env.FLUTTER_CHANGED == 'true'
+      if: env.DOCS_ONLY != 'true' && env.FLUTTER_CHANGED == 'true' && (github.event_name != 'workflow_dispatch' || inputs.full_run == 'true')
       working-directory: jive-flutter
       run: |
         set -o pipefail
@@ -183,7 +188,7 @@ jobs:
         path: flutter-analyze-output.txt
 
     - name: Run tests
-      if: env.DOCS_ONLY != 'true' && env.FLUTTER_CHANGED == 'true'
+      if: env.DOCS_ONLY != 'true' && env.FLUTTER_CHANGED == 'true' && (github.event_name != 'workflow_dispatch' || inputs.full_run == 'true')
       working-directory: jive-flutter
       run: |
         # Generate machine-readable test results (non-fatal for reporting)

From 5228eb8cb31f4128acf64a82ba78ed12473108aa Mon Sep 17 00:00:00 2001
From: zensgit <77236085+zensgit@users.noreply.github.com>
Date: Wed, 24 Sep 2025 14:33:08 +0800
Subject: [PATCH 8/8] fix(ci): skip Field Comparison Check when Flutter
 unchanged

- Add conditional execution to field-compare job
- Only run when flutter_changed == 'true'
- Fixes artifact not found error when Flutter tests are skipped
---
 .github/workflows/ci.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 941ef346..6f8732d0 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -555,6 +555,7 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     needs: [changes, flutter-test, rust-test]
+    if: needs.changes.outputs.flutter_changed == 'true'
     env:
       FLUTTER_CHANGED: ${{ needs.changes.outputs.flutter_changed }}