# 需求

> 本文只描述要什么与怎么算达成。技术方案、数据结构、字段定义见 [架构设计](04-architecture.md)。

## 一、业务现状

| 项 | 状态 |
| --- | --- |
| 用户 | AI coding 使用者和开发者需要快速判断哪个开源骨架适合自己的新项目。 |
| 数据 | 初期人工录入骨架项目、分类、标签、评分、推荐理由和文章。 |
| 现有系统 | 当前仓库为空项目，已建立 harness coding 文档。 |
| 约束 | 第一版使用 Python 3.12 + Wagtail + SQLite；面向 2 核 2G VPS；不做高并发写入。 |

## 二、用户角色

- **游客 / 未登录用户**：浏览首页、分类页、筛选列表、骨架详情页、文章页。
- **站点编辑者**：登录 Wagtail 后台，维护骨架项目、场景分类、语言、框架、评分和文章。
- **站点管理员**：管理后台账号、发布内容、配置导航和 SEO。

第一版不提供前台注册用户。

## 三、功能清单

### 第一版 MVP（最小闭环）

| 功能 | 用户能做什么 | 优先级 |
| --- | --- | --- |
| 首页与场景导航 | 用户能从首页看到主场景分类和推荐骨架入口。 | P0 |
| 骨架项目列表 | 用户能按场景浏览骨架项目列表。 | P0 |
| 筛选与基础搜索 | 用户能按语言、框架、数据库、AI 友好度筛选。 | P0 |
| 骨架详情页 | 用户能查看适合场景、技术栈、成熟度、维护状态、功能清单、AI 友好度评分、推荐理由和不适用场景。 | P0 |
| 后台内容管理 | 编辑者能通过 Wagtail 后台维护项目、分类、标签、评分和文章。 | P0 |
| SEO 基础 | 公开页面具备 title、description、slug、sitemap 基础能力。 | P0 |

### 后续迭代

| 功能 | 描述 | 阶段 |
| --- | --- | --- |
| 付费收录 / 赞助展示 | 保持 Sponsored 标识，和编辑推荐分离。 | V2 |
| Newsletter | 收集订阅，推送新骨架和评测文章。 | V2 |
| 用户提交项目 | 用户提交骨架项目，后台审核后发布。 | V2 |
| Affiliate 链接管理 | 管理云服务、部署平台、AI 工具等返佣链接。 | V2 |
| 付费数据库 / 会员 | 详细评分、对比表、维护状态提醒。 | V3 |
| GitHub 数据同步 | 同步 stars、最后提交、issues 等维护指标。 | V3 |
| PostgreSQL 迁移 | 当写入增加或 SQLite 锁冲突出现时迁移。 | V3 |

## 四、核心用户故事（MVP）

1. 作为游客，我打开首页后能按 SaaS、管理后台、API 服务、内容站、AI 应用等场景进入列表。
2. 我可以在列表中按语言、框架、数据库、AI 友好度筛选，并看到匹配项目。
3. 我可以打开骨架详情页，判断它适合什么项目、不适合什么项目、为什么推荐。
4. 作为编辑者，我可以登录后台新增或修改骨架项目，并发布到前台。
5. 当某个分类没有项目时，系统展示明确空状态，不报错。

## 五、验收标准（MVP）

- **首页与场景导航**：访问 `/` 时能看到场景入口、推荐项目区和最新文章入口。
- **骨架项目列表**：访问场景页时能看到该场景下已发布项目；无项目时显示空状态。
- **筛选与基础搜索**：选择语言或框架筛选后，列表只展示匹配项目；筛选条件可被 URL 表示。
- **骨架详情页**：详情页展示名称、简介、官网 / GitHub 链接、技术栈、适用场景、不适用场景、AI 友好度评分、维护状态和推荐理由。
- **后台内容管理**：管理员能在 Wagtail 后台新增项目、分类、语言、框架和评分，并发布后在前台可见。
- **SEO 基础**：核心公开页面有稳定 slug、页面标题、meta description，并可生成 sitemap。

## 六、范围边界与决策

| 问题 | 决策 |
| --- | --- |
| 第一版平台 | Web 网站 |
| 是否需要账号 | 前台不需要；后台使用 Wagtail 管理员账号 |
| 第一版范围 | 内容目录 + 筛选 + 详情 + 后台维护 + SEO |
| 暂不支持 | 用户注册、收藏、评论、支付、自动抓取、复杂搜索、多语言 |
| 数据库 | 开发和第一版上线使用 SQLite with JSON1 |
| Python | Python 3.12 |

## 七、待确认 / 风险点

- **数据质量风险**：骨架评分需要人工标准，先在 `04-architecture.md` 固定评分字段。
- **维护状态风险**：MVP 人工录入维护状态，不自动判断 GitHub 活跃度。
- **SQLite 并发风险**：多个读通常可接受，多个并发写可能触发锁；出现前台用户提交、评论、会员等写入功能时迁移 PostgreSQL。
- **SEO 风险**：Wagtail 页面结构和 slug 需要从一开始规范，避免上线后频繁改 URL。
- **商业信任风险**：赞助展示必须明确标识，不能影响编辑推荐排序。
- **版权风险**：引用第三方骨架项目时只写摘要、评分和链接，不复制大段 README 或文档内容。
- **待确认问题**：项目正式名称、域名、视觉风格、首批收录项目清单。