FullAccess —— 项目系统代码规范、冲刺任务与计划

@

目录

一、 团队代码开发规范（参考阿里 v1.3.0 与华为规范定制）

为了确保团队 8 位成员在协同开发过程中代码风格统一、提高代码可读性并降低分支合并冲突，团队综合参考《阿里巴巴 Java 开发手册 v1.3.0》核心思想，结合团队实际落地技术栈（后端 Python/FastAPI + 同步 psycopg、管理端 React / TypeScript、移动端 React Native / Expo、数据库 PostgreSQL / PostGIS），制定以下统一规范：

1. 命名与文件规范

• 后端（Python / FastAPI）：
  • 遵循标准：严格执行 PEP 8 规范。
  • 命名规则：模块文件名采用全小写下划线（如 work_order_service.py）；类名采用大驼峰（如 ReportService）；函数名与变量名采用小写蛇形（如 create_work_order()）；常量采用全大写下划线（如 MAX_CANDIDATE_LIMIT = 8、SUPPLEMENT_TIMEOUT_DAYS = 3）。
• 前端（React / React Native / TypeScript）：
  • 遵循标准：遵循 Airbnb JavaScript / React 规范。
  • 命名规则：组件文件与组件函数采用大驼峰命名（如 ReportDetailDrawer.tsx、PendingTable.tsx）；工具函数与 Hook 采用小驼峰命名（如 useWebSocket()）；严禁使用 any 规避类型检查。
• 数据库（PostgreSQL / PostGIS）：
  • 表名、字段名全小写单数蛇形命名（如 work_order、not_same）。
  • 主键规则：核心独立业务实体通常采用 UUID 主键（命名为 id）；关联表（如 event_origin、not_same 采用复合主键）及共享主键（如 worker_profile 使用 user_id）严格按 V0.2 数据字典规范执行。外键严格以 _id 结尾。

2. 代码组织与架构约束

• 分层边界：控制器层（Router）仅负责参数解析与响应包装；核心业务流转严格下沉至 Service 层；数据持久化封装在 CRUD / 仓储层，严禁在 Router 层直接拼装业务 SQL。
• 短小事务原则：所有涉及上报保存、派工分配、合并决策、完工凭证上传的操作，必须保证在独立的短数据库事务中执行。
• 外部 I/O 隔离：外部多模态模型网络调用严禁包含在数据库事务锁内部，防止外部网络延迟拖垮数据库连接池。

3. 状态枚举、空间计算与异常处理规范

• 状态枚举强约束：
  • event（事件状态）：仅限 open、blocked_info、completed、no_need、merged。
  • work_order（工单状态）：仅限 pending、in_progress、unable、completed、reassigned、cancelled（前三种为有效工单；一个事件最多一张有效工单）。
  • 回执文案由事件、有效工单与补充请求实时推导，不得自行在事件表新增 pending 或 processing 等状态。
• PostGIS 空间计算：
  • 坐标类型采用 geography(Point, 4326)，使用 ST_DWithin 计算 50 米距离时必须直接传入米数 50.0，严禁混用平面角度换算。
• 异常捕获与降级：
  • 严禁裸露的 except: pass；多模态模型调用必须包含异常清洗逻辑，解析失败时安全降级至人工审核流程，不得阻断主数据写入。

4. Git 提交规范

• Commit 规范：严格执行 Conventional Commits 规范，并在提交信息中明确关联本地 Backlog 任务号（FA-xxx）或远端 Issue 编号（例如：feat(FA-003): 建立真实数据库认证与三角色只读隔离接口）。

二、 引入 AI 技术员：角色定义与驱动方案

团队正式引入 3 名“AI 技术员”，通过严密的情境工程与 Prompt 模板辅助团队落地工程任务，其实际提效目标需经样本统计与冲刺复盘验证：

三、 全周期开发与 Alpha 冲刺 7 天具体安排

根据项目的最新研发要求与跨端联调特点，团队对原七周计划进行了前移调整，确立以 “10/26 跑通人工核心主流程、10/29 交付首轮可运行版本、11/5 完成全部主要功能、11/9 达成完整业务演示” 为核心的迭代节奏：

