# 工程规范

**文档版本**: 1.0.0
**最后更新**: 2026-04-19
**维护者**: 项目开发团队

---

## 1. 术语表

本节对项目中出现的专业术语和缩写提供说明，按类别分组。

### 1.1 <!-- 术语分类 -->

| 术语 | 全称 | 说明 |
|------|------|------|
| <!-- 术语 --> | <!-- 全称 --> | <!-- 说明 --> |

### 1.2 术语使用规范

<!-- 填写术语区分规则 -->

---

## 2. 编码规范

| 规范项 | 规则 |
|--------|------|
| **Python 版本** | 3.12+ |
| **类型注解** | mypy strict，禁止 `Any` |
| **格式化** | `ruff format`（4 空格缩进，100 字符行宽） |
| **Lint** | `ruff check` |
| **Docstring** | Google 风格，公共 API 必须有 |
| **命名** | PascalCase 类/类型/异常，snake_case 函数/变量/模块，UPPER_SNAKE_CASE 常量 |
| **字符串** | 用户可见用双引号，代码内部用单引号 |
| **测试覆盖率** | 核心模块 >90%，其他模块 >75% |
| **迁移版本追踪** | 使用 `PRAGMA user_version`，禁止自建版本表 |
| **迁移文件命名** | `{NNNN}_{snake_case}.sql`，4 位零填充序号 |

---

## 3. 项目目录结构

```
apps/
├── server/                         # 服务端模块
│   ├── src/<module_server>/
│   │   ├── main.py                 # FastAPI 入口
│   │   ├── api/                    # API 层
│   │   ├── models/                 # 数据模型
│   │   ├── services/               # 业务逻辑
│   │   ├── db/                     # 数据库管理
│   │   └── config/                 # 配置管理
│   ├── tests/
│   └── pyproject.toml
│
├── desktop/                        # 桌面端模块
│   ├── src/<module_desktop>/
│   │   ├── main.py                 # 入口
│   │   ├── api/                    # 本地 API
│   │   ├── services/               # 业务逻辑
│   │   ├── models/                 # 数据模型
│   │   └── db/                     # 数据库管理
│   ├── frontend/                   # 前端（独立构建系统）
│   ├── tests/
│   └── pyproject.toml
│
docs/                               # 项目文档
scripts/                            # 构建脚本
specs/                              # 功能规格
```

---

## 4. API 设计规范

### 4.1 RESTful 设计原则

| 规范项 | 规则 |
|--------|------|
| **基础路径** | `/api/v1`（版本化前缀） |
| **资源命名** | 复数名词、kebab-case |
| **HTTP 方法** | GET 查询、POST 创建、PUT 全量更新、PATCH 部分更新、DELETE 删除 |
| **协议** | 所有接口强制 HTTPS |
| **字符编码** | UTF-8 |
| **时间格式** | ISO 8601 |
| **分页参数** | `?page=1&per_page=50`（默认 50，最大 200） |

### 4.2 响应格式

**成功响应**：`{ "data": {...}, "meta": { "request_id": "..." } }`

**错误响应**：`{ "error": { "code": "ERROR_CODE", "message": "用户可读描述" }, "meta": { "request_id": "..." } }`

> 详细 API 定义见 [`09-API契约.md`](./09-API契约.md)。

---

## 5. 前端开发规范

### 5.1 组件设计原则

- **单职责**：每个组件只做一件事
- **组合优于继承**：使用组件嵌套和 slot 机制
- **状态最小化**：只存储无法从其他状态派生的数据
- **受控组件**：状态提升到共同父组件

---

## 6. 日志规范

### 6.1 日志级别

| 级别 | 使用场景 |
|------|----------|
| **ERROR** | 操作失败、异常捕获、数据完整性问题 |
| **WARN** | 接近阈值、非致命异常 |
| **INFO** | 操作成功记录 |
| **DEBUG** | 开发调试信息，生产环境默认关闭 |

### 6.2 日志内容规范

| 规范项 | 规则 |
|--------|------|
| **格式** | JSON 结构化日志 |
| **敏感字段** | 禁止记录敏感数据 |
| **请求追踪** | 每个请求携带 `request_id`（UUID v4） |

---

## 7. 测试规范

### 7.1 测试级别

| 级别 | 范围 | 工具 |
|------|------|------|
| **单元测试** | 单个函数/类/方法 | pytest |
| **功能测试** | 单个功能需求（FR） | pytest + httpx |
| **集成测试** | 跨模块交互 | pytest + FastAPI TestClient |
| **端到端测试** | 完整用户流程 | Playwright |
| **验收测试** | 验收标准（SC）验证 | 手动 + 自动化混合 |

### 7.2 覆盖率要求

| 模块 | 最低覆盖率 | 说明 |
|------|-----------|------|
| 核心模块 | >90% | <!-- 说明 --> |
| 重要模块 | >85% | <!-- 说明 --> |
| 其他模块 | >75% | <!-- 说明 --> |

---

## 8. 配置管理规范

### 8.1 配置层次

| 层次 | 来源 | 优先级 |
|------|------|--------|
| 默认值 | 代码内置常量 | 最低 |
| 配置文件 | YAML/TOML 文件 | 中 |
| 环境变量 | `APP_*` 前缀 | 最高 |

---

## 9. 版本控制规范

### 9.1 分支策略

| 规范项 | 规则 |
|--------|------|
| **主分支** | `trunk` |
| **策略** | Trunk-Based Development |
| **工具** | Jujutsu (jj)，并存模式 |

### 9.2 提交规范

| 规范项 | 规则 |
|--------|------|
| **格式** | `<类型>(<作用域>): <描述>` |
| **类型** | 使用中文：功能、修复、维护、文档、重构、测试、格式、性能、构建、安全、依赖、清理、配置、规格、合并 |
| **PR 约束** | 每个 PR 只改动一个模块，标题格式 `[模块] 描述` |

> 详细规范见 [`team/git.md`](../team/git.md) 和 [`team/jj.md`](../team/jj.md)。

---

**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板