ljwx-children/GITHUB-ISSUES-TRACKING.md

📊 GitHub Issues 任务跟踪

🎯 概述

已创建 6 个 GitHub Issues 用于可视化跟踪剩余开发任务。所有任务都可以在 GitHub Issues 和 GitHub Projects 看板中实时跟踪。

仓库地址： https://github.com/BrunoGaoSZ/ljwx-children

---

📋 任务清单

✅ 已完成任务（3 个）

任务	状态	说明
Database Migration	✅ 完成	Alembic 配置和初始迁移
Redis Integration	✅ 完成	Token blacklist 功能
Ollama AI Integration	✅ 完成	替换所有 mock AI/ML 实现

🚧 待完成任务（6 个）

Issue	标题	优先级	预估工时	GitHub 链接
#37	Complete test coverage: risk assessments endpoints	🔴 Critical	4-6h	Issue #37
#38	Complete test coverage: data collection endpoints	🟡 Low	4-6h	Issue #38
#39	Implement resource library endpoints	🟠 Medium	4-6h	Issue #39
#40	Implement communication endpoints	🟠 Medium	6-8h	Issue #40
#41	Implement analytics dashboard endpoints	🟡 Low-Medium	6-8h	Issue #41
#42	Deploy to OrbStack for local testing	🔴 High	4-6h	Issue #42

总预估工时： 28-40 小时

---

🔍 Issue 详情

Issue #37: 测试覆盖 - Risk Assessments API

目标： 为风险评估端点编写完整测试

范围：

• POST /risk-assessments - 创建风险评估
• GET /risk-assessments - 列出评估（分页、筛选）
• GET /risk-assessments/{id} - 获取单个评估

验收标准：

• 单元测试覆盖所有 3 个端点
• 集成测试（真实数据库）
• 测试覆盖率 >95%
• Mock Ollama 客户端
• 测试边界情况和错误处理

相关文件：

• backend/api/risk_assessments.py (480 行)
• tests/unit/test_api_risk_assessments.py (待创建)
• tests/integration/test_risk_flow.py (待创建)

---

Issue #38: 测试覆盖 - Data Collection API

目标： 为数据收集端点编写完整测试

范围：

• POST /data/voice - 上传语音文件
• POST /data/text - 提交文本数据

验收标准：

• 单元测试覆盖所有 2 个端点
• 测试文件上传（WAV/MP3/M4A）
• 测试文件验证（大小、格式）
• Mock Ollama 和 OSS
• 测试覆盖率 >95%

相关文件：

• backend/api/data.py (491 行)
• tests/unit/test_api_data.py (待创建)
• tests/integration/test_data_upload_flow.py (待创建)

---

Issue #39: 实现 Resource Library API

目标： 实现心理干预资源库功能

范围：

• POST /resources - 创建资源
• GET /resources - 列出资源（分页、筛选）
• GET /resources/{id} - 获取资源详情
• PUT /resources/{id} - 更新资源
• DELETE /resources/{id} - 删除资源（软删除）

数据库模型：

class Resource(Base):
    id: UUID
    title: str
    description: str
    type: str  # article/video/exercise/guide
    content_url: str
    target_age_group: str  # 6-9, 10-12, 13-15, 16-18
    tags: List[str]
    created_by_id: UUID
    view_count: int
    is_active: bool
    created_at: datetime
    updated_at: datetime

验收标准：

• 所有 5 个端点实现
• Alembic 迁移脚本（Expand 模式）
• SQLAlchemy 模型和关系
• 权限控制（psychologist, admin）
• 分页和筛选功能
• 测试覆盖率 >95%

---

Issue #40: 实现 Communication API

目标： 实现用户间消息通信功能

范围：

• POST /messages - 发送消息
• GET /messages - 列出消息（筛选未读）
• GET /messages/{id} - 获取消息详情
• GET /conversations - 列出会话
• GET /conversations/{id} - 获取会话详情
• POST /messages/{id}/read - 标记已读

数据库模型：

class Message(Base):
    id: UUID
    conversation_id: UUID
    sender_id: UUID
    recipient_id: UUID
    content: str
    message_type: str  # text/voice/image
    is_read: bool
    read_at: datetime
    created_at: datetime

