73 lines
3.6 KiB
Markdown
73 lines
3.6 KiB
Markdown
# BlogFlare 项目规则
|
||
|
||
## 包管理器
|
||
|
||
- **统一使用 `pnpm`**，禁止使用 `npm` 或 `yarn`。
|
||
- 运行一次性脚本时，使用 `pnpm dlx` 而不是 `npx`。
|
||
- 安装依赖时，使用 `pnpm install` 或 `pnpm add`。
|
||
|
||
## 质量保障与 CI 检查
|
||
|
||
- **修改代码后必须运行本地检查**，尤其是 Svelte 组件或 TypeScript 文件。
|
||
- 必须运行 `pnpm run check && pnpm run lint`，并确保 0 错误、0 警告。
|
||
- 没有实际运行并通过这些检查，不得宣布任务完成。
|
||
|
||
## 语义化配置（别名 Aliases，重要）
|
||
|
||
项目中的实体名称（文章、页面、分类、标签、系列）全部支持后台自定义别名，**禁止在任何前端文案中硬编码这些中文名称**，必须统一走 `aliases` 语义化配置。
|
||
|
||
- 别名来源：数据库 `settings` 表中 `alias.*` 键，由 `src/routes/admin/+layout.server.ts` 注入，管理端页面通过 `$page.data.aliases` 读取。
|
||
- 支持的别名 key：`post`、`page`、`category`、`tag`、`series`。
|
||
- 使用 `$page.data.aliases?.<key> || '<默认值>'` 形式读取，默认值必须与 `+layout.server.ts` 中保持一致。
|
||
|
||
```svelte
|
||
<h2>新{$page.data.aliases?.post || '文章'}</h2>
|
||
<h3>{$page.data.aliases?.tag || '标签'}</h3>
|
||
placeholder="+ 添加{$page.data.aliases?.tag || '标签'}..."
|
||
```
|
||
|
||
- 适用范围包括但不限于：标题、标签页签、按钮文案、占位符（placeholder）、提示语（title / aria-label）、空状态、确认弹窗等所有用户可见文本。
|
||
- 后台设置项在 `src/routes/admin/settings/+page.server.ts` 中以 `alias.<key>` 形式保存，默认值需同步维护。
|
||
|
||
## 核心原则
|
||
|
||
1. **渐进式开发优于大爆炸式开发**：小步提交，每次都能编译通过和测试通过。
|
||
2. **从现有代码学习优于重新发明**：先研究和规划，再开始实现。
|
||
3. **务实而非教条**：适应项目实际情况。
|
||
4. **明确意图优于聪明代码**：选择简单明了的解决方案，不使用聪明技巧。
|
||
5. **保持简单**：不要过度设计，避免过早抽象；如果需要额外解释，说明设计已经太复杂。
|
||
6. **单一职责**：每个函数/类只承担一项职责。
|
||
7. **控制复杂度**：注意圈复杂度，代码尽可能复用。
|
||
8. **遵循 RESTful 原则**：涉及 API 的地方要遵循 RESTful 设计。
|
||
9. **使用中文**：始终使用中文回复，代码注释也一律使用中文。
|
||
|
||
## 新需求流程
|
||
|
||
1. **首次沟通不急于编码**：当用户提出新需求时，先进行方案讨论。
|
||
2. **使用 ASCII 图表**：必要时绘制多个方案对比图，让用户选择最佳方案。
|
||
3. **用户确认后再开发**：只有用户明确确认方案后，才开始具体的开发工作。
|
||
|
||
## 实施过程
|
||
|
||
1. **理解现有模式**：研究代码库中的 3 个相似功能/组件。
|
||
2. **识别通用模式**：找出项目约定和模式。
|
||
3. **遵循现有规范**：使用相同的库/工具，遵循现有测试模式。
|
||
4. **分阶段实现**：将复杂工作分解为 3-5 个阶段。
|
||
|
||
## 卡住时（关键规则）
|
||
|
||
最多尝试 3 次后必须停止：
|
||
|
||
1. 记录失败内容（尝试了什么、具体错误、失败原因）。
|
||
2. 研究替代方案（找 2-3 个类似实现）。
|
||
3. 质疑基本假设（抽象层次对吗？能分解成更小问题吗？）。
|
||
4. 尝试不同角度（不同库/框架？不同架构模式？移除抽象？）。
|
||
|
||
## 决策框架优先级
|
||
|
||
1. **可测试性**：是否容易测试？
|
||
2. **可读性**：6 个月后还能理解吗？
|
||
3. **一致性**：是否符合项目模式？
|
||
4. **简洁性**：是否是最简单的可行方案？
|
||
5. **可逆性**：后续修改的难度？
|