feat(p1): complete P1 foundation stage
- monorepo: pnpm workspace + go.work + pyproject.toml + commitlint/husky - infra: docker-compose (minimal + full profiles) + init-sql + prometheus - arch-scan: multi-language scanner skeleton (TS/Go/Python/Proto) - shared-proto: buf v2 + classes.proto (ClassService CRUD contract) - api-gateway: Go/Gin + JWT HS256 auth + reverse proxy + request ID - classes: NestJS golden template (error system + observability + middleware + CRUD + tests) - teacher-portal: Next.js + paper-feel UI design system - CI/CD: 4 workflows (go/ts/py/proto) - docs: migration guide + project_rules + coding-standards + git-workflow + ui-design-system + 004 + 9 module READMEs + known-issues + spec/plan migration + roadmap
This commit is contained in:
SpecialX
28
docs/architecture/roadmap/README.md
Normal file
28
docs/architecture/roadmap/README.md
Normal file
@@ -0,0 +1,28 @@
|
||||
# 路线图索引
|
||||
|
||||
> 本目录存放项目长远规划，与架构事实（004）分离。
|
||||
|
||||
## 文档清单
|
||||
|
||||
| 文档 | 用途 |
|
||||
|------|------|
|
||||
| [tech-debt.md](./tech-debt.md) | 技术债清单（按 P0/P1/P2 优先级 + 已解决项） |
|
||||
| [pending-features.md](./pending-features.md) | 待开发功能路线图（6 阶段：P1 地基 → P6 硬化） |
|
||||
|
||||
## 6 阶段路线图总览
|
||||
|
||||
| 阶段 | 周期 | 核心交付 | 退出标准 |
|
||||
|------|------|----------|----------|
|
||||
| **P1 地基** | M1-M3 | 仓库骨架 + Docker 全量 infra + API Gateway + 契约层 + CI/CD + 文档体系 + classes 黄金模板 | classes 域 CRUD 端到端跑通 + 全横切关注点落地 + 30 分钟可复制新服务 |
|
||||
| **P2 身份** | M4-M6 | IAM 服务 + Teacher BFF(GraphQL) + 微前端骨架 | 教师可登录并看到空白 Dashboard |
|
||||
| **P3 核心教学** | M7-M10 | CoreEdu 服务 + Outbox 模式 + 考试/作业/成绩域 | 教师创建考试→学生作答→教师批改→成绩统计 全链路 |
|
||||
| **P4 内容分析** | M11-M13 | Content 服务(Neo4j) + DataAna(Python+CH) + CDC 链路 | 知识图谱查询 + 学情诊断宽表 5s 内返回 |
|
||||
| **P5 沟通AI** | M14-M16 | Msg 服务 + Push Gateway + AI 网关 + ES 题库检索 | 全校广播推送 + AI 辅助出题 + 题库检索 < 200ms |
|
||||
| **P6 硬化** | M17-M18 | Service Mesh + 全链路可观测 + 生产硬化 | 单服务可独立扩缩容 + 99.9% 可用性 |
|
||||
|
||||
## 维护规则
|
||||
|
||||
- 规划实现后从本目录删除，迁入 004 架构事实或 git 历史
|
||||
- 不含架构事实，不含经验（经验查 [../troubleshooting/known-issues.md](../troubleshooting/known-issues.md)）
|
||||
- 每阶段完成后打 tag：`v0.1.0-p1`、`v0.2.0-p2`...
|
||||
- 发现的新需求一律记入 `tech-debt.md`，不在当前阶段实现（YAGNI 原则）
|
||||
203
docs/architecture/roadmap/pending-features.md
Normal file
203
docs/architecture/roadmap/pending-features.md
Normal file
@@ -0,0 +1,203 @@
|
||||
# 待开发功能路线图
|
||||
|
||||
> 按 6 阶段组织的功能路线图，每阶段列出关键功能和交付物。
|
||||
> 阶段依赖：P1 → P2 → P3 → P4/P5（可并行但建议串行） → P6
|
||||
|
||||
---
|
||||
|
||||
## P1 地基阶段（M1-M3）
|
||||
|
||||
**目标**：搭建新仓库地基，多语言 monorepo + Docker 基础设施 + API Gateway + classes 黄金模板服务 + 文档体系 + CI/CD，端到端跑通 classes 域 CRUD。
|
||||
|
||||
**退出标准**：classes 域 CRUD 端到端跑通 + 全横切关注点落地 + 30 分钟可复制新服务。
|
||||
|
||||
### 关键功能
|
||||
|
||||
| 模块 | 功能 |
|
||||
|------|------|
|
||||
| 仓库骨架 | 多语言 monorepo（pnpm + go.work + pyproject）+ 大仓文档（LICENSE/CHANGELOG/CONTRIBUTING/SECURITY） |
|
||||
| Docker 基础设施 | 全量 docker-compose.yml（按 profiles 分阶段启用）+ 最小开发集（MySQL+Redis） |
|
||||
| API Gateway（Go） | 路由转发 + JWT HS256 校验 + 请求 ID 注入 + 健康检查 |
|
||||
| 契约层 | shared-proto 包 + classes.proto + buf lint/breaking + 三端代码生成配置 |
|
||||
| classes 黄金模板（TS/NestJS） | CRUD + 全横切关注点（错误处理/可观测/安全/契约/测试/文档/配置/i18n/CI/Dockerfile） |
|
||||
| arch.db 多语言扫描器 | TS 扫描（ts-morph）+ Go 扫描（正则骨架）+ Python 扫描（正则骨架）+ 查询工具 |
|
||||
| teacher-portal 测试页 | Next.js 单页验证 classes CRUD 端到端链路 |
|
||||
| CI/CD | 三语言 workflow（ci-go.yml / ci-ts.yml / ci-py.yml） |
|
||||
|
||||
### 交付物
|
||||
|
||||
- `docker-compose up -d` 全量容器健康
|
||||
- 浏览器创建班级 → MySQL 落库 → 列表显示
|
||||
- `buf lint` + `buf breaking` 通过，三端代码生成成功
|
||||
- 三语言 CI workflow 全绿（lint+test+build）
|
||||
- 单元 + 集成 + 契约 + E2E 四类测试齐备，覆盖率达标
|
||||
- 004 + 2 个模块 README + known-issues + project_rules 齐全
|
||||
- `npm run arch:query -- violations` 输出 0
|
||||
- 30 分钟内复制 classes 模板跑起新服务
|
||||
- 打 tag `v0.1.0-p1`
|
||||
|
||||
---
|
||||
|
||||
## P2 身份阶段（M4-M6）
|
||||
|
||||
**目标**：建 IAM 服务替换 P1 Gateway 内置鉴权；建首个完整 BFF（Teacher）与微前端骨架。
|
||||
|
||||
**退出标准**：教师登录 → 获取 JWT → 访问 teacher-portal → 侧边栏按 `viewports.L1` 渲染 → 看到空白 Dashboard。
|
||||
|
||||
### 关键功能
|
||||
|
||||
| 模块 | 功能 |
|
||||
|------|------|
|
||||
| IAM 服务（TS/NestJS） | 认证（登录/登出/JWT/2FA）+ RBAC（角色/权限/角色-权限 CRUD）+ 视口配置（4 层模型）+ DataScope 解析 + `getEffectivePermissions(userId)` |
|
||||
| MySQL schema | users / roles / permissions / role_permissions / role_viewports / parent_student_relations / class_subject_teachers |
|
||||
| JWT RS256 | IAM 私钥签发，Gateway/服务公钥校验，access 15min / refresh 7day |
|
||||
| 权限缓存 | `getEffectivePermissions` 结果 Redis 缓存 TTL 5 分钟，角色变更主动失效 |
|
||||
| Teacher BFF（TS/GraphQL） | GraphQL Yoga + DataLoader（防 N+1）+ 调 IAM 注入视口 |
|
||||
| teacher-portal（微前端宿主） | Module Federation + 路由骨架 + 侧边栏（viewports.L1 驱动）+ 登录页 |
|
||||
| API Gateway 升级 | 移除内置 JWT，改调 IAM 校验；路由表扩展 `/api/v1/iam/*` |
|
||||
|
||||
### 交付物
|
||||
|
||||
- IAM 服务完整实现认证 + RBAC + 视口 + DataScope
|
||||
- JWT RS256 非对称签名链路通畅
|
||||
- Teacher BFF GraphQL 接口可用
|
||||
- teacher-portal 微前端骨架 + 登录流程
|
||||
- 教师登录后侧边栏按角色渲染
|
||||
- 打 tag `v0.2.0-p2`
|
||||
|
||||
---
|
||||
|
||||
## P3 核心教学阶段（M7-M10）
|
||||
|
||||
**目标**：建 CoreEdu 服务实现考试全生命周期；落地 Outbox + Kafka 事件模式。
|
||||
|
||||
**退出标准**：教师创建考试 → 发布 → 学生作答提交 → 教师批改 → 事件发到 Kafka → 成绩统计更新 → 全链路可观测。
|
||||
|
||||
### 关键功能
|
||||
|
||||
| 模块 | 功能 |
|
||||
|------|------|
|
||||
| CoreEdu 服务（TS/NestJS） | 考试/作业/成绩域 CRUD + 批改业务编排 + Outbox 事件发布 |
|
||||
| MySQL schema | exams / exam_questions / homework_assignments / homework_submissions / homework_answers / grade_records / outbox_events |
|
||||
| Outbox 模式 | 业务事务同写 outbox_events 表；后台 relay worker 投递 Kafka |
|
||||
| Outbox relay（Go） | 独立服务 `services/outbox-relay/`，轻量高吞吐 |
|
||||
| Kafka | 启用业务 topic：exam.published / homework.graded / grade.recorded |
|
||||
| Teacher BFF 扩展 | 考试/作业/成绩的 GraphQL 查询与 mutation |
|
||||
| teacher-portal 扩展 | 考试创建/作业批改/成绩查看页面 |
|
||||
| student-portal（微前端） | 学生作答作业页面（Module Federation 子应用） |
|
||||
| Temporal | 引入但仅做 1 个工作流（考试发布编排：创建作业→通知）试点 |
|
||||
|
||||
### 交付物
|
||||
|
||||
- CoreEdu 服务考试全生命周期链路通畅
|
||||
- Outbox + Kafka 事件模式落地
|
||||
- Outbox relay worker 稳定投递
|
||||
- student-portal 微前端子应用接入
|
||||
- 全链路 trace 可追（OTel）
|
||||
- Outbox 模式回写黄金模板 README
|
||||
- 打 tag `v0.3.0-p3`
|
||||
|
||||
---
|
||||
|
||||
## P4 内容分析阶段（M11-M13）
|
||||
|
||||
**目标**：建 Content 服务（Neo4j 知识图谱）+ DataAna 服务（Python+ClickHouse）；落地 CDC 链路。
|
||||
|
||||
**退出标准**：教师查看知识图谱前置依赖（Neo4j 秒级返回）→ 学生查看学情诊断（ClickHouse 宽表 5s 内返回）→ CDC 链路延迟 < 5s。
|
||||
|
||||
### 关键功能
|
||||
|
||||
| 模块 | 功能 |
|
||||
|------|------|
|
||||
| Content 服务（TS/NestJS） | 教材/章节/知识点 CRUD（仅 CRUD，不实现检索）+ 知识图谱查询（Neo4j）+ 题库 CRUD（不实现检索） |
|
||||
| MySQL schema | textbooks / chapters / knowledge_points / questions |
|
||||
| Neo4j 数据 | 知识点前置依赖图（从 MySQL 同步） |
|
||||
| DataAna 服务（Python/FastAPI） | 学情诊断 API + 错题本 API + 消费 Kafka 构建宽表 |
|
||||
| ClickHouse | student_dashboard_view 宽表（DataAna 消费 Kafka 填充） |
|
||||
| CDC 链路 | Debezium 监听 MySQL binlog → Kafka（mysql.cdc.*）→ DataAna 消费写 ClickHouse |
|
||||
| BFF 扩展 | Teacher BFF 加知识图谱查询；Student BFF 加学情诊断查询（双轨读） |
|
||||
|
||||
### 交付物
|
||||
|
||||
- Content 服务知识图谱查询秒级返回
|
||||
- DataAna 学情诊断宽表 5s 内返回
|
||||
- CDC 链路延迟 < 5s
|
||||
- Neo4j 双写避免（消费事件同步）
|
||||
- 双轨读策略落地（实时查主库 + 聚合查宽表）
|
||||
- CDC 模式回写黄金模板 README
|
||||
- 打 tag `v0.4.0-p4`
|
||||
|
||||
---
|
||||
|
||||
## P5 沟通与 AI 阶段（M14-M16）
|
||||
|
||||
**目标**：建 Msg 服务 + Push Gateway + AI 网关；全文检索迁 ES。
|
||||
|
||||
**退出标准**：教师发广播通知 → 全在线学生实时收到（Push Gateway）→ AI 辅助出题流式返回 → 题库全文检索 < 200ms。
|
||||
|
||||
### 关键功能
|
||||
|
||||
| 模块 | 功能 |
|
||||
|------|------|
|
||||
| Msg 服务（TS/NestJS） | 会话/消息 CRUD + 调 Push Gateway 推送 + 通知偏好 |
|
||||
| Push Gateway（Go） | WebSocket 长连接管理 + 消费 Kafka 广播 + Redis PubSub 跨实例同步 |
|
||||
| AI 网关（Python/FastAPI） | LLM Provider 适配（OpenAI/Anthropic）+ Prompt 模板管理 + 流式 SSE + 用量计费 |
|
||||
| Elasticsearch | 题库全文检索（从 MySQL 同步）+ 全局搜索 API |
|
||||
| Notifications 模块 | 多渠道（站内/SMS/邮件/微信），沿用旧项目 dispatcher 模式 |
|
||||
| BFF/前端扩展 | Teacher BFF 加 AI 辅助出题 mutation；teacher-portal 加 SSE 流式 AI 对话 |
|
||||
|
||||
### 交付物
|
||||
|
||||
- Msg 服务会话/消息 CRUD + 推送链路
|
||||
- Push Gateway 单节点支撑 10w+ 连接
|
||||
- AI 网关流式 SSE 三层透传（AI → BFF → 前端）
|
||||
- ES 题库全文检索 < 200ms
|
||||
- 全校广播推送实时到达
|
||||
- 长连接模式回写黄金模板 README
|
||||
- 打 tag `v0.5.0-p5`
|
||||
|
||||
---
|
||||
|
||||
## P6 硬化阶段（M17-M18）
|
||||
|
||||
**目标**：生产硬化，达到可部署状态。
|
||||
|
||||
**退出标准**：单服务可独立扩缩容（HPA 生效）→ 全链路 trace 可追 → 模拟单服务宕机不影响核心链路 → 99.9% 可用性压测通过。
|
||||
|
||||
### 关键功能
|
||||
|
||||
| 模块 | 功能 |
|
||||
|------|------|
|
||||
| Service Mesh | Istio 服务网格（mTLS + 流量治理 + 可观测） |
|
||||
| 配置中心 | Consul 接入，配置热更新（限流阈值、功能开关） |
|
||||
| 全链路可观测 | OpenTelemetry + Jaeger（trace）+ Prometheus（metrics）+ Loki（logs） |
|
||||
| 限流/熔断 | Gateway 层限流（令牌桶）+ 服务间熔断（Envoy） |
|
||||
| 灰度发布 | Istio 流量拆分（金丝雀） |
|
||||
| K8s 部署 | 每服务 K8s manifest + HPA 自动扩缩容 |
|
||||
| 生产 CI/CD | Git tag 触发镜像构建 + 滚动部署 |
|
||||
| 灾备 | MySQL 主从 + Redis 哨兵 + Kafka 多副本 |
|
||||
|
||||
### 交付物
|
||||
|
||||
- Istio Service Mesh 全网格覆盖（mTLS）
|
||||
- 全链路 trace + Grafana 仪表盘 + Loki 日志查询
|
||||
- 限流熔断灰度发布可用
|
||||
- K8s HPA 自动扩缩容生效
|
||||
- 单服务宕机不影响核心链路
|
||||
- 99.9% 可用性压测通过
|
||||
- 降级方案：若时间紧张，Service Mesh 可降级为 K8s 原生 Service + Ingress
|
||||
- 打 tag `v1.0.0-p6`
|
||||
|
||||
---
|
||||
|
||||
## 跨阶段不变约束
|
||||
|
||||
每阶段都必须遵守：
|
||||
|
||||
- 契约先行（先改 proto，后写实现）
|
||||
- 文档同步（004 + 模块 README + arch.db + known-issues 实时更新）
|
||||
- CI 全绿才能合入 main
|
||||
- 每阶段末打 tag
|
||||
- Server/Handler 接口必须权限校验
|
||||
- 单文件行数遵循语言规范（TS ≤ 500/800/1000，Go ≤ 800，Python ≤ 800）
|
||||
- 阶段特有模式实现后回写黄金模板
|
||||
47
docs/architecture/roadmap/tech-debt.md
Normal file
47
docs/architecture/roadmap/tech-debt.md
Normal file
@@ -0,0 +1,47 @@
|
||||
# 技术债清单
|
||||
|
||||
> 记录已知的架构问题和技术债，按优先级排序。
|
||||
> 新项目从空白起步，随各阶段实施过程中发现的技术债记录于此。
|
||||
|
||||
## P0 - 高优先级（影响安全/性能/可维护性）
|
||||
|
||||
> 暂无。P1 实施过程中识别的高优先级技术债记录于此。
|
||||
|
||||
## P1 - 中优先级（影响开发效率/代码质量）
|
||||
|
||||
> 暂无。各阶段实施过程中识别的中优先级技术债记录于此。
|
||||
|
||||
## P2 - 低优先级（改进项）
|
||||
|
||||
> 暂无。各阶段实施过程中识别的低优先级改进项记录于此。
|
||||
|
||||
## 已解决项
|
||||
|
||||
> 暂无。已解决的技术债记录于此，含解决时间、方案、验证方式。
|
||||
|
||||
---
|
||||
|
||||
## 维护规则
|
||||
|
||||
### 优先级定义
|
||||
|
||||
| 优先级 | 含义 | 处理时机 |
|
||||
|--------|------|----------|
|
||||
| P0 | 影响安全/性能/可维护性 | 当前阶段必须解决，或立即修复 |
|
||||
| P1 | 影响开发效率/代码质量 | 计划在下一阶段或独立迭代解决 |
|
||||
| P2 | 改进项 | 时间允许时解决，不阻塞阶段推进 |
|
||||
|
||||
### 记录格式
|
||||
|
||||
每条技术债包含：
|
||||
- **编号**: `TD-{P0|P1|P2}-{序号}`，如 `TD-P0-001`
|
||||
- **状态**: 已识别 / 短期方案已实施 / 计划在某阶段实施 / 已解决
|
||||
- **影响**: 简述对系统的影响
|
||||
- **方案**: 短期方案 + 长期方案
|
||||
- **关联文件/模块**: 便于定位
|
||||
|
||||
### 同步规则
|
||||
|
||||
- 发现技术债时立即记录，不在当前阶段实现（YAGNI 原则）
|
||||
- 解决后移至"已解决项"分区，含解决时间与验证方式
|
||||
- 每阶段末回顾技术债清单，调整优先级
|
||||
Reference in New Issue
Block a user