From e44efb33e02980c8c9b5b51229fe52657cb4e815 Mon Sep 17 00:00:00 2001 From: augushong Date: Wed, 6 May 2026 19:25:45 +0800 Subject: [PATCH] =?UTF-8?q?docs(agents):=20=E9=87=8D=E6=9E=84=E5=BC=80?= =?UTF-8?q?=E5=8F=91=E6=B5=81=E7=A8=8B=E6=96=87=E6=A1=A3=EF=BC=8C=E4=BC=98?= =?UTF-8?q?=E5=8C=96=E7=BB=93=E6=9E=84=E5=B9=B6=E5=A2=9E=E5=8A=A0=E8=AF=A6?= =?UTF-8?q?=E7=BB=86=E6=8C=87=E5=BC=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 将 AGENTS.md 中的标准开发流程从步骤列表重构为表格形式，并链接到具体技能文件 - 重写 ulthon-scheme-curd-workflow 技能文档，明确区分首次生成和已有业务代码时的安全重新生成流程 - 新增业务定制、验证交付等详细章节，提供完整的检查清单和命令行验证示例 --- .../ulthon-scheme-curd-workflow/SKILL.md | 122 +++++++++++++++--- AGENTS.md | 43 ++---- 2 files changed, 116 insertions(+), 49 deletions(-) diff --git a/.agents/skills/ulthon-scheme-curd-workflow/SKILL.md b/.agents/skills/ulthon-scheme-curd-workflow/SKILL.md index 647a0f5..34592a6 100644 --- a/.agents/skills/ulthon-scheme-curd-workflow/SKILL.md +++ b/.agents/skills/ulthon-scheme-curd-workflow/SKILL.md @@ -36,7 +36,7 @@ description: "指导使用 Scheme 与 CURD 的标准开发流程。需要新增/ ## 推荐流程 -### A. 以代码为准（推荐） +### A. 首次生成（代码未做业务改造） 1. 在 `app/admin/scheme/` 新建或修改对应表的 Scheme 类。 2. 仅查看差异（不改库），确认当前 Scheme 与 DB 的不一致点： @@ -44,38 +44,26 @@ description: "指导使用 Scheme 与 CURD 的标准开发流程。需要新增/ ```bash php think scheme:sync --dry-run ``` -2. 执行同步，将代码结构同步到数据库： + +3. 执行同步，将代码结构同步到数据库： ```bash php think scheme:sync ``` -3. 生成 CURD（先生成到临时目录确认更稳妥，`{table}` 需使用下划线格式）： +4. 生成 CURD（先生成到临时目录确认更稳妥，`{table}` 需使用下划线格式）： ```bash php think curd -t {table} -r ``` -4. 初次接入（代码还未做业务改造）可选择正式生成或覆盖： +5. 确认无误后正式生成： ```bash php think curd -t {table} -php think curd -t {table} -f ``` -### A2. 已经做过业务改造时的推荐做法（临时生成 + 按需合并） - -适用场景：你已经修改过 CURD 生成的控制器/模型/视图/JS 等代码，此时再次 `-f` 覆盖会丢失业务改动。 - -1. 先完成结构同步（`scheme:sync` 或 `scheme:make`），确保与数据库一致。 -2. 始终生成到临时目录： - -```bash -php think curd -t {table} -r -``` - -3. 对比临时目录与正式目录的差异，仅把“新增字段/新增校验/新增表单项/新增列表列”等结构性变更按需合并回正式代码。 -4. 合并后再做一次功能自测，重点验证新增字段的新增/编辑/列表/详情与校验链路。 +也可以直接使用 `-f` 强制覆盖（首次生成或确认无需保留时）。 ### B. 以数据库为准 @@ -92,6 +80,104 @@ php think scheme:make -t {table} php think curd -t {table} -r ``` +## 已有业务代码时如何安全重新生成（核心能力） + +> 框架的 CURD 机制支持在任何阶段安全地重新生成代码。这是与其他很多系统的关键区别：其他系统要么不推荐重新生成，要么重新生成会直接覆盖已有改动。 + +### 场景 + +你已经基于 CURD 生成的代码做了业务定制（改过控制器逻辑、视图布局、JS 交互等），现在需要新增或调整字段。 + +### 错误做法 + +直接 `curd -t {table} -f` 强制覆盖 -- 会丢失所有业务改动。 + +### 正确做法（临时生成 + 按需合并） + +1. 先修改 Scheme 并同步结构（确保 Scheme 与 DB 一致）： + +```bash +php think scheme:sync +``` + +2. 生成到临时目录（**不影响正式代码**）： + +```bash +php think curd -t {table} -r +``` + +3. 对比临时目录与正式目录的差异，仅将结构性变更按需合并回正式代码： + - 新增字段对应的列表列、表单项、校验规则 + - 新增字段在模型中的属性声明 + - 其他自动生成的配置（如关联关系、组件类型） + +4. 合并后做一次功能自测，重点验证新增字段在新增/编辑/列表/详情中的完整链路。 + +### 临时目录位置 + +使用 `-r` 参数时，生成的文件会输出到 `runtime/curd/` 目录下，按表名组织，可直接与 `app/` 下的正式代码对比。 + +## 业务定制（生成后必做） + +CURD 生成的代码是标准化骨架，实际业务几乎都需要在此基础上调整。所有修改仅在 `app/` 目录进行。 + +### 生成物说明 + +一次 CURD 会生成以下文件（路径以 `app/admin/` 为基准）： + +| 类型 | 路径 | 说明 | +|------|------|------| +| 控制器 | `controller/<模块路径>.php` | 列表/新增/编辑/详情/删除等动作 | +| 模型 | `model/<表名>.php` | 字段定义、关联、获取器等 | +| 视图 | `view/<模块路径>/index.html` 等 | 列表页、新增/编辑/详情页 | +| JS 脚本 | `view/<模块路径>/index.js` 等 | 与视图同名配对的页面脚本 | +| 公共脚本 | `view/<模块路径>/_common.js` | 模块级公共逻辑 | + +### 逐页检查清单 + +1. **列表页（index）**：列展示字段、搜索项、行操作按钮（编辑/删除/详情等）、顶部工具栏按钮（新增等） +2. **新增/编辑页（add/edit）**：表单字段、校验规则、默认值、关联数据加载 +3. **详情页（read）**：展示字段与格式 +4. **公共逻辑（_common.js）**：模块级事件绑定与共享函数 + +### 接口需求 + +如需让页面同时支持 JSON 输出（供移动端/前端调用），使用"页面/接口同体机制"，详见 [ulthon-page-api-dual-mode](./ulthon-page-api-dual-mode/SKILL.md)。 + +## 验证与交付 + +### 功能验证 + +用 `tools:http:call` 在命令行模拟已登录管理员请求，验证增删改查链路： + +```bash +# 列表 +php think tools:http:call --url="/admin/<模块路径>/index" --method=GET +# 新增 +php think tools:http:call --url="/admin/<模块路径>/add" --method=POST --data='{"title":"测试"}' +# 编辑 +php think tools:http:call --url="/admin/<模块路径>/edit" --method=POST --data='{"id":1,"title":"修改后"}' +# 详情 +php think tools:http:call --url="/admin/<模块路径>/read?id=1" --method=GET +# 删除 +php think tools:http:call --url="/admin/<模块路径>/delete" --method=POST --data='{"id":1}' +``` + +异常时用 `php think tools:log:*` 追踪，详见 [ulthon-tools-http-call](./ulthon-tools-http-call/SKILL.md)。 + +### 功能配套 + +- **菜单**：用 `admin:menu:*` 新增/调整菜单，与页面路径/节点保持一致。详见 [ulthon-admin-menu-cli](./ulthon-admin-menu-cli/SKILL.md)。 +- **权限**：用 `admin:permission:nodes` 生成/核对节点，为角色分配节点并为用户分配角色。详见 [ulthon-permission-cli](./ulthon-permission-cli/SKILL.md)。 +- **数据库排错**：必要时用 `tools:db:*` 做只读检查，详见 [ulthon-db-tools-debug](./ulthon-db-tools-debug/SKILL.md)。 + +### 交付检查 + +- [ ] 后台页面：列表/表单/详情/删除等核心路径可用 +- [ ] 命令行验证：增删改查已通过 tools 命令跑通 +- [ ] 代码规范：按仓库根目录 `.php-cs-fixer.php` 约束自查 +- [ ] 菜单与权限：已配置且符合预期 + ## 交互提示 - 命令行工具通常支持 `--force-force`（`-ff`）跳过交互确认。 diff --git a/AGENTS.md b/AGENTS.md index e5a66fc..764d68d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -53,37 +53,18 @@ ### 标准开发流程（Scheme + CURD，默认必须执行） -1. 初始化开发环境（必须提前完成） - - 按项目文档完成：依赖安装、`.env` 配置、数据库连接与基础数据初始化、确保 `php think` 可用 - - 需要命令行联调与验证时，确保本地 CLI 与服务端使用同一套环境配置（尤其是缓存与数据库） -2. 设计/调整表结构（Scheme） - - 严格遵循表结构设计规范 - - 优先通过 Scheme 机制在 `app/admin/scheme/` 代码化维护表结构（避免 ENUM） -3. 同步并确保一致（Scheme <-> DB） - - 以代码为准（推荐）：`php think scheme:sync` - - 以数据库为准：`php think scheme:make -t {table}` - - 生成 CURD 前，Scheme 与数据库结构必须完全一致，否则会被拒绝 - - 数据调试仅用于排错：`php think tools:db:*`（不要用来“设计表结构”） -4. 生成基础代码（CURD），重要，只要是数据库表的功能开发，必须使用CURD机制生成代码。 - - 推荐先生成到临时目录确认：`php think curd -t {table} -r` - - 确认无误后再正式生成/覆盖：`php think curd -t {table}` / `php think curd -t {table} -f` - - 一旦开始在生成代码上做业务改造，后续结构变更默认走“临时生成 + 按需合并”，避免 `-f` 覆盖丢失业务修改 - - CURD 命令详解： -5. 业务代码定制（仅改 `app/`） - - 在生成代码基础上进行修改，仅操作 `app/` 目录 - - CURD 页面不仅包含列表表格页，还会生成若干配套页面/脚本；需要结合业务逐页检查与调整：按钮、字段展示、搜索项、表单校验、交互流程等 - - 如涉及接口输出或客户端（uni-app / Vue 等）调用，优先使用“页面 / 接口同体机制”，并确保同一路由在 HTML 与 JSON 两种模式下都符合预期 -6. 用内置 tools 与 CLI 完成功能验证（把增删改查跑通） - - 用 `php think tools:http:call` 在命令行模拟已登录管理员请求，验证列表/详情/新增/编辑/删除链路与返回结构 - - 必要时用 `php think tools:log:*` 定位异常、追踪请求链路与数据变化 -7. 完成功能配套（按需） - - 菜单管理：新增/调整菜单（`php think admin:menu:*`），并与页面路径/节点保持一致 - - 权限管理：基于 `auth` 注解生成/核对节点（`php think admin:permission:nodes`），为角色分配节点并为用户分配角色（`php think admin:role:*` / `php think admin:user:role:*`） - - 数据库排错：必要时使用 `php think tools:db:*` 做只读检查或最小化变更 -8. 最终检查与交付（完成“新功能开发”的定义） - - 后台页面：列表/表单/详情/删除等核心路径可用，交互与权限符合预期 - - 命令行验证：接口增删改查已通过 tools 命令跑通，关键异常可通过日志命令回溯 - - 代码规范：按仓库根目录 `.php-cs-fixer.php` 约束自查，避免引入不符合规范的写法 +> 完整操作细节见对应技能文件，本节仅列出流程骨架与核心约束。 + +| 步骤 | 说明 | 对应技能 | +|------|------|----------| +| 1. 初始化环境 | 依赖安装、`.env` 配置、数据库初始化、确保 `php think` 可用 | - | +| 2. 设计表结构 | 在 `app/admin/scheme/` 中编写 Scheme 类；遵循表结构设计规范 | [ulthon-scheme-definition](./.agents/skills/ulthon-scheme-definition/SKILL.md) | +| 3. 同步 Scheme 与 DB | `scheme:sync`（以代码为准）或 `scheme:make`（以 DB 为准）；**CURD 生成前两者必须一致** | [ulthon-scheme-curd-workflow](./.agents/skills/ulthon-scheme-curd-workflow/SKILL.md) | +| 4. 生成 CURD 代码 | `curd -t {table}`；后续字段变更可安全重新生成（`-r` 临时目录对比合并，不覆盖已改造的业务代码） | [ulthon-scheme-curd-workflow](./.agents/skills/ulthon-scheme-curd-workflow/SKILL.md) | +| 5. 业务定制 | 仅改 `app/`；逐页调整按钮/字段/表单/交互；接口需求用页面接口同体机制 | [ulthon-page-api-dual-mode](./.agents/skills/ulthon-page-api-dual-mode/SKILL.md) | +| 6. 功能验证 | `tools:http:call` 模拟请求跑通增删改查；`tools:log:*` 排查异常 | [ulthon-tools-http-call](./.agents/skills/ulthon-tools-http-call/SKILL.md) | +| 7. 功能配套 | 菜单（`admin:menu:*`）、权限节点（`admin:permission:nodes`）、角色分配 | [ulthon-admin-menu-cli](./.agents/skills/ulthon-admin-menu-cli/SKILL.md)、[ulthon-permission-cli](./.agents/skills/ulthon-permission-cli/SKILL.md) | +| 8. 最终检查 | 页面路径可用、命令行验证通过、代码规范自查 | - | ## 规则维护机制（框架基础 / 使用者补充）