3.4 KiB
ADDED Requirements
Requirement: 最小必要改动
同一功能或缺陷修复的代码变更 SHALL 仅包含完成任务所必需的修改；不得在同一提交中进行无关重构、大范围格式化或与需求无关的文件挪动。
Scenario: 修复单接口校验
- WHEN 修复某一接口字段校验
- THEN diff SHALL 主要限于该接口、对应 schema 与必要测试，而不包含同模块无关重命名
Requirement: Web 管理端工程约定
web-admin SHALL 遵循 AGENTS.md 中的栈与工具约定：包管理使用 pnpm；格式化以 Prettier（单引号、无分号、2 空格等）为准；ESLint/Stylelint 规则与仓库配置一致；Vue 与 Element Plus 依赖自动导入策略时，新增全局组件 SHALL 遵循既有 unplugin 配置而非随意手写重复导入（除非文件类型要求）。
Scenario: 提交前检查
- WHEN 提交
web-admin源码 - THEN 贡献者 SHALL 在本地或通过 CI 运行与仓库一致的 lint/format 门禁
Requirement: 后端工程约定
backend SHALL 使用 Python 3.9 与既有 FastAPI、SQLAlchemy、Pydantic v2 模式；新增领域逻辑 SHALL 优先落在 app/services/ 与 app/crud/，路由层保持薄；配置 SHALL 通过 pydantic-settings 与 .env 系列文件管理。
Scenario: 新增业务接口
- WHEN 新增一组管理端 API
- THEN 路由 SHALL 放入
app/api/合适模块，schema 放入app/schemas/，数据库访问放入app/crud/或复用基类
Requirement: 数据库脚本与迁移
涉及表结构变更时，维护者 SHALL 在 docs/sql/ 中维护或更新与需求一致的 SQL 说明（全量基线导出为 zkxw.sql；增量变更可补充同目录下其他 .sql），并评估 Alembic/脚本与运行环境的同步（与 AGENTS.md 数据库变更约定一致）。
Scenario: 新增业务表
- WHEN 增加新表或字段
- THEN 仓库 SHALL 包含可复现的 schema 片段或迁移，且与 OpenSpec
database-conventions中的公共字段规则一致
Requirement: 单文件行数上限
前端（web-admin）与后端（backend）的单个源码文件 SHALL 不超过 500 行。当文件因功能增长接近或超过此限制时，SHALL 将其拆分为多个职责单一的小文件（如：前端提取子组件、composable 或工具函数；后端按领域拆分 service、crud 模块或辅助函数）。配置文件、类型声明文件、SQL 脚本与自动生成文件不在此限制范围内。
Scenario: 前端页面文件增长
- WHEN 一个 Vue 组件文件超过 500 行
- THEN SHALL 将弹窗、复杂表格、可复用面板等拆分为独立子组件或 composable 函数，确保主入口文件在 500 行以内
Scenario: 后端模块文件增长
- WHEN 一个 Python 模块文件（api route、service、crud 等）超过 500 行
- THEN SHALL 按领域或功能边界拆分为多个子模块（如
crud/production_task.py→crud/production_task.py+crud/production_task_step.py），确保单个文件在 500 行以内
Requirement: 提交说明可读性
提交信息 SHALL 使用完整句子说明「改了什么、为何」，并符合仓库 Conventional Commits / commitlint 类型约束。
Scenario: merge request
- WHEN 创建合并请求
- THEN 描述 SHALL 使评审者无需阅读聊天历史即可理解动机与风险