跳到主要内容

Member 模块文档

1. 模块概述​

Member 是一个会员管理模块，提供用户积分、地址管理、行政区划等功能，适用于需要会员体系的应用系统。

1.1 核心功能​

  • 行政区划管理：国内行政区域数据管理
  • 用户地址管理：用户收货地址的增删改查
  • 用户积分管理：积分获取、消耗、每日签到
  • 积分流水管理：积分变动记录与查询

1.2 技术架构​

  • 基于 ASP.NET Core 构建
  • 使用 FreeSql 作为 ORM 框架
  • 支持多租户架构
  • 采用 MediatR 实现命令和查询分离

2. 核心功能模块​

2.1 行政区划模块​

2.1.1 获取区域列表​

  • API：GET /api/areas
  • 参数：父级区域ID（可选）
  • 返回：区域列表

3.1.2 获取区域详情​

  • API：GET /api/areas/{id}
  • 参数：区域ID
  • 返回：区域详情

2.2 用户地址模块​

2.2.1 获取用户地址列表​

  • API：GET /api/user-addresses
  • 参数：无
  • 返回：用户地址列表

2.2.2 获取地址详情​

  • API：GET /api/user-addresses/{id}
  • 参数：地址ID
  • 返回：地址详情

2.2.3 创建地址​

  • API：POST /api/user-addresses
  • 参数：收货人姓名、联系电话、省份、城市、区/县、详细地址、是否默认
  • 返回：创建的地址信息

2.2.4 更新地址​

  • API：PUT /api/user-addresses/{id}
  • 参数：收货人姓名、联系电话、省份、城市、区/县、详细地址、是否默认
  • 返回：更新后的地址信息

2.2.5 删除地址​

  • API：DELETE /api/user-addresses/{id}
  • 参数：地址ID
  • 返回：成功状态

2.3 用户积分模块​

2.3.1 获取用户积分​

  • API：GET /api/user-integrals
  • 参数：无
  • 返回：用户积分信息

2.3.2 每日签到​

  • API：POST /api/user-integrals/sign-in
  • 参数：无
  • 返回：签到结果、获得积分

2.3.3 获取积分流水​

  • API：GET /api/user-integral-logs
  • 参数：页码、每页数量、开始时间、结束时间
  • 返回：积分流水列表

4. 配置与部署​

4.1 模块注册​

List<Type> typeAssemblies = new List<Type>()
{
    typeof(Program),
    typeof(IApplicationService),
    typeof(FreeKitModule),
    typeof(MemberModuleStartup),
};

containerBuilder.RegisterModule(new FreeKitModule(typeAssemblies.ToArray(), null));
containerBuilder.RegisterModule(new UnitOfWorkModule(typeAssemblies.ToArray(), null));

4.2 服务依赖​

services.AddModule<MemberModuleStartup>("module-member", c);

4.3 CAP配置​

var assemblies = new List<Assembly>
{
    typeof(BasicIdentityModuleStartup).Assembly,
    typeof(MemberModuleStartup).Assembly,
};

services.AddKitCap(c) // 分布式事务一致性CAP
.AddSubscriberAssembly(assemblies.ToArray());

4.4 Swagger配置​

var projectNames = new List<string>()
{
    "FreeKit.Member",
};
//注入业务服务
services.AddSwagger(c, projectNames);

5. 使用示例​

5.1 获取区域列表示例​

// 获取省份列表
var provinces = await httpClient.GetFromJsonAsync<List<AreaDto>>("/api/areas");

// 获取城市列表
var cities = await httpClient.GetFromJsonAsync<List<AreaDto>>("/api/areas?parentId=110000");

5.2 管理用户地址示例​

// 创建地址
var newAddress = new CreateUserAddressDto
{
    Name = "张三",
    Phone = "13800138000",
    Province = "北京市",
    City = "北京市",
    District = "朝阳区",
    Address = "某某街道某某小区1号楼1单元101",
    IsDefault = true
};
var createdAddress = await httpClient.PostAsJsonAsync("/api/user-addresses", newAddress);

// 获取地址列表
var addresses = await httpClient.GetFromJsonAsync<List<UserAddressDto>>("/api/user-addresses");

5.3 积分管理示例​

// 每日签到
var signInResult = await httpClient.PostAsync("/api/user-integrals/sign-in", null);

// 获取积分信息
var integralInfo = await httpClient.GetFromJsonAsync<UserIntegralDto>("/api/user-integrals");

// 获取积分流水
var logs = await httpClient.GetFromJsonAsync<PagedResult<UserIntegralLogDto>>("/api/user-integral-logs?page=1&pageSize=10");

6. 最佳实践​

6.1 性能最佳实践​

  • 使用缓存存储行政区划数据，减少数据库查询
  • 批量操作减少API调用
  • 合理设置积分规则，避免过度消耗系统资源

6.2 业务最佳实践​

  • 为用户设置合理的积分获取规则
  • 定期清理过期的积分记录
  • 提供积分兑换功能，增加用户活跃度

6.3 安全最佳实践​

  • 验证用户身份，确保只有本人能操作自己的地址和积分
  • 防止恶意刷取积分的行为
  • 对积分变动进行日志记录，便于审计

7. 常见问题与解决方案​

7.1 积分签到失败​

  • 检查用户是否已签到
  • 检查系统时间是否正确
  • 检查积分规则配置是否正确

7.2 地址保存失败​

  • 检查地址信息是否完整
  • 检查用户权限是否正确
  • 检查数据库连接是否正常

7.3 行政区划数据不完整​

  • 检查行政区划数据是否已初始化
  • 检查API调用参数是否正确
  • 检查数据库中是否有完整的行政区划数据

8. 未来规划​

  • 支持更多国家和地区的行政区划
  • 增加积分等级体系
  • 提供积分兑换商城
  • 增强地址管理功能，支持地址智能解析
  • 集成第三方物流服务