项目规范指南

本文档定义了本项目的文档规范与代码规范，旨在确保代码的可维护性、可读性与团队协作效率。所有贡献者在开发过程中应遵循本规范。

代码规范的执行清单与语言分项规则请优先参考：docs/06-contributing/code-style.md。

文档规范

写作风格

技术文档应当像一篇好文章那样流畅自然。我们更倾向于使用分段的说明性文字，而非冰冷的条目堆砌。当需要表达因果关系或阐述设计决策时，完整的句子比编号列表更能传达清晰的逻辑。

例如，当解释一个模块的设计初衷时，不要写成：

支持多种嵌入模型
异步执行
缓存机制

而应该这样表述：

嵌入模块的设计目标是同时支持云端 API 与本地模型。考虑到嵌入计算可能阻塞主线程，我们采用了异步执行的方式，将计算任务放入线程池。为了减少重复请求的开销，模块内置了可选的缓存机制，对于相同文本的嵌入结果会直接从缓存返回。

这种写法更容易让新加入的开发者理解"为什么这样设计"，而不仅仅是"这里有什么功能"。

目录结构

项目文档按功能分区组织，以 docs/README.md 为入口，目录结构如下（与仓库实际一致）：

docs/
├── index.md                      # 文档站首页（目录入口）
├── README.md                     # 文档总览（内容页）
├── 01-getting-started/
├── 02-tutorials/
├── 03-how-to-guides/
│   └── deployment/
├── 04-reference/
│   ├── api/
│   ├── cli/
│   ├── config/
│   └── versioning/
├── 05-explanation/
│   ├── ai/
│   └── architecture/
├── 06-contributing/
├── 07-release-notes/
├── specs/
└── templates/

仓库结构（当前约定）

仓库以 code/ 为唯一可执行代码入口，其余顶层目录主要用于文档、测试与学术材料。

/
├── code/                         # 代码主目录
│   ├── backend/                  # Go 后端
│   ├── ai_service/               # Python AI 服务
│   ├── simulation/               # Python 仿真服务
│   ├── frontend-react/           # Web 前端（React + Vite）
│   ├── mobile/                   # 移动端（Expo，可选）
│   ├── shared/                   # 共享资源与配置
│   ├── deployment/               # 代码层部署配置
│   ├── scripts/                  # 构建与运维脚本
│   └── data/                      # 开发用数据样本
├── docs/                         # 技术文档
├── tests/                        # 仓库级测试与一致性校验
├── assets/                       # 素材与模板
├── academic/                     # 学术材料与论文
└── outputs/                      # 报告与输出产物

文档模板

每篇技术文档应当包含以下要素，但不必机械地按照固定格式填充。核心是让读者快速理解文档的目的、背景与使用方式。

开篇说明：用一两段话解释这个模块或功能解决什么问题，为什么需要它。这部分最重要，是读者决定是否继续阅读的依据。

核心概念：如果涉及领域特定的术语或设计模式，在这里做简要解释。帮助背景不同的读者建立共同的理解基础。

使用方式：通过清晰的代码示例展示如何使用该模块。示例应当是可运行的、有意义的，而不是过于简化的 foo() 和 bar()。

设计考量：解释关键的设计决策及其背后的权衡。这部分对于维护者尤其重要——当未来需要修改时，了解当初为什么这样做可以避免引入回归问题。

注意事项：已知的限制、边界条件、常见错误及其解决方法。

文档元信息

为了提高可追溯性与协作效率，建议所有正式文档在开头提供清晰的元信息块。元信息不必冗长，但应足够让读者知道“这是谁写的、适用于什么范围、何时更新”。

建议格式：

文档版本：1.0
负责人：姓名/角色
最后更新：YYYY-MM-DD
适用范围：例如“移动端 App / 后端网关 / AI 服务”
相关链接：如 API 文档、设计说明、Issue 追踪

图示与架构图规范

涉及系统结构、关键流程或跨模块协作的文档，必须包含至少一张架构图或流程图。图示优先使用 Mermaid（便于版本控制与评审），必要时提供 ASCII 备份图以确保在不支持 Mermaid 的环境仍可阅读。

最低要求：

分层架构图：展示客户端、服务层、数据层的边界与调用方向。
关键流程图：至少一个核心业务链路（如登录、AI 对话、作业提交）。

建议：

