# 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 页面时，应先复用共享样式，再补充页面特有布局。 - 如确需引入明显装饰效果，需要在页面需求中说明其内容价值，并同步更新本决策。