mirror of
https://github.com/kuaifan/dootask.git
synced 2025-12-11 02:12:53 +00:00
89 lines
8.3 KiB
Plaintext
89 lines
8.3 KiB
Plaintext
---
|
||
description: dootask 开发流程与代码结构约定（controller + model + module + Vue2 + ./cmd）
|
||
globs: []
|
||
alwaysApply: true
|
||
---
|
||
|
||
- **整体目标**
|
||
- 统一 dootask 项目的开发流程和代码结构约定，让后续协作、排障和重构更可预期。
|
||
- 为 Cursor 中的 AI 助手提供清晰的「在本仓库应该怎么查代码、怎么改代码、怎么跑命令」的行为规范。
|
||
|
||
- **一、在 Cursor 中处理需求的通用流程**
|
||
- 处理任何一个需求或问题时，AI 助手应优先按下面的步骤行动：
|
||
1. **澄清问题与范围**：从用户问题中提炼出是「Bug 修复」「新功能」「重构」还是「排查/文档」类任务，大概会影响哪些模块（如任务、项目、对话、WebSocket、报表等）。
|
||
2. **定位相关代码**：使用 `grep` / `codebase_search` / `read_file` 等工具，优先阅读路由、控制器、模型、模块，以及前端 `resources/assets/js` 下的相关页面或组件。
|
||
3. **设计修改方案**：在代码层面给出清晰的改动思路（改哪些文件、增加/修改哪些类和方法），必要时在回复中简单说明权衡点。
|
||
4. **实施改动并自检**：通过 `apply_patch` 修改代码，保持控制器+模型+模块结构清晰；需要运行命令时，统一通过 `./cmd ...`（如 `./cmd artisan ...`、`./cmd dev`、`./cmd build` 等），并使用 `read_lints` 等工具做基础检查。
|
||
5. **考虑长期沉淀**：对于「以后会反复遇到」的流程、约束或经验，可以再参考 `001-graphiti-mcp.mdc` 中的约定，选择性地写入 Graphiti（`group_id: "dootask-main"`），但 Graphiti 不是每次任务的必选步骤。
|
||
|
||
- **二、后端代码结构约定：Controller + Model + Module**
|
||
- **Controller（控制器，`app/Http/Controllers`）**
|
||
- 负责：路由入口、参数接收与基础验证、调用对应的模型/模块、最终组装 API 响应。
|
||
- 原则：控制器内尽量保持「薄」，只做请求编排，不堆积复杂业务逻辑。
|
||
- 错误处理：业务异常优先使用 `App\Exceptions\ApiException` 抛出，由全局 Handler 统一转换成标准 JSON 响应。
|
||
- **Model（模型，`app/Models`）**
|
||
- 负责：数据表结构映射、关系定义（relations）、访问器/修改器、自定义查询 Scope 等「数据层」逻辑。
|
||
- 原则：避免在模型方法中塞入大量跨业务的流程控制逻辑，复杂业务应下沉到模块中。
|
||
- **Module（模块，`app/Module`）**
|
||
- 负责：承载跨控制器、跨模型的业务逻辑，以及独立的功能子域。
|
||
- 适用场景示例：
|
||
- 外部服务集成：如 `AgoraIO/*`、`ZincSearch/*` 等第三方接口与搜索封装。
|
||
- 通用工具与能力：如 `Lock.php`（分布式锁）、`RandomColor.php`、`TextExtractor.php`、`Image.php` 等。
|
||
- 业务协作逻辑：项目/任务/对话等领域中，跨多个模型的复杂操作，可抽象为专门的模块方法。
|
||
- 原则：
|
||
- 新增较复杂的业务功能时，优先考虑创建/扩展 Module，而不是在 Controller 或 Model 中堆砌流程。
|
||
- Module 尽量保持「单一职责」与「可复用」，命名上能直接反映其业务或能力作用。
|
||
- 与长期约定的联动：
|
||
- 对于关键 Module（如权限相关、搜索相关、外部系统对接），在设计上应尽量保持单一职责和清晰边界；如需记录长期约定，可参考 `001-graphiti-mcp.mdc` 使用 Graphiti 做补充说明。
|
||
- **运行环境：Laravel + LaravelS（Swoole）**
|
||
- 本项目通过 LaravelS 将 Laravel 运行在 Swoole 常驻进程中，与传统「每请求重启框架」的 PHP-FPM 模式不同。
|
||
- 注意事项（AI 在修改后端代码时需特别留意）：
|
||
- 避免在静态属性、单例、全局变量中存储请求级状态或可变数据，防止请求间数据串联和内存泄漏。
|
||
- 不要假设构造函数、服务提供者或 `boot()` 方法会在每个请求重新执行；涉及配置、路由等的改动，通常需要通过 `./cmd php restart` 或容器重启后才能生效。
|
||
- 编写长连接、定时任务、WebSocket 等长生命周期逻辑时，优先复用现有模式（如 `Services`、`Module` 中的实现），并避免使用会长时间阻塞协程/事件循环的操作。
|
||
|
||
- **三、数据库与迁移约定**
|
||
- 表结构变更必须通过 Laravel migration 完成，禁止直接手工修改数据库结构。
|
||
- 与迁移相关的约定：
|
||
- 创建迁移文件和执行迁移时，优先使用容器内环境，通过 `./cmd artisan ...`（例如 `./cmd artisan make:migration ...`、`./cmd artisan migrate`）。
|
||
- 涉及核心表（项目、任务、对话、用户、权限等）的 schema 变更，应在代码注释、迁移命名和提交信息中尽量说明字段含义与兼容性考虑；如属于长期架构决策，可再结合 `001-graphiti-mcp.mdc` 选择性写入 Graphiti。
|
||
|
||
- **四、前端开发约定：Vue2 + Vite**
|
||
- 主前端代码位于 `resources/assets/js`，基于 Vue2 实现单页应用，结构大致包括：
|
||
- `app.js`、`App.vue`：应用入口与根组件。
|
||
- `components/`：通用组件与业务组件（如任务看板、文件预览、聊天等）。
|
||
- `pages/`：页面级组件（登录、项目管理、任务视图、消息、报表等）。
|
||
- `store/`：全局状态管理。
|
||
- `routes.js`：路由配置。
|
||
- 构建与开发命令：
|
||
- 开发模式：使用 `./cmd dev` 或 `./cmd serve`，内部通过 Vite 启动开发服务器，并自动处理端口与调试模式。
|
||
- 生产构建：使用 `./cmd build` 或 `./cmd prod`，内部使用 `npx vite build` 产出前端静态资源。
|
||
- 与后端接口的协作：
|
||
- 接口调用默认通过 Vuex 的 `call` action 封装：在组件/页面中使用 `this.$store.dispatch("call", {...})` 发起请求；如需新增接口，优先在 `store/actions.js` 中扩展逻辑，而不是在组件中直接调用 `axios/fetch`。
|
||
- 错误提示、登录态失效、权限校验等跨页面行为，尽量复用已有的全局处理逻辑（如 `AIAssistant.vue`、消息通知组件、全局异常组件等）；如形成稳定的新约定，可按需沉淀到文档或 Graphiti。
|
||
|
||
- **五、Electron 相关约定**
|
||
- 当前项目中 Electron 主要作为桌面入口壳，核心业务逻辑仍在 Web/Vue2 前端与 PHP/Laravel 后端。
|
||
- Electron 的构建与开发：
|
||
- 日常开发与调试优先使用 `./cmd electron ...`；仅在需要构建 App 端前端/安装包时，才使用 `./cmd appbuild`。
|
||
- 原则：
|
||
- 优先保证 Web 端行为正确，再通过 Electron 壳复用 Web 逻辑。
|
||
- 若未来扩展 Electron 专有功能（如本地文件访问、系统托盘等），应在代码与文档中说明边界；如属长期约束，可再结合 `001-graphiti-mcp.mdc` 写入 Graphiti。
|
||
|
||
- **六、命令行与开发工具统一通过 `./cmd`**
|
||
- 为了对齐 Docker 环境、避免本地环境差异，项目开发相关命令统一通过根目录的 `./cmd` 脚本执行，包括但不限于：
|
||
- 启动/停止服务：`./cmd up`、`./cmd down`、`./cmd restart`、`./cmd reup`。
|
||
- Laravel 工具：`./cmd artisan ...`（迁移、队列、任务、缓存等）。
|
||
- Composer：`./cmd composer ...`。
|
||
- PHP 命令：`./cmd php ...`。
|
||
- 生成 API 文档：`./cmd doc`。
|
||
- 规则：
|
||
- 在项目文档、脚本示例和与 AI 的交流中，示例命令尽量使用 `./cmd ...` 形式，而不是直接调用 `php`、`composer`、`npm` 等，保持环境一致性。
|
||
- 如需对 `./cmd` 脚本进行较大调整（例如新增开发流程或重构子命令），应在提交信息或说明文档中写清动机和影响范围；如这是长期流程变更，可参考 `001-graphiti-mcp.mdc` 选择性写入 Graphiti。
|
||
|
||
- **七、与 Graphiti 的关系（简要说明）**
|
||
- 本规则文件的重点是「在 Cursor 中如何开发 dootask」；Graphiti 作为「长期记忆」工具，仅在需要跨会话、跨任务复用的信息时才使用。
|
||
- 所有与 dootask 项目相关的 Graphiti 操作应使用 `group_id: "dootask-main"`，具体使用规范见 `001-graphiti-mcp.mdc`。
|
||
- 当 AI 判断某个流程/约束/事实值得长期记忆时，可结合 `001-graphiti-mcp.mdc` 中的说明，主动调用对应 MCP 工具进行写入。
|
||
|