diff --git a/.crmeb/skills/crmeb-dev/references/06-安装部署/install-deploy.md b/.crmeb/skills/crmeb-dev/references/06-安装部署/install-deploy.md index 8760201f1..60ffca2e5 100644 --- a/.crmeb/skills/crmeb-dev/references/06-安装部署/install-deploy.md +++ b/.crmeb/skills/crmeb-dev/references/06-安装部署/install-deploy.md @@ -32,7 +32,11 @@ ./run.sh delete # 停止并清理所有数据（危险） ./run.sh logs # 查看日志 ./run.sh ps # 查看容器状态 -./run.sh # 交互式菜单 +./run.sh admin:dev # 管理端前端开发测试启动（Vite 1619，/adminapi 代理 8011） +./run.sh admin:build # 管理端 build:all（主包+扩展 UMD）并发布到 backend/public/admin +./run.sh uni:dev # uniapp H5 开发测试启动（默认端口 5173） +./run.sh uni:build # uniapp H5 构建并发布到 backend/public（index.html、assets、pages、static） +./run.sh # 交互式菜单（含 11/12 管理端、21/22 uniapp 前端命令） ``` `install` 会删除 `backend/public/install.lock`、清空 `backend/runtime`、`docker/mysql/data` 等数据目录，完成后访问 **http://localhost:8011** 进入安装向导。 @@ -130,6 +134,15 @@ location /ws { | `frontend/admin` | Vue 3 + Element Plus + Vite | 管理后台，构建产物部署到 `/admin`；二开用 `scripts/build-extensions.js` 构建插件 UMD 扩展 | | `frontend/uni-app` | uni-app CLI（Vue 3） | 用户端（H5/小程序/APP），用 `npm run dev:h5` 等 CLI 命令运行 | +前端也可用仓库根 `run.sh` 一键执行（自动补装 `node_modules`，等价于进入对应目录执行 npm 命令）： + +| 菜单 | 命令 | 作用 | 产物 / 地址 | +|------|------|------|------------| +| 11 | `./run.sh admin:dev` | 管理端开发测试启动 | http://localhost:1619 | +| 12 | `./run.sh admin:build` | `npm run build:all`（主包 + 扩展 UMD）后发布 | `backend/public/admin/` | +| 21 | `./run.sh uni:dev` | uniapp H5 开发测试启动 | http://localhost:5173 | +| 22 | `./run.sh uni:build` | `npm run build:h5` 后发布 | `backend/public/`（index.html + assets/pages/static，PHP 侧文件不受影响） | + **注意**：前端 dev server 热更新可能失效，修改文件后页面若未更新，需手动重启服务。 ## 八、登录账号 diff --git a/.crmeb/skills/project-standard-bootstrap/SKILL.md b/.crmeb/skills/project-standard-bootstrap/SKILL.md new file mode 100644 index 000000000..278c66ec7 --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/SKILL.md @@ -0,0 +1,156 @@ +--- +name: project-standard-bootstrap +description: 审计、建立或修复项目统一工程规范，使全栈项目具备一致的 .crmeb AI 规则、统一技能包骨架、按后端与各前端目录拆分的架构认知和核心功能开发文档、主流 AI 工具入口、backend/frontend 目录、标准命令、Docker 本地开发、跨层开发指引、测试 CI、文档和自动升级包。适用于新项目初始化、旧项目规范化、AI 接手治理、前端补齐后端与数据库能力、UniApp 多端开发和快速运行；不用于只润色单篇文档或绕过目标仓库已有约束。 +--- + +# 项目统一工程规范 + +把目标项目建设成“目录统一、命令统一、规则可发现、全栈协作完整、环境可复现、变更可验证、交付可升级”的工程系统。统一的是项目契约和质量底线；语言、框架及部署实现由真实技术栈决定。 + +## 工作模式 + +- **仅审计**：运行只读审计并输出 P0/P1/P2 差距，不修改文件。 +- **初始化**：为新项目生成缺失的目录、`.crmeb/` 基线、项目契约，以及按代码目录拆分的架构认知与开发文档技能。 +- **审计并完善**：对已有项目增量补齐规范、技能包骨架、目录说明、脚本、文档和验证入口。 +- **刷新维护**：修复事实漂移、失效命令、规则冲突、目录说明过期、迁移断链和交付缺口。 + +用户只要求分析时不得修改。用户要求建立、完善、统一或升级时，完成实施与验证闭环。 + +## 不可妥协的统一契约 + +1. AI 规则正文只维护在 `.crmeb/`；根 `AGENTS.md` 等工具入口只做薄指针。 +2. `.crmeb/skills/` 采用统一技能包骨架：每个技能目录为 `SKILL.md` + `references/`，`assets/`、`scripts/`、`agents/` 按需存在；`SKILL.md` 只承载索引与最小流程，正文放 `references/`，不得在技能根目录散落规则正文。 +3. 架构认知与核心功能开发文档必须按代码目录拆分：后端一个技能，每个可独立构建的前端应用各一个技能，与 `.crmeb/project.json` 的 `applications` 对齐；每个目录必须有「项目目录说明」，并登记到 `.crmeb/AGENTS.md` 的技能索引，使 AI 无需遍历全仓即可快速了解架构。 +4. 后端业务代码位于 `backend/`；可独立构建的前端位于 `frontend/<应用名>/`。 +5. 知识目录职责分离：当前事实在 `help/docs/`，AI 规则在 `.crmeb/`，过程文档与测试索引统一在 `tests/`（`plans/`、`reports/`、可分发模板）；过程目录名由契约 `directories.process` 声明，审计、初始化与检查脚本读取该字段，不硬编码目录名。 +6. `.crmeb/project.json` 记录应用、服务、端口和标准命令映射，并由检查脚本防漂移。 +7. 项目提供 `doctor/setup/dev/stop/status/logs/check/test/build` 等价命令；实现可映射到现有 Make、Task、npm、Gradle、Compose 或脚本。 +8. 全栈变更同步检查数据、后端、API、权限、前端、测试、文档、迁移和升级包。 +9. 除“仅审计”外，必须根据当前项目后端真实运行环境自动生成或完善根 `docker-compose.yml`；同时生成所需 Dockerfile、配置和 `run.sh`，挂载本地源码、隔离依赖和数据卷，并区分安全停止与破坏性重置。 +10. 规则区分通用底线、技术栈 Profile 和项目专属约定，不把单一框架习惯强加给所有项目。 +11. 已发布版本、迁移和升级清单不可回改；可交付变更必须判断升级包触发条件。 +12. 不覆盖现有修改、不泄露凭据、不擅自清库、发布、推送或连接生产环境。 +13. Codex、Claude Code、Cursor、GitHub Copilot、Gemini CLI 等工具通过各自发现入口读取同一 `.crmeb` 真源，不复制规则正文。 + +## 执行流程 + +### 1. 发现与审计 + +先读取目标仓库所有适用的 `AGENTS.md`、README、贡献指南、manifest、lockfile、容器、CI、迁移和测试配置，并检查 Git 状态。运行： + +```bash +node /scripts/audit-project-standard.mjs +node /scripts/analyze-project-environment.mjs --write +``` + +环境分析器只读取 manifest、lockfile、非敏感配置样例和现有容器配置，不读取真实 `.env`。它输出运行时、应用、依赖服务、Docker 现状和动态文档缺口；结果必须由代码入口复核。事实以代码和可执行配置为准，旧文档只作线索。详细证据账本和优先级方法见 [文档与事实治理](references/documentation-governance.md)。 + +### 2. 建立项目契约 + +读取 [项目契约与标准命令](references/project-contract.md)，建立 `.crmeb/project.json`。新项目或确认需要初始化时可先运行： + +```bash +node /scripts/init-project-standard.mjs --dry-run +node /scripts/init-project-standard.mjs +``` + +初始化工具只创建缺失项，不覆盖现有文件。生成后必须根据真实项目补全命令、应用、服务和端口，禁止把草稿契约当成已完成。 + +### 3. 建立规则体系 + +按任务读取相关参考，不要一次加载全部： + +- 目录、模块边界和迁移：[目录与架构](references/directory-and-architecture.md) +- 全栈功能修改：[全栈开发流程](references/fullstack-workflow.md) +- 前端开发者跨到后端和数据库：[前端到后端与数据库](references/frontend-backend-database-bridge.md) +- 后端分层、事务、任务：[后端规范](references/backend-standard.md) +- 前端应用、状态、UI：[前端规范](references/frontend-standard.md) +- API、数据库和契约：[API 与数据库](references/api-and-database.md) +- 安全、日志、性能和运维：[安全与可观测性](references/security-and-observability.md) +- 测试、质量门禁和 CI：[测试与 CI](references/testing-and-ci.md) +- Docker 本地运行：[Docker 本地开发](references/docker-local-development.md) +- 项目文档完整度：[文档覆盖矩阵](references/documentation-coverage.md) +- 版本迁移和升级包：[自动升级包](references/upgrade-package.md) +- 最终验收和旧项目迁移：[迁移与验收](references/migration-and-acceptance.md) +- 多 AI 工具发现与单一真源：[AI 工具适配](references/ai-tool-adapters.md) + +把通用规则模板从 `assets/project-template/.crmeb/` 增量适配到目标项目。规则必须结合真实框架补充，不能保留与实现冲突的模板语句。 + +### 4. 生成架构认知与目录说明技能 + +系统必须自动、快速地让 AI 与新成员了解项目架构，不依赖人工口述或全仓遍历。在 `.crmeb/skills/` 下按代码目录建立技能，目录职责与分层方法见 [目录与架构](references/directory-and-architecture.md)： + +- **按目录拆分**：后端对应一个技能；每个可独立构建的前端应用各对应一个技能（如管理端、移动端、Web 端），与 `.crmeb/project.json` 的 `applications` 一一对应，技能名可从应用 ID 派生。 +- **每个目录必须有「项目目录说明」**：目录树、逐目录职责、关键文件与入口、请求与数据流转链路、依赖边界、禁止放置的内容。 +- **每个目录必须有核心功能开发文档**：该端核心功能的入口、路由或 API、业务层、数据模型、扩展点、依赖服务，以及测试与验证命令。 +- **统一骨架**：技能目录为 `SKILL.md` + `references/`；`SKILL.md` 只做索引与最小流程，正文按主题拆到 `references/`，需要时再补 `assets/`、`scripts/`、`agents/`。 +- **骨架来源与元数据**：从 `assets/app-skill-skeleton/` 复制并替换占位符（`{{SKILL_NAME}}`、`{{APP_ID}}`、`{{APP_PATH}}`、`{{RUNTIME}}`）；`SKILL.md` frontmatter 必须声明 `name`（与目录同名）、`description`、`appPath`、`directoryGuide`、`coreFeatures`，后两者指向技能内真实存在的文档。 + +初始化脚本会按 `applications` 自动生成技能骨架并登记 `.crmeb/AGENTS.md` 技能索引。脚本只搭骨架，正文必须由 AI 按当前代码补全；占位符或 TODO 未清除会被校验标为未完成。内容必须从当前代码、路由、manifest 和测试核对，禁止照搬模板或旧文档；架构事实变化时同步更新对应目录说明。已存在的技能只做增量补全，不覆盖用户已有改动。 + +### 5. 加载技术栈 Profile + +只加载检测到的技术栈： + +- PHP：[profiles/php.md](references/profiles/php.md) +- Node.js 后端：[profiles/node.md](references/profiles/node.md) +- Python：[profiles/python.md](references/profiles/python.md) +- Java：[profiles/java.md](references/profiles/java.md) +- Go：[profiles/go.md](references/profiles/go.md) +- Vue：[profiles/vue.md](references/profiles/vue.md) +- React：[profiles/react.md](references/profiles/react.md) +- UniApp：[profiles/uniapp.md](references/profiles/uniapp.md) + +Profile 用于发现权威版本、命令、常见目录和验证工具，不替代项目自身配置。 + +### 6. 强制生成 Docker 本地运行环境 + +初始化、审计并完善或刷新维护时，不论仓库原来是否存在 Docker，都必须先从后端 manifest、lockfile、版本文件、启动入口、扩展依赖、配置样例和外部服务提取真实运行要求，然后自动生成或语义完善根 `docker-compose.yml`。不得要求使用者手工选择通用 PHP、Node、Python、Java 或 Go 模板。 + +先预览，再写入缺失文件： + +```bash +node /scripts/generate-docker-environment.mjs +node /scripts/generate-docker-environment.mjs --write-missing +``` + +脚本只负责有把握的机械生成。如果脚本无法识别某种框架、启动命令、扩展或服务，AI 必须继续检查技术栈 Profile、代码入口、CI 和已有运行脚本，亲自完成 `docker-compose.yml`，不能把“脚本不支持”作为交付结果。已有 Compose 必须保留有效配置并按当前后端环境更新；不能仅因为文件已经存在就跳过。 + +最终 Compose 至少覆盖后端应用、实际必需的数据库/缓存、真实后台进程和健康检查；前端是否进入 Compose 由当前项目开发方式决定。Dockerfile、Nginx、入口脚本等辅助代码统一放入 `docker/`，根 `run.sh` 提供统一命令。生成后补全 `.crmeb/project.json` 的 Docker、服务、命令和文档字段。 + +### 7. 文档、运行与交付 + +使用 [文档模板](references/templates.md) 和 [文档覆盖矩阵](references/documentation-coverage.md)，根据环境分析结果建立根入口、项目概览、开发配置、架构、前后端、API、数据库、测试、Docker、部署、运维、安全、排障、备份恢复和升级文档。正式事实、AI 规则、过程记录和测试索引职责分离：过程记录写入契约 `directories.process` 声明的目录（缺省 `tests/`，即与测试索引同目录）；不得用空壳文档冒充完成。 + +必须扫描 `.crmeb/project.json` 和环境分析器识别出的每个后端、管理端、Web、UniApp、小程序或其他独立应用，逐一根据当前 manifest、构建配置、入口/路由、环境样例、API 客户端、测试和 CI 更新应用目录 `README.md` 与 `help/docs/applications/<应用ID>.md`。不能只更新总 README 或用一份前端说明覆盖多个项目。代码变更后重新核对受影响应用；无需改文档时也要在交付报告中说明检查依据。同一应用在 `.crmeb/skills/` 下的目录说明与核心功能开发文档，必须与该应用的 `README.md`、`help/docs/applications/<应用ID>.md` 事实一致，三者不得互相矛盾。 + +Docker 环境必须至少验证 Compose 解析、镜像构建、服务健康、源码挂载、前后端访问、测试和数据保留。触发升级交付时，生成 manifest、迁移、发布 payload、校验和和回滚说明，并在隔离环境验证旧版到新版。 + +### 8. 机器验收 + +运行： + +```bash +node /scripts/check-project-standard.mjs +``` + +再执行 `.crmeb/project.json` 声明的 `check`、`test`、`build` 和必要 smoke 命令。根据风险逐级报告文本检查、静态检查、构建测试、运行验证和生命周期验证，不得夸大覆盖范围。 + +检查脚本已校验技能骨架、`appPath` 应用覆盖、`directoryGuide` 与 `coreFeatures` 的存在性及索引登记；文档内容是否与当前代码一致仍需逐项核对，占位符或 TODO 未清除即视为未完成，不得用脚本通过代替。 + +## 完成标准 + +- 新开发者或 AI 能在 5 分钟内找到规则、配置和最短启动路径。 +- `.crmeb/skills/` 每个技能符合统一骨架（`SKILL.md` + `references/`）；后端与每个独立前端应用都有对应技能，技能与 `.crmeb/project.json` 的 `applications` 一一对应。 +- 每个代码目录都有经当前代码核对的「项目目录说明」与核心功能开发文档；新 AI 会话无需遍历全仓即可定位任一核心功能的入口链路。 +- 同一应用的技能文档、应用目录 `README.md` 与 `help/docs/applications/<应用ID>.md` 事实一致，没有跨应用混用。 +- 标准命令可从仓库根执行或有明确映射，失败信息能定位缺少的环境或服务。 +- 后端、前端、API 和数据库改动有一致的全栈同步与测试清单。 +- Docker 日常启动不删除数据，破坏性重置需要明确动作和确认。 +- 非“仅审计”任务已经根据当前后端运行环境自动生成或更新根 `docker-compose.yml`；缺失该文件或仅保留通用占位模板不得声明完成。 +- `docker-compose.yml`、`run.sh` 和 `docker/` 与当前项目真实运行时、版本、服务、端口和进程一致，不保留未经核对的模板值。 +- 文档覆盖由项目能力动态计算；数据库、UniApp、worker、升级或多前端存在时，对应文档不可缺省。 +- 后端及每个独立前端应用都有从当前代码核对过的就近 README 和详细说明，命令、端口、API、构建与发布事实没有跨项目混用。 +- CI 执行与本地相同的 `check/test/build` 契约。 +- 触发升级的改动可生成可追溯、可校验、经过验证的候选升级包。 +- 自动检查通过；未通过项、动态验证缺口和需负责人决策的内容明确列出。 diff --git a/.crmeb/skills/project-standard-bootstrap/assets/app-skill-skeleton/SKILL.md b/.crmeb/skills/project-standard-bootstrap/assets/app-skill-skeleton/SKILL.md new file mode 100644 index 000000000..9e29f6950 --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/assets/app-skill-skeleton/SKILL.md @@ -0,0 +1,24 @@ +--- +name: {{SKILL_NAME}} +description: {{APP_ID}} 应用的目录说明与核心功能开发文档，供 AI 在修改 {{APP_PATH}} 前快速了解该端架构、入口链路与验证命令 +appPath: {{APP_PATH}} +directoryGuide: references/项目目录说明.md +coreFeatures: + - references/核心功能开发.md +--- + +# {{APP_ID}} 应用开发技能 + +本技能覆盖 `{{APP_PATH}}`（运行时：{{RUNTIME}}）。只描述该端事实，不混入其他应用。 + +## 读取顺序 + +1. [项目目录说明](references/项目目录说明.md)：目录树、逐目录职责、关键入口、请求与数据链路、依赖边界。 +2. [核心功能开发](references/核心功能开发.md)：核心功能的入口、路由或 API、业务层、数据模型、扩展点、测试与验证命令。 + +## 使用要求 + +- 两份文档必须从当前代码、路由、manifest 和测试核对，禁止照搬模板或旧文档。 +- 修改 `{{APP_PATH}}` 后同步更新受影响条目；事实变化未同步即视为未完成。 +- 与 `{{APP_PATH}}/README.md`、`help/docs/applications/{{APP_ID}}.md` 事实保持一致，三者不得互相矛盾。 +- 需要更细的专题时，在本技能 `references/` 下按主题新增文件，并在此处登记。 \ No newline at end of file diff --git a/.crmeb/skills/project-standard-bootstrap/assets/app-skill-skeleton/references/核心功能开发.md b/.crmeb/skills/project-standard-bootstrap/assets/app-skill-skeleton/references/核心功能开发.md new file mode 100644 index 000000000..9d705db2e --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/assets/app-skill-skeleton/references/核心功能开发.md @@ -0,0 +1,28 @@ +# {{APP_ID}} 核心功能开发 + +> TODO：按当前代码补全，删除所有 TODO。每个核心功能都要能定位到入口与验证方式。 + +## 核心功能清单 + +| 功能 | 入口 | 关键文件 | 验证方式 | +| --- | --- | --- | --- | +| TODO | TODO | TODO | TODO | + +## 功能详解 + +### TODO：功能名称 + +- 入口：TODO（页面、路由或 API 路径） +- 业务层：TODO +- 数据模型：TODO（表或字段、迁移位置） +- 扩展点：TODO（插件、事件、钩子或配置） +- 依赖服务：TODO +- 测试与验证命令：TODO + +## 开发流程 + +TODO：新增一个功能时按顺序要改哪些层，各层对应的命令与检查项。 + +## 常见坑 + +TODO：该端特有的约束、易错点和已知限制。 \ No newline at end of file diff --git a/.crmeb/skills/project-standard-bootstrap/assets/app-skill-skeleton/references/项目目录说明.md b/.crmeb/skills/project-standard-bootstrap/assets/app-skill-skeleton/references/项目目录说明.md new file mode 100644 index 000000000..4b998132f --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/assets/app-skill-skeleton/references/项目目录说明.md @@ -0,0 +1,29 @@ +# {{APP_ID}} 项目目录说明 + +> TODO：按当前代码补全，删除所有 TODO。只写 `{{APP_PATH}}` 的事实，不写计划。 + +## 目录树 + +TODO：列出 `{{APP_PATH}}` 下的目录与关键文件，标注每项职责。 + +## 逐目录职责 + +| 目录 | 职责 | 禁止放置 | +| --- | --- | --- | +| TODO | TODO | TODO | + +## 关键入口 + +TODO：启动入口、路由注册、配置文件、依赖清单、构建配置的真实路径。 + +## 请求与数据链路 + +TODO：从请求或页面进入，到业务处理、数据访问和外部依赖的调用链，逐步给出真实文件位置。 + +## 依赖边界 + +TODO：本端可依赖哪些模块、不可反向依赖哪些模块、与哪些服务或应用交互。 + +## 变更影响面 + +TODO：改动本端目录时需要同步检查的 API、权限、数据库、测试、文档与升级包。 \ No newline at end of file diff --git a/.crmeb/skills/project-standard-bootstrap/assets/project-template/.crmeb/AGENTS.md b/.crmeb/skills/project-standard-bootstrap/assets/project-template/.crmeb/AGENTS.md new file mode 100644 index 000000000..6bb8b7bf6 --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/assets/project-template/.crmeb/AGENTS.md @@ -0,0 +1,41 @@ +# 项目 AI 开发规范 + +本目录是项目 AI 规则唯一正文来源。根级工具入口只指向本文，不复制规则。 + +## 处理任务前 + +1. 读取 `.crmeb/project.json`，确认应用、服务、路径和标准命令。 +2. 根据任务加载相关规则与技能，不整目录读取；改某端前先读该端技能的项目目录说明。 +3. 检查 Git 状态，区分用户已有改动与本任务改动。 +4. 从代码和配置核对事实，不把旧文档当作实现证据。 + +## 规则索引 + +| 规则 | 何时读取 | +| --- | --- | +| [架构与目录](rules/architecture.md) | 新增模块、调整依赖或移动目录 | +| [代码规范](rules/coding.md) | 修改任何代码 | +| [后端规范](rules/backend.md) | 修改 `backend/` | +| [前端规范](rules/frontend.md) | 修改 `frontend/` | +| [API 与数据](rules/api-and-data.md) | 修改接口、数据库、事件或消息 | +| [安全与日志](rules/security.md) | 涉及鉴权、输入、日志、外部系统 | +| [测试规范](rules/testing.md) | 新增功能、修复缺陷或改测试 | +| [Git 与发布](rules/git-and-release.md) | 提交、构建、升级或发布 | +| [文档规范](rules/documentation.md) | 新增或修改文档 | +| [升级包规范](rules/upgrade.md) | 可交付代码、数据或前端产物变化 | +| [全栈协作](rules/fullstack.md) | 前端功能涉及 API、权限、后端或数据库时 | + +## 技能索引 + +按代码目录拆分，后端与每个独立前端应用各一个技能；项目目录说明和核心功能开发文档都在技能 `references/` 内。技能与 `.crmeb/project.json` 的 `applications` 一一对应。 + +| 技能 | 何时读取 | +| --- | --- | + +## 跨层协作 + +主要负责前端的开发者提出全栈需求时，先从前端 API 路径追踪到后端路由、业务层、数据访问和迁移。解释每层影响并给出真实文件位置；禁止用手工改数据库替代迁移，也不能因为前端隐藏按钮就省略服务端权限校验。 + +## 完成要求 + +执行项目契约中的 `check`、相关 `test`、必要 `build` 和 smoke。静态检查不等于运行验证；升级包未完成隔离升级测试时只能标记为候选。 diff --git a/.crmeb/skills/project-standard-bootstrap/assets/project-template/.crmeb/rules/api-and-data.md b/.crmeb/skills/project-standard-bootstrap/assets/project-template/.crmeb/rules/api-and-data.md new file mode 100644 index 000000000..f6808f39b --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/assets/project-template/.crmeb/rules/api-and-data.md @@ -0,0 +1,14 @@ +--- +name: api-and-data +description: API 契约、数据库、迁移、事件和兼容性规则 +--- + +# API 与数据规则 + +- 请求校验、成功响应、错误码、分页、排序和过滤语义在项目内统一。 +- 高风险写接口和回调必须具备幂等、权限和重放防护。 +- OpenAPI/schema 等机器契约优先作为客户端类型和契约测试来源。 +- 表、字段、金额、时间、状态、软删除和多租户语义统一；索引对应真实查询。 +- 迁移只向前追加，已发布迁移不可回改；UPDATE/DELETE 必须有精确条件。 +- 新安装 schema 与所有历史迁移的最终结果一致，破坏性变更有兼容窗口和恢复计划。 + diff --git a/.crmeb/skills/project-standard-bootstrap/assets/project-template/.crmeb/rules/architecture.md b/.crmeb/skills/project-standard-bootstrap/assets/project-template/.crmeb/rules/architecture.md new file mode 100644 index 000000000..eb2d290f9 --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/assets/project-template/.crmeb/rules/architecture.md @@ -0,0 +1,14 @@ +--- +name: architecture +description: 项目目录、模块边界与依赖方向强制规则 +--- + +# 架构与目录规则 + +- AI 规则正文只维护在 `.crmeb/`。 +- 后端业务代码位于 `backend/`，前端应用位于 `frontend/<应用名>/`。 +- 模块公开入口和依赖方向必须明确；禁止跨模块引用内部实现或形成循环依赖。 +- 领域逻辑不依赖 UI、Web 框架、数据库驱动或具体第三方 SDK。 +- 共享代码只有存在两个以上真实消费者时才抽取，并具有明确所有者。 +- 目录迁移必须同步 import、构建、测试、Docker、CI、部署和文档，并作为可回滚的独立变更。 + diff --git a/.crmeb/skills/project-standard-bootstrap/assets/project-template/.crmeb/rules/backend.md b/.crmeb/skills/project-standard-bootstrap/assets/project-template/.crmeb/rules/backend.md new file mode 100644 index 000000000..08fd2e8a2 --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/assets/project-template/.crmeb/rules/backend.md @@ -0,0 +1,14 @@ +--- +name: backend +description: 后端分层、事务、缓存、队列与外部依赖规则 +--- + +# 后端规则 + +- 协议层只做输入适配、鉴权入口和输出映射；业务规则进入用例或领域层。 +- 持久化和第三方调用通过明确接口隔离，领域层不依赖具体实现。 +- 事务位于业务用例边界，避免在事务中执行不受控网络调用。 +- 写操作定义并发、幂等和重试；缓存定义 key、TTL、失效责任和一致性。 +- 队列与任务定义超时、退避、死信、补偿和重复消费策略。 +- 错误分层映射，结构化日志脱敏并携带请求或任务关联 ID。 + diff --git a/.crmeb/skills/project-standard-bootstrap/assets/project-template/.crmeb/rules/coding.md b/.crmeb/skills/project-standard-bootstrap/assets/project-template/.crmeb/rules/coding.md new file mode 100644 index 000000000..11246cfc8 --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/assets/project-template/.crmeb/rules/coding.md @@ -0,0 +1,14 @@ +--- +name: coding +description: 跨技术栈代码质量、命名、类型、注释与依赖规则 +--- + +# 代码规范 + +- 遵守项目格式化、lint、类型和框架工具；不引入并行风格。 +- 名称表达领域含义，避免无上下文缩写、布尔歧义和伪通用工具类。 +- 函数和模块保持单一职责，副作用、输入、输出和失败方式清晰。 +- 优先类型和可执行契约，不用注释重复代码；注释解释原因、不变量和风险。 +- 禁止吞异常、调试输出、硬编码秘密、无边界查询和未经说明的全局状态。 +- 新依赖需说明用途、许可证与维护状态，并写入正确 manifest 和 lockfile。 + diff --git a/.crmeb/skills/project-standard-bootstrap/assets/project-template/.crmeb/rules/documentation.md b/.crmeb/skills/project-standard-bootstrap/assets/project-template/.crmeb/rules/documentation.md new file mode 100644 index 000000000..06dd86b45 --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/assets/project-template/.crmeb/rules/documentation.md @@ -0,0 +1,15 @@ +--- +name: documentation +description: 项目事实、AI 规则、过程记录和测试索引边界规则 +--- + +# 文档规则 + +- `help/docs/` 描述当前项目事实，`.crmeb/` 维护 AI 规则和技能。 +- `tests/` 保存方案、决策和验收过程，并提供测试统一入口；过程文档与测试索引同目录，不另建平行的过程文档目录。 +- 同一事实只有一个权威正文，其他入口只摘要和链接。 +- 命令写明执行目录、前置条件、成功信号和已验证环境。 +- 代码、配置和可执行结果优先于旧文档；冲突时修正文档并记录证据。 +- 新增或移动文档后检查链接、索引和易漂移事实。 +- 后端及每个独立前端应用必须有就近 `README.md`，并链接到 `help/docs/applications/<应用ID>.md`；不能用一份总说明替代多个应用。 +- 代码变更影响应用职责、版本、命令、配置、端口、路由/API、数据、构建或发布方式时，同一变更检查并更新对应应用说明；不影响时记录已检查无需更新。 diff --git a/.crmeb/skills/project-standard-bootstrap/assets/project-template/.crmeb/rules/frontend.md b/.crmeb/skills/project-standard-bootstrap/assets/project-template/.crmeb/rules/frontend.md new file mode 100644 index 000000000..64cc3f27c --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/assets/project-template/.crmeb/rules/frontend.md @@ -0,0 +1,14 @@ +--- +name: frontend +description: 前端应用、组件、状态、接口、体验与构建规则 +--- + +# 前端规则 + +- 可独立构建的应用位于 `frontend/<应用名>/`，共享包通过 workspace 显式依赖。 +- 页面负责场景编排，业务逻辑进入 service、store、hook 或 composable。 +- 请求、响应、路由、组件属性和事件保持类型安全，并与 API 契约同步。 +- 页面覆盖 loading、empty、error、无权限和成功反馈，危险操作必须确认。 +- 使用设计令牌与共享组件，满足响应式、键盘操作和可访问名称要求。 +- 构建变量不得承载秘密；发布物从锁定依赖的干净环境生成。 + diff --git a/.crmeb/skills/project-standard-bootstrap/assets/project-template/.crmeb/rules/fullstack.md b/.crmeb/skills/project-standard-bootstrap/assets/project-template/.crmeb/rules/fullstack.md new file mode 100644 index 000000000..10ed5708c --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/assets/project-template/.crmeb/rules/fullstack.md @@ -0,0 +1,15 @@ +--- +name: fullstack +description: 前端到后端、API、权限、数据库和升级交付的跨层同步规则 +--- + +# 全栈协作规则 + +- 从前端 API 函数追踪 request 封装、后端路由、Controller、Service、Repository 和 migration，不根据字段名猜实现。 +- 前端校验负责体验，服务端负责安全校验、权限、所有权和业务不变量。 +- 新增持久化字段同步 migration、Model、Service、API schema、前端类型、表单、列表、测试和升级包。 +- 列表接口由后端分页、校验筛选和限制排序；数据库索引对应实际查询。 +- 权限同步菜单、路由、中间件、角色数据和前端控制，隐藏按钮不能替代服务端鉴权。 +- 手工改库只能用于经授权的临时诊断，正式交付必须通过可追踪迁移。 +- 对不熟悉后端的协作者，用页面/API语言解释影响，提供真实路径和最小验证命令。 + diff --git a/.crmeb/skills/project-standard-bootstrap/assets/project-template/.crmeb/rules/git-and-release.md b/.crmeb/skills/project-standard-bootstrap/assets/project-template/.crmeb/rules/git-and-release.md new file mode 100644 index 000000000..b4bab3d08 --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/assets/project-template/.crmeb/rules/git-and-release.md @@ -0,0 +1,14 @@ +--- +name: git-and-release +description: Git 变更边界、提交、版本、构建与发布规则 +--- + +# Git 与发布规则 + +- 修改前检查工作区，保留用户已有变更；提交按主题分离。 +- 不提交秘密、运行数据、缓存、依赖目录、临时产物和本地 IDE 配置。 +- 版本号来自唯一来源，已发布 tag、manifest 和迁移不可回改。 +- 构建和发布从干净提交执行，制品记录来源提交和校验和。 +- 生成本地制品不等于授权提交、推送、打 tag、发布或上传。 +- 发布说明包含变更、兼容性、迁移、备份、回滚边界和验证结果。 + diff --git a/.crmeb/skills/project-standard-bootstrap/assets/project-template/.crmeb/rules/security.md b/.crmeb/skills/project-standard-bootstrap/assets/project-template/.crmeb/rules/security.md new file mode 100644 index 000000000..087dfbd05 --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/assets/project-template/.crmeb/rules/security.md @@ -0,0 +1,14 @@ +--- +name: security +description: 凭据、鉴权、输入、上传、日志和供应链安全规则 +--- + +# 安全与日志规则 + +- 密钥、令牌、Cookie、真实账号和生产数据不得进入仓库、日志或升级包。 +- 服务端对每个资源执行认证、授权和对象所有权校验。 +- SQL 参数化；上传校验内容、大小、类型、位置和访问权限。 +- 回调和支付验证签名、时效、重放与幂等。 +- 日志结构化且脱敏，异常响应不泄露堆栈和内部配置。 +- 依赖使用锁文件与可信源；高风险漏洞必须在发布前处理或明确阻断。 + diff --git a/.crmeb/skills/project-standard-bootstrap/assets/project-template/.crmeb/rules/testing.md b/.crmeb/skills/project-standard-bootstrap/assets/project-template/.crmeb/rules/testing.md new file mode 100644 index 000000000..b2b0b26be --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/assets/project-template/.crmeb/rules/testing.md @@ -0,0 +1,14 @@ +--- +name: testing +description: 测试分层、回归、数据隔离与质量门禁规则 +--- + +# 测试规则 + +- 新功能和缺陷修复覆盖业务不变量、权限、失败路径和回归场景。 +- 单元、集成、契约、端到端和生命周期测试职责分明，不互相冒充。 +- 测试数据可重复创建和清理，不依赖个人环境或生产数据。 +- `check/test/build` 在本地与 CI 使用同一入口和锁定依赖。 +- 被跳过、环境受限或未运行的测试必须明确报告，不能写成通过。 +- 升级相关变更至少验证最近稳定版到目标版，声明跨级支持时验证完整迁移链。 + diff --git a/.crmeb/skills/project-standard-bootstrap/assets/project-template/.crmeb/rules/upgrade.md b/.crmeb/skills/project-standard-bootstrap/assets/project-template/.crmeb/rules/upgrade.md new file mode 100644 index 000000000..f36d80c9c --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/assets/project-template/.crmeb/rules/upgrade.md @@ -0,0 +1,14 @@ +--- +name: upgrade +description: 增量升级包、迁移、校验、备份和失败恢复规则 +--- + +# 升级包规则 + +- 后端、前端、数据库或运行配置发生可交付变化时判断升级包触发条件。 +- 核心升级包与插件/扩展包分离，按所有权收集文件和迁移。 +- manifest 记录版本范围、来源提交、组件、依赖、迁移、备份和回滚边界。 +- 数据迁移顺序稳定、尽可能幂等；已发布版本和迁移不可回改。 +- 包含文件清单与 SHA-256，禁止秘密、运行数据、上传文件和数据库备份。 +- 未完成旧版隔离升级、健康检查和失败恢复验证时只能标记为候选包。 + diff --git a/.crmeb/skills/project-standard-bootstrap/assets/project-template/.cursor/rules/project-standard.mdc b/.crmeb/skills/project-standard-bootstrap/assets/project-template/.cursor/rules/project-standard.mdc new file mode 100644 index 000000000..1ecc5b354 --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/assets/project-template/.cursor/rules/project-standard.mdc @@ -0,0 +1,7 @@ +--- +description: 项目统一工程规范入口；处理任何代码、文档、测试或发布任务时使用 +alwaysApply: true +--- + +项目规则唯一正文是 @../../.crmeb/AGENTS.md 。先读取该入口及其为当前任务指定的规则，不在 Cursor 目录维护第二份规则。修改后执行 `.crmeb/project.json` 声明的最小验证命令，并准确报告未验证项。 + diff --git a/.crmeb/skills/project-standard-bootstrap/assets/project-template/.github/copilot-instructions.md b/.crmeb/skills/project-standard-bootstrap/assets/project-template/.github/copilot-instructions.md new file mode 100644 index 000000000..b3457091e --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/assets/project-template/.github/copilot-instructions.md @@ -0,0 +1,4 @@ +# GitHub Copilot 项目指令 + +开始修改前先读取 [.crmeb/AGENTS.md](../.crmeb/AGENTS.md)。项目规则正文只维护在 `.crmeb/`，本文件不复制规则。按任务读取对应规则，保留已有工作区改动，并执行 `.crmeb/project.json` 声明的检查、测试和构建命令。 + diff --git a/.crmeb/skills/project-standard-bootstrap/assets/project-template/AGENTS.md b/.crmeb/skills/project-standard-bootstrap/assets/project-template/AGENTS.md new file mode 100644 index 000000000..f7d0fff07 --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/assets/project-template/AGENTS.md @@ -0,0 +1,6 @@ +# AI 开发入口 + +开始处理本仓库任务前，读取 [.crmeb/AGENTS.md](.crmeb/AGENTS.md)，再按其索引加载与目标文件和任务相关的规则。 + +项目事实以代码、可执行配置和正式文档为准。修改前保留已有工作区改动，完成后执行 `.crmeb/project.json` 声明的最小验证命令，并准确报告未验证项。 + diff --git a/.crmeb/skills/project-standard-bootstrap/assets/project-template/CLAUDE.md b/.crmeb/skills/project-standard-bootstrap/assets/project-template/CLAUDE.md new file mode 100644 index 000000000..5a0b70344 --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/assets/project-template/CLAUDE.md @@ -0,0 +1,6 @@ +@.crmeb/AGENTS.md + +# Claude Code 入口 + +项目规则正文只维护在 `.crmeb/`。先执行上面的导入，再按 `.crmeb/AGENTS.md` 的索引加载与当前任务有关的规则，不复制或另建第二套规范。 + diff --git a/.crmeb/skills/project-standard-bootstrap/assets/project-template/GEMINI.md b/.crmeb/skills/project-standard-bootstrap/assets/project-template/GEMINI.md new file mode 100644 index 000000000..8a9307d1e --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/assets/project-template/GEMINI.md @@ -0,0 +1,6 @@ +@./.crmeb/AGENTS.md + +# Gemini CLI 入口 + +项目规则正文只维护在 `.crmeb/`。先加载上面的项目规则，再按任务选择相关规则；修改后运行项目契约声明的最小验证命令。 + diff --git a/.crmeb/skills/project-standard-bootstrap/assets/project-template/README.md b/.crmeb/skills/project-standard-bootstrap/assets/project-template/README.md new file mode 100644 index 000000000..5db7c5cad --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/assets/project-template/README.md @@ -0,0 +1,21 @@ +# 项目入口 + +本仓库采用统一工程规范。项目业务介绍、真实技术栈和访问地址应在初始化后补充到本页。 + +## 快速开始 + +```bash +./run.sh doctor +./run.sh setup +./run.sh dev +./run.sh status +``` + +Windows PowerShell 使用对应的 `./run.ps1` 命令。标准命令的真实实现记录在 `.crmeb/project.json`。 + +## 导航 + +- AI 开发规则：[.crmeb/AGENTS.md](.crmeb/AGENTS.md) +- 项目正式文档：[help/docs/README.md](help/docs/README.md) +- 过程文档与测试索引：[tests/README.md](tests/README.md) + diff --git a/.crmeb/skills/project-standard-bootstrap/assets/project-template/help/docs/README.md b/.crmeb/skills/project-standard-bootstrap/assets/project-template/help/docs/README.md new file mode 100644 index 000000000..b2519ee20 --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/assets/project-template/help/docs/README.md @@ -0,0 +1,4 @@ +# 项目文档 + +本目录描述项目当前已实现事实。应用 Skill 后，根据代码和配置补齐项目概览、架构、开发运行、API、数据库、Docker、部署、运维和升级文档；不保留未经验证的模板结论。 + diff --git a/.crmeb/skills/project-standard-bootstrap/assets/project-template/llms.txt b/.crmeb/skills/project-standard-bootstrap/assets/project-template/llms.txt new file mode 100644 index 000000000..854a134d4 --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/assets/project-template/llms.txt @@ -0,0 +1,8 @@ +# Project AI entrypoints + +Project rules: .crmeb/AGENTS.md +Machine-readable project contract: .crmeb/project.json +Human project documentation: help/docs/README.md + +Always read the project rules before changing code. Tool-specific files are discovery adapters only; `.crmeb/` is the single source of truth. + diff --git a/.crmeb/skills/project-standard-bootstrap/assets/project-template/run.ps1 b/.crmeb/skills/project-standard-bootstrap/assets/project-template/run.ps1 new file mode 100644 index 000000000..3d2692986 --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/assets/project-template/run.ps1 @@ -0,0 +1,5 @@ +$ErrorActionPreference = 'Stop' +$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path +& node (Join-Path $scriptDir 'scripts/project-command.mjs') @args +exit $LASTEXITCODE + diff --git a/.crmeb/skills/project-standard-bootstrap/assets/project-template/run.sh b/.crmeb/skills/project-standard-bootstrap/assets/project-template/run.sh new file mode 100644 index 000000000..535756107 --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/assets/project-template/run.sh @@ -0,0 +1,6 @@ +#!/usr/bin/env sh +set -eu + +script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd) +exec node "$script_dir/scripts/project-command.mjs" "$@" + diff --git a/.crmeb/skills/project-standard-bootstrap/assets/project-template/scripts/docker-project.mjs b/.crmeb/skills/project-standard-bootstrap/assets/project-template/scripts/docker-project.mjs new file mode 100644 index 000000000..3ba8ec9bf --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/assets/project-template/scripts/docker-project.mjs @@ -0,0 +1,80 @@ +#!/usr/bin/env node +import fs from 'node:fs' +import path from 'node:path' +import { spawnSync } from 'node:child_process' +import { fileURLToPath } from 'node:url' + +const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..') +const composeFile = path.join(root, 'docker-compose.yml') +const action = process.argv[2] +const args = process.argv.slice(3) + +function run(command, commandArgs, options = {}) { + const result = spawnSync(command, commandArgs, { cwd: root, env: process.env, stdio: 'inherit', ...options }) + if (result.error) { + console.error(result.error.message) + process.exit(1) + } + if (result.status !== 0) process.exit(result.status ?? 1) +} + +function compose(commandArgs) { + if (!fs.existsSync(composeFile)) { + console.error('缺少 docker-compose.yml，请先生成或完善 Docker 本地环境。') + process.exit(2) + } + run('docker', ['compose', '-f', composeFile, ...commandArgs]) +} + +function requireService(value) { + if (!value || !/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(value)) { + console.error('请提供合法的 Compose 服务名。') + process.exit(2) + } + return value +} + +switch (action) { + case 'doctor': + run('docker', ['version']) + run('docker', ['compose', 'version']) + compose(['config', '--quiet']) + break + case 'setup': + compose(['build']) + break + case 'dev': + compose(['up', '-d', '--build', '--remove-orphans']) + compose(['ps']) + break + case 'restart': + compose(args.length ? ['restart', ...args.map(requireService)] : ['restart']) + break + case 'stop': + compose(['stop']) + break + case 'down': + compose(['down', '--remove-orphans']) + break + case 'status': + compose(['ps']) + break + case 'logs': + compose(['logs', '--tail', '200', '-f', ...args.map(requireService)]) + break + case 'shell': { + const service = requireService(args[0]) + compose(['exec', service, 'sh']) + break + } + case 'reset-data': + if (!args.includes('--yes')) { + console.error('该操作会删除本地 Compose 数据卷。确认后使用：./run.sh reset-data --yes') + process.exit(2) + } + compose(['down', '--volumes', '--remove-orphans']) + break + default: + console.error('用法：node scripts/docker-project.mjs [服务名|--yes]') + process.exit(2) +} diff --git a/.crmeb/skills/project-standard-bootstrap/assets/project-template/scripts/project-command.mjs b/.crmeb/skills/project-standard-bootstrap/assets/project-template/scripts/project-command.mjs new file mode 100644 index 000000000..fdc6ee5eb --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/assets/project-template/scripts/project-command.mjs @@ -0,0 +1,61 @@ +#!/usr/bin/env node +import fs from 'node:fs' +import path from 'node:path' +import { spawnSync } from 'node:child_process' +import { fileURLToPath } from 'node:url' + +const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..') +const contractPath = path.join(root, '.crmeb/project.json') +const requested = process.argv[2] +const aliases = { + 'reset-data': 'resetData', + 'upgrade-plan': 'upgradePlan', + 'upgrade-package': 'upgradePackage', + 'upgrade-verify': 'upgradeVerify', +} +const commandName = aliases[requested] || requested + +if (!requested || ['-h', '--help', 'help'].includes(requested)) { + console.log('用法：./run.sh [参数]') + process.exit(0) +} + +if (!fs.existsSync(contractPath)) { + console.error('缺少 .crmeb/project.json，请先完成项目规范初始化。') + process.exit(2) +} + +let contract +try { + contract = JSON.parse(fs.readFileSync(contractPath, 'utf8')) +} +catch (error) { + console.error(`无法解析 .crmeb/project.json：${error.message}`) + process.exit(2) +} + +const command = contract.commands?.[commandName] +if (!command) { + console.error(`标准命令尚未配置：${requested}`) + process.exit(2) +} + +const rawArgs = process.argv.slice(3) +for (const value of rawArgs) { + if (!/^[A-Za-z0-9._/@:+-]+$/.test(value)) { + console.error(`参数包含不允许的字符：${value}`) + process.exit(2) + } +} +const extraArgs = rawArgs.join(' ') +const result = spawnSync(extraArgs ? `${command} ${extraArgs}` : command, { + cwd: root, + env: process.env, + shell: true, + stdio: 'inherit', +}) +if (result.error) { + console.error(result.error.message) + process.exit(1) +} +process.exit(result.status ?? 1) diff --git a/.crmeb/skills/project-standard-bootstrap/assets/project-template/tests/README.md b/.crmeb/skills/project-standard-bootstrap/assets/project-template/tests/README.md new file mode 100644 index 000000000..0db151675 --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/assets/project-template/tests/README.md @@ -0,0 +1,14 @@ +# 过程文档与测试索引 + +本目录同时承担两项职责：保存方案、决策、迁移记录和验收报告等过程文档，并提供测试统一索引。 + +```text +tests/ + README.md 本文件：过程文档导航 + 测试索引 + plans/ 待评审、进行中的方案 + reports/ 检查、验收、回归报告 +``` + +过程文档顶部标注性质（待评审 / 已实施 / 已归档）与核对日期；已实施事实必须同步到正式文档或 `.crmeb/` 规则，过程记录不得冒充当前实现。失效后删除。 + +测试索引登记各应用的静态检查、单元、集成、契约、端到端和生命周期测试位置、命令、前置依赖与覆盖边界。测试脚本按端落位，本目录不存放测试脚本。 \ No newline at end of file diff --git a/.crmeb/skills/project-standard-bootstrap/references/ai-tool-adapters.md b/.crmeb/skills/project-standard-bootstrap/references/ai-tool-adapters.md new file mode 100644 index 000000000..2c84fb5d1 --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/references/ai-tool-adapters.md @@ -0,0 +1,38 @@ +# AI 工具适配 + +## 单一真源原则 + +所有项目规则正文维护在 `.crmeb/AGENTS.md`、`.crmeb/rules/` 和 `.crmeb/skills/`。工具专属文件只负责发现和导入，不复制长期规则，避免 Codex、Claude、Cursor、Copilot 和 Gemini 得到不同结论。 + +## 默认适配矩阵 + +| 工具 | 仓库入口 | 适配方式 | +| --- | --- | --- | +| Codex 及 AGENTS 兼容工具 | `AGENTS.md` | Markdown 薄入口指向 `.crmeb/AGENTS.md` | +| Claude Code | `CLAUDE.md` | 使用 `@.crmeb/AGENTS.md` 导入真源 | +| Cursor | `.cursor/rules/project-standard.mdc` | `alwaysApply: true`，引用 `.crmeb/AGENTS.md` | +| GitHub Copilot | `.github/copilot-instructions.md` | 仓库级指令要求先读取 `.crmeb/AGENTS.md` | +| Gemini CLI | `GEMINI.md` | 使用 `@./.crmeb/AGENTS.md` 导入真源 | +| 通用抓取或其他工具 | `llms.txt` | 只给项目入口和 `.crmeb` 真源路径 | + +这些路径依据各工具官方发现机制设置：[Codex AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md)、[Claude Code memory](https://code.claude.com/docs/en/memory)、[Cursor Rules](https://docs.cursor.com/context/rules)、[GitHub Copilot instructions](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions-in-your-ide/add-repository-instructions-in-your-ide)、[Gemini CLI context](https://google-gemini.github.io/gemini-cli/docs/cli/gemini-md.html)。 + +## 生成要求 + +- 初始化时创建缺失入口，不覆盖项目已有工具指令。 +- 已有入口包含项目专属内容时，保留内容并增加指向 `.crmeb` 的引导；冲突条款需人工或 AI 语义合并。 +- 默认使用入库薄文件而不是软链接，保证 Windows 和压缩包场景可用；项目明确采用软链接时验证 Git 与目标工具能正确发现。 +- 工具专属入口保持简短，避免每次会话加载完整规则库；具体规则由 `.crmeb/AGENTS.md` 按任务路由。 +- 子目录需要特殊约定时，优先使用工具支持的作用域机制或子目录入口，但正文仍链接到 `.crmeb/scopes/`。 + +## 验证 + +1. 静态检查所有入口存在且包含 `.crmeb/AGENTS.md`。 +2. Codex/AGENTS 工具确认根入口生效。 +3. Claude Code 用 `/context` 检查 `CLAUDE.md` 和导入文件。 +4. Gemini CLI 用 `/memory show` 或 `/memory list` 检查 `GEMINI.md`。 +5. Cursor 在 Rules 设置或上下文中确认项目规则生效。 +6. Copilot 用仓库上下文发起一次规则相关问题，确认读取仓库级指令。 + +若无法实际启动某工具，只能报告“入口静态有效”，不得声称已验证该工具发现成功。 + diff --git a/.crmeb/skills/project-standard-bootstrap/references/api-and-database.md b/.crmeb/skills/project-standard-bootstrap/references/api-and-database.md new file mode 100644 index 000000000..23a9acc27 --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/references/api-and-database.md @@ -0,0 +1,32 @@ +# API 与数据库规范 + +## API 契约 + +- HTTP/API 风格、版本策略和基础路径在项目中唯一定义。 +- 请求校验覆盖类型、长度、格式、枚举、范围和业务权限；未知字段策略明确。 +- 成功与错误响应稳定，错误含机器码和可安全展示的信息，不泄露内部异常。 +- 列表统一分页、排序和过滤语义；大结果集禁止无边界返回。 +- 创建、支付、回调和重试接口定义幂等键或等价机制。 +- OpenAPI、GraphQL schema、protobuf 等机器契约是客户端类型和契约测试的优先来源。 +- 破坏性变更先提供兼容窗口、弃用说明和升级路径。 + +## 数据库 + +- 表、字段、约束和索引遵守项目语言和数据库约定，并在规则中明确。 +- 主键、时间、金额、状态、软删除和多租户字段必须有统一类型与语义。 +- 索引来自实际查询模式；唯一业务约束优先由数据库保障。 +- 迁移只向前追加，已发布迁移不回改；大表采用分阶段兼容迁移。 +- UPDATE/DELETE 有精确条件；批量操作评估锁、事务大小和恢复方式。 +- 新安装 schema、种子和所有历史迁移必须得到一致结果。 + +## 契约联动 + +数据结构变化必须同步检查：Model/Entity、Repository、Service、API schema、前端类型、表单、列表、导入导出、权限、缓存、事件、测试、新安装和升级迁移。 + +## 验证 + +- 校验迁移顺序、重复执行行为和失败恢复。 +- 对关键查询查看执行计划或等价分析，确认索引命中和结果边界。 +- 契约测试覆盖必填/可选字段、错误、分页、权限和版本兼容。 +- 禁止把生产数据复制到开发或测试环境，脱敏数据也需遵守授权和保留策略。 + diff --git a/.crmeb/skills/project-standard-bootstrap/references/backend-standard.md b/.crmeb/skills/project-standard-bootstrap/references/backend-standard.md new file mode 100644 index 000000000..9bbdd6576 --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/references/backend-standard.md @@ -0,0 +1,42 @@ +# 后端通用规范 + +## 架构边界 + +- 依赖方向必须单向且可描述，领域层不依赖 Web、数据库驱动或具体第三方 SDK。 +- Controller/Handler 负责协议适配、鉴权入口和参数转换，不承载核心业务。 +- Service/UseCase 编排业务和事务；Repository/DAO 隔离持久化；外部服务通过 Adapter/Gateway 隔离。 +- 跨模块调用通过公开契约、事件或接口，不引用对方内部实现。 +- 框架确有不同最佳实践时，在 `.crmeb/rules/backend.md` 写清实际分层和例外。 + +## 数据与事务 + +- 事务边界位于业务用例层，事务内避免不受控网络调用和长耗时处理。 +- 写操作明确并发、幂等和重试语义；支付、库存、回调、任务尤其如此。 +- 查询必须分页，避免 N+1、无边界全表加载和 `SELECT *` 类不稳定契约。 +- 缓存必须定义 key、TTL、失效责任和一致性策略，不把缓存当权威数据源。 + +## 输入、错误和日志 + +- 所有外部输入在边界校验、归一化和限流；内部方法仍维护业务不变量。 +- 业务错误、校验错误、权限错误、依赖故障和未知异常分层映射。 +- 不吞异常、不空 catch、不把堆栈或敏感数据返回客户端。 +- 结构化日志包含请求/任务关联 ID、模块、动作和结果；密码、令牌、Cookie、身份证件等必须脱敏。 + +## 异步任务 + +- 队列消息和事件 payload 版本化，消费者可幂等处理和安全重试。 +- 定时任务和 worker 明确超时、重试、退避、死信和人工补偿。 +- 进程入口纳入标准 status/logs/healthcheck，升级后验证重启与积压情况。 + +## 验证 + +- 领域规则优先单元测试；数据库和外部适配使用集成测试。 +- 权限、并发、幂等、事务回滚、重试和失败补偿必须覆盖高风险路径。 +- 使用该语言 Profile 中项目真实存在的 lint、类型、测试和构建工具。 + +## 后端应用说明文档 + +- 后端目录必须维护就近 `README.md`，并链接到 `help/docs/applications/<后端ID>.md` 的详细说明；多后端应用或服务要分别建档。 +- 根据当前 manifest/lockfile、框架入口、路由、配置样例、迁移、worker/scheduler、测试和 CI 核对技术栈、版本、分层、命令、端口、依赖服务和健康信号。 +- 修改运行时、扩展、启动入口、路由/API、配置、数据库、异步进程、测试或部署方式时，同一变更检查并更新对应说明。 +- 旧说明与代码不一致时，以代码、配置和实际执行结果为准，并明确尚未动态验证的内容。 diff --git a/.crmeb/skills/project-standard-bootstrap/references/directory-and-architecture.md b/.crmeb/skills/project-standard-bootstrap/references/directory-and-architecture.md new file mode 100644 index 000000000..7f08fee10 --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/references/directory-and-architecture.md @@ -0,0 +1,156 @@ +# 目录与架构 + +本文给出可迁移的职责模型。目标项目已有成熟约定时，应映射职责而不是机械改名。 + +## 四层职责模型 + +| 层级 | 回答的问题 | 典型内容 | 生命周期 | +| --- | --- | --- | --- | +| 项目事实层 | 项目当前如何组成、运行和部署 | 项目概览、架构、开发、API、数据、部署、运维 | 随代码同步更新 | +| AI 协作层 | AI 应如何理解、修改和验证 | `AGENTS.md`、规则、技能、目录约定、验证要求 | 随工程规范更新 | +| 过程记录层 | 为什么改、如何迁移、验收结果是什么 | 方案、ADR、评审、迁移记录、检查报告 | 完成后归档或删除 | +| 测试验证层 | 如何证明系统仍然正确 | 测试地图、测试数据、执行命令、CI 说明、覆盖边界 | 随测试体系更新 | + +同一事实只在一个层级拥有正文。例如： + +- “Node 版本要求”归开发运行指南；AI 规则只链接过去。 +- “目录禁止放什么”归工程或 AI 规则；根 README 只给入口。 +- “某重构尚未实施”归方案；落地后把当前结果更新到正式文档。 +- “如何执行集成测试”归测试索引；方案只记录为什么增加它。 + +## 推荐目录 + +没有既有约定时，可从以下最小结构开始： + +```text +repository/ + README.md 项目单一入口 + AGENTS.md AI 发现入口，保持简短 + backend/ 全部后端代码与后端测试 + frontend/ 全部前端应用与前端共享包 + admin/ 示例：管理端（按真实应用命名） + web/ 示例：桌面 Web 端 + mobile/ 示例：移动端/H5/跨端应用 + help/docs/ + README.md 正式文档索引 + overview.md 产品定位、角色、能力边界 + architecture.md 系统结构、模块关系、关键链路 + development.md 环境、安装、配置、启动、构建 + testing.md 测试地图、命令、依赖与覆盖边界 + api.md API 约定或权威 API 文档入口 + database.md 数据模型、迁移、备份恢复边界 + deployment.md 部署、升级、回滚、健康检查 + operations.md 日志、监控、任务、常见故障 + docker-development.md Docker 本地开发、调试与数据维护 + upgrade.md 升级包生成、安装、验证与失败恢复 + .crmeb/ AI 规则、技能与子智能体唯一来源 + AGENTS.md 规则和技能索引 + rules/ + skills/ + agents/ + tests/ 过程记录层与测试验证层同目录，名称由契约 directories.process 声明（缺省 tests/） + README.md 过程文档导航 + 测试统一入口；正文可链接 help/docs/testing.md + plans/ + decisions/ + reports/ + docker/ 镜像与服务配置，不存放业务源码 + compose.yaml 本地开发服务编排入口 + upgrades/ + versions/ 版本迁移与升级定义真源 + packages/ 自动生成的升级包；通常由 .gitignore 排除 +``` + +只创建有真实内容和明确维护者的文件。小型项目可合并 `overview`、`architecture` 和 `development`；无数据库或部署职责的项目不应制造空文档。 + +## 代码目录统一规范 + +### 后端 `backend/` + +- 所有服务端业务代码、依赖清单、迁移和后端测试统一位于 `backend/`。 +- 单体项目直接在 `backend/` 内按框架惯例组织；多服务项目使用 `backend/apps/<服务名>/`，共享库使用 `backend/packages/` 或目标语言的标准 workspace 结构。 +- 不在仓库根目录散落 `api/`、`server/`、`service/` 等与 `backend/` 并列的后端业务目录。 +- 后端命令必须说明是在仓库根还是 `backend/` 执行；Docker 容器内工作目录也应映射到该边界。 + +### 前端 `frontend/` + +- 所有浏览器端、管理端、H5、移动端、桌面端等前端工程统一位于 `frontend/`。 +- 每个可独立安装、构建或发布的客户端使用 `frontend/<应用名>/`，例如 `frontend/admin/`、`frontend/web/`、`frontend/mobile/`。 +- 多应用共享组件和 SDK 使用 `frontend/packages/` 或 `frontend/shared/`；其依赖关系由 workspace 配置显式声明。 +- 不在根目录散落 `admin/`、`web/`、`h5/`，也不把前端构建产物放进 `backend/` 源码。若部署必须复制静态产物，应由构建或发布脚本完成并记录来源。 + +### 已有项目迁移 + +新项目直接遵守上述命名。已有项目目录不一致时，先盘点以下引用再迁移： + +- import、autoload、workspace 与构建入口； +- Docker build context、volume 和工作目录； +- CI、部署、Nginx、进程管理与脚本路径； +- 文档、测试、代码生成器和 IDE 配置。 + +目录迁移应作为独立变更，保留可回滚方案并运行构建、测试和启动验证。用户只要求完善文档时，只记录目标结构和迁移方案，不擅自移动业务代码。 + +## 入口设计 + +### 根 README + +根 README 是导航页，不是所有内容的复制品。它至少应让读者快速得到： + +1. 项目解决什么问题； +2. 主要目录或子项目是什么； +3. 最短可运行路径是什么； +4. 开发、测试、部署、贡献和 AI 规则在哪里； +5. 哪些事项必须先阅读。 + +### AI 入口 + +根 `AGENTS.md` 或工具发现文件应保持短小，只负责： + +- 指向规则唯一来源； +- 说明更深目录存在作用域更小的规则； +- 告诉 AI 如何选择技能和验证方式； +- 禁止明显高风险行为。 + +不要在多个工具目录复制整套规则。工具必须使用不同发现路径时，优先使用链接、薄入口或生成校验机制，并明确唯一维护源。 + +AI 规则正文统一维护在 `.crmeb/`： + +- `.crmeb/AGENTS.md`：项目总入口与索引； +- `.crmeb/rules/`：违反即错误的强制规则； +- `.crmeb/skills/`：任务操作流程和专项手册； +- `.crmeb/agents/`：可选的专项角色说明； +- `.crmeb/scopes/`：可选的子项目或目录补充约定。 + +根 `AGENTS.md`、`CLAUDE.md`、`llms.txt` 等仅作为发现入口并指向 `.crmeb/AGENTS.md`，不复制正文。若目标工具需要专属目录，使用薄入口或软链接，并提供链接完整性检查。 + +默认生成 Codex/AGENTS、Claude Code、Cursor、GitHub Copilot 和 Gemini CLI 的薄入口，具体路径和验证方式见 [AI 工具适配](ai-tool-adapters.md)。跨平台项目默认使用真实薄文件，只有确认 Git 与开发环境支持时才使用软链接。 + +### 文档索引 + +按用户任务组织导航，例如“第一次运行”“理解架构”“开发接口”“写测试”“部署排障”，而不是只按字母或文件名罗列。 + +## 权威来源矩阵 + +为易漂移事实定义权威来源： + +| 事实 | 推荐权威来源 | 文档写法 | +| --- | --- | --- | +| 语言和框架版本 | manifest、lockfile、运行镜像 | 标注来源，避免凭记忆填写 | +| 启动/构建命令 | package scripts、Makefile、任务配置 | 给出执行目录和前置依赖 | +| 服务端口 | 环境样例、容器、服务配置 | 区分默认值和可覆盖值 | +| API 路由 | 路由定义、OpenAPI 生成物 | 链接权威定义，避免手抄全量接口 | +| 数据表和迁移 | migration/schema | 自动生成或校验数量与关键对象 | +| 模块/插件清单 | 注册器、模块目录、配置 | 用脚本校验，说明启用条件 | +| 测试范围 | 测试配置、目录、CI | 说明已覆盖和未覆盖部分 | +| 部署流程 | 实际部署配置、流水线 | 区分本地示例与生产流程 | +| Docker 本地开发 | `compose.yaml`、Dockerfile、环境样例 | 说明源码挂载、端口、健康检查、数据卷和重建条件 | +| 版本与升级 | 版本文件、发布标签、迁移和升级 manifest | 已发布记录不可回改，生成包与真源可追溯 | + +## 生命周期 + +1. 设计阶段：方案进入过程记录层，明确状态、负责人或核对日期。 +2. 实施阶段：代码、测试和正式文档在同一变更中更新。 +3. 验收阶段：报告记录已执行验证、结果和未覆盖项。 +4. 完成阶段：把已落地事实合并到正式文档；过程文档归档或删除。 +5. 维护阶段：CI 或定期检查发现链接、命令和事实漂移。 + +建议在贡献规范中加入“变更是否需要更新文档”的检查项，但不要承诺不存在的自动化流程。 diff --git a/.crmeb/skills/project-standard-bootstrap/references/docker-local-development.md b/.crmeb/skills/project-standard-bootstrap/references/docker-local-development.md new file mode 100644 index 000000000..ef681ed1c --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/references/docker-local-development.md @@ -0,0 +1,215 @@ +# Docker 本地开发规范 + +本规范用于建立可复现的本地容器开发环境。除用户明确要求“仅审计”外，Skill 必须读取当前项目后端实际技术栈、依赖清单和启动入口，自动生成或完善根 `docker-compose.yml`；不要把示例端口、镜像或命令当成项目事实。 + +## 目标结构 + +```text +repository/ + docker-compose.yml 本地开发统一 Compose 入口 + run.sh macOS/Linux 标准命令入口 + run.ps1 Windows 标准命令入口（需要支持时） + .env.docker.example Compose 变量样例，不含真实秘密 + backend/ 后端源码、依赖清单、迁移 + frontend/ + / 可独立运行的前端应用 + docker/ 只保存 Docker 配置和脚本，不保存运行数据 + backend/Dockerfile.dev 后端开发镜像 + frontend//Dockerfile.dev 前端开发镜像（确有容器化需要时） + nginx/ 本地反向代理配置（按需） + scripts/ 容器入口和健康检查脚本（按需） + help/docs/docker-development.md 使用者文档 +``` + +根 `docker-compose.yml` 和 `run.sh` 是所有项目统一入口，后端统一映射到 `backend/`，前端统一映射到 `frontend/<应用名>/`。旧项目尚未完成目录迁移时，先在 `.crmeb/project.json` 记录兼容路径并制定迁移计划，不得为了形式统一直接移动大量源码。生产镜像和部署编排应与本地开发配置分开，避免源码挂载、调试扩展和开发端口进入生产。 + +## 自动分析与生成 + +先运行环境分析器，核对后端运行时和版本、包管理器、启动命令、全部前端、数据库/缓存/队列、端口、worker/scheduler/WebSocket、现有 Docker 文件和配置样例。只读取非敏感样例，不读取或复制真实 `.env`。 + +生成器分两步运行：默认只预览；`--write-missing` 只创建缺失文件。已有 `docker-compose.yml`、`run.sh` 或 `docker/` 配置必须保留并语义合并。机械脚本无法可靠识别运行时、启动命令或服务时应停止猜测，但 AI 必须继续读取代码入口、技术栈 Profile、CI 和现有脚本完成生成；除非项目本身缺少必要事实且已经形成明确阻塞，否则不得把“待确认”当作最终结果。禁止用 `sleep infinity`、无效端口或虚假的 healthy 状态掩盖缺口。 + +## 后端环境到 Compose 的强制映射 + +生成 `docker-compose.yml` 前必须建立证据映射： + +| 后端事实 | Compose/Docker 输出 | +| --- | --- | +| 语言及版本约束 | 固定到兼容的基础镜像版本和构建参数 | +| manifest、lockfile、系统扩展 | Dockerfile 的依赖安装，依赖卷及重建条件 | +| Web/CLI 启动入口 | `command`、工作目录、监听地址、应用端口和健康检查 | +| 数据库、缓存、队列、对象存储 | 对应服务、版本、健康检查、网络、非敏感变量和具名卷 | +| worker、scheduler、WebSocket | 独立 Compose 服务，复用后端镜像和源码但使用真实命令 | +| migration、seed、初始化脚本 | 首次启动说明和可重复执行的初始化入口，不塞进普通重启 | +| 上传、日志和持久化目录 | 明确开发卷、权限和保留策略，不提交运行数据 | + +PHP 必须继续核对 Composer `ext-*`、FPM/CLI 和 Web 入口；Node 必须核对 Node 版本、包管理器、lockfile 与真实 script；Python 必须核对依赖管理器和 ASGI/WSGI 入口；Java 必须核对 JDK、Maven/Gradle 与启动产物；Go 必须核对 Go 版本、构建入口和运行参数。框架 Profile 只能帮助发现事实，不能替代项目分析。 + +## Compose 必备信息 + +根据项目实际需要定义服务，常见职责如下： + +| 服务 | 代码/数据来源 | 必须说明 | +| --- | --- | --- | +| `backend` | `backend/` 源码挂载 | 工作目录、启动命令、应用端口、健康检查 | +| `frontend-` | `frontend//` 源码挂载 | 包管理器、开发命令、HMR 端口、API 地址 | +| `db` | 命名数据卷 | 数据库版本、库名、健康检查、初始化/迁移方式 | +| `redis` | 命名数据卷或临时卷 | 版本、端口、持久化策略 | +| `proxy` | `docker/nginx/` 等配置 | 对外入口、转发目标、静态文件来源 | +| worker/scheduler | 与后端相同源码或镜像 | 命令、依赖服务、重启策略、日志位置 | + +必须满足以下约束： + +1. 使用明确的镜像版本，不使用不可追溯的 `latest` 作为长期基线。 +2. `docker-compose.yml` 中的 build context、Dockerfile、working directory 与 `backend/`、`frontend/` 目录一致。 +3. 开发容器挂载本地源码，实现代码修改立即生效；不要把宿主机的依赖目录直接覆盖容器依赖。 +4. 依赖目录使用容器命名卷，例如 `/workspace/backend/vendor`、`/workspace/frontend/admin/node_modules`，或使用经验证的宿主机策略。 +5. 数据库、缓存等有状态服务使用具名卷；清理卷是破坏性操作，文档必须单独警告。 +6. 密码和令牌通过未入库的 `.env` 注入，仓库只提供 `.env.example` 与非敏感默认值。 +7. 服务依赖优先结合 `healthcheck` 判断就绪；`depends_on` 的启动顺序不等于依赖服务已经可用。 +8. 应用监听容器内 `0.0.0.0`，端口映射可由环境变量覆盖，并在文档中列出默认值。 +9. macOS/Windows 说明文件监听、权限和卷性能差异；Linux 说明 UID/GID 映射策略。 +10. 本地 Compose 不复用生产数据库、生产凭据或生产网络。 + +## 源码挂载模式 + +Compose 配置应表达以下关系，具体镜像和命令从项目事实生成： + +```yaml +services: + backend: + build: + context: . + dockerfile: docker/backend/Dockerfile.dev + working_dir: /workspace/backend + volumes: + - ./backend:/workspace/backend + - backend-dependencies:/workspace/backend/vendor + env_file: + - .env + depends_on: + db: + condition: service_healthy + + frontend-admin: + build: + context: . + dockerfile: docker/frontend/admin/Dockerfile.dev + working_dir: /workspace/frontend/admin + volumes: + - ./frontend/admin:/workspace/frontend/admin + - frontend-admin-dependencies:/workspace/frontend/admin/node_modules + environment: + FILE_WATCH_POLLING: "false" + +volumes: + backend-dependencies: + frontend-admin-dependencies: + database-data: +``` + +上例只展示目录和卷策略。生成目标项目配置时必须替换为真实的依赖目录、环境变量和服务命令；非 PHP 后端不应保留 `vendor`，非 Node 前端不应保留 `node_modules`。仅在原生文件监听失效时才为对应平台启用轮询，避免无谓 CPU 消耗。 + +## 必须生成的本地运行文档 + +`help/docs/docker-development.md` 至少包含以下章节。 + +### 1. 适用范围 + +- Docker 是默认开发方式、可选兼容方式还是仅用于某些依赖； +- 已验证的 Docker Engine、Compose 与 CPU 架构； +- 与宿主机直接运行方式的区别和不能覆盖的场景。 + +### 2. 服务与端口 + +列出服务名、容器端口、宿主机默认端口、健康检查、数据卷和用途。明确端口由哪个环境变量覆盖，避免只写一个可能冲突的固定值。 + +### 3. 首次启动 + +按可执行顺序记录： + +1. 检查 Docker 与 Compose 版本； +2. 从 `.env.example` 创建本地 `.env`； +3. 构建开发镜像； +4. 启动基础设施并等待健康； +5. 安装后端和前端依赖； +6. 创建数据库、执行迁移或导入最小数据； +7. 启动应用、worker 和 scheduler； +8. 通过健康检查、页面或最小 API 验证成功。 + +每一步都要写明执行目录和成功信号。只有实际存在且验证过的命令才能进入文档。 + +### 4. 日常开发 + +文档应给出项目真实对应命令： + +```bash +docker compose up -d +docker compose ps +docker compose logs -f backend +docker compose exec backend +docker compose exec frontend-admin +docker compose stop +docker compose down +``` + +同时说明： + +- 修改后端和前端源码是否立即生效； +- 新增依赖后在容器内执行什么命令、何时需要重建镜像； +- 如何运行 lint、类型检查、单元测试、集成测试和构建； +- 如何进入容器、查看日志、检查端口和健康状态； +- worker、scheduler、WebSocket 等进程如何重启。 + +`` 只是编写模板时的标记，交付到目标项目文档前必须替换为真实命令，不能原样保留。 + +### 5. 数据库与持久化 + +- 说明初始化、迁移、种子、备份和恢复命令； +- 标明数据库卷名称和数据保留行为； +- `docker compose down` 与 `docker compose down -v` 的区别必须写清楚； +- 删除数据卷、重建数据库或执行不可逆迁移前必须获得明确授权； +- 测试数据和开发账号不得包含生产数据或真实个人信息。 + +### 6. 重建与清理 + +按影响分级： + +| 操作 | 适用场景 | 数据影响 | +| --- | --- | --- | +| 重启服务 | 配置或进程异常 | 不删除数据 | +| 重建指定镜像 | Dockerfile、系统扩展变化 | 通常保留命名卷 | +| 重装应用依赖卷 | lockfile 或依赖损坏 | 删除依赖缓存，不删除数据库 | +| 删除数据库卷 | 确认要全量重置本地数据 | 不可恢复，必须显著警告 | + +给出精确的项目命令，禁止把删除卷作为普通故障排查第一步。 + +### 7. 常见故障 + +至少覆盖： + +- 端口占用和端口覆盖； +- 镜像架构不兼容； +- 文件权限或 UID/GID； +- macOS/Windows 文件监听与卷性能； +- 数据库“已启动但未就绪”； +- 宿主机与容器访问地址混用； +- 源码已更新但容器使用旧镜像/旧依赖卷； +- Compose 项目名不同导致连接到另一组容器或数据卷。 + +每个故障写“症状、检查命令、原因、处理、验证结果”，不要只给破坏性重置命令。 + +## 验证要求 + +至少完成并如实报告： + +1. `docker compose config` 能解析当前配置； +2. 开发镜像能构建，或明确未构建原因； +3. 必要服务达到 healthy/running； +4. 本地源码修改能在容器内可见，热更新按技术栈生效； +5. 后端健康检查或最小 API 可访问； +6. 每个前端应用至少能启动或构建； +7. 测试命令能在文档指定目录执行； +8. 停止再启动后，有状态数据按文档预期保留。 + +不能启动完整环境时，至少执行 Compose 解析、Dockerfile/路径静态核对和文档链接检查，并明确未完成运行验证。 diff --git a/.crmeb/skills/project-standard-bootstrap/references/documentation-coverage.md b/.crmeb/skills/project-standard-bootstrap/references/documentation-coverage.md new file mode 100644 index 000000000..cd65efb77 --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/references/documentation-coverage.md @@ -0,0 +1,58 @@ +# 项目文档覆盖矩阵 + +文档不是固定数量的空文件，而是由项目能力动态生成的可运行知识地图。环境分析器给出 `documentation.required` 和 `missing`，AI 再以源码、配置和实际验证补全内容。 + +## 所有项目必备 + +| 文档 | 必须回答 | +| --- | --- | +| `README.md` | 项目用途、组成、五分钟启动、标准命令、文档导航 | +| `help/docs/README.md` | 按角色和任务导航全部正式文档 | +| `project-overview.md` | 用户、边界、主要能力、外部系统和非目标 | +| `architecture.md` | 应用/模块、调用链、进程、数据流、关键决策和扩展点 | +| `development.md` | 版本、依赖安装、配置、初始化、启动和成功信号 | +| `configuration.md` | 变量名、用途、必填性、默认值来源、覆盖顺序和秘密管理 | +| `api.md` | 协议、鉴权、错误、分页、幂等、版本和契约来源 | +| `testing.md` | 静态、单元、集成、端到端、冒烟、测试数据和覆盖边界 | +| `deployment.md` | 构建物、环境、部署步骤、健康检查和回滚入口 | +| `operations.md` | 进程、日志、指标、告警、任务、容量和日常操作 | +| `troubleshooting.md` | 已验证的症状、检查、原因、处理和验证结果 | +| `security.md` | 权限、秘密、敏感数据、依赖风险和安全响应 | +| `upgrade-and-rollback.md` | 版本源、升级路径、迁移、备份、验证、失败恢复 | + +## 按能力强制增加 + +| 检测到的能力 | 必备文档 | +| --- | --- | +| 后端应用 | 后端目录 `README.md` + `help/docs/applications/<后端ID>.md`：职责、入口、分层、任务、异常、事务、命令和调试 | +| 每个独立前端应用 | `frontend/<应用名>/README.md` + `help/docs/applications/<应用ID>.md`：职责、页面/路由、状态、API 客户端、环境、命令、构建和发布 | +| UniApp | `uniapp-development.md`：平台矩阵、条件编译、权限、分包、真机与发布 | +| 数据库 | `database-and-migrations.md`、`backup-and-recovery.md` | +| Docker 本地环境 | `docker-development.md`，并与根 compose/run 逐项一致 | +| worker/queue/scheduler/WebSocket | 在架构、开发和运维文档分别说明启动、健康、日志和重启 | +| 多租户、支付、对象存储、搜索等 | 增加专项边界、数据、安全、故障和测试说明 | +| 可安装升级包 | 升级清单、包格式、校验和、连续迁移与隔离验证 | + +## 内容质量门槛 + +每份正式文档必须链接证据来源，命令写明执行目录、前置条件、成功信号和副作用。待确认内容标注状态和负责人；计划不得写成已实现。禁止真实凭据、生产数据、机器私有绝对路径和无证据版本号。 + +文档完成不以“文件存在”为标准。至少执行链接检查、事实静态检查和项目标准检查；运行、部署、备份恢复或升级未实际验证时，必须明确验证等级和缺口。 + +## 逐应用说明文档 + +每个可独立安装、运行、测试、构建或发布的后端/前端应用都必须有自己的说明，不能用一份笼统的“前端开发”文档代替多个应用。应用目录内的 `README.md` 是开发者就近入口，详细事实文档放在 `help/docs/applications/<应用ID>.md`；两者应以链接分工，避免复制整段内容。 + +逐应用说明至少由当前代码核对以下事实： + +1. 应用用途、用户、边界以及与其他应用的关系； +2. 运行时、框架、包管理器和版本来源文件； +3. 目录入口、路由/页面或请求入口、状态与 API 客户端； +4. 安装、配置、开发、测试、构建、预览和发布命令； +5. 环境变量名称、默认端口、代理、依赖服务和健康信号； +6. 构建产物、部署目标、平台差异以及当前限制； +7. 常见调试入口、日志、测试位置和关联正式文档。 + +检查顺序是 manifest/lockfile → 构建配置 → 代码入口/路由 → 环境样例 → API 客户端与后端路由 → 测试/CI → 现有说明。旧 README 与代码冲突时按代码和可执行结果更新，不能反过来照抄旧说明。 + +代码变更影响应用职责、目录、运行时版本、命令、配置、端口、路由、API、权限、数据、构建产物或发布方式时，同一变更必须检查并更新对应应用说明及文档索引。纯内部重构若不改变上述事实，可以不改正文，但交付报告应说明已检查且无需更新。 diff --git a/.crmeb/skills/project-standard-bootstrap/references/documentation-governance.md b/.crmeb/skills/project-standard-bootstrap/references/documentation-governance.md new file mode 100644 index 000000000..c2300e931 --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/references/documentation-governance.md @@ -0,0 +1,146 @@ +# 文档与事实治理 + +## 1. 先建立证据账本 + +对每项关键事实记录四个字段： + +| 事实 | 证据 | 验证方式 | 状态 | +| --- | --- | --- | --- | +| 运行时版本 | manifest、lockfile、容器镜像 | 读取约束并与实际环境比较 | 已核对 / 冲突 / 未验证 | +| 启动命令 | scripts、Makefile、compose | 在正确目录执行或静态解析 | 已运行 / 仅静态 | +| API 前缀 | 路由注册文件 | 搜索注册链路，必要时列路由 | 已核对 / 待运行 | +| 数据结构 | migrations、schema | 解析迁移或连接测试库 | 已核对 / 环境受限 | + +先收集证据，再决定写什么。遇到冲突时报告冲突并以可执行配置为优先，不应选择看起来更合理的旧描述。 + +## 2. 项目发现顺序 + +### 仓库与规则 + +- 根目录、Git 状态、远程托管平台； +- 所有适用的 `AGENTS.md`、贡献指南和目录规则； +- workspace/monorepo 配置和各子项目边界； +- 当前未提交修改，避免覆盖或误归因。 + +### 技术栈与依赖 + +- manifest、lockfile、运行镜像和版本文件； +- 后端、前端、移动端、插件、任务进程等入口； +- 包管理器、构建工具、代码生成、数据库和缓存； +- 生产依赖与仅开发依赖的区别。 + +### 可执行工作流 + +- 安装、初始化、启动、停止、构建、测试、lint、类型检查； +- 环境变量样例、配置覆盖顺序、默认端口； +- 数据库创建、迁移、种子、升级、备份和回滚； +- 容器、CI、发布、健康检查和日志位置。 + +项目存在 Dockerfile 或 Compose 时，还要确认它是生产构建、本地开发还是两者兼有，并检查源码是否挂载、依赖目录如何隔离、服务是否有健康检查。详细检查使用 [Docker 本地开发规范](docker-local-development.md)。 + +### 系统结构 + +- 请求入口、路由、控制器/服务/数据访问层； +- 前端路由、状态管理、API 客户端和构建产物； +- 异步任务、定时器、WebSocket、缓存、文件存储； +- 插件或模块的发现、安装、启停、卸载和权限边界。 + +### 验证资产 + +- 单元、集成、端到端、契约、冒烟测试； +- fixture、测试数据和依赖服务； +- CI 实际执行的检查； +- 本地无法覆盖的动态路径。 + +### 版本与升级资产 + +- 唯一版本源、发布标签、历史版本和允许升级范围； +- 数据库迁移、基础数据迁移、升级日志和失败恢复机制； +- 后端发布物、各前端应用构建产物及配置覆盖边界； +- 现有升级器、manifest、校验和、备份与回滚能力； +- 核心升级包与插件/扩展包的所有权边界。 + +需要生成或修复升级交付时使用 [自动升级包规范](upgrade-package.md)，不得仅依据工作区全部改动直接压缩。 + +## 3. 差距评估 + +按以下维度给出“完整 / 部分 / 缺失 / 冲突”，每条结论必须附证据： + +1. 发现性：根入口是否能到达所有关键文档； +2. 正确性：版本、路径、命令、端口、路由是否与代码一致； +3. 可运行性：新环境是否有从零到运行的闭环； +4. 可开发性：架构、目录、规则和扩展方式是否明确； +5. 可验证性：测试层级、命令、成功信号和限制是否明确； +6. 可运维性：部署、升级、回滚、日志、监控是否覆盖； +7. AI 友好性：规则是否可发现、范围是否清楚、验证是否可执行； +8. 可维护性：是否存在重复真相源、失效链接和自动校验缺口。 +9. 目录一致性：AI 规则、后端与前端是否分别归入 `.crmeb/`、`backend/`、`frontend/`，不一致时是否有安全迁移方案。 +10. 升级能力：旧版本能否通过连续迁移、安全文件替换和验证步骤升级，失败时是否可停止并恢复。 +11. 文档覆盖：按 [项目文档覆盖矩阵](documentation-coverage.md) 检查通用文档与数据库、UniApp、异步进程、Docker、升级等条件文档，防止只补 README 和启动说明。 + +## 4. 实施策略 + +### 先修 P0 + +- 错误或危险命令； +- 泄露的凭据或真实环境数据； +- 根入口和实际项目完全脱节； +- 多份文档对同一事实给出冲突结论； +- 把待实施方案写成当前能力。 + +### 再补最短闭环 + +以新接手者路径实施： + +1. 从根 README 识别项目； +2. 安装正确版本的运行环境和依赖； +3. 从样例建立本地配置； +4. 启动最小依赖和应用； +5. 确认健康状态或首个可见页面； +6. 运行最小测试或静态检查； +7. 找到架构、接口、数据和贡献规则。 + +命令块附近要写明执行目录、前置服务、预期结果。若某一步只适用于特定平台或版本，应紧邻命令说明。 + +### 最后治理漂移 + +优先校验最容易变化且能低成本提取的事实： + +- Markdown 内部链接与路径； +- 运行时版本和包管理器； +- 公开脚本名称； +- 模块、插件、数据库迁移或路由的关键清单； +- 根入口是否链接到规则和测试索引。 + +校验脚本应失败得清楚：指出文档值、实际值和证据位置。不要只检查“文件存在”，也不要为不可稳定解析的内容制造脆弱正则。 + +## 5. 验证分级 + +| 级别 | 含义 | 可声明的结论 | +| --- | --- | --- | +| L0 文本检查 | 格式、链接、路径、拼写 | 文档结构与引用有效 | +| L1 静态事实检查 | 从配置/代码解析版本、脚本、路由等 | 文档与当前源码一致 | +| L2 构建/测试 | 安装、lint、类型检查、单测、构建 | 对应检查在当前环境通过 | +| L3 运行验证 | 启动服务、健康检查、集成/冒烟测试 | 指定运行链路已实际验证 | +| L4 生命周期验证 | 安装、升级、回滚、插件启停/卸载 | 指定生命周期场景已验证 | + +报告必须使用实际达到的级别。L0/L1 不能写成“项目可正常运行”，单元测试通过也不能替代部署或升级验证。 + +## 6. 环境与安全边界 + +- 不读取或输出真实密钥、令牌、Cookie、个人数据；环境示例只保留占位值。 +- 不因文档检查擅自连接生产库、运行生产迁移、删除数据或发布版本。 +- 不默认容器存在或能启动；先检查运行时、镜像和服务状态。 +- 不把本机偶然路径写成所有开发者的固定要求，除非项目本身规定如此。 +- 添加 CI 前先确认托管平台和现有流水线；非 GitHub 项目不要擅自添加 GitHub Actions。 +- 依赖不可用时，完成安全的静态验证并明确动态覆盖缺口。 + +## 7. 审计输出格式 + +仅审计时，推荐用表格输出： + +| 优先级 | 问题 | 证据 | 影响 | 建议 | +| --- | --- | --- | --- | --- | +| P0/P1/P2 | 明确且可复现的问题 | 文件、配置或命令结果 | 对运行/开发/AI 的影响 | 最小可实施动作 | + +结尾给出建议实施顺序和验证计划。没有证据的推测单独标注为“待确认”。 diff --git a/.crmeb/skills/project-standard-bootstrap/references/frontend-backend-database-bridge.md b/.crmeb/skills/project-standard-bootstrap/references/frontend-backend-database-bridge.md new file mode 100644 index 000000000..312055d41 --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/references/frontend-backend-database-bridge.md @@ -0,0 +1,100 @@ +# 前端到后端与数据库 + +本指南帮助以页面开发为主的开发者和 AI 安全完成全栈改动。目标不是要求前端绕过后端直接改库，而是能追踪数据来源、理解影响并使用迁移和测试完成闭环。 + +## 先建立请求链路 + +```text +页面/组件 + → 前端 API 函数与类型 + → HTTP 请求封装、认证和 base URL + → 后端路由与中间件 + → Controller/Handler 输入校验 + → Service/UseCase 业务规则与事务 + → Repository/DAO/ORM + → 数据库表、索引与迁移 + → 统一响应、错误码和前端状态 +``` + +排查或开发时沿这条链路双向追踪，记录每层真实文件。不要只从页面字段名猜测数据库字段，也不要从表结构直接推断接口权限和业务语义。 + +## 快速找到后端实现 + +1. 从前端 API 函数找到请求方法和相对路径。 +2. 确认 request 封装添加的 API 前缀、版本、租户和认证头。 +3. 在后端路由中搜索静态路径片段；动态参数按路由声明核对。 +4. 继续定位 Controller/Handler、输入校验和权限中间件。 +5. 从 Service/UseCase 找到业务规则、事务、事件和缓存失效。 +6. 从 Repository/DAO/ORM 找到表、字段、关联和查询条件。 +7. 从 migration/schema 确认结构真源，不以运行库临时状态代替迁移。 + +找不到时优先查看路由列表命令、OpenAPI、框架注册器和模块清单，不要新建重复接口。 + +## 前端常见任务的全链路清单 + +### 新增一个字段 + +- 明确字段属于展示、提交、数据库持久化还是计算结果。 +- 数据库存储时新增迁移、索引/约束和新安装 schema；设置安全默认值及历史数据策略。 +- 更新 Entity/Model、允许字段、Repository、Service 和序列化。 +- 更新请求校验、API schema、响应类型、前端类型、表单和展示。 +- 覆盖新建、编辑、详情、列表、导入导出和权限场景。 +- 将迁移和受影响构建产物加入升级包。 + +### 新增列表和筛选 + +- 后端实现分页、排序白名单、筛选校验和权限范围。 +- 查询避免 N+1；为实际筛选和排序组合评估索引。 +- 响应返回稳定的列表和总数契约。 +- 前端在筛选变化时重置分页，防止重复请求并处理空、错和加载结束状态。 +- 测试无数据、大数据量、非法筛选、越权和边界页。 + +### 新增或编辑表单 + +- 前端校验改善体验，后端校验才是安全边界。 +- 后端重新计算价格、权限、所有权和不可由客户端信任的数据。 +- 防止重复提交；高风险写操作使用幂等键、版本号或唯一约束。 +- 事务覆盖必须同时成功的写入，外部调用失败有补偿策略。 + +### 权限和菜单 + +- 前端路由、菜单和按钮控制只负责体验，服务端接口仍必须鉴权和校验对象所有权。 +- 权限标识、角色种子、路由中间件和前端指令保持同一稳定 key。 +- 新安装数据、存量升级迁移和卸载/回滚边界同步处理。 + +## 数据库最低知识 + +- **主键**：稳定标识记录，不把可变化的展示值当主键。 +- **唯一约束**：从数据库层阻止重复业务记录，应用仍需返回友好错误。 +- **索引**：加速特定查询但增加写入和存储成本，按查询模式设计。 +- **事务**：保证一组数据库操作整体成功或失败，不自动覆盖外部网络调用。 +- **迁移**：可追踪地改变结构或基础数据；已发布迁移不能回改。 +- **外键/软删除**：遵守项目既有策略，删除前确认关联、审计和恢复需求。 +- **NULL 与默认值**：区分未知、未填写和空值；不要依赖前端补默认值。 + +禁止在共享、测试或生产数据库手工改表来代替迁移。需要查看数据时先确认环境和只读范围；SQL UPDATE/DELETE 必须带精确条件并先用 SELECT 验证影响集合。 + +## 常见错误定位 + +| 现象 | 优先检查 | +| --- | --- | +| 401 | token 是否发送、是否过期、认证中间件和环境域名 | +| 403 | 角色权限、对象所有权、租户范围；不是简单隐藏按钮 | +| 404 | API 前缀、版本、路由方法、动态参数和代理转发 | +| 422/参数错误 | 前后端字段名、类型、必填、枚举和嵌套结构 | +| 500 | 后端结构化日志、关联 ID、异常链和数据库错误；不要只在前端重试 | +| 列表重复/缺失 | 分页基准、排序稳定性、筛选重置和并发请求覆盖 | +| 保存成功但页面不变 | 响应契约、缓存失效、状态更新和返回页面刷新 | +| 本地可用、容器失败 | base URL、容器服务名、端口、CORS、挂载和环境变量 | + +## AI 输出要求 + +当请求来自主要做前端的开发者时，AI 应： + +- 用页面和 API 语言解释后端层级与数据库影响，并给出真实文件定位； +- 明确哪些值由前端提交、后端验证、后端计算和数据库约束； +- 优先修改迁移与代码，不指导手工改库作为正式方案； +- 给出最小可执行验证命令和请求示例，但不暴露真实凭据； +- 说明本次是否涉及权限、缓存、异步任务、历史数据和升级包； +- 不要求用户先掌握后端框架术语才提供可落地方案。 + diff --git a/.crmeb/skills/project-standard-bootstrap/references/frontend-standard.md b/.crmeb/skills/project-standard-bootstrap/references/frontend-standard.md new file mode 100644 index 000000000..e72a69432 --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/references/frontend-standard.md @@ -0,0 +1,39 @@ +# 前端通用规范 + +## 应用与目录 + +- 每个可独立安装、运行和发布的客户端位于 `frontend/<应用名>/`。 +- 共享组件、类型和 SDK 进入显式 workspace package，不通过跨应用相对路径偷渡。 +- 页面负责场景编排，业务逻辑进入 composable/hook/service/store；基础组件不依赖具体业务模块。 +- API client 统一处理 base URL、鉴权、超时、取消、错误映射和响应解包。 +- 前端需求涉及新增字段、筛选、权限、持久化或后端错误时，使用 [前端到后端与数据库](frontend-backend-database-bridge.md) 追踪完整链路，不在页面层猜测或绕过后端。 +- 检测到 `@dcloudio/*`、`pages.json` 或 UniApp manifest 时，同时读取 [UniApp Profile](profiles/uniapp.md)。 + +## 类型与状态 + +- 接口请求、响应、路由参数、组件属性和事件保持类型安全；避免无理由的 `any` 或类型断言。 +- 服务端状态优先由请求缓存层管理；跨页面客户端状态才进入全局 store。 +- 派生状态使用计算值，不维护可推导的重复副本；副作用明确生命周期和清理。 +- 接口契约变化同步类型、调用方、mock、测试和兼容策略。 + +## 页面体验 + +- 页面必须处理 loading、empty、error、无权限、离线/超时和成功反馈。 +- 表单有标签、校验、提交中防重复、错误定位和键盘操作。 +- 列表有分页或虚拟化策略，搜索与筛选状态可恢复；危险操作二次确认。 +- 使用项目设计令牌和共享组件，支持响应式、深色模式及目标浏览器范围。 +- 交互元素具备可访问名称、焦点状态和合理对比度；图片和图标提供替代信息。 + +## 构建与发布 + +- `.env` 只存本地非入库配置，公开构建变量不得承载秘密。 +- lockfile 必须与选定包管理器一致；禁止混用造成依赖解析漂移。 +- 构建产物从干净依赖生成并写入升级包或部署制品，不把开发源码冒充线上产物。 +- 每个应用独立记录 dev、typecheck、lint、test、build 和 preview/smoke 命令。 + +## 每个前端应用的说明文档 + +- 每个 `frontend/<应用名>/` 必须维护就近 `README.md`，并链接到 `help/docs/applications/<应用ID>.md` 的详细说明。 +- 不能只维护一份总的“前端开发文档”；管理端、Web、H5、UniApp、小程序、桌面端等独立项目分别核对 manifest、lockfile、构建配置、路由/页面、环境变量、API 客户端、测试和发布脚本。 +- 新增或修改命令、端口、代理、路由、权限、API 地址、构建产物、目标平台或发布流程时，同步更新该应用说明和正式文档索引。 +- 文档中的版本与命令必须来自当前代码并经过静态或运行验证，不沿用另一个前端项目的配置。 diff --git a/.crmeb/skills/project-standard-bootstrap/references/fullstack-workflow.md b/.crmeb/skills/project-standard-bootstrap/references/fullstack-workflow.md new file mode 100644 index 000000000..22b2e2696 --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/references/fullstack-workflow.md @@ -0,0 +1,47 @@ +# 全栈开发流程 + +## 开始前 + +1. 读取 `.crmeb/AGENTS.md`、相关规则和应用作用域。 +2. 用 `.crmeb/project.json` 定位应用、命令和依赖服务。 +3. 检查工作区现有改动，确定本任务基线和修改边界。 +4. 明确用户角色、权限、业务不变量、验收场景和非目标。 + +## 变更链路 + +按实际影响选择，不机械制造无关层： + +1. **领域与数据**：业务规则、状态机、表结构、索引、迁移和新安装 schema。 +2. **后端**：路由、输入校验、权限、Service、Repository/DAO、事务、事件和任务。 +3. **API 契约**：请求、响应、错误码、分页、幂等、版本和 OpenAPI。 +4. **前端接口层**：类型、API client、错误映射和兼容处理。 +5. **前端体验**：路由、权限、状态、页面、组件、加载/空/错状态和可访问性。 +6. **异步与运维**：队列、定时任务、缓存失效、日志、指标和告警。 +7. **测试**：领域单测、接口集成、前端组件、关键 E2E 和回归场景。 +8. **文档与配置**：环境变量、开发运行、API、部署和运维说明。 +9. **升级交付**：迁移、构建产物、manifest、校验和、备份及回滚边界。 + +## 接口变更同步清单 + +- 路由和权限注册； +- 请求校验、响应类型、错误码和示例； +- OpenAPI 或其他契约真源； +- 前端 API client、类型和调用方； +- 缓存 key、事件 payload、队列消息和 webhook； +- mock、fixture、契约测试和兼容窗口； +- 发布说明和升级依赖。 + +删除或重命名字段前先确认所有消费者。跨版本部署时采用先扩展、再迁移、最后收缩的兼容策略。 + +## 最小验证顺序 + +1. 针对改动的格式、lint、类型和静态架构检查； +2. 后端领域与接口测试； +3. 前端组件、类型检查和构建； +4. 数据迁移幂等与新安装一致性； +5. Docker 或宿主机 smoke； +6. 关键角色的端到端路径； +7. 升级包静态检查与旧版升级验证。 + +交付时逐项报告实际执行结果。只通过静态检查不能声明功能、部署或升级已验证。 + diff --git a/.crmeb/skills/project-standard-bootstrap/references/migration-and-acceptance.md b/.crmeb/skills/project-standard-bootstrap/references/migration-and-acceptance.md new file mode 100644 index 000000000..0807d39ea --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/references/migration-and-acceptance.md @@ -0,0 +1,119 @@ +# 迁移与验收 + +## 已有项目迁移顺序 + +1. 先审计并冻结事实，不移动目录、不改命令。 +2. 建立 `.crmeb/` 真源和根级薄入口，不复制多套规则。 +3. 生成 `.crmeb/project.json`，把现有命令映射到统一契约。 +4. 补齐 `check/test/build` 门禁，再处理 Docker 和快速启动。 +5. 规划 `backend/`、`frontend/` 迁移，逐项更新 import、autoload、workspace、CI、Docker、部署和文档。 +6. 目录迁移作为独立变更，运行全量构建、测试和 smoke，并保留回滚点。 +7. 最后接入升级包与发布流程，验证旧版到新版链路。 + +用户只要求文档或规范时，不擅自移动业务代码。无法一次迁移的项目可用兼容入口过渡，但必须记录淘汰计划，避免长期双路径。 + +## 入口与导航 + +- [ ] 根 README 能说明项目定位、组成和最短启动路径。 +- [ ] 开发、架构、测试、部署和 AI 规则都能从根入口到达。 +- [ ] 文档索引按任务组织，没有孤立的关键文档。 +- [ ] 内部链接、相对路径和标题锚点全部有效。 +- [ ] 后端及每个独立前端应用都有就近 README，并链接到各自的 `help/docs/applications/<应用ID>.md`。 + +## 事实准确性 + +- [ ] 语言、框架和工具版本来自 manifest、lockfile、镜像或版本配置。 +- [ ] 安装、启动、构建、测试命令在正确目录存在。 +- [ ] 端口、路由/API 前缀、模块和数据结构与当前代码一致。 +- [ ] 文档明确区分默认值、示例值和环境覆盖值。 +- [ ] 待实施方案没有写成已具备能力。 +- [ ] 易漂移数字或清单有来源，能自动生成或校验时不靠手工维护。 +- [ ] 已逐应用检查 manifest/lockfile、构建配置、入口/路由、环境样例、API 客户端、测试和 CI，并据此更新说明。 +- [ ] 本次代码变更影响的应用文档已同步；无需更新的应用已记录检查结论和依据。 + +## 可运行与可开发 + +- [ ] 新环境的前置依赖、配置、初始化、启动和成功信号完整。 +- [ ] 命令标注执行目录、前置服务和平台限制。 +- [ ] 后端业务代码统一位于 `backend/`，没有并列散落的后端业务目录。 +- [ ] 每个可独立构建的前端应用位于 `frontend/<应用名>/`，共享包边界明确。 +- [ ] 核心目录、模块关系和关键调用链足以支持定位改动。 +- [ ] API、数据库、插件/扩展机制等项目关键领域有权威入口。 +- [ ] 常见问题包含症状、原因和验证过的处理方式。 + +## AI 协作 + +- [ ] `.crmeb/` 是 AI 规则、技能和子智能体的唯一正文来源。 +- [ ] 根 AI 入口短小，能指向 `.crmeb/AGENTS.md`。 +- [ ] `CLAUDE.md`、`GEMINI.md`、Cursor Rules、Copilot instructions 和 `llms.txt` 都是薄入口，没有复制规则正文。 +- [ ] 静态检查确认所有工具入口存在并指向 `.crmeb/AGENTS.md`；已实际验证的工具与仅静态适配的工具分别报告。 +- [ ] 规则说明作用域、禁止事项、代码风格和最小验证要求。 +- [ ] 子目录有特殊约定时能被 AI 发现。 +- [ ] 不同工具入口没有复制多份长期维护正文。 +- [ ] AI 能区分正式事实、过程记录和测试说明。 + +## 前端跨层与 UniApp + +- [ ] 前端开发指南能从 API 函数追踪到请求封装、后端路由、业务层、数据访问和迁移。 +- [ ] 新字段、列表筛选、表单和权限均有前后端、数据库、测试及升级包同步清单。 +- [ ] 文档明确禁止用手工改库替代迁移，也不把前端隐藏控件当作服务端鉴权。 +- [ ] 存在 UniApp 时登记真实平台脚本、API 地址链路、认证封装、pages/分包和条件编译约定。 +- [ ] UniApp 通用改动至少验证 H5 和目标小程序/App 平台；无法真机验证时明确限制。 +- [ ] 升级交付区分 H5 产物、小程序审核、App 资源包和原生安装包。 + +## Docker 本地开发 + +- [ ] 已从当前后端的版本、manifest/lockfile、扩展、启动入口和依赖服务生成证据映射。 +- [ ] 根 `docker-compose.yml` 已自动生成或按当前环境语义更新，不是未替换的通用模板。 +- [ ] `docker-compose.yml`、Dockerfile、工作目录与 `backend/`、`frontend/` 的实际结构一致。 +- [ ] 文档列出服务、端口、健康检查、源码挂载、依赖卷和数据卷。 +- [ ] 首次启动包含配置、构建、依赖安装、数据库初始化和成功验证。 +- [ ] 日常开发包含启动、停止、日志、容器内命令、测试和进程重启。 +- [ ] 源码改动能在容器内可见，热更新或需要重启的边界明确。 +- [ ] lockfile、Dockerfile 或系统依赖变化后的重建方式明确。 +- [ ] `down` 与 `down -v` 的数据影响明确，删除数据卷有显著警告。 +- [ ] macOS、Windows、Linux 的监听、权限或架构差异按实际情况说明。 +- [ ] 至少执行 `docker compose config`；未构建或未启动时说明原因。 + +## 测试与验证 + +- [ ] 测试地图列出层级、目录、命令、依赖和覆盖范围。 +- [ ] 文档检查至少覆盖格式、链接和引用路径。 +- [ ] 关键事实检查能报告文档值、实际值和证据位置。 +- [ ] 实际执行的 lint、测试、构建或运行验证有结果记录。 +- [ ] 未执行项及其原因明确，没有夸大验证范围。 + +## 自动升级包 + +- [ ] 已定义唯一版本源、目标版本、允许来源版本和版本递增规则。 +- [ ] 后端、前端、数据库、配置和插件变更能被正确分类。 +- [ ] 核心升级包不混入独立插件/扩展文件，插件包不修改无所有权的核心数据。 +- [ ] manifest 包含来源提交、组件、运行要求、迁移、备份、回滚边界和人工步骤。 +- [ ] 文件清单和 SHA-256 由构建结果生成并能完整复验。 +- [ ] 包内没有 `.env`、密钥、日志、缓存、上传文件、数据库备份或本地运行数据。 +- [ ] 数据迁移可追踪、顺序稳定、尽可能幂等，已发布迁移没有被回改。 +- [ ] 新安装结果与执行全部存量迁移后的最终结构一致。 +- [ ] 所有受影响的前端应用生成发布构建产物，而不是把开发源码冒充线上产物。 +- [ ] 至少验证最近稳定版到目标版；声明跨级升级时验证完整迁移链。 +- [ ] 失败不会写入成功记录，备份、停止和恢复路径有验证或明确限制。 +- [ ] 交付报告包含版本、包路径、来源提交、SHA-256、迁移概要和未验证项。 + +## 安全与维护 + +- [ ] 文档和示例不含真实密钥、令牌、Cookie、个人数据或生产地址凭据。 +- [ ] 数据迁移、删除、发布、回滚等高风险操作带有边界和前置条件。 +- [ ] CI 配置与项目实际托管平台和现有流水线一致。 +- [ ] 每类文档有清晰职责和生命周期，不存在重复真相源。 +- [ ] 改动未覆盖用户已有修改，`git diff --check` 通过。 + +## 完成判定 + +以下条件同时满足才能声明“文档体系已完善”： + +1. P0 问题全部解决或明确阻塞； +2. 从零运行、理解架构、修改代码、执行测试四条核心路径都有入口； +3. 关键事实已达到至少静态核对级别； +4. 所有实际验证与未验证项如实报告； +5. 没有为追求目录完整而留下空文档或虚构内容。 +6. 触发升级交付的变更已经生成候选升级包；未完成动态验证时没有标记为正式可发布。 +7. 非“仅审计”任务已生成或完善根 `docker-compose.yml`；无法生成时必须作为未完成阻塞报告，不能声明规范建设完成。 diff --git a/.crmeb/skills/project-standard-bootstrap/references/profiles/go.md b/.crmeb/skills/project-standard-bootstrap/references/profiles/go.md new file mode 100644 index 000000000..8bae91da7 --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/references/profiles/go.md @@ -0,0 +1,9 @@ +# Go Profile + +- 从 `go.mod`、toolchain、CI 和镜像核对 Go 版本；依赖由 `go.sum` 锁定。 +- 后端位于 `backend/`；多模块仓库使用明确的 `go.work` 和模块边界。 +- 遵循 `gofmt`/`goimports`，错误保留上下文并使用 `errors.Is/As` 等可判定机制。 +- 标准检查映射 `go vet`、项目 lint、`go test ./...`、race 测试和构建。 +- Context、超时、goroutine 生命周期、连接关闭和信号处理必须可验证。 +- 静态二进制、CGO 和目标架构进入 Docker 与升级包说明。 + diff --git a/.crmeb/skills/project-standard-bootstrap/references/profiles/java.md b/.crmeb/skills/project-standard-bootstrap/references/profiles/java.md new file mode 100644 index 000000000..04e4e86bf --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/references/profiles/java.md @@ -0,0 +1,9 @@ +# Java Profile + +- 从 Maven/Gradle 配置、toolchain、wrapper 和镜像核对 JDK 与构建工具版本。 +- 后端位于 `backend/`；必须使用仓库内 Maven/Gradle Wrapper，避免本机版本漂移。 +- 多模块依赖方向在构建文件中显式声明，领域层不依赖 Web 或持久化实现。 +- 标准检查映射 formatter、Checkstyle/SpotBugs、单测、集成测试和 assemble/build。 +- 配置按 profile/environment 隔离，密钥不进入 `application*.yml`。 +- 数据库迁移、JVM 参数、健康检查、优雅关闭和容器内存边界进入运行文档。 + diff --git a/.crmeb/skills/project-standard-bootstrap/references/profiles/node.md b/.crmeb/skills/project-standard-bootstrap/references/profiles/node.md new file mode 100644 index 000000000..54125d3a2 --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/references/profiles/node.md @@ -0,0 +1,9 @@ +# Node.js Profile + +- 从 `package.json` engines/packageManager、lockfile、版本文件和容器镜像核对 Node 与包管理器。 +- 只使用 lockfile 对应的 npm、pnpm、Yarn 或 Bun；CI 使用冻结锁文件安装。 +- Node 后端位于 `backend/`，多包项目的 workspace 边界必须显式配置。 +- 标准检查映射项目实际 scripts：lint、typecheck、test、build、start/dev。 +- 生产运行不依赖开发服务器；处理信号、优雅关闭、健康检查和未捕获异常。 +- 不提交 `node_modules/`，升级包是否带依赖由部署模型明确决定。 + diff --git a/.crmeb/skills/project-standard-bootstrap/references/profiles/php.md b/.crmeb/skills/project-standard-bootstrap/references/profiles/php.md new file mode 100644 index 000000000..a6e0ef7cd --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/references/profiles/php.md @@ -0,0 +1,9 @@ +# PHP Profile + +- 从 `composer.json`、`composer.lock`、容器镜像和 `composer check-platform-reqs` 核对 PHP 与扩展版本。 +- 后端根目录统一为 `backend/`，Composer 命令在该目录执行；`vendor/` 默认不入库。 +- 使用项目既有的 PSR、框架分层和自动加载约定，不凭经验改 namespace。 +- 标准检查优先映射 Composer scripts、PHP-CS-Fixer/PHPCS、PHPStan/Psalm、PHPUnit/Pest 和框架命令。 +- 迁移、队列、定时任务、长驻进程和 OPcache 重载必须进入运行与升级说明。 +- 宿主 PHP 不满足版本时可使用项目开发镜像，但须说明实际验证环境。 + diff --git a/.crmeb/skills/project-standard-bootstrap/references/profiles/python.md b/.crmeb/skills/project-standard-bootstrap/references/profiles/python.md new file mode 100644 index 000000000..35ce2a76b --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/references/profiles/python.md @@ -0,0 +1,9 @@ +# Python Profile + +- 从 `pyproject.toml`、lockfile、`.python-version`、tox/nox 和镜像核对 Python 版本与依赖工具。 +- 后端位于 `backend/`，虚拟环境和缓存不入库；应用包采用明确的 `src` 或框架结构。 +- 依赖必须锁定；开发、测试和生产组边界清楚。 +- 标准检查映射 Ruff/Black、mypy/pyright、pytest、构建和框架健康检查中的实际工具。 +- 数据库迁移、ASGI/WSGI、worker、scheduler 和静态资源处理进入运行说明。 +- 测试隔离时区、事件循环、数据库事务和外部服务。 + diff --git a/.crmeb/skills/project-standard-bootstrap/references/profiles/react.md b/.crmeb/skills/project-standard-bootstrap/references/profiles/react.md new file mode 100644 index 000000000..0df7f2c8d --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/references/profiles/react.md @@ -0,0 +1,9 @@ +# React Profile + +- React 应用位于 `frontend/<应用名>/`，从 manifest、lockfile 和构建框架配置核对版本。 +- 组件保持纯渲染；副作用只处理外部同步并明确依赖、取消和清理。 +- props、事件、路由、API 和表单保持类型安全，避免把派生值复制进 state。 +- 服务端缓存、全局客户端状态和组件局部状态使用不同层，避免单一 store 承载一切。 +- 标准检查映射 ESLint、TypeScript、单元/组件/E2E 测试和生产构建。 +- SSR/CSR 边界、环境变量暴露、hydration、错误边界和静态资源路径进入开发文档。 + diff --git a/.crmeb/skills/project-standard-bootstrap/references/profiles/uniapp.md b/.crmeb/skills/project-standard-bootstrap/references/profiles/uniapp.md new file mode 100644 index 000000000..a3490c58e --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/references/profiles/uniapp.md @@ -0,0 +1,44 @@ +# UniApp Profile + +## 识别与目录 + +- UniApp 应用统一位于 `frontend/uni-app/`；多套独立 UniApp 应用使用 `frontend/<应用名>/` 并在项目契约分别登记。 +- 从 `package.json` 的 `@dcloudio/*`、Vite 配置、`pages.json` 和 `manifest.json` 判断 CLI 工程、Vue 版本和目标平台。 +- 所有 `@dcloudio/*` 依赖保持同一发行版本，升级时整体同步并用 lockfile 固定。 +- 先读取 package scripts 获取真实的 H5、小程序和 App 开发/构建命令，不假设项目一定使用 HBuilderX 或某个包管理器。 + +## 页面与平台边界 + +- 页面必须登记在 `pages.json` 的主包或分包；控制主包体积并记录分包边界。 +- 页面生命周期从 UniApp API 获取，组件生命周期遵循对应 Vue 版本；不要混用导致重复请求或状态丢失。 +- 导航、请求、存储、上传、权限和系统能力优先使用 `uni.*` 跨端 API。 +- 浏览器 DOM、微信 API、App 原生能力等必须放入正确的条件编译块，块保持成对和平衡。 +- 使用 `rpx`、安全区和触屏交互规范；权限、定位、相机、相册等能力同步隐私声明与平台配置。 + +## 接口与认证 + +- 追踪“环境变量 → 构建配置 → API base URL → request 封装 → 后端路由”的完整链路。 +- 明确 token header、登录过期、刷新/重新登录、语言、租户、设备等公共请求信息。 +- API 函数只传领域路径和参数，统一封装响应、错误、超时、取消、上传及未登录处理。 +- 前端使用匿名标记前，必须确认后端路由和中间件也允许匿名。 +- 后端下发的状态、按钮、页面配置和组件 key 是跨端契约，不能在页面再次硬编码另一套映射。 + +## 多端验证矩阵 + +| 改动 | 最低验证 | +| --- | --- | +| 通用页面、组件、API | H5 + 需求指定的至少一个小程序或 App 端 | +| H5 DOM、登录、分享 | 普通浏览器；相关时验证微信内浏览器 | +| 微信/支付宝等小程序能力 | 对应平台开发者工具和真实权限配置 | +| App 原生能力 | 受影响的 Android/iOS 平台，缺少真机时明确限制 | +| `pages.json`、manifest、条件编译 | 所有受影响的平台构建 | + +同时覆盖未登录、已登录、token 过期、慢请求、空数据、后端错误、返回页面刷新和重复提交。 + +## 构建与升级交付 + +- H5 产物可按部署模型进入核心升级包，并记录 base path、API 地址和缓存刷新方式。 +- 微信、支付宝等小程序通常需要重新上传和审核；升级包 manifest 必须提示人工发布步骤，不能声称覆盖已发布小程序。 +- App 本地资源包、热更新包、原生安装包和应用商店发布是不同制品，分别记录版本、平台和签名要求。 +- `manifest.json`、App ID、证书、平台密钥和生产域名不得用个人或真实秘密模板覆盖。 + diff --git a/.crmeb/skills/project-standard-bootstrap/references/profiles/vue.md b/.crmeb/skills/project-standard-bootstrap/references/profiles/vue.md new file mode 100644 index 000000000..c1c55c1a5 --- /dev/null +++ b/.crmeb/skills/project-standard-bootstrap/references/profiles/vue.md @@ -0,0 +1,9 @@ +# Vue Profile + +- Vue 应用位于 `frontend/<应用名>/`，从 package manifest、lockfile 和 Vite/Nuxt 配置核对版本。 +- Vue 3 优先 Composition API 与 `