diff --git a/.agents/rules/chat.md b/.agents/rules/chat.md deleted file mode 100644 index d4ec8a5..0000000 --- a/.agents/rules/chat.md +++ /dev/null @@ -1,150 +0,0 @@ ---- -trigger: always_on ---- - -> **技术栈**:Laravel 12 · PHP 8.4 · Laravel Reverb (WebSocket) · Redis · MySQL 8.0 · Laravel Horizon -> **原项目**:`/Users/pllx/Web/chat/hp0709`(VBScript ASP + MS Access 聊天室) -> **目标域名**:`http://chatroom.test`(Herd 自动配置) - ---- - -## 一、环境版本要求 - -| 组件 | 版本 | -| --------------------- | -------------------------- | -| **PHP** | 8.4.5+ | -| **Laravel Framework** | v12.x | -| **Laravel Reverb** | latest(WebSocket 服务器) | -| **Laravel Horizon** | v5(Redis 队列可视化管理) | -| **PHPUnit** | v11(测试框架) | -| **Node.js** | 20.x LTS | -| **MySQL** | 8.0+ | -| **Redis** | 7.x | - ---- - -## 二、代码规范(强制执行) - -### 2.1 Laravel Pint 格式化 - -```bash -# 提交代码前必须运行,修复格式问题 -vendor/bin/pint --dirty - -# 检查格式问题(不修复) -vendor/bin/pint --test - -# 格式化整个项目 -vendor/bin/pint -``` - -### 2.2 PHP 8.4 类型系统(必须遵守) - -```php -// ✅ 正确:构造函数属性提升 (Constructor Property Promotion) -class ChatController extends Controller -{ - public function __construct( - private readonly ChatStateService $chatState, - private readonly MessageFilterService $filter, - ) {} -} - -// ❌ 错误:不允许无参空构造函数 -class SomeClass -{ - public function __construct() {} // 禁止! -} - -// ✅ 正确:显式返回类型 + 参数类型提示 -public function send(SendMessageRequest $request): JsonResponse -{ - // ... -} - -// ✅ 正确:使用 PHP 8.4 新特性 -// 联合类型 -public function findUser(int|string $id): User|null {} - -// readonly 属性 -class MessageDto -{ - public function __construct( - public readonly string $content, - public readonly string $fromUser, - public readonly int $roomId, - ) {} -} -``` - -### 2.3 Laravel 12 中间件配置(重要) - -> [!IMPORTANT] -> Laravel 12 已废弃 `Kernel.php`,中间件在 `bootstrap/app.php` 中配置。 - -```php -// bootstrap/app.php -return Application::configure(basePath: dirname(__DIR__)) - ->withRouting( - web: __DIR__.'/../routes/web.php', - api: __DIR__.'/../routes/api.php', // API 路由 - channels: __DIR__.'/../routes/channels.php', // WebSocket 频道 - commands: __DIR__.'/../routes/console.php', - health: '/up', - ) - ->withMiddleware(function (Middleware $middleware): void { - // 注册聊天室登录验证中间件 - $middleware->alias([ - 'chat.auth' => \App\Http\Middleware\ChatAuthenticate::class, - 'chat.level' => \App\Http\Middleware\LevelRequired::class, - ]); - - // Session 中间件(Web 路由自动携带) - $middleware->web(append: [ - \App\Http\Middleware\HandleInertiaRequests::class, - ]); - }) - ->withExceptions(function (Exceptions $exceptions): void { - // - })->create(); -``` - -### 2.4 中文注释规范(每个文件必须) - -```php -redis->hset("room:{$roomId}:users", $username, json_encode($userInfo)); - } -} -``` - -### 2.5 迁移文件注意事项 - -同时新建多个迁移文件时,要注意 是否有关联主键问题,主键所在表要先创建,所以迁移文件名称 要比被调用表文件名的靠前,否则执行迁移时会报错; diff --git a/.agents/skills/tailwindcss-development/SKILL.md b/.agents/skills/tailwindcss-development/SKILL.md deleted file mode 100644 index 21a7e46..0000000 --- a/.agents/skills/tailwindcss-development/SKILL.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -name: tailwindcss-development -description: "Styles applications using Tailwind CSS v4 utilities. Activates when adding styles, restyling components, working with gradients, spacing, layout, flex, grid, responsive design, dark mode, colors, typography, or borders; or when the user mentions CSS, styling, classes, Tailwind, restyle, hero section, cards, buttons, or any visual/UI changes." -license: MIT -metadata: - author: laravel ---- - -# Tailwind CSS Development - -## When to Apply - -Activate this skill when: - -- Adding styles to components or pages -- Working with responsive design -- Implementing dark mode -- Extracting repeated patterns into components -- Debugging spacing or layout issues - -## Documentation - -Use `search-docs` for detailed Tailwind CSS v4 patterns and documentation. - -## Basic Usage - -- Use Tailwind CSS classes to style HTML. Check and follow existing Tailwind conventions in the project before introducing new patterns. -- Offer to extract repeated patterns into components that match the project's conventions (e.g., Blade, JSX, Vue). -- Consider class placement, order, priority, and defaults. Remove redundant classes, add classes to parent or child elements carefully to reduce repetition, and group elements logically. - -## Tailwind CSS v4 Specifics - -- Always use Tailwind CSS v4 and avoid deprecated utilities. -- `corePlugins` is not supported in Tailwind v4. - -### CSS-First Configuration - -In Tailwind v4, configuration is CSS-first using the `@theme` directive — no separate `tailwind.config.js` file is needed: - - -```css -@theme { - --color-brand: oklch(0.72 0.11 178); -} -``` - -### Import Syntax - -In Tailwind v4, import Tailwind with a regular CSS `@import` statement instead of the `@tailwind` directives used in v3: - - -```diff -- @tailwind base; -- @tailwind components; -- @tailwind utilities; -+ @import "tailwindcss"; -``` - -### Replaced Utilities - -Tailwind v4 removed deprecated utilities. Use the replacements shown below. Opacity values remain numeric. - -| Deprecated | Replacement | -|------------|-------------| -| bg-opacity-* | bg-black/* | -| text-opacity-* | text-black/* | -| border-opacity-* | border-black/* | -| divide-opacity-* | divide-black/* | -| ring-opacity-* | ring-black/* | -| placeholder-opacity-* | placeholder-black/* | -| flex-shrink-* | shrink-* | -| flex-grow-* | grow-* | -| overflow-ellipsis | text-ellipsis | -| decoration-slice | box-decoration-slice | -| decoration-clone | box-decoration-clone | - -## Spacing - -Use `gap` utilities instead of margins for spacing between siblings: - - -```html -
-
Item 1
-
Item 2
-
-``` - -## Dark Mode - -If existing pages and components support dark mode, new pages and components must support it the same way, typically using the `dark:` variant: - - -```html -
- Content adapts to color scheme -
-``` - -## Common Patterns - -### Flexbox Layout - - -```html -
-
Left content
-
Right content
-
-``` - -### Grid Layout - - -```html -
-
Card 1
-
Card 2
-
Card 3
-
-``` - -## Common Pitfalls - -- Using deprecated v3 utilities (bg-opacity-*, flex-shrink-*, etc.) -- Using `@tailwind` directives instead of `@import "tailwindcss"` -- Trying to use `tailwind.config.js` instead of CSS `@theme` directive -- Using margins for spacing between siblings instead of gap utilities -- Forgetting to add dark mode variants when the project uses dark mode \ No newline at end of file diff --git a/.codex/environments/environment-2.toml b/.codex/environments/environment-2.toml deleted file mode 100644 index af827c1..0000000 --- a/.codex/environments/environment-2.toml +++ /dev/null @@ -1,12 +0,0 @@ -# THIS IS AUTOGENERATED. DO NOT EDIT MANUALLY -version = 1 -name = "chatroom" - -[setup] -script = "" - -[cleanup] -script = ''' -php artisan reverb:start -php artisan horizon -''' diff --git a/.codex/environments/environment.toml b/.codex/environments/environment.toml deleted file mode 100644 index 9847506..0000000 --- a/.codex/environments/environment.toml +++ /dev/null @@ -1,14 +0,0 @@ -# THIS IS AUTOGENERATED. DO NOT EDIT MANUALLY -version = 1 -name = "chatroom" - -[setup] -script = "" - -[[actions]] -name = "启动ws" -icon = "tool" -command = ''' -php artisan reverb:start -php artisan horizon -''' diff --git a/.gemini/settings.json b/.gemini/settings.json deleted file mode 100644 index a561af2..0000000 --- a/.gemini/settings.json +++ /dev/null @@ -1,20 +0,0 @@ -{ - "mcpServers": { - "laravel-boost": { - "command": "php", - "args": [ - "artisan", - "boost:mcp" - ] - }, - "herd": { - "command": "php", - "args": [ - "/Applications/Herd.app/Contents/Resources/herd-mcp.phar" - ], - "env": { - "SITE_PATH": "/Users/pllx/Web/Herd/chatroom" - } - } - } -} \ No newline at end of file diff --git a/.github/skills/tailwindcss-development/SKILL.md b/.github/skills/tailwindcss-development/SKILL.md deleted file mode 100644 index 21a7e46..0000000 --- a/.github/skills/tailwindcss-development/SKILL.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -name: tailwindcss-development -description: "Styles applications using Tailwind CSS v4 utilities. Activates when adding styles, restyling components, working with gradients, spacing, layout, flex, grid, responsive design, dark mode, colors, typography, or borders; or when the user mentions CSS, styling, classes, Tailwind, restyle, hero section, cards, buttons, or any visual/UI changes." -license: MIT -metadata: - author: laravel ---- - -# Tailwind CSS Development - -## When to Apply - -Activate this skill when: - -- Adding styles to components or pages -- Working with responsive design -- Implementing dark mode -- Extracting repeated patterns into components -- Debugging spacing or layout issues - -## Documentation - -Use `search-docs` for detailed Tailwind CSS v4 patterns and documentation. - -## Basic Usage - -- Use Tailwind CSS classes to style HTML. Check and follow existing Tailwind conventions in the project before introducing new patterns. -- Offer to extract repeated patterns into components that match the project's conventions (e.g., Blade, JSX, Vue). -- Consider class placement, order, priority, and defaults. Remove redundant classes, add classes to parent or child elements carefully to reduce repetition, and group elements logically. - -## Tailwind CSS v4 Specifics - -- Always use Tailwind CSS v4 and avoid deprecated utilities. -- `corePlugins` is not supported in Tailwind v4. - -### CSS-First Configuration - -In Tailwind v4, configuration is CSS-first using the `@theme` directive — no separate `tailwind.config.js` file is needed: - - -```css -@theme { - --color-brand: oklch(0.72 0.11 178); -} -``` - -### Import Syntax - -In Tailwind v4, import Tailwind with a regular CSS `@import` statement instead of the `@tailwind` directives used in v3: - - -```diff -- @tailwind base; -- @tailwind components; -- @tailwind utilities; -+ @import "tailwindcss"; -``` - -### Replaced Utilities - -Tailwind v4 removed deprecated utilities. Use the replacements shown below. Opacity values remain numeric. - -| Deprecated | Replacement | -|------------|-------------| -| bg-opacity-* | bg-black/* | -| text-opacity-* | text-black/* | -| border-opacity-* | border-black/* | -| divide-opacity-* | divide-black/* | -| ring-opacity-* | ring-black/* | -| placeholder-opacity-* | placeholder-black/* | -| flex-shrink-* | shrink-* | -| flex-grow-* | grow-* | -| overflow-ellipsis | text-ellipsis | -| decoration-slice | box-decoration-slice | -| decoration-clone | box-decoration-clone | - -## Spacing - -Use `gap` utilities instead of margins for spacing between siblings: - - -```html -
-
Item 1
-
Item 2
-
-``` - -## Dark Mode - -If existing pages and components support dark mode, new pages and components must support it the same way, typically using the `dark:` variant: - - -```html -
- Content adapts to color scheme -
-``` - -## Common Patterns - -### Flexbox Layout - - -```html -
-
Left content
-
Right content
-
-``` - -### Grid Layout - - -```html -
-
Card 1
-
Card 2
-
Card 3
-
-``` - -## Common Pitfalls - -- Using deprecated v3 utilities (bg-opacity-*, flex-shrink-*, etc.) -- Using `@tailwind` directives instead of `@import "tailwindcss"` -- Trying to use `tailwind.config.js` instead of CSS `@theme` directive -- Using margins for spacing between siblings instead of gap utilities -- Forgetting to add dark mode variants when the project uses dark mode \ No newline at end of file diff --git a/.gitignore b/.gitignore index fb4ee22..f71d6d7 100644 --- a/.gitignore +++ b/.gitignore @@ -15,6 +15,8 @@ /.github /.gemini /.agents +/.codex +/.hermes /auth.json /node_modules /public/build @@ -30,3 +32,7 @@ vendor.zip test-captcha.php public/.user.ini dump.rdb + +# AI 生成文件 +AGENTS.md +GEMINI.md diff --git a/.hermes/plans/chatroom-security-performance-plan.md b/.hermes/plans/chatroom-security-performance-plan.md deleted file mode 100644 index 681f477..0000000 --- a/.hermes/plans/chatroom-security-performance-plan.md +++ /dev/null @@ -1,335 +0,0 @@ -# 🛡️ 聊天室项目 — 安全与访问速度优化规划方案 - -> **项目路径:** `/Users/pllx/Web/Herd/chatroom` -> **技术栈:** Laravel 12 + PHP 8.4 + Redis + MySQL + Reverb (WebSocket) + TailwindCSS 4 + Vite -> **检查日期:** 2026-04-27 - ---- - -## 一、安全优化(🔴高危 / 🟡中危 / 🟢低危) - -### 🔴 1. 关闭 APP_DEBUG(生产环境) - -**当前:** `.env` 中 `APP_DEBUG=true` -**风险:** 生产环境开启 DEBUG 会在报错时泄露数据库密码、Redis 密码、Reverb 密钥等敏感信息。 - -**方案:** -``` -# .env 生产环境改为 -APP_DEBUG=false -``` - ---- - -### 🔴 2. 启用 Session 加密 - -**当前:** `SESSION_ENCRYPT=false` -**风险:** Session 数据以明文存储在 Redis 中,若 Redis 被入侵或存在 SSRF,用户身份数据全部泄露。 - -**方案:** -``` -# .env 添加 -SESSION_ENCRYPT=true -``` - ---- - -### 🔴 3. 限制 Reverb WebSocket 允许源(Allowed Origins) - -**当前:** `config/reverb.php` 中 `'allowed_origins' => ['*']` -**风险:** 任何第三方网站均可连接你的 WebSocket 服务,可被用于 CSWSH(Cross-Site WebSocket Hijacking)攻击,窃取聊天消息。 - -**方案:** -```php -// config/reverb.php -'allowed_origins' => [ - env('APP_URL', 'http://chatroom.test'), - // 如果有多个域名,手动列出 -], -``` - ---- - -### 🔴 4. Reverb WebSocket 启用 TLS(WSS) - -**当前:** `REVERB_SCHEME=http`,WebSocket 走明文 HTTP -**风险:** 所有聊天消息、用户在线状态等实时数据明文传输,可被中间人攻击窃听。 - -**方案:** -``` -# .env 生产环境 -REVERB_SCHEME=https -REVERB_PORT=443 # 或 8443 -# 并在 reverb.php 中配置 TLS 证书路径 -``` - ---- - -### 🔴 5. 设置 Session Cookie Secure 标志 - -**当前:** `SESSION_SECURE_COOKIE` 未设置(null) -**风险:** 在 HTTPS 下,未标记 Secure 的 Cookie 仍可能被非 HTTPS 连接泄露。 - -**方案:** -``` -# .env 生产环境 -SESSION_SECURE_COOKIE=true -SESSION_SAME_SITE=strict -``` - ---- - -### 🟡 6. 加强登录安全策略 - -**当前状况:** -- 存在验证码(mews/captcha)✅ -- 登录有 `throttle:chat-login` 限流 ✅ -- 自动注册(用户名+密码即可注册)⚡ 双刃剑 -- MD5 老密码兼容 ✅ 会自动升级为 Bcrypt - -**优化方案:** - -| 项目 | 建议 | -|------|------| -| 登录失败锁定 | 同一 IP 5 次失败后临时锁定 15 分钟,后端实现 | -| 密码强度 | 最低 6 位,建议增加 min:6 验证或至少含数字/字母 | -| 管理员登录 2FA | id=1 站长登录时增加二次验证(如邮箱验证码) | -| 验证码频率 | 同一 IP 每天最多注册 3 个账号,防恶意注册 | - ---- - -### 🟡 7. 敏感字段防止 Mass Assignment - -**当前:** User 模型的 `$fillable` 中包含 `user_level`、`jjb`、`meili`、`bank_jjb`、`exp_num` 等金钱/权限字段。 - -**风险:** 如果其他地方调用了 `User::create($request->all())` 或 `User::update($request->all())` 且未使用 FormRequest 过滤,可能导致权限提升或刷币。 - -**方案:** -- 将 `user_level`、`jjb`、`meili`、`bank_jjb`、`exp_num` 等敏感字段移出 `$fillable` -- 仅在特定 Service 中使用 `forceFill()` 并加日志审计 - ---- - -### 🟡 8. XSS 输出转义检查 - -**当前:** 消息内容 `content` 限制 500 字符 ✅,但需确认前端渲染时是否正确转义 HTML。 - -**需要检查的点:** -- [ ] 聊天消息在前端如何渲染?(`innerHTML` 还是 `textContent`?) -- [ ] 用户签名(sign)字段是否转义? -- [ ] 房间公告是否转义? -- [ ] 用户头像路径是否校验?(当前有基本校验) - -**建议加固:** -- 前端渲染消息一律使用 `textContent` 或 Vue/React 自动转义 -- 如果必须支持 HTML 表情/颜色,使用白名单 sanitizer(如 DOMPurify) - ---- - -### 🟡 9. 管理员操作审计加强 - -**当前:** 已有 `PositionAuthorityLog` 和 `AdminLog` 记录 ✅ -**建议:** -- 所有金币/积分操作必须有完整的前后对比日志 -- 敏感操作(封号、解封、改权限)推送微信通知给站长 - ---- - -### 🟡 10. 隐藏管理员入口路径 - -**当前:** `/lkddi` 作为管理员登录入口(隐藏路径),但路径硬编码在 `routes/web.php` 中。 -**风险:** 任何能阅读源码或通过路径扫描的人都能发现。 - -**方案(可选):** -- 改为通过环境变量配置:`ADMIN_LOGIN_PATH=lkddi` -- 增加 IP 白名单限制:仅站长 IP 可访问 `/admin/*` - ---- - -### 🟢 11. 其他安全改进 - -| 项目 | 说明 | -|------|------| -| CSP Header | 添加 Content-Security-Policy HTTP 头,限制脚本执行来源 | -| X-Frame-Options | 添加 DENY/SAMEORIGIN 防止点击劫持 | -| Reverb 消息大小上限 | 当前 10KB,建议根据业务适当降低 | -| 依赖安全扫描 | 定期运行 `composer audit` 检查 Laravel 及第三方包漏洞 | -| 文件上传安全 | 自定义头像上传已限制图片类型 ✅,但建议增加文件内容校验 | - ---- - -## 二、访问速度优化(🔥高优 / ⚡中优 / 💡低优) - -### 🔥 1. 启用 Laravel OPcache - -**当前环境:** 通过 Laravel Herd 运行(PHP-FPM),未启用 OPcache。 -**影响:** 每个 PHP 请求都要重新编译框架文件,浪费大量 CPU。 - -**方案(Mac/Linux 生产环境):** -```ini -; php.ini -opcache.enable=1 -opcache.memory_consumption=128 -opcache.max_accelerated_files=10000 -opcache.revalidate_freq=0 -opcache.validate_timestamps=0 ; 生产环境关闭文件修改检查 -``` - ---- - -### 🔥 2. 数据库查询优化 - -**当前状况:** -- 使用 Redis 缓存,但部分页面可能直接查询 MySQL -- 存在多个游戏(百家乐、赛马、彩票、五子棋等),每次查询都走数据库 - -**优化方案:** - -| 措施 | 说明 | 优先级 | -|------|------|--------| -| 排行榜缓存 | `->remember(60)` 缓存排行榜结果 60 秒 | 🔥 | -| 在线人数缓存 | 当前使用 Redis 实时维护 ✅,保持现状 | - | -| 房间列表缓存 | `Room::all()` 结果缓存到 Redis | 🔥 | -| 游戏配置缓存 | `GameConfig::isEnabled()` 结果缓存 10 秒 | ⚡ | -| 慢查询日志 | 启用 MySQL slow_query_log,定位慢 SQL | ⚡ | - ---- - -### 🔥 3. 静态资源 CDN 加速 - -**当前:** 所有静态资源(CSS、JS、图片)直接从源服务器加载。 - -**方案:** - -| 资源类型 | 方案 | -|----------|------| -| Vite 构建产物(CSS/JS) | 上传到 CDN(阿里云 OSS+CDN / CloudFlare R2) | -| 头像图片 | 启用单独域名或 CDN,添加长期缓存头 | -| 聊天背景图 | 使用 CDN 分发 12 张背景图 | -| Reverb WS 连接 | 通过 CDN/反向代理(如 Nginx)代理 WSS 连接 | - -**当前已做:** `.htaccess` 中已对 Vite 构建产物设置 31536000 秒缓存 ✅ -**改进:** 将 `public/build/` 下的资源部署到 CDN。 - ---- - -### 🔥 4. Reverb WebSocket 优化 - -**当前:** Reverb 单节点运行,HTTP 协议,端口 8080。 - -**优化方案:** - -| 措施 | 说明 | -|------|------| -| 升级为 WSS | 启用 TLS,避免被运营商劫持/限速 | -| 水平扩展 | 启用 Reverb Scaling(通过 Redis 发布订阅,见 `reverb.php` 配置) | -| Nginx 反向代理 | 用 Nginx 代理 WSS,可同时处理 HTTP 静态资源 | -| 心跳优化 | 当前 `ping_interval=60s`,可考虑适当延长 | - ---- - -### ⚡ 5. Laravel 应用层优化 - -| 措施 | 说明 | 优先级 | -|------|------|--------| -| 路由缓存 | `php artisan route:cache` — 减少路由注册开销 | ⚡ | -| 配置缓存 | `php artisan config:cache` — 减少 config 加载 | ⚡ | -| 事件缓存 | `php artisan event:cache` — L12 原生支持 | ⚡ | -| 视图缓存 | `php artisan view:cache` — Blade 编译缓存 | ⚡ | -| 模型预加载 | 检查 N+1 查询,使用 `->with()` | ⚡ | - -**⚠️ 注意:** `php artisan optimize` 已在 Laravel 12 中被移除,应单独执行以上四个命令。 - ---- - -### ⚡ 6. Redis 优化 - -**当前:** 单机单实例 Redis,承载 Session、Cache、Queue、Reverb Scaling 全部功能。 - -**建议:** -- 生产环境建议至少 2 个 Redis 实例:一个用于 Session/Cache(可随时清),一个用于 Queue(需持久化) -- Reverb Scaling 发布订阅建议单独连接 -- 为 Redis 设置 `maxmemory` 和 `maxmemory-policy allkeys-lru` 防止内存溢出 - ---- - -### ⚡ 7. 前端加载优化 - -| 措施 | 说明 | -|------|------| -| JS 代码分割 | Vite 动态 import 拆分大 JS 文件 | -| 懒加载 | 游戏模块(百家乐、赛马等)按需加载 | -| 图片懒加载 | 头像、礼物图片使用 `loading="lazy"` | -| Alpine.js 轻量化 | 当前已使用 Alpine.js ✅ 但避免过多 watcher | - ---- - -### 💡 8. 考虑 Laravel Octane(长期规划) - -**说明:** Laravel Octane(Swoole / RoadRunner)将应用常驻内存,消除框架启动开销,可带来 10-30 倍并发性能提升。 - -**条件:** 需要确保代码无静态变量状态污染,适合用户量增长后的升级。 - ---- - -## 三、实施优先级建议 - -### 第一阶段(紧急 · 1-2 天)🔴🔥 -| # | 任务 | 预估工时 | -|---|------|---------| -| 1 | 关闭 `APP_DEBUG` | 5 分钟 | -| 2 | 启用 `SESSION_ENCRYPT` | 5 分钟 | -| 3 | 限制 Reverb `allowed_origins` | 10 分钟 | -| 4 | 配置 Route/Config/Event/View 缓存 | 30 分钟 | -| 5 | 排行榜、房间列表等 Redis 缓存 | 1 小时 | - -### 第二阶段(重要 · 3-5 天)🟡⚡ -| # | 任务 | 预估工时 | -|---|------|---------| -| 6 | 敏感字段移出 `$fillable` | 1 小时 | -| 7 | 登录失败锁定 + 注册频率限制 | 2 小时 | -| 8 | 数据库慢查询分析与索引优化 | 2 小时 | -| 9 | 前端 JS 懒加载与代码分割 | 3 小时 | -| 10 | OPcache 配置 | 30 分钟 | - -### 第三阶段(完善 · 1-2 周)🟢💡 -| # | 任务 | 预估工时 | -|---|------|---------| -| 11 | Reverb WSS + Nginx 反向代理 | 2 小时 | -| 12 | 管理员 2FA 验证 | 4 小时 | -| 13 | CDN 部署静态资源 | 1 天 | -| 14 | Content-Security-Policy 等安全头 | 1 小时 | -| 15 | 生产环境 Redis 分实例部署 | 2 小时 | -| 16 | 评估 Laravel Octane 迁移 | 2-3 天 | - ---- - -## 四、检查清单工具 - -部署到生产环境前可使用以下命令快速检查: - -```bash -# Laravel 安全检查 -php artisan about # 查看环境配置 -php artisan route:list # 查看所有路由(确认无暴露的管理路径) - -# Composer 安全审计 -composer audit - -# 缓存优化 -php artisan config:cache -php artisan route:cache -php artisan event:cache -php artisan view:cache - -# 依赖更新 -composer update --no-dev -o -``` - ---- - -> **总结:** 该项目整体架构设计良好(Redis + Reverb 实时通信 + Alpine.js 轻量前端), -> 主要安全短板集中在**生产环境配置**(DEBUG 未关、Session 未加密、WebSocket 无 TLS)和**部分敏感字段保护**。 -> 速度优化则聚焦于**缓存策略**和**CDN 静态资源分发**。 -> -> 建议从第一阶段紧急问题入手,逐步推进到第二阶段。需要我帮你实施其中任何一部分,随时说! diff --git a/.junie/guidelines.md b/.junie/guidelines.md deleted file mode 100644 index de20950..0000000 --- a/.junie/guidelines.md +++ /dev/null @@ -1,256 +0,0 @@ - -=== foundation rules === - -# Laravel Boost Guidelines - -The Laravel Boost guidelines are specifically curated by Laravel maintainers for this application. These guidelines should be followed closely to ensure the best experience when building Laravel applications. - -## Foundational Context - -This application is a Laravel application and its main Laravel ecosystems package & versions are below. You are an expert with them all. Ensure you abide by these specific packages & versions. - -- php - 8.4.5 -- laravel/framework (LARAVEL) - v12 -- laravel/horizon (HORIZON) - v5 -- laravel/prompts (PROMPTS) - v0 -- laravel/reverb (REVERB) - v1 -- laravel/boost (BOOST) - v2 -- laravel/mcp (MCP) - v0 -- laravel/pail (PAIL) - v1 -- laravel/pint (PINT) - v1 -- laravel/sail (SAIL) - v1 -- phpunit/phpunit (PHPUNIT) - v11 -- laravel-echo (ECHO) - v2 -- tailwindcss (TAILWINDCSS) - v4 - -## Skills Activation - -This project has domain-specific skills available. You MUST activate the relevant skill whenever you work in that domain—don't wait until you're stuck. - -- `tailwindcss-development` — Styles applications using Tailwind CSS v4 utilities. Activates when adding styles, restyling components, working with gradients, spacing, layout, flex, grid, responsive design, dark mode, colors, typography, or borders; or when the user mentions CSS, styling, classes, Tailwind, restyle, hero section, cards, buttons, or any visual/UI changes. - -## Conventions - -- You must follow all existing code conventions used in this application. When creating or editing a file, check sibling files for the correct structure, approach, and naming. -- Use descriptive names for variables and methods. For example, `isRegisteredForDiscounts`, not `discount()`. -- Check for existing components to reuse before writing a new one. - -## Verification Scripts - -- Do not create verification scripts or tinker when tests cover that functionality and prove they work. Unit and feature tests are more important. - -## Application Structure & Architecture - -- Stick to existing directory structure; don't create new base folders without approval. -- Do not change the application's dependencies without approval. - -## Frontend Bundling - -- If the user doesn't see a frontend change reflected in the UI, it could mean they need to run `npm run build`, `npm run dev`, or `composer run dev`. Ask them. - -## Documentation Files - -- You must only create documentation files if explicitly requested by the user. - -## Replies - -- Be concise in your explanations - focus on what's important rather than explaining obvious details. - -=== boost rules === - -# Laravel Boost - -- Laravel Boost is an MCP server that comes with powerful tools designed specifically for this application. Use them. - -## Artisan - -- Use the `list-artisan-commands` tool when you need to call an Artisan command to double-check the available parameters. - -## URLs - -- Whenever you share a project URL with the user, you should use the `get-absolute-url` tool to ensure you're using the correct scheme, domain/IP, and port. - -## Tinker / Debugging - -- You should use the `tinker` tool when you need to execute PHP to debug code or query Eloquent models directly. -- Use the `database-query` tool when you only need to read from the database. -- Use the `database-schema` tool to inspect table structure before writing migrations or models. - -## Reading Browser Logs With the `browser-logs` Tool - -- You can read browser logs, errors, and exceptions using the `browser-logs` tool from Boost. -- Only recent browser logs will be useful - ignore old logs. - -## Searching Documentation (Critically Important) - -- Boost comes with a powerful `search-docs` tool you should use before trying other approaches when working with Laravel or Laravel ecosystem packages. This tool automatically passes a list of installed packages and their versions to the remote Boost API, so it returns only version-specific documentation for the user's circumstance. You should pass an array of packages to filter on if you know you need docs for particular packages. -- Search the documentation before making code changes to ensure we are taking the correct approach. -- Use multiple, broad, simple, topic-based queries at once. For example: `['rate limiting', 'routing rate limiting', 'routing']`. The most relevant results will be returned first. -- Do not add package names to queries; package information is already shared. For example, use `test resource table`, not `filament 4 test resource table`. - -### Available Search Syntax - -1. Simple Word Searches with auto-stemming - query=authentication - finds 'authenticate' and 'auth'. -2. Multiple Words (AND Logic) - query=rate limit - finds knowledge containing both "rate" AND "limit". -3. Quoted Phrases (Exact Position) - query="infinite scroll" - words must be adjacent and in that order. -4. Mixed Queries - query=middleware "rate limit" - "middleware" AND exact phrase "rate limit". -5. Multiple Queries - queries=["authentication", "middleware"] - ANY of these terms. - -=== php rules === - -# PHP - -- Always use curly braces for control structures, even for single-line bodies. - -## Constructors - -- Use PHP 8 constructor property promotion in `__construct()`. - - `public function __construct(public GitHub $github) { }` -- Do not allow empty `__construct()` methods with zero parameters unless the constructor is private. - -## Type Declarations - -- Always use explicit return type declarations for methods and functions. -- Use appropriate PHP type hints for method parameters. - - -```php -protected function isAccessible(User $user, ?string $path = null): bool -{ - ... -} -``` - -## Enums - -- Typically, keys in an Enum should be TitleCase. For example: `FavoritePerson`, `BestLake`, `Monthly`. - -## Comments - -- Prefer PHPDoc blocks over inline comments. Never use comments within the code itself unless the logic is exceptionally complex. - -## PHPDoc Blocks - -- Add useful array shape type definitions when appropriate. - -=== herd rules === - -# Laravel Herd - -- The application is served by Laravel Herd and will be available at: `https?://[kebab-case-project-dir].test`. Use the `get-absolute-url` tool to generate valid URLs for the user. -- You must not run any commands to make the site available via HTTP(S). It is always available through Laravel Herd. - -=== laravel/core rules === - -# Do Things the Laravel Way - -- Use `php artisan make:` commands to create new files (i.e. migrations, controllers, models, etc.). You can list available Artisan commands using the `list-artisan-commands` tool. -- If you're creating a generic PHP class, use `php artisan make:class`. -- Pass `--no-interaction` to all Artisan commands to ensure they work without user input. You should also pass the correct `--options` to ensure correct behavior. - -## Database - -- Always use proper Eloquent relationship methods with return type hints. Prefer relationship methods over raw queries or manual joins. -- Use Eloquent models and relationships before suggesting raw database queries. -- Avoid `DB::`; prefer `Model::query()`. Generate code that leverages Laravel's ORM capabilities rather than bypassing them. -- Generate code that prevents N+1 query problems by using eager loading. -- Use Laravel's query builder for very complex database operations. - -### Model Creation - -- When creating new models, create useful factories and seeders for them too. Ask the user if they need any other things, using `list-artisan-commands` to check the available options to `php artisan make:model`. - -### APIs & Eloquent Resources - -- For APIs, default to using Eloquent API Resources and API versioning unless existing API routes do not, then you should follow existing application convention. - -## Controllers & Validation - -- Always create Form Request classes for validation rather than inline validation in controllers. Include both validation rules and custom error messages. -- Check sibling Form Requests to see if the application uses array or string based validation rules. - -## Authentication & Authorization - -- Use Laravel's built-in authentication and authorization features (gates, policies, Sanctum, etc.). - -## URL Generation - -- When generating links to other pages, prefer named routes and the `route()` function. - -## Queues - -- Use queued jobs for time-consuming operations with the `ShouldQueue` interface. - -## Configuration - -- Use environment variables only in configuration files - never use the `env()` function directly outside of config files. Always use `config('app.name')`, not `env('APP_NAME')`. - -## Testing - -- When creating models for tests, use the factories for the models. Check if the factory has custom states that can be used before manually setting up the model. -- Faker: Use methods such as `$this->faker->word()` or `fake()->randomDigit()`. Follow existing conventions whether to use `$this->faker` or `fake()`. -- When creating tests, make use of `php artisan make:test [options] {name}` to create a feature test, and pass `--unit` to create a unit test. Most tests should be feature tests. - -## Vite Error - -- If you receive an "Illuminate\Foundation\ViteException: Unable to locate file in Vite manifest" error, you can run `npm run build` or ask the user to run `npm run dev` or `composer run dev`. - -=== laravel/v12 rules === - -# Laravel 12 - -- CRITICAL: ALWAYS use `search-docs` tool for version-specific Laravel documentation and updated code examples. -- Since Laravel 11, Laravel has a new streamlined file structure which this project uses. - -## Laravel 12 Structure - -- In Laravel 12, middleware are no longer registered in `app/Http/Kernel.php`. -- Middleware are configured declaratively in `bootstrap/app.php` using `Application::configure()->withMiddleware()`. -- `bootstrap/app.php` is the file to register middleware, exceptions, and routing files. -- `bootstrap/providers.php` contains application specific service providers. -- The `app\Console\Kernel.php` file no longer exists; use `bootstrap/app.php` or `routes/console.php` for console configuration. -- Console commands in `app/Console/Commands/` are automatically available and do not require manual registration. - -## Database - -- When modifying a column, the migration must include all of the attributes that were previously defined on the column. Otherwise, they will be dropped and lost. -- Laravel 12 allows limiting eagerly loaded records natively, without external packages: `$query->latest()->limit(10);`. - -### Models - -- Casts can and likely should be set in a `casts()` method on a model rather than the `$casts` property. Follow existing conventions from other models. - -=== pint/core rules === - -# Laravel Pint Code Formatter - -- If you have modified any PHP files, you must run `vendor/bin/pint --dirty --format agent` before finalizing changes to ensure your code matches the project's expected style. -- Do not run `vendor/bin/pint --test --format agent`, simply run `vendor/bin/pint --format agent` to fix any formatting issues. - -=== phpunit/core rules === - -# PHPUnit - -- This application uses PHPUnit for testing. All tests must be written as PHPUnit classes. Use `php artisan make:test --phpunit {name}` to create a new test. -- If you see a test using "Pest", convert it to PHPUnit. -- Every time a test has been updated, run that singular test. -- When the tests relating to your feature are passing, ask the user if they would like to also run the entire test suite to make sure everything is still passing. -- Tests should cover all happy paths, failure paths, and edge cases. -- You must not remove any tests or test files from the tests directory without approval. These are not temporary or helper files; these are core to the application. - -## Running Tests - -- Run the minimal number of tests, using an appropriate filter, before finalizing. -- To run all tests: `php artisan test --compact`. -- To run all tests in a file: `php artisan test --compact tests/Feature/ExampleTest.php`. -- To filter on a particular test name: `php artisan test --compact --filter=testName` (recommended after making a change to a related file). - -=== tailwindcss/core rules === - -# Tailwind CSS - -- Always use existing Tailwind conventions; check project patterns before adding new ones. -- IMPORTANT: Always use `search-docs` tool for version-specific Tailwind CSS documentation and updated code examples. Never rely on training data. -- IMPORTANT: Activate `tailwindcss-development` every time you're working with a Tailwind CSS or styling-related task. - - diff --git a/.junie/mcp/mcp.json b/.junie/mcp/mcp.json deleted file mode 100644 index ff55465..0000000 --- a/.junie/mcp/mcp.json +++ /dev/null @@ -1,20 +0,0 @@ -{ - "mcpServers": { - "laravel-boost": { - "command": "/opt/homebrew/Cellar/php/8.4.5_1/bin/php", - "args": [ - "/Users/pllx/Web/Herd/chatroom/artisan", - "boost:mcp" - ] - }, - "herd": { - "command": "/opt/homebrew/Cellar/php/8.4.5_1/bin/php", - "args": [ - "/Applications/Herd.app/Contents/Resources/herd-mcp.phar" - ], - "env": { - "SITE_PATH": "/Users/pllx/Web/Herd/chatroom" - } - } - } -} \ No newline at end of file diff --git a/.junie/skills/tailwindcss-development/SKILL.md b/.junie/skills/tailwindcss-development/SKILL.md deleted file mode 100644 index 21a7e46..0000000 --- a/.junie/skills/tailwindcss-development/SKILL.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -name: tailwindcss-development -description: "Styles applications using Tailwind CSS v4 utilities. Activates when adding styles, restyling components, working with gradients, spacing, layout, flex, grid, responsive design, dark mode, colors, typography, or borders; or when the user mentions CSS, styling, classes, Tailwind, restyle, hero section, cards, buttons, or any visual/UI changes." -license: MIT -metadata: - author: laravel ---- - -# Tailwind CSS Development - -## When to Apply - -Activate this skill when: - -- Adding styles to components or pages -- Working with responsive design -- Implementing dark mode -- Extracting repeated patterns into components -- Debugging spacing or layout issues - -## Documentation - -Use `search-docs` for detailed Tailwind CSS v4 patterns and documentation. - -## Basic Usage - -- Use Tailwind CSS classes to style HTML. Check and follow existing Tailwind conventions in the project before introducing new patterns. -- Offer to extract repeated patterns into components that match the project's conventions (e.g., Blade, JSX, Vue). -- Consider class placement, order, priority, and defaults. Remove redundant classes, add classes to parent or child elements carefully to reduce repetition, and group elements logically. - -## Tailwind CSS v4 Specifics - -- Always use Tailwind CSS v4 and avoid deprecated utilities. -- `corePlugins` is not supported in Tailwind v4. - -### CSS-First Configuration - -In Tailwind v4, configuration is CSS-first using the `@theme` directive — no separate `tailwind.config.js` file is needed: - - -```css -@theme { - --color-brand: oklch(0.72 0.11 178); -} -``` - -### Import Syntax - -In Tailwind v4, import Tailwind with a regular CSS `@import` statement instead of the `@tailwind` directives used in v3: - - -```diff -- @tailwind base; -- @tailwind components; -- @tailwind utilities; -+ @import "tailwindcss"; -``` - -### Replaced Utilities - -Tailwind v4 removed deprecated utilities. Use the replacements shown below. Opacity values remain numeric. - -| Deprecated | Replacement | -|------------|-------------| -| bg-opacity-* | bg-black/* | -| text-opacity-* | text-black/* | -| border-opacity-* | border-black/* | -| divide-opacity-* | divide-black/* | -| ring-opacity-* | ring-black/* | -| placeholder-opacity-* | placeholder-black/* | -| flex-shrink-* | shrink-* | -| flex-grow-* | grow-* | -| overflow-ellipsis | text-ellipsis | -| decoration-slice | box-decoration-slice | -| decoration-clone | box-decoration-clone | - -## Spacing - -Use `gap` utilities instead of margins for spacing between siblings: - - -```html -
-
Item 1
-
Item 2
-
-``` - -## Dark Mode - -If existing pages and components support dark mode, new pages and components must support it the same way, typically using the `dark:` variant: - - -```html -
- Content adapts to color scheme -
-``` - -## Common Patterns - -### Flexbox Layout - - -```html -
-
Left content
-
Right content
-
-``` - -### Grid Layout - - -```html -
-
Card 1
-
Card 2
-
Card 3
-
-``` - -## Common Pitfalls - -- Using deprecated v3 utilities (bg-opacity-*, flex-shrink-*, etc.) -- Using `@tailwind` directives instead of `@import "tailwindcss"` -- Trying to use `tailwind.config.js` instead of CSS `@theme` directive -- Using margins for spacing between siblings instead of gap utilities -- Forgetting to add dark mode variants when the project uses dark mode \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index de20950..0000000 --- a/AGENTS.md +++ /dev/null @@ -1,256 +0,0 @@ - -=== foundation rules === - -# Laravel Boost Guidelines - -The Laravel Boost guidelines are specifically curated by Laravel maintainers for this application. These guidelines should be followed closely to ensure the best experience when building Laravel applications. - -## Foundational Context - -This application is a Laravel application and its main Laravel ecosystems package & versions are below. You are an expert with them all. Ensure you abide by these specific packages & versions. - -- php - 8.4.5 -- laravel/framework (LARAVEL) - v12 -- laravel/horizon (HORIZON) - v5 -- laravel/prompts (PROMPTS) - v0 -- laravel/reverb (REVERB) - v1 -- laravel/boost (BOOST) - v2 -- laravel/mcp (MCP) - v0 -- laravel/pail (PAIL) - v1 -- laravel/pint (PINT) - v1 -- laravel/sail (SAIL) - v1 -- phpunit/phpunit (PHPUNIT) - v11 -- laravel-echo (ECHO) - v2 -- tailwindcss (TAILWINDCSS) - v4 - -## Skills Activation - -This project has domain-specific skills available. You MUST activate the relevant skill whenever you work in that domain—don't wait until you're stuck. - -- `tailwindcss-development` — Styles applications using Tailwind CSS v4 utilities. Activates when adding styles, restyling components, working with gradients, spacing, layout, flex, grid, responsive design, dark mode, colors, typography, or borders; or when the user mentions CSS, styling, classes, Tailwind, restyle, hero section, cards, buttons, or any visual/UI changes. - -## Conventions - -- You must follow all existing code conventions used in this application. When creating or editing a file, check sibling files for the correct structure, approach, and naming. -- Use descriptive names for variables and methods. For example, `isRegisteredForDiscounts`, not `discount()`. -- Check for existing components to reuse before writing a new one. - -## Verification Scripts - -- Do not create verification scripts or tinker when tests cover that functionality and prove they work. Unit and feature tests are more important. - -## Application Structure & Architecture - -- Stick to existing directory structure; don't create new base folders without approval. -- Do not change the application's dependencies without approval. - -## Frontend Bundling - -- If the user doesn't see a frontend change reflected in the UI, it could mean they need to run `npm run build`, `npm run dev`, or `composer run dev`. Ask them. - -## Documentation Files - -- You must only create documentation files if explicitly requested by the user. - -## Replies - -- Be concise in your explanations - focus on what's important rather than explaining obvious details. - -=== boost rules === - -# Laravel Boost - -- Laravel Boost is an MCP server that comes with powerful tools designed specifically for this application. Use them. - -## Artisan - -- Use the `list-artisan-commands` tool when you need to call an Artisan command to double-check the available parameters. - -## URLs - -- Whenever you share a project URL with the user, you should use the `get-absolute-url` tool to ensure you're using the correct scheme, domain/IP, and port. - -## Tinker / Debugging - -- You should use the `tinker` tool when you need to execute PHP to debug code or query Eloquent models directly. -- Use the `database-query` tool when you only need to read from the database. -- Use the `database-schema` tool to inspect table structure before writing migrations or models. - -## Reading Browser Logs With the `browser-logs` Tool - -- You can read browser logs, errors, and exceptions using the `browser-logs` tool from Boost. -- Only recent browser logs will be useful - ignore old logs. - -## Searching Documentation (Critically Important) - -- Boost comes with a powerful `search-docs` tool you should use before trying other approaches when working with Laravel or Laravel ecosystem packages. This tool automatically passes a list of installed packages and their versions to the remote Boost API, so it returns only version-specific documentation for the user's circumstance. You should pass an array of packages to filter on if you know you need docs for particular packages. -- Search the documentation before making code changes to ensure we are taking the correct approach. -- Use multiple, broad, simple, topic-based queries at once. For example: `['rate limiting', 'routing rate limiting', 'routing']`. The most relevant results will be returned first. -- Do not add package names to queries; package information is already shared. For example, use `test resource table`, not `filament 4 test resource table`. - -### Available Search Syntax - -1. Simple Word Searches with auto-stemming - query=authentication - finds 'authenticate' and 'auth'. -2. Multiple Words (AND Logic) - query=rate limit - finds knowledge containing both "rate" AND "limit". -3. Quoted Phrases (Exact Position) - query="infinite scroll" - words must be adjacent and in that order. -4. Mixed Queries - query=middleware "rate limit" - "middleware" AND exact phrase "rate limit". -5. Multiple Queries - queries=["authentication", "middleware"] - ANY of these terms. - -=== php rules === - -# PHP - -- Always use curly braces for control structures, even for single-line bodies. - -## Constructors - -- Use PHP 8 constructor property promotion in `__construct()`. - - `public function __construct(public GitHub $github) { }` -- Do not allow empty `__construct()` methods with zero parameters unless the constructor is private. - -## Type Declarations - -- Always use explicit return type declarations for methods and functions. -- Use appropriate PHP type hints for method parameters. - - -```php -protected function isAccessible(User $user, ?string $path = null): bool -{ - ... -} -``` - -## Enums - -- Typically, keys in an Enum should be TitleCase. For example: `FavoritePerson`, `BestLake`, `Monthly`. - -## Comments - -- Prefer PHPDoc blocks over inline comments. Never use comments within the code itself unless the logic is exceptionally complex. - -## PHPDoc Blocks - -- Add useful array shape type definitions when appropriate. - -=== herd rules === - -# Laravel Herd - -- The application is served by Laravel Herd and will be available at: `https?://[kebab-case-project-dir].test`. Use the `get-absolute-url` tool to generate valid URLs for the user. -- You must not run any commands to make the site available via HTTP(S). It is always available through Laravel Herd. - -=== laravel/core rules === - -# Do Things the Laravel Way - -- Use `php artisan make:` commands to create new files (i.e. migrations, controllers, models, etc.). You can list available Artisan commands using the `list-artisan-commands` tool. -- If you're creating a generic PHP class, use `php artisan make:class`. -- Pass `--no-interaction` to all Artisan commands to ensure they work without user input. You should also pass the correct `--options` to ensure correct behavior. - -## Database - -- Always use proper Eloquent relationship methods with return type hints. Prefer relationship methods over raw queries or manual joins. -- Use Eloquent models and relationships before suggesting raw database queries. -- Avoid `DB::`; prefer `Model::query()`. Generate code that leverages Laravel's ORM capabilities rather than bypassing them. -- Generate code that prevents N+1 query problems by using eager loading. -- Use Laravel's query builder for very complex database operations. - -### Model Creation - -- When creating new models, create useful factories and seeders for them too. Ask the user if they need any other things, using `list-artisan-commands` to check the available options to `php artisan make:model`. - -### APIs & Eloquent Resources - -- For APIs, default to using Eloquent API Resources and API versioning unless existing API routes do not, then you should follow existing application convention. - -## Controllers & Validation - -- Always create Form Request classes for validation rather than inline validation in controllers. Include both validation rules and custom error messages. -- Check sibling Form Requests to see if the application uses array or string based validation rules. - -## Authentication & Authorization - -- Use Laravel's built-in authentication and authorization features (gates, policies, Sanctum, etc.). - -## URL Generation - -- When generating links to other pages, prefer named routes and the `route()` function. - -## Queues - -- Use queued jobs for time-consuming operations with the `ShouldQueue` interface. - -## Configuration - -- Use environment variables only in configuration files - never use the `env()` function directly outside of config files. Always use `config('app.name')`, not `env('APP_NAME')`. - -## Testing - -- When creating models for tests, use the factories for the models. Check if the factory has custom states that can be used before manually setting up the model. -- Faker: Use methods such as `$this->faker->word()` or `fake()->randomDigit()`. Follow existing conventions whether to use `$this->faker` or `fake()`. -- When creating tests, make use of `php artisan make:test [options] {name}` to create a feature test, and pass `--unit` to create a unit test. Most tests should be feature tests. - -## Vite Error - -- If you receive an "Illuminate\Foundation\ViteException: Unable to locate file in Vite manifest" error, you can run `npm run build` or ask the user to run `npm run dev` or `composer run dev`. - -=== laravel/v12 rules === - -# Laravel 12 - -- CRITICAL: ALWAYS use `search-docs` tool for version-specific Laravel documentation and updated code examples. -- Since Laravel 11, Laravel has a new streamlined file structure which this project uses. - -## Laravel 12 Structure - -- In Laravel 12, middleware are no longer registered in `app/Http/Kernel.php`. -- Middleware are configured declaratively in `bootstrap/app.php` using `Application::configure()->withMiddleware()`. -- `bootstrap/app.php` is the file to register middleware, exceptions, and routing files. -- `bootstrap/providers.php` contains application specific service providers. -- The `app\Console\Kernel.php` file no longer exists; use `bootstrap/app.php` or `routes/console.php` for console configuration. -- Console commands in `app/Console/Commands/` are automatically available and do not require manual registration. - -## Database - -- When modifying a column, the migration must include all of the attributes that were previously defined on the column. Otherwise, they will be dropped and lost. -- Laravel 12 allows limiting eagerly loaded records natively, without external packages: `$query->latest()->limit(10);`. - -### Models - -- Casts can and likely should be set in a `casts()` method on a model rather than the `$casts` property. Follow existing conventions from other models. - -=== pint/core rules === - -# Laravel Pint Code Formatter - -- If you have modified any PHP files, you must run `vendor/bin/pint --dirty --format agent` before finalizing changes to ensure your code matches the project's expected style. -- Do not run `vendor/bin/pint --test --format agent`, simply run `vendor/bin/pint --format agent` to fix any formatting issues. - -=== phpunit/core rules === - -# PHPUnit - -- This application uses PHPUnit for testing. All tests must be written as PHPUnit classes. Use `php artisan make:test --phpunit {name}` to create a new test. -- If you see a test using "Pest", convert it to PHPUnit. -- Every time a test has been updated, run that singular test. -- When the tests relating to your feature are passing, ask the user if they would like to also run the entire test suite to make sure everything is still passing. -- Tests should cover all happy paths, failure paths, and edge cases. -- You must not remove any tests or test files from the tests directory without approval. These are not temporary or helper files; these are core to the application. - -## Running Tests - -- Run the minimal number of tests, using an appropriate filter, before finalizing. -- To run all tests: `php artisan test --compact`. -- To run all tests in a file: `php artisan test --compact tests/Feature/ExampleTest.php`. -- To filter on a particular test name: `php artisan test --compact --filter=testName` (recommended after making a change to a related file). - -=== tailwindcss/core rules === - -# Tailwind CSS - -- Always use existing Tailwind conventions; check project patterns before adding new ones. -- IMPORTANT: Always use `search-docs` tool for version-specific Tailwind CSS documentation and updated code examples. Never rely on training data. -- IMPORTANT: Activate `tailwindcss-development` every time you're working with a Tailwind CSS or styling-related task. - - diff --git a/GEMINI.md b/GEMINI.md deleted file mode 100644 index de20950..0000000 --- a/GEMINI.md +++ /dev/null @@ -1,256 +0,0 @@ - -=== foundation rules === - -# Laravel Boost Guidelines - -The Laravel Boost guidelines are specifically curated by Laravel maintainers for this application. These guidelines should be followed closely to ensure the best experience when building Laravel applications. - -## Foundational Context - -This application is a Laravel application and its main Laravel ecosystems package & versions are below. You are an expert with them all. Ensure you abide by these specific packages & versions. - -- php - 8.4.5 -- laravel/framework (LARAVEL) - v12 -- laravel/horizon (HORIZON) - v5 -- laravel/prompts (PROMPTS) - v0 -- laravel/reverb (REVERB) - v1 -- laravel/boost (BOOST) - v2 -- laravel/mcp (MCP) - v0 -- laravel/pail (PAIL) - v1 -- laravel/pint (PINT) - v1 -- laravel/sail (SAIL) - v1 -- phpunit/phpunit (PHPUNIT) - v11 -- laravel-echo (ECHO) - v2 -- tailwindcss (TAILWINDCSS) - v4 - -## Skills Activation - -This project has domain-specific skills available. You MUST activate the relevant skill whenever you work in that domain—don't wait until you're stuck. - -- `tailwindcss-development` — Styles applications using Tailwind CSS v4 utilities. Activates when adding styles, restyling components, working with gradients, spacing, layout, flex, grid, responsive design, dark mode, colors, typography, or borders; or when the user mentions CSS, styling, classes, Tailwind, restyle, hero section, cards, buttons, or any visual/UI changes. - -## Conventions - -- You must follow all existing code conventions used in this application. When creating or editing a file, check sibling files for the correct structure, approach, and naming. -- Use descriptive names for variables and methods. For example, `isRegisteredForDiscounts`, not `discount()`. -- Check for existing components to reuse before writing a new one. - -## Verification Scripts - -- Do not create verification scripts or tinker when tests cover that functionality and prove they work. Unit and feature tests are more important. - -## Application Structure & Architecture - -- Stick to existing directory structure; don't create new base folders without approval. -- Do not change the application's dependencies without approval. - -## Frontend Bundling - -- If the user doesn't see a frontend change reflected in the UI, it could mean they need to run `npm run build`, `npm run dev`, or `composer run dev`. Ask them. - -## Documentation Files - -- You must only create documentation files if explicitly requested by the user. - -## Replies - -- Be concise in your explanations - focus on what's important rather than explaining obvious details. - -=== boost rules === - -# Laravel Boost - -- Laravel Boost is an MCP server that comes with powerful tools designed specifically for this application. Use them. - -## Artisan - -- Use the `list-artisan-commands` tool when you need to call an Artisan command to double-check the available parameters. - -## URLs - -- Whenever you share a project URL with the user, you should use the `get-absolute-url` tool to ensure you're using the correct scheme, domain/IP, and port. - -## Tinker / Debugging - -- You should use the `tinker` tool when you need to execute PHP to debug code or query Eloquent models directly. -- Use the `database-query` tool when you only need to read from the database. -- Use the `database-schema` tool to inspect table structure before writing migrations or models. - -## Reading Browser Logs With the `browser-logs` Tool - -- You can read browser logs, errors, and exceptions using the `browser-logs` tool from Boost. -- Only recent browser logs will be useful - ignore old logs. - -## Searching Documentation (Critically Important) - -- Boost comes with a powerful `search-docs` tool you should use before trying other approaches when working with Laravel or Laravel ecosystem packages. This tool automatically passes a list of installed packages and their versions to the remote Boost API, so it returns only version-specific documentation for the user's circumstance. You should pass an array of packages to filter on if you know you need docs for particular packages. -- Search the documentation before making code changes to ensure we are taking the correct approach. -- Use multiple, broad, simple, topic-based queries at once. For example: `['rate limiting', 'routing rate limiting', 'routing']`. The most relevant results will be returned first. -- Do not add package names to queries; package information is already shared. For example, use `test resource table`, not `filament 4 test resource table`. - -### Available Search Syntax - -1. Simple Word Searches with auto-stemming - query=authentication - finds 'authenticate' and 'auth'. -2. Multiple Words (AND Logic) - query=rate limit - finds knowledge containing both "rate" AND "limit". -3. Quoted Phrases (Exact Position) - query="infinite scroll" - words must be adjacent and in that order. -4. Mixed Queries - query=middleware "rate limit" - "middleware" AND exact phrase "rate limit". -5. Multiple Queries - queries=["authentication", "middleware"] - ANY of these terms. - -=== php rules === - -# PHP - -- Always use curly braces for control structures, even for single-line bodies. - -## Constructors - -- Use PHP 8 constructor property promotion in `__construct()`. - - `public function __construct(public GitHub $github) { }` -- Do not allow empty `__construct()` methods with zero parameters unless the constructor is private. - -## Type Declarations - -- Always use explicit return type declarations for methods and functions. -- Use appropriate PHP type hints for method parameters. - - -```php -protected function isAccessible(User $user, ?string $path = null): bool -{ - ... -} -``` - -## Enums - -- Typically, keys in an Enum should be TitleCase. For example: `FavoritePerson`, `BestLake`, `Monthly`. - -## Comments - -- Prefer PHPDoc blocks over inline comments. Never use comments within the code itself unless the logic is exceptionally complex. - -## PHPDoc Blocks - -- Add useful array shape type definitions when appropriate. - -=== herd rules === - -# Laravel Herd - -- The application is served by Laravel Herd and will be available at: `https?://[kebab-case-project-dir].test`. Use the `get-absolute-url` tool to generate valid URLs for the user. -- You must not run any commands to make the site available via HTTP(S). It is always available through Laravel Herd. - -=== laravel/core rules === - -# Do Things the Laravel Way - -- Use `php artisan make:` commands to create new files (i.e. migrations, controllers, models, etc.). You can list available Artisan commands using the `list-artisan-commands` tool. -- If you're creating a generic PHP class, use `php artisan make:class`. -- Pass `--no-interaction` to all Artisan commands to ensure they work without user input. You should also pass the correct `--options` to ensure correct behavior. - -## Database - -- Always use proper Eloquent relationship methods with return type hints. Prefer relationship methods over raw queries or manual joins. -- Use Eloquent models and relationships before suggesting raw database queries. -- Avoid `DB::`; prefer `Model::query()`. Generate code that leverages Laravel's ORM capabilities rather than bypassing them. -- Generate code that prevents N+1 query problems by using eager loading. -- Use Laravel's query builder for very complex database operations. - -### Model Creation - -- When creating new models, create useful factories and seeders for them too. Ask the user if they need any other things, using `list-artisan-commands` to check the available options to `php artisan make:model`. - -### APIs & Eloquent Resources - -- For APIs, default to using Eloquent API Resources and API versioning unless existing API routes do not, then you should follow existing application convention. - -## Controllers & Validation - -- Always create Form Request classes for validation rather than inline validation in controllers. Include both validation rules and custom error messages. -- Check sibling Form Requests to see if the application uses array or string based validation rules. - -## Authentication & Authorization - -- Use Laravel's built-in authentication and authorization features (gates, policies, Sanctum, etc.). - -## URL Generation - -- When generating links to other pages, prefer named routes and the `route()` function. - -## Queues - -- Use queued jobs for time-consuming operations with the `ShouldQueue` interface. - -## Configuration - -- Use environment variables only in configuration files - never use the `env()` function directly outside of config files. Always use `config('app.name')`, not `env('APP_NAME')`. - -## Testing - -- When creating models for tests, use the factories for the models. Check if the factory has custom states that can be used before manually setting up the model. -- Faker: Use methods such as `$this->faker->word()` or `fake()->randomDigit()`. Follow existing conventions whether to use `$this->faker` or `fake()`. -- When creating tests, make use of `php artisan make:test [options] {name}` to create a feature test, and pass `--unit` to create a unit test. Most tests should be feature tests. - -## Vite Error - -- If you receive an "Illuminate\Foundation\ViteException: Unable to locate file in Vite manifest" error, you can run `npm run build` or ask the user to run `npm run dev` or `composer run dev`. - -=== laravel/v12 rules === - -# Laravel 12 - -- CRITICAL: ALWAYS use `search-docs` tool for version-specific Laravel documentation and updated code examples. -- Since Laravel 11, Laravel has a new streamlined file structure which this project uses. - -## Laravel 12 Structure - -- In Laravel 12, middleware are no longer registered in `app/Http/Kernel.php`. -- Middleware are configured declaratively in `bootstrap/app.php` using `Application::configure()->withMiddleware()`. -- `bootstrap/app.php` is the file to register middleware, exceptions, and routing files. -- `bootstrap/providers.php` contains application specific service providers. -- The `app\Console\Kernel.php` file no longer exists; use `bootstrap/app.php` or `routes/console.php` for console configuration. -- Console commands in `app/Console/Commands/` are automatically available and do not require manual registration. - -## Database - -- When modifying a column, the migration must include all of the attributes that were previously defined on the column. Otherwise, they will be dropped and lost. -- Laravel 12 allows limiting eagerly loaded records natively, without external packages: `$query->latest()->limit(10);`. - -### Models - -- Casts can and likely should be set in a `casts()` method on a model rather than the `$casts` property. Follow existing conventions from other models. - -=== pint/core rules === - -# Laravel Pint Code Formatter - -- If you have modified any PHP files, you must run `vendor/bin/pint --dirty --format agent` before finalizing changes to ensure your code matches the project's expected style. -- Do not run `vendor/bin/pint --test --format agent`, simply run `vendor/bin/pint --format agent` to fix any formatting issues. - -=== phpunit/core rules === - -# PHPUnit - -- This application uses PHPUnit for testing. All tests must be written as PHPUnit classes. Use `php artisan make:test --phpunit {name}` to create a new test. -- If you see a test using "Pest", convert it to PHPUnit. -- Every time a test has been updated, run that singular test. -- When the tests relating to your feature are passing, ask the user if they would like to also run the entire test suite to make sure everything is still passing. -- Tests should cover all happy paths, failure paths, and edge cases. -- You must not remove any tests or test files from the tests directory without approval. These are not temporary or helper files; these are core to the application. - -## Running Tests - -- Run the minimal number of tests, using an appropriate filter, before finalizing. -- To run all tests: `php artisan test --compact`. -- To run all tests in a file: `php artisan test --compact tests/Feature/ExampleTest.php`. -- To filter on a particular test name: `php artisan test --compact --filter=testName` (recommended after making a change to a related file). - -=== tailwindcss/core rules === - -# Tailwind CSS - -- Always use existing Tailwind conventions; check project patterns before adding new ones. -- IMPORTANT: Always use `search-docs` tool for version-specific Tailwind CSS documentation and updated code examples. Never rely on training data. -- IMPORTANT: Activate `tailwindcss-development` every time you're working with a Tailwind CSS or styling-related task. - -