1. 总体开发与验收计划（10/23 — 11/09）

2. Alpha 冲刺 7 天具体实施计划（10/23 — 10/29）

• Day 1（10月23日）· 确定范围并启动工程
  • 任务规划：敏捷看板 40 个任务拆解与估算录入（首日 8 项共计 28 人时）；统一状态码、接口路径与错误返回规范。
  • 环境搭建：初始化三端项目工程；在端口 55432 执行初版数据库迁移脚本，验证物理表约束与三角色只读隔离。
  • 随笔交付：发布置顶集合随笔、代码规范与计划随笔、Day 1 冲刺日志。
• Day 2（10月24日）· 完成登录、真实上报与查询
  • 后端：实现基础身份认证与区域拦截中间件，提供上报创建与单据查询接口。
  • 移动端与管理端：上报者 App 实现地点选择、描述填写与照片上传；Web 管理端接入上报列表读取。
  • 排障验证：完成一次真实多模态模型调用及一次地图 SDK 最小选点验证。
• Day 3（10月25日）· 打通派工与工作者任务
  • 管理端与后端：实现人工选择师傅派工接口，检查区域与工种匹配，显示派工状态。
  • 工作者端：实现任务列表卡片渲染、任务详情走查与“开始处理”状态提交。
  • 约束校验：后端强校验“一事件最多一张有效工单”，拦截越权操作。
• Day 4（10月26日）· 完成第一条完整处理流程（核心里程碑）
  • 全链路打通：跑通“上报 $\to$ 管理员派工 $\to$ 师傅开始 $\to$ 拍照完工 $\to$ 上报人查验结果”完整主流程。
  • 闭环反馈：完工照片持久化存储，操作日志入库，触发基础站内信生成。
  • 成果沉淀：录制首段全业务真实演示视频，作为答辩核心素材。
• Day 5（10月27日）· 加入基础补充与 AI 建议
  • 补充与退回：管理员对待处理事件发出信息补充请求；接入工作者“无法处理”状态上报（保留原工单，工单转为 unable，管理员可回复继续或改派）。
  • AI 接入：管理端“待处理”看板接入多模态模型给出的结构化命名与分类建议；模型失败时保留人工处理通道。
• Day 6（10月28日）· 版本收口与自动化测试推进
  • 稳定性收口：停止增加首轮功能，集中修复主流程中断与数据状态冲突。
  • 自动化测试：执行 Pytest 自动化接口测试，重点覆盖越权与非法状态转换场景。
  • 作业材料：发布独立的《测试随笔》，完成答辩 PPT 初稿与腾讯共享文档评审表设计。
• Day 7（10月29日）· 最终回归验收、答辩排练与提交
  • 验收封版：全链路回归复测，更新实际燃尽图，发布《冲刺总结随笔》并附上答辩 PPT。
  • 交付提交通道：20:00 前完成博客附件上传，21:00 前完成课程作业链接提交，预留平台机审时间。

四、 团队开发分工表

对照前期确认的团队成员权威资料，本次冲刺与后续阶段的分工责任矩阵如下：

五、 项目燃尽图（Burn Down Chart）规划

团队在敏捷看板中将 7 天任务拆解为 40 个具体任务项（FA-001 至 FA-040），初始总估算工作量为 160 人时（团队以 8 人每天 4 小时合计 224 人时作为容量上限，其余人时预留给站会沟通、材料编写、技术调研与联调缓冲）。

1. 计划工时下降基线与首日核销说明

注：本计划于 2026-10-23 冲刺首日正式确认录入。度量单位为剩余估算人时（remaining_estimated_person_hours）。首日通过验收的任务工时如实清零，未验收任务不计扣减。

2. 初始燃尽图展示

(注：下图由项目验证脚本读取本地 40 项任务数据并通过 Matplotlib 生成。虚线为 160h 理想燃尽基线，实线为 Day 1 完成 FA-001 至 FA-008 共 28h 后的实际剩余工作量 132h。)