# AGENTS.md ## 项目定位 这是一个 ASP.NET Core 选举与投票信息系统。它包含在线匿名投票、线下纸质票计票与复核、混合结果汇总、公开实时看板和 CMS。实现必须优先保证选民资格、投票唯一性、选票匿名性、计票可追溯性和权限范围隔离。 ## 设计与实现原则 - 保持变更小而完整；一个功能必须覆盖授权、验证、数据迁移、可操作界面、审计与正常/异常路径。 - 优先采用成熟组件与框架能力，不重复自建认证、权限、任务调度、富文本、实时推送、图表和对象存储基础设施。 - 核心选举规则、计票规则、资格判断和审计边界必须在服务端实现，不能仅依赖前端限制。 - 所有读取、统计、导出和写操作先施加组织范围与活动权限，再进行筛选、分页和聚合。 - 默认在线投票为匿名；任何改变为实名投票的需求都需要明确的产品与合规确认。 ## 强制安全边界 - 绝不在常规业务模型、日志、导出或公开接口中建立“选民身份 -> 匿名选票内容”的可查询关联。 - 已投状态只用于防重复投票；其数据模型与匿名选票模型分离。 - 通过数据库唯一约束、服务端事务和并发控制保证每名合格选民每项活动最多投一次。 - 投票资格必须在服务端重新验证：用户状态、活动状态、时间窗口、资格快照、投票方式与选择规则。 - 投票开始后，选民范围、候选人和关键规则应冻结；例外变更必须经过受控审核并记录审计。 - 线上与线下混合模式默认互斥：线下签到和线上已投状态必须交叉校验。 - 已确认的线下计票不可原地修改。任何修正必须创建新版本并记录原因、操作者、复核人与时间。 - 未复核的线下录入数据不得计入最终结果，也不得出现在对外公开接口。 - 对外实时页面默认仅公开参与率；候选人实时得票必须由活动级公开策略显式开启。 - 公开 API、日志和错误消息不得泄露选民身份信息、联系方式、内部审计记录或未公开计票数据。 ## 建议模块 - `Identity`：认证、用户、角色、权限。 - `Organization`：组织层级、成员归属、范围授权。 - `Election`：活动、候选人、资格规则、状态机与结果规则。 - `Voting`：线上资格验证、匿名选票、已投状态和投票回执。 - `OfflineCounting`：场次、签到、票箱、双人录入、差异复核、监票确认与封存。 - `Results`：线上/线下已确认结果汇总、审核、发布、归档。 - `Cms`：文章、公告、政策、媒体、版本、审核和发布。 - `PublicBoard`：对外只读看板、公开策略、SignalR 推送与缓存。 - `Audit`：不可抵赖的关键操作记录与查询。 ## 技术约定 - 后端：ASP.NET Core Web API、EF Core、PostgreSQL、OpenAPI。 - 优先按需使用 ABP Framework 提供的身份、权限、审计、设置与模块化能力。 - 认证优先使用 OpenIddict 或 Keycloak；不要自行发明不兼容的令牌协议。 - SignalR 用于实时状态推送；Hangfire 处理定时发布、自动开关活动、提醒和归档。 - Redis 用于缓存、限流和短期协调，不能作为选票或审计事实的唯一持久化来源。 - MinIO/S3 用于候选人照片、附件和线下计票凭证；文件访问必须有授权策略。 - 管理端建议 Vue 3 + Element Plus；公开 CMS/看板建议 Nuxt 3；富文本使用 CKEditor 5 或 TinyMCE；图表使用 ECharts。 ## 数据与迁移 - 每个新增持久化实体必须同时提供 EF Core 配置、数据库迁移、索引、约束与测试数据策略。 - 对 `ElectionId + VoterId` 等防重字段建立数据库唯一索引；不要只依赖应用层先查后写。 - 金额/票数/统计字段必须使用适当整型或 decimal 类型，禁止浮点计算票数。 - 所有时间使用 UTC 持久化，并在展示层转换为活动配置时区。 - 禁止在迁移中无条件删除业务数据；有破坏性迁移须先说明影响并取得明确授权。 ## API 与前端 - 管理 API、选民 API 与公开 API 分开路由、授权策略和响应模型；不要把后台 DTO 直接返回给公开页面。 - 写接口要求明确的资源授权、参数验证、幂等/并发策略和审计记录。 - 列表接口必须分页；导出必须遵守同一范围授权，不得绕过筛选或泄露跨组织数据。 - 前端提示不代替后端校验。对异常状态应提供可理解的错误码和可恢复指引。 - 公共看板的数据最小化：只返回活动公开策略允许的数据，并明确标注数据更新时间与统计口径。 ## 测试与验证 - 每项核心规则至少覆盖：正常路径、权限越权、重复操作、并发冲突、时间边界和异常恢复。 - 必测场景：重复线上投票、线上线下重复参与、无资格访问、候选人数选择越界、线下双录不一致、未确认线下数据泄露、公开策略切换和结果发布。 - 构建成功仅证明编译；涉及迁移、实时推送、公开页面或部署时，要分别说明已验证和未验证的边界。 - 不要执行破坏性 git 命令或删除用户现有文件，除非用户明确授权。 ## 文档要求 - 变更涉及选举规则、数据模型、权限、公开口径或部署时，同步更新相关设计文档和操作说明。 - 对有产品决策影响的默认值（匿名/实名、实时票数公开、线下双录、平票规则）必须明确记录，不能静默假设。