class Conversation(Base):
    id: UUID
    participant_1_id: UUID
    participant_2_id: UUID
    last_message_id: UUID
    last_message_at: datetime

验收标准：

• 所有 6 个端点实现
• Alembic 迁移脚本
• 权限控制（发送者/接收者）
• 未读计数功能
• 自动创建会话
• 测试覆盖率 >95%

---

Issue #41: 实现 Analytics Dashboard API

目标： 实现数据分析和可视化端点

范围：

• GET /analytics/risk-trends - 风险趋势分析
• GET /analytics/emotion-distribution - 情绪分布统计
• GET /analytics/intervention-effectiveness - 干预效果评估
• GET /analytics/usage-stats - 系统使用统计
• GET /analytics/child-summary/{id} - 儿童档案汇总
• GET /analytics/high-risk-children - 高风险儿童列表

验收标准：

• 所有 6 个端点实现
• SQL 查询优化（使用索引）
• 日期范围筛选
• 权限控制（guardian, psychologist, admin）
• 数据聚合准确性
• 响应时间 <500ms
• 测试覆盖率 >90%

性能要求：

• 使用 SQLAlchemy func.count(), func.avg() 进行聚合
• 添加数据库索引：child_id, created_at, risk_category
• 考虑 Redis 缓存频繁访问的分析结果

---

Issue #42: OrbStack 本地部署

目标： 部署完整应用到 OrbStack Kubernetes 环境

范围：

• Docker 镜像构建
• Helm Chart 创建
• Kubernetes 资源配置
• 数据库设置（PostgreSQL）
• 可观测性集成（Prometheus + Loki + Tempo）
• 端到端测试

部署组件：

• Deployment (2 replicas)
• Service (ClusterIP, port 8000)
• Ingress (ljwx-children.local)
• ConfigMap (环境变量)
• Secret (敏感配置)
• ServiceMonitor (Prometheus 抓取)
• Init Container (Alembic 迁移)

验收标准：

• Helm chart 部署成功
• 所有 Pod 运行正常
• 健康检查端点响应
• 数据库迁移已应用
• API 可通过 Ingress 访问
• 能够注册用户和认证
• 能够上传数据和创建评估
• Ollama 集成正常工作
• Metrics 在 Prometheus 可见
• Logs 在 Loki 可见
• Traces 在 Tempo 可见
• Grafana Dashboard 显示数据

环境变量：

APP_ENV: development
LOG_LEVEL: INFO
OTEL_ENABLED: "true"
DATABASE_URL: postgresql+asyncpg://...
SECRET_KEY: <random-key>
REDIS_URL: redis://...
OLLAMA_BASE_URL: http://host.orbstack.internal:11434

---

📊 可视化跟踪方式

方式 1: GitHub Issues 列表

访问 Issues 页面查看所有任务：

https://github.com/BrunoGaoSZ/ljwx-children/issues

筛选器：

• 查看所有待办：is:open is:issue
• 查看高优先级：is:open is:issue label:priority/critical
• 查看测试任务：is:open is:issue label:category/testing

方式 2: GitHub Projects 看板

创建看板项目进行可视化管理：

# 1. 创建新项目（在 GitHub Web UI）
# https://github.com/BrunoGaoSZ/ljwx-children/projects

# 2. 添加看板视图，设置 3 列：
# - 📋 Todo (待办)
# - 🚧 In Progress (进行中)
# - ✅ Done (已完成)

# 3. 将 Issues #37-#42 添加到项目
gh project item-add <PROJECT_NUMBER> --owner BrunoGaoSZ --url https://github.com/BrunoGaoSZ/ljwx-children/issues/37
gh project item-add <PROJECT_NUMBER> --owner BrunoGaoSZ --url https://github.com/BrunoGaoSZ/ljwx-children/issues/38
gh project item-add <PROJECT_NUMBER> --owner BrunoGaoSZ --url https://github.com/BrunoGaoSZ/ljwx-children/issues/39
gh project item-add <PROJECT_NUMBER> --owner BrunoGaoSZ --url https://github.com/BrunoGaoSZ/ljwx-children/issues/40
gh project item-add <PROJECT_NUMBER> --owner BrunoGaoSZ --url https://github.com/BrunoGaoSZ/ljwx-children/issues/41
gh project item-add <PROJECT_NUMBER> --owner BrunoGaoSZ --url https://github.com/BrunoGaoSZ/ljwx-children/issues/42

