# OMNIAXS 开发规范（2026 版）

## 0. 文档信息
- 文档名称：OMNIAXS 开发规范（2026 版）
- 文档版本：V1.0
- 文档日期：2026-04-03
- 适用对象：后端、前端、测试开发、代码评审者
- 适用范围：`apps/*`、`libs/*`、`infra/*`、`scripts/*`
- 关联文档：
  - `docs/TECH_DEV_GUIDE_v1.1_zh.md`
  - `docs/EXTERNAL_API_SPEC_v1_zh.md`
  - `docs/openapi-v1.yaml`
  - `docs/SYSTEM_TEST_GUIDE_v1_zh.md`

## 1. 目标与原则
1. 统一代码风格，降低跨团队阅读与维护成本。
2. 通过类型、静态检查、自动化测试提升可维护性与正确性。
3. 保障关键链路（交易、审批、中转、风控）可审计、可回归、可扩展。
4. 采用 2026 基线：类型优先、自动化优先、安全默认开启、可观测默认开启。

## 2. 语言与工具基线
### 2.1 后端（Python）
1. Python 版本：`3.12+`。
2. Web 框架：FastAPI + Pydantic v2。
3. 必备工具：Ruff、Black、Mypy、Pytest。

### 2.2 前端（TypeScript）
1. TypeScript：`5.x`，开启 `strict`。
2. 框架：Next.js + React。
3. 必备工具：ESLint、Prettier、`tsc --noEmit`。

### 2.3 目录放置规范（强制）
1. 服务代码仅放在 `apps/<service>/src`，服务私有测试放在 `apps/<service>/tests`。
2. 跨服务复用能力必须放在 `libs/*`，禁止复制粘贴到多个服务目录。
3. 跨服务测试资产放在 `tests/{contract,integration,e2e,system,performance,chaos}`。
4. 自动化脚本统一放在 `scripts/{dev,ci,ops}`，禁止散落在根目录。
5. 运行时配置（非密钥）放在 `configs/*`，禁止将密钥写入仓库文件。
6. 基础设施代码放在 `infra/{helm,terraform}`，与业务代码解耦。

## 3. 命名规范（强制）
### 3.1 通用命名
1. 目录名：`kebab-case` 或语义分层目录（如 `api-gateway`）。
2. Python 文件名：`snake_case.py`。
3. TypeScript 文件名：组件文件 `PascalCase.tsx`，工具文件 `camelCase.ts` 或 `kebab-case.ts`（团队统一一种）。
4. 环境变量：`UPPER_SNAKE_CASE`。

### 3.2 Python 命名
1. 类名：`PascalCase`，示例：`OrderRouter`。
2. 函数与变量：`snake_case`，示例：`build_order_payload`。
3. 常量：`UPPER_SNAKE_CASE`，示例：`MAX_RETRY_COUNT`。
4. 协议类后缀：`Protocol`，异常类后缀：`Error`。
5. 布尔变量前缀推荐：`is_`、`has_`、`can_`。

### 3.3 API / Schema / DB 命名
1. API 字段统一使用 `snake_case`，与 OpenAPI 一致。
2. 错误码统一使用 `UPPER_SNAKE_CASE`，示例：`ACCESS_NOT_PROVISIONED`。
3. 数据库表名使用复数 `snake_case`，示例：`access_applications`。
4. 数据库列名使用 `snake_case`，禁止混用驼峰。

### 3.4 命名示例
1. 类：`AccessApplicationService`、`RiskPolicyEvaluator`。
2. 函数：`validate_idempotency_key`、`map_upstream_error`。
3. 变量：`tenant_id`、`selected_exchange`、`is_retryable`。
4. 常量：`DEFAULT_PAGE_SIZE`、`MAX_SINGLE_NOTIONAL`。

## 4. 代码结构与长度约束（强制）
### 4.1 长度约束
1. 单文件建议不超过 600 行，硬上限 800 行（超出必须拆分并在 PR 说明原因）。
2. 单类建议不超过 220 行，硬上限 300 行（仅限经评审批准的特殊场景）。
3. 单函数建议不超过 40 行，硬上限 80 行。
4. 单函数参数建议不超过 5 个，超过时必须封装请求对象。

### 4.2 长度统计口径
1. 长度默认按“逻辑行”统计：不含空行与纯注释行。
2. 自动生成代码（如迁移脚本）不纳入硬上限，但必须隔离在独立目录。
3. 超限例外必须在 PR 模板中声明原因、拆分计划与预计完成时间。

