doccano模块开发与功能扩展协作指南

在开源社区中，高效的协作流程和清晰的开发规范是项目成功的关键。本文将系统介绍doccano项目的核心概念、环境配置、功能开发、协作规范及问题排查方法，帮助开发者快速参与到Xposed模块开发中，实现设备属性定制与功能扩展。

[理解核心概念] 掌握项目架构与模块设计

开发者须知：系统架构 overview

doccano采用前后端分离架构，通过Docker容器化部署，主要包含Web服务器、应用服务器、数据库服务器等核心组件。前端基于Vue.js和TypeScript构建用户界面，后端采用Django框架提供API服务，PostgreSQL作为数据存储，Celery处理异步任务，RabbitMQ作为消息代理。

核心模块解析

• 项目管理模块：负责项目的创建、配置与管理，核心代码位于projects/models.py
• 数据标注模块：提供多种标注功能，如序列标注、文本分类等，实现代码在examples/views/
• 自动标注模块：支持通过API集成外部模型实现自动标注，配置界面在configAutoLabeling/

实施步骤：模块间交互流程

1. 前端通过RESTful API与后端通信
2. 后端处理请求并与数据库交互
3. 异步任务通过Celery队列处理
4. 结果实时返回给前端展示

常见误区：新手常忽略Celery任务队列的配置，导致异步操作无法正常执行。需确保RabbitMQ服务正常运行，并在settings中正确配置Celery参数。

建议配图：模块间交互时序图

[准备开发环境] 配置本地开发与测试环境

开发者须知：环境依赖要求

• Python 3.8+
• Node.js 14+
• Docker及Docker Compose
• PostgreSQL 13+
• Git

实施步骤：环境搭建流程

1. 克隆项目代码

   git clone https://gitcode.com/gh_mirrors/doc/doccano
   

2. 配置后端环境

   cd doccano/backend
   poetry install
   cp .env.example .env
   # 编辑.env文件配置数据库连接
   poetry run python manage.py migrate
   

3. 配置前端环境

   cd ../frontend
   yarn install
   cp .env.example .env
   # 编辑.env文件配置API地址
   

4. 启动开发服务器

   # 后端
   cd backend
   poetry run python manage.py runserver
   
   # 前端
   cd frontend
   yarn dev
   

调试技巧：使用poetry run python manage.py shell进入Django shell，可快速测试模型方法和数据库查询。

建议配图：开发环境配置流程图

[开发核心功能] 实现项目创建与标注功能

开发者须知：项目创建流程

项目创建是doccano的基础功能，用户通过前端界面选择项目类型、设置参数，后端创建相应的数据库记录并初始化项目配置。

实施步骤：新增项目类型

1. 定义项目模型 在projects/models.py中创建新的项目类型类，继承自BaseProject

2. 添加前端界面 在ProjectTypeField.vue中添加新的项目类型选项

3. 实现API接口 在project.py中添加新类型的处理逻辑

4. 编写测试用例 在test_project.py中添加相应的测试

实施步骤：实现命名实体识别标注

1. 设计标注数据结构 在labels/models.py中定义实体类型和标注结果模型

2. 开发前端标注组件 在sequenceLabeling/中实现标注界面

3. 实现后端存储逻辑 在span.py中处理标注数据的保存与查询

常见误区：开发新功能时未考虑权限控制，导致未授权用户可访问敏感功能。需在permissions.py中添加相应的权限检查。

建议配图：实体标注数据流程图

[遵循协作规范] 代码提交与版本控制策略

开发者须知：分支管理策略

• main：稳定的生产环境代码
• develop：开发主分支，包含最新开发特性
• feature/xxx：新功能开发分支
• fix/xxx：bug修复分支
• release/x.y.z：版本发布分支

实施步骤：代码提交规范

提交信息格式：

[类型]: 简短描述

详细说明（可选）

类型包括：

• feat：新功能
• fix：bug修复
• refactor：代码重构
• docs：文档更新
• test：测试相关
• chore：构建/依赖管理

实施步骤：Pull Request流程

1. 从develop分支创建功能分支
2. 完成开发后，提交PR到develop分支
3. 至少一名团队成员代码审查通过
4. 所有CI检查通过
5. 合并到develop分支

最佳实践：每个PR应聚焦单一功能或修复，代码量控制在300行以内，便于审查和测试。

建议配图：协作流程示意图

[解决常见问题] 调试与问题排查指南

开发者须知：日志与调试工具

• 后端日志：logs/目录下
• 前端调试：浏览器开发者工具 + Vue Devtools
• API测试：使用Postman或curl测试API接口

实施步骤：自动标注功能故障排查

1. 检查配置 确认自动标注配置正确，特别是API端点和参数设置

2. 查看任务状态 通过Celery Flower监控任务执行情况：

   poetry run celery -A config flower
   

3. 检查日志 查看celery.log中的错误信息

实施步骤：数据库连接问题解决

1. 检查PostgreSQL服务是否运行
2. 验证.env文件中的数据库连接参数
3. 测试数据库连接：

   poetry run python -c "import psycopg2; psycopg2.connect(dbname='doccano', user='postgres', password='password', host='localhost')"
   

调试技巧：使用django-debug-toolbar查看SQL查询和性能信息，帮助定位数据库相关问题。

建议配图：问题排查流程图

社区贡献案例

案例一：自定义标注导出格式

某团队需要将标注数据导出为特定格式用于模型训练，开发者通过以下步骤实现：

1. 在data_export/pipeline/formatters.py中添加新的格式化类
2. 在apiDownloadFormatRepository.ts中添加格式选项
3. 编写测试用例并提交PR，一周内被合并到主分支

案例二：集成第三方NLP模型

开发者通过自动标注功能集成了Hugging Face模型：

1. 创建新的自动标注模板auto_labeling/pipeline/execution.py
2. 添加前端配置界面ConfigTemplate.vue
3. 提交文档更新，说明使用方法和限制条件

这些案例展示了社区贡献的多样性和价值，欢迎开发者提交更多创新功能和改进。

结语

本文详细介绍了doccano项目的开发流程，从核心概念到实际开发，再到协作规范和问题解决。通过遵循这些指南，开发者可以高效参与项目贡献，实现功能扩展和模块开发。开源社区的成长依赖于每一位开发者的贡献，期待更多创新想法和代码提交。