从“11111”占位符到完整系统：需求澄清与项目落地实战

我接到过一个特别有意思的项目，整个需求文档只有一行，项目标题写着“11111”，连个空格都没有。当时手头还有三个正常排期的项目，看到这个编号我愣了半天，第一反应是“这谁传错了吧”。后来一问才知道，这是客户内部临时立项的代号，意思是“先占个号，细节后面补”。而我的任务，就是在这个什么都没有的项目名下，把需求、方案、排期、代码全部从零搭起来。

这篇内容我就用这个真实经历展开，聊聊当一个项目只有一个“数字壳”的时候，怎么一步步把它变成一个能交付、能运行、能交接的完整系统。适合正在带项目的技术负责人、独立接单的开发者，以及刚学会CRUD就想挑战完整项目的同学。核心内容不涉及具体业务细节，但整个过程的方法论是可以直接复用的。

1. 内容整体设计与思路拆解

1.1 需求还原：先搞清楚这个代号背后到底是谁的需求

“11111”这个标题最大的问题不是没有信息，而是没有任何约束。没有约束意味着你无法判断这是一个内部工具、一个对外站点、一个数据管道，还是一个硬件配套。所以在项目启动的第一周，我没有写一行代码，而是做了一件事：把能约到的人全部聊了一遍。

这个过程在我的经验里被称为“需求考古”。因为数字代号往往只存在于OA系统或工单系统里，真正知道这个项目要干什么的人，可能在客户那边的某个部门。你需要拿着这个代号去问，而不是拿着一个空白的PRD去问。实际操作中，我会准备一张A4纸，上面只写三行字：“项目编号11111、项目目标（空）、项目使用者（空）”。让每个被访者自己填，而不是我替他们填空。这样做的好处是，对方不会因为看到你写好的“猜测需求”而被带着走，反馈往往更接近真实使用场景。

我当时用三天时间整理完访谈记录，最终拼出了一个模糊但方向明确的轮廓：这不是一个独立业务系统，而是一个需要嵌入现有管理后台的数据统计模块。核心用户是运营和财务两个部门，他们关注的数据维度完全不同。这个发现直接决定了后续的架构方向——没有分析清楚这一点就动手写代码，大概率会把一个轻量模块做成重型系统。

这里有个非常关键的判断：当项目信息极度缺失时，千万不要自己充当需求方。你不是客户，你替客户猜出来的需求，返工概率超过八成。合理的做法是，把项目标题当成一个验证入口，通过访谈、问卷、甚至直接查看对方现有报表来还原真实业务。

1.2 五个关键问题：把“11111”从占位符还原成业务场景

闲聊式访谈只能帮你建立直觉，真正让项目从“一团雾”变成“一张图”的，是我在后续项目中反复使用的五个问题清单。这五个问题不是随意提的，而是针对“空壳项目”这种特殊场景设计的，每个问题都能帮你切割出一块有效信息。

第一个问题是“这个项目上线后，哪个人会每天打开它”。这个问题的答案定义了系统的活跃用户画像。如果答案是运营专员，那么系统需要支持批量导入和快速筛选；如果答案是财务经理，那么系统必须直接对接导出Excel，并且要支持自定义时间段汇总。同一个统计模块，面对不同使用者的设计差别是天壤之别。

第二个问题是“谁为这个项目最终结果买单”。这决定了验收标准。我遇到的那次访谈里，客户方的项目经理自己都说不清这句话，于是我换个方式问：“如果这个项目明天上线，第一周你希望看到什么数据是对的？”他说希望看到连续七天的访问趋势图。于是我知道，这个项目的核心是趋势分析，而不是绝对值统计。

第三个问题是“这个项目最不能丢的数据是什么”。数据丢失的代价决定了存储方案。如果数据丢了会影响财务结算，那必须走事务性数据库；如果只是辅助决策的参考数据，允许重跑，那可以走离线管道。很多项目后期出事故，就是因为在这个问题上没谈清楚。

第四个问题是“如果一期只能做三个功能，你选哪三个”。这是我控制需求边界最有效的手段。当对方明确知道只能做三个功能时，他们会把真正核心的东西排出来，而不会贪多。那次访谈的结果是：活跃用户趋势、渠道来源分布、自定义报表导出。

第五个问题是“这个项目上线一年后，你希望它变成什么样”。这个问题的价值在于描绘演进路径。对方说希望后续能接入更多数据源，这个回答直接让我在数据层设计时留了扩展字段，而不是把所有列都写死。虽然一年后的改版不一定由我来做，但至少不会因为我一期的短视而让整个表结构推倒重来。

