目录

一、项目目标

校园里的失物信息往往分散在群聊、朋友圈和线下公告中。失主需要反复寻找线索，拾得者也需要确认物品应交给谁。“拾光友人帐”希望把寻物、招领、匹配、沟通和归还连接起来，让用户能够追踪物品从发布到归还的全过程。

本轮 Alpha 冲刺安排在 2026 年 10 月 23 日至 10 月 29 日，共七天。团队将围绕以下主流程组织开发：

登录与校园认证 → 发布寻物或招领 → 浏览与搜索 → 查看候选线索 → 提交认领 → 匿名沟通与核验 → 双方确认归还。

在这条主流程之外，我们安排个人中心、善意值、举报审核和收纳点管理，为真实使用提供必要支撑。匹配只提供候选和解释，物品归属仍通过双方核验确认。

二、团队代码规范

2.1 规范来源与执行方式

团队以《阿里巴巴 Java 开发手册（终极版 v1.3.0）》为主要参考，制定命名、分层、异常日志、数据库和测试规范。版本信息见阿里巴巴官方版本历史。

安全编程部分参考公开的 OpenHarmony Java 安全编程指南，重点落实输入边界检查、异常处理、资源释放和并发安全。缩进、目录、接口和协作流程按照本项目技术栈统一约定。

后端按 Java、Spring Boot 和 MyBatis-Plus 工程组织，前端采用小程序工程，数据层使用 MySQL，并根据需要使用 Redis。所有人使用统一依赖配置、格式化配置和接口约定，AI 生成内容也执行同样的规范。

规范分为两级：必须遵守的规则进入提交和评审检查；建议采用的规则允许结合场景调整，但应说明原因。许毅君维护规范，成员在开发中发现不适用之处时共同讨论并更新。

2.2 命名、排版与注释

变量命名应能说明含义，避免把 data1、tmp2 一类名称用于业务对象。方法聚焦一个明确任务；发现一个方法同时处理上传、认领、积分和通知时，应拆分职责。

公共接口和复杂规则应有必要说明。注释重点解释原因和约束，例如“双方确认满足后才能完成归还”，不逐行重复代码。接口变化时同步修改注释与文档，避免留下过时说明。

2.3 分层与前后端边界

后端遵循以下职责划分：

前端页面负责展示和交互，请求统一通过接口层发起。服务地址、超时、令牌和错误处理集中维护，不在每个页面复制一套。页面必须明确加载、成功、空结果和失败状态；请求失败时保留必要输入，让用户可以修正或重试。

模块之间通过约定的接口协作。认领状态、积分和消息分别有明确维护入口，其他模块不能为了方便直接改写对方的数据。公共组件优先复用，避免重复实现。

2.4 接口、校验与权限

接口统一使用 /api/v1 前缀，返回结构保持一致：

{
  "code": "0",
  "message": "ok",
  "data": {},
  "traceId": "请求追踪标识"
}

成功和失败分别使用约定的状态与错误码。客户端根据状态和业务码处理，不依赖中文提示判断分支。列表明确分页、排序和条数上限，较大的整数标识以字符串传输，避免前端精度丢失。

参数至少检查必填项、长度、类型和取值范围。照片上传检查数量、大小和实际文件类型，不能只检查扩展名。数据库访问使用参数绑定，排序字段采用白名单。

用户身份从服务端验证的会话取得，不能信任请求体中的操作者、角色或认证结果。每次写操作检查对象归属和当前状态，重点防止替换物品、认领、会话或点位标识后的越权。前端隐藏按钮不能代替服务端授权。

2.5 异常、日志与敏感信息

业务拒绝返回明确原因，例如未认证、无权访问、重复申请或状态冲突；系统故障交给统一异常处理器转换。禁止空 catch，禁止失败后仍返回成功，也不将堆栈、SQL 和内部连接信息直接展示给用户。

日志记录时间、模块、操作结果和请求标识，便于定位问题。令牌、密码、密钥、完整学号及核验材料不原样写入日志。调试截图和 AI 输入也执行脱敏要求。

文件、连接和锁在成功及异常路径中都应可靠释放。涉及共享变量和并发任务时，先明确数据归属与生命周期，避免用临时全局变量保存请求身份。

