isos/team
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

配置: 初始化 ISOS Agent Teams 软件研发模板
CI / lint (push) Successful in 6s
Details

Browse Source
This commit is contained in:
arno
2026-04-19 21:47:08 +08:00
parent 3ab6fe6504
commit 34346be862
202 changed files with 23544 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/01-用户需求.md
+68
View File
@@ -0,0 +1,68 @@
# 用户需求
**文档版本**: 1.0.0
**最后更新**: 2026-04-19
**维护者**: 项目开发团队
---
## 1. 项目简介
**项目名称**: ISOS
**部署环境**: <!-- 填写实际部署环境 -->
ISOS 是一个 <!-- 填写项目描述 -->。
## 2. 核心特性
| 特性 | 说明 |
|------|------|
| <!-- 特性1 --> | <!-- 说明 --> |
| <!-- 特性2 --> | <!-- 说明 --> |
| <!-- 特性3 --> | <!-- 说明 --> |
## 3. 项目目标
<!-- 填写项目目标列表 -->
- **目标1**: <!-- 描述 -->
- **目标2**: <!-- 描述 -->
- **目标3**: <!-- 描述 -->
## 4. 角色定义
### 4.1 用户
<!-- 填写用户角色描述 -->
### 4.2 系统管理员
<!-- 填写管理员角色描述 -->
## 5. 用户假设
1. <!-- 假设1 -->
2. <!-- 假设2 -->
3. <!-- 假设3 -->
## 6. 验收标准
### 6.1 可衡量的结果
| ID | 验收标准 | 目标值 |
|----|----------|--------|
| SC-001 | <!-- 验收标准描述 --> | <!-- 目标值 --> |
| SC-002 | <!-- 验收标准描述 --> | <!-- 目标值 --> |
| SC-003 | <!-- 验收标准描述 --> | <!-- 目标值 --> |
### 6.2 安全标准
| ID | 安全标准 | 验证方式 |
|----|----------|----------|
| SC-016 | <!-- 安全标准描述 --> | <!-- 验证方式 --> |
| SC-017 | <!-- 安全标准描述 --> | <!-- 验证方式 --> |
---
**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板
docs/02-产品需求.md
+96
View File
@@ -0,0 +1,96 @@
# 产品需求
**文档版本**: 1.0.0
**最后更新**: 2026-04-19
**维护者**: 项目开发团队
---
## 1. 核心概念
<!-- 填写项目的核心概念和术语定义 -->
## 2. 非功能性需求
### 2.1 安全性
**NFR-1: 安全标准**
- <!-- 安全需求描述 -->
**NFR-2: 访问控制**
- <!-- 访问控制需求描述 -->
### 2.2 性能
**NFR-4: 响应时间**
- <!-- 性能需求描述 -->
**NFR-5: 数据容量**
- <!-- 容量需求描述 -->
### 2.3 可用性
**NFR-6: 可用性要求**
- <!-- 可用性需求描述 -->
**NFR-7: 数据一致性**
- <!-- 一致性需求描述 -->
### 2.4 兼容性
**NFR-8: 平台支持**
- <!-- 兼容性需求描述 -->
### 2.5 可维护性
**NFR-9: 代码质量**
- 遵循严格的代码规范
- 使用强类型语言开发
- 测试覆盖率：核心模块 >90%，其他模块 >75%
**NFR-10: 日志记录**
- 结构化日志格式
- 日志级别：DEBUG、INFO、WARNING、ERROR
- 日志文件按日期滚动
**NFR-11: 构建和部署**
- 提供一键构建脚本
- 构建过程可重复
- 输出清晰的构建信息
- 构建产物可独立运行
## 3. 约束
### 3.1 技术约束
1. <!-- 约束1 -->
2. <!-- 约束2 -->
3. <!-- 约束3 -->
### 3.2 架构约束
1. 模块完全独立，禁止跨模块引用代码
2. 模块间仅通过 REST API 通信
3. 每个 PR 只能改动一个模块
## 4. 依赖
1. <!-- 依赖1 -->
2. <!-- 依赖2 -->
## 5. 风险
1. <!-- 风险1 -->
2. <!-- 风险2 -->
3. <!-- 风险3 -->
## 6. 边缘情况处理
1. <!-- 边缘情况1 -->
2. <!-- 边缘情况2 -->
3. <!-- 边缘情况3 -->
---
**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板
docs/03-功能列表.md
+58
View File
@@ -0,0 +1,58 @@
# 功能列表
**文档版本**: 1.0.0
**最后更新**: 2026-04-19
**维护者**: 项目开发团队
---
## 1. 优先级定义
| 优先级 | 说明 | 包含功能 |
|--------|------|----------|
| **P1** | 核心功能，MVP 必须包含 | <!-- 填写 P1 功能范围 --> |
| **P2** | 重要功能，MVP 后第一版迭代 | <!-- 填写 P2 功能范围 --> |
| **P3** | 增强功能，后续版本 | <!-- 填写 P3 功能范围 --> |
---
## 2. P1 核心功能
### 2.1 <!-- 功能模块名称 -->
**功能需求**:
- **FR-001**: <!-- 功能描述 -->
- **FR-002**: <!-- 功能描述 -->
- **FR-003**: <!-- 功能描述 -->
### 2.2 <!-- 功能模块名称 -->
**功能需求**:
- **FR-010**: <!-- 功能描述 -->
- **FR-011**: <!-- 功能描述 -->
- **FR-012**: <!-- 功能描述 -->
---
## 3. P2 重要功能
### 3.1 <!-- 功能模块名称 -->
**功能需求**:
- **FR-020**: <!-- 功能描述 -->
- **FR-021**: <!-- 功能描述 -->
---
## 4. P3 增强功能
### 4.1 <!-- 功能模块名称 -->
**功能需求**:
- **FR-030**: <!-- 功能描述 -->
- **FR-031**: <!-- 功能描述 -->
---
**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板
docs/04-用户故事.md
+123
View File
@@ -0,0 +1,123 @@
# 用户故事
**文档版本**: 1.0.0
**最后更新**: 2026-04-19
**维护者**: 项目开发团队
---
## 1. 用户故事编号映射
为便于任务管理和开发追踪，功能需求按功能域组织为以下用户故事：
| 用户故事 | 描述 | 功能需求范围 | 优先级 | 负责模块 |
|---------|------|-------------|--------|----------|
| **US1** | <!-- 描述 --> | FR-001~FR-003 | P1 | <!-- 模块 --> |
| **US2** | <!-- 描述 --> | FR-010~FR-012 | P1 | <!-- 模块 --> |
| **US3** | <!-- 描述 --> | FR-020~FR-021 | P2 | <!-- 模块 --> |
---
## 2. P1 核心功能用户故事
### US1: <!-- 用户故事标题 -->
**作为** <!-- 角色 -->，
**我希望** <!-- 功能描述 -->，
**以便** <!-- 价值描述 -->。
**优先级**: P1 | **负责模块**: <!-- 模块名 -->
#### 功能需求
| FR 编号 | 功能描述 |
|---------|---------|
| FR-001 | <!-- 描述 --> |
| FR-002 | <!-- 描述 --> |
| FR-003 | <!-- 描述 --> |
#### 验收标准
| 验收标准 | 关联 SC/NFR |
|---------|-------------|
| <!-- 验收标准 --> | <!-- 关联 --> |
#### 前置条件
- <!-- 前置条件 -->
#### 关联需求
- **SC**: <!-- 关联验收标准 -->
- **NFR**: <!-- 关联非功能需求 -->
---
### US2: <!-- 用户故事标题 -->
**作为** <!-- 角色 -->，
**我希望** <!-- 功能描述 -->，
**以便** <!-- 价值描述 -->。
**优先级**: P1 | **负责模块**: <!-- 模块名 -->
#### 功能需求
| FR 编号 | 功能描述 |
|---------|---------|
| FR-010 | <!-- 描述 --> |
#### 验收标准
| 验收标准 | 关联 SC/NFR |
|---------|-------------|
| <!-- 验收标准 --> | <!-- 关联 --> |
#### 前置条件
- <!-- 前置条件 -->
#### 关联需求
- **SC**: <!-- 关联验收标准 -->
---
## 3. P2 重要功能用户故事
<!-- 按 US1 格式填写 P2 用户故事 -->
---
## 4. P3 增强功能用户故事
<!-- 按 US1 格式填写 P3 用户故事 -->
---
## 5. 追溯矩阵
### 5.1 FR -> US 反向映射
| FR 编号 | 所属 US |
|---------|---------|
| FR-001 ~ FR-003 | US1 |
| FR-010 ~ FR-012 | US2 |
| FR-020 ~ FR-021 | US3 |
### 5.2 SC -> US 映射
| SC 编号 | 验收标准 | 关联 US |
|---------|---------|---------|
| SC-001 | <!-- 描述 --> | US1 |
### 5.3 NFR -> US 映射
| NFR 编号 | 非功能需求 | 关联 US |
|----------|---------|---------|
| NFR-1 | <!-- 描述 --> | US1 |
---
**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板
docs/05-设计-UI.md
+120
View File
@@ -0,0 +1,120 @@
# UI 设计文档
**文档版本**: 1.0.0
**最后更新**: 2026-04-19
**设计系统**: Apple 风格（详见 `./设计-Apple风格.md`）
---
## 模块索引
> 本文档为 UI 设计主索引，各模块详细设计已拆分为独立文件。
| 模块 | 文件 | 界面 | 行数 |
|------|------|------|------|
| <!-- 模块1 --> | [设计-UI-<!-- 子文件名 -->.md](./设计-UI-<!-- 子文件名 -->.md) | <!-- 界面范围 --> | <!-- 行数 --> |
| <!-- 模块2 --> | [设计-UI-<!-- 子文件名 -->.md](./设计-UI-<!-- 子文件名 -->.md) | <!-- 界面范围 --> | <!-- 行数 --> |
### 界面索引
| 界面 | 名称 | 所属模块 | 路径 |
|------|------|----------|------|
| <!-- N --> | <!-- 名称 --> | [<!-- 模块 -->](./设计-UI-<!-- 子文件名 -->.md) | `<!-- 路径 -->` |
### 开发加载指引
| 开发场景 | 加载文件 |
|----------|----------|
| <!-- 场景1 --> | `05-设计-UI.md`（设计系统摘要）+ `设计-UI-<!-- 子文件名 -->.md` |
| <!-- 场景2 --> | `05-设计-UI.md`（设计系统摘要）+ `设计-UI-<!-- 子文件名 -->.md` |
---
## 设计系统摘要
> 以下为各模块共用的设计令牌摘要，完整设计系统见 `./设计-Apple风格.md`。
### 色彩规范
| 用途 | 色值 | 参考 |
|------|------|------|
| 纯黑背景 | `#000000` | 设计-Apple风格.md §2 |
| 浅灰背景 | `#f5f5f7` | 设计-Apple风格.md §2 |
| 主要文字（浅色背景） | `#1d1d1f` | 设计-Apple风格.md §2 |
| 次要文字 | `rgba(0,0,0,0.8)` | 设计-Apple风格.md §2 |
| 交互色（Apple 蓝） | `#0071e3` | 设计-Apple风格.md §2 |
| 链接色（浅色背景） | `#0066cc` | 设计-Apple风格.md §2 |
| 链接色（深色背景） | `#2997ff` | 设计-Apple风格.md §2 |
| 错误色 | `#ff3b30` | Apple 系统色 |
| 警告色 | `#ff9500` | Apple 系统色 |
| 成功色 | `#34c759` | Apple 系统色 |
### 排版规范
| 角色 | 字体 | 字号 | 字重 | 行高 | 字间距 |
|------|------|------|------|------|--------|
| 展示级标题 | Inter Display | 56px | 600 | 1.07 | -0.28px |
| 区块标题 | Inter Display | 40px | 600 | 1.10 | normal |
| 卡片标题 | Inter Display | 28px | 400 | 1.14 | 0.196px |
| 正文 | Inter | 17px | 400 | 1.47 | -0.374px |
| 按钮 | Inter | 17px | 400 | 2.41 | normal |
| 说明文字 | Inter | 14px | 400 | 1.29 | -0.224px |
### 组件规范
| 组件 | 规范 |
|------|------|
| 主 CTA 按钮 | 8px 圆角，`#0071e3` 背景，内边距 8px 15px |
| 胶囊链接 | 980px 圆角，透明背景，描边 |
| 输入框 | 11px 圆角，`#fafafc` 背景 |
| 卡片阴影 | `rgba(0,0,0,0.22) 3px 5px 30px` |
| 导航栏 | `rgba(0,0,0,0.8)` + `backdrop-filter: saturate(180%) blur(20px)` |
### 间距体系
- 基准单位：8px
- 页面边距：24px
- 卡片间距：16px
- 元素间距：8px
---
## 附录
### 尺寸规范汇总
| 组件/元素 | 尺寸 |
|-----------|------|
| 最小窗口宽度 | 800px |
| 侧边栏宽度 | 240px |
| 状态栏高度 | 32px |
| 导航栏高度 | 48px |
| 对话框宽度 | 400px |
| 按钮高度 | 36px |
| 输入框高度 | 36px |
| 基准间距 | 8px |
### 图标规范
| 位置 | 尺寸 |
|------|------|
| Logo | 64px |
| 卡片图标 | 24px |
| 按钮图标 | 16px |
| 状态图标 | 12px |
| 导航图标 | 20px |
### 动画规范
| 动画 | 时长 | 缓动 |
|------|------|------|
| 页面切换 | 300ms | ease-in-out |
| 对话框 | 250ms | ease-out |
| Toast | 300ms | ease-in-out |
| 加载旋转 | 1s | linear |
| 进度条 | 实时 | linear |
---
**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板
docs/06-设计-UX.md
+85
View File
@@ -0,0 +1,85 @@
# 用户体验设计文档
**文档版本**: 1.0.0
**最后更新**: 2026-04-19
---
## 模块索引
> 本文档为 UX 设计主索引，各模块详细设计已拆分为独立文件。
| 模块 | 文件 | 章节 | 行数 |
|------|------|------|------|
| 用户旅程 | [设计-UX-用户旅程.md](./设计-UX-用户旅程.md) | §2 核心用户旅程 | <!-- 行数 --> |
| 交互模式 | [设计-UX-交互模式.md](./设计-UX-交互模式.md) | §3 交互模式说明 | <!-- 行数 --> |
| 操作流程 | [设计-UX-操作流程.md](./设计-UX-操作流程.md) | §4 操作流程图 | <!-- 行数 --> |
| 错误处理 | [设计-UX-错误处理.md](./设计-UX-错误处理.md) | §5 错误处理与反馈 | <!-- 行数 --> |
| 无障碍与响应式 | [设计-UX-无障碍与响应式.md](./设计-UX-无障碍与响应式.md) | §7 无障碍设计 + §8 响应式行为 | <!-- 行数 --> |
### 章节索引
| 章节 | 名称 | 所属模块 | 页内章节 |
|------|------|----------|----------|
| <!-- §N.N --> | <!-- 名称 --> | [<!-- 模块 -->](./设计-UX-<!-- 子文件名 -->.md) | — |
### 开发加载指引
| 开发场景 | 加载文件 |
|----------|----------|
| <!-- 场景1 --> | `06-设计-UX.md` + `设计-UX-<!-- 子文件名 -->.md` |
| <!-- 场景2 --> | `06-设计-UX.md` + `设计-UX-<!-- 子文件名 -->.md` |
---
## 1. 用户角色定义
### 1.1 <!-- 角色名称 -->
**职责**：
- <!-- 职责1 -->
- <!-- 职责2 -->
**使用场景**：
- <!-- 场景1 -->
- <!-- 场景2 -->
---
## 6. 快捷键
### 6.1 全局快捷键
| 快捷键 | 功能 | 说明 |
|--------|------|------|
| <!-- 快捷键 --> | <!-- 功能 --> | <!-- 说明 --> |
### 6.2 <!-- 场景 -->快捷键
| 快捷键 | 功能 | 说明 |
|--------|------|------|
| <!-- 快捷键 --> | <!-- 功能 --> | <!-- 说明 --> |
---
## 附录：设计原则
### A.1 设计哲学
1. **克制的戏剧性**：大面积留白突出内容
2. **产品即主角**：核心数据是主角，UI 退居无形
3. **精准与自信**：紧凑的行高、负字间距传达精密感
4. **二元明暗节奏**：浅灰/深色区块交替营造节奏感
### A.2 交互设计原则
1. **即时反馈**：每个操作都有明确的视觉或触觉反馈
2. **可逆操作**：大多数操作可以撤销
3. **渐进披露**：复杂功能分步展示，避免一次性呈现
4. **智能默认**：提供合理的默认值，减少用户决策
5. **优雅降级**：错误处理保证核心功能可用
---
**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板
docs/07-系统架构.md
+123
View File
@@ -0,0 +1,123 @@
# 系统架构
**文档版本**: 1.0.0
**最后更新**: 2026-04-19
**维护者**: 项目开发团队
---
## 1. 系统架构图
```mermaid
flowchart TB
subgraph Client["客户端"]
direction TB
C_UI["UI 渲染层"]
C_Svc["Service 层"]
C_Data["Data 层 (SQLite + FS)"]
C_UI -->|"HTTPS (localhost)"| C_Svc
C_Svc --> C_Data
end
subgraph Server["服务端 (Docker)"]
direction TB
S_API["REST API 层"]
S_Biz["业务逻辑层"]
S_Data["Data 层 (SQLite)"]
S_API --> S_Biz
S_Biz --> S_Data
end
Client -->|"HTTPS"| Server
```
**架构说明**：
- 客户端采用三层分离架构（UI 渲染层、Service 层、Data 层）
- 客户端与服务端之间通过 HTTPS 进行通信
- 服务端运行在 Docker 容器中，提供 REST API
---
## 2. 技术架构摘要
### 2.1 客户端架构
| 层次 | 职责 | 技术栈 | 通信方式 |
|------|------|--------|----------|
| **UI 渲染层** | 用户界面、交互逻辑、状态管理 | <!-- 填写 --> | HTTPS 调用 Service 层 |
| **Service 层** | 业务逻辑、数据处理 | <!-- 填写 --> | 读写 Data 层 |
| **Data 层** | 本地存储 | SQLite、文件系统 | -- |
### 2.2 服务端架构
| 层次 | 职责 |
|------|------|
| **REST API 层** | 请求路由、认证授权 |
| **业务逻辑层** | <!-- 填写 --> |
| **Data 层** | SQLite 存储 |
---
## 3. 数据流
### 3.1 数据流图
```mermaid
flowchart TB
subgraph 数据操作
A1["UI: 用户输入"] -->|"HTTPS"| A2["Service: 处理数据"]
A2 --> A3["SQLite: 存储数据"]
end
```
### 3.2 数据流规范
| 流程 | 数据流 | 说明 |
|------|--------|------|
| <!-- 操作1 --> | <!-- 数据流 --> | <!-- 说明 --> |
| <!-- 操作2 --> | <!-- 数据流 --> | <!-- 说明 --> |
---
## 4. 部署架构
```mermaid
flowchart TB
subgraph Server["服务器"]
Docker["Docker Engine"]
Container["应用容器"]
Docker --> Container
end
subgraph Client["客户端"]
App["客户端应用"]
LocalDB["本地数据库"]
App --> LocalDB
end
Client -->|"HTTPS"| Server
```
### 4.1 部署约束
| 组件 | 平台 | 容器化 |
|------|------|--------|
| 服务端 | <!-- 填写 --> | Docker 容器 |
| 客户端 | <!-- 填写 --> | 原生应用 |
| 数据库 | SQLite 3.45+ | 嵌入式 |
---
## 5. 模块划分
| 模块 | 职责 | 技术栈 |
|------|------|--------|
| <!-- 模块1 --> | <!-- 职责 --> | <!-- 技术 --> |
| <!-- 模块2 --> | <!-- 职责 --> | <!-- 技术 --> |
**模块独立性**：各模块完全独立开发，不共享代码包，仅通过 REST API 通信。
---
**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板
docs/08-数据库设计.md
+116
View File
@@ -0,0 +1,116 @@
# 数据库设计
**文档版本**: 1.0.0
**最后更新**: 2026-04-19
**维护者**: 项目开发团队
---
## 1. 概述
项目采用**模块化数据库架构**：各模块各自维护独立的 SQLite 数据库，通过 REST API 通信，禁止跨模块直接访问。
### 1.1 设计原则
| 原则 | 说明 |
|------|------|
| **模块独立性** | 各模块数据库完全隔离，仅通过 API 交换数据 |
| **数据安全** | 敏感数据加密存储 |
| **可迁移性** | Schema 版本化管理，支持渐进式迁移 |
---
## 2. 服务端数据库
### 2.1 ER 图
```mermaid
erDiagram
%% 服务端核心实体关系图
%% EntityA ||--o{ EntityB : "关系描述"
%%
%% EntityA {
%% text id PK "主键说明"
%% text field1 "字段说明"
%% }
```
### 2.2 表结构详细定义
<!-- 按以下模板为每个表编写定义 -->
#### <!-- 表名 -->（<!-- 表说明 -->）
| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| `id` | TEXT | PK | UUID v4 |
| <!-- 字段 --> | <!-- 类型 --> | <!-- 约束 --> | <!-- 说明 --> |
### 2.3 索引设计
| 表名 | 索引名 | 字段 | 类型 |
|------|--------|------|------|
| <!-- 表 --> | <!-- 索引 --> | <!-- 字段 --> | <!-- 类型 --> |
### 2.4 SQLite DDL 参考
```sql
-- 按以下模板编写建表语句
-- CREATE TABLE TableName (
-- id TEXT PRIMARY KEY,
-- ...
-- );
```
---
## 3. 客户端本地数据库
### 3.1 ER 图
```mermaid
erDiagram
%% 客户端核心实体关系图
```
### 3.2 表结构详细定义
<!-- 按服务端模板格式填写 -->
---
## 4. 数据版本迁移策略
### 4.1 Schema 版本管理
数据库 Schema 使用 **user_version** pragma 进行版本管理：
```sql
-- 获取当前版本
PRAGMA user_version;
-- 设置版本号（迁移后执行）
PRAGMA user_version = 1;
```
### 4.2 迁移脚本规范
迁移脚本位于各模块的 `db/migrations/` 目录，按 4 位零填充序号命名。
### 4.3 迁移执行流程
1. 应用启动时检查 `user_version`
2. 按 `0001`、`0002`... 顺序执行未应用的迁移
3. 每个迁移在事务中执行，失败则回滚
4. 迁移成功后更新 `user_version`
### 4.4 向后兼容策略
- **字段添加**: 使用 `ALTER TABLE ADD COLUMN`（带 DEFAULT 值）
- **字段删除**: 标记为废弃，保留至少一个大版本
- **表结构变更**: 创建新表，数据迁移后删除旧表
---
**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板
docs/09-API契约.md
+142
View File
@@ -0,0 +1,142 @@
# API 契约
**文档版本**: 1.0.0
**最后更新**: 2026-04-19
---
## 1. 通用规范
| 规范项 | 规则 |
|--------|------|
| **基础路径** | `/api/v1` |
| **协议** | HTTPS（所有接口强制 HTTPS） |
| **时间格式** | ISO 8601（示例：`2026-04-15T14:30:00Z`） |
| **字符编码** | UTF-8 |
| **分页参数** | `?page=1&per_page=50`（默认 50，最大 200） |
### 1.1 认证方式
| 接口类别 | 认证方式 | 说明 |
|----------|----------|------|
| <!-- 类别1 --> | <!-- 方式 --> | <!-- 说明 --> |
| <!-- 类别2 --> | <!-- 方式 --> | <!-- 说明 --> |
---
## 2. 通用响应格式
### 2.1 成功响应
```json
{
"data": {
"key": "value"
},
"meta": {
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}
```
### 2.2 错误响应
```json
{
"error": {
"code": "ERROR_CODE",
"message": "用户可读的错误描述"
},
"meta": {
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}
```
### 2.3 分页响应
```json
{
"data": [],
"meta": {
"total": 100,
"page": 1,
"per_page": 50,
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}
```
---
## 3. HTTP 状态码
| 状态码 | 场景 |
|--------|------|
| 200 | 成功 |
| 201 | 创建成功 |
| 204 | 删除成功（无响应体） |
| 400 | 请求参数错误 |
| 401 | 未认证 |
| 403 | 未授权 |
| 404 | 资源不存在 |
| 409 | 冲突 |
| 429 | 请求过于频繁 |
| 500 | 服务端内部错误 |
---
## 4. 错误码规范
| 范围 | 错误码 | 说明 |
|------|--------|------|
| `AUTH_*` | <!-- 错误码 --> | 认证相关 |
| `VALIDATION_*` | <!-- 错误码 --> | 验证相关 |
| <!-- 范围 --> | <!-- 错误码 --> | <!-- 说明 --> |
---
## 5. 接口定义
<!-- 按以下模板为每个接口编写定义 -->
### 5.1 <!-- HTTP方法 --> <!-- 路径 --> -- <!-- 接口说明 -->
**请求：**
```json
{
"field": "value"
}
```
**响应 <!-- 状态码 -->：**
```json
{
"data": {},
"meta": {
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}
```
**错误响应：**
| 状态码 | 错误码 | 说明 |
|--------|--------|------|
| <!-- 状态码 --> | <!-- 错误码 --> | <!-- 说明 --> |
---
## 6. FR 映射表
| FR 编号 | 功能 | 对应 API 接口 |
|---------|------|---------------|
| FR-001 | <!-- 功能 --> | <!-- 接口 --> |
| FR-002 | <!-- 功能 --> | <!-- 接口 --> |
---
**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板
docs/10-测试-方案.md
+188
View File
@@ -0,0 +1,188 @@
# 测试方案
**文档版本**: 1.0.0
**最后更新**: 2026-04-19
**维护者**: 项目开发团队
---
## 目录
1. [测试策略总览](#1-测试策略总览)
2. [单元测试](#2-单元测试)
3. [功能测试](#3-功能测试)
4. [集成测试](#4-集成测试)
5. [系统测试](#5-系统测试)
6. [接口测试](#6-接口测试)
7. [端到端测试](#7-端到端测试)
8. [验收测试](#8-验收测试)
9. [测试环境](#9-测试环境)
10. [覆盖率要求](#10-覆盖率要求)
---
## 1. 测试策略总览
### 1.1 测试目标
确保系统在功能正确性、安全性、性能、可靠性等方面满足需求规格。
### 1.2 测试原则
| 原则 | 说明 |
|------|------|
| **分层测试** | 按测试金字塔模型，单元测试数量最多、执行最快 |
| **模块独立** | 各模块测试完全独立，跨模块交互通过集成测试覆盖 |
| **可重复性** | 所有测试使用隔离环境，确保可重复执行 |
| **自动化优先** | 所有测试自动化执行 |
### 1.3 测试级别定义
| 级别 | 职责 | 执行频率 | 工具 |
|------|------|----------|------|
| **单元测试** | 验证单个函数/类的行为正确性 | 每次提交 | pytest, pytest-cov |
| **功能测试** | 验证用户操作流程和 UI 交互 | 每次提交 | pytest, Playwright |
| **集成测试** | 验证跨组件、跨模块交互 | 每日/PR | pytest, FastAPI TestClient |
| **系统测试** | 验证部署、性能、安全、兼容性 | 每个迭代 | Docker, wrk |
| **接口测试** | 验证 REST API 契约一致性 | 每次提交 | pytest, httpx |
| **E2E 测试** | 验证完整用户旅程 | 每个迭代 | Playwright |
| **验收测试** | 验证需求验收标准 | 发布前 | 手动 + 自动化 |
### 1.4 覆盖率要求概览
| 模块类别 | 最低覆盖率 | 适用范围 |
|----------|-----------|----------|
| 核心模块 | >90% | <!-- 填写 --> |
| 重要模块 | >85% | <!-- 填写 --> |
| 其他模块 | >75% | <!-- 填写 --> |
---
## 2. 单元测试
### 2.1 测试框架和工具
| 工具 | 用途 | 适用范围 |
|------|------|----------|
| **pytest** | 测试框架 | 全部 |
| **pytest-cov** | 覆盖率报告 | 全部 |
| **pytest-mock** | Mock 和 Patch | 全部 |
| **faker** | 测试数据生成 | 全部 |
| **tmp_path** | 临时文件和目录 | 文件操作 |
### 2.2 测试文件组织
```
apps/<module>/
└── tests/
├── conftest.py # 公共 fixtures
├── unit/ # 单元测试
│ ├── services/ # 业务逻辑层测试
│ └── api/ # API 路由层测试
└── integration/ # 集成测试
```
### 2.3 Mock 策略
| 策略 | 说明 |
|------|------|
| **数据库隔离** | 每个测试用例使用独立的内存 SQLite |
| **文件系统隔离** | 使用 `tmp_path` 创建临时目录 |
| **网络隔离** | Mock 所有外部 HTTP 请求 |
---
## 3. 功能测试
<!-- 按模块填写功能测试策略 -->
---
## 4. 集成测试
### 4.1 测试范围
| 范围 | 说明 | 关联 FR |
|------|------|---------|
| <!-- 范围1 --> | <!-- 说明 --> | <!-- FR --> |
| <!-- 范围2 --> | <!-- 说明 --> | <!-- FR --> |
---
## 5. 系统测试
### 5.1 性能测试策略
| 测试项 | 性能指标 | 目标值 | 验证方式 |
|--------|----------|--------|----------|
| <!-- 测试项 --> | <!-- 指标 --> | <!-- 目标 --> | <!-- 方式 --> |
### 5.2 安全测试策略
| 测试项 | 验证方式 |
|--------|----------|
| <!-- 测试项 --> | <!-- 方式 --> |
---
## 6. 接口测试
<!-- 填写接口测试策略 -->
---
## 7. 端到端测试
### 7.1 核心用户旅程
```
<!-- 填写核心用户旅程步骤 -->
```
---
## 8. 验收测试
### 8.1 验收标准来源
| 来源 | 文档 | 验收标准 |
|------|------|----------|
| **用户需求** | `01-用户需求.md` | SC-001 ~ SC-NNN |
| **用户故事** | `04-用户故事.md` | 用户场景验证 |
---
## 9. 测试环境
| 配置项 | 要求 |
|--------|------|
| **操作系统** | <!-- 填写 --> |
| **Python 版本** | 3.12+ |
| **数据库** | SQLite 3.45+ |
---
## 10. 覆盖率要求
### 10.1 覆盖率标准
| 模块 | 最低覆盖率 | 适用范围 |
|------|-----------|----------|
| 核心模块 | >90% | <!-- 填写 --> |
| 重要模块 | >85% | <!-- 填写 --> |
| 其他模块 | >75% | <!-- 填写 --> |
### 10.2 覆盖率统计方法
```bash
# 生成覆盖率报告
uv run pytest tests/ --cov=src --cov-report=term-missing
# 生成 HTML 覆盖率报告
uv run pytest tests/ --cov=src --cov-report=html
```
---
**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板
docs/11-工程规范.md
+188
View File
@@ -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): 初始化模板
docs/12-管理-项目.md
+208
View File
@@ -0,0 +1,208 @@
# ISOS Agent Teams 软件研发模板 - 项目管理
**文档版本**: 1.0.0
**最后更新**: 2026-04-19
---
## 目录
1. [项目概况](#1-项目概况)
2. [开发里程碑](#2-开发里程碑)
3. [工作流程](#3-工作流程)
4. [协作规范](#4-协作规范)
5. [质量保证](#5-质量保证)
6. [风险管理](#6-风险管理)
---
## 1. 项目概况
### 1.1 项目简介
<!-- 填写项目简介 -->
### 1.2 技术栈
| 组件 | 技术 |
|------|------|
| 语言 | Python 3.12+ / TypeScript（前端） |
| 服务端 | FastAPI + SQLite |
| 桌面端 | PyWebView + Svelte 5 + SQLite |
| 版本控制 | Jujutsu (jj) |
| 容器化 | Docker（服务端） |
### 1.3 核心约束
| 约束 | 说明 |
|------|------|
| 模块独立性 | 各模块完全独立，禁止跨模块代码引用 |
| 通信方式 | 仅通过 REST API |
| PR 约束 | 每个 PR 只改动一个模块 |
---
## 2. 开发里程碑
### 2.1 里程碑概览
| 里程碑 | 优先级 | 核心目标 | 状态 |
|--------|--------|----------|------|
| M1: 基础架构 | P1 | <!-- 目标 --> | 待开发 |
| M2: <!-- 名称 --> | P1 | <!-- 目标 --> | 待开发 |
| M3: <!-- 名称 --> | P1 | <!-- 目标 --> | 待开发 |
| M4: <!-- 名称 --> | P2 | <!-- 目标 --> | 待开发 |
### 2.2 M1: 基础架构
**目标**: 搭建项目基础框架，确立架构模式。
**功能范围**:
- <!-- 功能1 -->
- <!-- 功能2 -->
**验收标准**:
- <!-- 标准1 -->
- <!-- 标准2 -->
---
## 3. 工作流程
### 3.1 版本控制
- 主分支：`trunk`
- 分支策略：Trunk-Based Development
- 版本控制工具：Jujutsu (jj)，并存模式
- 提交规范：使用中文类型（详见 [`team/git.md`](../team/git.md)）
- PR 约束：每个 PR 只改动一个模块，标题格式 `[模块] 描述`
### 3.2 开发流程
功能开发采用 speckit 集成流程：
```
/speckit.specify -> spec.md -> /speckit.plan -> plan.md -> /speckit.tasks -> tasks.md -> /speckit.implement
```
### 3.3 代码审查
#### 审查流程
```
代码完成 -> 自测通过 -> 创建 PR -> Agent 代码审查 -> 修改（如需） -> 合并到 trunk
```
#### 审查清单
| 审查维度 | 检查项 |
|----------|--------|
| **功能正确性** | 是否满足对应 FR 的功能要求 |
| **代码质量** | 类型注解完整、命名规范、无冗余代码 |
| **测试覆盖** | 是否达到对应模块的覆盖率要求 |
| **文档同步** | 相关文档是否已更新 |
| **模块边界** | 是否遵守模块独立性 |
### 3.4 发布流程
#### 发布前检查
| 检查项 | 命令 |
|--------|------|
| 类型检查 | `uv run mypy src/ --strict` |
| 全量测试 | `uv run pytest` |
| 代码格式 | `ruff format --check . && ruff check .` |
| 覆盖率 | 测试覆盖率满足模块要求 |
#### 版本号规则
- **MAJOR**: 所有文档共享，不轻易变更
- **MINOR**: 实质性内容/功能变更
- **PATCH**: 错别字、格式修正、Bug 修复
---
## 4. 协作规范
### 4.1 Agent Team 协作
详见 [`管理-Agent-Team分工及提示词.md`](./管理-Agent-Team分工及提示词.md)
#### Agent 角色分工
| 角色 | Skill | 职责 |
|------|-------|------|
| 需求文档 | <!-- Skill --> | <!-- 职责 --> |
| UI/UX 设计 | <!-- Skill --> | <!-- 职责 --> |
| 系统架构 | <!-- Skill --> | <!-- 职责 --> |
| 项目管理 | <!-- Skill --> | <!-- 职责 --> |
| 前端开发 | <!-- Skill --> | <!-- 职责 --> |
| 后端开发 | <!-- Skill --> | <!-- 职责 --> |
| 测试 | <!-- Skill --> | <!-- 职责 --> |
| 运维 | <!-- Skill --> | <!-- 职责 --> |
### 4.2 文档管理
- docs/ 下所有 `.md` 文件使用中文文件名
- 文档索引维护在 [`README.md`](./README.md)
- 上下文加载指引在 [`CLAUDE.md`](./CLAUDE.md)
- 文档变更需同步更新索引
### 4.3 文档一致性
文档变更后必须执行一致性检查：
| 变更类型 | 需检查的关联文档 |
|----------|-----------------|
| 功能需求变更 | `03-功能列表.md` -> `01-用户需求.md` -> `04-用户故事.md` |
| API 变更 | `09-API契约.md` -> `07-系统架构.md` -> `08-数据库设计.md` |
| 架构变更 | `07-系统架构.md` -> `11-工程规范.md` -> `08-数据库设计.md` |
| 测试变更 | `10-测试-方案.md` -> `测试-用例.md` -> `测试-计划.md` |
| 索引变更 | `README.md` -> `CLAUDE.md` |
---
## 5. 质量保证
### 5.1 测试策略
| 测试级别 | 目标 | 执行时机 |
|----------|------|----------|
| 单元测试 | 函数/类级别正确性 | 每次提交 |
| 功能测试 | 单个 FR 功能验证 | 功能完成后 |
| 集成测试 | 跨模块交互验证 | 里程碑完成后 |
| 端到端测试 | 完整用户流程 | 发布前 |
| 验收测试 | 验收标准（SC）验证 | 发布前 |
### 5.2 自动化检查
| 检查项 | 工具 | 频率 |
|--------|------|------|
| 代码格式 | `ruff format --check` | 每次提交 |
| Lint | `ruff check` | 每次提交 |
| 类型检查 | `mypy --strict` | 每次提交 |
| 单元测试 | `pytest` | 每次提交 |
| 覆盖率 | `pytest --cov` | 功能完成后 |
---
## 6. 风险管理
### 6.1 技术风险
| 风险 | 影响 | 概率 | 缓解措施 |
|------|------|------|----------|
| <!-- 风险 --> | <!-- 影响 --> | <!-- 概率 --> | <!-- 措施 --> |
### 6.2 项目风险
| 风险 | 影响 | 概率 | 缓解措施 |
|------|------|------|----------|
| 功能范围蔓延 | 高 | 中 | 严格按 P1->P2->P3 优先级开发 |
| 模块间耦合 | 高 | 低 | 模块独立性约束；仅通过 REST API 通信 |
| 文档与代码不同步 | 中 | 中 | 文档一致性检查流程 |
---
**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板
docs/13-Mermaid图集.md
+71
View File
@@ -0,0 +1,71 @@
# Mermaid 图集
**文档版本**: 1.0.0
**最后更新**: 2026-04-19
> 本文件汇总 `docs/` 目录下所有 Mermaid 图，按分类索引，便于查阅和去重。
> 本文件中的图**不参与重复性检查** -- 它们是其他文档中图的镜像引用。
---
## 目录
| 分类 | 图数量 | 来源文档 |
|------|--------|----------|
| [1. 系统架构图](#1-系统架构图) | <!-- 数量 --> | `07-系统架构.md` |
| [2. 数据模型图](#2-数据模型图) | <!-- 数量 --> | `08-数据库设计.md` |
| [3. 用户旅程图](#3-用户旅程图) | <!-- 数量 --> | `设计-UX-用户旅程.md` |
| [4. 操作流程图](#4-操作流程图) | <!-- 数量 --> | `设计-UX-操作流程.md` |
**合计**: <!-- 数量 --> 个文件，<!-- 数量 --> 个 Mermaid 图
---
## 1. 系统架构图
> 来源: [`07-系统架构.md`](./07-系统架构.md)
<!-- 按以下格式添加图表 -->
### 1.1 <!-- 图表标题 -->
<!-- SOURCE: 07-系统架构.md §N line XX -->
```mermaid
<!-- 粘贴对应的 Mermaid 图 -->
```
---
## 2. 数据模型图
> 来源: [`08-数据库设计.md`](./08-数据库设计.md)
---
## 3. 用户旅程图
> 来源: [`设计-UX-用户旅程.md`](./设计-UX-用户旅程.md)
---
## 4. 操作流程图
> 来源: [`设计-UX-操作流程.md`](./设计-UX-操作流程.md)
---
## 维护规范
### 同步更新规则
1. 当源文档中的 Mermaid 图发生**创建、更新、删除**时，必须同步更新本文件对应章节
2. 新增 Mermaid 图时，在本文件对应分类末尾追加，编号递增
3. 删除 Mermaid 图时，从本文件移除对应条目，并在分类目录中更新图数量
4. 更新 Mermaid 图时，同时更新本文件中的镜像副本和 `<!-- SOURCE -->` 注释中的行号
5. **本文件中的图不参与重复性检查** -- 它们是其他文档的镜像引用
---
**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板
docs/CLAUDE.md
+43
View File
@@ -0,0 +1,43 @@
# docs/ CLAUDE.md
> 本文件为 Claude Code 提供上下文优化指引，避免每次加载完整文档。
## 文档加载指引
| 场景 | 加载文档 |
|------|----------|
| 了解项目是做什么的 | `01-用户需求.md` |
| 添加/修改功能 | `03-功能列表.md` + `02-产品需求.md` |
| 编写用户故事 | `04-用户故事.md` |
| 架构设计 | `07-系统架构.md` + `08-数据库设计.md` + `09-API契约.md` |
| 安全相关变更 | `02-产品需求.md`（安全性 NFR） |
| 查阅 Mermaid 图 | `13-Mermaid图集.md` |
| UI/前端开发 | `05-设计-UI.md` + `06-设计-UX.md` + 对应模块文件 |
| 术语不理解 | `11-工程规范.md`（术语表） |
| 部署相关 | `运维-部署实施.md` |
| 测试相关 | `10-测试-方案.md` + `测试-用例.md` |
| 发布追踪 | `运维-发布日志.md` |
## 关键约束速查
### 架构
- 模块独立性：各模块完全独立，禁止跨模块引用
- 通信方式：仅通过 REST API
- 数据库：SQLite 3.45+
### 编码规范
- 语言：Python 3.12+ / TypeScript（前端）
- 格式化：ruff format / ruff check
- 类型：mypy strict，禁止 Any
- 详见 `.claude/CLAUDE.md`
## 文件命名规范
docs/ 下所有 `.md` 文件使用**分类前缀**命名：
- 核心文档: `01-` ~ `12-` 编号前缀
- 设计文档: `设计-` 前缀
- 管理文档: `管理-` 前缀
- 运维文档: `运维-` 前缀
- 测试文档: `测试-` 前缀
描述部分使用中文，避免与前缀重复。仅 UI/UX 等通用缩写可保留英文。
docs/README.md
+92
View File
@@ -0,0 +1,92 @@
# ISOS 项目文档
本目录包含 ISOS Agent Teams 软件研发模板的全部项目文档。
---
## 文档索引
### 核心文档
| 文档 | 用途 |
|------|------|
| [`01-用户需求.md`](./01-用户需求.md) | 用户视角需求、项目目标、验收标准 |
| [`02-产品需求.md`](./02-产品需求.md) | 非功能性需求、约束、风险、边缘情况 |
| [`03-功能列表.md`](./03-功能列表.md) | 按优先级组织的功能需求（FR）列表 |
| [`04-用户故事.md`](./04-用户故事.md) | 用户故事（US）集合 |
| [`07-系统架构.md`](./07-系统架构.md) | 系统架构图、技术架构、模块划分 |
| [`08-数据库设计.md`](./08-数据库设计.md) | 关键实体数据模型 |
| [`11-工程规范.md`](./11-工程规范.md) | 术语表、工程规范 |
| [`09-API契约.md`](./09-API契约.md) | API 契约、接口定义 |
| [`13-Mermaid图集.md`](./13-Mermaid图集.md) | 全项目 Mermaid 图汇总索引 |
### 设计文档
| 文档 | 用途 |
|------|------|
| [`设计-Apple风格.md`](./设计-Apple风格.md) | Apple 风格设计系统（色彩、排版、组件规范） |
| [`05-设计-UI.md`](./05-设计-UI.md) | UI 界面设计规范 |
| [`06-设计-UX.md`](./06-设计-UX.md) | UX 用户体验设计、交互模式 |
### 管理文档
| 文档 | 用途 |
|------|------|
| [`12-管理-项目.md`](./12-管理-项目.md) | 项目管理、工作流程、协作规范 |
| [`管理-开发入门.md`](./管理-开发入门.md) | Claude Code 工具链配置与开发入门指引 |
| [`管理-开发环境搭建.md`](./管理-开发环境搭建.md) | 本地开发环境配置、依赖安装 |
| [`管理-Agent-Team分工及提示词.md`](./管理-Agent-Team分工及提示词.md) | Agent Team 分工及提示词 |
### 运维文档
| 文档 | 用途 |
|------|------|
| [`运维-部署实施.md`](./运维-部署实施.md) | 部署实施方案 |
| [`运维-发布日志.md`](./运维-发布日志.md) | 版本变更历史、功能更新记录 |
| [`运维-安全审计.md`](./运维-安全审计.md) | 安全策略、漏洞跟踪 |
| [`运维-故障排除.md`](./运维-故障排除.md) | 常见问题排查、错误码对照、诊断指引 |
| [`运维-性能基准.md`](./运维-性能基准.md) | 性能基准 |
### 测试文档
| 文档 | 用途 |
|------|------|
| [`10-测试-方案.md`](./10-测试-方案.md) | 测试策略（含单元/功能/集成/系统/接口/端到端/验收各级别） |
| [`测试-计划.md`](./测试-计划.md) | 测试计划 |
| [`测试-用例.md`](./测试-用例.md) | 测试用例（按级别组织） |
| [`测试-单元.md`](./测试-单元.md) | 单元测试标准与规范（开发者维护） |
| [`测试-接口.md`](./测试-接口.md) | 接口测试规范 |
| [`测试-接口-分类.md`](./测试-接口-分类.md) | 分类接口测试用例模板 |
| [`测试-报告.md`](./测试-报告.md) | 测试执行报告与缺陷跟踪 |
---
## 阅读指引
**快速了解项目**: 01-用户需求.md -> 07-系统架构.md -> 03-功能列表.md
**开发准备**: 02-产品需求.md -> 09-API契约.md -> 08-数据库设计.md -> 11-工程规范.md -> 管理-开发环境搭建.md
**UI 开发**: 设计-Apple风格.md -> 05-设计-UI.md -> 06-设计-UX.md -> team/svelte.md
**测试编写**: 10-测试-方案.md -> 测试-用例.md -> 01-用户需求.md（验收标准）
**问题排查**: 运维-故障排除.md -> 运维-发布日志.md
---
## 文档命名规范
本目录下所有 `.md` 文件统一使用**中文文件名**，仅 UI/UX 等国际通用缩写可在文件名中保留英文缩写。
**命名规则**：
- **核心文档**: `01-` ~ `12-` 编号前缀
- **设计文档**: `设计-` 前缀
- **管理文档**: `管理-` 前缀
- **运维文档**: `运维-` 前缀
- **测试文档**: `测试-` 前缀
---
**版本历史**:
- v1.0.0 (2026-04-19): 初始化 ISOS Agent Teams 软件研发模板
docs/review/.gitkeep
View File
docs/superpowers/plans/.gitkeep
View File
docs/superpowers/specs/.gitkeep
View File
docs/测试-单元.md
+89
View File
@@ -0,0 +1,89 @@
# 单元测试规范
**文档版本**: 1.0.0
**最后更新**: 2026-04-19
---
## 1. 概述
本文档定义项目各模块的单元测试规范和测试清单，确保代码质量和功能正确性。测试按模块组织，与系统架构中的模块划分一致。
### 1.1 覆盖率目标
| 模块类别 | 覆盖率目标 | 适用范围 |
|----------|-----------|----------|
| <!-- 核心模块 --> | ><!-- % --> | <!-- 范围 --> |
| <!-- 其他模块 --> | ><!-- % --> | <!-- 范围 --> |
### 1.2 测试框架和工具
| 工具 | 用途 |
|------|------|
| **pytest** | 测试框架 |
| **pytest-cov** | 覆盖率报告 |
| **pytest-asyncio** | 异步测试支持 |
| **pytest-mock / unittest.mock** | Mock 和 Patch |
| **faker** | 测试数据生成 |
| **freezegun** | 时间冻结（测试时间相关逻辑） |
### 1.3 测试文件组织结构
```
apps/<!-- 模块 -->/
├── src/<!-- 模块名 -->/
│ ├── services/
│ ├── api/
│ └── ...
└── tests/
├── conftest.py # 公共 fixtures
├── unit/
│ ├── services/
│ │ └── <!-- test_*.py -->
│ └── api/
│ └── <!-- test_*.py -->
└── integration/
└── ...
```
### 1.4 通用 Mock 策略
| 策略 | 说明 |
|------|------|
| **数据库隔离** | 每个测试用例使用独立的内存 SQLite 数据库（`file::memory:`），测试结束自动销毁 |
| **文件系统隔离** | 使用 `tmp_path` fixture 创建临时目录，测试结束自动清理 |
| **网络隔离** | Mock 所有外部 HTTP 请求，禁止真实网络调用 |
| **时间控制** | 使用 `freezegun` 冻结时间，确保时间相关测试可重复 |
---
## 2. 模块测试文档索引
<!-- 按模块拆分为独立文件后在此列出索引 -->
| 文件 | 内容 | 子模块数 | 测试函数数 |
|------|------|----------|------------|
| <!-- 测试文件 --> | <!-- 说明 --> | <!-- 数 --> | <!-- 数 --> |
---
## 3. 测试执行命令
```bash
# 运行所有单元测试
uv run pytest tests/unit/ -v
# 运行指定模块测试
uv run pytest tests/unit/services/<!-- test_module -->.py -v
# 生成覆盖率报告
uv run pytest tests/unit/ --cov=src --cov-report=html
# 仅运行 P1 优先级测试
uv run pytest tests/unit/ -v -k "p1"
```
---
**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板
docs/测试-报告.md
+41
View File
@@ -0,0 +1,41 @@
# 测试报告
**文档版本**: 1.0.0
**最后更新**: 2026-04-19
---
## 目录
1. [报告总览](#1-报告总览)
2. [执行记录](#2-执行记录)
3. [缺陷跟踪](#3-缺陷跟踪)
4. [覆盖率统计](#4-覆盖率统计)
5. [风险评估](#5-风险评估)
---
## 1. 报告总览
> 待编写
## 2. 执行记录
> 待编写
## 3. 缺陷跟踪
> 待编写
## 4. 覆盖率统计
> 待编写
## 5. 风险评估
> 待编写
---
**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板
docs/测试-接口-分类.md
+42
View File
@@ -0,0 +1,42 @@
# <!-- 接口模块 -->测试
**文档版本**: 1.0.0
**最后更新**: 2026-04-19
> 来源: [接口测试规范](./测试-接口.md) §<!-- 章节 -->
---
### <!-- N --> <!-- HTTP方法--> <!-- 路径 --> — <!-- 接口名称 -->
**关联 FR**: <!-- FR编号 -->
**认证方式**: <!-- 认证方式 -->
#### <!-- N -->.1 正向测试
| 用例编号 | 场景 | 请求 | 预期响应 |
|----------|------|------|----------|
| <!-- 编号 --> | <!-- 场景 --> | <!-- 请求 --> | <!-- 预期 --> |
#### <!-- N -->.2 逆向测试
| 用例编号 | 场景 | 请求 | 预期响应 |
|----------|------|------|----------|
| <!-- 编号 --> | <!-- 场景 --> | <!-- 请求 --> | <!-- 预期 --> |
#### <!-- N -->.3 边界测试
| 用例编号 | 场景 | 请求 | 预期响应 |
|----------|------|------|----------|
| <!-- 编号 --> | <!-- 场景 --> | <!-- 请求 --> | <!-- 预期 --> |
#### <!-- N -->.4 安全测试
| 用例编号 | 场景 | 攻击方式 | 预期响应 |
|----------|------|----------|----------|
| <!-- 编号 --> | <!-- 场景 --> | <!-- 方式 --> | <!-- 预期 --> |
---
**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板
docs/测试-接口.md
+92
View File
@@ -0,0 +1,92 @@
# 接口测试规范
**文档版本**: 1.0.0
**最后更新**: 2026-04-19
---
## 1. 概述
本文档定义项目所有 API 接口的测试规范。测试按接口分组组织，与 [09-API契约.md](./09-API契约.md) 章节结构一致。
### 1.1 测试目标
| 目标 | 说明 |
|------|------|
| **契约一致性** | 验证所有接口的请求/响应格式与 API 契约完全一致 |
| **状态码正确性** | 验证每个接口在各种场景下返回正确的 HTTP 状态码 |
| **错误码准确性** | 验证错误响应中的 code 和 message 符合错误码规范 |
| **安全性** | 验证认证机制、权限控制和注入防护 |
| **边界条件** | 验证空值、超长输入、特殊字符等边界场景 |
| **性能基准** | 验证接口响应时间满足非功能性需求 |
### 1.2 测试工具
| 工具 | 用途 | 适用范围 |
|------|------|----------|
| **pytest** | 测试框架 | 全部 |
| **httpx** | HTTP 客户端 | 全部 |
| **faker** | 测试数据生成 | 全部 |
### 1.3 HTTP 状态码速查
| 状态码 | 场景 |
|--------|------|
| 200 | 成功 |
| 201 | 创建成功 |
| 204 | 删除成功（无响应体） |
| 400 | 请求参数错误 |
| 401 | 未认证 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 409 | 冲突 |
| 500 | 服务端内部错误 |
---
## 2. 通用响应格式验证
### 2.1 成功响应结构
**验证点**：
- 响应体必须包含 `data` 和 `meta` 两个顶层字段
- `meta` 必须包含 `request_id`
### 2.2 错误响应结构
**验证点**：
- 响应体必须包含 `error` 和 `meta` 两个顶层字段
- `error` 必须包含 `code` 和 `message`
### 2.3 分页响应结构
**验证点**：
- `meta` 必须包含 `total`、`page`、`per_page`
- `data` 为数组类型
---
## 3. 接口测试文档索引
<!-- 按接口分组拆分为独立文件后在此列出索引 -->
| 文件 | 内容 | 章节来源 |
|------|------|----------|
| [测试-接口-分类.md](./测试-接口-分类.md) | 分类接口测试用例模板 | §3+ |
---
## 4. 测试文件组织结构
```
apps/<!-- 模块 -->/
└── tests/
└── api/
├── conftest.py # API 公共 fixtures
└── <!-- test_*.py --> # 接口测试文件
```
---
**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板
docs/测试-用例.md
+110
View File
@@ -0,0 +1,110 @@
# 测试用例
**文档版本**: 1.0.0
**最后更新**: 2026-04-19
---
## 1. 概述
### 1.1 目的
本文档定义项目的功能测试用例，覆盖所有功能需求，确保系统行为符合需求规格。
### 1.2 编号规则
```
TC-[级别]-[序号]
```
| 级别 | 含义 | 适用场景 |
|------|------|----------|
| **FUN** | 功能测试 | UI 交互、用户操作流程验证 |
| **INT** | 集成测试 | 跨组件、跨模块交互验证 |
| **SYS** | 系统测试 | 部署、运行环境、整体行为验证 |
| **API** | 接口测试 | REST API 请求/响应验证 |
| **E2E** | 端到端测试 | 完整用户旅程验证 |
| **A11Y** | 可访问性测试 | 无障碍、响应式验证 |
### 1.3 优先级
| 优先级 | 说明 |
|--------|------|
| **P1** | 核心路径，必须通过 |
| **P2** | 重要功能，应当通过 |
| **P3** | 增强功能，建议通过 |
### 1.4 测试类型
| 类型 | 说明 |
|------|------|
| **正向** | 验证功能正常工作的预期行为 |
| **反向** | 验证异常输入或非法操作的错误处理 |
| **边界** | 验证边界值和极限条件下的行为 |
---
## 2. P1 核心功能测试用例
> **已拆分**: 以下章节已拆分为独立文件，点击链接查看详细用例。
| 文件 | 内容 | 用例范围 |
|------|------|----------|
| <!-- 测试-用例-*.md --> | <!-- 说明 --> | <!-- 范围 --> |
---
## 3. P2 重要功能测试用例
### <!-- N --> <!-- 功能模块 -->
### TC-FUN-<!-- NNN -->: <!-- 用例标题 -->
- **关联FR**: <!-- FR编号 -->
- **优先级**: <!-- P值 -->
- **前置条件**: <!-- 条件 -->
- **步骤**:
1. <!-- 步骤 -->
- **预期结果**: <!-- 预期 -->
- **类型**: <!-- 类型 -->
---
## 4. P3 增强功能测试用例
> 待编写
---
## 5. E2E 端到端测试用例
> 待编写
---
## 6. 可访问性测试用例
> 待编写
---
## 附录 A: FR 测试覆盖矩阵
| FR | 功能描述 | 测试用例 | 类型 |
|----|----------|----------|------|
| <!-- FR --> | <!-- 描述 --> | <!-- 用例 --> | <!-- 类型 --> |
---
## 附录 B: 测试用例统计
| 级别 | 数量 | P1 | P2 | P3 |
|------|------|----|----|----|
| FUN | <!-- 数 --> | <!-- 数 --> | <!-- 数 --> | <!-- 数 --> |
| INT | <!-- 数 --> | <!-- 数 --> | <!-- 数 --> | <!-- 数 --> |
| **合计** | **<!-- 总数 -->** | **<!-- 数 -->** | **<!-- 数 -->** | **<!-- 数 -->** |
---
**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板
docs/测试-计划.md
+200
View File
@@ -0,0 +1,200 @@
# 测试计划
**文档版本**: 1.0.0
**最后更新**: 2026-04-19
---
## 1. 测试目标与范围
### 1.1 测试目标
| 目标 | 说明 | 验证标准 |
|------|------|----------|
| **功能正确性** | 所有功能需求按预期工作 | P1 功能测试通过率 100% |
| **安全性** | <!-- 安全目标 --> | 安全测试零漏洞 |
| **性能达标** | 满足非功能性需求 | 性能测试全部达标 |
| **覆盖率** | 满足各模块覆盖率要求 | <!-- 覆盖率标准 --> |
### 1.2 测试范围
#### 包含范围
| 范围 | 说明 |
|------|------|
| <!-- 模块1 --> | <!-- 说明 --> |
| <!-- 模块2 --> | <!-- 说明 --> |
#### 排除范围
| 范围 | 说明 |
|------|------|
| 第三方库内部 | 不测试第三方库本身 |
| 操作系统层面 | 不测试操作系统功能 |
### 1.3 版本关联
| 关联文档 | 版本 | 用途 |
|----------|------|------|
| `测试-用例.md` | <!-- 版本 --> | 功能测试用例 |
| `测试-单元.md` | <!-- 版本 --> | 单元测试规范 |
| `测试-接口.md` | <!-- 版本 --> | 接口测试规范 |
| `10-测试-方案.md` | <!-- 版本 --> | 测试策略总览 |
---
## 2. 测试策略概述
### 2.1 测试层次模型
```
┌─────────────────────────┐
│ 验收测试（UAT） │ 用户视角验证
├─────────────────────────┤
│ 端到端测试（E2E） │ 完整用户旅程
├─────────────────────────┤
│ 系统测试（SYS） │ 部署+运行环境
├─────────────────────────┤
│ 集成测试（INT） │ 跨组件交互
├─────────────────────────┤
│ 接口测试（API） │ REST API 契约
├─────────────────────────┤
│ 功能测试（FUN） │ UI/用户操作
├─────────────────────────┤
│ 单元测试（UNIT） │ 代码逻辑
└─────────────────────────┘
```
---
## 3. 测试阶段与里程碑
### 3.1 单元测试阶段
#### 阶段目标
验证各模块内部逻辑正确性，确保每个函数和方法按预期工作，达到规定的覆盖率目标。
#### 进入条件
| 条件 | 说明 |
|------|------|
| 代码开发完成 | 目标模块代码已完成并通过编译 |
| 测试框架就绪 | pytest + 相关插件已配置 |
#### 退出条件
| 条件 | 说明 |
|------|------|
| 所有测试通过 | 无失败、无跳过的 P1 测试用例 |
| 覆盖率达标 | 满足各模块覆盖率要求 |
| 无 P1/P2 级缺陷 | 阻塞性缺陷必须清零 |
#### 预计工作量
| 模块 | 预计人天 | 说明 |
|------|---------|------|
| <!-- 模块 --> | <!-- 人天 --> | <!-- 说明 --> |
---
### 3.2 功能测试阶段
> 待编写
---
### 3.3 接口测试阶段
> 待编写
---
### 3.4 集成测试阶段
> 待编写
---
### 3.5 系统测试阶段
> 待编写
---
### 3.6 端到端测试阶段
> 待编写
---
### 3.7 验收测试阶段
> 待编写
---
## 4. 测试环境要求
### 4.1 <!-- 环境 -->
| 项目 | 要求 | 说明 |
|------|------|------|
| 操作系统 | <!-- 要求 --> | <!-- 说明 --> |
| <!-- 运行时 --> | <!-- 版本 --> | <!-- 说明 --> |
| 数据库 | <!-- 要求 --> | <!-- 说明 --> |
### 4.2 测试工具
| 工具 | 版本 | 用途 |
|------|------|------|
| pytest | 8.x | 测试框架 |
| pytest-cov | 最新 | 覆盖率报告 |
| httpx | 最新 | HTTP 客户端 |
---
## 5. 测试资源分配
### 5.1 角色与职责
| 角色 | 职责 | 参与阶段 |
|------|------|----------|
| 测试负责人 | 测试计划制定、进度跟踪 | 全阶段 |
| <!-- 角色 --> | <!-- 职责 --> | <!-- 阶段 --> |
---
## 6. 风险评估与应对
### 6.1 风险清单
| 风险 ID | 风险描述 | 可能性 | 影响 | 风险等级 |
|---------|---------|--------|------|----------|
| <!-- 风险 --> | <!-- 描述 --> | <!-- 可能性 --> | <!-- 影响 --> | <!-- 等级 --> |
---
## 7. 测试交付物清单
| 序号 | 交付物 | 格式 | 负责人 | 交付阶段 |
|------|--------|------|--------|----------|
| 1 | 测试计划 | Markdown | 测试负责人 | 测试启动前 |
| 2 | 单元测试代码 | Python | 各模块测试工程师 | 单元测试阶段 |
| 3 | 测试报告 | HTML/Markdown | 测试负责人 | 各阶段完成后 |
---
## 8. 测试进度跟踪表
| 阶段 | 状态 | 计划开始 | 计划结束 | 预计人天 | 关联用例 |
|------|------|----------|----------|---------|----------|
| 3.1 单元测试 | 未开始 | — | — | <!-- 人天 --> | <!-- 用例 --> |
| 3.2 功能测试 | 未开始 | — | — | <!-- 人天 --> | <!-- 用例 --> |
| 3.3 接口测试 | 未开始 | — | — | <!-- 人天 --> | <!-- 用例 --> |
| **合计** | — | — | — | **<!-- 总人天 -->** | — |
---
**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板
docs/管理-Agent-Team分工及提示词.md
+285
View File
@@ -0,0 +1,285 @@
# Agent Team 分工及提示词
**文档版本**: 1.0.0
**最后更新**: 2026-04-19
---
## 目录
1. [概述](#1-概述)
2. [角色定义与分工](#2-角色定义与分工)
3. [<!-- 角色1 -->Agent](#3-角色1-agent)
4. [<!-- 角色2 -->Agent](#4-角色2-agent)
5. [<!-- 角色3 -->Agent](#5-角色3-agent)
6. [<!-- 角色4 -->Agent](#6-角色4-agent)
7. [协作流程](#7-协作流程)
8. [资源约束](#8-资源约束)
9. [产出物验收标准](#9-产出物验收标准)
---
## 1. 概述
### 1.1 目的
本文档定义项目**开发阶段**的 Agent Team 协作模式，面向实际编码和测试工作。每个角色的提示词模板可直接复制到 tmux Pane 中启动 Agent。
### 1.2 适用范围
- **阶段**: <!-- 开发阶段说明 -->
- **角色**: <!-- 角色列表 -->
- **协作方式**: tmux 4 Pane 并行工作
### 1.3 核心约束
| 约束 | 说明 |
|------|------|
| 模块独立性 | 各模块完全独立，禁止跨模块代码引用 |
| 通信方式 | 仅通过 REST API |
| 版本控制 | Jujutsu (jj)，主分支 `trunk` |
| 提交类型 | 使用中文（功能、修复、维护、文档、重构、测试...） |
| 包管理 | uv（Python）、nvm + npm（前端） |
---
## 2. 角色定义与分工
### 2.1 角色总览
| 角色 | 代码目录 | 技术栈 | 负责里程碑 |
|------|---------|--------|-----------|
| **<!-- 角色1 -->** | `apps/<!-- 模块1 -->/` | <!-- 技术栈 --> | <!-- 里程碑 --> |
| **<!-- 角色2 -->** | `apps/<!-- 模块2 -->/` | <!-- 技术栈 --> | <!-- 里程碑 --> |
| **<!-- 角色3 -->** | `tests/` | <!-- 技术栈 --> | 所有里程碑 |
| **项目经理** | `docs/`, 项目根目录 | 文档管理、进度追踪 | 所有里程碑 |
### 2.2 里程碑与角色映射
| 里程碑 | <!-- 角色1 --> | <!-- 角色2 --> | 测试 |
|--------|:---:|:---:|:---:|
| M1: <!-- 阶段1 --> | ● | ● | ○ |
| M2: <!-- 阶段2 --> | ● | | ● |
| M3: <!-- 阶段3 --> | | ● | ● |
● 主要负责 ○ 配合测试
### 2.3 角色依赖关系
```
PM ──分发任务──→ <!-- 角色1 --> ──完成──→ 测试工程师
│ │
├──分发任务──→ <!-- 角色2 --> ──完成──→ 测试工程师
│ │
└──────────进度跟踪 & 验收────────────┘
```
---
## 3. <!-- 角色1 -->Agent
### 3.1 职责
- <!-- 职责1 -->
- <!-- 职责2 -->
### 3.2 技术栈
| 组件 | 技术 | 约束 |
|------|------|------|
| <!-- 组件 --> | <!-- 技术 --> | <!-- 约束 --> |
### 3.3 项目结构
```
apps/<!-- 模块 -->/
├── src/<!-- 模块名 -->/
│ ├── main.py
│ ├── api/
│ ├── services/
│ ├── models/
│ ├── db/
│ └── config/
├── tests/
│ ├── conftest.py
│ ├── unit/
│ └── integration/
└── pyproject.toml
```
### 3.4 完整提示词模板
**复制以下内容到 tmux Pane 启动 Agent**：
```
你是项目的<!-- 角色1 -->工程师。
## 你的职责
<!-- 职责列表 -->
## 技术栈
- <!-- 技术栈列表 -->
## 编码规范
- 缩进：4 空格 | 行宽：100 字符
- 命名：PascalCase 类/类型，snake_case 函数/变量，UPPER_SNAKE_CASE 常量
- Docstring：Google 风格，公共函数和类必须有
- 字符串：用户可见用双引号，代码内部用单引号
- 类型注解：所有函数必须有完整类型注解
## 架构约束
- 各模块完全独立，禁止跨模块引用
- 通信方式：仅 REST API
## 验证步骤
每次编码完成后执行：
1. uv run mypy src --strict # 类型检查
2. ruff format --check . && ruff check . # 代码格式和 Lint
3. uv run pytest tests/unit/ -v # 单元测试
4. uv run pytest --cov=src # 覆盖率检查
## 版本控制
- 工具：Jujutsu (jj)，并存模式
- 主分支：trunk
- 提交格式：<中文类型>(<作用域>): <描述>
- 提交标题不超过 50 字符
```
---
## 4. <!-- 角色2 -->Agent
<!-- 按 §3 模板添加 -->
---
## 5. <!-- 角色3 -->Agent
<!-- 按 §3 模板添加 -->
---
## 6. 项目经理 Agent
### 6.1 职责
- 任务分析和分发
- 进度跟踪和协调
- 代码审查协调
- 验收检查
- Agent 生命周期管理
### 6.2 完整提示词模板
**复制以下内容到 tmux Pane 启动 Agent**：
```
你是项目的项目经理（PM），负责开发阶段的任务分发、进度跟踪和质量验收。
## 你的职责
1. 分析任务需求，拆解为可分发的子任务
2. 通过 tmux send-keys 向各 Pane 分发任务
3. 跟踪各 Agent 的进度和完成状态
4. 协调 Agent 间的依赖关系
5. 执行产出物验收检查
6. 管理 Agent 生命周期
## 验收检查项
| 检查项 | 命令 |
|--------|------|
| 类型检查 | uv run mypy src --strict |
| 格式化 | ruff format --check . |
| Lint | ruff check . |
| 单元测试 | uv run pytest tests/unit/ -v |
| 覆盖率 | uv run pytest --cov=src --cov-report=term |
## 版本控制
- 工具：Jujutsu (jj)
- 主分支：trunk
- 提交格式：<中文类型>(<作用域>): <描述>
```
---
## 7. 协作流程
### 7.1 启动团队
```bash
# 使用 /isos-tmux-team 启动 4 Pane 工作空间
/isos-tmux-team
```
### 7.2 典型任务流转
```
1. PM 分析任务
2. PM → 对应 Pane：发送任务提示词
3. Agent 完成开发
4. PM 验收：类型检查 + 测试 + 覆盖率
5. PM → 测试 Pane：发送测试任务
6. 测试 Agent 完成
7. PM 最终验收
```
---
## 8. 资源约束
### 8.1 tmux 资源
| 约束 | 限制 | 原因 |
|------|------|------|
| Window 数量 | 最多 1 个 | 资源集中 |
| Pane 数量 | 最多 4 个 | 内存和 CPU 限制 |
| Agent 运行时间 | 建议不超过 30 分钟 | 上下文窗口限制 |
### 8.2 并行开发
- Agent 通过 `EnterWorktree` 在独立 git worktree 中工作
- 禁止多个 Agent 在同一目录编辑
- 合并冲突在主目录解决
---
## 9. 产出物验收标准
### 9.1 代码类产出
| 检查项 | 标准 | 命令 |
|--------|------|------|
| 类型检查 | mypy --strict 通过 | `uv run mypy src --strict` |
| 格式化 | ruff format 通过 | `ruff format --check .` |
| Lint | ruff check 通过 | `ruff check .` |
| 单元测试 | 全部通过 | `uv run pytest tests/unit/ -v` |
| 覆盖率 | 达到模块要求 | `uv run pytest --cov=src` |
### 9.2 测试类产出
| 检查项 | 标准 |
|--------|------|
| 覆盖率 | 满足各模块覆盖率要求 |
| 功能覆盖 | 测试用例覆盖所有相关 FR |
### 9.3 版本控制
| 检查项 | 标准 |
|--------|------|
| 提交类型 | 使用中文类型 |
| 提交标题 | 不超过 50 字符 |
| 模块边界 | 每个 PR 只改动一个模块 |
---
**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板
docs/管理-开发入门.md
+232
View File
@@ -0,0 +1,232 @@
# 开发入门
**文档版本**: 1.0.0
**最后更新**: 2026-04-19
---
## 目录
1. [项目概览](#1-项目概览)
2. [快速开始](#2-快速开始)
3. [项目结构](#3-项目结构)
4. [开发工作流](#4-开发工作流)
5. [常用命令](#5-常用命令)
6. [代码质量](#6-代码质量)
7. [测试](#7-测试)
8. [文档体系](#8-文档体系)
---
## 1. 项目概览
<!-- 项目简介 -->
### 技术栈
| 组件 | 技术 |
|------|------|
| 语言 | <!-- 语言 --> |
| 框架 | <!-- 框架 --> |
| 数据库 | <!-- 数据库 --> |
| 版本控制 | Jujutsu (jj) |
| 包管理 | uv（Python）/ nvm + npm（前端） |
### 核心架构约束
- **模块独立性**：各模块完全独立，禁止跨模块代码引用
- **通信方式**：仅通过 REST API
- <!-- 其他约束 -->
---
## 2. 快速开始
### 2.1 环境搭建
完整的环境搭建指南见 [`管理-开发环境搭建.md`](./管理-开发环境搭建.md)。核心步骤：
```bash
# 1. 克隆仓库
jj git clone <!-- 仓库地址 -->
cd <!-- 项目目录 -->
# 2. 安装依赖
cd apps/<!-- 模块 --> && uv sync && cd ../..
```
### 2.2 验证安装
```bash
# <!-- 模块 -->
cd apps/<!-- 模块 -->
uv run python -c "from <!-- 模块名 -->.main import app; print('OK')"
```
---
## 3. 项目结构
```
<!-- 项目名 -->/
├── apps/
│ ├── <!-- 模块1 -->/ # <!-- 说明 -->
│ │ ├── src/<!-- 模块名 -->/
│ │ │ ├── main.py
│ │ │ ├── api/
│ │ │ ├── services/
│ │ │ ├── models/
│ │ │ └── db/
│ │ ├── tests/
│ │ └── pyproject.toml
│ │
│ └── <!-- 模块2 -->/ # <!-- 说明 -->
│ └── ...
│
├── docs/ # 项目文档
├── specs/ # 功能规格
├── team/ # 团队公共知识
└── .claude/ # Claude Code 配置
```
### 模块边界
| 规则 | 说明 |
|------|------|
| 禁止跨模块引用 | 各模块之间不能 import |
| 仅通过 REST API 通信 | <!-- 说明 --> |
| 独立数据库 | 各模块有独立数据库，Schema 版本独立递增 |
| 独立依赖 | 各模块有独立 `pyproject.toml` |
---
## 4. 开发工作流
### 4.1 speckit 功能开发流程
```
/speckit.specify → spec.md → /speckit.plan → plan.md → /speckit.tasks → tasks.md → /speckit.implement
```
### 4.2 版本控制
项目使用 Jujutsu (jj)，并存模式：
```bash
# 日常开发
jj new trunk # 在 trunk 上新建工作副本
# ... 编写代码 ...
jj diff # 查看变更
jj describe -m "功能: 添加xxx" # 设置提交消息
jj new # 固化当前提交
# 推送到远程
jj b c feature-xxx # 创建书签
jj git push -b feature-xxx # 推送
```
> 完整 jj 命令对照表见 [`team/jj.md`](../team/jj.md)，Git 提交规范见 [`team/git.md`](../team/git.md)。
**提交类型（中文）**：功能、修复、维护、文档、重构、测试、格式、性能、构建、安全、依赖、清理、配置、规格、合并、回滚
### 4.3 PR 规范
- 每个 PR 只能改动一个模块
- 标题格式：`[模块] 描述`
- 主分支：`trunk`（Trunk-Based Development）
---
## 5. 常用命令
```bash
# 类型检查
uv run mypy src --strict
# 运行测试
uv run pytest
# 代码质量
ruff format --check . && ruff check .
# 格式化
ruff format .
# Lint 自动修复
ruff check . --fix
```
---
## 6. 代码质量
### 编码规范
| 规范项 | 规则 |
|--------|------|
| 缩进 | 4 空格 |
| 行长度 | 100 字符 |
| 命名 | PascalCase 类/类型，snake_case 函数/变量，UPPER_SNAKE_CASE 常量 |
| 类型注解 | mypy strict，禁止 `Any` |
| Docstring | Google 风格，公共 API 必须有 |
| 字符串 | 用户可见用双引号，代码内部用单引号 |
### 质量门禁
```bash
ruff format --check . # 格式检查
ruff check . # Lint 检查
uv run mypy --strict # 类型检查
uv run pytest # 测试通过
```
---
## 7. 测试
### 测试策略
详见 [`10-测试-方案.md`](./10-测试-方案.md) 和 [`测试-计划.md`](./测试-计划.md)。
### 测试文件组织
```
apps/<!-- 模块 -->/tests/
├── unit/ # 单元测试
├── integration/ # 集成测试
└── conftest.py # 测试夹具
```
### 运行测试
```bash
# 全部测试
uv run pytest
# 仅单元测试
uv run pytest tests/unit/
# 带覆盖率
uv run pytest --cov=src --cov-report=term-missing
```
---
## 8. 文档体系
项目文档按类型分类，全部使用中文命名：
| 类别 | 前缀 | 示例 |
|------|------|------|
| 核心文档 | `01-` ~ `12-` | `01-用户需求.md` |
| 设计文档 | `设计-` | `设计-Apple风格.md` |
| 管理文档 | `管理-` | `管理-开发入门.md` |
| 运维文档 | `运维-` | `运维-部署实施.md` |
| 测试文档 | `测试-` | `测试-方案.md` |
完整索引见 [`README.md`](./README.md) 和 [`CLAUDE.md`](./CLAUDE.md)。
---
**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板
docs/管理-开发环境搭建.md
+142
View File
@@ -0,0 +1,142 @@
# 开发环境搭建
**文档版本**: 1.0.0
**最后更新**: 2026-04-19
---
## 目录
1. [环境要求](#1-环境要求)
2. [<!-- 模块1 -->环境](#2-模块1环境)
3. [<!-- 模块2 -->环境](#3-模块2环境)
4. [IDE 配置](#4-ide-配置)
5. [常见问题](#5-常见问题)
---
## 1. 环境要求
### 1.1 操作系统
- <!-- 操作系统要求 -->
### 1.2 基础依赖
| 工具 | 版本 | 用途 |
|------|------|------|
| <!-- 工具 --> | <!-- 版本 --> | <!-- 用途 --> |
### 1.3 镜像源配置
国内开发环境建议配置镜像源（详见 [`team/mirrors.md`](../team/mirrors.md)）。
---
## 2. <!-- 模块1 -->环境
### 2.1 克隆与安装
```bash
# 克隆仓库
jj git clone <!-- 仓库地址 -->
cd <!-- 项目目录 -->
# 安装依赖
cd apps/<!-- 模块 -->
uv sync
```
### 2.2 开发服务器启动
```bash
cd apps/<!-- 模块 -->
uv run <!-- 启动命令 -->
```
### 2.3 数据库初始化
> 待编写
---
## 3. <!-- 模块2 -->环境
### 3.1 <!-- 环境说明 -->
```bash
# 安装依赖
cd apps/<!-- 模块 -->
uv sync
# 启动
uv run <!-- 启动命令 -->
```
---
## 4. IDE 配置
### 4.1 VS Code 推荐扩展
```json
{
"recommendations": [
"charliermarsh.ruff",
"ms-python.mypy-type-checker",
"ms-python.python"
]
}
```
| 扩展 | 用途 |
|------|------|
| **Ruff** | Python 格式化 + Lint |
| **mypy Type Checker** | Python 类型检查 |
| **Python** | Python 语言支持、调试 |
### 4.2 代码格式化与 Lint
- 格式化：`ruff format`
- Lint：`ruff check`
- 类型检查：`mypy --strict`
### 4.3 调试配置
> 待编写
---
## 5. 常见问题
### 5.1 Python 环境问题
**Q: `uv sync` 安装依赖失败**
A: 检查 Python 版本是否符合要求，并确认镜像源配置正确。
**Q: `mypy --strict` 报大量错误**
A: 项目强制 mypy strict 模式，禁止 `Any` 类型。确保所有函数和变量都有完整类型注解。
### 5.2 前端环境问题
> 待编写
### 5.3 数据库问题
**Q: Schema 迁移失败**
A: 迁移前会自动备份。恢复方法：
```bash
cp backups/backup_v{N}.db data/<!-- 数据库文件 -->
```
### 5.4 版本控制问题
**Q: jj 和 git 命令如何选择**
A: 项目默认使用 jj。常用命令对照见 [`team/jj.md`](../team/jj.md)。
> 更多运行时故障排除见 [`运维-故障排除.md`](./运维-故障排除.md)。
---
**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板
docs/设计-Apple风格.md
+325
View File
@@ -0,0 +1,325 @@
# Apple 风格设计系统
**文档版本**: 1.0.0
**最后更新**: 2026-04-19
## 1. 视觉主题与氛围
Apple 的网站堪称"克制的戏剧性"之典范——大面积的纯黑与近白色充当电影般的背景幕布，产品如画廊中的雕塑般被精心呈现。其设计哲学的核心是"减法"：每一个像素都为产品服务，界面本身则退隐至无形。这不是审美偏好上的极简主义，而是对产品本身的"致敬式"极简。
排版是一切的根基。Inter 字体族（大字号使用 Inter Display，正文使用 Inter）是专为屏幕设计的开源字体，采用光学尺寸技术，可根据字号自动调整字形，CJK 字形自动回退到 Noto Sans SC。在展示级尺寸（56px）下，字重 600、紧凑行高 1.07 并辅以微量的负字间距（-0.28px），打造出"精密加工"而非"手工排版"的标题感受——精准、自信、毫不妥协。在正文尺寸（17px）下，字距略微放松（-0.374px），行高展开至 1.47，营造舒适而不松散的阅读节奏。
色彩叙事呈现极端的二元对立。产品区块在纯黑（`#000000`）背景配白色文字与浅灰（`#f5f5f7`）背景配近黑色文字（`#1d1d1f`）之间交替。这营造出电影般的节奏感——暗色区块沉浸而高端，浅色区块开阔而信息丰富。唯一的彩色点缀是 Apple 蓝（`#0071e3`），专门保留给交互元素：链接、按钮和焦点状态。在一片中性色调中，这一独特色彩让每一个可点击元素都拥有不可忽视的辨识度。
**核心特征：**
- Inter Display/Inter 配合光学尺寸——字形随尺寸上下文自动适配
- 二元明暗区块节奏：纯黑（`#000000`）与浅灰（`#f5f5f7`）交替出现
- 单一强调色：Apple 蓝（`#0071e3`）专属于交互元素
- 产品即主角的产品摄影置于纯色背景——无渐变、无纹理、无干扰
- 极度紧凑的标题行高（1.07-1.14），营造压缩的、广告牌般的视觉冲击力
- 全宽区块布局搭配居中内容——视口即画布
- 胶囊形 CTA 按钮（980px 圆角），柔和且亲切的行动号召
- 区块间充裕的留白，让每个产品展示"独立呼吸"
## 2. 色彩体系与角色
### 主色调
- **纯黑** (`#000000`)：主视觉区块背景、沉浸式产品展示。最深的画布衬托最亮眼的产品。
- **浅灰** (`#f5f5f7`)：交替区块背景、信息展示区域。不是纯白——微妙的蓝灰色调避免了刻板感。
- **近黑** (`#1d1d1f`)：浅色背景上的主要文字、深色按钮填充。比纯黑略暖，阅读更舒适。
### 交互色
- **Apple 蓝** (`#0071e3`)：`--sk-focus-color`，主要 CTA 背景色、焦点环。界面中唯一的彩色。
- **链接蓝** (`#0066cc`)：`--sk-body-link-color`，行内文字链接。比 Apple 蓝略深，确保文字级可读性。
- **亮蓝** (`#2997ff`)：暗色背景上的链接。更高的亮度确保在黑色区块上的对比度。
### 文字色
- **白色** (`#ffffff`)：暗色背景上的文字、蓝色/深色 CTA 上的按钮文字。
- **近黑** (`#1d1d1f`)：浅色背景上的主要正文文字。
- **80% 黑** (`rgba(0, 0, 0, 0.8)`)：次要文字、浅色背景上的导航项。略柔化处理。
- **48% 黑** (`rgba(0, 0, 0, 0.48)`)：辅助文字、禁用状态、轮播控件。
### 表面与暗色变体
- **暗色表面 1** (`#272729`)：暗色区块中的卡片背景。
- **暗色表面 2** (`#262628`)：暗色环境中的微妙表面变化。
- **暗色表面 3** (`#28282a`)：暗色背景上的凸起卡片。
- **暗色表面 4** (`#2a2a2d`)：最高暗色表面层级。
- **暗色表面 5** (`#242426`)：最深的暗色表面色调。
### 按钮状态
- **按钮激活** (`#ededf2`)：浅色按钮的激活/按下状态。
- **按钮默认浅色** (`#fafafc`)：搜索/筛选按钮背景。
- **遮罩** (`rgba(210, 210, 215, 0.64)`)：媒体控件遮罩、覆盖层。
- **32% 白** (`rgba(255, 255, 255, 0.32)`)：暗色弹窗关闭按钮的悬停状态。
### 阴影
- **卡片阴影** (`rgba(0, 0, 0, 0.22) 3px 5px 30px 0px`)：产品卡片柔和、弥散的抬升阴影。偏移量与宽幅模糊营造自然、如摄影般的阴影效果。
## 3. 排版规范
### 字体族
- **展示字体**：`Inter Display`，备选字体：`Inter, Noto Sans SC, sans-serif`
- **正文字体**：`Inter`，备选字体：`Noto Sans SC, sans-serif`
- **等宽字体**：`JetBrains Mono`，备选字体：`monospace`
- Inter Display 用于 20px 及以上；Inter 针对 19px 及以下优化。Inter Display 具有更宽的字间距和更细的笔画，针对大字号优化；Inter 更紧凑扎实，适合小字号。CJK 字形自动回退到 Noto Sans SC。
### 层级体系
| 角色 | 字体 | 字号 | 字重 | 行高 | 字间距 | 备注 |
|------|------|------|------|------|--------|------|
| 展示级主视觉 | Inter Display | 56px (3.50rem) | 600 | 1.07（紧凑） | -0.28px | 产品发布标题，最大视觉冲击 |
| 区块标题 | Inter Display | 40px (2.50rem) | 600 | 1.10（紧凑） | normal | 功能区块标题 |
| 瓷砖标题 | Inter Display | 28px (1.75rem) | 400 | 1.14（紧凑） | 0.196px | 产品瓷砖标题 |
| 卡片标题 | Inter Display | 21px (1.31rem) | 700 | 1.19（紧凑） | 0.231px | 粗体卡片标题 |
| 副标题 | Inter Display | 21px (1.31rem) | 400 | 1.19（紧凑） | 0.231px | 常规卡片标题 |
| 导航标题 | Inter | 34px (2.13rem) | 600 | 1.47 | -0.374px | 大号导航标题 |
| 子导航 | Inter | 24px (1.50rem) | 300 | 1.50 | normal | 轻量子导航文字 |
| 正文 | Inter | 17px (1.06rem) | 400 | 1.47 | -0.374px | 标准阅读文字 |
| 正文强调 | Inter | 17px (1.06rem) | 600 | 1.24（紧凑） | -0.374px | 强调正文、标签 |
| 大号按钮 | Inter | 18px (1.13rem) | 300 | 1.00（紧凑） | normal | 大号按钮文字，轻字重 |
| 按钮 | Inter | 17px (1.06rem) | 400 | 2.41（宽松） | normal | 标准按钮文字 |
| 链接 | Inter | 14px (0.88rem) | 400 | 1.43 | -0.224px | 正文链接，"了解更多" |
| 说明文字 | Inter | 14px (0.88rem) | 400 | 1.29（紧凑） | -0.224px | 次要文字、描述 |
| 说明文字粗体 | Inter | 14px (0.88rem) | 600 | 1.29（紧凑） | -0.224px | 强调说明文字 |
| 微型文字 | Inter | 12px (0.75rem) | 400 | 1.33 | -0.12px | 脚注、附注 |
| 微型文字粗体 | Inter | 12px (0.75rem) | 600 | 1.33 | -0.12px | 粗体附注 |
| 纳米文字 | Inter | 10px (0.63rem) | 400 | 1.47 | -0.08px | 法律声明文字，最小字号 |
### 设计原则
- **Inter 光学尺寸**：Inter 在 Display 与 Text 光学尺寸间对应——Inter Display 具有更宽的字间距和更细的笔画，针对大字号（≥20px）优化；Inter 更紧凑扎实，适合小字号（<20px）。CJK 字形通过 fontconfig 自动回退到 Noto Sans SC。
- **等宽密码显示**：密码、代码和 ID 字段使用 JetBrains Mono，确保字符等宽可读。
- **字重克制**：字重跨度从 300（轻体）到 700（粗体），但绝大部分文字使用 400（常规）和 600（半粗）。字重 300 仅出现在大型装饰性文字上。字重 700 较为罕见，仅用于粗体卡片标题。
- **全字号负字间距**：与大多数仅对标题应用字间距的系统不同，Apple 甚至在正文字号也施加微量负字间距（17px 时 -0.374px，14px 时 -0.224px，12px 时 -0.12px）。这造就了全局紧凑、高效的文字排布。
- **极端的行高范围**：标题压缩至 1.07，正文展开至 1.47，某些按钮场景甚至拉伸至 2.41。这种戏剧性的范围差仅凭节奏就创造了清晰的视觉层级。
## 4. 组件样式
### 按钮
**主要蓝色按钮（CTA）**
- 背景：`#0071e3`（Apple 蓝）
- 文字：`#ffffff`
- 内边距：8px 15px
- 圆角：8px
- 边框：1px solid transparent
- 字体：Inter, 17px, 字重 400
- 悬停：背景略微提亮
- 激活：背景色偏移至 `#ededf2`
- 焦点：`2px solid var(--sk-focus-color, #0071E3)` 轮廓
- 用途：主要行动号召（"购买"、"选购 iPhone"）
**深色主要按钮**
- 背景：`#1d1d1f`
- 文字：`#ffffff`
- 内边距：8px 15px
- 圆角：8px
- 字体：Inter, 17px, 字重 400
- 用途：次要 CTA，深色变体
**胶囊链接（了解更多 / 选购）**
- 背景：transparent
- 文字：`#0066cc`（浅色背景）或 `#2997ff`（深色背景）
- 圆角：980px（全胶囊形）
- 边框：1px solid `#0066cc`
- 字体：Inter, 14px-17px
- 悬停：下划线装饰
- 用途："了解更多"和"选购"链接——Apple 标志性的行内 CTA
**筛选/搜索按钮**
- 背景：`#fafafc`
- 文字：`rgba(0, 0, 0, 0.8)`
- 内边距：0px 14px
- 圆角：11px
- 边框：3px solid `rgba(0, 0, 0, 0.04)`
- 焦点：`2px solid var(--sk-focus-color, #0071E3)` 轮廓
- 用途：搜索栏、筛选控件
**媒体控件**
- 背景：`rgba(210, 210, 215, 0.64)`
- 文字：`rgba(0, 0, 0, 0.48)`
- 圆角：50%（圆形）
- 激活：scale(0.9)，背景色偏移
- 焦点：`2px solid var(--sk-focus-color, #0071e3)` 轮廓，白色背景，黑色文字
- 用途：播放/暂停、轮播箭头
### 卡片与容器
- 背景：`#f5f5f7`（浅色）或 `#272729`-`#2a2a2d`（深色）
- 边框：无（Apple 的设计体系中极少使用边框）
- 圆角：5px-8px
- 阴影：`rgba(0, 0, 0, 0.22) 3px 5px 30px 0px`，用于凸起的产品卡片
- 内容：居中，充裕的内边距
- 悬停：无标准悬停状态——卡片是静态的，其中的链接才是交互元素
### 导航
- 背景：`rgba(0, 0, 0, 0.8)`（半透明深色）配合 `backdrop-filter: saturate(180%) blur(20px)`
- 高度：48px（紧凑）
- 文字：`#ffffff`，12px，字重 400
- 激活：悬停时显示下划线
- Logo：Apple 标志（SVG）居中或左对齐，17x48px 视口
- 移动端：折叠为汉堡菜单，配合全屏覆盖式菜单
- 导航悬浮于内容之上，无论下方区块背景如何，始终保持深色半透明毛玻璃效果
### 图片处理
- 产品置于纯色背景（黑色或白色）——无背景、无场景、只有产品本身
- 通栏区块图片横跨整个视口宽度
- 产品摄影采用超高分辨率，配以微妙阴影
- 生活方式图片限定在圆角容器中（12px+ 圆角）
### 特色组件
**产品主视觉模块**
- 全视口宽度区块，纯色背景（黑色或 `#f5f5f7`）
- 产品名称作为主标题（Inter Display, 56px, 字重 600）
- 下方一行轻字重描述文字
- 两个并排胶囊 CTA："了解更多"（描边）和"购买" / "选购"（填充）
**产品网格瓷砖**
- 正方形或近方形卡片，置于对比色背景上
- 产品图片占据瓷砖 60-70% 的面积
- 下方为产品名称 + 一行描述
- 底部为"了解更多"和"选购"链接对
**功能对比条**
- 产品变体的水平滚动展示
- 每个变体以纵向卡片呈现，包含图片、名称和核心规格
- 极简装饰——让产品自己说话
## 5. 布局原则
### 间距体系
- 基准单位：8px
- 刻度：2px, 4px, 5px, 6px, 7px, 8px, 9px, 10px, 11px, 14px, 15px, 17px, 20px, 24px
- 显著特征：刻度在小尺寸端密集（2-11px），以 1px 为增量粒度递增，然后以较大步长跳跃。这允许对排版和图标对齐进行精确的微调。
### 网格与容器
- 最大内容宽度：约 980px（胶囊按钮中反复出现的"980px 圆角"正呼应了这一宽度）
- 主视觉：全视口宽度区块，居中内容块
- 产品网格：居中容器内的 2-3 列布局
- 主视觉场景采用单列——一个产品、一个信息、全部注意力
- 无可见网格线或间距槽——间距本身暗示结构
### 留白哲学
- **电影般的呼吸空间**：每个产品区块占据接近整个视口高度。产品之间的留白不是"空白"——它是电影场景之间的"停顿"。
- **通过色块建立纵向节奏**：Apple 不仅依靠间距来分隔区块，更通过交替的背景色（黑色、`#f5f5f7`、白色）来区分。每次色彩变化都标志着一个新的"场景"。
- **内紧外松**：文字块排列紧凑（负字间距、紧凑行高），而周围的留白则极为广阔。这在密集与开阔之间制造了一种张力。
### 圆角刻度
- 微型（5px）：小型容器、链接标签
- 标准（8px）：按钮、产品卡片、图片容器
- 舒适（11px）：搜索输入框、筛选按钮
- 大号（12px）：功能面板、生活方式图片容器
- 全胶囊（980px）：CTA 链接（"了解更多"、"选购"）、导航胶囊
- 圆形（50%）：媒体控件（播放/暂停、箭头）
## 6. 层次与抬升
| 层级 | 处理方式 | 用途 |
|------|----------|------|
| 平面（层级 0） | 无阴影，纯色背景 | 标准内容区块、文字块 |
| 导航毛玻璃 | 在 `rgba(0,0,0,0.8)` 上应用 `backdrop-filter: saturate(180%) blur(20px)` | 固定导航栏——毛玻璃效果 |
| 微妙抬升（层级 1） | `rgba(0, 0, 0, 0.22) 3px 5px 30px 0px` | 产品卡片、浮动元素 |
| 媒体控件 | `rgba(210, 210, 215, 0.64)` 背景配合缩放变换 | 播放/暂停按钮、轮播控件 |
| 焦点（无障碍） | `2px solid #0071e3` 轮廓 | 所有交互元素的键盘焦点 |
**阴影哲学**：Apple 极其节制地使用阴影。主要阴影（`3px 5px 30px`，透明度 0.22）柔和、宽广且带偏移——模拟漫射影棚灯光在实体物体下方投射的自然阴影。这强化了"产品即实体雕塑"的隐喻。大多数元素完全没有阴影；层级感来自背景色的对比（暗色卡片置于更深的背景上，或浅色卡片置于略不同的灰色上）。
### 装饰性深度
- 导航毛玻璃：半透明、模糊的导航栏是最具辨识度的深度元素，营造出 UI 悬浮于滚动内容之上的感觉
- 区块色彩过渡：深度感通过黑色与浅灰区块的交替来暗示，而非通过阴影
- 产品摄影阴影：产品本身在摄影中即投射阴影，因此 UI 不需要添加人工阴影
## 7. 设计准则
### 应该做的
- 20px 及以上使用 Inter Display，20px 以下使用 Inter——尊重光学尺寸边界
- 在所有文字尺寸下应用负字间距（不仅限于标题）——Apple 全局使用紧凑字距
- 仅将 Apple 蓝（`#0071e3`）用于交互元素——它必须是唯一的强调色
- 在黑色与浅灰（`#f5f5f7`）区块背景之间交替，营造电影般的节奏感
- CTA 链接使用 980px 胶囊圆角——Apple 标志性的链接形状
- 将产品图片置于纯色背景上，排除任何竞争性视觉元素
- 固定导航使用半透明深色毛玻璃（`rgba(0,0,0,0.8)` + 模糊）
- 将标题行高压缩至 1.07-1.14——Apple 的标题以紧凑著称
### 不应该做的
- 不要引入额外的强调色——全部色彩预算都花在了蓝色上
- 不要使用浓重阴影或多层阴影——Apple 的阴影体系要么是一个柔和弥散阴影，要么完全没有
- 不要在卡片或容器上使用边框——Apple 几乎从不使用可见边框（特定按钮除外）
- 不要对 Inter 施加宽松字间距——它在每个尺寸下都设计为紧凑排列
- 不要使用 800 或 900 字重——最大为 700（粗体），即便如此也很少使用
- 不要在背景上添加纹理、图案或渐变——仅使用纯色
- 不要让导航栏变为不透明——毛玻璃模糊效果是 Apple UI 身份的核心要素
- 不要将正文居中对齐——Apple 的正文采用左对齐；仅标题居中
- 不要在矩形元素上使用超过 12px 的圆角（980px 仅用于胶囊形按钮）
## 8. 响应式行为
### 断点
| 名称 | 宽度 | 关键变化 |
|------|------|----------|
| 小型移动端 | <360px | 最低支持尺寸，单列 |
| 移动端 | 360-480px | 标准移动端布局 |
| 大型移动端 | 480-640px | 更宽的单列，更大的图片 |
| 小型平板 | 640-834px | 开始出现两列产品网格 |
| 平板 | 834-1024px | 完整平板布局，展开导航 |
| 小型桌面 | 1024-1070px | 标准桌面布局开始 |
| 桌面 | 1070-1440px | 完整布局，最大内容宽度 |
| 大型桌面 | >1440px | 居中展示，充裕边距 |
### 触控目标
- 主要 CTA：8px 15px 内边距，形成约 44px 触控高度
- 导航链接：48px 高度，间距充足
- 媒体控件：50% 圆角的圆形按钮，最小 44x44px
- "了解更多"胶囊：充裕的内边距，确保舒适的点击体验
### 折叠策略
- 主视觉标题：56px Display → 40px → 移动端 28px，按比例保持紧凑行高
- 产品网格：3 列 → 2 列 → 单列堆叠
- 导航：完整水平导航 → 紧凑移动端菜单（汉堡图标）
- 产品主视觉模块：所有尺寸保持通栏，文字等比缩小
- 区块背景：所有断点下保持全宽色块——电影般的节奏永不中断
- 图片尺寸：产品等比缩放，绝不裁剪——产品轮廓是神圣不可侵犯的
### 图片行为
- 产品摄影在所有断点下保持宽高比
- 主视觉产品图片等比缩小但始终居中
- 通栏区块背景在每个尺寸下持续展示
- 生活方式图片在移动端可能裁剪，但保持圆角
- 折叠线以下的产品图片采用懒加载
## 9. Agent 提示词指南
### 快速色彩参考
- 主要 CTA：Apple 蓝（`#0071e3`）
- 页面背景（浅色）：`#f5f5f7`
- 页面背景（深色）：`#000000`
- 标题文字（浅色背景）：`#1d1d1f`
- 标题文字（深色背景）：`#ffffff`
- 正文文字：浅色背景上 `rgba(0, 0, 0, 0.8)`，深色背景上 `#ffffff`
- 链接（浅色背景）：`#0066cc`
- 链接（深色背景）：`#2997ff`
- 焦点环：`#0071e3`
- 卡片阴影：`rgba(0, 0, 0, 0.22) 3px 5px 30px 0px`
### 组件提示词示例
- "创建一个黑色背景的主视觉区块。标题使用 56px Inter Display 字重 600，行高 1.07，字间距 -0.28px，颜色白色。下方一行副标题使用 21px Inter Display 字重 400，行高 1.19，颜色白色。两个胶囊 CTA 并排：'了解更多'（透明背景，白色文字，1px 白色描边，980px 圆角）和'购买'（Apple 蓝 #0071e3 背景，白色文字，8px 圆角，8px 15px 内边距）。"
- "设计一张产品卡片：#f5f5f7 背景，8px 圆角，无边框，无阴影。产品图片占据卡片上方 60%，纯色背景。标题使用 28px Inter Display 字重 400，字间距 0.196px，行高 1.14。描述使用 14px Inter 字重 400，颜色 rgba(0,0,0,0.8)。'了解更多'和'选购'链接使用 #0066cc，14px。"
- "构建 Apple 导航栏：固定定位，48px 高度，背景 rgba(0,0,0,0.8) 配合 backdrop-filter: saturate(180%) blur(20px)。链接使用 12px Inter 字重 400，白色文字。Apple logo 居左，链接居中，搜索和购物袋图标居右。"
- "创建交替区块布局：第一个区块黑色背景配白色文字和居中产品图片，第二个区块 #f5f5f7 背景配 #1d1d1f 文字。每个区块接近全视口高度，含 56px 标题和下方两个胶囊 CTA。"
- "设计一个'了解更多'链接：浅色背景上文字颜色 #0066cc 或深色背景上 #2997ff，14px Inter，悬停时显示下划线。文字后包含右箭头字符（>）。用 980px 圆角的容器包裹，作为独立 CTA 使用时呈胶囊形状。"
### 迭代指南
1. 所有交互元素使用 Apple 蓝（`#0071e3`）——不使用其他强调色
2. 区块背景交替使用：黑色用于沉浸式场景，`#f5f5f7` 用于信息展示场景
3. 排版光学尺寸：20px 及以上使用 Inter Display，以下使用 Inter——绝不混用
4. 所有尺寸下使用负字间距：56px 时 -0.28px，17px 时 -0.374px，14px 时 -0.224px，12px 时 -0.12px
5. 导航毛玻璃效果（半透明深色 + 模糊）是不可妥协的——它定义了 Apple 的网页体验
6. 产品始终出现在纯色背景上——主视觉模块中绝不使用渐变、纹理或生活方式背景
7. 阴影极其罕见且始终柔和：`3px 5px 30px 透明度 0.22` 或完全不使用
8. 胶囊 CTA 使用 980px 圆角——这创造了 Apple 标志性的"看起来像胶囊的圆角矩形"形状
---
**版本历史**:
- v1.0.0 (2026-04-19): 初始化 ISOS 模板
- v4.1.0 (2026-04-16): 字体体系跨平台调整 — SF Pro Display/Text → Inter Display/Inter + Noto Sans SC + JetBrains Mono；§3 字体族/层级体系/设计原则全面重写；§1/§4/§5/§7/§9 字体引用同步更新
- v4.0.0 (2026-04-14): 初始创建
docs/设计-UI-主界面.md
+52
View File
@@ -0,0 +1,52 @@
# UI 设计文档：主界面
**文档版本**: 1.0.0
**最后更新**: 2026-04-19
**所属模块**: [05-设计-UI.md](./05-设计-UI.md) → 主界面
**设计系统**: Apple 风格（详见 `./设计-Apple风格.md`）
> 本文档为 `05-设计-UI.md` 的拆分子文件，设计系统摘要和附录见主文件。
---
## 主界面
<!-- 描述主界面布局方式 -->
### <!-- N --> 主布局
**路径**: `/`
**入口**: <!-- 入口描述 -->
#### 线框图
```
<!-- 粘贴主布局线框图 -->
```
#### 设计规范
| 元素 | 规范 | 设计-Apple风格.md 参考 |
|------|------|---------------|
| <!-- 元素 --> | <!-- 规范 --> | <!-- 参考 --> |
#### 状态说明
- 默认状态: <!-- 说明 -->
- <!-- 其他状态 -->: <!-- 说明 -->
#### 交互说明
- <!-- 交互1 -->
- <!-- 交互2 -->
---
### <!-- N+1 --> <!-- 界面名称 -->
<!-- 按以上模板添加每个界面 -->
---
**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板
docs/设计-UI-状态组件.md
+44
View File
@@ -0,0 +1,44 @@
# UI 设计文档：状态组件
**文档版本**: 1.0.0
**最后更新**: 2026-04-19
**所属模块**: [05-设计-UI.md](./05-设计-UI.md) → 状态组件
**设计系统**: Apple 风格（详见 `./设计-Apple风格.md`）
> 本文档为 `05-设计-UI.md` 的拆分子文件，设计系统摘要和附录见主文件。
---
## 状态组件
### <!-- N --> <!-- 组件名称 -->
**位置**: <!-- 位置 -->
**用途**: <!-- 用途 -->
#### 线框图
```
<!-- 粘贴组件线框图 -->
```
#### 设计规范
| 状态 | 样式 | 动画 |
|------|------|------|
| <!-- 状态1 --> | <!-- 样式 --> | <!-- 动画 --> |
#### 交互说明
- <!-- 交互1 -->
---
### <!-- N+1 --> <!-- 组件名称 -->
<!-- 按以上模板添加每个状态组件 -->
---
**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板
docs/设计-UX-交互模式.md
+48
View File
@@ -0,0 +1,48 @@
# 用户体验设计 — 交互模式
**文档版本**: 1.0.0
**最后更新**: 2026-04-19
**所属模块**: [06-设计-UX.md](./06-设计-UX.md) → 交互模式
> 主索引: [06-设计-UX.md](./06-设计-UX.md) | 本文件: §3 交互模式说明
---
## 3. 交互模式说明
### <!-- N --> <!-- 交互名称 -->
**触发方式**: <!-- 触发方式 -->
**视觉反馈**:
- 默认状态: <!-- 说明 -->
- 悬停状态: <!-- 说明 -->
- 点击后: <!-- 说明 -->
**完成条件**:
- <!-- 条件1 -->
**超时处理**:
- <!-- 超时规则 -->
**错误处理**:
- <!-- 错误处理 -->
**状态图**:
```mermaid
stateDiagram-v2
[*] --> <!-- 初始状态 -->
<!-- 初始状态 --> --> <!-- 目标状态 -->: <!-- 触发条件 -->
```
---
### <!-- N+1 --> <!-- 交互名称 -->
<!-- 按以上模板添加每个交互模式 -->
---
**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板
docs/设计-UX-操作流程.md
+43
View File
@@ -0,0 +1,43 @@
# 用户体验设计 — 操作流程
**文档版本**: 1.0.0
**最后更新**: 2026-04-19
**所属模块**: [06-设计-UX.md](./06-设计-UX.md) → 操作流程
> 主索引: [06-设计-UX.md](./06-设计-UX.md) | 本文件: §4 操作流程图
---
## 职责边界
本文件专注于**系统决策流程**：分支条件、错误处理路径、状态转换逻辑。
用户侧的**步骤描述、系统响应文案、帮助提示**见 [用户旅程](./设计-UX-用户旅程.md)（§2）。两份文档描述相同场景的不同维度，本文件不重复用户旅程的内容。
---
## 4. 操作流程图
### <!-- N --> <!-- 流程名称 -->
> 用户侧步骤描述见 [§2 对应用户旅程](./设计-UX-用户旅程.md)。
```mermaid
flowchart TD
A[<!-- 起点 -->] --> B{<!-- 判断条件 -->}
B -->|成功| C[<!-- 成功路径 -->]
B -->|失败| D[<!-- 错误处理 -->]
D --> E[<!-- 重试或退出 -->]
C --> F[<!-- 下一步 -->]
```
---
### <!-- N+1 --> <!-- 流程名称 -->
<!-- 按以上模板添加每个操作流程 -->
---
**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板
docs/设计-UX-无障碍与响应式.md
+108
View File
@@ -0,0 +1,108 @@
# 用户体验设计 — 无障碍与响应式
**文档版本**: 1.0.0
**最后更新**: 2026-04-19
**所属模块**: [06-设计-UX.md](./06-设计-UX.md) → 无障碍与响应式
> 主索引: [06-设计-UX.md](./06-设计-UX.md) | 本文件: §7 无障碍设计 + §8 响应式行为
---
## 7. 无障碍设计
### 7.1 键盘导航
**Tab 键导航顺序**：
1. <!-- 页面1 焦点顺序 -->
2. <!-- 页面2 焦点顺序 -->
**焦点管理**：
- 对话框打开时自动聚焦第一个输入框
- 对话框关闭时返回触发元素
- Toast 消息不获取焦点
---
### 7.2 焦点可见性
**焦点环样式**：
- 颜色：<!-- 色值 -->
- 宽度：2px
- 样式：实线（solid）
- 偏移：2px（outline-offset）
---
### 7.3 ARIA 标签
**关键元素 ARIA 标签**：
```html
<!-- <!-- 表单示例 --> -->
<form role="form" aria-label="<!-- 表单名称 -->">
<input aria-label="<!-- 字段名称 -->" aria-required="true">
</form>
<!-- <!-- 列表示例 --> -->
<ul role="listbox" aria-label="<!-- 列表名称 -->">
<li role="option"><!-- 条目 --></li>
</ul>
<!-- Toast 消息 -->
<div role="status" aria-live="polite" aria-atomic="true"><!-- 消息内容 --></div>
```
---
### 7.4 屏幕阅读器公告
**关键事件公告**：
1. <!-- 事件1公告文案 -->
2. <!-- 事件2公告文案 -->
---
### 7.5 色彩对比度
**WCAG AA 标准**：
- 正文文字：对比度 >= 4.5:1
- 大号文字（24px+）：对比度 >= 3:1
- 图标和图形：对比度 >= 3:1
---
### 7.6 高对比度模式
**支持方式**：
- 检测系统高对比度设置
- 自动切换到高对比度主题
- 增强边框和轮廓
---
## 8. 响应式行为
### 8.1 窗口大小调整
**最小窗口**: <!-- 最小宽高 -->
**窗口尺寸行为**：
| 宽度 | 布局变化 |
|------|----------|
| >= <!-- 宽度 --> | <!-- 说明 --> |
| <!-- 范围 --> | <!-- 说明 --> |
| < <!-- 宽度 --> | <!-- 说明 --> |
---
### 8.2 <!-- 响应式组件 -->
<!-- 按需要添加响应式布局说明 -->
---
**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板
docs/设计-UX-用户旅程.md
+49
View File
@@ -0,0 +1,49 @@
# 用户体验设计 — 用户旅程
**文档版本**: 1.0.0
**最后更新**: 2026-04-19
**所属模块**: [06-设计-UX.md](./06-设计-UX.md) → 用户旅程
> 主索引: [06-设计-UX.md](./06-设计-UX.md) | 本文件: §2 核心用户旅程
---
## 2. 核心用户旅程
### <!-- N --> <!-- 旅程名称 -->
**描述**: <!-- 旅程描述 -->
**前置条件**:
- <!-- 前置条件1 -->
- <!-- 前置条件2 -->
**步骤分解**:
| 步骤 | 用户操作 | 系统响应 | 下一步选项 | 帮助提示 |
|------|----------|----------|------------|----------|
| 1 | <!-- 操作 --> | <!-- 响应 --> | <!-- 下一步 --> | <!-- 提示 --> |
**成功标准**:
- <!-- 标准1 -->
- <!-- 标准2 -->
**异常分支**:
```mermaid
flowchart TD
A[<!-- 起点 -->] --> B{<!-- 判断条件 -->}
B -->|成功| C[<!-- 成功路径 -->]
B -->|失败| D[<!-- 错误处理 -->]
```
---
### <!-- N+1 --> <!-- 旅程名称 -->
<!-- 按以上模板添加每个用户旅程 -->
---
**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板
docs/设计-UX-错误处理.md
+62
View File
@@ -0,0 +1,62 @@
# 用户体验设计 — 错误处理与反馈
**文档版本**: 1.0.0
**最后更新**: 2026-04-19
**所属模块**: [06-设计-UX.md](./06-设计-UX.md) → 错误处理与反馈
> 主索引: [06-设计-UX.md](./06-设计-UX.md) | 本文件: §5 错误处理与反馈
---
## 5. 错误处理与反馈
### 5.0 错误提示规范
所有错误提示必须遵循以下模板：
> **错误提示 = 问题描述 + 建议操作 + 帮助链接**
| 组成部分 | 说明 | 示例 |
|----------|------|------|
| 问题描述 | 简洁明确地说明发生了什么 | <!-- 示例 --> |
| 建议操作 | 用户可以采取的具体步骤 | <!-- 示例 --> |
| 帮助链接 | 指向详细说明（可选） | [了解更多 →] |
### 5.1 <!-- 错误类别 -->
| 错误场景 | 用户提示文案 | 恢复建议 | 自动处理 |
|----------|--------------|----------|----------|
| <!-- 场景 --> | <!-- 提示 --> | <!-- 建议 --> | <!-- 处理 --> |
---
### <!-- N --> Toast 提示样式
**成功提示**：
- 背景色：<!-- 色值 -->
- 图标：✓（对勾）
- 显示时长：2秒
- 位置：屏幕底部中央
**错误提示**：
- 背景色：<!-- 色值 -->
- 图标：!（感叹号）
- 显示时长：3秒
- 位置：屏幕底部中央
**警告提示**：
- 背景色：<!-- 色值 -->
- 图标：⚠（警告）
- 显示时长：3秒
- 位置：屏幕底部中央
**信息提示**：
- 背景色：<!-- 色值 -->
- 图标：i（信息）
- 显示时长：2秒
- 位置：屏幕底部中央
---
**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板
docs/运维-发布日志.md
+36
View File
@@ -0,0 +1,36 @@
# 发布日志
**文档版本**: 1.0.0
**最后更新**: 2026-04-19
---
## 版本历史
### v0.1.0 (开发中)
**状态**: 开发中
**范围**: <!-- 版本范围 -->
#### 新增
- <!-- 新增内容 -->
#### 待实现
- <!-- 待实现内容 -->
---
## 版本命名规范
- **主版本号（Major）**: 不兼容的架构变更
- **次版本号（Minor）**: 功能新增
- **修订号（Patch）**: Bug 修复
格式：`vMAJOR.MINOR.PATCH`，如 `v1.0.0`
---
**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板
docs/运维-安全审计.md
+86
View File
@@ -0,0 +1,86 @@
# 安全审计
**文档版本**: 1.0.0
**最后更新**: 2026-04-19
---
## 目录
1. [安全架构概览](#1-安全架构概览)
2. [安全规范审计](#2-安全规范审计)
3. [威胁模型](#3-威胁模型)
4. [安全策略](#4-安全策略)
5. [漏洞跟踪](#5-漏洞跟踪)
6. [审计记录](#6-审计记录)
---
## 1. 安全架构概览
### 1.1 核心安全原则
1. <!-- 安全原则1 -->
2. <!-- 安全原则2 -->
3. <!-- 安全原则3 -->
### 1.2 <!-- 安全技术规范 -->
| 场景 | 技术 | 参数 |
|------|------|------|
| <!-- 场景 --> | <!-- 技术 --> | <!-- 参数 --> |
---
## 2. 安全规范审计
### 2.1 <!-- 审计项 -->
> 待编写
---
## 3. 威胁模型
### 3.1 攻击面分析
> 待编写
### 3.2 已知风险
> 待编写
### 3.3 风险缓解措施
> 待编写
---
## 4. 安全策略
### 4.1 <!-- 策略项 -->
> 待编写
---
## 5. 漏洞跟踪
| 编号 | 描述 | 优先级 | 状态 | 发现日期 | 修复日期 |
|------|------|--------|------|----------|----------|
| | | | | | |
> 随开发进展逐步记录
---
## 6. 审计记录
| 日期 | 审计类型 | 范围 | 结果 | 审计人 |
|------|----------|------|------|--------|
| <!-- 日期 --> | <!-- 类型 --> | <!-- 范围 --> | <!-- 结果 --> | <!-- 审计人 --> |
---
**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板
docs/运维-性能基准.md
+51
View File
@@ -0,0 +1,51 @@
# 性能基准
**文档版本**: 1.0.0
**最后更新**: 2026-04-19
---
## 目录
1. [性能指标](#1-性能指标)
2. [<!-- 模块 -->性能](#2-模块性能)
3. [测试环境](#3-测试环境)
---
## 1. 性能指标
### 1.1 目标
| 指标 | 目标值 | 来源 |
|------|--------|------|
| <!-- 指标 --> | <!-- 目标 --> | <!-- 来源 --> |
### 1.2 实际基准
| 指标 | 目标值 | 实际值 | 测试日期 | 备注 |
|------|--------|--------|----------|------|
| | | | | |
---
## 2. <!-- 模块 -->性能
> 待编写
---
## 3. 测试环境
| 项目 | 配置 |
|------|------|
| 操作系统 | <!-- 配置 --> |
| CPU | 待记录 |
| 内存 | 待记录 |
| 存储 | 待记录 |
| <!-- 运行时 --> | <!-- 版本 --> |
---
**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板
docs/运维-故障排除.md
+72
View File
@@ -0,0 +1,72 @@
# 故障排除
**文档版本**: 1.0.0
**最后更新**: 2026-04-19
---
## 目录
1. [错误码对照表](#1-错误码对照表)
2. [安装与初始化](#2-安装与初始化)
3. [连接与网络](#3-连接与网络)
4. [<!-- 其他分类 -->](#4-其他分类)
5. [日志与诊断](#5-日志与诊断)
---
## 1. 错误码对照表
| 错误码 | 含义 | 建议操作 |
|--------|------|----------|
| <!-- 错误码 --> | <!-- 含义 --> | <!-- 操作 --> |
---
## 2. 安装与初始化
### 2.1 <!-- 问题标题 -->
> 待编写
---
## 3. 连接与网络
### 3.1 <!-- 问题标题 -->
> 待编写
---
## 4. <!-- 其他分类 -->
> 待编写
---
## 5. 日志与诊断
### 5.1 日志位置
> 待编写
### 5.2 日志级别说明
> 待编写
---
## 附录
### A. 错误提示规范
每个错误提示应包含：
1. **问题描述**: 清晰说明发生了什么
2. **建议操作**: 用户可以做什么
3. **帮助链接**: 指向本文档的具体章节
---
**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板
docs/运维-部署实施.md
+41
View File
@@ -0,0 +1,41 @@
# 部署实施
**文档版本**: 1.0.0
**最后更新**: 2026-04-19
---
## 目录
1. [部署架构](#1-部署架构)
2. [环境要求](#2-环境要求)
3. [部署步骤](#3-部署步骤)
4. [配置说明](#4-配置说明)
5. [验证清单](#5-验证清单)
---
## 1. 部署架构
> 待编写
## 2. 环境要求
> 待编写
## 3. 部署步骤
> 待编写
## 4. 配置说明
> 待编写
## 5. 验证清单
> 待编写
---
**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板