“H”是项目代号，取“Hub”的意思。这个项目要解决的事，简单说就是把团队散落在文档、邮箱、聊天记录和表格里的周报统一收进来，清洗成规范数据，再做成一个内部看板，让管理者和一线成员随时能看到真实进度，不用再手动追着人问“这周到底干完了没”。启动之前我们内部也吵过几轮，觉得这种“周报聚合”的事买现成工具行不行，后来发现通用工具根本匹配不了内部口径，数据还是得人工二次加工，于是决定自己动手写一套。这篇文章就把H项目从0到1的第一周全过程拆开讲，包括目标拆解、每日执行、技术选型、踩坑记录和复盘指标。如果你也是一两个人撑起一个内部小项目，或者正准备启动类似的数据收集类工具，这篇复盘应该能给你一些可以直接抄的作业。
1. 项目启动前，先做减法而不是加法
1.1 想清楚H项目到底解决谁的什么问题
很多人启动项目第一周就急着写代码，我反而建议先花半天把“服务对象”和“问题边界”写死。
H项目的触发点很直接：团队接近50人，每周末各组长要把组员周报汇总成一份Excel发给上级，再人工挑数据做PPT。整个过程耗时两三个小时，而且口径经常对不上——有人写“完成了80%”，有人写“基本完成”，还有人贴了一长段流水账。我们做H项目，不是想做一个大而全的OA系统，也不是要替代绩效系统，目标只有一个：把周报从“人读”变成“机器能读”，再自动算出一组可信的进度指标。
这个边界非常重要。一旦想清楚边界，后面所有需求讨论都会变得简单：凡是和“周报收集、清洗、展示、归档”无关的功能，第一周统统不做。凡是要求复杂审批流、组织架构管理、绩效打分这类超纲需求，统一丢进backlog，等核心链路跑通再说。
给项目取名叫“Hub”，也是因为它的定位就是一个数据收发中枢，不是业务系统的替代品。这个定位在第一天就要讲清楚，不然干系人容易产生错觉，以为你在做一个能管所有人的平台。
1.2 立项沟通时如何对齐干系人预期
第一周最容易出问题的地方不是代码，而是预期错位。管理层想要的“看板”，和一线员工理解的“周报”，经常是两回事。
我做法是：启动前约了三类人各聊15分钟——管理层代表、两个组长、三个普通成员。问题固定成三个维度：你现在汇总周报最痛的点是什么；你希望看板出现哪几个数字；你绝对不能接受哪种操作方式（比如强制填模板、多系统跳转、登录太麻烦）。
得到的反馈非常有价值。管理层最关注“任务完成率”和“阻塞项”，组长希望减少复制粘贴，普通成员则希望还是按原来的习惯交周报，不想额外学习成本。这三点直接影响了我后面第一周的需求优先级：解析层优先兼容“自由文本”，展示层优先放“完成率”和“风险”，操作层保留“原有提交路径”。
对齐完预期还有一个关键动作：把统一口径写进项目说明文档。比如“完成率”的定义，是“已关闭任务数/计划任务数”，不是“上报人数/应上报人数”。这个公式看着简单，如果不在前期定义清楚，后面十有八九要返工。
1.3 把第一周拆成“看得见结果”的里程碑
第一周不能只写“搭环境”“做调研”这种模糊任务，否则到周五你会发现啥也拿不出手。我把第一周拆成了五个里程碑，每天结束都有一个可演示的增量。
表格如下：
| 日期 | 核心目标 | 产出物 | 验收标准 |
|---|---|---|---|
| 周一 | 需求澄清与技术栈锁定 | 需求清单、技术选型记录 | 全员确认边界，环境可跑通Hello world |
| 周二 | 数据模型设计与采集验证 | 数据库表设计、同步脚本原型 | 能从一份测试周报里提取结构化字段 |
| 周三 | 项目骨架与最小链路打通 | FastAPI服务、任务调度、SQLite库 | 提交周报后自动入库，接口能查到数据 |
| 周四 | 解析清洗与看板接口 | 周报解析规则、统计接口 | 50条历史周报解析成功率超过90% |
| 周五 | 联调、冒烟测试与首轮演示 | 原型演示、问题清单、下周计划 | 操作路径完整，干系人反馈已收集 |
现在回头看，这套拆解核心思路是两个：一是保证每天都有“看得见的东西”，避免临近截止才暴露风险；二是把最不确定的部分（数据解析）放在前半段，因为解析成功率直接决定整个项目可行性。如果第一周验证了解析走不通，后面看板做得再漂亮都没意义。
2. 每日执行记录与技术决策复盘
2.1 周一：需求澄清，把技术栈一次锁死
周一上午All in需求澄清，下午直接锁技术栈。
技术选型没有搞太复杂的评审，我们团队以Python为主，项目体量又不大，最终选了FastAPI + SQLite + APScheduler。有人问为什么不直接上PostgreSQL + Redis，我的判断是：第一周目标是验证核心链路，SQLite完全够用，而且文件型数据库对部署和备份都非常友好；等数据量真到几十万行再迁移PostgreSQL，FastAPI的ORM层基本不用改。缓存更是不需要，这个看板的读QPS一天也就几百次，上Redis纯属给自己增加运维负担。
前端选了Vue 3 + 一个开源Admin模板。没有花时间自己写UI框架，因为内部工具最重要的是信息密度和加载速度，不是视觉效果。周一晚上就把项目骨架拉起来，FastAPI的/health接口能正常返回，就算环境验证通过。
这里面一个容易踩的坑是：一个团队成员本机Python还是3.8，另一个已经用到3.12。为了不在这件事上浪费半天，我们直接用uv创建虚拟环境并锁定Python 3.11版本，所有依赖写进pyproject.toml，确保任何人拉代码都能在五分钟内恢复环境。
2.2 周二：数据模型设计与采集方案验证
周二的核心任务是定义表结构，并验证“周报数据到底能不能被机器读出来”。
我们设计了三张核心表：member（成员）、weekly_report（周报原文与解析结果）、task_metric（任务级指标）。weekly_report表主要存report_date、raw_content、parsed_json、submit_time这几个字段；task_metric表存任务名、状态、计划时间、备注等。一开始就有同事提意见说要不要把人员和组织架构做成一张全量表，被我否了——第一周先把“摊子”支起来，人员同步后面单独做一个定时任务就成，现在做复杂关联只会拖慢进度。
采集方案本来想直接对接IM机器人，让成员往机器人对话里发周报。但调研后发现很多成员更习惯在邮箱里写完直接发，而且有些组的周报还带附件Excel。为了不增加学习成本，第一版采集做成了“邮箱导入 + 手动上传Excel”双通道：可以设置邮箱定时拉取，也可以在页面里拖文件上传。IM机器人则放进第二周迭代计划。
下午用20封真实周报做了格式分析，发现最大的难点是文本格式五花八门。有人分点列出，有人一段写完，还有人在“完成情况”里夹杂下周计划。这让我确认了：解析层不能硬写正则，必须设计一套“分段规则 + 关键字段抽取 + 人工修正辅助”的机制，这个结论直接影响周四的开发安排。
2.3 周三：项目骨架与最小同步链路打通
周三开始写正式代码。我先用FastAPI搭了一个最简单的服务，配上SQLite数据库初始化脚本和APScheduler调度任务。项目结构如下：
h-project/ ├── app/ │ ├── main.py # FastAPI入口 │ ├── models.py # SQLAlchemy模型 │ ├── schemas.py # Pydantic校验 │ ├── routers/ │ │ ├── report.py # 周报提交与查询接口 │ │ └── dashboard.py # 看板统计接口 │ ├── services/ │ │ ├── parser.py # 周报解析器 │ │ └── collector.py # 邮箱/文件采集 │ └── scheduler.py # APScheduler任务 ├── tests/ ├── pyproject.toml └── README.md下午把最小同步链路跑通：一个mock的周报文本进入解析器，解析结果写入SQLite，然后通过接口查询返回。代码量不大，但这一步是整周的胜负手，因为链路一通，后面所有页面和统计都能往上叠。
这里有个实操心得：最小链路一定要“端到端”，不能只测解析函数，也不能只建表和接口。哪怕第一版数据是写死的，也要走完“采集→解析→入库→查询→展示”的全流程。这样每周五演示的时候，永远有一条能跑通的故事线，而不是一堆孤立的功能点。
2.4 周四：解析清洗与看板接口实现
周四是整个第一周最紧张的一天，因为真实周报的“脏数据”比预期更多。
解析器我写了一个主流程：先按空行和序号把文本拆成片段，再根据关键词（“完成”“进行中”“阻塞”“风险”“下周计划”）给片段打标签，最后用规则+正则抽取任务名、状态、负责人和计划时间。中英文逗号、括号不匹配、百分比写法不统一这些坑，在写第10条规则时全部冒出来了。
分享一个处理脏数据的思路：不要试图用一个正则覆盖所有情况，而是先把文本规范化——统一把中文逗号转英文逗号、去全角空格、归一化百分比表达，再做结构化抽取。规范化和抽取分离的好处是，后续每遇到一个新格式，只需加一条规范化规则，不必动核心解析逻辑。
到下午五点，用之前收集的50条历史周报做验证，解析成功率到了88%。剩下的12%多是表格型周报，因为文本转Excel后行列结构复杂，规则处理不了。我决定第二周引入大模型做兜底，把解析失败或置信度低于阈值的文本丢给模型做二次结构化，第一周不再继续硬撑正则逻辑。
看板接口相对简单，主要提供三个聚合指标：任务完成率、阻塞项数量、按组统计的进度分布。接口返回结构固定成JSON，前端直接渲染，不给前端同学留任何二次计算的余地。
2.5 周五：联调、冒烟测试和首轮演示
周五上午做联调和冒烟测试。所谓冒烟测试，就是把核心路径用真实数据走一遍：提交一条周报、触发解析、看板更新、导出周报汇总。我们环境里放的是40条脱敏测试数据，确保演示时不会泄露真实业务内容。
下午组织了第一轮15分钟演示会。演示顺序非常讲究：先展示“提交周报”的入口，让观众建立代入感；再展示看板上的完成率、阻塞项，同步解析出背后的周报原文；最后演示一键导出汇总Excel。整个过程控制在十分钟内，留五分钟收集反馈。
反馈比我预想的更有价值。管理层提出要看“趋势”，即对比过去四周的完成率走向；组长提出希望解析结果能人工修正，因为有些任务状态机器判不准。这两条都很有用，但我不打算在第二周全部做掉。第一周复盘时我们明确了优先级：趋势图是管理层高频需求，必须做；人工修正功能涉及编辑交互，放到第三周。
3. 实施中容易翻车的细节与控制点
3.1 分支策略与提交规范，小项目也别偷懒
很多小项目觉得就两三个人开发，Git随便用就行，结果第一周就吃了大亏。H项目第一天就定了三条规矩：main分支永远是稳定版，日常开发在dev分支；提交信息统一为feat/fix/docs/chore前缀加中文描述；每次合并必须走一次本地测试，不能“盲合”。
这套规范第一周就救了场。周三晚上前端同学改样式时不小心把一个接口的依赖搞坏了，因为提交信息写得清楚、分支隔得干净，半小时就定位并回滚了。如果几个人都在main分支上硬怼，排查成本会成倍增加。
另外文档跟进也很重要。每天结束前花十分钟更新README和设计记录，把当天做的决定、为什么这么选、留下了什么坑写进docs/decision-log.md。领导不一定会看，但第二周你打开那个文件时，会感谢自己当时的十分钟。
3.2 数据权限和安全边界，越早布置越好
周报内容涉及大量成员隐私和业务细节，权限设计不能等系统上线再想。第一周我先做了一版简单的RBAC：管理员可以看全部数据；组长只能看本组数据；普通成员只能看自己和公开的组维度统计。表结构里增加owner_id和group_id字段，所有查询接口强制走数据范围过滤。
同时，对外的演示环境里只用脱敏数据。真实的邮箱拉取脚本和控制台日志都做了脱敏配置，日志里不打印邮件正文和原始文本，只打印解析结果的长度和耗时。我们内部开玩笑说，如果周报数据漏了，比程序宕机还社死，因为里面全是成员对自己工作的吐槽。
3.3 验收口径：第一周到底怎么算“完成”
第一周快结束时，组里对“做完了没有”产生了分歧。程序员觉得解析器、接口、页面都写了，算完成；但我坚持要按最初里程碑口径验收：提交一条周报后，看板能看到指标变化，导出文件结构正确，这才算端到端完成。
这也是我个人做项目特别看重的一点：验收标准必须以用户可见的结果为准，而不是以开发工作量为主。第一周不做完整测试体系可以接受，但至少要准备三五条“关键路径冒烟用例”，每次改动后手动跑一遍。当天演示能够顺利走通，就是靠这几个用例提前发现了两个接口的字段不匹配问题。
4. 第一周踩坑记录与排查思路
4.1 环境不一致导致“在我电脑上是好的”
这句话几乎每个项目都会听到。我们第一周就撞上了：前端同事本地Node版本是20，构建正常；我环境里是18，一启动就报语法错误。排查半小时才发现，问题不在代码，而在依赖锁定和Node版本差异。
后来在项目根目录加了一个.engine的配置文件，固定Node和Python版本，并在README里写明“请使用项目指定版本运行”。Docker镜像也顺手做了出来，虽然不是生产级优化版，但至少保证了任何人拉下来都能直接跑。这个事给了我一个教训：环境一致性问题一定要在项目前两天解决，越拖越消耗士气。
4.2 统计口径信息差导致返工
周报解析和看板都做完后，管理层问了一句“这个完成率怎么和我平时看的差那么多”，我们才发现口径不一致。管理层以前算的“完成率”是按任务状态等于“已完成”除以“总任务数”，而我们默认把“进行中”也算成0.5权重加权计算，两者结果差出十几个百分点。
这就是前期需求对齐时没有落到公式层面导致的问题。后来把口径定义做成了一张对照表，贴在项目首页和文档里：完成率=已关闭任务/计划任务总数；阻塞率=阻塞任务/计划任务总数；上报率=已提交周报人数/应提交人数。每个指标都写清楚计算公式、数据来源和更新频率。从这以后，再没有人因为数字口径吵过架。
4.3 需求蔓延是第一周最大的敌人
项目第三天内测时，有同事顺口说“能不能顺便加个任务看板，把每个人的任务按甘特图展示出来”，第四天又有人说“周报里能自动提取OKR吗”。如果每个都接，第一周绝对完不成核心链路。
我处理需求蔓延的方式是一个“需求池四象限”：按紧急度和重要度分，高优的进迭代计划，低优的进待办池，明确“本周不做清单”并同步给所有干系人。不该在这个阶段做的事情，要么是因为核心链路没通，要么是因为调研不足，总之要有一个公开的记录，而不是口头答应后悄悄消失。
讲个实际例子：管理者提出的“趋势图”被列进第二周计划，因为它的价值高但复杂度也高；同事说的“甘特图”放进backlog，因为第一周还没有足够的任务数据做支撑。需求池表记录清晰之后，再没有人反复追着问“XX功能什么时候做”，因为他们能看到优先级和排期。
5. 首周复盘应该盯住哪些指标
5.1 任务完成率与估算偏差
第一周结束，我复盘了一张表：每个任务的计划工时、实际工时、完成状态。结果发现最耗时的不是解析器，而是“需求沟通”和“数据准备”。原本计划两天完成数据模型和采集，实际多占了半天，因为周报样本需要人工脱敏整理。
这个偏差让我重新调整了第二周的时间分配：把数据准备这类隐形工作前置，并给所有涉及外部输入的环节多加30%的缓冲时间。任务完成率虽然最终是100%，但过程偏差很大，如果只看完成率不看偏差，下一周还会在同一个地方翻车。
5.2 技术债务清单，哪些可以先欠着
第一周注定会积累技术债务，关键是心里要有数。我们列了三条：解析器对表格型周报支持不完善，目前靠人工修正兜底；看板没有权限控制的前端路由，只能靠后端接口过滤；定时任务没有做失败重试，邮箱拉取中断需要手动跑脚本。
债务要同时写清“还款时间”。我的原则是：会在核心链路附近引发事故的债务必须两周内还，比如定时任务失败重试；不影响演示和验证的债务可以放一放，比如权限的前端体验。把这些写进docs/debt.md后，第二周排期就非常轻松，照单还款就可以。
5.3 干系人反馈的结构化收集
周五演示后收集的反馈，我用了一个最简单的模板：三个问题——你最喜欢哪个页面/功能；你最希望下一版改哪个点；有什么场景你觉得目前完全没覆盖到。每个问题限制在200字以内，避免泛泛而谈。
收集到的反馈按“需求池四象限”处理了一下，发现一个很有意思的现象：一线成员反馈最多的其实是“写周报的时间能不能短一点”，而不是看板界面好不好看。这提醒我，第二周除了做趋势图，还应该优化解析器的容错率，让成员不需要为格式操心。干系人反馈的价值就在于此：帮你发现你以为重要但其实不重要的事。
第一周跑的这五天，让我印象最深的不是技术选型，也不是解析准确率，而是“节奏感”。项目启动阶段信息最杂、噪音最多，如果没有明确里程碑，很容易被带偏。H项目能第一天就锁定技术栈、第二天验证数据可解析、第三天打通端到端链路，靠的就是前期把目标和边界反复砸实。后面几周的路还长，但第一周的地基已经稳了。