复杂模块采用子图分组，减少单图拥挤。
图示名称与正文保持一致，避免“图中叫 A，正文叫 B”的情况。

API 文档规范

API 文档必须做到“可实现、可验证、可协作”。除了接口列表，还应让任何接入方可以快速写出调用代码，并知道如何处理错误。

必备要素：

基础信息：基地址、版本、认证方式、限流策略。
接口列表：方法、路径、权限、说明、关键参数。
请求与响应示例：至少覆盖 1-2 个核心接口。
错误约定：错误码、错误信息结构、重试建议。

一致性要求：

文档与实际实现一致，更新 API 时必须同步文档。
客户端 SDK（如 code/mobile/src/api.ts）与 API 文档保持字段命名一致。

代码规范

详细代码规范已统一收敛到单一文档：docs/06-contributing/code-style.md。

本页只保留代码规范的高层原则，避免双份细则维护：

模块化：一处一责，接口边界清晰，避免跨层耦合。
显式配置：环境变量、权限、超时、错误码均可追踪。
兼容优先：任何对外 API 语义变化必须同步 OpenAPI、文档和测试。
最小改动：提交应聚焦需求本身，不引入无关重构。
可验证交付：合并前必须通过对应语言测试与文档构建检查。

执行清单请以 docs/06-contributing/code-style.md 为准。

Git 工作流规范

分支管理

项目采用简化的 Git Flow 模型。main 分支始终保持可部署状态，所有开发工作在特性分支上进行。

分支命名遵循统一格式：<类型>/<简短描述>。例如 feature/hybrid-retrieval 表示新功能，fix/citation-display 表示问题修复，docs/api-reference 表示文档更新。

提交信息

提交信息使用中文，格式为 <类型>: <描述>。类型包括：

feat: 新功能
fix: 问题修复
docs: 文档更新
refactor: 代码重构
test: 测试相关
chore: 构建或工具链变更

描述应当简洁明了，说明这次提交做了什么，而不是怎么做的。例如：

feat: 实现混合检索的 RRF 融合算法
fix: 修复引用标注序号不连续的问题
docs: 补充 GraphRAG 接口文档

代码评审

所有合入 main 分支的代码都需要通过代码评审。评审重点包括：

代码是否符合本规范
是否有足够的测试覆盖
是否有清晰的文档说明
是否有潜在的性能或安全问题

测试规范

测试分类

单元测试验证单个函数或类的行为。这类测试应当快速、独立、可重复。对于有外部依赖的代码，使用 mock 来隔离。

集成测试验证多个模块之间的协作。例如测试检索模块与向量存储的交互，或者测试 API 端点的完整请求处理流程。

端到端测试从用户视角验证完整的功能场景。这类测试较慢，主要用于关键路径的验收。

测试指标（建议阈值）

以下指标为建议值，可按环境与阶段调整：

范畴	指标	目标
覆盖率	核心模块行覆盖率	>=60%
稳定性	关键路径用例通过率	>=95%
性能	非 AI API p95 响应	<=300ms
性能	AI/仿真接口平均响应	<=10s
质量	引用正确率（GraphRAG）	>=85%
质量	工具调用正确率	>=90%

标准测试流程（必执行）

该流程用于合并到 main 或发布前的统一测试，确保上表关键指标都有对应的数据产出与结论。流程按仓库结构展开：先做仓库一致性，再做服务级单测/集成/端到端，最后完成性能与质量评测。仅文档类变更可以跳过服务级步骤，但仍需通过仓库一致性测试。

步骤 1：范围确认与测试矩阵。明确受影响的模块（code/backend、code/ai_service、code/simulation、code/frontend-react、tests/），列出需执行的测试类型与指标；若某模块缺少测试脚本，必须在评审中说明缺口并给出补齐计划。

步骤 2：仓库一致性测试。运行 tests/ 下的仓库级校验，确保目录结构、文档与迁移规则符合标准。

bash

cd tests
npm test

步骤 3：服务级单元测试与覆盖率。对 Go 与 Python 服务执行单测并产出覆盖率报告；覆盖率是关键指标之一，不得缺失。前端当前若未配置自动化测试，至少执行构建校验作为最低保障。

bash

cd code/backend
go test ./... -cover

cd code/ai_service
pytest -v --cov=app --cov-report=term-missing

cd code/simulation
pytest -v --cov=app --cov-report=term-missing

cd code/frontend-react
npm run build

