# 里程碑待办追踪

> 按“小程序版模块规划”划分四个里程碑；每个里程碑只含对应范围的任务，便于分阶段推进。

---
## Phase 1（当前阶段）：租户/商家入驻、门店与菜品、扫码堂食、基础下单支付、预购自提、第三方配送骨架
- [x] 管理端租户 API：注册、实名认证、套餐订阅/续费/升降配、审核流，Swagger ≥6 个端点，含审核日志。
  - 已交付：`src/Api/TakeoutSaaS.AdminApi/Controllers/TenantsController.cs` 暴露注册、详情、实名提交、审核、订阅创建/升降配、审核日志 8 个端点；对应命令/查询位于 `src/Application/TakeoutSaaS.Application/App/Tenants`，仓储实现 `EfTenantRepository`，并写入 `TenantAuditLog` 记录。Swagger 自动收录上述接口，满足 Phase1 租户管理要求。
- [x] 商家入驻 API：证照上传、合同管理、类目选择，驱动待审/审核/驳回/通过状态机，文件持久在 COS。
  - 已交付：`src/Api/TakeoutSaaS.AdminApi/Controllers/MerchantsController.cs` 新增证照上传/审核、合同创建与状态更新、商户审核、审核日志、类目列表等 8 个端点；应用层新增 `AddMerchantDocumentCommand`、`CreateMerchantContractCommand`、`ReviewMerchantCommand` 等 Handler；`MerchantDocument/Contract/Audit` DTO 完整返回详情，文件 URL 仍通过 `/api/admin/v1/files/upload` 上 COS。仓储实现扩展 `EfMerchantRepository` 支持文档/合同/AuditLog 持久化，`TakeoutAppDbContext` 新增 `merchant_audit_logs` 表实现状态机追踪。
- [x] RBAC 模板：平台管理员、租户管理员、店长、店员四角色模板；API 可复制并允许租户自定义扩展。
  - 已交付：角色模板改为数据库驱动，新增 `RoleTemplate/RoleTemplatePermission` 实体与仓储接口/实现；应用层提供模板列表/详情/创建/更新/删除、按模板复制与租户批量初始化命令/查询；Admin 端 `RolesController` 暴露模板 CRUD 与复制/初始化端点（`src/Api/TakeoutSaaS.AdminApi/Controllers/RolesController.cs`），复制时补齐缺失权限且保留租户自定义授权；预置模板/权限种子写入 `src/Api/TakeoutSaaS.AdminApi/appsettings.Seed.*.json`。
- [x] 配额与套餐：TenantPackage CRUD、订阅/续费/配额校验（门店/账号/短信/配送单量），超额返回 409 并记录 TenantQuotaUsage。
  - 已交付：新增套餐仓储与命令/查询/DTO（`src/Application/TakeoutSaaS.Application/App/Tenants`），Admin 端新增 `TenantPackagesController` 提供套餐列表/详情/创建/更新/删除接口。新增配额校验命令与租户接口 `/api/admin/v1/tenants/{id}/quotas/check`，基于当前订阅套餐限额校验并占用配额，超额抛出 409 并写入 `TenantQuotaUsage`。仓储注册于 `AddAppInfrastructure`。
- [x] 租户运营面板：欠费/到期告警、账单列表、公告通知接口，支持已读状态并在 Admin UI 展示。
  - 已交付：新增账单/公告/通知实体与仓储，Admin 端提供 `/tenants/{id}/billings`（列表/详情/创建/标记支付）、`/announcements`（列表/详情/创建/更新/删除/已读）、`/notifications`（列表/已读）端点；权限码补充 `tenant-bill:*`、`tenant-announcement:*`、`tenant-notification:*`，种子模板更新；配额/订阅告警可通过通知表承载。
- [x] 门店管理：Store/StoreBusinessHour/StoreDeliveryZone/StoreHoliday CRUD 完整，含 GeoJSON 配送范围及能力开关。
  - 已交付：营业时间/配送区/节假日命令、查询、验证与处理器齐全，Admin API 子路由完成 CRUD，门店能力开关（预约/排队）对外暴露，仓储读写删除均带租户过滤。
