mirror of
https://gitee.com/ulthon/ulthon_admin.git
synced 2026-07-09 19:42:47 +08:00
e44efb33e0
- 将 AGENTS.md 中的标准开发流程从步骤列表重构为表格形式，并链接到具体技能文件 - 重写 ulthon-scheme-curd-workflow 技能文档，明确区分首次生成和已有业务代码时的安全重新生成流程 - 新增业务定制、验证交付等详细章节，提供完整的检查清单和命令行验证示例
184 lines
7.0 KiB
Markdown
184 lines
7.0 KiB
Markdown
---
|
||
name: "ulthon-scheme-curd-workflow"
|
||
description: "指导使用 Scheme 与 CURD 的标准开发流程。需要新增/调整表结构并生成模块基础代码时调用。"
|
||
---
|
||
|
||
# Scheme + CURD 标准工作流
|
||
|
||
## 何时调用
|
||
|
||
- 新增业务表、调整字段、补充索引/注释，并希望保持“代码 <-> 数据库”一致。
|
||
- 准备生成控制器/模型/视图等基础 CRUD 代码。
|
||
|
||
## 关键原则
|
||
|
||
- CURD 生成前，Scheme 与数据库表结构必须完全一致，否则会被拒绝。
|
||
- 业务 Scheme 代码统一放在 `app/admin/scheme/`。
|
||
- 表结构设计遵循项目数据库规范：表名小写下划线、字段注释完整、避免 ENUM。
|
||
- CURD 命令中的 `{table}` 参数应为**不含前缀的下划线**格式（例如：数据库表 `ul_user_profile` 对应的参数为 `user_profile`）。
|
||
- CURD 生成的页面脚本（`index.js` / `add.js` / `edit.js` / `read.js` / `_common.js`）默认与视图文件放在同一目录：`app/admin/view/<模块路径>/`，不提供“输出到其他 JS 目录”的配置项。
|
||
- 一旦你开始在生成代码上做业务改造，就应默认“正式目录不可被覆盖”，后续结构变更需要走“临时生成 + 按需合并”。
|
||
|
||
## CURD 命令参数说明
|
||
|
||
| 参数 | 简写 | 说明 |
|
||
|------|------|------|
|
||
| `--table` | `-t` | 主表名（支持带前缀或不带前缀） |
|
||
| `--force` | `-f` | 强制覆盖模式（**谨慎使用**） |
|
||
| `--delete` | `-d` | 删除模式（**删除生成的文件，不是数据库操作**） |
|
||
| `--runtime` | `-r` | 临时生成模式（**推荐用于预览**） |
|
||
|
||
### 参数使用建议
|
||
|
||
1. **首次生成**：直接使用 `-t` 生成到项目目录
|
||
2. **已有业务代码**：使用 `-r` 生成到临时目录，对比并手动合并新增字段/逻辑
|
||
3. **删除文件**：`-d` 用于清理已生成的文件，不影响数据库
|
||
|
||
## 推荐流程
|
||
|
||
### A. 首次生成（代码未做业务改造）
|
||
|
||
1. 在 `app/admin/scheme/` 新建或修改对应表的 Scheme 类。
|
||
2. 仅查看差异（不改库），确认当前 Scheme 与 DB 的不一致点：
|
||
|
||
```bash
|
||
php think scheme:sync --dry-run
|
||
```
|
||
|
||
3. 执行同步，将代码结构同步到数据库：
|
||
|
||
```bash
|
||
php think scheme:sync
|
||
```
|
||
|
||
4. 生成 CURD（先生成到临时目录确认更稳妥，`{table}` 需使用下划线格式）：
|
||
|
||
```bash
|
||
php think curd -t {table} -r
|
||
```
|
||
|
||
5. 确认无误后正式生成：
|
||
|
||
```bash
|
||
php think curd -t {table}
|
||
```
|
||
|
||
也可以直接使用 `-f` 强制覆盖（首次生成或确认无需保留时）。
|
||
|
||
### B. 以数据库为准
|
||
|
||
1. 在数据库中创建/修改表结构。
|
||
2. 反向生成 Scheme 代码（`{table}` 需使用下划线格式）：
|
||
|
||
```bash
|
||
php think scheme:make -t {table}
|
||
```
|
||
|
||
3. 再执行 CURD：
|
||
|
||
```bash
|
||
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`）跳过交互确认。
|