XuJiacheng
a8c7cf74e6
添加 Kafka 消费者、数据库写入、Redis 集成等核心模块，实现设备上下线事件处理 - 创建项目基础目录结构与配置文件 - 实现 Kafka 消费逻辑与手动提交偏移量 - 添加 PostgreSQL 数据库连接与分区表管理 - 集成 Redis 用于错误队列和项目心跳 - 包含数据处理逻辑，区分重启与非重启数据 - 提供数据库初始化脚本与分区创建工具 - 添加单元测试与代码校验脚本
87 lines
4.2 KiB
Markdown
87 lines
4.2 KiB
Markdown
开发框架约束（供 AI 创建项目使用）
|
||
|
||
目的：本文件用于约束 AI 在创建/改造项目时的技术选型、目录结构、工程化与交付流程。除非明确得到人工指令，否则 AI 不得偏离本文件的约束。
|
||
|
||
1. 运行环境与基础约束
|
||
|
||
- Node.js 版本：必须使用 Node.js 22+（建议使用最新 LTS）。
|
||
- 主要语言：JavaScript（.js）为主。
|
||
- 允许在必要时引入类型检查方案（例如 JSDoc + // @ts-check），但默认不将 TypeScript 作为主要语言。
|
||
- 包管理器：**强制统一使用 `npm`**。
|
||
- 跨平台：默认需兼容 Windows（PowerShell）与类 Unix 环境。
|
||
|
||
2. 技术栈约束
|
||
|
||
2.1 前端（如需要前端）
|
||
|
||
- 框架：必须使用 Vue 3.x。
|
||
- 生态库：仅引入与 Vue 3.x 兼容的相关库；避免引入与 Vue 2.x 绑定的历史库。
|
||
- 构建工具：优先 Vite（如与既有工程冲突，需说明原因并保持一致性）。
|
||
|
||
2.2 后端（如需要后端）
|
||
|
||
- 运行时：必须使用 Node.js。
|
||
- 语言：后端同样以 JavaScript 为主。
|
||
- API 风格：默认使用 HTTP JSON API（如采用 GraphQL/WebSocket 等需明确说明并仍遵循 OpenSpec 约束）。
|
||
|
||
3. OpenSpec（规范驱动）开发流程约束
|
||
|
||
> 说明：这里的 OpenSpec 指通过全局安装 `@fission-ai/openspec` 获得的规范驱动工具链；在 API 场景下，接口契约必须使用并遵守 OpenAPI 3.1。两者不冲突：OpenSpec 用于驱动/校验流程，OpenAPI 3.1 是规范文件中必须满足的契约。
|
||
|
||
3.0 OpenSpec 工具链安装（强制）
|
||
|
||
- 开发与 CI 环境必须确保可用的 OpenSpec 工具链：
|
||
- 安装命令：npm install -g @fission-ai/openspec@latest
|
||
- AI 在生成项目脚本时：
|
||
- 必须将规范校验能力接入到 npm scripts（见 3.3）。
|
||
- 不得绕过 OpenSpec 校验直接交付“未受规范约束”的 API 实现。
|
||
3.1 必须交付的规范产物
|
||
|
||
- 项目必须包含一个可追溯的规范文件：
|
||
- API 项目：`spec/openapi.yaml`（或 `spec/openapi.json`），版本 OpenAPI 3.1。
|
||
- 非 API 项目：仍需提供对应的“规格说明”（例如流程/数据结构/输入输出契约），放在 spec/ 目录下。
|
||
- 规范文件需满足：
|
||
- 可被校验（lint/validate）
|
||
- 与实现一致（实现变更必须同步更新规范）
|
||
3.2 开发顺序（强制）
|
||
|
||
1. 先写/更新规范（spec-first）：在新增/修改功能前，先更新 `spec/` 下的规范。
|
||
2. 再实现：实现必须与规范一致。
|
||
3. 再验证：CI/本地脚本必须包含规范校验步骤。
|
||
4. 再文档化：README 中必须说明如何查看/使用规范与如何运行校验。
|
||
|
||
3.3 规范校验与联动（强制）
|
||
|
||
- 必须提供脚本（示例命名，可按项目调整但不可缺失）：
|
||
- npm run spec:lint：调用 OpenSpec 对 spec/ 做 lint（具体 CLI 参数以 openspec --help 为准）
|
||
- npm run spec:validate：调用 OpenSpec 对 spec/ 做结构/引用/契约校验（具体 CLI 参数以 openspec --help 为准）
|
||
- 若为 API：
|
||
- 必须在实现层提供请求/响应校验或至少在测试阶段进行契约校验。
|
||
- 鼓励（非强制）从 OpenAPI 生成 client/server stub 或生成类型定义，但不得改变“JS 为主语言”的前提。
|
||
4. 工程结构约束（建议默认）
|
||
|
||
AI 创建项目时，默认使用以下结构；如项目类型不适用，可在不违背约束的前提下做最小调整。
|
||
|
||
- spec/：OpenSpec 规范（OpenAPI 或其他规格说明）
|
||
- src/：源代码
|
||
- tests/：测试
|
||
- scripts/：工程脚本（构建/校验/生成等）
|
||
- README.md：必须包含运行、测试、规范使用方式
|
||
5. 质量与交付约束（强制）
|
||
|
||
- 必须提供基础脚本：
|
||
- npm run dev（如可交互开发）
|
||
- npm run build（如需要构建）
|
||
- npm run test
|
||
- npm run lint
|
||
- 变更要求：
|
||
- 修改实现时同步更新 spec/ 与测试。
|
||
- 不得只改实现不改规范；也不得只改规范不改实现。
|
||
6. AI 行为约束（强制）
|
||
|
||
- 若用户需求与本文件冲突：
|
||
- 先指出冲突点，并请求用户确认是否允许偏离约束。
|
||
- 未明确要求时：
|
||
- 不引入与约束无关的“额外页面/功能/组件/花哨配置”。
|
||
- 保持最小可用、可验证、可维护的实现。
|