- [x] 桌码管理：批量生成桌码、绑定区域/容量、导出二维码 ZIP（POST /api/admin/stores/{id}/tables 可下载）。
  - 已交付：桌台区域/桌码 DTO、命令、查询、验证与处理器完善，支持批量生成、区域绑定/更新；Admin API 增加区域/桌码 CRUD 与二维码 ZIP 导出（QRCoder 生成 SVG 打包），仓储补齐查找、更新、删除。
- [x] 员工排班：创建员工、绑定门店角色、维护 StoreEmployeeShift，可查询未来 7 日排班。
  - 已交付：门店员工 DTO/命令/查询/验证/处理器完成，支持创建/更新/删除/查询；排班 CRUD（默认未来 7 天）含归属与时间冲突校验；Admin API 增加员工与排班控制器及权限种子，仓储含排班查询/更新/删除。
- [x] 桌码扫码入口：Mini 端解析二维码，GET /api/mini/tables/{code}/context 返回门店、桌台、公告。
  - 已交付：桌码上下文查询 DTO/验证/处理器完成，可按桌码返回门店名称/公告/标签与桌台信息；MiniApi 新增 `TablesController` `/context` 端点，仓储支持按桌码查询。
- [x] 菜品建模：分类、SPU、SKU、规格/加料组、价格策略、媒资 CRUD + 上下架流程；Mini 端可拉取完整 JSON。
  - 已交付：Admin 侧补齐 SKU/规格/加料/媒资/定价替换命令、验证与端点，并新增上/下架接口与全量详情；权限种子补充 `product:publish` 与子资源读写。Mini 侧新增门店菜单接口，按门店返回分类 + 商品全量 JSON（含 SKU/规格/加料/媒资/定价），支持 `updatedAfter` 增量。
- [x] 库存体系：SKU 库存、批次、调整、售罄管理，支持预售/档期锁定并在订单中扣减/释放。
  - 已交付：库存模型补充预售/限购/并发字段与批次策略（FIFO/FEFO），新增锁定记录与幂等、过期释放；应用层提供调整/锁定/释放/扣减/批次维护命令与查询，Admin API 暴露库存与批次端点及权限种子。需后续生成迁移落库，并可按需将过期释放接入定时任务。
- [x] 自提档期：门店配置自提时间窗、容量、截单时间；Mini 端据此限制下单时间。
  - 已交付：新增自提设置与档期实体/表、并发控制，Admin 端提供自提配置与档期 CRUD 权限/接口；Mini 端提供按日期查询可用档期，包含截单与容量校验。下单限制待后续与订单流程联调。
- [ ] 购物车服务：ShoppingCart/CartItem/CartItemAddon API 支持并发锁、限购、券/积分预校验，保证并发无脏数据。
  - 当前：领域层与表结构已有 `ShoppingCart/CartItem/CartItemAddon`，但缺少 CQRS 命令/查询、并发锁/限购/券积分预校验以及任何 Admin/Mini 端接口。
- [ ] 订单与支付：堂食/自提/配送下单、微信/支付宝支付、优惠券/积分抵扣、订单状态机与通知链路齐全。
  - 当前：Admin 端 `OrdersController`/`PaymentsController` 仅提供基础 CRUD，未覆盖堂食/自提/配送业务流、微信/支付宝支付、优惠券/积分抵扣、订单状态机、通知链路及与库存/配送的集成，Mini 端也无下单/支付接口。
- [ ] 桌台账单：合单/拆单、结账、电子小票、桌台释放，完成结账后恢复 Idle 并生成票据 URL。
  - 当前：无桌台账单/合单/拆单/结账或电子小票逻辑，桌台仅有基础实体定义。
- [ ] 自配送骨架：骑手管理、取送件信息录入、费用补贴记录，Admin 端可派单并更新 DeliveryOrder。
  - 当前：`DeliveryOrder` CRUD 支持录入 `CourierName/Phone`，但缺少骑手管理、派单流程、取送件详情与补贴记录等自配送骨架。
