Skip to content

AGENTS.md

Latest commit

 

History

History
235 lines (204 loc) · 16.4 KB

AGENTS.md

File metadata and controls

235 lines (204 loc) · 16.4 KB
Raw

OpenSpec Instructions

These instructions are for AI assistants working in this project.

Always open @/openspec/AGENTS.md when the request:

  • Mentions planning or proposals (words like proposal, spec, change, plan)
  • Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
  • Sounds ambiguous and you need the authoritative spec before coding

Use @/openspec/AGENTS.md to learn:

  • How to create and apply change proposals
  • Spec format and conventions
  • Project structure and guidelines

Keep this managed block so 'openspec update' can refresh the instructions.

ModStart System Development Guide

Project Overview

This is a Web system built on ModStart framework. It uses Laravel (compatible with Laravel 5.1 and 9.x) for construction, and uses MySQL and Redis for data storage.

Key Principles

  1. Convention over Configuration: Follow ModStart's conventions strictly
  2. Simplicity First: Write clear, maintainable code without over-engineering
  3. Example-Driven: Always reference provided code examples before writing new code
  4. Security: Always validate user input and use prepared statements for database queries

Folder Structure

  • /app: Contains the source code for business.
  • /bootstrap: Contains Laravel bootstrap files, usually not modified.
  • /config: Contains configuration files for the Laravel application.
  • /database: Contains database migrations and seeders.
  • /module: Contains ModStart modules, which are the core features of the system, the system is modularized into different modules for better maintainability.
  • /public: Contains public web assets, including static files and entry points.
  • /resources: Contains resources such as language files and Blade templates.
  • /storage: Contains file storage and cache.
  • /vendor: Contains Composer dependencies, including the ModStart framework.

Coding Standards

  • Do NOT over design the code, keep it simple and easy to understand.
  • You MUST strictly follow the code in "Code Examples Here". Do NOT invent new patterns or freestyle. All development code MUST refer to the examples provided.
  • CRITICAL: Always read the referenced example files FIRST before writing any code. Use the exact patterns, naming conventions, and structures from those examples.
  • When implementing a feature, find the most similar example and adapt it rather than creating from scratch.
  • Ask clarifying questions if requirements are unclear, rather than making assumptions.

PHP Coding Standards

  • Use the php5.6 syntax, Do NOT use the php7+ syntax.
    • Do NOT use: type hints, return types, null coalescing operator (??)
  • Use the ModStart's build-in util in ModStart\Core\Util if available.
    • Util Ref: @/.modstart-agent/manual/util.md
  • Model only contains the table name, Do NOT define any business logic/fillable fields/casts.
  • Use ModStart\Core\Dao\ModelUtil for database operations.
  • Use bcdiv, bcmul, bcadd, bcsub for currency calculations.
  • All Controller name should start with module name, e.g. NewsPaperController or NewsPaperDemoController.
  • Use BizException for all exceptions, Do NOT use Laravel's built-in exception or try-catch, the system will handle BizException globally.
  • Do NOT create test code in the module.
  • Do NOT generate any markdown documentation for code.

Blade Coding Standards

  • Files end with .blade.php is the laravel blade template.
  • Use the SUI and TailwindCSS-custom style framework.
  • ONLY use the SUI and TailwindCSS-custom style classes, DO NOT use any other CSS framework or custom CSS styles.
  • SUI and TailwindCSS-custom Ref: @/.modstart-agent/manual/style.md
  • Follow ModStart's view structure: /View/pc/moduleName/xxx.blade.php for desktop views
  • Use @extends(), @section(), @yield() for layout inheritance

Database Standards

  • Use migrations for all database schema changes.
  • Follow ModStart's migration naming conventions:
    • Create table migration: <timestamp>_<module_name>_<table_name>_create.php
    • Change table migration: <timestamp>_<module_name>_<table_name>_change_N.php
    • Job table migration: <timestamp>_<module_name>_<table_name>_job_create.php
  • Use ModStart\Core\Dao\ModelUtil for all database operations.
  • Use transactions for multi-step database operations to ensure data integrity.
  • DO NOT drop tables or columns in migrations when uninstalling modules, just leave them as is.

Module Structure

Each module located in the /module directory should follow a specific structure to ensure consistency and maintainability. Below is the recommended structure for a module:

