TakeoutSaaS.AdminUI/document/99页面ToDo.md

页面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 或组件测试）覆盖核心流程。