docs(agents): 重构开发流程文档,优化结构并增加详细指引

- 将 AGENTS.md 中的标准开发流程从步骤列表重构为表格形式,并链接到具体技能文件
- 重写 ulthon-scheme-curd-workflow 技能文档,明确区分首次生成和已有业务代码时的安全重新生成流程
- 新增业务定制、验证交付等详细章节,提供完整的检查清单和命令行验证示例
This commit is contained in:
augushong
2026-05-06 19:25:45 +08:00
parent 8b0a59c880
commit e44efb33e0
2 changed files with 116 additions and 49 deletions

View File

@@ -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 命令详解:<https://doc.ulthon.com/read/augushong/ulthon_admin/curd-command/zh-cn/2.x.html>
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. 最终检查 | 页面路径可用、命令行验证通过、代码规范自查 | - |
## 规则维护机制(框架基础 / 使用者补充)