/ModuleName
    /Admin # Admin management
        /Controller # Admin controllers
            /ConfigController.php # Admin config controller
            /FooController.php # Admin other controller
        /routes.php # Admin routes
    /Api # API management
        /Controller # API controllers
        /routes.php # API routes
    /Core # Core module files
        /ModuleServiceProvider.php # Module service provider
    /Docs
        /doc
            /FooBar.md # Module documentation
        /module
            /content.md # Module content documentation
            /mobilePreview.md # Mobile preview images, each line should be a absolute path to the image
            /preview.md # Desktop preview images, each line should be a absolute path to the image
            /demo.md # Module demo documentation
        /release.md # Module release notes
    /Migrate # Migration files
        /2025_01_01_000000_module_name_foo_create.php #  table MUST start with <module_name>, create migration ends with _create
        /2025_01_02_000000_module_name_foo_change_1.php # change migration ends with _change_N
        /2025_01_02_000000_module_name_bar_job_create.php # job table SHOULD end with _job
    /Model # Module models
    /Type # Module types, usually extends `ModStart\Core\Type\BaseType`
    /Util # Module utilities
    /Job # Module jobs
        /ModuleNameTestJob.php
    /View # Module views
        /pc
            /moduleName/xxx.blade.php # PC views
    /Web # Web management
        /Controller # Web controllers
        /routes.php # Web routes
    /config.json   # Module configuration file, used to define module metadata

Module Commands

  • php artisan modstart:module-install <ModuleName> : Install a module, including database migration.
  • php artisan modstart:module-enable <ModuleName> : Enable a module.
  • php artisan modstart:module-disable <ModuleName> : Disable a module.
  • php artisan modstart:module-uninstall <ModuleName> : Uninstall a module.
  • php artisan modstart:module-install-all : Install all modules.

Exception Handling - BizException

  • Throw business exceptions using BizException class, the system will handle them globally.
// BizException - 业务异常处理类，系统会全局统一处理
BizException::throws('错误信息'); // 直接抛出业务异常
BizException::throws('参数错误', ['statusCode' => 404]); // 带自定义状态码
BizException::throws('错误', ['view' => 'theme.default.error', 'viewData' => ['foo' => 'bar']]); // 使用自定义视图模板
BizException::throwsIf('条件错误', $condition); // 条件为真时抛出异常
BizException::throwsIfEmpty('记录不存在', $record); // 对象为空时抛出异常
BizException::throwsIfNotEmpty('数据已存在', $existRecord); // 对象不为空时抛出异常
BizException::throwsIfResponseError($response); // 响应有错误时抛出异常
// 异常消息匹配
BizException::throwsIfMessageMatch($error, [
    'Duplicate entry' => '数据重复',
    'Connection refused' => '连接失败'
], '数据库错误：');

Code Examples Here