### 4.3 复杂度约束
1. 圈复杂度建议 <= 10，硬上限 15。
2. 嵌套层级建议 <= 3 层，超过需重构。
3. 禁止“巨型服务类”承载多领域职责，遵循单一职责。

## 5. 中文注释与文档规范（强制）
### 5.1 中文注释使用规则
1. 业务规则、合规边界、交易路由原因必须用中文注释，确保团队一致理解。
2. 注释写“为什么”，不写“显而易见的做什么”。
3. 一行代码翻译式注释禁止提交。
4. 外部协议关键字可保留英文原词，必要时附中文解释。

### 5.2 Docstring 规则
1. 对外公开函数、类、模块必须有 docstring。
2. docstring 至少包含：用途、参数、返回、异常。
3. 复杂算法必须补充边界条件与失败策略说明。

### 5.3 TODO/FIXME 规则
1. 必须带责任人和截止版本，例如：`TODO(leon, v1.2): ...`。
2. 没有截止版本的 TODO 不允许进入主分支。

## 6. 类型、异常与日志规范
### 6.1 类型规范
1. Python 公共函数必须显式类型标注（参数 + 返回值）。
2. 禁止未约束的 `dict`/`Any` 在跨模块接口直接传递。
3. DTO 必须通过 Pydantic/TypedDict/dataclass 建模。

### 6.2 异常规范
1. 业务异常必须映射到标准错误码，不允许裸 `Exception` 透出。
2. 捕获异常后必须记录 `trace_id` 与上下文，不吞异常。
3. 外部连接器异常必须保留 `upstream_code`。

### 6.3 日志规范
1. 日志最小字段：`timestamp, level, trace_id, tenant_id, endpoint, error_code`。
2. 禁止输出明文密钥、完整身份信息、敏感凭证。
3. 错误日志必须包含可定位信息（请求路径、关键参数摘要、调用阶段）。

## 7. API 与中间件实现规范
1. 写接口必须使用 Header `Idempotency-Key`，禁止自定义重复实现。
2. 鉴权、限流、幂等、审计必须通过统一中间件链处理。
3. 任何接口变更必须先更新 `docs/openapi-v1.yaml`。
4. 与审批/中转相关代码不得绕过状态机和绑定约束。

## 8. 测试与质量门禁（2026）
### 8.1 必须通过
1. 单元测试通过。
2. 集成测试通过。
3. 契约测试通过。
4. 静态检查通过（Ruff/Mypy/ESLint/TS 编译）。

### 8.2 覆盖率目标
1. 核心交易与审批模块：行覆盖率 >= 85%。
2. 其他业务模块：行覆盖率 >= 75%。
3. 关键异常分支必须有测试（幂等冲突、权限不足、连接器不可用等）。

## 9. 代码评审规范
1. PR 必须说明变更动机、方案、风险、回滚方式。
2. 每个 PR 至少 1 名后端 + 1 名 QA 审阅（关键链路建议加架构评审）。
3. 评审重点：正确性、边界条件、可读性、可观测性、安全性、可测试性。
4. 不允许“先合并后补测试”的主干提交策略。

## 10. Git 与提交规范
1. 分支命名：`feature/*`、`fix/*`、`chore/*`、`release/*`。
2. 提交信息建议：`type(scope): summary`，示例：`feat(order): add idempotency conflict handling`。
3. 禁止将格式化、重构、功能改动混在一个不可审阅提交中。

## 11. 禁止项清单（必须遵守）
1. 禁止硬编码密钥、账号、法务名单、Geo-Fencing 国家列表。
2. 禁止绕过统一错误码体系直接返回自由文本错误。
3. 禁止在核心链路中使用无超时的外部调用。
4. 禁止将审批状态写入多个来源导致状态不一致。
5. 禁止提交超长类或超长函数而无拆分说明。

## 12. 快速检查清单（开发自检）
1. 命名是否符合规范（类 PascalCase、函数 snake_case、错误码大写下划线）。
2. 类/函数/文件长度是否超限。
3. 中文注释是否聚焦“原因与规则”，是否避免翻译式注释。
4. 类型标注是否完整，是否避免 `Any` 污染。
5. 是否补齐测试与文档，是否更新 OpenAPI。
6. 日志与错误是否可追踪，是否包含 `trace_id`。

## 13. 规范生效与例外流程
1. 本规范默认对所有新代码生效。
2. 存量代码在改动时按“触点治理”逐步对齐。
3. 超限或例外必须在 PR 中说明，并由负责人批准。
4. 涉及架构基线例外必须提交 ACR。