yumoqing/pipeline_core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(skills): 规范分层——global project-directory-spec 去掉 apps/modules(只留通用项目目录)，产线版(pipelines/sdlc_general/common/)新增 apps/modules/spec.json/引用模块写保护/部署前远程仓库

Browse Source
This commit is contained in:
yumoqing 2026-08-24 17:24:47 +08:00
parent 21a9f3cfad
commit 20f3e6ebb2
2 changed files with 148 additions and 84 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

124
skills_library/all/project-directory-spec/SKILL.md
View File

@ -1,16 +1,16 @@
---
name: project-directory-spec
description: 所有 SDLC 角色产出/检查交付件落点前必读——机构工作空间 projects/apps/modules 三目录 + 项目目录(README+docs/+env/+{应用名}_spec.json)。应用代码落机构 apps/、模块代码落机构 modules/，项目只维护 app spec.json 描述引用/生成模块，无 repos/ 无 references/。不加载会把应用/模块代码落到项目目录下（应落机构 apps/modules）。
description: 所有 SDLC 角色产出/检查交付件落点前必读——项目目录结构（README + docs/ + env/）与各角色文档落点路径。应用/模块代码的落点（apps/modules）由产线规范（pipeline 版 project-directory-spec）定义，本 global 版只覆盖通用部分。不加载会把文档落到错误路径。
essential: true
---
# 项目目录规范
# 项目目录规范（global 通用版）
## 一、定位与客制化
本技能是**全局（global）基础规范**，规定机构工作空间与项目目录结构、各目录作用。
本技能是**全局（global）基础规范**，规定项目目录结构（README + docs/ + env/）与各目录作用。
所有角色（requirement / design / develop / deploy_test / test / deploy_prod / pm / qc）在产出或检查交付件前，都必须先读本技能，确认文件应落在哪个目录、应从哪个目录检查。
所有角色（requirement / design / develop / deploy_test / test / deploy_prod / pm / qc）在产出或检查交付件前，都必须先读本技能，确认文档应落在哪个目录、应从哪个目录检查。
同名技能按 scope 逐级覆盖实现客制化，优先级（低→高）：
@ -18,32 +18,18 @@ essential: true
global（全局基础）→ org（客户）→ pipeline（产线）→ project（项目）
```
- **全局版**：最通用的目录约定（即本文件）。
- **客户（org）版**：客户组织自己的目录要求，覆盖全局。
- **产线（pipeline）版**：某条产线（如开发产线）的目录细化，覆盖客户/全局。
- **项目（project）版**：单个项目的特殊目录，覆盖以上所有。
- **全局版**：最通用的项目目录约定（即本文件）——只覆盖「项目目录内部结构」与「文档落点」。
- **产线（pipeline）版**：某条产线（如开发产线）的目录细化（机构工作空间三目录 projects/apps/modules、应用/模块代码落点、app spec.json），覆盖全局。
- **客户（org）版 / 项目（project）版**：进一步覆盖。
## 二、机构工作空间（顶层）
⚠️ 本 global 版**不定义应用/模块代码的落点**（apps/、modules/ 是开发产线特有的要求，见产线版 project-directory-spec）。开发产线的角色请以产线版为准。
机构工作空间根下只有三个子目录：
## 二、项目目录结构（通用）
每个项目目录内部结构：
```
{机构工作空间}/
├── projects/ # 项目目录
├── apps/ # 应用本地仓库目录
└── modules/ # 模块本地仓库目录
```
- **三个子目录下都可以创建子目录**。
- **子目录命名规则**：英文字母 + 下划线 + 数字组合（`[a-zA-Z0-9_]+`），禁用中文、空格、连字符、其它符号。
- `apps/{应用名}/`：应用本地仓库，按 **web-application-spec** 创建文件和目录。
- `modules/{模块名}/`：模块本地仓库，按 **module-development-spec** 创建和生成文件和子目录。
- `projects/{项目名}/`：一个项目，按本规范创建和生成子目录。
## 三、项目目录结构
```
projects/{项目名}/
{项目目录}/
├── README.md # 项目说明
├── docs/ # 项目过程文档
│ ├── 00-requirement/ # 需求文档
@ -52,77 +38,47 @@ projects/{项目名}/
│ ├── 03-test/ # 测试文档
│ ├── 04-deploy/ # 部署文档
│ └── 05-pm/ # 项目管理 + QC 审计文档
├── env/ # 部署环境信息（集中保存）
│ ├── test.json
│ └── prod.json
└── {应用名}_spec.json # 每个 app 一个 spec.json（描述引用/生成模块）
└── env/ # 部署环境信息（集中保存）
├── test.json
└── prod.json
```
- **项目目录下没有 repos/ 也没有 references/ 目录**。
- 有几个 app，就写几个 `{应用名}_spec.json`，后面只维护这些 spec.json 文件。
- 应用/模块的实际代码在机构 `apps/`、`modules/` 下，不在项目目录下。
- 项目目录**所在位置**（如 projects/{项目名}/）由产线规范定义，本 global 版不写死。
- 应用/模块代码**不在项目目录下**（落点由产线规范定义）。
## 四、{应用名}_spec.json 内容
## 三、命名规范
每个 app 一个 spec.json，描述该应用引用了哪些模块、需要生成哪些模块：
```json
{
"app": "hrs6",
"referenced_modules": ["apppublic", "sqlor", "ahserver", "rbac"],
"generated_modules": ["organization", "payroll", "recruitment"]
}
```
- `app`：应用名（对应机构 `apps/{应用名}/`）。
- `referenced_modules`：**引用的模块**——机构 `modules/` 下已有的模块（基础模块 apppublic/sqlor/ahserver/rbac/appbase/accounting 等），直接引用，不重新开发。
- `generated_modules`：**需要生成的模块**——本项目要开发的业务模块，develop 产出到机构 `modules/{模块名}/`。
## 五、命名规范
| 目录 | 命名 | 示例 |
| 类型 | 命名 | 示例 |
|------|------|------|
| 项目 | `{项目名}`（`[a-zA-Z0-9_]+`） | `hrs6`、`personnel_system` |
| 应用 | `{应用名}`（`[a-zA-Z0-9_]+`） | `hrs6_app` |
| 模块 | `{模块名}`（`[a-zA-Z0-9_]+`） | `organization`、`payroll` |
- 所有目录名用英文字母 + 下划线 + 数字，禁用中文、连字符、空格。
- 模块名用能表达模块职责的英文名，不用序号或占位名。
- 目录名用英文字母 + 下划线 + 数字，禁用中文、连字符、空格。
## 六、各角色产出落点
## 四、各角色文档落点（文档类，相对项目目录）
| 角色 | 产出 | 落点 |
|------|------|------|
| requirement | 需求规格说明书 | `projects/{项目名}/docs/00-requirement/requirement-spec.md` |
| requirement | 应用 spec.json | `projects/{项目名}/{应用名}_spec.json`（有几个 app 写几个） |
| requirement | 部署环境信息 | `projects/{项目名}/env/test.json` + `prod.json` |
| design | 系统架构 / UI 设计 | `projects/{项目名}/docs/01-design/architecture.md`、`ui-design.md` |
| design | 模块级设计 | `projects/{项目名}/docs/01-design/modules/{模块名}.md` |
| develop | 应用源码 | 机构 `apps/{应用名}/`（按 web-application-spec） |
| develop | 模块源码 | 机构 `modules/{模块名}/`（按 module-development-spec） |
| develop | 开发说明 | `projects/{项目名}/docs/02-develop/dev-notes.md` |
| test | 测试文档 | `projects/{项目名}/docs/03-test/` |
| deploy_test | 测试环境部署 | `projects/{项目名}/docs/04-deploy/deploy-test-env.md` |
| deploy_prod | 生产部署 | `projects/{项目名}/docs/04-deploy/` |
| pm | 项目文档 | `projects/{项目名}/docs/05-pm/` |
| requirement | 需求规格说明书 | `docs/00-requirement/requirement-spec.md` |
| requirement | 部署环境信息 | `env/test.json` + `prod.json` |
| design | 系统架构 / UI 设计 | `docs/01-design/architecture.md`、`ui-design.md` |
| design | 模块级设计 | `docs/01-design/modules/{模块名}.md` |
| develop | 开发说明 | `docs/02-develop/dev-notes.md` |
| test | 测试文档 | `docs/03-test/` |
| deploy_test | 测试环境部署文档 | `docs/04-deploy/deploy-test-env.md` |
| deploy_prod | 生产部署文档 | `docs/04-deploy/` |
| pm | 项目文档 | `docs/05-pm/` |
## 七、各角色检查落点（QC / PM 必读）
> 应用/模块**代码**的落点（apps/{应用名}/、modules/{模块名}/）见产线版 project-directory-spec。
| 检查对象 | 完整路径 |
|---------|---------|
| 需求文档 | `projects/{项目名}/docs/00-requirement/` |
| app spec | `projects/{项目名}/{应用名}_spec.json` |
| 设计文档 | `projects/{项目名}/docs/01-design/` |
| 应用代码 | 机构 `apps/{应用名}/`（按 web-application-spec） |
| 模块代码 | 机构 `modules/{模块名}/`（按 module-development-spec） |
| 测试文档 | `projects/{项目名}/docs/03-test/` |
| 部署文档 | `projects/{项目名}/docs/04-deploy/` |
## 五、各角色检查落点（QC / PM 必读）
⚠️ 应用/模块代码在机构 `apps/`、`modules/` 下，**不在项目目录下**。检查应用/模块代码时，路径是机构工作空间的 `apps/{应用名}/`、`modules/{模块名}/`，不是 `projects/{项目}/...`。
文档检查路径相对项目目录：
## 八、部署前设置远程仓库
| 检查对象 | 路径 |
|---------|------|
| 需求文档 | `docs/00-requirement/` |
| 设计文档 | `docs/01-design/` |
| 测试文档 | `docs/03-test/` |
| 部署文档 | `docs/04-deploy/` |
应用部署测试前，机构 `apps/` 和 `modules/` 下应用使用到的仓库**都要设置远程仓库**（`git remote add origin <远程地址>`），否则部署时无法 git pull 拉取最新代码。
- 应用仓库：`apps/{应用名}/` 设置远程仓库。
- 模块仓库：`modules/{模块名}/` 中，被应用 referenced_modules / generated_modules 引用的都要设置远程仓库。
> 应用/模块代码的检查路径见产线版 project-directory-spec。

108
skills_library/pipelines/sdlc_general/common/project-directory-spec/SKILL.md Normal file
View File

@ -0,0 +1,108 @@
---
name: project-directory-spec
description: 开发产线（sdlc_general）目录规范——机构工作空间 projects/apps/modules 三目录 + 项目在 projects/{项目名}/ + 应用代码在 apps/{应用名}/ + 模块代码在 modules/{模块名}/ + app spec.json（引用/生成模块）+ 部署前设置远程仓库。完整覆盖 global 版，开发产线各角色必读。
---
# 项目目录规范（开发产线版 sdlc_general）
> 本技能是**产线（pipeline）版**，完整覆盖 global 版的 project-directory-spec（同名技能整体替换，非合并）。开发产线（sdlc_general）的角色以本版为准。
## 一、机构工作空间（开发产线层）
开发产线的机构工作空间 = `/d/pipeline/workspaces/{org_id}/sdlc_general/`，下有三个子目录：
```
{机构工作空间}/ # = /d/pipeline/workspaces/{org_id}/sdlc_general/
├── projects/ # 项目
├── apps/ # 应用本地仓库
└── modules/ # 模块本地仓库
```
- 三个子目录下都能再建子目录，命名 = `[a-zA-Z0-9_]+`（英文字母 + 下划线 + 数字，禁用中文/连字符/空格）
- `projects/{项目名}/` = 一个项目
- `apps/{应用名}/` = 应用本地仓库（按 web-application-spec）
- `modules/{模块名}/` = 模块本地仓库（按 module-development-spec）
## 二、项目目录结构
```
projects/{项目名}/
├── README.md # 项目说明
├── docs/ # 项目过程文档
│ ├── 00-requirement/ # 需求文档
│ ├── 01-design/ # 设计文档
│ ├── 02-develop/ # 开发说明
│ ├── 03-test/ # 测试文档
│ ├── 04-deploy/ # 部署文档
│ └── 05-pm/ # 项目管理 + QC 审计文档
├── env/ # 部署环境信息（集中保存）
│ ├── test.json
│ └── prod.json
└── {应用名}_spec.json # 每个 app 一个 spec.json
```
- 项目目录下**没有 repos/ 也没有 references/**，有几个 app 就写几个 `{应用名}_spec.json`
- 应用/模块代码在机构 `apps/`、`modules/` 下，**不在项目目录下**
## 三、app spec.json（每个 app 一个）
```json
{
"app": "hrs6",
"referenced_modules": ["apppublic", "sqlor", "ahserver", "rbac"],
"generated_modules": ["organization", "payroll", "recruitment"]
}
```
- `app`：应用名（对应机构 `apps/{应用名}/`）
- `referenced_modules`：**引用的模块**——机构 `modules/` 下已有的模块（基础模块 apppublic/sqlor/ahserver/rbac/appbase/accounting 等），直接引用，**只读不重新开发**
- `generated_modules`：**需要生成的模块**——本项目要开发的业务模块，develop 产出到机构 `modules/{模块名}/`
### 引用模块写保护（铁律）
- `referenced_modules`（引用的模块）是机构 `modules/` 下已有的模块，**只读，develop 不得修改**——它们被多个项目共享，改一个会影响所有引用它的项目。
- `generated_modules`（本项目的模块）本项目 develop 可写；但**若被其他项目 spec.json 的 referenced_modules 引用，改动必须走 git 版本控制 + 变更评审**，不能直接覆盖。
- 基础模块（apppublic/sqlor/ahserver/rbac/appbase/accounting）是 ocai 组织缺省模块，任何项目**一律不得修改**（改了会破坏所有依赖它的应用/项目）。
## 四、命名规范
| 目录 | 命名 | 示例 |
|------|------|------|
| 项目 | `{项目名}`（`[a-zA-Z0-9_]+`） | `hrs6`、`personnel_system` |
| 应用 | `{应用名}`（`[a-zA-Z0-9_]+`） | `hrs6_app` |
| 模块 | `{模块名}`（`[a-zA-Z0-9_]+`） | `organization`、`payroll` |
## 五、各角色产出落点（相对机构工作空间 {机构工作空间}/）
| 角色 | 产出 | 落点 |
|------|------|------|
| requirement | 需求规格说明书 | `projects/{项目名}/docs/00-requirement/requirement-spec.md` |
| requirement | 部署环境信息 | `projects/{项目名}/env/test.json` + `prod.json` |
| design | 系统架构 / UI 设计 | `projects/{项目名}/docs/01-design/architecture.md`、`ui-design.md` |
| design | 模块级设计 | `projects/{项目名}/docs/01-design/modules/{模块名}.md` |
| design | app spec.json | `projects/{项目名}/{应用名}_spec.json`（每个 app 一个） |
| develop | 应用源码 | `apps/{应用名}/`（按 web-application-spec） |
| develop | 模块源码 | `modules/{模块名}/`（按 module-development-spec） |
| develop | 开发说明 | `projects/{项目名}/docs/02-develop/dev-notes.md` |
| test | 测试文档 | `projects/{项目名}/docs/03-test/` |
| deploy_test | 测试环境部署文档 | `projects/{项目名}/docs/04-deploy/deploy-test-env.md` |
| deploy_prod | 生产部署文档 | `projects/{项目名}/docs/04-deploy/` |
| pm | 项目文档 | `projects/{项目名}/docs/05-pm/` |
## 六、各角色检查落点（QC / PM 必读）
| 检查对象 | 完整路径 |
|---------|---------|
| 需求文档 | `projects/{项目名}/docs/00-requirement/` |
| app spec | `projects/{项目名}/{应用名}_spec.json` |
| 设计文档 | `projects/{项目名}/docs/01-design/` |
| 应用代码 | 机构 `apps/{应用名}/`（按 web-application-spec） |
| 模块代码 | 机构 `modules/{模块名}/`（按 module-development-spec） |
| 测试文档 | `projects/{项目名}/docs/03-test/` |
| 部署文档 | `projects/{项目名}/docs/04-deploy/` |
⚠️ 应用/模块代码在机构 `apps/`、`modules/` 下，**不在项目目录下**。检查应用/模块代码时，路径是机构工作空间的 `apps/{应用名}/`、`modules/{模块名}/`，不是 `projects/{项目}/...`。
## 七、部署前设置远程仓库
应用部署测试前，机构 `apps/` 和 `modules/` 下应用使用到的仓库都要设置远程仓库（`git remote add origin <远程地址>`），否则部署时无法 git pull 拉取最新代码。