You MUST refer to the following demo code sources:

  • 注册管理菜单，注册Widget链接: @/.modstart-agent/sources/module/Demo/Core/ModuleServiceProvider.php
  • 测试工具类，清除缓存，获取测试数据: @/.modstart-agent/sources/module/Demo/Util/DemoTestUtil.php
  • 本模块URL封装: @/.modstart-agent/sources/module/Demo/Util/UrlUtil.php
  • 清除缓存，获取分类数据，构建树形结构，获取分类链: @/.modstart-agent/sources/module/Demo/Util/DemoTestCategoryUtil.php
  • 显示演示首页，检查会员登录: @/.modstart-agent/sources/module/Demo/Web/Controller/DemoController.php
  • 显示测试列表，显示测试详情: @/.modstart-agent/sources/module/Demo/Web/Controller/DemoTestController.php
  • 定义前台页面路由: @/.modstart-agent/sources/module/Demo/Web/routes.php
  • ****: @/.modstart-agent/sources/module/Demo/config.json
  • 模块前端样式Webpack配置: @/.modstart-agent/sources/module/Demo/resources/asset/webpack.config.js
  • ****: @/.modstart-agent/sources/module/Demo/resources/asset/package.json
  • 模块前端样式Gulp配置: @/.modstart-agent/sources/module/Demo/resources/asset/gulpfile.js
  • 模块样式代码: @/.modstart-agent/sources/module/Demo/resources/asset/src/js/Xxxx/xxx.css
  • 模块脚本代码: @/.modstart-agent/sources/module/Demo/resources/asset/src/js/Xxxx/xxx.js
  • 加载ECharts，处理任务统计请求，权限控制: @/.modstart-agent/sources/module/Demo/Admin/Widget/TasksWidget.php
  • ****: @/.modstart-agent/sources/module/Demo/Admin/Widget/DevicesWidget.vue
  • 加载ECharts，处理设备统计请求，权限控制: @/.modstart-agent/sources/module/Demo/Admin/Widget/DevicesWidget.php
  • 加载ECharts，处理任务统计请求，权限控制: @/.modstart-agent/sources/module/Demo/Admin/Widget/TasksWidget.vue
  • 渲染版权信息视图: @/.modstart-agent/sources/module/Demo/Admin/Widget/DemoCopyrightWidget.php
  • 加载ECharts，处理用户统计请求，权限控制: @/.modstart-agent/sources/module/Demo/Admin/Widget/UsersWidget.vue
  • 加载ECharts，处理用户统计请求，权限控制: @/.modstart-agent/sources/module/Demo/Admin/Widget/UsersWidget.php
  • 配置树状数据表格，管理测试分类: @/.modstart-agent/sources/module/Demo/Admin/Controller/GridTreeController.php
  • 显示404页面，显示500页面: @/.modstart-agent/sources/module/Demo/Admin/Controller/FrontPageController.php
  • 配置动态显示表单，演示条件字段: @/.modstart-agent/sources/module/Demo/Admin/Controller/FormDynamicController.php
  • 显示开发者文档和链接: @/.modstart-agent/sources/module/Demo/Admin/Controller/DocController.php
  • 复杂布局表单控制器，演示表单的复杂布局和面板: @/.modstart-agent/sources/module/Demo/Admin/Controller/FormLayoutController.php
  • Tailwind CSS控制器，演示Tailwind CSS样式: @/.modstart-agent/sources/module/Demo/Admin/Controller/FrontTwController.php
  • 后台任务调度控制器，演示任务调度的管理: @/.modstart-agent/sources/module/Demo/Admin/Controller/AppTestJobController.php
  • 复杂数据导入控制器，演示数据导入功能: @/.modstart-agent/sources/module/Demo/Admin/Controller/AppImportController.php
  • 默认数据表单控制器，演示表单的基本使用和保存处理: @/.modstart-agent/sources/module/Demo/Admin/Controller/FormController.php
  • 数据统计卡片控制器，演示数据统计卡片的显示: @/.modstart-agent/sources/module/Demo/Admin/Controller/WidgetController.php
  • 页面布局控制器，演示栅格布局的使用: @/.modstart-agent/sources/module/Demo/Admin/Controller/FrontLayoutController.php
  • Vue单文件Widget控制器，演示Vue组件式Widget: @/.modstart-agent/sources/module/Demo/Admin/Controller/WidgetVueController.php
  • Vue+ElementUI集成控制器，演示Vue组件集成: @/.modstart-agent/sources/module/Demo/Admin/Controller/FrontVueController.php
  • 多个数据表格控制器，演示多个独立Grid的处理: @/.modstart-agent/sources/module/Demo/Admin/Controller/GridMultiController.php
  • 独立控制表格控制器，提供测试数据的表格、表单和详情页面的独立定制: @/.modstart-agent/sources/module/Demo/Admin/Controller/GridRawController.php
  • ECharts集成控制器，演示图表组件的使用: @/.modstart-agent/sources/module/Demo/Admin/Controller/FrontEchartController.php
  • 基础示例控制器，演示Tailwind CSS: @/.modstart-agent/sources/module/Demo/Admin/Controller/FrontBasicController.php
  • 默认数据表格控制器，提供测试数据的CRUD操作和导入功能: @/.modstart-agent/sources/module/Demo/Admin/Controller/GridController.php
  • 自定义视图控制器，演示Grid自定义条目显示: @/.modstart-agent/sources/module/Demo/Admin/Controller/GridCustomItemController.php
  • 表格自定义控制器，提供批量操作和自定义操作: @/.modstart-agent/sources/module/Demo/Admin/Controller/GridOperateController.php
  • Icon图标控制器，演示图标的使用: @/.modstart-agent/sources/module/Demo/Admin/Controller/FrontIconController.php
  • 系统配置表单控制器，演示配置项的读取和保存: @/.modstart-agent/sources/module/Demo/Admin/Controller/FormConfigController.php
  • 弹窗表单控制器，演示表单在弹窗中的使用: @/.modstart-agent/sources/module/Demo/Admin/Controller/FormDialogController.php
  • 表单所有组件控制器，演示所有表单字段组件: @/.modstart-agent/sources/module/Demo/Admin/Controller/FormFieldController.php
  • 静态Widget控制器，演示静态Widget的使用: @/.modstart-agent/sources/module/Demo/Admin/Controller/WidgetStaticController.php
  • 管理后台路由文件，定义各种控制器路由: @/.modstart-agent/sources/module/Demo/Admin/routes.php
  • 模块说明Markdown文件: @/.modstart-agent/sources/module/Demo/Docs/module/content.md
  • 手机预览图: @/.modstart-agent/sources/module/Demo/Docs/module/mobilePreview.md
  • PC预览图: @/.modstart-agent/sources/module/Demo/Docs/module/preview.md
  • 模块更新说明: @/.modstart-agent/sources/module/Demo/Docs/release.md
  • 多语言示例: @/.modstart-agent/sources/module/Demo/Lang/zh.php
  • 多语言示例: @/.modstart-agent/sources/module/Demo/Lang/en.php
  • 类型定义类: @/.modstart-agent/sources/module/Demo/Type/DemoType.php
  • 测试任务表创建迁移: @/.modstart-agent/sources/module/Demo/Migrate/2021_09_26_000000_demo_test_job_create.php
  • 测试表创建迁移: @/.modstart-agent/sources/module/Demo/Migrate/2021_09_26_000000_demo_test_create.php
  • 测试分类表创建迁移: @/.modstart-agent/sources/module/Demo/Migrate/2021_09_26_000000_demo_test_category_create.php
  • 测试分类表变更迁移1: @/.modstart-agent/sources/module/Demo/Migrate/2021_09_27_000000_demo_test_category_change_1.php
  • 测试数据模型: @/.modstart-agent/sources/module/Demo/Model/DemoTest.php
  • 测试任务数据模型: @/.modstart-agent/sources/module/Demo/Model/DemoTestJob.php
  • 测试分类数据模型: @/.modstart-agent/sources/module/Demo/Model/DemoTestCategory.php
  • 测试运行任务类，演示后台任务的执行: @/.modstart-agent/sources/module/Demo/Job/DemoTestRunJob.php
  • 演示首页，展示测试分类、内容、配置、多语言、模块集成: @/.modstart-agent/sources/module/Demo/View/pc/demo/index.blade.php
  • 测试详情展示: @/.modstart-agent/sources/module/Demo/View/pc/demo/testShow.blade.php
  • 会员登录要求页面，用户信息展示: @/.modstart-agent/sources/module/Demo/View/pc/demo/memberLoginRequired.blade.php
  • 测试列表: @/.modstart-agent/sources/module/Demo/View/pc/demo/test.blade.php
  • 自定义组件: @/.modstart-agent/sources/module/Demo/View/inc/testWidget.blade.php
  • 自定义组件（支持其他模块调用）: @/.modstart-agent/sources/module/Demo/View/DemoView.php
  • 数据导入功能: @/.modstart-agent/sources/module/Demo/View/admin/app/import.blade.php
  • 版权信息及链接展示: @/.modstart-agent/sources/module/Demo/View/admin/widget/copyright.blade.php
  • Vue+ElementUI 集成示例: @/.modstart-agent/sources/module/Demo/View/admin/front/vue.blade.php
  • 图标列表展示，支持复制: @/.modstart-agent/sources/module/Demo/View/admin/front/icon.blade.php
  • 测试分类API控制器: @/.modstart-agent/sources/module/Demo/Api/Controller/DemoTestCategoryController.php
  • 测试API控制器: @/.modstart-agent/sources/module/Demo/Api/Controller/DemoTestController.php
  • API路由文件，定义API接口路由: @/.modstart-agent/sources/module/Demo/Api/routes.php