feat: 新增模块设计模板(design.md+skill/SKILL.md)——统一模块设计结构,design产出用模板保证develop读到一致结构
This commit is contained in:
parent
4939d7cb52
commit
d744fd962b
@ -66,6 +66,10 @@ modules/<模块名>/
|
||||
|
||||
**原则**: 数据、CRUD、处理逻辑、skills 都属于模块本身,不放在应用级 design 里,这样模块可整体复用(换个应用直接带着自己的数据/逻辑/skills 一起加载)。
|
||||
|
||||
**模板**: 设计产出用统一模板,保证 develop 读到的每个模块设计结构一致——
|
||||
- `design.md` 模板 → `templates/module-design.md`(模块元信息 / 数据设计→models / CRUD→json / 处理逻辑→dspy / 入口菜单)
|
||||
- `skill/SKILL.md` 模板 → `templates/module-skill.md`(frontmatter / 概述 / 数据模型 / 关键接口 / 陷阱 / 依赖)
|
||||
|
||||
## 应用说明文件 `apps/<应用名>.md`
|
||||
|
||||
```markdown
|
||||
|
||||
@ -0,0 +1,74 @@
|
||||
# <模块名> 模块设计
|
||||
|
||||
> 本文件由 design 阶段设计师产出,develop 工程师据此实现。数据/CRUD/处理逻辑/skills 都属于本模块,模块可整体复用。
|
||||
|
||||
## 1. 模块元信息
|
||||
|
||||
| 项 | 值 |
|
||||
|----|----|
|
||||
| 模块名 | <模块名> |
|
||||
| 功能 | <一句话描述模块职责> |
|
||||
| 技术栈 | <如:Python + sqlor(数据)+ ahserver(HTTP)+ bricks(前端)> |
|
||||
| 仓库 | git@git.opencomputing.cn:org/<模块名>.git |
|
||||
| 依赖模块 | <列出依赖的其他模块,如 rbac(权限)、appbase(配置)、sqlor(数据)> |
|
||||
| 开发顺序 | <拓扑序位置,说明须先开发哪些依赖模块> |
|
||||
|
||||
## 2. 数据设计(实现为 models/<表名>.json)
|
||||
|
||||
> 表定义格式遵循 `database-table-definition-spec`:根键 summary/fields/indexes/codes。
|
||||
> 字段类型用抽象类型(str/int/double/date/timestamp/text…),不用数据库原生类型。
|
||||
|
||||
### 表 `<表名1>`(<表标题>)
|
||||
|
||||
| 字段 | 类型 | 长度/精度 | 可空 | 默认 | 说明 |
|
||||
|------|------|----------|------|------|------|
|
||||
| id | str | 32 | no | - | 主键 |
|
||||
| <字段> | <类型> | <长度> | <yes/no> | <默认> | <说明> |
|
||||
|
||||
- **主键**: `["id"]`
|
||||
- **索引**: `<唯一/普通索引,如 idx_<表名>_<字段> unique(<字段>)>`
|
||||
- **字典/外键(codes)**: `<如 status → appcodes_kv(cond 用 parentid='<字典组名>')、org_id → organization>`
|
||||
|
||||
### 表 `<表名2>`(<表标题>)
|
||||
|
||||
(同上,每张表一段)
|
||||
|
||||
## 3. CRUD 设计(实现为 json/<alias>.json)
|
||||
|
||||
> CRUD 格式遵循 `crud-definition-spec`:根键 tblname/params(browserfields/editable/subtables/data_filter)。
|
||||
|
||||
### 界面 `<alias>`(表 `<表名>`)
|
||||
|
||||
- **视图类型**: list / tree
|
||||
- **列表展示**: <browserfields,说明展示哪些字段>
|
||||
- **隐藏字段**: <exclouded,如 id、敏感字段>
|
||||
- **编辑排除**: <editexclouded,如 created_at、org_id 等系统字段>
|
||||
- **下拉字段(alters)**: <如 status→appcodes、providerid→organization,说明数据源>
|
||||
- **子表(subtables)**: <如 field=父表外键 subtable=子表,url 用 ../alias>
|
||||
- **过滤/搜索(data_filter)**: <如按 org_id 隔离、按名称 LIKE>
|
||||
- **权限隔离**: <logined_userorgid / logined_userid 指向哪个字段>
|
||||
|
||||
### 界面 `<alias2>`(表 `<表名2>`)
|
||||
|
||||
(同上)
|
||||
|
||||
## 4. 处理逻辑 / 接口设计(实现为 wwwroot/api/*.dspy)
|
||||
|
||||
> dspy 格式遵循 `dspy-file-implementation-spec`:用 sor.C/U/D/R/I/sqlExe,return 显式,禁用 import/print/uuid。
|
||||
|
||||
### 接口 `<名>.dspy`
|
||||
|
||||
- **用途**: <一句话>
|
||||
- **输入**: <参数列表>
|
||||
- **逻辑**: <处理步骤,含权限校验、数据校验、事务>
|
||||
- **输出**: <返回结构,如 [{value,text}]、widget、或 {success:...}>
|
||||
|
||||
### 接口 `<名2>.dspy`
|
||||
|
||||
(同上)
|
||||
|
||||
## 5. 模块入口 / 菜单
|
||||
|
||||
- **index.ui**: <模块主页,卡片导航到各 CRUD/功能页,用 {{entire_url(...)}}>
|
||||
- **菜单归属**: <系统菜单(app.xxx TabPanel)/ 用户菜单(Popup)>
|
||||
- **RBAC**: <模块路径声明 + 应用 conf/rp.json 定义 role→path + import_rp.py 幂等导入>
|
||||
@ -0,0 +1,30 @@
|
||||
---
|
||||
name: <模块名>
|
||||
version: 1.0.0
|
||||
description: <模块一句话描述 + 何时加载(触发条件)>
|
||||
trigger_conditions:
|
||||
- <开发/维护 <模块名> 模块时>
|
||||
- <涉及该模块的数据表/接口/前端时>
|
||||
---
|
||||
|
||||
# <模块名> 模块
|
||||
|
||||
## 概述
|
||||
|
||||
<模块职责、定位、核心功能。让 develop agent 一眼看懂这个模块是干什么的、解决什么问题。>
|
||||
|
||||
## 数据模型
|
||||
|
||||
<核心表及其关系,引用 models/ 下的表。可用表格或列表说明每张表的用途和关键字段。>
|
||||
|
||||
## 关键接口
|
||||
|
||||
<主要 API / 处理逻辑,引用 wwwroot/api/ 下的 dspy。说明每个接口的输入/输出/用途。>
|
||||
|
||||
## 实现要点 / 陷阱
|
||||
|
||||
<开发此模块时的注意事项、已踩过的坑、必须遵循的约定(如 sqlor 用 sor.C/U/D/R/I/sqlExe、dspy 显式 return、CRUD 根键 tblname、id 用 getID() 等)。>
|
||||
|
||||
## 依赖
|
||||
|
||||
<依赖的基础模块(apppublic/sqlor/ahserver/accounting/appbase/rbac)和第三方模块,以及本模块对它们的使用方式。>
|
||||
Loading…
x
Reference in New Issue
Block a user