WonderQ-Project/docs/decisions.md

WonderQ 当前技术与文档决策

本文档只记录当前有效决策，避免非当前技术路径干扰后续开发。

DEC-001：后端采用 Python + FastAPI 技术栈

状态：已接受

当前后端服务位于 WonderQ-Admin，技术栈为 Python、FastAPI、SQLAlchemy 2、Alembic、PostgreSQL、JWT 和 Pydantic。

原因：

• 当前代码和文档已经围绕该技术栈落地。
• Alembic 负责数据库迁移，适合继续演进 PostgreSQL 结构。
• FastAPI 与 Pydantic 能清晰表达 Public API 和 Admin API 的请求响应契约。

影响：

• 后端文档以 backend-api-service.md 和 backend-plan.md 为准。
• 不在当前文档中保留其它后端技术栈规划。

DEC-002：Public API 与 Admin API 分离

状态：已接受

WonderQ-MiniAPP 只对接 /api/public/...，不依赖后台鉴权；WonderQ-Admin-UI 只对接 /api/admin/...，除登录外均需要后台登录态。

原因：

• 前台展示和后台运营权限边界不同。
• Public API 需要过滤未发布或未启用内容。
• Admin API 需要返回运营维护所需的完整配置和草稿数据。

影响：

• public-api.md 是 MiniAPP 对接后端的唯一 Public API 契约。
• admin-api-requirements.md 是 Admin UI 对接后端的主契约。

DEC-003：页面模块 CRUD 细节以 module-config-api.md 为准

状态：已接受

首页轮播、目的地、地图、主题卡、特价优惠、精选线路、特色酒店、万趣用车和更多服务的新增、更新、删除、排序细节，统一维护在 module-config-api.md。

原因：

• 页面模块字段多、规则细，放在 Admin API 主文档里会造成重复。
• 管理前端和后端实现都需要同一份细粒度契约。

影响：

• admin-api-requirements.md 只保留站点配置主接口和模块入口说明。
• 任何页面模块字段、状态码、排序、媒体上传规则变化，都先更新 module-config-api.md。

DEC-004：文档保持扁平结构

状态：已接受

docs/ 目录不再按子项目分目录，所有当前文档直接放在 docs/ 根目录。

原因：

• 当前项目只有少量关键文档，扁平结构查找更快。
• 三端联调需要跨项目阅读，按子项目分目录会增加跳转成本。

影响：

• docs/README.md 是唯一文档入口。
• 新文档必须在 docs/README.md 登记。

DEC-005：当前文档只服务现行架构

状态：已接受

当前文档集中只保留服务现行架构和三端联调的内容。

原因：

• 非当前技术路径会干扰三端当前开发判断。
• 当前任务目标是提高后端、管理前端和 MiniAPP 的开发进度，文档需要服务现行架构。

影响：

• 新成员只需要阅读当前文档即可理解现行协作方式。
• 如未来需要记录重大调整，直接新增当前决策或更新本文件。

DEC-006：MiniAPP 采用简约、内容优先的移动端视觉风格

状态：已接受

WonderQ-MiniAPP 的 H5 与微信小程序前台统一采用扁平、低装饰的简约风格。内容图片和信息层级优先于装饰效果，交互状态通过颜色、边框和轻量动效表达。

原因：

• 旅行内容页需要让用户快速扫描目的地、线路和服务入口，复杂背景和重装饰会削弱信息层级。
• H5 与小程序运行设备性能差异较大，减少渐变、模糊和重阴影可以降低渲染负担并提高跨端一致性。
• 固定导航采用稳定布局，避免浮动徽章和缩放动画造成视觉干扰或布局跳动。

约定：

• 基础色使用白色、浅灰和低饱和绿色；主操作使用绿色，价格等业务强调色保持低饱和暖色。
• 卡片、输入框和按钮优先使用 8-12px 圆角、细边框和轻阴影；不新增大面积渐变、装饰性光晕或重阴影。
• 复用 WonderQ-MiniAPP/src/app.css 的 --wq-* 设计变量及共享组件样式，页面局部样式不得重新建立一套颜色和阴影体系。

影响：

• 新增或调整 MiniAPP 页面时，应先复用共享样式，再补充页面特有布局。
• 如确需引入明显装饰效果，需要在页面需求中说明其内容价值，并同步更新本决策。