1.3 需求清晰度与工作量的关系：宁可少做，不能藏雷

当需求只有“11111”时，工作量评估很容易走两个极端：要么因为信息不全而严重低估，要么因为被吓到而严重高估。这两种极端都会伤害后续的信任关系。我的做法是，把需求拆分到“可交付的功能点”级别，然后单独拉一张表，列出每个功能点的“模糊度指数”。

模糊度指数不是复杂度的概念。复杂度是“这个东西做起来有多难”，模糊度是“我们对这个东西的理解有多不清楚”。一个模糊度高的功能点，哪怕技术上只有一百行代码，也要给足排查时间，因为后期大概率会因为理解偏差而返工。

举一个具体例子：需求里有一项叫“数据概览”。这个概念模糊度极高，到底展示哪几个指标、指标的时间粒度是多少、是否对标上期，每一项都是待定项。如果把“数据概览”当成一个普通功能来排期，很可能用了两天做出来，最后被用户一句“我要的不是这个”打回重做。所以我常用的方法是，把这类模糊需求拆成“预期假设+验证方式”：

• 预期假设：数据概览展示最近7天的核心指标
• 验证方式：拿一个真实数据样本做个静态原型，给用户看排布方式

这个做法虽然会额外占用半天时间，但能显著降低项目中期改版的风险。对于标题只有一个数字的项目来说，前期多花的时间，后期都会以“少加班”的形式返还给你。

2. 核心细节解析与实操要点

2.1 技术选型不纠结：从约束条件倒推方案

一个空项目最容易犯的错，就是把技术选型当成秀肌肉的机会。我见过不少同行拿到“11111”这种类型的项目后，直接上最新框架、微服务、容器编排，仿佛不做这些就对不起这个项目的存在。但真实情况是，项目信息越少，越不能选过重的技术方案，因为你连未来三个月要承载多大流量、有哪些非功能需求都说不清。

我的选型原则只有一个：在没有明确证据表明业务会爆炸性增长之前，选主流、稳定、自己最熟悉、团队维护成本最低的组合。这里有一个容易被忽略的约束条件——谁来维护。如果是客户方自己的技术团队接手，那就得选他们已有的技术栈；如果是我方长期维护，那选热门的开源方案没问题。一句话，技术选型先问维护者，再问功能需求，最后才轮到技术偏好。

具体到我做的这个统计模块，技术栈选得很保守：前端就是Vue加一个轻量UI库，后端用Spring Boot单体应用，数据库用MySQL加Redis做缓存，部署就一台Linux服务器用Docker跑起来。没有服务网格、没有消息队列、没有分库分表。这套组合土吗？确实土。但它有两个实实在在的好处：一是团队里任何一个人都能上手维护；二是排查问题时不需要跨越十几个服务来回追踪调用链。

2.2 单体架构的边界判断：什么时候不需要微服务

很多人在“11111”这种模糊项目的架构评审会上会问：要不要上微服务？我的回答通常是一句话：如果你现在还不知道业务量级，那就先不要上。微服务是为了解决多个团队并行开发和独立部署的问题，不是为了让你在本地写代码时感觉到酷。

但“先不上微服务”不等于“永远不拆分”。我通常会按两个维度来评估拆分的边界：团队规模和业务模块间的依赖方向。如果团队小于五人，业务模块之间还有强依赖，强行拆分只会增加联调成本。我接触过太多小团队，三个开发能在一个单体里搞定的事，非要拆成六个服务，结果每天晚上都在对接口、修数据不一致的问题。

真正的做法是，先保证模块边界清晰。哪怕代码部署在同一个容器里，也要在代码层面通过包结构划分清楚。这样将来业务量起来了，把一个模块单独抽取成服务，成本要低得多。我在这个统计模块里的做法是，把所有对数据库的访问封装在独立的repository层，所有外部接口调用统一放service层，Controller只负责参数校验和结果封装。这套分层虽然老套，但它给了未来重构最大的余地。

2.3 数据模型与接口设计：先画边界，再写代码

对于“11111”这种空项目，我强烈建议在设计数据模型之前，先画一张系统的边界图。边界图的元素只有三类：数据从哪来、数据存哪、数据被谁消费。你不用画统一的图示工具，用一张白纸也可以。画完之后，项目里所有模块的存在感就清楚了。

我画出的边界是这样的：外部数据源定时推送文件到FTP，一个采集任务负责把文件解析入库；核心库存放统计结果和元数据；对外提供一套JSON接口给前台展示，同时提供Excel导出功能。这个边界看起来简单，但它定义了系统的三个大范围：采集层、计算层、展示层。每一层可以独立测试，出了问题也可以单独排查。

