量潮健康云

产品定位

量潮健康云是健康管理领域的应用，面向个人、家庭、企业三类主体：

• 个人：相对全面的健康管理（身体 + 心理）
• 家庭：大病管理为主（重疾风险、病程跟踪、家庭协同照护）
• 企业：共同问题管理为主（如知识工作的过疲劳、职业健康与健康福利）

健康数据属高度敏感信息，数据安全是本产品的底线要求：加密、脱敏、访问控制与审计。

项目结构

qtcloud-health/
├── src/
│   ├── server/           # 后端服务（Go）
│   ├── python_sdk/       # Python 工具箱
│   └── studio/           # 前端 Flutter 应用
├── tests/                # 测试fixtures和数据
├── docs/
│   └── dev-guide/        # 开发指南（BRD/PRD/IXD/ADD/QA）
└── scripts/              # 项目初始化脚本

当前阶段：企业后台壳

• 客户端（src/studio）为企业后台壳：常驻侧边导航 + 企业后台概览占位（企业健康报表 / 租户与组织 / 员工心理健康管理，规划中，见 docs/dev-guide/add/enterprise-reporting.md）
• 个人前台已迁移：情绪日记、心理量表（PHQ-9 / GAD-7 / PSS-4 / Mini-IPIP / CBI）等个人功能已迁移至 qthealth（个人前台，含官方站点与部署流水线）
• 企业后台能力建设路线：provider（Go，src/provider）→ 脱敏聚合报表 → 租户与组织管理；基础设施见 manifests/terraform/

快速开始

前置要求

• Go >= 1.22（后端服务）
• Python >= 3.12 + UV（仅 Python 工具箱）
• Flutter >= 3.0（仅 Studio）

项目初始化

使用顶层的初始化脚本来设置开发环境：

# 初始化所有项目
./scripts/setup.sh all

# 或者单独初始化某个项目
./scripts/setup.sh server
./scripts/setup.sh python_sdk
./scripts/setup.sh studio

常用命令

Server（后端服务，Go）

cd src/server

# 安装依赖
go mod tidy

# 运行测试
go test ./...
go test -v ./...  # 详细输出

# 启动开发服务器
go run ./cmd/api

# 添加依赖
go get <package>

Python SDK

cd src/python_sdk

# 安装依赖
uv sync --dev

# 运行测试
uv run pytest
uv run pytest -v

# 添加依赖
uv add <package>

Studio（前端应用）

cd src/studio

# 安装依赖
flutter pub get

# 运行应用
flutter run

# 运行测试
flutter test

# 添加依赖
flutter pub add <package>

开发工作流

1. 克隆仓库

   git clone <repository-url>
   cd qtcloud-health

2. 初始化环境

   ./scripts/setup.sh all

3. 启动开发服务器

   # Server
   cd src/server
   go run ./cmd/api
   
   # Studio
   cd src/studio
   flutter run

4. 运行测试

   # Server
   go test ./...
   
   # Python SDK
   cd src/python_sdk
   uv run pytest
   
   # Studio
   flutter test

发布与上线

按 qtcloud-secret 的方法发布并上线到 https://health.cloud.quanttide.com（网站名「量潮健康云」）：

# 1. 发布（版本以 pubspec.yaml + CHANGELOG.md 为准，创建 tag → 推送 → GitHub Release）
qtcloud-devops release publish -v studio/<version> -y

# 2. 部署：推送 studio/* tag 触发 .github/workflows/deploy-studio.yml
#    （flutter build web --release + ossutil 上传 OSS + 刷新 CDN）

• 基础设施：manifests/terraform/（OSS 静态站点桶 qtcloud-health-studio + CDN 域名 + DNS，阿里云，对齐 qtcloud-secret）
• HTTPS：acme.sh 单域名证书（Let's Encrypt，health.cloud.quanttide.com，90 天自动续期并重配 CDN）
• 当前已发布：studio/v0.1.0-alpha.1

文档

• 开发指南 - 文档体系入口（BRD/PRD/IXD/ADD/QA）

Git 提交规范

为保证提交历史的一致性和可读性，所有 Git 提交消息必须遵循 Conventional Commits 规范，格式如下：

<type>(<scope>): <description>

字段说明

• <type>: 提交类型

  • feat: 新功能(feature)
  • fix: 修复bug
  • docs: 文档(documentation)
  • style: 代码格式调整，不影响逻辑
  • refactor: 重构，既不修复bug也不添加功能
  • test: 测试相关
  • chore: 构建过程或辅助工具的变动
  • init: 初始化项目

• <scope>: 影响范围(可选)

  • server: 后端服务
  • studio: 前端Flutter应用
  • python_sdk: Python SDK
  • qtcloud-health: 整个项目
  • 其他特定模块名

• <description>: 简短描述

  • 使用祈使句、现在时态，例如"use"而非"used"或"uses"
  • 不要大写首字母
  • 不要以句号结尾

配置提交模板

为确保每次提交都遵循规范，请设置 Git 提交模板：

# 在项目根目录下执行
git config commit.template .gitmessage

示例

feat(server): 添加用户认证接口
docs(readme): 修正拼写错误
fix(dataset): 解决数据集查询的性能问题
chore: 更新构建脚本

License

Apache 2.0