feat: 新增模块设计模板(design.md+skill/SKILL.md)——统一模块设计结构,design产出用模板保证develop读到一致结构

This commit is contained in:
yumoqing 2026-08-19 23:14:39 +08:00
parent 4939d7cb52
commit d744fd962b
3 changed files with 108 additions and 0 deletions

View File

@ -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

View File

@ -0,0 +1,74 @@
# <模块名> 模块设计
> 本文件由 design 阶段设计师产出develop 工程师据此实现。数据/CRUD/处理逻辑/skills 都属于本模块,模块可整体复用。
## 1. 模块元信息
| 项 | 值 |
|----|----|
| 模块名 | <模块名> |
| 功能 | <一句话描述模块职责> |
| 技术栈 | <Python + sqlor数据+ ahserverHTTP+ 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_kvcond 用 parentid='<字典组名>'、org_id → organization>`
### 表 `<表名2>`<表标题>
(同上,每张表一段)
## 3. CRUD 设计(实现为 json/<alias>.json
> CRUD 格式遵循 `crud-definition-spec`:根键 tblname/paramsbrowserfields/editable/subtables/data_filter
### 界面 `<alias>`(表 `<表名>`
- **视图类型**: list / tree
- **列表展示**: <browserfields说明展示哪些字段>
- **隐藏字段**: <exclouded id敏感字段>
- **编辑排除**: <editexclouded created_atorg_id 等系统字段>
- **下拉字段alters**: < statusappcodesprovideridorganization说明数据源>
- **子表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/sqlExereturn 显式,禁用 import/print/uuid。
### 接口 `<名>.dspy`
- **用途**: <一句话>
- **输入**: <参数列表>
- **逻辑**: <处理步骤含权限校验数据校验事务>
- **输出**: <返回结构 [{value,text}]、widget {success:...}>
### 接口 `<名2>.dspy`
(同上)
## 5. 模块入口 / 菜单
- **index.ui**: <模块主页卡片导航到各 CRUD/功能页 {{entire_url(...)}}>
- **菜单归属**: <系统菜单app.xxx TabPanel/ 用户菜单Popup>
- **RBAC**: <模块路径声明 + 应用 conf/rp.json 定义 rolepath + import_rp.py 幂等导入>

View File

@ -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/sqlExedspy 显式 returnCRUD 根键 tblnameid getID() >
## 依赖
<依赖的基础模块apppublic/sqlor/ahserver/accounting/appbase/rbac和第三方模块以及本模块对它们的使用方式>