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