139 lines
12 KiB
Markdown
139 lines
12 KiB
Markdown
# 页面ToDo
|
||
|
||
## 背景与接口基线
|
||
|
||
- 后端架构：Clean Architecture（Api/Application/Domain/Infrastructure），Admin API 路由前缀 `api/admin/v{version}/`，Mini API 路由前缀 `api/mini/v{version}/`，鉴权为 JWT + 权限码（`PermissionAuthorize`），长整型 ID 以字符串返回，前端需保持大数解析（可用 `json-bigint`）。
|
||
- Admin 端已交付核心 API（Phase 1）：
|
||
- 租户：注册/分页/详情、实名认证提交与审核、套餐订阅/续费/升降配、审核日志、公告/通知、账单、配额占用校验。
|
||
- 商户：入驻创建、证照上传、合同管理、审核流程、审核日志、类目列表。
|
||
- 套餐与配额：TenantPackage CRUD、订阅历史、配额占用校验。
|
||
- RBAC 模板：角色模板 CRUD、复制、租户初始化，权限码种子齐全。
|
||
- 门店：门店 CRUD、营业时间/配送区/节假日、能力开关（预约/排队）。
|
||
- 桌码：区域与桌码 CRUD、批量生成、二维码 ZIP 导出。
|
||
- 员工排班：员工 CRUD、门店角色绑定、排班 CRUD（默认未来 7 天）。
|
||
- 菜品：分类/SPU/SKU/规格/加料/媒资/定价 CRUD，上/下架；Mini 端可拉取门店菜单。
|
||
- 库存：SKU 库存与批次、调整/锁定/释放/售罄管理（表已具备，接口可用）。
|
||
- 自提档期：自提设置与时间窗 CRUD；Mini 端按日期查询档期。
|
||
- Mini 端基础：桌码扫码上下文（门店+桌台+公告）。
|
||
- 尚未交付的模块（前端需占位但标记阻塞）：购物车、完整下单/支付/优惠、桌台账单、自配送与第三方配送抽象、预购自提核销、业务指标大盘。
|
||
- 业务关系（前端路由/权限需体现上下游约束）：
|
||
- 租户 ↔ 商户：商户属于租户，租户未通过实名认证/订阅过期时，商户入驻审核需提示或限制；租户停用后商户与门店入口应灰显。
|
||
- 租户套餐/配额 ↔ 门店/员工/商品：套餐与配额决定可创建的门店数、员工数、商品数/库存操作等，前端在创建/批量操作时需展示剩余额度（调用配额校验接口），超额时阻止提交。
|
||
- RBAC ↔ 模块入口：权限码控制菜单与按钮显隐；角色模板可复制到租户，租户停用/配额不足时仍可查看权限但部分操作需禁用；商户/门店/商品等操作按钮需绑权限码，防止“看得见点不了”的体验分裂。
|
||
|
||
## 搭建顺序（推荐）
|
||
|
||
1. [ ] 环境与基础设施：`pnpm i`、配置 `.env` 的 API 基地址；axios 实例 + 拦截器（加 Authorization、全局错误/超时提示、TraceId 透传）。
|
||
2. [ ] 全局框架：登录页、基础布局（侧边导航/头部/标签页）、动态路由/菜单与权限控制（基于角色模板权限码）。
|
||
3. [ ] 通用组件：表格查询模板、表单/抽屉、批量操作、上传（对接文件上传 API/COS）、二维码下载、富文本/备注输入。
|
||
4. [ ] 模块页面按优先级迭代（见下表）；每个模块先做列表 → 详情 → 创建/编辑 → 审核/状态流转 → 导出/下载。
|
||
5. [ ] 联调与观测：与 Swagger 一致的请求/响应模型，统一错误提示，必要时对长 ID 使用字符串展示；完成一模块后补充 E2E/组件级用例。
|
||
|
||
## 页面清单与依赖
|
||
|
||
| 模块 | 页面 | 关键功能 | 依赖 API | 优先级 |
|
||
| --- | --- | --- | --- | --- |
|
||
| 认证/首页 | 登录/登出 | 账号登录、Token 缓存/续期、租户/角色选择 | Admin 鉴权接口（Swagger），权限码获取 | P0 |
|
||
| | 控制台总览 | 展示租户数/门店数/商品数、待办项入口 | 后续可接统计接口（暂用静态/Mock） | P2 |
|
||
| 系统权限 | 角色模板列表/详情 | 查看模板、权限码树、变更记录 | `api/admin/v1/role-templates`\*（根据 RolesController 路由） | P1 |
|
||
| | 角色模板新建/编辑 | 复制模板、勾选权限、保存 | 同上 | P1 |
|
||
| | 租户初始化权限 | 选择模板批量初始化租户权限 | 角色模板复制/初始化接口 | P2 |
|
||
| 租户管理 | 租户列表/搜索 | 分页、状态筛选、关键字搜索 | `api/admin/v1/tenants` GET | P0 |
|
||
| | 租户详情 | 基本信息、当前套餐/订阅、实名状态、公告/通知概览 | `tenants/{id}` GET | P0 |
|
||
| | 注册租户 | 提交注册信息并初始化套餐 | `tenants` POST | P1 |
|
||
| | 实名提交/审核 | 上传资料、查看审核记录、通过/驳回 | `tenants/{id}/verification` POST / `tenants/{id}/review` POST 等 | P1 |
|
||
| | 订阅与配额 | 订阅创建/续费/升降配、配额占用校验历史 | `tenants/{id}/subscriptions`、`tenants/{id}/quotas/check` | P1 |
|
||
| | 账单与通知 | 账单列表/详情/标记支付，公告/通知列表+已读 | `tenants/{id}/billings`、`announcements`、`notifications` | P2 |
|
||
| | 审核日志 | 查看租户审核日志 | `tenants/{id}/audits` | P2 |
|
||
| 商户入驻 | 商户列表/详情 | 状态筛选、合同/证照查看、审核轨迹 | `api/admin/v1/merchants` GET | P0 |
|
||
| | 商户创建/编辑 | 录入基本信息、证照上传、合同录入 | `merchants` POST/PUT、`merchants/{id}/documents`、`contracts` | P1 |
|
||
| | 商户审核 | 状态流转（待审/驳回/通过）、驳回原因 | `merchants/{id}/review` | P1 |
|
||
| | 类目管理 | 类目列表/选择 | `merchant-categories` 列表接口 | P2 |
|
||
| 门店 | 门店列表/详情 | 基本信息、营业时间、配送区、能力开关 | `stores` CRUD | P0 |
|
||
| | 门店编辑 | 基础信息维护、配送区 GeoJSON、节假日 | `stores` PUT、`stores/{id}/delivery-zones` | P1 |
|
||
| | 门店公告 | 门店公告/通知管理 | `tenant-announcements` (按租户/门店) | P2 |
|
||
| 桌码 | 区域与桌台列表 | 区域/桌码 CRUD、状态展示 | `stores/{id}/tables`、`table-areas` | P1 |
|
||
| | 批量生成与导出 | 按区域/容量生成，下载二维码 ZIP | `stores/{id}/tables:batch`、`/export` | P1 |
|
||
| 员工与排班 | 员工列表/编辑 | 员工信息、门店角色绑定 | `store-employees` CRUD | P1 |
|
||
| | 排班日历 | 未来 7 天排班视图、冲突提示、批量排班 | `store-employee-shifts` | P1 |
|
||
| 菜品与菜单 | 分类管理 | 分类 CRUD、排序 | `product-categories` | P1 |
|
||
| | 商品列表/详情 | SPU/SKU/规格/加料/媒资、上下架 | `products`、`product-skus`、`publish`/`unpublish` | P0 |
|
||
| | 商品编辑 | 规格/加料组维护、媒资上传、定价 | 同上 | P1 |
|
||
| | 菜单预览 | 拉取门店全量菜单 JSON 预览 | Mini 菜单接口 `api/mini/v1/stores/{id}/menu` | P2 |
|
||
| 库存 | 库存列表 | SKU 库存、锁定/售罄状态 | `inventory-items` | P1 |
|
||
| | 批次管理 | 批次列表、调整、售罄 | `inventory-batches` | P1 |
|
||
| | 库存调整 | 增减、预售/限购、锁定/释放记录 | `inventory-adjustments`、`inventory-lock-records` | P2 |
|
||
| 自提档期 | 自提设置 | 截单时间、容量、开关 | `stores/{id}/pickup-settings` | P2 |
|
||
| | 档期日历 | 日期选择、可用档期/余量展示 | `stores/{id}/pickup-slots` | P2 |
|
||
| 运营 | 公告/通知 | 公告列表/发布/上下架、已读状态 | `tenant-announcements`、`tenant-notifications` | P2 |
|
||
| | 账单/对账 | 账单列表、详情、标记支付 | `tenants/{id}/billings` | P2 |
|
||
| 待后端的占位 | 购物车、下单/支付、桌台账单、自配送/第三方配送、预购自提核销、业务指标报表 | 只做菜单占位或灰显入口，待后端接口就绪再实现 | 无 | P3 |
|
||
|
||
> 说明：表内路由根据当前 Controllers 约定推断，实际联调请以 Swagger `api/admin/swagger/index.html` 暴露的接口为准。
|
||
|
||
## 下一步行动（可直接执行）
|
||
|
||
1. 初始化 axios/路由/权限骨架，完成登录页与基础布局。
|
||
2. 先联调租户列表/详情/注册与商户列表/审核，确保 RBAC 与菜单权限生效。
|
||
3. 依次落地门店→桌码→员工排班→商品→库存→自提档期页面，完成 Phase 1 闭环。
|
||
4. 为未交付模块预留菜单占位（灰色状态 + “开发中”），避免导航缺口。
|
||
|
||
## 迭代执行序列（更细步骤）
|
||
|
||
1. 环境与骨架（当天完成）
|
||
- [ ] 配置 `.env`：Admin API 基地址、超时、Token 存储键名。
|
||
- [ ] 初始化 axios 拦截器：附带 Authorization、长 ID 使用 `json-bigint` 解析、全局错误提示、TraceId 透传。
|
||
- [ ] 路由/布局：登录页、基础布局（侧边栏 + 顶栏 + 页签），路由守卫检查 Token 与权限码。
|
||
2. 权限与菜单（P0）
|
||
- [ ] 角色模板列表/详情页：展示权限树、变更记录。
|
||
- [ ] 角色模板创建/编辑：复制模板、新增/删除权限码、保存。
|
||
- [ ] 菜单与按钮显隐：基于权限码动态生成侧栏，按钮加指令控制。
|
||
3. 登录与首页（P0）
|
||
- [ ] 登录页：账号密码登录，Token 缓存与续期。
|
||
- [ ] 控制台总览：占位展示租户数/门店数/商品数、待办（实名/审核/续费），数据可先用 Mock。
|
||
4. 租户管理（P0-P1）
|
||
- [ ] 租户列表：分页、状态/关键词筛选，列出套餐、实名状态、到期时间。
|
||
- [ ] 租户详情：基本信息、当前订阅、配额剩余、公告/通知概览、审核日志。
|
||
- [ ] 注册租户：表单提交注册；提交后跳转详情。
|
||
- [ ] 实名提交流程：资料上传、状态展示、提交/驳回/通过操作；显示审核记录。
|
||
- [ ] 订阅与配额：创建/续费/升降配、调用配额校验接口并展示剩余额度，超额禁止提交。
|
||
- [ ] 账单/公告/通知：账单列表/详情/标记支付，公告/通知列表和已读状态。
|
||
5. 商户入驻（P0-P1）
|
||
- [ ] 商户列表：分页、状态筛选，显示所属租户、审核状态。
|
||
- [ ] 商户详情：基本信息、证照、合同、审核轨迹。
|
||
- [ ] 商户创建/编辑：信息录入、证照上传（COS 上传 API）、合同录入。
|
||
- [ ] 商户审核：待审/通过/驳回，填写驳回原因。
|
||
- [ ] 类目管理：类目列表选择，支持搜索。
|
||
6. 门店管理（P0-P1）
|
||
- [ ] 门店列表：展示租户/商户、状态、能力开关（预约/排队）。
|
||
- [ ] 门店详情/编辑：基础信息、营业时间、配送区 GeoJSON、节假日；套餐/配额超额时禁用创建。
|
||
- [ ] 门店公告：公告列表/发布/上下架（若后端按租户共享则合并视图）。
|
||
7. 桌码管理（P1）
|
||
- [ ] 桌码区域与桌台列表：区域 CRUD、桌台 CRUD，显示容量/状态。
|
||
- [ ] 批量生成：按区域/容量批量生成桌码。
|
||
- [ ] 二维码导出：ZIP 下载，支持按区域过滤。
|
||
8. 员工与排班（P1）
|
||
- [ ] 员工列表/编辑：基础信息、门店角色绑定。
|
||
- [ ] 排班日历：未来 7 天排班视图，创建/编辑/删除，冲突提示。
|
||
9. 菜品与菜单（P0-P1）
|
||
- [ ] 分类管理：列表/排序/CRUD。
|
||
- [ ] 商品列表：SPU/SKU 列表，支持状态/分类筛选、上下架。
|
||
- [ ] 商品编辑：规格/加料组、媒资上传、定价策略；保存后刷新 SKU 列表。
|
||
- [ ] 菜单预览：按门店拉取全量菜单 JSON，供验收与演示。
|
||
10. 库存管理（P1-P2）
|
||
- [ ] 库存列表：SKU 库存、锁定/售罄状态，支持搜索/筛选。
|
||
- [ ] 批次管理：批次列表、批次调整（数量/售罄），展示策略（FIFO/FEFO）。
|
||
- [ ] 库存调整：增减、锁定/释放记录查看；展示幂等键与状态。
|
||
11. 自提档期（P2）
|
||
- [ ] 自提设置：截单时间、容量、开关配置。
|
||
- [ ] 档期日历：选择日期，查看可用档期与剩余容量，支持新增/编辑/删除。
|
||
12. 运营与账单（P2）
|
||
- [ ] 公告/通知：公告发布/上下架，通知列表与已读状态。
|
||
- [ ] 账单/对账：账单列表/详情、标记支付、导出。
|
||
13. 占位与后续（P3）
|
||
- [ ] 购物车、下单/支付、桌台账单、自配送/第三方配送、预购自提核销、业务指标报表：菜单入口置灰或“开发中”，待后端接口完成后再实施。
|
||
14. 联调与验收（每完成一模块即进行）
|
||
- [ ] 对照 Swagger 校验请求/响应；异常与权限错误统一提示。
|
||
- [ ] 大整数字段保持字符串展示；上传类接口校验文件大小/格式。
|
||
- [ ] 完成后补充基础用例（可用 Cypress/Playwright 或组件测试）覆盖核心流程。
|