2.6 数据库、事务与幂等

表结构变更保留脚本和说明，禁止只改本机数据库。新增字段说明用途、默认值、可空性及对已有数据的影响；生成文件通过统一工具更新。

一次认领归还可能同时影响物品状态、认领记录、代管流水和事件。开发时明确事务边界，失败后不能留下部分成功的数据。积分记录通过业务唯一标识防重，不能仅靠前端禁用按钮避免重复加分。

对发布、认领和核销等关键写操作设计幂等行为：同一请求重试不产生额外记录；同一个幂等键携带不同内容时应拒绝。业务事件使用 Outbox 支撑可靠处理，消费者能够识别重复事件，失败重试不能重复通知或计分。

2.7 测试与代码评审

开发与测试同步进行。每位开发者负责本模块自测，李明学组织自动化与跨模块回归，许煜煌从用户操作角度交叉验收，其他成员按模块参与复测。

测试覆盖正常流程、参数边界、权限、状态冲突及重试。涉及数据库约束、回滚和并发的场景使用独立测试库验证；模拟接口只服务于开发准备，不作为真实联调通过的依据。

提交前至少完成格式检查、编译或构建、相关测试和差异自查。代码合入前由另一名成员复核，重点检查业务含义、接口兼容、授权与数据影响。发现缺陷时记录复现步骤、预期和实际结果，修复后再次验证。

2.8 Git 与协作记录

集成分支保持可运行，功能通过独立分支开发。每项任务建立真实 Issue，写明负责人、范围、依赖和完成标准；提交或合并记录关联对应 Issue。

提交信息表达具体变化，例如：

feat(publish): 新增寻物发布与草稿保存
fix(claim): 防止重复确认产生重复积分
test(message): 补充非参与者访问拒绝用例
docs(team): 更新冲刺计划与验收说明

一次提交聚焦一个目的。依赖变化同步工程配置，凭据和本地环境文件不进入仓库。合并说明包含改动目的、验证结果和未验证事项。

三、冲刺范围与成员任务

3.1 优先交付的内容

主流程及关键权限、事务问题优先处理。复杂视觉效果、匹配算法的进一步优化和扩展统计作为后续增强；若交付范围调整，在任务看板和总结中说明。

3.2 工作量分配

为了避免核心业务、测试和材料集中在少数人身上，本轮同时考虑开发复杂度、集成责任、测试与文档工作。拟设置 72 个任务点，每人承担约 12 点。任务点是计划阶段的相对估算，不等于工时或最终贡献比例。

刘传浩的发布和认领分阶段推进；李明学的测试由全员自测和许煜煌的流程验收共同支撑。成员遇到阻塞时在站会提出，团队按剩余工作调整协作，避免一人积压、多人数日等待。

3.3 完成一项任务的标准

任务达到以下条件才转为“已完成”：

1. 接口或页面达到 Issue 的验收条件，正常流程可运行。
2. 关键失败路径、权限和数据约束经过适用的测试。
3. 调用方能够使用，相关说明与配置同步更新。
4. 有代码签入，或测试、设计、文档等具体成果。
5. 完成另一名成员的复核，缺陷和未验证项已记录。

验收由任务负责人和复核成员共同确认，并保留相应记录。

四、七天冲刺计划

第一天：10 月 23 日——规则、环境与任务就绪

当日验收目标：统一规范和接口约定，各成员能够在准备好的环境中开始本模块工作。

第二天：10 月 24 日——发布与浏览

当日验收目标：从发布到列表和详情的流程使用真实接口连通。

第三天：10 月 25 日——首页搜索与业务补齐

当日验收目标：首页搜索可用；点位授权和登记具备后续核销的基础条件。

第四天：10 月 26 日——匹配与认领申请

当日验收目标：可依据候选线索提交真实认领申请，核销前置能力可以联调。

第五天：10 月 27 日——沟通、归还与积分闭环

当日验收目标：认领、沟通、确认和归还连通；重复请求不会造成重复核销或加分。

第六天：10 月 28 日——管理、个人中心与全面验收

