// ============================================================================
// 【文件说明】SecureDocumentRequest.cs - 安全文档访问请求 DTO
// ============================================================================
// 这是访问受保护文档的请求数据结构。
// 
// 【业务背景】
// 某些文档需要密码保护：
// - 机密文档：需要输入密码才能查看
// - 内部文档：限制访问权限
// - 临时分享：设置访问密码
// 
// 【安全设计】
// - 不直接在 URL 中传递密码（会被日志记录）
// - 通过请求体传递密码
// - 服务端验证密码后返回文档内容
// 
// 【与 Java Spring Boot 的对比】
// Java 通常用 @RequestBody 接收：
//   @PostMapping("/secure-document")
//   public Result access(@RequestBody SecureDocumentRequest request) {
//       ...
//   }
// 
// C# 在 Admin.NET 中直接用参数接收，框架自动绑定。
// ============================================================================

namespace Admin.NET.Plugin.HwPortal;

/// <summary>
/// 安全文档访问请求。
/// <para>
/// 【业务场景】
/// 用户访问受密码保护的文档时：
/// 1. 前端弹出密码输入框
/// 2. 用户输入密码
/// 3. 前端发送此请求
/// 4. 服务端验证密码，返回文档内容
/// </para>
/// <para>
/// 【安全说明】
/// - 密码不存储在前端
/// - 每次访问都需要验证
/// - 密码错误返回 403 错误
/// </para>
/// </summary>
public class SecureDocumentRequest
{
    /// <summary>
    /// 文档 ID。
    /// <para>
    /// 【业务说明】
    /// 要访问的文档的唯一标识。
    /// 用于查询文档信息和验证密码。
    /// </para>
    /// </summary>
    public string DocumentId { get; set; }

    /// <summary>
    /// 用户提供的密码。
    /// <para>
    /// 【业务说明】
    /// 用户输入的访问密码。
    /// 与文档存储的密码进行比对。
    /// </para>
    /// <para>
    /// 【安全最佳实践】
    /// - 密码不明文存储，存储哈希值
    /// - 传输使用 HTTPS 加密
    /// - 验证失败不返回具体错误原因
    /// </para>
    /// <para>
    /// 【C# 语法知识点 - 字符串属性】
    /// string 是 C# 的字符串类型：
    /// - 引用类型，但不可变
    /// - 对比 Java：Java 的 String 也是不可变引用类型
    /// 
    /// 为什么用 string 而不是 SecureString？
    /// - SecureString 是安全字符串，但使用复杂
    /// - 对于 Web API，HTTPS 已加密传输
    /// - string 更简单，适合大多数场景
    /// </para>
    /// </summary>
    public string ProvidedKey { get; set; }
}