expressgy
2518986557
✨ 新增功能设计文档： - M2基础用户系统数据库设计（12个核心表，RBAC权限模型） - M2基础用户系统接口设计（41个API接口，含排序功能） - 完整的项目需求文档和开发计划 📚 核心文档结构： - 数据库设计：支持树形结构、软删除、审计日志的完整用户权限体系 - 接口设计：包含认证、用户管理、角色权限、组织架构、字典标签等9大模块 - 排序功能：新增7个排序接口，支持拖拽和批量操作 - 项目规划：从MVP到完整生态的4阶段开发计划 🔧 技术栈确定： - 后端：Elysia + Bun.js + MySQL + Redis + Elasticsearch - 前端：Vue.js/React + TypeScript - 部署：Docker + Docker Compose - 测试：Vitest + 完整测试规范 📋 设计亮点： - 无外键约束设计，应用层维护数据完整性 - 树形结构支持（path、level字段优化查询） - 完整的权限继承机制和权限快照 - 支持root超级管理员和多级角色体系 - 标签系统和智能推荐功能 - 统一的响应格式和错误码规范 🎯 覆盖功能： - 用户认证与管理（注册、登录、权限控制） - RBAC角色权限体系（树形角色、权限继承） - 组织架构管理（多级组织、人员分配） - 数据字典与标签系统 - 完整的排序和数据导入导出功能 📈 文档规模： - 数据库设计：38KB，922行 - 接口设计：55KB，3024行 - 总计：约100KB的详细技术文档 🔄 配套更新： - 更新Elysia后端开发规范 - 完善健康检查控制器 - 统一项目代码规范和注释规范
217 lines
11 KiB
Markdown
217 lines
11 KiB
Markdown
# 星撰个人综合平台 - 软件开发概要设计
|
||
|
||
---
|
||
|
||
## 1. 引言
|
||
|
||
### 1.1. 文档目的
|
||
本概要设计文档旨在为"星撰"个人综合平台项目定义一个完整的软件开发生命周期（SDLC）框架。它将作为项目从规划、设计、实现到部署和维护的最高指导性文件，确保所有开发活动遵循标准化的软件工程最佳实践。
|
||
|
||
### 1.2. 项目概述
|
||
"星撰"是一个高度集成的个人数字化中枢，其核心功能、用户故事及非功能性需求已在《个人网站综合平台产品需求文档 (PRD)》中详细定义。本项目旨在将该PRD转化为一个稳定、可扩展、高质量的软件产品。
|
||
|
||
### 1.3. 范围
|
||
本文档覆盖范围包括：
|
||
- 项目开发模型的选定。
|
||
- 系统的高层体系结构设计。
|
||
- 各阶段（设计、开发、测试、部署）的规划和规范。
|
||
- 项目管理、风险控制和质量保证策略。
|
||
|
||
---
|
||
|
||
## 2. 项目规划与管理
|
||
|
||
### 2.1. 开发模型
|
||
本项目采用 **迭代式增量开发模型 (Iterative and Incremental Development)**。
|
||
- **迭代式**: 将开发过程划分为多个短周期的迭代，每个迭代都包含需求分析、设计、编码、测试的完整流程。
|
||
- **增量式**: 每个迭代都会产出一个可测试、可交付的软件增量。产品功能将分阶段（见PRD中的优先级规划）逐步构建和完善。
|
||
|
||
**优势**: 此模型能够快速交付核心功能（MVP），及时获取反馈，灵活应对需求变化，并有效控制项目风险。
|
||
|
||
### 2.2. 项目里程碑
|
||
项目将按照PRD中的优先级划分为四个主要里程碑（阶段）：
|
||
|
||
| 里程碑 | 名称 | 核心交付物 | 目标 |
|
||
|--------|--------------|------------------------------------------------------|------------------------------------|
|
||
| M1 | **核心基础 (MVP)** | 基础用户系统、笔记核心功能、基础博客发布、CI/CD流程建立 | 验证核心架构，跑通开发部署全流程 |
|
||
| M2 | **内容增强** | 完整博客系统、个人空间、基础工具、搜索引擎集成 | 完善内容生态，提升用户体验 |
|
||
| M3 | **高级功能** | 阅读管理、文件管理、AI功能集成、第三方平台同步 | 扩展平台能力，引入智能化 |
|
||
| M4 | **生态完善** | 移动端应用、浏览器插件、高级分析功能、性能深度优化 | 构建跨平台生态，实现长期稳定运营 |
|
||
|
||
### 2.3. 风险管理
|
||
| 风险类别 | 风险描述 | 可能性 | 影响 | 应对策略 |
|
||
|--------------|----------------------------------------|--------|------|------------------------------------------------------------------------|
|
||
| **技术风险** | 第三方API变更（如B站、QQ音乐） | 中 | 中 | 封装Adapter层，隔离变化；设计优雅降级机制。 |
|
||
| | 新技术引入（Bun/Elysia）的未知问题 | 低 | 中 | 保持对社区的关注，构建完善的测试体系以快速发现问题。 |
|
||
| **进度风险** | 个人项目时间投入不稳定 | 高 | 高 | 严格遵循任务清单，将大任务分解为小任务，利用碎片时间完成。 |
|
||
| **安全风险** | 个人敏感数据（密码、文件）泄露 | 中 | 高 | 强制加密存储；定期进行安全扫描；代码审查时关注安全漏洞。 |
|
||
|
||
---
|
||
|
||
## 3. 系统设计
|
||
|
||
### 3.1. 系统架构
|
||
系统采用分层、模块化的架构，实现前后端分离。
|
||
|
||
```mermaid
|
||
graph TD
|
||
subgraph "客户端 (Clients)"
|
||
WebApp[Web 应用 (Vue/React)]
|
||
BrowserExt[浏览器插件]
|
||
MobileApp[移动应用 (PWA/Native)]
|
||
end
|
||
|
||
subgraph "服务端 (Backend - Elysia.js on Bun)"
|
||
API_Gateway[API 网关 / 路由层]
|
||
|
||
subgraph "核心服务层 (Core Services)"
|
||
AuthService[认证与授权服务]
|
||
UserService[用户管理服务]
|
||
ContentService[内容管理服务 (笔记/博客)]
|
||
FileService[文件管理服务]
|
||
end
|
||
|
||
subgraph "工具服务层 (Utility Services)"
|
||
ToolService[密码/书签/同步等工具服务]
|
||
end
|
||
|
||
subgraph "插件与中间件 (Plugins & Middlewares)"
|
||
Logger[日志插件]
|
||
ErrorHandler[错误处理]
|
||
JWTMiddleware[JWT认证]
|
||
Swagger[Swagger文档]
|
||
end
|
||
end
|
||
|
||
subgraph "数据与存储层 (Data & Storage)"
|
||
MySQL[(MySQL - 关系型数据)]
|
||
Redis[(Redis - 缓存/会话)]
|
||
Elasticsearch[(Elasticsearch - 全文搜索)]
|
||
ObjectStorage[对象存储 (OSS/NAS)]
|
||
end
|
||
|
||
subgraph "第三方服务 (3rd Party Services)"
|
||
EmailService[邮件服务]
|
||
OAuth[OAuth 2.0 提供商]
|
||
AI_API[AI/LLM API]
|
||
end
|
||
|
||
%% 连接关系
|
||
WebApp --> API_Gateway
|
||
BrowserExt --> API_Gateway
|
||
MobileApp --> API_Gateway
|
||
|
||
API_Gateway --> AuthService
|
||
API_Gateway --> UserService
|
||
API_Gateway --> ContentService
|
||
API_Gateway --> FileService
|
||
API_Gateway --> ToolService
|
||
|
||
AuthService <--> MySQL
|
||
UserService <--> MySQL
|
||
ContentService <--> MySQL
|
||
ContentService <--> Elasticsearch
|
||
FileService <--> ObjectStorage
|
||
ToolService <--> MySQL
|
||
|
||
AuthService --> JWTMiddleware
|
||
API_Gateway -- use --> Logger
|
||
API_Gateway -- use --> ErrorHandler
|
||
API_Gateway -- use --> JWTMiddleware
|
||
API_Gateway -- use --> Swagger
|
||
|
||
subgraph "通用依赖"
|
||
AuthService <--> Redis
|
||
UserService <--> Redis
|
||
ContentService <--> Redis
|
||
end
|
||
|
||
AuthService --> EmailService
|
||
AuthService --> OAuth
|
||
ContentService --> AI_API
|
||
```
|
||
* **客户端层**: 负责用户交互和数据展示。
|
||
* **服务端层**: 核心业务逻辑处理中心。通过API网关统一入口，内部按业务垂直划分为多个服务模块。
|
||
* **数据与存储层**: 持久化存储数据，提供缓存和搜索能力。
|
||
* **第三方服务**: 集成外部服务以完成特定功能。
|
||
|
||
### 3.2. 模块划分
|
||
系统功能将按以下模块进行开发，每个模块对应`src/controllers`, `src/services`下的独立子目录。
|
||
1. **`core`**: 核心模块，包括用户、角色、权限、组织、字典等。
|
||
2. **`content`**: 内容模块，包括笔记、博客、评论、分类、标签等。
|
||
3. **`space`**: 个人空间模块，包括生活日志、社交互动。
|
||
4. **`reader`**: 阅读模块，包括电子书管理、批注。
|
||
5. **`tools`**: 工具模块，包括密码、书签、文件、同步等。
|
||
6. **`system`**: 系统模块，包括健康检查、监控、配置管理。
|
||
|
||
### 3.3. 详细设计规划
|
||
本概要设计完成后，将对每个模块进行详细设计，产出物包括：
|
||
- **数据库设计文档**: E-R图、表结构定义（字段、类型、约束、索引）、数据字典。
|
||
- **API接口设计文档**: 使用Swagger/OpenAPI规范，定义每个端点的URL、HTTP方法、请求参数、响应体结构及错误码。
|
||
- **UI/UX设计稿**: 针对核心页面和流程，制作线框图或高保真原型。
|
||
|
||
---
|
||
|
||
## 4. 实现与编码
|
||
|
||
### 4.1. 开发环境与工具
|
||
- **IDE**: Visual Studio Code
|
||
- **语言**: TypeScript
|
||
- **运行时**: Bun.js
|
||
- **包管理器**: Bun
|
||
- **版本控制**: Git / GitHub
|
||
- **代码检查与格式化**: ESLint / Prettier
|
||
|
||
### 4.2. 编码规范
|
||
- 严格遵守项目已定义的注释、命名、代码风格规范。
|
||
- 所有业务逻辑必须在 `services` 层实现，`controllers` 层只负责路由和数据校验。
|
||
- 禁止在代码中硬编码配置项（如密钥、端口），所有配置通过环境变量或配置文件注入。
|
||
|
||
### 4.3. 版本控制策略
|
||
采用 **Gitflow工作流** 的简化版：
|
||
- `main`: 主分支，存放稳定、可发布的代码。每个里程碑完成后合并。
|
||
- `develop`: 开发分支，集成了所有已完成的功能。
|
||
- `feat/feature-name`: 功能分支，每个新功能或任务都在此分支开发，完成后合并到 `develop`。
|
||
- `fix/bug-name`: Bug修复分支。
|
||
|
||
---
|
||
|
||
## 5. 测试策略
|
||
|
||
### 5.1. 测试层次
|
||
- **单元测试**: 使用 `Vitest` 对 `services` 和 `utils` 中的核心函数进行测试，目标覆盖率 > 90%。
|
||
- **接口测试 (集成测试)**: 使用 `supertest` 或Elysia的内置测试工具，对每个API端点进行测试，验证其与数据库、缓存的交互是否正确。
|
||
- **端到端测试 (系统测试)**: 使用 `Playwright` 或 `Cypress` 对关键用户流程（如注册登录、发布博客）进行自动化测试。
|
||
- **性能测试**: 使用 `autocannon` 对核心API进行压力测试，确保其满足技术指标。
|
||
|
||
### 5.2. 测试执行
|
||
- 所有代码提交前，必须在本地通过相关单元测试和接口测试。
|
||
- CI/CD流水线将在每次向 `develop` 或 `main` 分支合并代码时，自动运行全量测试用例。测试不通过则禁止合并。
|
||
|
||
---
|
||
|
||
## 6. 部署与运维
|
||
|
||
### 6.1. 部署流程 (CI/CD)
|
||
使用 **GitHub Actions** 自动化构建、测试和部署流程。
|
||
1. **Push to `feat/*`**: 触发ESLint检查和单元测试。
|
||
2. **Merge to `develop`**: 触发全量测试，构建Docker镜像并推送到镜像仓库，然后部署到 **Staging (预发布)** 环境。
|
||
3. **Merge to `main`**: 触发全量测试，构建生产Docker镜像，并部署到 **Production (生产)** 环境。
|
||
|
||
### 6.2. 基础设施
|
||
- **运行环境**: Docker容器。
|
||
- **容器编排**: Docker Compose (初期) / Kubernetes (未来扩展)。
|
||
- **数据库/缓存**: 使用云服务商提供的托管服务或在Docker中自建。
|
||
|
||
### 6.3. 运维监控
|
||
- **日志**: 使用 `pino` 记录结构化日志，并聚合到统一的日志管理平台（如ELK Stack或Loki）。
|
||
- **监控与告警**: 使用 `Prometheus` 收集应用指标，`Grafana` 进行可视化展示，并针对关键指标（如API错误率、延迟）设置告警。
|
||
|
||
---
|
||
|
||
## 7. 维护与演进
|
||
|
||
- **问题跟踪**: 使用GitHub Issues跟踪Bug和功能请求。
|
||
- **文档同步**: 所有代码变更，若涉及架构、API或数据库设计，必须同步更新相关设计文档。
|
||
- **定期审查**: 每个里程碑结束后，进行项目复盘，评估开发流程、代码质量和系统架构，并进行优化。
|
||
- **依赖更新**: 定期（如每季度）审查并更新项目依赖，以修复潜在的安全漏洞和利用新特性。 |