边界确定以后，数据模型设计就顺理成章了。第一版核心表只有三张：原始数据表、指标汇总表、统计任务日志表。很多人设计表的时候喜欢一开始就加上大量冗余字段，怕以后不够用。但我更倾向于先满足当前明确需求，额外预留两到三个可空扩展字段就够了。过度的冗余字段只会让你在后续维护时不知道该信任哪一列。

接口设计方面，我遵循一个原则：先写接口文档，再写业务代码。因为接口是前后端协作的契约，双方都按共同契约开发，联调阶段会省掉大量的扯皮。这个项目的接口总共六个：趋势查询、列表分页、单日明细、渠道分析、报表导出、任务状态查询。每个接口我在文档里都写清了入参格式、出参结构和错误码。这样即使后来接手的人不是当初的开发，也能一眼看懂这个系统对外提供了哪些能力。

3. 实操过程与核心环节实现

3.1 从零搭建项目骨架：数据库脚本先行

手工搭一个有实际业务逻辑的项目，我不太建议上来就写代码逻辑，而是建议先整理数据库脚本。因为数据是系统的地基，表结构定了，后面的代码才能有依有据。对于“11111”项目，我建了一个初始化SQL脚本，集中管理表结构和初始化数据。

简单展示一下核心表的DDL思路（用占位结构示意，不指向具体业务）：

sql复制CREATE TABLE raw_source_data (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  source_key VARCHAR(64) NOT NULL,
  data_date DATE NOT NULL,
  metric_value DECIMAL(12,4),
  extra_attrs JSON,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  UNIQUE KEY uk_source_date (source_key, data_date)
);

CREATE TABLE metric_daily_summary (
  stat_date DATE NOT NULL,
  metric_code VARCHAR(64) NOT NULL,
  metric_value DECIMAL(16,2),
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (stat_date, metric_code)
);

这个设计里有几个细节值得展开说说。第一，原始数据表里加了extra_attrs字段，类型是JSON，就是前面提到的“为未来留余地”。当后端的需求方后续提出要增加统计维度时，不需要改表结构，直接把新属性放到JSON里，等稳定后再拆成正式列。第二，汇总表把日期和指标代码组成联合主键，天然支持按时间维度的更新和后续重跑任务。我见过太多用自增ID做主键的汇总表，结果同一个日期的数据被插入两遍，查询时不知道该信谁。

数据库脚本写完之后，我会做一次完整的本地初始化测试，确保脚本在一台空机器上能直接从零跑起来。这一步很多人会偷懒，觉得本地开发环境已经有了数据库就不用管，但到了测试环境重新部署时，就会发现各种漏配用户名、漏建索引的问题。省掉这一步，后面环境问题会加倍找回来。

3.2 后端接口与定时任务：把核心逻辑一次写透

这个项目后端逻辑核心是两部分：对外接口和定时采集任务。很多人会把接口和任务串在一起写，在接口里直接查文件、解析文件、再返回结果。这种做法风险极大，因为接口的响应时间不可控，用户会等到超时。

我的做法是，把采集任务和查询接口完全解耦。定时任务负责拉取文件、解析、计算汇总，把结果落到汇总表；接口只负责从表里查询结果并返回给前端。用户看到的趋势数据，实际上是上一个采集周期已经算好的结果，而不是实时计算。对于多数统计类场景，这完全够用，而且响应速度轻松达到毫秒级别。

采集任务实现时，有个很容易被忽视的点：幂等性。任务可能因为网络超时、数据库异常等原因被重新触发，如果不做幂等处理，同一个文件会被解析两遍，导致汇总数据翻倍。我是怎么处理的？在任务日志表里记一个处理状态，每次任务启动先查一下当天的文件是否已经成功处理过，处理过就直接跳过。这个设计看起来简单，但救了我好几次。

python复制if task_log.is_processed(data_date):
    logger.info("skip already processed date: %s", data_date)
    return

rows = parse_file(file_path)
for row in rows:
    upsert_raw_source(row)
recompute_daily_summary(data_date)
mark_task_done(data_date)

这里有个细节值得提一下：汇总计算函数recompute_daily_summary不是简单地累加原始表里的值，而是会先清理该日期的旧汇总数据，再重新计算。这么做的原因，是因为源文件的数据可能会在上游被修正，重跑时用“先删后插”的方式能够保证结果一致性。如果你直接用“累加”，重跑一次数据就错了。

3.3 前端页面与数据可视化：先把骨架搭出来

