TakeoutSaaS.C-Side-Mini-Program-V1/AGENTS.md

TakeoutSaaS.C-Side-Mini-Program-Taro

项目定位

• 这是 TakeoutSaaS 面向顾客的微信小程序前端仓库（Taro 版本）。
• 当前技术栈固定为 Taro 4 + Vue3 + TypeScript + Pinia + NutUI Taro + Vite。
• 目标先跑通 V1.0 顾客主交易闭环：选店、点餐、购物车、结算、订单查询。

强制约束

• 小程序前端必须基于官方 Taro CLI 脚手架维护，不要手搓工程骨架替代官方初始化结果。
• 当前输出端固定为 微信小程序，除非用户明确要求多端同发。
• 所有后端 ID 一律按 string 处理，不要在前端转 number。
• 所有接口统一先经过 src/services 请求层封装，再进入页面或 store；页面里不要直接散落 Taro.request。
• 所有后端响应按 ApiResponse<T> 解包；页面层只消费已经解包后的业务数据。

当前接口约束

• 真实基址：https://api-mini-dev.laosankeji.com/api/mini/v1
• 固定租户头：X-Tenant-Code: t1770086772899
• 当前已确认真实接口：GET /bootstrap、GET /health
• 其它业务接口当前仍允许走 mock，直到后端正式补齐。

目录约定

• src/pages：页面目录，按业务域拆分。
• src/components：页面级复用组件，统一使用目录入口结构。
• src/stores：Pinia 状态。
• src/services：请求层与领域接口封装。
• src/shared：类型、常量、格式化函数、mock 数据。
• src/utils：通用工具。

技术规范

• 页面负责展示与交互编排，store 负责跨页状态，services 负责接口协议适配，shared 负责纯数据与类型。
• 场景枚举统一使用：Delivery、Pickup、DineIn。
• 小程序渠道枚举统一使用：WeChatMiniProgram。
• 环境变量统一通过构建期常量注入，不要在页面里硬编码域名。
• UI 风格保持轻量、清晰、可触达，优先保证 44px 以上点击区和明确状态反馈。
• 静态样式禁止直接写在模板的 style="" 上；改成语义类名并落到 scss 文件。

Vue 文件拆分规范

• 页面入口固定为 src/pages/**/index.vue，只保留模板、薄胶水脚本和 @use './styles/index.scss'；业务加载、计算、提交流程统一下沉到 composables/useXxxPage.ts。
• 复杂页面必须继续二级拆分到 src/pages/**/composables/<page-key>/，至少按 helpers.ts、*actions.ts、constants.ts 这类职责拆开，不要把大段流程重新塞回 useXxxPage.ts。
• 页面样式固定放在 src/pages/**/styles/，styles/index.scss 只负责聚合；当样式超过 150 行或已经出现多个视觉域时，必须拆成 base.scss、card.scss、submit.scss 这类分片。
• 根组件固定使用目录入口：src/components/<kebab-name>/index.vue，并通过 @/components/<kebab-name>/index.vue 引用，不再新增平铺的 src/components/*.vue。
• 组件逻辑放在同目录的 useXxx.ts；由于 Vue 宏限制，defineProps / defineEmits 可以留在 index.vue，但计算、事件、映射、辅助函数必须下沉到 useXxx.ts。
• 当组件样式简单时允许使用同级 styles.scss；当组件样式超过 150 行或明显分区时，升级为 styles/index.scss + 分片.scss。
• 新增页面或组件时，优先复用现有拆分模式；不要再创建“模板 + 大段脚本 + 大段样式”三段混写的单文件组件。

修改约定

• 新增页面后，必须同步注册 src/app.config.ts 路由。
• 新增接口后，优先补在 src/services/mini.ts 或对应领域文件，不要直接写进页面。
• 如果修改了目录结构、命令或工程规范，要同步更新 README.md。