- [ ] 第三方配送抽象：统一下单/取消/加价/查询接口，支持达达、美团、闪送等，含回调验签与异常补偿骨架。
  - 当前：尚未提供第三方配送抽象、回调验签或补偿逻辑，配送模块仅有基础 CRUD。
- [ ] 预购自提核销：提货码生成、手机号/二维码核销、自提柜/前台流程，超时自动取消或退款，记录操作者与时间。
  - 当前：存在 `Reservation` 实体及订单字段 `ReservationId/CheckInCode`，但未实现提货码生成、核销接口、超时取消/退款或核销人记录，未与订单支付联动。
- [ ] 指标与日志：Prometheus 输出订单创建、支付成功率、配送回调耗时等，Grafana ≥8 个图表；关键流程日志记录 TraceId + 业务 ID。
  - 当前：Admin/Mini/User API 与网关已接入 OpenTelemetry（OTLP 与 Prometheus 导出）和 TraceId 结构化日志，但缺少订单/支付/配送等业务指标定义、Prometheus 爬取路径说明及 Grafana 图表配置。
- [ ] 测试：Phase 1 核心 API 具备 ≥30 条自动化用例（单元 + 集成），覆盖租户→商户→下单链路。
  - 当前：仓库尚无自动化测试项目/用例，Phase 1 链路未覆盖 xUnit/Moq/FluentAssertions 的单元或集成测试。
---

## Phase 2（下一阶段）：拼单、优惠券与基础营销、会员积分/会员日、客服聊天、同城自配送调度、搜索
- [ ] 拼单引擎：GroupOrder/Participant CRUD、发起/加入/成团条件、自动解散与退款、团内消息与提醒。
- [ ] 优惠券与基础营销：模板管理、领券、核销、库存/有效期/叠加规则，基础抽奖/秒杀/满减活动。
- [ ] 会员与积分：会员档案、等级/成长值、会员日通知；积分获取/消耗、有效期、黑名单。
- [ ] 客服聊天：实时会话、机器人/人工切换、排队/转接、消息模板、敏感词审查、工单流转与评价。
- [ ] 同城自配送调度：骑手智能指派、路线估时、无接触配送、费用补贴策略、调度看板。
- [ ] 搜索：门店/菜品/活动/优惠券搜索，过滤/排序、热门/历史记录、联想与纠错。
---

## Phase 3：分销返利、签到打卡、预约预订、地图导航、社区、高阶营销、风控与补偿
- [ ] 分销返利：AffiliatePartner/Order/Payout 管理，佣金阶梯、结算周期、税务信息、违规处理。
- [ ] 签到打卡：CheckInCampaign/Record、连签奖励、补签、积分/券/成长值奖励、反作弊机制。
- [ ] 预约预订：档期/资源占用、预约下单/支付、提醒/改期/取消、到店核销与履约记录。
- [ ] 地图导航扩展：附近门店/推荐、距离/路线规划、跳转原生导航、导航请求埋点。
- [ ] 社区：动态发布、评论、点赞、话题/标签、图片/视频审核、举报与风控，店铺口碑展示。
- [ ] 高阶营销：秒杀/抽奖/裂变、裂变海报、爆款推荐位、多渠道投放分析。
- [ ] 风控与审计：黑名单、频率限制、异常行为监控、审计日志、补偿与告警体系。
---

## Phase 4：性能优化、缓存、运营大盘、测试与文档、上线与监控
- [ ] 性能与缓存：热点接口缓存、慢查询治理、批处理优化、异步化改造。
- [ ] 可靠性：幂等与重试策略、任务调度补偿、链路追踪、告警联动。
- [ ] 运营大盘：交易/营销/履约/用户维度的细分报表、GMV/成本/毛利分析。
- [ ] 文档与测试：完整测试矩阵、性能测试报告、上线手册、回滚方案。
- [ ] 监控与运维：上线发布流程、灰度/回滚策略、系统稳定性指标、24x7 监控与告警。
