# 贡献指南

感谢你帮助改进 Ydisks 闲鱼助手。本项目主要服务中国用户，问题反馈、讨论、代码注释、文档和
Pull Request 描述均使用中文即可，不要求提供英文版本。

## 参与方式

你可以通过以下方式参与：

- 使用 Issue 模板报告可复现的问题；
- 提交功能建议，并说明实际使用场景；
- 提交 Pull Request 修复问题、补充测试、改进文档或完善部署流程；
- 在 Issue 中补充环境、版本和脱敏后的复现信息。

请先搜索已有 Issue，避免重复创建。涉及账号、订单、卡密、Cookie、Token、密码、API 密钥、
Webhook 或日志时，只能提供脱敏后的示例，不能上传真实数据。

## 提交 Issue

问题反馈至少应包含：

1. 使用的版本号、安装方式和操作系统；
2. 复现问题的最小步骤；
3. 预期结果与实际结果；
4. 与问题直接相关的脱敏日志或截图；
5. 是否仅在特定数据库、浏览器或账号状态下出现。

不要在公开 Issue 中粘贴完整 Cookie、Token、密码、二维码、数据库文件、卡密、收件人地址、
订单隐私或未公开的漏洞利用细节。安全问题请按照 [安全策略](SECURITY.md) 私下报告。

## 提交 Pull Request

Pull Request 应做到：

- 一个 Pull Request 聚焦一个问题或一个相互关联的改动；
- 标题和描述使用中文，说明背景、方案、行为变化和已知限制；
- 关联对应的 Issue；
- 为新增或修改的确定性行为补充聚焦测试；
- 同步更新 README、Wiki 源文件、OpenAPI 契约或其他受影响文档；
- 不提交真实账号数据、构建缓存、数据库文件、浏览器数据和密钥；
- 不通过关闭测试、扩大忽略范围或降低门禁来掩盖问题。

涉及登录、账号、浏览器、凭证、验证码、自动化或平台协议的修改，提交前必须阅读仓库中的
相关架构规则和 `docs/slider-captcha-frozen-spec.md`。除非明确授权，不得改变已冻结的滑块验证
行为、选择器、轨迹、时序、重试条件或浏览器调用顺序。

## 本地验证

后端或跨层改动至少运行：

```bash
make check
```

前端改动至少运行：

```bash
npm --prefix frontend run typecheck
npm --prefix frontend test
npm --prefix frontend run build
```

数据库访问或迁移改动应运行 SQLite 定向测试；有可用的 MySQL 和 PostgreSQL 环境时，再运行：

```bash
make test-multidb
```

浏览器相关改动应在本地可用的 Chromium 环境中运行相应测试。没有真实账号或外部平台授权时，
请使用本地夹具、`httptest`、模拟数据和本地浏览器页面，不要在测试中调用真实平台。

## 代码和文档要求

- Go、TypeScript 和 TSX 的新增或修改声明使用准确的中文注释；
- 保持 `app -> features -> shared` 的前端依赖方向；
- 新 API 先更新 `api/openapi.yaml`，再生成类型并补充真实契约测试；
- 敏感数据只能在必要的边界内使用，不能进入日志、错误响应或前端状态；
- 保持 SQLite、MySQL 和 PostgreSQL 的迁移与行为一致；
- 代码格式、测试、架构、API 契约和注释门禁必须通过。

## 评审和合并

维护者会根据正确性、安全性、兼容性、测试证据和文档完整性进行评审。维护者可能要求拆分
过大的改动、补充复现步骤、增加回归测试或调整实现边界。未经维护者确认，不要强行关闭他人
Issue，也不要在未验证平台行为时宣称已修复真实账号问题。

合并后的代码会由维护者安排版本发布。未经确认，不要把未发布的提交描述为稳定版本，也不要
向用户承诺闲鱼平台接口、风控策略或账号状态的长期兼容性。