方式 3: GitHub CLI 查看

使用命令行快速查看任务状态：

# 列出所有待办任务
gh issue list --repo BrunoGaoSZ/ljwx-children --state open

# 查看特定 issue
gh issue view 37 --repo BrunoGaoSZ/ljwx-children

# 关闭已完成任务
gh issue close 37 --repo BrunoGaoSZ/ljwx-children

# 添加评论
gh issue comment 37 --repo BrunoGaoSZ/ljwx-children --body "开始工作"

方式 4: Milestone 跟踪

创建 Milestone 将任务分组：

# 创建 Phase 2 Milestone
gh api repos/BrunoGaoSZ/ljwx-children/milestones -f title="Phase 2: Core Features" -f description="Implement core API endpoints and testing" -f due_on="2026-02-01T00:00:00Z"

# 将 issues 添加到 milestone
gh issue edit 37 --milestone "Phase 2: Core Features"
gh issue edit 38 --milestone "Phase 2: Core Features"
# ... 重复其他 issues

---

📈 进度跟踪

当前状态

指标	数值
总任务数	9 个
已完成	3 个 (33%)
进行中	0 个 (0%)
待开始	6 个 (67%)

进度图表

已完成 ████████████░░░░░░░░░░░░░░░░░░░░ 33%

建议开发顺序

根据依赖关系和优先级，建议按以下顺序完成：

1. Issue #37 - Risk Assessments 测试 (高优先级，核心功能)
2. Issue #38 - Data Collection 测试 (高优先级，核心功能)
3. Issue #42 - OrbStack 部署 (尽早验证部署流程)
4. Issue #39 - Resource Library API (独立功能)
5. Issue #40 - Communication API (独立功能)
6. Issue #41 - Analytics Dashboard (依赖数据积累)

---

🔄 工作流程

开始新任务

# 1. 在 GitHub 上将 issue 移到 "In Progress" 列
gh issue edit <NUMBER> --add-label "status/in-progress"

# 2. 创建功能分支
git checkout -b feature/issue-<NUMBER>-<description>

# 3. 开发完成后提交
git add .
git commit -m "feat: <description> (#<NUMBER>)"
git push origin feature/issue-<NUMBER>-<description>

# 4. 创建 Pull Request
gh pr create --title "Feature: <description>" --body "Closes #<NUMBER>"

# 5. PR 合并后自动关闭 issue

更新进度

# 添加进度评论
gh issue comment <NUMBER> --body "✅ 完成 API 实现
⏳ 正在编写测试
Progress: 70%"

# 更新标签
gh issue edit <NUMBER> --add-label "status/testing"

完成任务

# PR 描述中包含 "Closes #<NUMBER>" 或 "Fixes #<NUMBER>"
# PR 合并后 issue 自动关闭并移到 "Done" 列

---

📝 Issue 模板

Bug Report

**描述问题：**
清晰描述 bug 是什么。

**复现步骤：**
1. 执行 '...'
2. 点击 '...'
3. 查看错误

**预期行为：**
应该发生什么。

**实际行为：**
实际发生了什么。

**环境：**
- OS: macOS/Linux/Windows
- Python 版本: 3.11
- FastAPI 版本: 0.109.0

Feature Request

**功能描述：**
清晰描述想要的功能。

**使用场景：**
为什么需要这个功能？

**实现建议：**
如何实现这个功能？

**替代方案：**
考虑过哪些替代方案？

---

🎯 成功标准

项目被认为完成当：

• ✅ 所有 6 个 issues 关闭
• ✅ 测试覆盖率 >90%
• ✅ 所有 API 端点正常工作
• ✅ OrbStack 部署成功
• ✅ 可观测性完整（Metrics + Logs + Traces）
• ✅ 文档完整（API docs, README, 部署指南）
• ✅ 没有已知高优先级 bug

---

📞 联系方式

• GitHub: https://github.com/BrunoGaoSZ/ljwx-children
• Issues: https://github.com/BrunoGaoSZ/ljwx-children/issues
• 项目负责人: BrunoGaoSZ

---

最后更新： 2026-01-01 文档版本： 1.0.0