配置: 初始化 ISOS Agent Teams 软件研发模板

2026-04-19 21:47:08 +08:00
parent 3ab6fe6504
commit 34346be862
202 changed files with 23544 additions and 0 deletions
@@ -0,0 +1,188 @@
+# 工程规范
+
+**文档版本**: 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): 初始化模板