election-system/AGENTS.md

AGENTS.md

项目定位

这是一个 ASP.NET Core 选举与投票信息系统。它包含在线匿名投票、线下纸质票计票与复核、混合结果汇总、公开实时看板和 CMS。实现必须优先保证选民资格、投票唯一性、选票匿名性、计票可追溯性和权限范围隔离。

设计与实现原则

• 保持变更小而完整；一个功能必须覆盖授权、验证、数据迁移、可操作界面、审计与正常/异常路径。
• 优先采用成熟组件与框架能力，不重复自建认证、权限、任务调度、富文本、实时推送、图表和对象存储基础设施。
• 核心选举规则、计票规则、资格判断和审计边界必须在服务端实现，不能仅依赖前端限制。
• 所有读取、统计、导出和写操作先施加组织范围与活动权限，再进行筛选、分页和聚合。
• 默认在线投票为匿名；任何改变为实名投票的需求都需要明确的产品与合规确认。

强制安全边界

• 绝不在常规业务模型、日志、导出或公开接口中建立“选民身份 -> 匿名选票内容”的可查询关联。
• 已投状态只用于防重复投票；其数据模型与匿名选票模型分离。
• 通过数据库唯一约束、服务端事务和并发控制保证每名合格选民每项活动最多投一次。
• 投票资格必须在服务端重新验证：用户状态、活动状态、时间窗口、资格快照、投票方式与选择规则。
• 投票开始后，选民范围、候选人和关键规则应冻结；例外变更必须经过受控审核并记录审计。
• 线上与线下混合模式默认互斥：线下签到和线上已投状态必须交叉校验。
• 已确认的线下计票不可原地修改。任何修正必须创建新版本并记录原因、操作者、复核人与时间。
• 未复核的线下录入数据不得计入最终结果，也不得出现在对外公开接口。
• 对外实时页面默认仅公开参与率；候选人实时得票必须由活动级公开策略显式开启。
• 公开 API、日志和错误消息不得泄露选民身份信息、联系方式、内部审计记录或未公开计票数据。

建议模块

• Identity：认证、用户、角色、权限。
• Organization：组织层级、成员归属、范围授权。
• Election：活动、候选人、资格规则、状态机与结果规则。
• Voting：线上资格验证、匿名选票、已投状态和投票回执。
• OfflineCounting：场次、签到、票箱、双人录入、差异复核、监票确认与封存。
• Results：线上/线下已确认结果汇总、审核、发布、归档。
• Cms：文章、公告、政策、媒体、版本、审核和发布。
• PublicBoard：对外只读看板、公开策略、SignalR 推送与缓存。
• Audit：不可抵赖的关键操作记录与查询。

技术约定

• 后端：ASP.NET Core Web API、EF Core、MySql、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 直接返回给公开页面。
• 写接口要求明确的资源授权、参数验证、幂等/并发策略和审计记录。
• 列表接口必须分页；导出必须遵守同一范围授权，不得绕过筛选或泄露跨组织数据。
• 前端提示不代替后端校验。对异常状态应提供可理解的错误码和可恢复指引。
• 公共看板的数据最小化：只返回活动公开策略允许的数据，并明确标注数据更新时间与统计口径。
• 公开 CMS 当前固定八类内容：选举公告、规则与政策、候选人公示、选民指南、结果公告、常见问题、资料下载、历史归档。变更内容类型时，必须同步更新 CMS 定义、PublicContentSections、首页展示和主菜单入口，不能只新增后台类型或只展示其中三类。
• 公开端采用中性政务信息风格（白底、政务蓝、冷灰、清晰分隔），以任务和已发布信息为中心；不加载外部字体或追踪脚本，不用装饰性配色掩盖信息层级。八个公开栏目必须有直接可访问的菜单入口，且不得显示未发布内容、未确认计票数据或个人投票信息。

测试与验证

• 每项核心规则至少覆盖：正常路径、权限越权、重复操作、并发冲突、时间边界和异常恢复。
• 必测场景：重复线上投票、线上线下重复参与、无资格访问、候选人数选择越界、线下双录不一致、未确认线下数据泄露、公开策略切换和结果发布。
• 构建成功仅证明编译；涉及迁移、实时推送、公开页面或部署时，要分别说明已验证和未验证的边界。
• 不要执行破坏性 git 命令或删除用户现有文件，除非用户明确授权。

文档要求

• 变更涉及选举规则、数据模型、权限、公开口径或部署时，同步更新相关设计文档和操作说明。
• 对有产品决策影响的默认值（匿名/实名、实时票数公开、线下双录、平票规则）必须明确记录，不能静默假设。