diff --git a/skills_library/all/project-directory-spec/SKILL.md b/skills_library/all/project-directory-spec/SKILL.md index a5ad5e9..e168e0a 100644 --- a/skills_library/all/project-directory-spec/SKILL.md +++ b/skills_library/all/project-directory-spec/SKILL.md @@ -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。 diff --git a/skills_library/pipelines/sdlc_general/common/project-directory-spec/SKILL.md b/skills_library/pipelines/sdlc_general/common/project-directory-spec/SKILL.md new file mode 100644 index 0000000..8e8f456 --- /dev/null +++ b/skills_library/pipelines/sdlc_general/common/project-directory-spec/SKILL.md @@ -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 拉取最新代码。