189 lines
5.4 KiB
Markdown
189 lines
5.4 KiB
Markdown
# 工程规范
|
||
|
||
**文档版本**: 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): 初始化模板
|