shanxia2.0/openspec/changes/zkxw-engineering-standards/specs/coding-conventions/spec.md

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: 路由层访问 Pydantic 请求体字段

app/api/** 中从请求体 body: XxxBody 读取字段时，SHALL 使用 app/schemas/** 里定义的 Python 属性名（多为 snake_case），SHALL NOT 使用 JSON camelCase 的 Field(alias=...) 字符串作为 body.xxx（例如 SHALL NOT 写 body.createTimeRange）。传 CRUD 时优先 body.model_dump(exclude_unset=True)。

完整约定、字段对照表与反例 EC-API-001 见 api-conventions §「JSON 字段命名（前后端 camelCase 对齐）」及 §「常见错误案例（API / Pydantic）」。

Scenario: 新增 POST 路由拆解 body 字段

• WHEN 路由需将列表查询参数传入 app/crud/，且 Schema 中 view_mode 的 alias 为 viewMode
• THEN SHALL 写 view_mode=body.view_mode，SHALL NOT 写 view_mode=body.viewMode

Requirement: 默认租户编号 tenant_no（代码层）

本仓库门户默认租户编号 SHALL 为 shanxia2.0，与 OpenSpec database-conventions 中 DDL 默认值一致。

层级	约定
配置	app/core/config.py 中 DEFAULT_TENANT_NO SHALL 为 "shanxia2.0"；本地/部署 .env、.env.example SHALL 提供 DEFAULT_TENANT_NO=shanxia2.0
ORM	app/models/ 中含 tenant_no 的 Column SHALL 使用 default="shanxia2.0"（sys_tenant.tenant_no 除外，其为租户编码主字段）
CRUD / 服务	无登录上下文或需门户默认租户时（如 Web 登录按 user_no 查用户、新建实体未从 JWT 注入租户），SHALL 使用 settings.DEFAULT_TENANT_NO，SHALL NOT 硬编码 zkxw
写入	业务写入 SHALL 将 tenant_no 设为当前用户租户；未显式赋值且由 ORM/服务端默认填充时，SHALL 落库为 shanxia2.0

Scenario: 新增 SQLAlchemy 模型

• WHEN 在 app/models/ 为业务表增加 tenant_no 字段
• THEN 模型 SHALL 声明 default="shanxia2.0"，并与 docs/sql/ 中对应表的 DEFAULT 'shanxia2.0' 一致

Scenario: Web 管理端登录查用户

• WHEN 调用 user_crud.get_by_user_no 等按账号解析用户的入口且未传入 tenant_no
• THEN 查询条件中的租户 SHALL 为 settings.DEFAULT_TENANT_NO（shanxia2.0），与库中 sys_user.tenant_no 一致

Scenario: 代码评审

• WHEN 评审涉及租户隔离或新建表的变更
• THEN SHALL NOT 引入 default="zkxw" 或 DEFAULT_TENANT_NO=zkxw；若发现历史 zkxw 数据，SHALL 通过 docs/sql/ 迁移脚本统一而非在代码中保留旧默认

Requirement: 数据库脚本与迁移

涉及表结构变更时，维护者 SHALL 在 docs/sql/ 中维护或更新与需求一致的 SQL 说明（全量基线导出为 shanxia2.0.sql；增量变更可补充同目录下其他 .sql），并评估 Alembic/脚本与运行环境的同步（与 AGENTS.md 数据库变更约定一致）；含 tenant_no 的表 SHALL 符合 database-conventions 默认租户 shanxia2.0 约定。

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 使评审者无需阅读聊天历史即可理解动机与风险

Requirement: 前端 API 返回值消费约定

web-admin 的 axios 拦截器（src/utils/http/index.ts）已对响应做两层解包：res.data.data → 返回值即为后端 data 字段的内容。因此页面组件中消费 API 函数返回值时，SHALL NOT 再做 { data } 解构或 .data 取值，SHALL 直接从返回值中读取业务字段。

Scenario: 调用列表 API

• GIVEN 后端返回 {"code": 200, "data": {"list": [...], "total": 12}}
• WHEN 页面调用 const result = await fetchXxxList(params)
• THEN result 已经是 {"list": [...], "total": 12}，SHALL 使用 result.list、result.total，SHALL NOT 写 const { data } = await fetchXxxList() 再从 data.list 取值

Scenario: 调用单条 API

• GIVEN 后端返回 {"code": 200, "data": {"smsContent": "..."}}
• WHEN 页面调用 const result = await fetchGenerateSms(id)
• THEN result 已经是 {"smsContent": "..."}，SHALL 使用 result.smsContent，SHALL NOT 写 const { data } = await fetchGenerateSms() 再从 data.smsContent 取值

Scenario: 新增 API 调用前确认返回值层级

• WHEN 编写新的页面消费 API 函数
• THEN 开发者 SHALL 先查看 src/utils/http/index.ts 第 420 行的 return res.data.data as T，确认拦截器已剥离 {code, data} 外层包装，消费端直接拿返回值即可

Requirement: 前后端统一 POST 调用

前端 API 函数 SHALL 统一使用 request.post() 调用后端接口（文件上传下载除外），与后端统一 POST 路由规范保持一致（详见 api-conventions spec「统一 POST 接口」）。

Scenario: 新增 API 接口

• WHEN 后端定义 @router.post("/products/list")
• THEN 前端对应的 fetchProductList SHALL 使用 request.post({ url: '/web/crm/products/list', data: params })

Scenario: 代码评审检查项

• WHEN 评审涉及前后端联调的变更
• THEN 评审者 SHALL 校验前端 request.post() 与后端 @router.post() 一一匹配，SHALL NOT 出现 request.get() / request.put() / request.delete() 调用业务接口

Requirement: 已有系统迁移的蔓延控制

将已有系统（CRM、报销、地磅等）的业务模块迁移到 shanxia2.0 框架时，SHALL 严格遵循以下约束，防止功能蔓延：

1. 仅迁移源系统已有的功能：迁移范围 SHALL 以源系统的实际代码和功能为边界。SHALL NOT 在迁移过程中自行添加源系统不存在的「增强」、「优化」或「扩展」功能。
2. 逐接口对照验证：每个迁移的 API 端点和前端页面 SHALL 与源系统逐一对照，确保功能完整且未超出原范围。
3. 不做功能裁剪也不做功能膨胀：源系统有的功能 SHALL 全部迁移；源系统没有的功能 SHALL NOT 自行添加。如果判断某功能不再需要，SHALL 由用户明确确认排除后记录到变更文档中。
4. 框架适配不等于功能变更：使用 shanxia2.0 的技术栈（FastAPI、Element Plus、Tailwind CSS 4 等）重写是允许的，但业务逻辑和用户交互 SHALL 忠实还原源系统的行为。
5. 用户确认的排除项必须文档化：所有经用户确认排除的功能（如「不需要产品定价」、「不需要复制产品」），SHALL 在对应迭代的设计文档或实施计划中明确标注为「已排除：[功能名] - 原因：[用户确认不需要]」。

Scenario: 迁移 CRM 产品模块

• GIVEN CRM 源系统有产品 CRUD、产品分类、Excel 导入导出，但用户确认不需要产品定价、标签、复制功能
• WHEN 实现 shanxia2.0 的产品管理模块
• THEN SHALL 只实现产品 CRUD、产品分类、Excel 导入导出，SHALL NOT 自行添加定价、标签、复制等功能，排除项 SHALL 记录在设计文档中

Scenario: 迁移过程中发现源系统的隐藏功能

• WHEN 在迁移过程中发现源系统有某个未被初始分析覆盖的功能（如某个批量操作或联动逻辑）
• THEN 开发者 SHALL 将该功能加入迁移清单并实现，SHALL NOT 以「之前没提到」为由跳过

Scenario: 代码评审检查项

• WHEN 评审迁移类代码变更
• THEN 评审者 SHALL 对照源系统功能清单，确认实现的功能既未遗漏也未超出

Requirement: Blob 文件下载（Excel 导出等）

web-admin 调用 responseType: 'blob' 的接口（CRM Excel 导出、导入模板下载等）时，axios 封装（src/utils/http/index.ts）SHALL：

1. 二进制响应：当 Content-Type 为 xlsx/octet-stream 等非 JSON 时，SHALL 跳过 JSON 业务码（code === 200）校验，直接返回 Blob。
2. JSON 错误体：当后端仍返回 application/json（如 openpyxl 未安装、code: 500）时，SHALL 解析 JSON 并走统一错误抛出，SHALL NOT 将错误 JSON 当作文件下载。
3. 返回值层级：request() 在 responseType: 'blob' 时 SHALL 返回 res.data（Blob 本身），SHALL NOT 返回 res.data.data。
4. 错误提示：导出类 API 函数 SHOULD 设置 showErrorMessage: false，由页面 catch 展示「导出失败」，避免与全局 showError 重复。

Scenario: CRM 线索导出成功

• WHEN 前端 exportClue 使用 responseType: 'blob' 且后端返回 xlsx 流
• THEN 拦截器 SHALL 不抛 HttpError，页面 SHALL 能通过 URL.createObjectURL 触发下载

Scenario: CRM 导出后端异常

• WHEN 后端返回 JSON { "code": 500, "message": "..." } 且 HTTP 状态仍为 200
• THEN 前端 SHALL 进入 catch 并提示失败，SHALL NOT 下载损坏的「伪 xlsx」文件