ljwx-health/CONTRIBUTING.md

贡献指南

感谢你对LJWX Health项目的关注！我们欢迎所有形式的贡献。

---

📋 目录

• 行为准则
• 如何贡献
• 开发流程
• 代码规范
• 提交规范
• 文档贡献

---

🤝 行为准则

参与本项目的所有人员应遵守以下原则：

• 尊重所有贡献者
• 保持专业和包容的态度
• 接受建设性的批评
• 关注项目整体利益

---

💡 如何贡献

报告Bug

提交Bug时请包含：

1. 问题描述: 清晰描述遇到的问题
2. 复现步骤: 详细的操作步骤
3. 预期行为: 应该发生什么
4. 实际行为: 实际发生了什么
5. 环境信息:
   • 操作系统及版本
   • Docker/K8s版本
   • LJWX版本
6. 日志输出: 相关错误日志
7. 截图: 如适用

模板: Bug Report

功能建议

提交功能建议时请包含：

1. 问题陈述: 这个功能解决什么问题
2. 建议方案: 你希望的实现方式
3. 替代方案: 是否考虑过其他方案
4. 影响范围: 哪些模块会受影响

模板: Feature Request

---

🔧 开发流程

1. Fork项目

# Fork项目到你的GitHub账号
# 然后clone到本地
git clone https://github.com/YOUR-USERNAME/ljwx-health.git
cd ljwx-health

# 添加上游仓库
git remote add upstream https://github.com/yourorg/ljwx-health.git

2. 创建分支

# 确保从最新的main分支创建
git checkout main
git pull upstream main

# 创建功能分支（遵循命名规范）
git checkout -b feature/data-flow-dashboard
git checkout -b fix/login-timeout
git checkout -b docs/update-deployment-guide

分支命名规范:

