从三个字母的需求到可用Demo：REA项目冷启动与落地全复盘

手头这个项目的全部资料最开始只有三个字母rea。没有需求文档没有原型图甚至连一个完整的句子都没有。当时我对着这几个字母愣了半天脑子里冒出来的全是问号——这是个什么东西谁要用它要解决什么问题后来我按照自己惯用的冷启动流程把这个只有代号的项目一步步推进成一个能跑的Demo过程中踩了几个挺有代表性的坑正好整理出来给同样经常接到三无需求的朋友做个参考。这篇文章不会讲什么高深架构也不会拱一堆听起来厉害但其实用不上的技术名词。我会完整复盘REA我后来给这个代号补上的全称是Realtime Entry Assistant随手记助手从需求拆解、功能定级、技术选型到编码落地、问题排查的整个过程。适合刚开始独立做小项目、正在做课程设计或者工作中需要把模糊想法快速变成可演示原型的人阅读。1. 项目冷启动手里只有一个代号REA时我先做哪三件事拿到一个空壳需求最忌讳的事情就是立刻打开编辑器开始写代码。我当时给自己定了三个规矩先圈领域再找问题最后写边界。这三件事听起来像项目管理课上才会说的套话但实际执行起来非常具体而且每一件都能直接决定后面几千行代码往哪儿走。1.1 先圈定业务领域而不是先挑语言和框架很多人一拿到项目就纠结用Python还是Java上不上Redis要不要用Docker这些都是顺序错乱的决策。REA只有三个字母它的业务领域完全未知这时候选任何技术栈都是空中楼阁。我做的第一件事是坐下来把随手记这个方向写了下来因为rea作为代号读起来很像record和assistant的组合联想结合当时和需求方反复确认中透露的碎片信息这个项目最合理的定位就是一个轻量的个人记录工具。这个圈定动作的价值在于它把所有无关的技术选项全部过滤掉了。既然定位是个人记录工具那就不存在高并发、分布式、多租户这些词既然强调随手那交互链路就必须短既然要求助手那我至少要做一点智能解析而不是单纯存个字符串。你看一个简单的领域判断直接推导出了一串硬约束后面所有决策都省了一半力气。如果一上来就抱着万一以后要做大的心态选一个重框架只会让Demo阶段寸步难行。1.2 用一场虚拟访谈把模糊需求变成可执行交付物没有真实用户的时候我会做一次虚拟访谈站在目标用户的立场把使用场景像演话剧一样在脑子里过一遍。REA的目标用户被我设定成一个经常需要在电脑上快速记东西的普通办公者他每天会冒出各种碎片信息会议时间、待办事项、临时灵感、购物清单。他讨厌打开一个复杂的笔记软件然后手动填标题、选分类、设提醒他想要的是直接输一句话剩下的系统自己处理。我写了一条很具体的用户故事作为经常随手记东西的人我希望输入明天下午3点和团队评审方案时系统自动把时间、事项、标签拆好这样我就不用再动手填任何表单。这条用户故事后来成了整个项目的北极星所有功能都是围绕它展开的。我给需求方做虚拟访谈时还会特意追问几个关键问题记录频率大概多高会不会经常写错要改要不要跨设备这些问题再结合我对这个领域的常识判断就能拼出足够的需求画像。1.3 一圈白板之后我写下了REA的边界需求梳理完我做的第三件事是写不做清单。REA的边界被我明确为四条只处理纯文本输入不碰语音转写和图片识别数据先放在本地不做云同步单用户使用场景不做账号体系交互入口以网页为主不急着做手机原生App。这四条边界在项目中途帮我挡掉了好几次加需求冲动。我还会把非功能目标也写下来比如解析一条记录的时间要小于100毫秒系统重启后数据不能丢界面操作要有基本反馈。这些指标在Demo阶段可能不会全部严格考核但它们会让完成这个词变得可以被验证。一个只有代号的项目就是靠这种一层层往下拆的方式从虚空里长出实实在在的骨架。2. 把REA翻译成功能清单从一句话到一棵功能树边界划定之后下一步是把产品定义翻译成具体的功能。这一步如果偷懒写代码的时候一定会东一榔头西一棒子所以我习惯先把一句话定义展开成功能树再从功能树上裁剪出MVP。2.1 从缩写逆推产品定义我给REA补全的全称是Realtime Entry Assistant。这三个词的每一个都有明确含义Realtime指用户输入内容后立即得到结构化反馈Entry强调以条为单位而不是以文档为单位Assistant则意味着系统要能自动完成一部分工作。结合起来就是用户输入一条文本系统实时解析并组织成结构化记录减少手动整理成本。这个定义看起来简单但它直接决定了解析模块是整个项目的核心。我当时的目标是让用户在表单里输入一句话点击保存后页面下方已经能看到被自动识别出的时间、标题、标签和优先级。用户几乎不需要做二次修改至少覆盖80%的常见表达。这一定调让后续开发方向非常清晰。2.2 MVP功能清单与验收标准定完定义我列了一张MVP功能清单每条都写了可验收的标准避免出现差不多能用这种模糊状态。表格如下功能预期行为验收标准新增记录用户输入一句话并提交保存成功后列表立即出现新记录且页面无需刷新时间解析自动识别今天、明天、下周、几点几分等表达对20种预设表达样式的识别准确率不低于90%标签提取从文本中识别#话题标签含#号词被正确拆出其余文本归为标题列表展示按时间倒序展示所有记录新记录始终出现在最上方搜索筛选按关键词或标签过滤记录输入关键词后能在300毫秒内返回结果删除归档删除不再需要的记录删除后列表即时刷新有误删确认提示这里每一条其实都能再拆出子任务但MVP阶段把它们当作验收单位就够了写代码的人心里有数需求方也知道什么时候能验收。2.3 不做清单同样重要MVP的另一半是不做清单。REA明确不做云同步、不做账号系统、不做移动端App、不做语音输入、不做定时提醒推送。很多开发者害怕说不做总觉得会得罪需求方其实恰恰相反在资源有限的情况下不做本身就是一种承诺它保证了我在最短时间内交付一个能演示、能试用、能收集反馈的东西。当时我对需求方的原话是先把这个东西跑起来让你用一周你会发现真实的痛点根本不是缺云同步而是解析不准输入太慢之类的问题。这个判断后来被验证是对的一周后收集到的反馈里甚至没有人提到云同步。功能清单砍得越狠你真正要做的事情才越能被看见。3. 架构与选型为什么我选了轻量单体而不是微服务REA的架构决策在很多人看来可能过于简单但简单不是错匹配需求才是硬道理。在这个项目里我没有引入消息队列、没有上微服务连前端框架都没用理由是很实在的负载计算。3.1 先算负载再定架构我做了一个非常粗糙的估算假设每个真实用户平均每天新增20条记录每条文本平均200个字符一年就是7300条约1.5MB数据。哪怕用户数量乘以10一年多也才15MB。这个数量级意味着什么一张Excel表就能放下任何一个嵌入式数据库都毫无压力。既然数据量这么小那所谓的读写性能瓶颈根本不存在顺手得出结论一台单机、一个数据库文件、一个Web服务进程足够覆盖初期全部需求。那高并发呢同样做了极端假设整个团队最多几十个人同时用每秒请求量可能连两位数都到不了完全没有必要为了想象中的并发去搭建负载均衡和分布式缓存。我一贯的原则是当数据规模和并发量还没超过单机能力两个数量级之前不要给项目增加任何分布式组件。这些组件带来的配置复杂度、运维成本和排查难度在小项目里会被成倍放大。3.2 选型决定前后端一体 SQLite 本地部署基于上述计算REA整体采用了一个极简单体结构后端用Python和Flask前端用服务端渲染的Jinja2模板加少量原生JavaScript数据存储用SQLite部署方式就是在一台电脑上跑一个进程局域网内其他人通过浏览器访问。这个组合没有任何花哨的新技术但它有几个不可替代的优势。首先Python和Flask让开发效率最大化一个解析模块用几十行代码就能写完其次SQLite是零运维数据库不需要安装服务、不需要账号密码、数据就落在单个文件里备份就是复制文件再次服务端渲染让页面结构简单出现问题时通过浏览器右键查看元素就能定位对一个小项目来说调试成本比引入前后端分离低一个量级。我见过太多小团队在MVP阶段引入微前端、K8s最后连Demo都没跑通那才是真正的资源浪费。3.3 模块边界输入、解析、存储、展示架构选型解决的是用什么东西搭模块边界解决的是代码怎么分。REA被拆成四个模块职责清晰得可以用一句话概括模块职责关键接口输入模块接收用户提交的原始文本做基础校验create_entry(raw_text)解析模块从文本中提取时间、标题、标签等结构化字段parse_text(raw_text)存储模块负责SQLite读写、查询、删除操作save_entry(entry), query_entries(filter)展示模块渲染页面、表格、错误提示render_list(entries), render_error(msg)模块之间不互相调用内部方法只通过清晰定义的函数交互。这样做的直接好处是我在后面给解析模块加新规则时完全不需要动存储和展示代码。模块边界就像切蛋糕切得干净每一块才能被独立吃掉。4. 实现过程从空目录到第一个可用版本需求清楚了架构选定之后实现阶段反而是最机械的部分。但机械不等于没有讲究我把过程拆成八个关键步骤每一步都配合简单的代码和说明。4.1 工程结构与初始化项目根目录结构设计成下面这样尽量让每个文件的用途一眼可辨rea/ ├── app.py ├── parser.py ├── storage.py ├── templates/ │ ├── index.html │ └── entry_form.html ├── static/ │ ├── style.css │ └── app.js ├── tests/ │ └── test_parser.py └── requirements.txtapp.py负责把Flask应用和路由串起来parser.py专门处理文本解析storage.py封装所有SQLite操作。这样划分之后我写app.py的时候根本不用关心解析函数内部用的是正则还是字典只需要知道调用parse_text会返回一个结构体。测试文件单独放在tests目录里因为我很清楚解析模块这种规则密集的代码没有自动化测试迟早会改崩。初始化环境时我用了一个虚拟环境requirements.txt里只列了Flask和pytest两个依赖。这里故意没锁精确版本号因为项目并不需要严格的版本复现少一点约束之后升级依赖也方便。安装完依赖、创建好目录结构我马上在空项目里写了一个最简单的hello world路由先确认框架能跑起来再往里面填逻辑。4.2 建数据表一张表就够REA的数据模型非常直观我建了一张名为entries的表字段包括id自增主键、raw_text原始文本、title解析出来的标题、event_time解析出来的事件时间、tag标签、priority优先级、status状态、created_at创建时间。核心建表语句如下CREATE TABLE IF NOT EXISTS entries ( id INTEGER PRIMARY KEY AUTOINCREMENT, raw_text TEXT NOT NULL, title TEXT, event_time TEXT, tag TEXT, priority TEXT DEFAULT normal, status TEXT DEFAULT active, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP );故意不把event_time设计成真正的日期时间类型而是存成统一格式的字符串比如2025-06-12 15:00。原因很简单在SQLite里TEXT类型的ISO格式字符串可以直接按字典序比较和排序而且避免了时区转换的麻烦。这个决定在后面处理明天下午3点这样的相对时间表达时省了不少事。4.3 自然语言解析的核心逻辑解析模块是整个REA的灵魂。刚起步时我完全可以用现成的自然语言处理库但评估之后决定先用手写规则正则的方案。原因有三一是REA的输入场景非常固定用户不会写太复杂的句子二是离线运行、零额外依赖部署在哪都能跑三是规则可解释出了问题直接看正则就知道怎么回事。我把解析目标定为从明天下午3点和团队评审方案中提取出title和团队评审方案、event_time2025-06-13 15:00。核心代码思路大概是先用一组正则把时间词抠掉剩下来的文本作为标题再从标题里拆#标签。下面是一段高度简化的示意代码import re from datetime import datetime, timedelta TIME_PATTERNS [ (r明天(上午|下午|晚上)?(\d{1,2})点(半)?, 1), (r下周([一二三四五六日天]), 7), ] def parse_text(raw_text): result {original: raw_text, title: raw_text, event_time: None} for pattern, day_offset in TIME_PATTERNS: match re.search(pattern, raw_text) if match: base datetime.now() timedelta(daysday_offset) result[event_time] base.strftime(%Y-%m-%d %H:%M) result[title] raw_text[:match.start()] raw_text[match.end():] break return result这只是一个演示用的骨架真实实现里我会把今天明天下周下午晚上点半15:00这些常见表达全部做成规则表。建议所有规则先放在一个列表里后续加词只需要扩充规则不需要改主流程。不要一开始就追求覆盖所有自然语言表达先把最常用的20种场景做好效果远比一个看起来智能但实际经常出错的大而全方案好。4.4 写入与查询注意SQLite并发存储模块封装了对entries表的所有操作写入时使用了事务和参数化查询避免拼字符串带来的注入风险。一个容易忽略的细节是SQLite在默认情况下允许多线程读取但对同一文件写入时会有锁竞争尤其当用户快速连续点击保存按钮时会出现database is locked错误。我的解决办法是让每个请求在自己的线程里创建独立的数据库连接用完关闭。同时设置两个重要的PRAGMA参数写进连接初始化函数import sqlite3 def get_connection(): conn sqlite3.connect(rea.db, timeout10) conn.execute(PRAGMA journal_modeWAL;) conn.execute(PRAGMA foreign_keysON;) return connWAL模式Write-Ahead Logging能显著减少读写互相阻塞的问题对于REA这种轻量写入场景来说已经非常够用。至于查询由于MVP阶段数据量不大直接使用LIKE模糊查询就够我在界面上提供关键词搜索框底层对应一句WHERE title LIKE ?即可。4.5 Web界面先做丑但能用的页面界面的第一版我甚至不想称它为UI因为实在太简陋。一个顶部输入框、一个保存按钮、下面一张记录列表仅此而已。表单提交用的是常规POST请求返回后跳转回首页。为了让反馈更即时我加了一小段原生JavaScript用fetch提交数据成功后把新记录追加到列表顶部这样用户不用等整页刷新。这段代码只有二十几行核心逻辑就是监听表单submit事件、阻止默认行为、把文本发给后端、拿返回的记录对象拼HTML插入列表。我不建议在这个阶段引入Vue或者React因为一个输入框加一个列表引入框架反而要面临构建工具、组件生命周期、状态管理这一堆和业务无关的复杂度。丑一点没关系先逻辑全通再谈美化。4.6 联调三步假数据、边界数据、异常数据代码写完不等于功能完成我会用三类数据来做测试。假数据主要验证主链路是否通畅比如手动往数据库里插几条记录确认能被正常展示边界数据验证解析模块在极端输入下的表现比如空字符串、全是符号的文本、超长文本这些输入不能导致崩溃异常数据则验证用户在误操作时的体验比如连续点击两次保存会不会出现重复记录。我把测试用例写成了一个小表格贴在项目文档里输入文本预期解析结果实际作用明天上午10点开会时间为明天10:00标题为开会验证基础时间解析买牛奶无时间默认当天标题为买牛奶验证无时间兜底空文本提交给出提示不保存验证前端校验#urgent 修Bug标签为urgent标题为修Bug验证标签提取这一轮跑完之后REA的第一个可用版本才算真正落地。浏览器打开、输入一句话、回车、列表里多一条结构化记录——那一刻项目才从三个字母变成了一个能给人演示的东西。5. 排雷实录REA开发中真实遇到的三类障碍Demo跑通之后我原本觉得剩下的事情都是水到渠成结果试用阶段连续碰到了三个问题每一个都让我意识到纸上推演和真实运行的差距有多大。5.1 中文时间表达的词法与歧义第一个问题来自我自信满满的时间解析模块。我预设的20种表达样式覆盖了今天明天下午3点15:30这些常见写法但真实用户输入比我预想的野得多。有人输入周五下班前交报告里面的周五是本周还是下周有人输入一点多去吃午饭这里的一点多到底算13点多还是14点多之前还有人输入后天下午去机场后天这个词我的规则表里根本没有。这个问题的根源在于中文时间表达本身高度依赖上下文和约定俗成单纯靠几个正则根本不可能覆盖所有情况。我没有选择去训练一个复杂模型而是转向了务实的策略把能稳定处理的表达做深做透处理不了的表达就降级处理。具体来说我在解析失败时不再返回空时间而是把文本原样保留为用户标题并在界面上提示未识别到时间信息。同时我梳理了一份新的规则表把后天周X下下周X点半这些高频但之前漏掉的表达补了进去用三十多个测试用例锁死行为。5.2 一个隐藏的并发问题SQLite写锁与页面卡住第二个问题在多人同时试用时暴露出来。有用户反馈两个人几乎同时保存记录时其中一个请求会卡住几秒钟甚至直接报错。我一开始以为是网络问题后来看日志才发现错误信息是database is locked。根因就是我前面提到的SQLite并发写锁。Flask开发服务器默认开多线程每个请求一个线程如果公共的数据库连接被多个线程同时使用写操作就会因为文件锁冲突而阻塞。修复方案是每个线程独立创建连接并给连接加一个合理的等待超时时间同时启用WAL模式。改完之后我模拟了并发写入场景连续发20个并发请求全部成功无阻塞问题解决。这种坑最大的特点是逻辑代码零改动但它会让你怀疑整个项目能不能上线。现象根因修复多人同时保存偶发卡顿多线程共享同一个SQLite连接每请求创建独立连接设置timeout10运行时偶尔报database is lockedSQLite默认日志模式写读互斥PRAGMA journal_modeWAL页面提交后没有提示后端异常未捕获返回空响应增加try/except和JSON错误提示5.3 打包后的路径问题第三个坑出现在我把REA打包成可执行文件分发试用时。本地从源码运行一切正常打包之后却启动失败点开日志发现找不到数据库文件。原因在于PyInstaller这类打包工具会把资源文件解压到一个临时目录代码里的相对路径rea.db在源码运行时指向项目目录在打包后却指向了解压临时目录程序一退出目录就被清理数据自然存不下来。解决这个问题需要分开处理两种路径代码和配置文件放在临时目录用sys._MEIPASS定位用户数据数据库文件则放在固定用户目录比如操作系统的文档文件夹。代码示意如下import sys import os def get_app_dir(): if hasattr(sys, _MEIPASS): return sys._MEIPASS return os.path.dirname(os.path.abspath(__file__)) def get_data_dir(): return os.path.join(os.path.expanduser(~), .rea_data)数据库文件必须放在get_data_dir()返回的路径下临时目录只放打包进去的静态资源和模板。这个坑一旦踩过就再也不会忘也提醒我在写任何涉及路径的代码时先想清楚这个是代码资源还是用户数据。6. 项目复盘从能跑到好用还差哪几步REA的第一版稳定运行了两周试用收集到的信息比我从任何需求文档里能拿到的都真实。复盘阶段我没有急着加功能而是先做了一次系统性的体检。6.1 验收清单与量化数据我把项目当初写下的非功能目标翻出来逐条比对了实测结果指标目标值实测结果单条记录解析耗时100ms平均12ms满足搜索响应时间300ms平均40ms满足保存记录成功率100%正常使用100%并发场景修复后100%解析准确率常见表达≥90%覆盖30种表达式实际约92%重启后数据不丢失必须数据库文件持久化满足从数据上看REA的骨架是健康的但它离好用仍有很大差距。最大的短板在于解析准确率虽然过了九成但那一成的失败案例恰恰是用户最在意的少数情况比如下周三下午2点这种多层次时间表达。这让我意识到规则系统很快会撞到天花板下一阶段可能要考虑引入更灵活的词槽填充方式或轻量模型。6.2 下一步迭代优先级结合试用反馈我整理了一个迭代计划排序依据是用户痛点强度和实现成本的比值提升时间解析覆盖率补全节假日、模糊时间等表达并把解析结果提供给用户二次修改增加云备份能力解决用户担心本地数据丢失的问题可以先用一个简单的导入导出功能过渡增加提醒推送把解析出来的带时间记录同步到系统日历或浏览器通知移动端适配让用户在手机上也能快速输入但通过适配移动端网页实现不急着做原生App。这些需求在最初版本里全被列进了不做清单但现在它们依次变成了非做不可。做产品就是这样边界不是一成不变的关键是不可在错误的阶段做过早的优化。6.3 一个经验收尾从单点工具到可演进体系回看整个REA项目我最大的感受不是我学会了Flask或SQLite而是想明白了一个道理在没有需求的时候写代码是最容易的真正困难的是忍住不写、先把问题弄明白。每一个阶段的决策——领域圈定、MVP克制、轻量选型、路径避坑——本质上都是在和想多做一点的冲动做对抗。最后再分享一个小技巧我在整个开发过程中坚持在项目根目录记录了一个decisions.md文件每天的架构调整、踩坑结论都写在里面哪怕只有两三行。这个习惯帮我复盘时快速回忆起为什么当时选了这个方案而没选另一个对下一次启动类似项目非常有价值。拿到一个光秃秃的rea不可怕只要先把问题问对再让逻辑自然长出来任何空壳项目都能变成一个能站住脚的东西。