larablog/docs/architecture.md

LaraBlog 架构与开发思想

目标

把 sablog 内容与 SEO 权重迁到现代 Laravel 栈：不克隆过时能力（Trackback/WAP/旧 Admin），用主题/插件/对象存储/AI 队列替换。

分层

HTTP (legacy .shtml + /admin Filament + /api/v1)
  → Controllers / Filament Pages
    → Domain (Blog / Media / Theme / Plugin / Seo / Ai)
      → Eloquent Models + Spatie Settings
        → S3 disk / Redis queues / Workerman

关键约定

区域	路径
Legacy 前台 URL	routes/legacy.php
Web 辅助	routes/web.php
JSON API（小程序/其他端）	routes/api.php → /api/v1/*
领域逻辑	app/Domain/*
主题	themes/{slug}/
插件	plugins/{vendor}/{name}/
规格	docs/specs/larablog-platform/
OpenAPI	docs/api/openapi.yaml

开发模式

1. 规格先行：非琐碎功能写 SPEC / CHECKLIST / TESTPLAN
2. 兼容优先：文章/分类 ID、.shtml 内容 URL 保持可达
3. 引用不写死 CDN：正文存 [attach=id] / attach:id，渲染期转 /attachment.php?id=
4. 异步 AI：Web 不阻塞 LLM；队列 / Workerman 消费
5. 默认中文：APP_LOCALE=zh_CN，文案走 lang/zh_CN/*
6. 测试：PHPUnit Feature sqlite :memory:（见 phpunit.xml）；CI 同配置

PHP / 代码风格

• 目标运行时：PHP 8.2+（composer.json）
• 应用代码逐步统一 declare(strict_types=1);
• 类型提示、返回类型、枚举优先；避免软依赖全局状态

一期 vs 二期

• 一期已做：核心博客、主题引擎、插件框架、SEO/GEO、导入、AI stub 管道、前台皮肤、后台 Filament
• 一期骨架：支付 / 会员 / 双商城（非真实结算）
• 二期：自动配图、真实支付会员、小程序完整写接口与鉴权深化