# 星撰个人综合平台 - 软件开发概要设计

---

## 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或数据库设计，必须同步更新相关设计文档。
-   **定期审查**: 每个里程碑结束后，进行项目复盘，评估开发流程、代码质量和系统架构，并进行优化。
-   **依赖更新**: 定期（如每季度）审查并更新项目依赖，以修复潜在的安全漏洞和利用新特性。