当日验收目标：冻结新增范围，进入缺陷修复和交付准备；报告与演示均对应真实版本。

第七天：10 月 29 日——最终回归与交付

当日验收目标：在课程规定的 10 月 29 日 23:59 前完成代码和材料提交，提前留出平台审核与问题处理时间。截止要求见课程原文。

五、执行与交付安排

5.1 每日协作与随笔轮值

每天举行约 10—15 分钟站立会，每人说明已完成工作、困难、下一步安排和心得。接口或数据变更当天同步；复杂问题在会后由相关成员集中处理。

每日随笔由刘伟鑫、刘传浩、许毅君、王永臻、李明学、许煜煌、刘伟鑫依次主笔。主笔汇总各成员提交的进展、问题、次日计划、心得及成果记录。

当天会议保留真实且不复用的照片；运行素材由功能负责人提供，许煜煌协助整理。王永臻更新实际燃尽图，李明学提供测试结果，AI 使用者补充具体任务和人工检查情况。刘伟鑫将每日文章加入置顶集合。

5.2 进度与工作量记录

初始任务点为 72 点，横轴为七天，纵轴为剩余工作。任务通过验收后扣减相应点数；较大任务拆分为可独立验收的子任务。新增缺陷、范围调整和估点变化保留说明，燃尽图按实际剩余工作更新。

每人约 12 点用于控制计划负担。实际贡献在冲刺结束后结合开发、测试、组织、文档、演示和协作证据共同评价，不把计划点数直接当作最终工作量比例。

5.3 测试、文章与交付安排

本轮准备置顶集合、规范计划、七篇每日随笔、独立测试随笔和冲刺总结，共 11 篇文章。规范计划说明开工规则；每日记录呈现实际过程；测试随笔和总结在冲刺中持续积累、截止前完整发布。文章要求见课程原文。

测试由李明学组织，开发者自测、许煜煌交叉验收，权限和事务分别由许毅君、王永臻重点复核。工具拟采用 JUnit/MockMvc 进行后端测试，Postman 进行接口检查，小程序开发工具辅助界面验证；数据库和 Redis 相关行为在隔离环境运行。

最终交付包含可运行版本、启动与配置说明、测试用例和报告、实际燃尽图、已知问题、总结与答辩 PPT，以及腾讯共享文档评审表。文档中的模拟、真实联调、跳过和未验证状态分别说明。

5.4 风险与调整

六、AI 技术员协作计划

6.1 角色、任务和人工负责人

我们计划使用 Codex 等 AI 编程工具承担设计、编程和测试辅助工作，同一工具可按任务切换角色。AI 输出必须有人工负责人和验收方式。

6.2 任务分配与输入要求

成员向 AI 提供任务目标、相关代码和接口、业务约束、修改范围及验收标准。设计建议由负责人确认后进入实现；测试预期根据需求规则确定，由成员核对。

6.3 AI 成果的采用流程

AI 辅助任务纳入 Issue 管理。负责人审查生成内容的业务规则、接口、授权、事务和依赖，执行相关检查与测试，再由另一名成员复核后合入。协作记录包含任务、采用内容、人工修改、验证结果及遗留问题。

涉及归还与积分的实现，还需重复发送确认请求和事件，核对认领状态、积分流水及余额，确认重试不会重复计分。

6.4 使用边界与贡献评价

AI 输入使用脱敏数据，密码、令牌、证件和完整核验资料不进入输入内容。生成代码、图片和文稿在采用前检查来源与适用性。

每日记录 AI 建议的采纳情况、人工修改原因、发现的问题和实际测试结果。冲刺总结结合这些记录评价 AI 在方案比较、编码和测试中的作用及局限。需求取舍、代码合入和最终交付由成员负责。

七、本轮预期成果

七天结束时，我们希望交付一个能够复现寻物与归还主流程的 Alpha 版本，并同时说明其权限规则、数据约束、测试结果和当前限制。团队协作的成果还体现在统一规范、清晰接口、持续测试与可追溯记录中。

冲刺结束后，团队将对照任务计划复盘功能交付、协作分工、测试质量和 AI 使用情况，明确未完成事项与下一阶段安排。