配置功能完善

AGENTS.md

@@ -1,41 +1,46 @@
 # Repository Guidelines
 
 ## Project Structure & Module Organization
-- `app/` contains core backend code (`Http/Controllers`, `Services`, `Models`, `Support`, `Enums`).
-- `routes/web.php` defines HTTP routes; `routes/console.php` holds CLI routes.
-- `resources/views` stores Blade templates, while `resources/js` and `resources/css` are Vite frontend entry points.
-- `database/migrations`, `database/seeders`, and `database/factories` manage schema and seed data.
-- `tests/Feature` covers HTTP/integration behavior; `tests/Unit` covers isolated domain logic.
-- `public/` is web root; generated assets are bundled by Vite.
+- `app/` contains application logic (controllers, models, services).
+- `resources/views/` stores Blade templates for public pages and admin UI.
+- `routes/web.php` defines frontend/admin routes.
+- `database/migrations/` contains schema and data migration files.
+- `tests/Feature/` and `tests/Unit/` hold feature and unit tests.
+- `public/` serves static assets; uploaded files are exposed via `public/storage`.
 
 ## Build, Test, and Development Commands
-- `composer install` — install PHP dependencies.
-- `npm install` — install frontend build tooling.
-- `composer setup` — one-shot project bootstrap (`.env`, key, migration, frontend build).
-- `composer dev` — run local development stack (Laravel server, queue listener, logs, Vite).
-- `php artisan serve` — run backend only.
-- `npm run dev` / `npm run build` — start Vite dev server or build production assets.
-- `composer test` (or `php artisan test`) — clear config and run test suites.
+- `composer install` installs PHP dependencies.
+- `npm install` installs frontend dependencies.
+- `composer run dev` starts local Laravel + Vite development workflow.
+- `php artisan migrate` runs database migrations.
+- `composer test` clears config and runs test suite.
+- `php artisan storage:link` creates the `/storage` public symlink for uploads.
 
 ## Coding Style & Naming Conventions
-- Follow `.editorconfig`: UTF-8, LF, 4-space indent (YAML: 2 spaces), trim trailing whitespace.
-- PHP follows PSR-12 and Laravel conventions; format with `./vendor/bin/pint` before PR.
-- Use PSR-4 namespaces under `App\` with clear suffixes (`*Controller`, `*Request`, `*Service`).
-- Use `StudlyCase` for classes, `camelCase` for methods/variables, and `snake_case` for DB columns/migration names.
+- Follow PSR-12 for PHP; use 4-space indentation.
+- Use strict types (`declare(strict_types=1);`) in PHP files.
+- Class names: `PascalCase`; methods/variables: `camelCase`; constants: `UPPER_SNAKE_CASE`.
+- Blade components should be reusable and grouped by domain (e.g. `resources/views/components/portal/`).
+- Keep controller actions focused; extract reusable logic to private methods/services.
 
 ## Testing Guidelines
-- Framework: PHPUnit 11 via Laravel test runner.
-- Place tests in `tests/Feature` or `tests/Unit`; filename pattern: `*Test.php`.
-- Add/adjust tests for every behavioral change; prioritize Feature tests for route/controller updates.
-- Keep tests deterministic; use factories/seed data and avoid external service dependencies.
+- Write unit tests for pure logic in `tests/Unit/`.
+- Write feature tests for routes/forms/permissions in `tests/Feature/`.
+- Name tests by behavior, e.g. `test_admin_can_update_home_modules`.
+- Run `composer test` before opening a PR.
 
 ## Commit & Pull Request Guidelines
-- Current history uses short summaries (e.g., `init`, `添加 1`); keep commits concise, imperative, and scoped.
-- Prefer format like `feat: add admin article filter` or `fix: validate model score bounds`.
-- PRs should include: purpose, key changes, test evidence (`composer test` output), and related issue IDs.
-- Include screenshots/GIFs for UI changes under `resources/views` or frontend assets.
+- Use clear, scoped commit messages, e.g. `feat(admin): add structured home module settings`.
+- Keep commits focused; avoid mixing unrelated refactors.
+- PRs should include:
+  - What changed and why
+  - Screenshots/GIFs for UI updates
+  - Migration/rollback notes if schema changes
+  - Test coverage notes or manual verification steps
 
 ## Security & Configuration Tips
-- Never commit secrets from `.env`; keep `.env.example` updated for new config keys.
-- Use least-privilege credentials for local/dev databases.
-- Validate and authorize all admin-side inputs using Form Requests and middleware.
+- Never commit `.env` or secrets.
+- Ensure `APP_URL` is correct in each environment.
+- For markdown/image uploads, prefer relative `/storage/...` paths to avoid host lock-in.
+- Validate all admin inputs (URL type, route whitelist, required fields) before persistence.
+