Securo 开源个人财务管家开发者指南从提交第一个 PR 到测试驱动完整贡献路径【免费下载链接】securoOpen-source personal finance manager. Self-hosted, privacy-first.项目地址: https://gitcode.com/gh_mirrors/se/securoSecuro 是一个自托管、隐私优先的开源个人财务管理工具支持多账户、预算、规则引擎、银行同步与报表分析。本文带你走通贡献 Securo 的完整路径搭建开发环境、挑选首个任务、遵循测试驱动流程直到你的 PR 顺利被合并。先认识 Securo你将要贡献的项目Securo 让你把完整的财务数据握在自己手里——账户余额、支出习惯、资产增值、储蓄目标全部跑在你自己的基础设施上。启动后你会看到这样的仪表盘项目采用前后端分离的 monorepo 结构技术栈一目了然层技术栈后端FastAPI SQLAlchemy Alembic CeleryPython 3.11前端React TypeScript Vite Tailwind CSS数据库 / 队列PostgreSQL / Redis Celery核心目录速览backend/app/— API 路由、数据模型、业务服务与任务backend/alembic/versions/— 数据库迁移脚本90 个严格按编号链式串联backend/tests/— 190 个后端测试文件frontend/src/— React 页面、组件、Hooks 与库函数docs/— 设计文档与 PR 截图归档第一步3 条命令搭好本地开发环境克隆仓库并在本地拉起完整技术栈含 PostgreSQL、Redis、前后端git clone https://gitcode.com/gh_mirrors/se/securo cd securo docker compose up --build打开http://localhost:3000创建一个账户Securo 就已经跑起来了。官方建议用 mise 管理工具链仓库根目录与backend/、frontend/各有mise.toml任务定义一条mise backend:test就能跑完后端测试。 环境装好后先完整跑一遍测试见下文确认基线是绿的再开始改代码。第二步如何挑选第一个贡献任务官方贡献指南 CONTRIBUTING.md 给出了清晰建议从 Issue 出发浏览标记为good first issue或help wanted的问题选一个边界清晰的来。小改动免谈小 bug 修复、文档改进、翻译更新英文 葡萄牙语永远欢迎直接开 PR 即可。先在 Issue 里留言认领避免两个人做同一件事。改动核心机制前先沟通涉及账户、交易、预算、规则引擎、工作区、银行同步等核心逻辑比如规则引擎这类自动分类系统建议先提功能请求或到社区讨论确认方向一致再动手。规则引擎页面长这样——它就是典型的核心机制之一关于 AI 辅助开发项目明确欢迎使用 AI 写代码但原则是我们审查的是你不是 AI——方案要能自圆其说、质量要对齐现有代码、改动范围要严格匹配 Issue 要求合并后出问题也由你负责。用 AI 没问题别当甩手掌柜。第三步日常开发工作流分支 → 测试 → 提交标准流程如下全部来自 CONTRIBUTING.md从main切分支git checkout -b feature/your-feature后端测试与 CI 完全一致cd backend uv sync --all-extras # 首次运行按 uv.lock 精确还原依赖 uv run pytest前端检查cd frontend npm run lint npm test用清晰的提交信息提交仓库采用 Conventional Commits 风格feat: add CSV export for transactions fix: correct balance calculation on account closure docs: update setup instructions refactor: simplify rule engine matching推荐安装 pre-commit 钩子用prek或pip install pre-commit提交backend/*.py时自动执行ruff check和ty check配置读取自 backend/pyproject.toml本地与 CI 保持同一套标准。两个容易踩的坑改了pyproject.toml依赖后务必运行./scripts/lock.sh重新生成并一起提交uv.lockCI 会检查依赖漂移。新增数据库迁移时把编号接在当前最大编号之后如revision 077、down_revision 076并用python3 scripts/check_migration_chain.py验证链条仍是单线。CI 的 Migration Chain 任务会在你与main合并后检测编号冲突。第四步测试驱动开发——Securo 的质量底线Securo 的测试体系值得学习为新功能加测试是 PR 的硬性要求。后端内存 SQLite 异步 HTTP 客户端所有后端测试运行在内存 SQLite 上不依赖外部数据库。共享夹具定义在 backend/tests/conftest.py会话级建表、测试级事务回滚隔离client夹具基于 httpx 的ASGITransport直接调用 FastAPI 应用——所以 API 测试又快又稳。一个典型的预算 API 测试见 backend/tests/test_budgets_api.pyresponse await client.post( /api/budgets, json{category_id: str(cat.id), amount: 500, month: ...}, headersauth_headers, ) assert response.status_code 201想量化覆盖率时pytest --covapp --cov-reportterm-missing。前端Vitest Testing Library前端测试文件与源码同目录存放如month-stepper.test.tsx用npm test即vitest run执行。约定有三条详见 CONTRIBUTING.md统一通过/test/utils的renderWithProviders渲染组件它接好了 TanStack Query、路由和 i18n用/别名导入不用相对路径断言用户可见的东西渲染出的文案、被禁用的按钮、失败请求冒出的错误而不是内部状态。给 PR 配截图是 Securo 的传统涉及界面改动的 PR惯例是在docs/下归档截图。比如 SimpleFIN 银行重连功能的 PR 就留下了这样的截图方便评审者直观确认交互第五步提交能通过 CI 的 PR合并前自查清单✅ 一个 PR 只做一件事——聚焦单一功能或修复✅ PR 描述写清改了什么、为什么✅ 后端测试 前端 lint 全绿✅ 新功能附带测试✅ 新增用户可见文案时同步更新翻译EN PT-BR贡献即同意代码以 AGPL-3.0 许可 发布。常用路径速查资源路径贡献指南必读CONTRIBUTING.md后端依赖与工具链配置backend/pyproject.toml后端测试夹具backend/tests/conftest.py数据库迁移链backend/alembic/versions/迁移链校验脚本scripts/check_migration_chain.py前端脚本与依赖frontend/package.json前端测试配置frontend/vitest.config.ts设计与实现文档docs/许可协议LICENSE从一条docker compose up到一次被合并的贡献Securo 的流程没有任何神秘之处环境本地化、基线先验证、改动小而聚焦、测试自己跑过。挑一个good first issue今天就动手吧 【免费下载链接】securoOpen-source personal finance manager. Self-hosted, privacy-first.项目地址: https://gitcode.com/gh_mirrors/se/securo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考