isos/team

Fork 0

Files

arno 34346be862

CI / lint (push) Successful in 6s

Details

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

2026-04-19 21:47:08 +08:00

5.4 KiB

Raw Permalink Blame History

工程规范

文档版本: 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。

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/jj.md。

版本历史:

v1.0.0 (2026-04-19): 初始化模板

5.4 KiB Raw Permalink Blame History Unescape Escape