前端这块，我承认自己不是专业前端，但用一套主流组件库搭后台页面还是够用的。这个项目的页面总共三个：总览页、明细页、导出中心。总览页展示数据趋势图、核心指标卡、渠道占比；明细页提供筛选条件下的表格列表；导出中心负责处理耗时的报表导出请求。

如果你是第一次搭这类页面，我建议把精力集中在“数据接口联调”上，而不是花大量时间调CSS样式。因为后台系统最重要的是数据准确、操作清晰，过度设计会让用户看得眼花缭乱。趋势图我用了比较流行的开源图表库，直接把接口返回的JSON塞进去，代码量不大，效果也非常直观。

这里有一个实际开发中会遇到的问题：当接口返回的数据结构变化时，前端很容易崩。比如接口字段名sourcename被改成了sourceName，前端如果没有做防御性取值，页面直接白屏。我的习惯是，所有接口字段在前端统一经过一个映射函数处理，即便后端调整了字段名，只需要改一处映射就行。虽然这在前端开发里算基础功夫，但大多数人都是等出了问题才想起来。

3.4 测试与部署：用最简单的流程保证稳定性

这个项目的测试策略分为三层：单元测试、接口冒烟测试、回归测试。单元测试重点覆盖计算逻辑，因为有史以来最容易出错的就是各种指标公式；接口冒烟测试关注六个核心接口是否按预期返回；回归测试则是在页面新增功能后，快速把原有主要流程过一遍。

部署流程我选择了Git加Docker的简易方案：本地提交代码，服务器拉取最新分支，重新构建镜像，启动容器。没有上什么重量级的持续集成工具，因为项目就一个服务端加一个前端静态资源，工具太重反而成了新的维护负担。如果你想在这个环节做得更稳健一些，我建议至少把数据库的初始化脚本也放进镜像的启动流程中，保证新环境拉起时数据库是就绪状态。我曾经见过一个项目，所有代码部署完，数据库里还是空的，最后发现是忘了执行初始化脚本，这个坑很容易踩。

4. 常见问题与排查技巧实录

4.1 第一天就被问“数据为什么没了”

项目上线第二天，客户反馈说“昨天的数据看不到了”。我当时第一反应是查数据库，结果数据在，任务日志显示处理成功。再仔细排查，发现是时区问题：定时任务用的是UTC时间，而系统在数据库里记录日期时直接取了UTC的“今天”，导致数据被挂到了前一天。前端查询默认查本地时区的“今天”，两边差了八小时，数据自然“消失”了。

这个问题的根因特别典型：凡是涉及跨时区的日期计算，必须指定统一的时区基准。我的修复方案是，在后端统一用本地时区取日期，同时在上游文件解析时也明确时区偏移。排查这类问题，我总结了一条经验：先看日志，再看数据，最后看代码。很多人一上来就翻代码试图定位，效率很低。正确的顺序是，通过日志确认系统实际跑了什么逻辑，然后通过数据库确认数据到底在哪里，最后用代码确认为什么数据会被写到那里。三步下来，问题基本无处遁形。

4.2 任务卡死：谁说长期运行的任务就不需要看门狗

统计任务在运行了快一个月后，某天突然不再处理新文件。我上服务器看日志，发现解析任务在凌晨四点开始处理一个超大文件，卡在了内存解析环节，既没有报错，也没有结束。因为任务是单线程执行的，它卡住了，后面的任务全部排队等待，表现就是“系统没有数据更新”。

排查时我先看了任务日志表，发现最后一条成功记录的日期停在三天前，而队列里的等待任务已经堆了几十个。这时候我做的第一件事不是调大内存，因为那个文件本身并不算特别大，真正的原因是代码里解析文件的循环没有设置超时退出机制。一个异常行可能会导致循环无法结束。

修复措施分两步：第一步，在解析逻辑里加上文件行数上限校验，超过预期值时直接告警并跳过；第二步，给定时任务加上“看门狗”逻辑，即如果当前任务执行时间超过预设阈值，主动中断并记录日志。这两个措施同时上线后，我特意观察了两周，任务再也没有卡死过。这里我也想提醒一下，任何长时间运行的任务都要有“断点续跑”和“超时保护”能力，哪怕你现在觉得数据量不大，也一定要提前加，因为出问题时补这个功能的成本远高于一开始就写。

4.3 联调阶段最常见的接口问题：字段名不一致

前后端联调时，最让人抓狂的一类问题是“这接口文档明明写了source_name，为什么前端收到的是sourceName”。这个问题在“11111”项目里也遇到过，而且不止一次。核心原因往往不在技术，而在协作：后端用了下划线命名，前端用了驼峰命名，两边都觉得自己没写错，但JSON序列化时没做配置，默认输出方式不同，就产生了偏差。

