## 功能说明 提供小区列表查询、资源分配、分配历史与使用记录查询接口，支持按名称搜索、分配前二次确认逻辑。 ## 文件位置 - Controller: src/controller/smsCommunityController.ts - Service: src/service/smsCommunityService.ts - Model: src/model/smsCommunityModel.ts ## 接口定义 - 请求方式: GET - 路径: /api/v1/sms/platform/:platformId/communities - 请求参数: query keyword?:string, page:number=1, pageSize:number=20 - 响应格式: ```json {"code":200,"data":{"list":[{"communityId":1,"communityName":"小区A","remainingCount":800,"usedTotal":200,"usedThisMonth":50,"createdAt":"2024-08-01"}],"total":1,"alertCount":1},"message":"success"} ``` - 请求方式: POST - 路径: /api/v1/sms/community/:communityId/allocate - 请求参数: ```json {"platformId":1,"method":1,"amount":100,"convertRate":0.1,"count":1000,"effectiveStart":null,"effectiveEnd":null,"remark":"按金额分配","confirm":true} ``` - 响应格式: ```json {"code":200,"data":{"beforeRemaining":0,"afterRemaining":1000,"platformAvailableAfter":3800,"allocatedUnusedAfter":2200},"message":"success"} ``` - 请求方式: GET - 路径: /api/v1/sms/community/:communityId/alloc/history - 请求参数: query page=1, pageSize=20 - 响应格式: ```json {"code":200,"data":{"list":[{"method":1,"count":1000,"amount":100,"convertRate":0.1,"beforeRemaining":0,"afterRemaining":1000,"effectiveStart":null,"effectiveEnd":null,"remark":"备注","operator":"ops","createdAt":"2024-09-01"}],"total":1},"message":"success"} ``` - 请求方式: GET - 路径: /api/v1/sms/community/:communityId/usage - 请求参数: query page=1, pageSize=20 - 响应格式: ```json {"code":200,"data":{"list":[{"pushTime":"2024-09-01 10:00","pushName":"通知A","content":"内容","status":1,"successCount":95,"failCount":5}],"total":1},"message":"success"} ``` ## 数据库操作 - 涉及表: sms_community_quota, sms_community_alloc_log, sms_community_usage, sms_platform_resource - SQL示例: - 列表: SELECT ... FROM sms_community_quota WHERE platform_id=? AND community_name LIKE ? ORDER BY created_at DESC LIMIT ?,?; - 计算本月使用: SUM(used_count) from usage filtered by month (可预聚合或视图)。 - 分配: UPDATE sms_platform_resource SET remaining_count=remaining_count-? WHERE platform_id=? AND remaining_count>=?; - 更新小区: UPDATE sms_community_quota SET allocated_total=allocated_total+?, remaining_count=remaining_count+? WHERE community_id=?; - 写日志: INSERT INTO sms_community_alloc_log(...); - 使用查询: SELECT ... FROM sms_community_usage WHERE community_id=? ORDER BY push_time DESC LIMIT ?,?; ## 业务逻辑 1. 参数校验: method∈{1,2}; amount/count/convertRate>0; confirm=true方可提交；community与platform匹配校验。 2. 权限检查: 运营角色 required。 3. 数据处理: - 列表: 过滤keyword; 计算alertCount=剩余<1000条数；返回历史使用总计、本月使用（需按usage聚合）。 - 分配: 根据method计算缺省字段(按金额时count=round(amount*convertRate);按条数时amount=round(count/convertRate,2)); 使用最终用户输入值为准；检查平台剩余可分配(remaining-已分配未使用)≥count；二次确认标志校验；扣减平台remaining_count并增加已分配未使用（通过小区记录实现）；更新小区remaining/allocated_total；写入alloc_log；返回最新平台可分配与已分配未使用。 - 历史/使用: 按时间倒序分页返回全字段。 4. 返回结果: 统一code/message；分配成功返回前后值与平台剩余。 ## 错误处理 - 400: 参数错误 - method非法/必填字段缺失/数值<=0/confirm=false - 403: 无权限 - 非运营角色 - 404: 数据不存在 - communityId或platformId无效 - 409: 余额不足 - 平台剩余可分配不足或小区记录锁失败 ## 验收标准 - [ ] 接口能正常调用并返回预期数据 - [ ] 参数校验正确 - [ ] 错误处理完善