• feature/* - 新功能
• fix/* - Bug修复
• docs/* - 文档更新
• refactor/* - 代码重构
• test/* - 测试相关
• chore/* - 构建/工具相关

3. 开发与测试

# 开发前端
cd ljwx-admin
pnpm install
pnpm dev
pnpm lint
pnpm typecheck

# 开发后端
cd ljwx-boot
./run-local.sh
mvn test

# 开发大屏
cd ljwx-bigscreen/bigscreen
python run.py
pytest

重要检查:

• ✅ 代码通过所有单元测试
• ✅ 代码符合lint规范
• ✅ 类型检查无错误
• ✅ 本地环境验证通过

4. 提交代码

# 添加变更
git add .

# 提交（遵循提交规范）
git commit -m "feat(data-flow): 添加数据流监控Dashboard"

# 推送到你的fork
git push origin feature/data-flow-dashboard

5. 创建Pull Request

1. 访问你的fork页面
2. 点击 "New Pull Request"
3. 填写PR模板
4. 等待代码审查

---

📝 代码规范

后端代码 (Java)

必须遵守:

• PROMPT_BLUEPRINT.md - 工程蓝图强制约束
• OpenAPI-First开发，所有API必须有契约
• 仅使用DTO，禁止暴露Entity/Map
• 所有公开方法必须有JavaDoc注释

代码风格:

// ✅ 推荐
@Operation(summary = "获取用户列表", description = "分页查询用户列表")
@GetMapping("/list")
public Result<PageVO<UserVO>> list(
    @Parameter(description = "页码") @RequestParam Integer page,
    @Parameter(description = "每页数量") @RequestParam Integer size
) {
    // ...
}

// ❌ 不推荐
@GetMapping("/list")
public Object list(Map params) {
    // ...
}

OpenAPI契约检查:

cd ljwx-boot
./scripts/export-openapi.sh
./scripts/check-api-breaking-changes.sh

前端代码 (Vue3 + TypeScript)

代码风格:

// ✅ 推荐 - 使用组合式API
<script setup lang="ts">
import { ref, computed } from 'vue'

interface Props {
  userId: number
}

const props = defineProps<Props>()
const count = ref(0)
const doubleCount = computed(() => count.value * 2)
</script>

// ❌ 不推荐 - 避免选项式API（除非必要）
<script lang="ts">
export default {
  data() {
    return { count: 0 }
  }
}
</script>

类型安全:

• 所有组件props必须有类型定义
• API调用必须有明确的返回类型
• 避免使用any类型

Lint检查:

pnpm lint       # ESLint检查
pnpm typecheck  # TypeScript检查

Python代码 (ljwx-bigscreen)

代码风格 (PEP 8):

# ✅ 推荐
def calculate_health_score(
    user_id: int,
    data_type: str,
    date_range: Tuple[datetime, datetime]
) -> float:
    """计算健康评分
    
    Args:
        user_id: 用户ID
        data_type: 数据类型
        date_range: 时间范围
        
    Returns:
        健康评分（0-100）
    """
    # ...

# ❌ 不推荐
def calc(u, d, r):
    # ...

类型注解:

• Python 3.8+ 类型注解
• 所有公开函数必须有docstring

测试:

pytest tests/

---

📋 提交规范

Conventional Commits

格式: <type>(<scope>): <subject>

类型 (type):

• feat: 新功能
• fix: Bug修复
• docs: 文档更新
• style: 代码格式（不影响功能）
• refactor: 代码重构
• test: 测试相关
• chore: 构建/工具相关
• perf: 性能优化

范围 (scope): 影响的模块

• data-flow - 数据流
• alert - 告警系统
• geofence - 电子围栏
• admin - 前端管理
• boot - 后端API
• bigscreen - 监控大屏
• docs - 文档

示例:

feat(data-flow): 添加WebSocket实时推送
fix(alert): 修复多租户告警规则冲突
docs(deployment): 更新Kubernetes部署指南
refactor(bigscreen): 优化健康评分计算算法
test(api): 添加OpenAPI契约测试

Git提交消息

<type>(<scope>): <subject>

<body>

<footer>

示例:

feat(data-flow): 添加数据流监控Dashboard

- ECharts Sankey拓扑图
- WebSocket实时推送（3秒刷新）
- 6个关键指标统计
- Grafana仪表板集成

Closes #123

---

📚 文档贡献

文档结构

所有文档遵循新的目录结构：

docs/
├── 01-getting-started/   # 快速开始
├── 02-architecture/      # 架构设计
├── 03-deployment/        # 部署指南
├── 04-operations/        # 运维手册
├── 05-features/          # 功能文档
├── 06-development/       # 开发指南
├── 07-compliance/        # 工程规范
└── 08-reference/         # 参考资料

文档模板

功能文档模板:

# 功能名称

**状态**: ✅ 稳定 / 🔧 Beta / ⚠️ 实验性
**版本**: v1.0
**最后更新**: 2026-01-04

## 概述
[1-2段说明]

## 快速开始
[最简示例]

## 详细说明
[分章节展开]

## 配置参考
[配置项说明]

## 故障排查
[常见问题]

## 相关文档
- [链接1]
- [链接2]

文档命名规范

• ✅ 使用小写 + 连字符: quick-start-docker.md
• ❌ 避免大写: QUICK_START.md
• ❌ 避免驼峰: QuickStart.md
• ❌ 避免空格: quick start.md

文档更新流程

1. 创建/更新文档
2. 更新顶部的"最后更新"日期
3. 更新 CHANGELOG.md
4. 如果是新功能，更新 docs/README.md 索引
5. 提交PR

---

🔍 代码审查

审查清单

功能性:

• 代码实现符合需求
• 边界条件处理正确
• 错误处理完善

质量:

• 代码可读性好
• 无重复代码
• 变量命名清晰

测试:

• 单元测试覆盖核心逻辑
• 集成测试通过
• 边界测试完整

安全:

• 无SQL注入风险
• 无XSS漏洞
• 敏感数据加密

合规:

• 符合PROMPT_BLUEPRINT.md
• OpenAPI契约已更新
• 文档已更新

---

❓ 常见问题

Q: 如何同步上游更新？

git checkout main
git fetch upstream
git merge upstream/main
git push origin main

Q: 如何处理合并冲突？

# 拉取最新代码
git fetch upstream
git rebase upstream/main

# 解决冲突
# 编辑冲突文件
git add .
git rebase --continue

Q: 如何修改已提交的commit？

# 修改最后一次commit
git commit --amend

# 修改多个commit
git rebase -i HEAD~3

---

📞 获取帮助

• 技术问题: GitHub Discussions
• Bug报告: GitHub Issues
• 实时交流: [Discord/Slack]
• 邮件联系: [email protected]

---

🎉 贡献者

感谢所有贡献者！

查看完整贡献者列表: Contributors

---

再次感谢你的贡献！ ❤️