步骤 4：集成测试。在 Docker Compose 或开发环境下验证服务间调用与数据库交互，覆盖鉴权、课程、作业、AI 调用与仿真链路。

步骤 5：端到端测试。运行关键路径脚本，当前至少包含引导式学习链路。

bash

./scripts/e2e_guided_learning.sh

步骤 6：性能与质量评测。对非 AI API p95、AI/仿真平均响应、引用正确率、工具调用正确率进行量化评测，并在测试报告中记录数据与结论。评测脚本统一放在 scripts/ 或服务内 tests/ 下，评测基线（样例集）需版本化管理。

步骤 7：门槛判定。关键指标未达标视为测试失败；如需调整阈值，必须在评审中说明原因并给出整改计划与时间表。

关键指标覆盖映射：

指标	归属步骤	采集方式	判定
核心模块行覆盖率	步骤 3	`go test -cover` / `pytest --cov`	>=60%
关键路径用例通过率	步骤 4-5	集成 + E2E 通过数/总数	>=95%
非 AI API p95 响应	步骤 6	k6/wrk 压测报告	<=300ms
AI/仿真接口平均响应	步骤 6	压测或采样统计	<=10s
引用正确率（GraphRAG）	步骤 6	标准评测集	>=85%
工具调用正确率	步骤 6	标准评测集	>=90%

测试文件组织（按语言区分）

不同语言按各自生态放置测试用例，仓库级测试统一放在 tests/。

code/ai_service/
├── app/
└── tests/
    ├── test_retrieve.py
    └── test_embedding.py

code/backend/
└── internal/
    └── service/
        └── course_test.go

code/frontend-react/
└── src/
    └── __tests__/
        └── task-registry.test.ts

tests/
└── overall-structure-validation.test.ts

测试用例设计

每个测试用例应当测试一个具体的行为，测试名称应当描述被测试的场景和预期结果。

python

class TestBuildRagContextHybrid:
    """混合检索的测试套件。"""
    
    async def test_returns_citations_with_source_info(self, mock_embedding, mock_store):
        """验证返回的引用包含来源信息。"""
        result = await build_rag_context_hybrid(context, index, embedding, store)
        assert len(result.citations) > 0
        assert all(c.source for c in result.citations)
    
    async def test_filters_by_user_id_for_student_role(self, mock_embedding, mock_store):
        """验证学生角色只能检索自己的提交。"""
        context = RetrievalContext(query="...", user_role="student", user_id="123")
        result = await build_rag_context_hybrid(context, index, embedding, store)
        assert all(c.user_id == "123" for c in result.sources)

调试指南

日志配置

开发环境下，将日志级别设置为 DEBUG 可以看到详细的执行过程。生产环境使用 INFO 级别。

python

import logging
logging.basicConfig(level=logging.DEBUG)

常见问题排查

检索结果为空。首先检查索引是否已正确加载（查看启动日志）。然后验证查询文本是否与索引内容匹配。可以降低相似度阈值或增加返回数量来观察是否有潜在匹配。

工具调用失败。检查工具定义的 schema 是否正确。查看 LLM 返回的原始响应，确认工具调用请求的格式是否符合预期。验证工具执行器是否正常工作。

嵌入请求超时。检查嵌入服务是否可达。考虑增加超时时间或添加重试机制。对于高并发场景，考虑使用批量嵌入接口减少请求次数。

项目规范指南 ​

文档规范 ​

写作风格 ​

目录结构 ​

仓库结构（当前约定） ​

文档模板 ​

文档元信息 ​

图示与架构图规范 ​

API 文档规范 ​

代码规范 ​

Git 工作流规范 ​

分支管理 ​

提交信息 ​

代码评审 ​

测试规范 ​

测试分类 ​

测试指标（建议阈值） ​

标准测试流程（必执行） ​

测试文件组织（按语言区分） ​

测试用例设计 ​

调试指南 ​

日志配置 ​

常见问题排查 ​

项目规范指南

文档规范

写作风格

目录结构

仓库结构（当前约定）

文档模板

文档元信息

图示与架构图规范

API 文档规范

代码规范

Git 工作流规范

分支管理

提交信息

代码评审

测试规范

测试分类

测试指标（建议阈值）

标准测试流程（必执行）

测试文件组织（按语言区分）

测试用例设计

调试指南

日志配置

常见问题排查