我的处理办法是在项目一开始就约定：所有接口统一用驼峰命名，数据库字段用下划线命名，中间通过ORM的映射规则自动转换。这样前端拿到的是统一的驼峰风格，后端写SQL时保持数据库习惯，谁也不迁就谁。如果你接手的是老项目，已有接口都是下划线风格，那就反过来——前端适配后端，保持现状最重要。别在这个问题上搞统一规范运动，一致性比风格更重要。

4.4 环境不一致：本地好的，服务器上就崩

有一次我把代码推上去之后，服务器上报表导出直接报错，但在本地一点问题都没有。排查到最后发现是时区问题加上字符集问题同时爆发：服务器系统默认的字符集是POSIX，而导出模板里有中文，生成的CSV直接乱码。这个问题的排查过程其实很耗时间，因为错误信息在日志里只是一个通用的编码异常，不是那种一眼能定位的堆栈。

这个经历让我养成了一个习惯：任何项目在部署时，我都会先在服务器上执行一段简单的环境自检脚本，输出系统时区、字符集、Java版本、数据库连接等信息。把这些环境差异量化之后，再遇到“本地正常、线上崩”的诡异问题，第一步就能排除掉环境因素，而不是在代码里瞎猜。环境不一致的问题，本质上还是要靠环境标准化来根治。

4.5 常见问题速查表

这张表是我每次做类似统计类项目都要维护的，每解决一个新问题就往里加一行。把它保留在项目文档里，后来接手的人遇到相同问题，直接查表就能少走弯路，不用重复“踩坑——查日志——猜原因”这个循环。

5. 项目复盘与经验沉淀

5.1 复盘：为什么“只有标题”的项目反而更考验功底

“11111”落地之后，我认真做了一轮复盘。一个只有项目编号的任务，最终顺利交付，背后最核心的支撑因素不是某一种技术框架，而是三件事：需求澄清的能力、边界控制的能力、以及面对未知问题时基于经验的判断力。

技术层面，这个项目的代码量并不大，单体和几个表的架构也确实谈不上惊艳。但如果没有前期那场访谈，没有每天坚持写任务日志，没有在测试阶段把各种异常场景重跑了一遍，这个项目大概率会变成那种“上线三天就频繁返工”的典型失败案例。项目的难度从来不在于代码复杂度，而在于信息的不确定性。谁能在不确定性里找到确定性，谁就能把项目带好。

我的一个体会是，代码写不出来时可以查文档，但需求不明时没有文档可查。所以空壳项目的处理重点，是把“人”的信息挖掘出来，再转换成“系统”的设计。技术方案永远只是执行层的工具。

5.2 留给未来的扩展建议

到现在为止，“11111”项目的核心功能已经能满足第一期的需求，但它远不是完美的。如果未来要继续演进，我建议从三个方向入手。

第一，接入更多的数据源类型。目前只处理了定时推送的文件，如果后续目标数据源改成接口拉取、消息队列，哪么采集层的抽象可以进一步扩展。第二，增加指标自定义配置能力。目前指标是代码写死的，如果运营人员能自己配置指标口径和图表，会让系统的灵活性上一个台阶。第三，考虑把汇总计算迁移到更加独立的计算节点上。虽然当前的数据量单机没问题，但如果数据量增长十倍，还是需要提前规划计算的横向扩展能力。

这些建议都是基于“如果还有后续版本”做的提前思考，并不是说当前版本有严重缺陷。在交付完一期项目后，把这类扩展性建议以文档形式提交给客户，也是建立信任的一个好方式。

6. 写在最后：从“11111”到完整交付，我收获了什么

回头再看这个项目，我觉得最有价值的不是那套运行稳定的系统，而是那段“面对一片空白如何下笔”的经验。现在很多项目都强调敏捷和迭代，但敏捷的前提是有明确的方向。如果项目只有一个数字编号，那第一步不是去跑What，而是要把Who和Why问清楚。

我在实际操作中的体会是，越是看起来“没内容可做”的项目，越要稳扎稳打走完需求澄清的流程。你可能会觉得这一步烦琐，但相信我，它们不会白做。项目代号“11111”从一开始的占位符，到后来成为一套真实运行的系统，中间靠的不是什么神奇的技术，而是一步一步把模糊变清晰的过程。

如果你想从这类空壳项目里全身而退，我最后再分享一个小技巧：在项目启动的第一天，就建立一份“决策日志”。把每一个需求确认、每一次技术选型、每一个变动的原因都记下来。这份日志在项目初期看起来没什么用，但在项目后期或者发生争议的时候，它就是你的保护伞，也是你对这个项目认知沉淀的最好载体。