feat: 新增 develop 角色技能 module-development + project-directory-spec 模块结构改引用 module-development-spec
- 新增 develop 角色技能（pipelines/sdlc_general/roles/agent.develop/module-development）， 把模块开发规范写进角色技能而非 system_prompt：模块目录结构(包目录=模块名)、 init.py三处同步、表定义四段式/CRUD格式、RBAC load_path、模块skill文档、sqlor标准API - project-directory-spec 的模块仓库结构(src/ddl)改为引用 module-development-spec，消除两本规范冲突 - 这样用户用缺省开发产线(sdlc_general)做开发时，develop 角色自动加载该技能遵守规范， 其他公司可复用机制也可定制自己的角色技能
This commit is contained in:
parent
304acab965
commit
4b8823f774
@ -78,15 +78,7 @@ global（全局基础）→ org（客户）→ pipeline（产线）→ project
|
||||
- 存放一个独立模块的代码（可复用单元，含自己的数据 / CRUD / 处理逻辑 / skills）。
|
||||
- 一个模块一个仓库，命名 `{模块名}`（无后缀），由 design 阶段划分。
|
||||
- 有远程 git 仓库。
|
||||
- 内部结构（参考）：
|
||||
```
|
||||
{模块名}/
|
||||
├── README.md
|
||||
├── src/ # 源码
|
||||
├── ddl/ # 表结构 DDL
|
||||
├── init/ # 初始化数据
|
||||
└── selftest.py # 自测
|
||||
```
|
||||
- 内部结构以 `module-development-spec` 技能为准（Python 包目录=模块名 + wwwroot/models/json/init/scripts/skill/pyproject.toml），本规范不重复定义。
|
||||
|
||||
## 四、命名规范
|
||||
|
||||
@ -109,7 +101,7 @@ global（全局基础）→ org（客户）→ pipeline（产线）→ project
|
||||
| requirement | 应用部署单元定义 | `repos/{项目名}_pc/apps/{应用名}.md` |
|
||||
| design | 系统架构 / UI 设计 | `repos/{项目名}_pc/docs/01-design/architecture.md`、`ui-design.md` |
|
||||
| design | 模块清单 + 模块级设计 | `repos/{项目名}_pc/modules/{模块名}.md` + `repos/{项目名}_pc/modules/{模块名}/design.md` + `repos/{项目名}_pc/modules/{模块名}/skill/SKILL.md`（模块技能文档，develop 参考） |
|
||||
| develop | 模块源码 + DDL | `repos/{模块名}/src/`、`repos/{模块名}/ddl/` |
|
||||
| develop | 模块源码 | `repos/{模块名}/`（内部结构以 module-development-spec 为准） |
|
||||
| develop | 开发说明 | `repos/{项目名}_pc/docs/02-develop/dev-notes.md` |
|
||||
| test | 测试计划 / 用例 / 报告 | `repos/{项目名}_pc/docs/03-test/` |
|
||||
| deploy_test | 测试环境部署 | `repos/{项目名}_pc/docs/04-deploy/deploy-test-env.md` |
|
||||
@ -125,7 +117,7 @@ QC/PM 检查交付件时，用 `read_file` / `list_files` 的路径是相对工
|
||||
| 需求文档 | `repos/{项目名}_pc/docs/00-requirement/requirement-spec.md` |
|
||||
| 应用定义 | `repos/{项目名}_pc/apps/{应用名}.md` |
|
||||
| 设计文档 | `repos/{项目名}_pc/docs/01-design/` + `repos/{项目名}_pc/modules/` |
|
||||
| 模块代码 | `repos/{模块名}/src/`、`repos/{模块名}/ddl/` |
|
||||
| 模块代码 | `repos/{模块名}/`（内部结构以 module-development-spec 为准） |
|
||||
| 测试文档 | `repos/{项目名}_pc/docs/03-test/` |
|
||||
| 部署文档 | `repos/{项目名}_pc/docs/04-deploy/` |
|
||||
|
||||
|
||||
@ -0,0 +1,108 @@
|
||||
---
|
||||
name: module-development
|
||||
description: 产线开发工程师模块开发规范——模块目录结构(包目录=模块名,非src)、init.py三处同步注册、表定义四段式/CRUD格式、RBAC load_path、模块技能文档、sqlor标准API(仅C/U/D/R/I/sqlExe)。触发：开发模块源码、创建模块仓库目录、写models/json/dspy/init.py。
|
||||
capability: task_capability
|
||||
---
|
||||
|
||||
# 产线开发工程师模块开发规范
|
||||
|
||||
本 skill 是产线开发工程师（agent.develop）产出模块源码时必须遵守的规范。
|
||||
表定义四段式格式、CRUD 格式、sqlor API 的完整细则沿用 `module-development-spec` / `database-table-definition-spec` / `crud-definition-spec`，
|
||||
本 skill 聚焦：**模块目录怎么建**、**init.py 怎么注册**、**表/CRUD 用什么格式**、**RBAC 怎么注册**、**模块技能文档怎么写**、**sqlor 只能用哪些 API**。
|
||||
|
||||
## 一、模块目录结构（铁律）
|
||||
|
||||
每个模块一个独立仓库，仓库名 = 模块名（英文小写），目录结构：
|
||||
|
||||
```
|
||||
{模块名}/
|
||||
├── {模块名}/ # Python 包目录（包名 = 模块名，不是 src/！）
|
||||
│ ├── __init__.py # 导出 init.py 的 async 函数
|
||||
│ ├── init.py # load_{模块名}() 注册函数到 ServerEnv
|
||||
│ └── *.py # 其他源码
|
||||
├── wwwroot/ # 前端
|
||||
│ ├── index.ui # 模块入口页（必须）
|
||||
│ └── api/*.dspy # 后端接口
|
||||
├── models/ # 表定义 JSON（四段式）
|
||||
├── json/ # CRUD 定义 JSON
|
||||
├── init/ # 初始化数据
|
||||
│ └── data.json # 编码字典等种子数据
|
||||
├── scripts/
|
||||
│ └── load_path.py # RBAC 权限注册
|
||||
├── skill/
|
||||
│ └── SKILL.md # 模块技能文档（后续 agent 参考）
|
||||
├── pyproject.toml # 打包配置
|
||||
└── README.md
|
||||
```
|
||||
|
||||
**禁止**：
|
||||
- 禁止用 `src/` 代替 `{模块名}/` 包目录——Python 包名必须 = 模块名，否则 `import {模块名}` 失败
|
||||
- 禁止把 `init.py`/`__init__.py` 放在模块根目录（必须在包目录 `{模块名}/` 内）
|
||||
- 禁止用 `module.json` / `conf/rp.json` / `import_rp.py` 代替 `pyproject.toml` / `scripts/load_path.py`
|
||||
|
||||
## 二、init.py 注册（三处同步，漏一处就 500）
|
||||
|
||||
每个模块的 `init.py` 里必须有 `load_{模块名}()` 函数，把公开函数注册到 ServerEnv。
|
||||
**新增/删除一个函数必须同步改三处**：
|
||||
|
||||
1. 函数定义（`{模块名}/init.py` 或包内其他 .py）
|
||||
2. 导出（`{模块名}/__init__.py` 的 `from .init import (...)`）
|
||||
3. 注册（`init.py` 的 `env.xxx = xxx`）
|
||||
|
||||
漏 #2 → ImportError；漏 #3 → .dspy 里 NameError 500。
|
||||
|
||||
**CRUD 单复数**：xls2ui 生成的 CRUD wrapper dspy 用复数名（`create_xxx`），init.py 定义常是单数，两者都要注册：
|
||||
```python
|
||||
env.create_supplier = create_supplier
|
||||
env.create_suppliers = create_supplier # xls2ui 用复数
|
||||
```
|
||||
|
||||
## 三、表定义四段式格式（models/*.json）
|
||||
|
||||
每张表一个 JSON，格式 = `summary` + `fields` + `indexes` + `codes` 四段：
|
||||
|
||||
```json
|
||||
{
|
||||
"summary": [{"name": "org_employee", "title": "员工表", "primary": ["id"]}],
|
||||
"fields": [
|
||||
{"name": "id", "title": "主键", "type": "str", "length": 32, "nullable": "no"},
|
||||
{"name": "orgid", "title": "所属组织", "type": "str", "length": 32},
|
||||
{"name": "empname", "title": "姓名", "type": "str", "length": 255},
|
||||
{"name": "salary", "title": "工资", "type": "double", "length": 18, "dec": 2},
|
||||
{"name": "status", "title": "状态", "type": "str", "length": 16},
|
||||
{"name": "created_at", "title": "创建时间", "type": "timestamp"}
|
||||
],
|
||||
"indexes": [{"name": "idx_org_employee_org", "idxtype": "index", "idxfields": ["orgid"]}],
|
||||
"codes": [{"field": "status", "table": "appcodes_kv", "valuefield": "k", "textfield": "v", "cond": "parentid='emp_status'"}]
|
||||
}
|
||||
```
|
||||
|
||||
**类型铁律**：用抽象类型 `str/int/double/timestamp/date/text`，**禁原生类型**（`varchar`/`bigint`/`boolean`/`int(11)`）。字段语义→类型映射见 design 角色技能 `database-design`。金额统一 `double` + `18/2`（用 double 不用 decimal）。业务日期用 `date` 不用 `timestamp`。
|
||||
|
||||
## 四、CRUD 定义格式（json/*.json）
|
||||
|
||||
每个 CRUD 一个 JSON，根键 = `tblname` + `params`：
|
||||
|
||||
```json
|
||||
{"tblname": "org_employee",
|
||||
"params": {"browserfields": {...}, "editable": {...}}}
|
||||
```
|
||||
|
||||
**铁律**：根键必须是 `tblname` + `params`，不能自创 `{"table":..., "list":...}` 格式。
|
||||
|
||||
## 五、RBAC 权限注册（scripts/load_path.py）
|
||||
|
||||
模块的 API/页面路径用 `scripts/load_path.py` 注册到 any/logined 角色（调 set_role_perm.py wrapper），
|
||||
不用 `conf/rp.json` / `import_rp.py` 这种非标机制。
|
||||
|
||||
## 六、模块技能文档（skill/SKILL.md，必须）
|
||||
|
||||
每个模块必须有 `skill/SKILL.md`，内容：数据模型（表清单+关键字段）、关键接口（dspy/函数）、陷阱、依赖。
|
||||
这是给后续 agent（测试/部署/维护）的参考，不能省。
|
||||
|
||||
## 七、sqlor 标准 API（禁编造）
|
||||
|
||||
sqlor 只有这 6 个方法：`sor.C`(建) / `sor.U`(改) / `sor.D`(删) / `sor.R`(查) / `sor.I`(查表结构) / `sor.sqlExe`(原生SQL)。
|
||||
**禁止**编造 `sqlor.save/list/one/delete/insert/query` —— 这些不存在，会 NameError。
|
||||
|
||||
写原生 SQL 引用列名时，**必须核对 models/{表}.json 的字段名**，不要凭记忆猜（如 permission 表是 `path`/`name` 不是 `permcode`/`permname`）。
|
||||
Loading…
x
Reference in New Issue
Block a user